diff --git a/solutions/69dd4221f309a98be0006b2e_сырой_текст_задания___плоская_карточка/README.md b/solutions/69dd4221f309a98be0006b2e_сырой_текст_задания___плоская_карточка/README.md index 4f36504..c9847fd 100644 --- a/solutions/69dd4221f309a98be0006b2e_сырой_текст_задания___плоская_карточка/README.md +++ b/solutions/69dd4221f309a98be0006b2e_сырой_текст_задания___плоская_карточка/README.md @@ -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` | Ключевые критерии оценки | -| Поле | Тип | Описание | -|------|-----|----------| -| `title` | `str` | Краткое название задачи | -| `subject` | `str` | Предмет или область знаний | -| `deadline_hint` | `str` | Указание срока сдачи в свободной форме | -| `deliverable_type` | `str` | Тип сдаваемого материала (отчёт, код, презентация и т.д.) | -| `grading_hints` | `List[str]` | Ключевые критерии оценки, упомянутые в тексте | - -Модуль использует **LangChain** для общения с LLM и **Pydantic** для гарантированного парсинга результата. +The extractor uses **LangChain** with an OpenAI model to parse the raw text and output a validated `TaskCard` Pydantic object. --- -## Установка зависимостей +## 📦 Установка зависимостей ```bash # Создайте виртуальное окружение (рекомендуется) python -m venv .venv -source .venv/bin/activate # Windows: .venv\Scripts\activate +source .venv/bin/activate # Windows: .\.venv\Scripts\activate -# Установите зависимости -pip install langchain-core langchain-openai pydantic python-dotenv +# Установите зависимости из requirements.txt +pip install -r requirements.txt ``` -> **Важно** -> 1. Для работы с LLM понадобится ключ OpenAI (или другой провайдер). -> 2. Ключ можно задать через переменную окружения `OPENAI_API_KEY` или в файле `.env`. +`requirements.txt`: + +```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 -# Убедитесь, что переменная OPENAI_API_KEY установлена -export OPENAI_API_KEY="sk-..." - -python task_card.py +python extract_task_card.py "Напиши задание по теме «Алгоритмы сортировки». Дедлайн – завтра. Сдача: код + отчёт. Оценка по точности, читаемости и эффективности." ``` -При запуске скрипт запросит у пользователя ввод текста задания и выведет распарсенный объект `TaskCard`. +Вывод будет в формате JSON: -### 2️⃣ Использование как модуля +```json +{ + "title": "Алгоритмы сортировки", + "subject": "Тема «Алгоритмы сортировки»", + "deadline_hint": "завтра", + "deliverable_type": "код + отчёт", + "grading_hints": [ + "точность", + "читаемость", + "эффективность" + ] +} +``` + +### 2️⃣ Запуск из кода ```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 = """ -Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал. -Сдать код и README. Срок сдачи – через две недели после начала проекта. -Оценка будет по качеству кода, читаемости и покрытию тестами. +Напиши задание по теме «Алгоритмы сортировки». Дедлайн – завтра. +Сдача: код + отчёт. Оценка по точности, читаемости и эффективности. """ -card: TaskCard = parse_task_text(raw) +card = extract_from_text(raw) print(card.json(indent=2)) ``` --- -## Пример использования +## 📚 Пример использования -```bash -$ python task_card.py -Введите текст задания: -Нужно написать программу на Python, которая будет генерировать отчёт о продажах за последний квартал. -Сдать код и README. Срок сдачи – через две недели после начала проекта. -Оценка будет по качеству кода, читаемости и покрытию тестами. +```python +from extract_task_card import TaskCard, extract_from_text -Результат: -{ - "title": "Генерация отчёта о продажах", - "subject": "Python", - "deadline_hint": "через две недели после начала проекта", - "deliverable_type": "код и README", - "grading_hints": [ - "качество кода", - "читаемость", - "покрытие тестами" - ] -} +raw_description = """ +Создать программу, которая генерирует случайный массив из 1000 чисел, +сортирует его методом быстрой сортировки и выводит время выполнения. +Дедлайн – через неделю. Сдача: код + краткое описание алгоритма. +Оценка по скорости, корректности и читаемости кода. +""" + +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)) ``` --- -## Структура файлов +## 🔧 Настройка модели -| Файл | Описание | -|------|----------| -| `task_card.py` | Основной скрипт: определение модели, шаблона промпта и функции парсинга. | -| `.env.example` | Пример файла с переменными окружения (ключи API). | +- **Модель**: по умолчанию используется `gpt-4o-mini`. При необходимости можно изменить в коде: + ```python + llm = ChatOpenAI(model="gpt-4o", temperature=0.2) + ``` +- **Температура**: регулирует креативность ответа (по умолчанию 0.2). --- -## Тестирование +## 📜 Лицензия -```bash -# Установите pytest, если ещё не установлен -pip install pytest +MIT License – свободно используйте и модифицируйте по своему усмотрению. -# Запустите тесты (если они есть) -pytest -``` - -> *В текущей версии тестов нет, но вы можете добавить свои.* - ---- - -## Вклад в проект - -1. Сделайте fork репозитория. -2. Создайте ветку `feature/your-feature`. -3. Добавьте изменения и запустите тесты. -4. Откройте Pull Request. - ---- - -## Лицензия - -MIT © 2026 \ No newline at end of file +--- \ No newline at end of file