сырой текст задания → плоская карточка: README.md
This commit is contained in:
+92
-81
@@ -1,126 +1,137 @@
|
|||||||
# Task Card – превращение сырого текста задания в структурированные данные
|
# Task Card Extractor
|
||||||
|
|
||||||
## Описание проекта
|
A lightweight Python utility that transforms informal task descriptions into a **flat JSON card** containing the following fields:
|
||||||
|
|
||||||
`task_card.py` реализует модуль, который принимает неформальное описание задачи (как в переписке или на сайте курса) и преобразует его в **структурированный объект** `TaskCard`.
|
| Field | Description |
|
||||||
Объект содержит поля:
|
|-------|-------------|
|
||||||
|
| `title` | Название задания |
|
||||||
|
| `subject` | Тема/область задачи |
|
||||||
|
| `deadline_hint` | Подсказка по дедлайну |
|
||||||
|
| `deliverable_type` | Тип сдачи (отчёт, код и т.д.) |
|
||||||
|
| `grading_hints` | Ключевые критерии оценки |
|
||||||
|
|
||||||
| Поле | Тип | Описание |
|
The extractor uses **LangChain** with an OpenAI model to parse the raw text and output a validated `TaskCard` Pydantic object.
|
||||||
|------|-----|----------|
|
|
||||||
| `title` | `str` | Краткое название задачи |
|
|
||||||
| `subject` | `str` | Предмет или область знаний |
|
|
||||||
| `deadline_hint` | `str` | Указание срока сдачи в свободной форме |
|
|
||||||
| `deliverable_type` | `str` | Тип сдаваемого материала (отчёт, код, презентация и т.д.) |
|
|
||||||
| `grading_hints` | `List[str]` | Ключевые критерии оценки, упомянутые в тексте |
|
|
||||||
|
|
||||||
Модуль использует **LangChain** для общения с LLM и **Pydantic** для гарантированного парсинга результата.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Установка зависимостей
|
## 📦 Установка зависимостей
|
||||||
|
|
||||||
```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
|
||||||
|
|
||||||
# Установите зависимости
|
# Установите зависимости из requirements.txt
|
||||||
pip install langchain-core langchain-openai pydantic python-dotenv
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
> **Важно**
|
`requirements.txt`:
|
||||||
> 1. Для работы с LLM понадобится ключ OpenAI (или другой провайдер).
|
|
||||||
> 2. Ключ можно задать через переменную окружения `OPENAI_API_KEY` или в файле `.env`.
|
```text
|
||||||
|
langchain-core>=0.2.0
|
||||||
|
langchain-openai>=0.1.0
|
||||||
|
pydantic>=2.0
|
||||||
|
openai>=1.0 # для ChatOpenAI
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Важно**:
|
||||||
|
> Установите переменную окружения `OPENAI_API_KEY` с вашим ключом OpenAI, иначе модель не сможет работать.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export OPENAI_API_KEY="sk-..."
|
||||||
|
# Windows:
|
||||||
|
set OPENAI_API_KEY=sk-...
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Как запустить
|
## 📁 Структура проекта
|
||||||
|
|
||||||
### 1️⃣ Запуск скрипта вручную
|
| Файл | Описание |
|
||||||
|
|------|----------|
|
||||||
|
| `extract_task_card.py` | Основной скрипт, содержащий модель `TaskCard`, конфигурацию LangChain и пример запуска. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Запуск
|
||||||
|
|
||||||
|
### 1️⃣ Простой запуск через CLI
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Убедитесь, что переменная OPENAI_API_KEY установлена
|
python extract_task_card.py "Напиши задание по теме «Алгоритмы сортировки». Дедлайн – завтра. Сдача: код + отчёт. Оценка по точности, читаемости и эффективности."
|
||||||
export OPENAI_API_KEY="sk-..."
|
|
||||||
|
|
||||||
python task_card.py
|
|
||||||
```
|
```
|
||||||
|
|
||||||
При запуске скрипт запросит у пользователя ввод текста задания и выведет распарсенный объект `TaskCard`.
|
Вывод будет в формате JSON:
|
||||||
|
|
||||||
### 2️⃣ Использование как модуля
|
```json
|
||||||
|
{
|
||||||
|
"title": "Алгоритмы сортировки",
|
||||||
|
"subject": "Тема «Алгоритмы сортировки»",
|
||||||
|
"deadline_hint": "завтра",
|
||||||
|
"deliverable_type": "код + отчёт",
|
||||||
|
"grading_hints": [
|
||||||
|
"точность",
|
||||||
|
"читаемость",
|
||||||
|
"эффективность"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2️⃣ Запуск из кода
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from task_card import parse_task_text, TaskCard
|
from pathlib import Path
|
||||||
|
import os
|
||||||
|
|
||||||
|
# Импортируем модель и функцию извлечения
|
||||||
|
from extract_task_card import TaskCard, extract_from_text
|
||||||
|
|
||||||
raw = """
|
raw = """
|
||||||
Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал.
|
Напиши задание по теме «Алгоритмы сортировки». Дедлайн – завтра.
|
||||||
Сдать код и README. Срок сдачи – через две недели после начала проекта.
|
Сдача: код + отчёт. Оценка по точности, читаемости и эффективности.
|
||||||
Оценка будет по качеству кода, читаемости и покрытию тестами.
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
card: TaskCard = parse_task_text(raw)
|
card = extract_from_text(raw)
|
||||||
print(card.json(indent=2))
|
print(card.json(indent=2))
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Пример использования
|
## 📚 Пример использования
|
||||||
|
|
||||||
```bash
|
```python
|
||||||
$ python task_card.py
|
from extract_task_card import TaskCard, extract_from_text
|
||||||
Введите текст задания:
|
|
||||||
Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал.
|
|
||||||
Сдать код и README. Срок сдачи – через две недели после начала проекта.
|
|
||||||
Оценка будет по качеству кода, читаемости и покрытию тестами.
|
|
||||||
|
|
||||||
Результат:
|
raw_description = """
|
||||||
{
|
Создать программу, которая генерирует случайный массив из 1000 чисел,
|
||||||
"title": "Генерация отчёта о продажах",
|
сортирует его методом быстрой сортировки и выводит время выполнения.
|
||||||
"subject": "Python",
|
Дедлайн – через неделю. Сдача: код + краткое описание алгоритма.
|
||||||
"deadline_hint": "через две недели после начала проекта",
|
Оценка по скорости, корректности и читаемости кода.
|
||||||
"deliverable_type": "код и README",
|
"""
|
||||||
"grading_hints": [
|
|
||||||
"качество кода",
|
task_card = extract_from_text(raw_description)
|
||||||
"читаемость",
|
|
||||||
"покрытие тестами"
|
print("Title:", task_card.title)
|
||||||
]
|
print("Subject:", task_card.subject)
|
||||||
}
|
print("Deadline hint:", task_card.deadline_hint)
|
||||||
|
print("Deliverable type:", task_card.deliverable_type)
|
||||||
|
print("Grading hints:", ", ".join(task_card.grading_hints))
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Структура файлов
|
## 🔧 Настройка модели
|
||||||
|
|
||||||
| Файл | Описание |
|
- **Модель**: по умолчанию используется `gpt-4o-mini`. При необходимости можно изменить в коде:
|
||||||
|------|----------|
|
```python
|
||||||
| `task_card.py` | Основной скрипт: определение модели, шаблона промпта и функции парсинга. |
|
llm = ChatOpenAI(model="gpt-4o", temperature=0.2)
|
||||||
| `.env.example` | Пример файла с переменными окружения (ключи API). |
|
```
|
||||||
|
- **Температура**: регулирует креативность ответа (по умолчанию 0.2).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Тестирование
|
## 📜 Лицензия
|
||||||
|
|
||||||
```bash
|
MIT License – свободно используйте и модифицируйте по своему усмотрению.
|
||||||
# Установите pytest, если ещё не установлен
|
|
||||||
pip install pytest
|
|
||||||
|
|
||||||
# Запустите тесты (если они есть)
|
---
|
||||||
pytest
|
|
||||||
```
|
|
||||||
|
|
||||||
> *В текущей версии тестов нет, но вы можете добавить свои.*
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Вклад в проект
|
|
||||||
|
|
||||||
1. Сделайте fork репозитория.
|
|
||||||
2. Создайте ветку `feature/your-feature`.
|
|
||||||
3. Добавьте изменения и запустите тесты.
|
|
||||||
4. Откройте Pull Request.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Лицензия
|
|
||||||
|
|
||||||
MIT © 2026
|
|
||||||
Reference in New Issue
Block a user