docs: comprehensive README with architecture diagram

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`.
+## Структура TaskCard
-2. Создаёт цепочку: шаблон промпта → LLM (BroJS) → парсер Pydantic.
-3. В примере запуска выводит валидированный объект и человекочитаемую сводку.
 
-## Как запустить
+```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: 2 страницы, упор на агентов.
+  Оценка: за полноту и за пример кода.
 
---- Человекочитаемая сводка ---
+─── Валидированный объект (model_dump) ─────────────────────
+{
+  "title": "Мини-отчёт по LangChain",
+  "subject": "LangChain",
+  "deadline_hint": "к пятнице",
+  "deliverable_type": "отчёт",
+  "grading_hints": ["полнота", "пример кода"],
+  "notes": null
+}
+
+─── Человекочитаемая сводка ─────────────────────────────────
   Задача:       Мини-отчёт по LangChain
   Тема:         LangChain
   Срок:         к пятнице
   Тип сдачи:    отчёт
-Критерии оценки: полнота, пример кода
+  Критерии:     полнота, пример кода
 ```