# Сырой текст задания → плоская карточка

## Описание проекта

В рамках курса по созданию ассистента для учебного процесса данная программа принимает **неформальное описание задачи** (например, сообщение преподавателя в чате или короткий абзац из сайта) и преобразует его в структурированный объект `TaskCard`.  
Полученный объект содержит ключевые поля, которые можно использовать дальше в пайплайне: фильтрацию, хранение, передачу другим модулям.

## Стек технологий

- **Python** 3.10+
- **langchain-core**, **langchain-openai** – взаимодействие с LLM
- **pydantic** – типизация и валидация выходных данных
- **python-dotenv** (необязательно) – загрузка переменных окружения

## Установка зависимостей

```bash
# Создайте виртуальное окружение (рекомендовано)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Установите пакеты
pip install langchain-core langchain-openai pydantic python-dotenv
```

> **Важно**  
> Для работы с LLM необходимо задать ключ API. Самый простой способ – создать файл `.env` в корне проекта:

```dotenv
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

или экспортировать переменную окружения напрямую:

```bash
export OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```

## Как запустить

Файл `task.py` содержит всю логику.  
Пример использования в интерактивном режиме:

```python
# task_demo.py
from task import TaskCard, parser, llm  # импортируем готовый LLM и парсер

raw_text = """
Нужно написать отчёт по теме «Алгоритмы сортировки». Сдача до следующей недели. Оценка будет по структуре и корректности кода.
"""

# Формируем запрос к модели
prompt_template = parser.get_prompt()
prompt = prompt_template.format(input=raw_text)

# Получаем ответ от LLM
response = llm.invoke(prompt)

# Парсим в объект TaskCard
task_card = parser.parse(response)
print(task_card.json(indent=2))
```

Запуск:

```bash
python task_demo.py
```

Вывод будет примерно таким:

```json
{
  "title": "Отчёт по алгоритмам сортировки",
  "subject": "Алгоритмы сортировки",
  "deadline_hint": "до следующей недели",
  "deliverable_type": "отчёт",
  "grading_hints": [
    "структура",
    "корректность кода"
  ]
}
```

## Пример использования в пайплайне

```python
# pipeline.py
from task import TaskCard, parser, llm

def process_task(raw_description: str) -> TaskCard:
    prompt = parser.get_prompt().format(input=raw_description)
    response = llm.invoke(prompt)
    return parser.parse(response)

if __name__ == "__main__":
    raw = "Написать презентацию по теме «Машинное обучение» до 15.09."
    card = process_task(raw)
    print(card.title)          # Презентация по теме «Машинное обучение»
```

## Что делает код

1. **`TaskCard`** – Pydantic‑модель, описывающая структуру карточки задания.
2. **`PydanticOutputParser`** – обёртка, которая формирует запрос к LLM и парсит JSON‑ответ в `TaskCard`.
3. Внутри `task.py` создаётся объект LLM (`ChatOpenAI`) с использованием ключа из переменных окружения.
4. При вызове `parser.parse()` модель генерирует ответ в формате, совместимом с Pydantic, и парсер преобразует его в экземпляр `TaskCard`.

## Тесты

Для быстрой проверки можно написать простые unit‑тесты:

```bash
pip install pytest
pytest tests/
```

(В проекте пока нет тестов – их добавьте по необходимости.)

## FAQ

| Вопрос | Ответ |
|--------|-------|
| Как изменить модель? | Измените параметры `ChatOpenAI` в `task.py`. |
| Что делать, если LLM не возвращает валидный JSON? | Попробуйте добавить в шаблон более строгие инструкции или использовать `parser.get_prompt()` с параметром `strict=True`. |
| Можно ли использовать другую LLM (например, Gemini)? | Да – замените импорт и объект `ChatOpenAI` на соответствующий клиент. |

## Лицензия

MIT © 2026