сырой текст задания → плоская карточка: README.md
This commit is contained in:
+85
-83
@@ -1,32 +1,26 @@
|
|||||||
# Сырой текст задания → плоская карточка
|
# Task Card – превращение сырого текста задания в структурированные данные
|
||||||
|
|
||||||
## 📖 Описание проекта
|
## Описание проекта
|
||||||
В рамках курса «Ассистент по учёбе» вы разрабатываете модуль, который принимает **неформальное описание задачи** (например, сообщение преподавателя в чате) и преобразует его в структурированный объект. Полученный объект можно дальше фильтровать, сохранять или передавать следующему шагу пайплайна.
|
|
||||||
|
|
||||||
### Что делает программа?
|
`task_card.py` реализует модуль, который принимает неформальное описание задачи (как в переписке или на сайте курса) и преобразует его в **структурированный объект** `TaskCard`.
|
||||||
- Принимает одну строку/абзац с формулировкой задания.
|
Объект содержит поля:
|
||||||
- С помощью LLM (OpenAI, Azure, Anthropic и т.д.) извлекает ключевые поля:
|
|
||||||
- `title` – название задачи
|
|
||||||
- `subject` – предмет / тема
|
|
||||||
- `deadline_hint` – подсказка о сроке сдачи (строка в свободной форме)
|
|
||||||
- `deliverable_type` – тип сдаваемого материала (отчёт, код, презентация и т.п.)
|
|
||||||
- `grading_hints` – список строк с упоминаниями оценивания
|
|
||||||
|
|
||||||
### Почему это важно?
|
| Поле | Тип | Описание |
|
||||||
- Позволяет быстро структурировать входные данные без ручного парсинга.
|
|------|-----|----------|
|
||||||
- Делает дальнейшую обработку более надёжной и предсказуемой.
|
| `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
|
```bash
|
||||||
# Создайте виртуальное окружение (рекомендовано)
|
# Создайте виртуальное окружение (рекомендуется)
|
||||||
python -m venv .venv
|
python -m venv .venv
|
||||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
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
|
pip install langchain-core langchain-openai pydantic python-dotenv
|
||||||
```
|
```
|
||||||
|
|
||||||
> **Важно**:
|
> **Важно**
|
||||||
> 1. Создайте файл `.env` в корне проекта и добавьте ключи доступа к LLM, например:
|
> 1. Для работы с LLM понадобится ключ OpenAI (или другой провайдер).
|
||||||
> ```dotenv
|
> 2. Ключ можно задать через переменную окружения `OPENAI_API_KEY` или в файле `.env`.
|
||||||
> OPENAI_API_KEY=sk-...
|
|
||||||
> ```
|
|
||||||
> 2. Если используете другую модель (Azure, Anthropic), настройте соответствующие переменные окружения согласно документации `langchain-openai`.
|
|
||||||
|
|
||||||
## 📂 Структура проекта
|
---
|
||||||
|
|
||||||
```
|
## Как запустить
|
||||||
project/
|
|
||||||
├── .env # Переменные окружения
|
|
||||||
├── main.py # Точка входа – пример использования
|
|
||||||
├── task_parser.py # Модуль с Pydantic‑моделью и функцией парсинга
|
|
||||||
└── README.md # Это файл
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 Запуск
|
### 1️⃣ Запуск скрипта вручную
|
||||||
|
|
||||||
### 1. Пример запуска через `main.py`
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python main.py
|
# Убедитесь, что переменная OPENAI_API_KEY установлена
|
||||||
|
export OPENAI_API_KEY="sk-..."
|
||||||
|
|
||||||
|
python task_card.py
|
||||||
```
|
```
|
||||||
|
|
||||||
`main.py` содержит пример входного текста и выводит распарсенный объект.
|
При запуске скрипт запросит у пользователя ввод текста задания и выведет распарсенный объект `TaskCard`.
|
||||||
|
|
||||||
> **Вывод**
|
### 2️⃣ Использование как модуля
|
||||||
> ```text
|
|
||||||
> Task(title='Составить отчёт по проекту', subject='Информатика', deadline_hint='до 15.09', deliverable_type='отчёт', grading_hints=['проверка структуры, логики и оформления'])
|
|
||||||
> ```
|
|
||||||
|
|
||||||
### 2. Использование как библиотеки
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from task_parser import parse_task_text, Task
|
from task_card import parse_task_text, TaskCard
|
||||||
|
|
||||||
text = "Напиши код для решения задачи по алгоритмам до 20.10."
|
raw = """
|
||||||
task: Task = parse_task_text(text)
|
Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал.
|
||||||
print(task.title) # → 'Написать код'
|
Сдать код и README. Срок сдачи – через две недели после начала проекта.
|
||||||
print(task.grading_hints) # → ['проверка корректности кода', ...]
|
Оценка будет по качеству кода, читаемости и покрытию тестами.
|
||||||
|
"""
|
||||||
|
|
||||||
|
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": "Подготовка презентации",
|
"title": "Генерация отчёта о продажах",
|
||||||
"subject": "Машинное обучение",
|
"subject": "Python",
|
||||||
"deadline_hint": "до 30 сентября",
|
"deadline_hint": "через две недели после начала проекта",
|
||||||
"deliverable_type": "презентация",
|
"deliverable_type": "код и README",
|
||||||
"grading_hints": [
|
"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/)
|
|
||||||
|
|
||||||
## 🤝 Вклад
|
| Файл | Описание |
|
||||||
|
|------|----------|
|
||||||
Если хотите улучшить проект:
|
| `task_card.py` | Основной скрипт: определение модели, шаблона промпта и функции парсинга. |
|
||||||
1. Форкните репозиторий.
|
| `.env.example` | Пример файла с переменными окружения (ключи API). |
|
||||||
2. Создайте ветку с вашим изменением.
|
|
||||||
3. Откройте Pull Request и опишите, что было сделано.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**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