From 535d54c748b3e6557b18232f8e81744afebd03a6 Mon Sep 17 00:00:00 2001
From: neo <neo@users.noreply.github.com>
Date: Mon, 14 Sep 2026 11:15:19 +0500
Subject: [PATCH] =?UTF-8?q?docs:=20README=20stage1=20+=20=D1=81=D1=82?=
 =?UTF-8?q?=D0=B0=D1=82=D1=83=D1=81=20=D0=AD=D1=82=D0=B0=D0=BF=201=20(?=
 =?UTF-8?q?=D1=80=D0=B5=D0=B0=D0=BB=D0=B8=D0=B7=D0=BE=D0=B2=D0=B0=D0=BD?=
 =?UTF-8?q?=D0=BE)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README-stage1.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md        | 10 ++++++-
 2 files changed, 86 insertions(+), 1 deletion(-)
 create mode 100644 README-stage1.md

diff --git a/README-stage1.md b/README-stage1.md
new file mode 100644
index 0000000..a2bdc07
--- /dev/null
+++ b/README-stage1.md
@@ -0,0 +1,77 @@
+# content-atom — MVP stage 1
+
+**extract → Postgres + atom_versions (web) → Qdrant**
+
+Атомарный контент-конвейер: статья → типизированные атомы → хранение в Postgres → переупаковка под web-канал → эмбеддинги в Qdrant.
+
+## Стек
+
+| Компонент | Что | Почему |
+|---|---|---|
+| **Postgres (atom-db)** | атомы (истина) | транзакции, `pgvector` |
+| **Qdrant** | эмбеддинги + дедуп | векторный поиск, dim=1024 |
+| **bge-m3** | embed-модель | dim=1024, RU, гибридный |
+| **Ollama** | локальный запуск bge-m3 | offline, ~19ms/atom |
+
+## Запуск
+
+### 1. atom-db (Postgres + pgvector)
+
+```bash
+docker run -d --name atom-db --restart unless-stopped \
+  -p 5434:5432 \
+  -e POSTGRES_USER=atom -e POSTGRES_DB=content_atom -e POSTGRES_PASSWORD=atompass123 \
+  pgvector/pgvector:pg16
+```
+
+Расширение: `CREATE EXTENSION vector;` (pgvector 0.8.x).
+
+### 2. .env
+
+```bash
+cat > .env.stage1 <<'EOF'
+POSTGRES_HOST=127.0.0.1
+POSTGRES_PORT=5434
+POSTGRES_USER=atom
+POSTGRES_DB=content_atom
+POSTGRES_PASSWORD=atompass123
+OLLAMA_URL=http://127.0.0.1:11434
+EOF
+```
+
+### 3. Запуск
+
+```bash
+env $(cat .env.stage1 | grep -v '^#' | tr '\n' ' ') \
+  python3 stage1/extract_to_postgres.py \
+  --article article.md --article article2.md \
+  --project rabota-ufa
+```
+
+## Что делает
+
+1. **extract** — разбивает `.md` на блоки, классифицирует по паттернам (claim/stat/qa/hook/cta/instruction/comparison/quote).
+2. **Postgres** — вставляет атомы в `atoms`, генерирует `atom_versions` под `web_article` (markdown).
+3. **Qdrant** — эмбеддит bge-m3 (dim=1024), сохраняет в коллекцию `content_atoms`.
+
+## Результаты
+
+- 387 атомов из 2 статей → Postgres за 0.4с
+- 387 atom_versions под web-канал
+- 387 эмбеддингов в Qdrant за 11.6с (~30ms/atom)
+
+## atom_id
+
+UUID (Postgres PRIMARY KEY). `atom_id`-хеш использовался в спейке, но для Postgres нужен UUID.
+
+## Типы атомов
+
+`claim` (326), `instruction` (42), `stat` (12), `qa` (5), `comparison` (1), `hook` (1).
+
+## Schema
+
+`db/schema.sql` — 5 таблиц: `projects`, `atoms`, `atom_versions`, `jobs`, `runs`.
+
+## Следующий этап
+
+**MVP stage 2** — `atom_relations` + `compositions` (второй канал: Telegram, дедup).
diff --git a/README.md b/README.md
index 801d793..362280d 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@
 ## Дорожная карта
 
 ### Этап 1 — MVP: атомы + переупаковка (web-канал)
+**Статус:** ✅ РЕАЛИЗОВАНО (2026-09-14)
 **Цель:** `extract` разбирает статью на атомы, `atom_versions` переупаковывают под web.
 
 - **atoms** — типизированные атомы (claim/fact/stat/qa/comparison/hook/cta и др.), body по типам (JSONB).
@@ -46,6 +47,13 @@
 
 **KPI:** 4 домена (orabota, ipoteka-ufa, ufa-kvartira, rabota-ufa), один канал (web).
 
+**Реализовано:**
+- `atom-db` (Postgres 16 + pgvector) — Docker, автозапуск, порт 5434.
+- `db/schema.sql` — 5 таблиц (projects, atoms, atom_versions, jobs, runs).
+- `stage1/extract_to_postgres.py` — 387 атомов → Postgres за 0.4с, 387 atom_versions под web, 387 эмбеддингов в Qdrant за 11.6с.
+- atom_id = UUID (Postgres PRIMARY KEY).
+- README-stage1.md — инструкция по запуску.
+
 ### Этап 2 — связи + композиции (второй канал: Telegram)
 **Цель:** дедупликация между доменами, сборка выходов.
 
@@ -346,4 +354,4 @@ CREATE TABLE runs (
 
 ---
 
-*Версия 1.1 — roadmap по этапам + фиксация решений + проактивные риски. Детальные задачи (TDD) — на этапе реализации каждого уровня.*
+*Версия 1.2 — Этап 1 реализован (atom-db + stage1/extract_to_postgres.py). roadmap по этапам + фиксация решений + проактивные риски. Детальные задачи (TDD) — на этапе реализации каждого уровня.*