сырой текст задания → плоская карточка: README.md
This commit is contained in:
+85
-83
@@ -1,32 +1,26 @@
|
||||
# Сырой текст задания → плоская карточка
|
||||
# Task Card – превращение сырого текста задания в структурированные данные
|
||||
|
||||
## 📖 Описание проекта
|
||||
В рамках курса «Ассистент по учёбе» вы разрабатываете модуль, который принимает **неформальное описание задачи** (например, сообщение преподавателя в чате) и преобразует его в структурированный объект. Полученный объект можно дальше фильтровать, сохранять или передавать следующему шагу пайплайна.
|
||||
## Описание проекта
|
||||
|
||||
### Что делает программа?
|
||||
- Принимает одну строку/абзац с формулировкой задания.
|
||||
- С помощью LLM (OpenAI, Azure, Anthropic и т.д.) извлекает ключевые поля:
|
||||
- `title` – название задачи
|
||||
- `subject` – предмет / тема
|
||||
- `deadline_hint` – подсказка о сроке сдачи (строка в свободной форме)
|
||||
- `deliverable_type` – тип сдаваемого материала (отчёт, код, презентация и т.п.)
|
||||
- `grading_hints` – список строк с упоминаниями оценивания
|
||||
`task_card.py` реализует модуль, который принимает неформальное описание задачи (как в переписке или на сайте курса) и преобразует его в **структурированный объект** `TaskCard`.
|
||||
Объект содержит поля:
|
||||
|
||||
### Почему это важно?
|
||||
- Позволяет быстро структурировать входные данные без ручного парсинга.
|
||||
- Делает дальнейшую обработку более надёжной и предсказуемой.
|
||||
| Поле | Тип | Описание |
|
||||
|------|-----|----------|
|
||||
| `title` | `str` | Краткое название задачи |
|
||||
| `subject` | `str` | Предмет или область знаний |
|
||||
| `deadline_hint` | `str` | Указание срока сдачи в свободной форме |
|
||||
| `deliverable_type` | `str` | Тип сдаваемого материала (отчёт, код, презентация и т.д.) |
|
||||
| `grading_hints` | `List[str]` | Ключевые критерии оценки, упомянутые в тексте |
|
||||
|
||||
## ⚙️ Стек и установка
|
||||
Модуль использует **LangChain** для общения с LLM и **Pydantic** для гарантированного парсинга результата.
|
||||
|
||||
| Пакет | Версия (рекоменд.) |
|
||||
|-------|--------------------|
|
||||
| `langchain-core` | 0.2.x |
|
||||
| `langchain-openai` | 0.1.x |
|
||||
| `pydantic` | 2.x |
|
||||
| `python-dotenv` | любой |
|
||||
---
|
||||
|
||||
## Установка зависимостей
|
||||
|
||||
```bash
|
||||
# Создайте виртуальное окружение (рекомендовано)
|
||||
# Создайте виртуальное окружение (рекомендуется)
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
|
||||
@@ -34,91 +28,99 @@ source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install langchain-core langchain-openai pydantic python-dotenv
|
||||
```
|
||||
|
||||
> **Важно**:
|
||||
> 1. Создайте файл `.env` в корне проекта и добавьте ключи доступа к LLM, например:
|
||||
> ```dotenv
|
||||
> OPENAI_API_KEY=sk-...
|
||||
> ```
|
||||
> 2. Если используете другую модель (Azure, Anthropic), настройте соответствующие переменные окружения согласно документации `langchain-openai`.
|
||||
> **Важно**
|
||||
> 1. Для работы с LLM понадобится ключ OpenAI (или другой провайдер).
|
||||
> 2. Ключ можно задать через переменную окружения `OPENAI_API_KEY` или в файле `.env`.
|
||||
|
||||
## 📂 Структура проекта
|
||||
---
|
||||
|
||||
```
|
||||
project/
|
||||
├── .env # Переменные окружения
|
||||
├── main.py # Точка входа – пример использования
|
||||
├── task_parser.py # Модуль с Pydantic‑моделью и функцией парсинга
|
||||
└── README.md # Это файл
|
||||
```
|
||||
## Как запустить
|
||||
|
||||
## 🚀 Запуск
|
||||
|
||||
### 1. Пример запуска через `main.py`
|
||||
### 1️⃣ Запуск скрипта вручную
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
# Убедитесь, что переменная OPENAI_API_KEY установлена
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
|
||||
python task_card.py
|
||||
```
|
||||
|
||||
`main.py` содержит пример входного текста и выводит распарсенный объект.
|
||||
При запуске скрипт запросит у пользователя ввод текста задания и выведет распарсенный объект `TaskCard`.
|
||||
|
||||
> **Вывод**
|
||||
> ```text
|
||||
> Task(title='Составить отчёт по проекту', subject='Информатика', deadline_hint='до 15.09', deliverable_type='отчёт', grading_hints=['проверка структуры, логики и оформления'])
|
||||
> ```
|
||||
|
||||
### 2. Использование как библиотеки
|
||||
### 2️⃣ Использование как модуля
|
||||
|
||||
```python
|
||||
from task_parser import parse_task_text, Task
|
||||
from task_card import parse_task_text, TaskCard
|
||||
|
||||
text = "Напиши код для решения задачи по алгоритмам до 20.10."
|
||||
task: Task = parse_task_text(text)
|
||||
print(task.title) # → 'Написать код'
|
||||
print(task.grading_hints) # → ['проверка корректности кода', ...]
|
||||
raw = """
|
||||
Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал.
|
||||
Сдать код и README. Срок сдачи – через две недели после начала проекта.
|
||||
Оценка будет по качеству кода, читаемости и покрытию тестами.
|
||||
"""
|
||||
|
||||
card: TaskCard = parse_task_text(raw)
|
||||
print(card.json(indent=2))
|
||||
```
|
||||
|
||||
## 🧩 Как работает `parse_task_text`
|
||||
---
|
||||
|
||||
1. **Формирование запроса** – создаётся prompt, в котором описывается формат ответа (JSON).
|
||||
2. **Вызов LLM** – через `langchain-openai` отправляется запрос и получает JSON‑строку.
|
||||
3. **Проверка схемы** – строка парсится в `pydantic.BaseModel`, гарантируя типизацию и наличие обязательных полей.
|
||||
## Пример использования
|
||||
|
||||
Если модель не может распарсить ответ, выбрасывается исключение с подробным сообщением.
|
||||
```bash
|
||||
$ python task_card.py
|
||||
Введите текст задания:
|
||||
Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал.
|
||||
Сдать код и README. Срок сдачи – через две недели после начала проекта.
|
||||
Оценка будет по качеству кода, читаемости и покрытию тестами.
|
||||
|
||||
## 📄 Пример входного текста
|
||||
|
||||
```text
|
||||
"Пожалуйста, подготовьте презентацию по теме «Машинное обучение» до 30 сентября. В оценке учитываются оригинальность и глубина анализа."
|
||||
```
|
||||
|
||||
### Ожидаемый результат (JSON)
|
||||
|
||||
```json
|
||||
Результат:
|
||||
{
|
||||
"title": "Подготовка презентации",
|
||||
"subject": "Машинное обучение",
|
||||
"deadline_hint": "до 30 сентября",
|
||||
"deliverable_type": "презентация",
|
||||
"title": "Генерация отчёта о продажах",
|
||||
"subject": "Python",
|
||||
"deadline_hint": "через две недели после начала проекта",
|
||||
"deliverable_type": "код и README",
|
||||
"grading_hints": [
|
||||
"оригинальность",
|
||||
"глубина анализа"
|
||||
"качество кода",
|
||||
"читаемость",
|
||||
"покрытие тестами"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 Полезные ссылки
|
||||
---
|
||||
|
||||
- [LangChain Docs – OpenAI](https://langchain.com/docs/integrations/providers/openai)
|
||||
- [Pydantic v2.0](https://docs.pydantic.dev/latest/)
|
||||
- [Python‑dotenv](https://pypi.org/project/python-dotenv/)
|
||||
## Структура файлов
|
||||
|
||||
## 🤝 Вклад
|
||||
|
||||
Если хотите улучшить проект:
|
||||
1. Форкните репозиторий.
|
||||
2. Создайте ветку с вашим изменением.
|
||||
3. Откройте Pull Request и опишите, что было сделано.
|
||||
| Файл | Описание |
|
||||
|------|----------|
|
||||
| `task_card.py` | Основной скрипт: определение модели, шаблона промпта и функции парсинга. |
|
||||
| `.env.example` | Пример файла с переменными окружения (ключи API). |
|
||||
|
||||
---
|
||||
|
||||
**Happy parsing!**
|
||||
## Тестирование
|
||||
|
||||
```bash
|
||||
# Установите pytest, если ещё не установлен
|
||||
pip install pytest
|
||||
|
||||
# Запустите тесты (если они есть)
|
||||
pytest
|
||||
```
|
||||
|
||||
> *В текущей версии тестов нет, но вы можете добавить свои.*
|
||||
|
||||
---
|
||||
|
||||
## Вклад в проект
|
||||
|
||||
1. Сделайте fork репозитория.
|
||||
2. Создайте ветку `feature/your-feature`.
|
||||
3. Добавьте изменения и запустите тесты.
|
||||
4. Откройте Pull Request.
|
||||
|
||||
---
|
||||
|
||||
## Лицензия
|
||||
|
||||
MIT © 2026
|
||||
Reference in New Issue
Block a user