From f09a4e877728128d58d72a27b72a74db0aa88ed2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=9A=D0=B8=D1=80=D0=B8=D0=BB=D0=BB=20=D0=9A=D1=83=D1=82?=
 =?UTF-8?q?=D0=BB=D0=B0=D1=85=D0=BC=D0=B5=D1=82=D0=BE=D0=B2?=
 <kirillkutlahmetov10@gmail.com>
Date: Tue, 26 May 2026 12:21:14 +0000
Subject: [PATCH] docs: comprehensive README with architecture diagram

---
 README.md | 103 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 77 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 1473113..7c2a7ec 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,96 @@
-# Task 69dd4221f309a98be0006b2e
+# Парсер задания: сырой текст → TaskCard
 
-## Описание
+Модуль принимает неформальное описание учебного задания и возвращает
+структурированный объект `TaskCard` — без диалога, за один запрос к модели.
 
-Программа принимает неформальное описание задания от преподавателя и преобразует его в структурированный объект `TaskCard`.
+## Стек
 
-### Что делает
+| Компонент | Библиотека |
+|-----------|------------|
+| Языковая модель | BroJS (`openai/gpt-oss-20b:free`) |
+| LLM-клиент | `langchain-openai` → `ChatOpenAI` |
+| Промпт | `langchain-core` → `PromptTemplate` |
+| Парсер | `langchain-core` → `PydanticOutputParser` |
+| Модель данных | `pydantic` → `BaseModel` |
 
-1. Определяет модель `TaskCard` с полями: `title`, `subject`, `deadline_hint`, `deliverable_type`, `grading_hints`.
-2. Создаёт цепочку: шаблон промпта → LLM (BroJS) → парсер Pydantic.
-3. В примере запуска выводит валидированный объект и человекочитаемую сводку.
+## Структура TaskCard
 
-## Как запустить
+```python
+class TaskCard(BaseModel):
+    title: str            # Краткое название (2–6 слов)
+    subject: str          # Область знаний / технология
+    deadline_hint: str    # Срок в свободной форме
+    deliverable_type: str # Что сдать: отчёт, код, презентация…
+    grading_hints: list[str]  # Критерии оценки
+    notes: Optional[str]  # Дополнительные заметки
+```
+
+## Цепочка обработки
+
+```
+task_text
+    │
+    ▼
+PromptTemplate  ← format_instructions от PydanticOutputParser
+    │
+    ▼
+ChatOpenAI (BroJS, один запрос)
+    │
+    ▼
+PydanticOutputParser
+    │
+    ▼
+TaskCard (валидированный объект)
+```
+
+## Установка
 
 ```bash
-# Установить зависимости
 pip install -r requirements.txt
-
-# Запустить пример
-python main.py
 ```
 
 ## Переменные окружения
 
-- `JOURNAL_MCP_PAT` – токен доступа к LLM BroJS.
+| Переменная | Описание |
+|------------|----------|
+| `JOURNAL_MCP_PAT` | Токен доступа к BroJS LLM |
 
-## Пример входа
+Создай `.env`:
+```
+JOURNAL_MCP_PAT=jrnl_...
+```
 
-```text
-Сдайте к пятнице мини-отчёт по LangChain: 2 страницы, упор на агентов. Оценка: за полноту и за пример кода.
+## Запуск
+
+```bash
+# Встроенный пример
+python main.py
+
+# Своё описание задания
+python main.py "Сдайте до понедельника презентацию по RAG: 10 слайдов. Оценка: за полноту и визуализацию."
 ```
 
 ## Пример вывода
 
-```text
---- Валидированный объект ---
-{'title': 'Мини-отчёт по LangChain', 'subject': 'LangChain', 'deadline_hint': 'к пятнице', 'deliverable_type': 'отчёт', 'grading_hints': ['полнота', 'пример кода']}
-
---- Человекочитаемая сводка ---
-Задача: Мини-отчёт по LangChain
-Тема: LangChain
-Срок: к пятнице
-Тип сдачи: отчёт
-Критерии оценки: полнота, пример кода
+```
+Вход:
+  Сдайте к пятнице мини-отчёт по LangChain: 2 страницы, упор на агентов.
+  Оценка: за полноту и за пример кода.
+
+─── Валидированный объект (model_dump) ─────────────────────
+{
+  "title": "Мини-отчёт по LangChain",
+  "subject": "LangChain",
+  "deadline_hint": "к пятнице",
+  "deliverable_type": "отчёт",
+  "grading_hints": ["полнота", "пример кода"],
+  "notes": null
+}
+
+─── Человекочитаемая сводка ─────────────────────────────────
+  Задача:       Мини-отчёт по LangChain
+  Тема:         LangChain
+  Срок:         к пятнице
+  Тип сдачи:    отчёт
+  Критерии:     полнота, пример кода
 ```