LangGraph AI Tutor Agent

Интеллектуальный агент-репетитор, созданный с использованием LangGraph и LangChain, который классифицирует вопросы пользователя и отвечает на них по математике, истории или английскому языку.

📋 Содержание

• Особенности
• Архитектура
• Установка
• Конфигурация
• Использование
• Структура проекта
• API Документация
• Разработка
• Вклад в проект
• Лицензия

Особенности

• LLM-интеграция с Together AI для мощных языковых моделей
• Ветвление с помощью LangGraph для сложной логики принятия решений
• Память диалога (RunnableWithMessageHistory) для контекстных бесед
• Автоматическая классификация вопросов по предметам
• Математические операции (сложение, вычитание)
• Обучение истории Казахстана
• Изучение английского языка
• Расширяемая архитектура для добавления новых предметов и навыков
• Гибкая конфигурация через YAML файлы

Архитектура

Проект построен на основе графа состояний (StateGraph) с использованием LangGraph:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Memory    │───▶│    Main     │───▶│  Classifier │
│   (История)  │    │ (Классификатор) │    │ (Маршрутизатор) │
└─────────────┘    └─────────────┘    └─────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
              ┌─────▼─────┐ ┌─────▼─────┐
              │   Math    │ │  History  │
              │ (Математика) │ │ (История)  │
              └─────┬─────┘ └─────┬─────┘
                    │             │
              ┌─────▼─────┐ ┌─────▼─────┐
              │ Plus/Minus│ │  English  │
              │ (Операции) │ │(Английский)│
              └───────────┘ └───────────┘

Основные компоненты:

1. GraphState - центральное состояние графа с полями:

   • text - входящий текст пользователя
   • memory - история диалога
   • answer - ответ агента

2. Классификатор - определяет тип вопроса (math/history/english)

3. Роутеры - направляют запросы к соответствующим инструментам

4. Инструменты - специализированные модули для каждого предмета

Установка

Предварительные требования

• Python 3.8 или выше
• API ключ Together AI

Быстрая установка

# Клонирование репозитория
git clone https://github.com/Kairatzh/langgraph-ai-tutor-agent.git
cd langgraph-ai-tutor-agent

# Установка зависимостей
pip install -r requirements.txt

# Или установка в режиме разработки
pip install -e ".[dev]"

Альтернативная установка через Makefile

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

# Установка для разработки
make install-dev

Конфигурация

1. Настройка переменных окружения

Скопируйте файл .env.example в .env:

cp env.example .env

Отредактируйте .env файл:

# Together AI API ключ
TOGETHER_API_KEY=your_together_api_key_here

2. Настройка конфигурации

Отредактируйте configs/config.yml:

project:
  name: "AgentPractic"

agent:
  model: "meta-llama/Llama-2-7b-chat-hf"  # Модель LLM
  together_api_key: ${TOGETHER_API_KEY}   # API ключ из переменной окружения
  temperature: 0.6                        # Креативность ответов (0.0-1.0)
  max_tokens: 100                         # Максимальная длина ответа

Использование

Базовое использование

from agent import agent_gen

# Простой вызов агента
result = agent_gen("Сколько будет 5 + 3?")
print(result.answer)

# Вопрос по истории
result = agent_gen("Расскажи о Чингисхане")
print(result.answer)

# Вопрос по английскому
result = agent_gen("Как сказать 'привет' по-английски?")
print(result.answer)

Запуск через командную строку

# Прямой запуск
python agent.py

# Через Makefile
make run

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

Математические операции:

agent_gen("5 + 3")  # Результат: 8
agent_gen("10 - 4") # Результат: 6

Вопросы по истории:

agent_gen("Кто такой Абай Кунанбаев?")
agent_gen("Расскажи о Великой Отечественной войне")

Изучение английского:

agent_gen("Как переводится слово 'computer'?")
agent_gen("Объясни Present Simple")

Структура проекта

AgentPractic/
├── agent.py                 # Основной скрипт агента
├── requirements.txt         # Зависимости Python
├── pyproject.toml          # Конфигурация проекта
├── Makefile               # Команды для разработки
├── README.md              # Документация
├── CHANGELOG.md           # История изменений
├── LICENSE                # Лицензия MIT
├── env.example            # Пример переменных окружения
│
├── configs/               # Конфигурационные файлы
│   ├── config.yml        # Основная конфигурация
│   └── settings.py       # Загрузчик конфигурации
│
├── tools/                 # Инструменты агента
│   ├── classifier_tools.py # Классификатор вопросов
│   ├── math_tools.py      # Математические операции
│   ├── history_tools.py   # Инструменты для истории
│   ├── english_tools.py   # Инструменты для английского
│   └── memory.py         # Система памяти диалога
│
└── utils/                 # Утилиты
    ├── prompts.py        # Шаблоны промптов
    └── states.py         # Определения состояний

API Документация

Основные функции

agent_gen(text: str) -> GraphState

Основная функция для взаимодействия с агентом.

Параметры:

• text (str): Вопрос или запрос пользователя

Возвращает:

• GraphState: Объект состояния с ответом агента

Пример:

result = agent_gen("Сколько будет 2 + 2?")
print(result.answer)  # "4"

Классы состояний

GraphState

class GraphState(BaseModel):
    text: Optional[str] = None      # Входящий текст
    memory: Optional[List[Dict[str, str]]] = None  # История диалога
    answer: Optional[str] = None    # Ответ агента

Инструменты

Математические инструменты

• plus_tool: Сложение двух чисел
• minus_tool: Вычитание двух чисел

Предметные инструменты

• history: Ответы на вопросы по истории Казахстана
• english_answer: Помощь в изучении английского языка
• classifier_tool: Классификация входящих вопросов

Разработка

Настройка окружения разработки

# Установка зависимостей для разработки
make install-dev

# Настройка pre-commit хуков
make setup-hooks

Доступные команды

# Запуск тестов
make test

# Проверка кода линтерами
make lint

# Форматирование кода
make format

# Очистка временных файлов
make clean

# Сборка пакета
make build

Тестирование

# Запуск всех тестов
pytest tests/ -v

# Запуск с покрытием кода
pytest tests/ -v --cov=tools --cov=utils --cov-report=html

Линтинг и форматирование

Проект использует:

• Black - форматирование кода
• isort - сортировка импортов
• flake8 - проверка стиля
• mypy - статическая типизация

Pre-commit хуки

Автоматическая проверка кода при коммитах:

# Установка хуков
make setup-hooks

# Обновление хуков
make update-hooks

Вклад в проект

Мы приветствуем вклад в развитие проекта!

Как внести вклад:

1. Форкните репозиторий
2. Создайте ветку для новой функции (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add amazing feature')
4. Отправьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

Стандарты кода:

• Следуйте PEP 8
• Добавляйте типы для всех функций
• Пишите документацию для новых функций
• Добавляйте тесты для новой функциональности

Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для получения дополнительной информации.

Автор

Kairat Zhaksylykov

• Email: [email protected]
• GitHub: @Kairatzh

Благодарности

• LangChain - фреймворк для работы с LLM
• LangGraph - библиотека для построения графов агентов
• Together AI - платформа для доступа к языковым моделям
• Pydantic - валидация данных

---

Если проект вам понравился, поставьте звезду на GitHub!