Stateful RAG AI Agent 🤖

Stateful RAG AI Agent — это интеллектуальный микросервис на базе FastAPI и LangGraph. Агент выступает в роли умного корпоративного ассистента, который умеет искать информацию по внутренней базе знаний (RAG) и выполнять действия в сторонних системах (создание задач, добавление комментариев), сохраняя при этом контекст диалога с каждым пользователем.

Проект ориентирован на локальное выполнение: генерация текста и векторные представления (embeddings) работают через локальный сервер Ollama, что гарантирует безопасность корпоративных данных.

---

🌟 Ключевые возможности

• Stateful Память (Контекст диалога): Агент запоминает историю общения и идентификаторы созданных задач для каждого user_id, обеспечивая бесшовный многошаговый диалог.
• RAG (Retrieval-Augmented Generation): Интегрированный поиск по .md документации с использованием векторной БД (ChromaDB) и эмбеддингов Nomic.
• Tool Calling (Использование инструментов): LLM самостоятельно принимает решение о вызове Python-функций (поиск документов, создание тикетов, добавление комментариев) на основе намерений пользователя.
• Структурированное логирование: Использование python-json-logger для удобной интеграции логов с системами мониторинга (ELK, Grafana Loki).

---

🛠 Технологический стек

• Web Фреймворк: FastAPI + Uvicorn
• LLM Оркестрация: LangChain & LangGraph
• Локальные нейросети: Ollama (модели: llama3.1, nomic-embed-text)
• Векторная база данных: ChromaDB
• Валидация и настройки: Pydantic & Pydantic Settings

---

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

rag_stateful_ai_agent/
├── docs/                   # Внутренняя документация в формате Markdown (.md)
│   ├── agents.md           
│   ├── fastapi.md          
│   └── rag.md              
├── agent.py                # Описание графа состояний (StateGraph) и логики LLM
├── log.py                  # Настройка JSON-логирования
├── main.py                 # FastAPI приложение, API роуты и менеджмент сессий
├── retriever.py            # Загрузка документов, чанкинг и инициализация ChromaDB
├── settings.py             # Глобальные настройки (Pydantic BaseSettings)
├── tools.py                # Инструменты для агента (search_docs, create_task, add_comment)
└── requirements.txt        # Зависимости проекта

---

🚀 Установка и запуск

1. Системные требования

• Python: 3.10, 3.11 или 3.12
• Ollama: Установленный локальный сервер (скачать с ollama.com)

2. Загрузка моделей Ollama

Перед запуском агента необходимо загрузить используемые LLM в Ollama:

ollama pull llama3.1
ollama pull nomic-embed-text

3. Настройка окружения

Склонируйте репозиторий и создайте виртуальное окружение:

python -m venv venv

# Активация для Windows:
venv\Scripts\activate
# Активация для Linux/macOS:
source venv/bin/activate

Установите необходимые зависимости:

pip install -r requirements.txt

4. Запуск сервера

Запустите FastAPI приложение с помощью Uvicorn:

uvicorn main:app_api --host 0.0.0.0 --port 8000 --reload

Сервер будет доступен по адресу: http://localhost:8000. Интерактивная документация (Swagger UI) доступна по адресу: http://localhost:8000/docs.

---

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

POST /ask

Главный эндпоинт для общения с агентом.

Пример запроса (Поиск по RAG):

curl -X 'POST' \
  'http://localhost:8000/ask' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "alex_123",
  "query": "Что такое RAG система?"
}'

Пример ответа:

{
  "answer": "RAG (Retrieval-Augmented Generation) — это система, которая используется для ответов на вопросы по документам. Подробнее..."
}

Пример запроса (Создание задачи с использованием контекста):

# Шаг 1: Просим создать задачу
curl -X 'POST' 'http://localhost:8000/ask' -H 'Content-Type: application/json' \
-d '{"user_id": "alex_123", "query": "Создай задачу на обновление серверов"}'
# Ответ: "Задача создана, её номер TSI-777."

# Шаг 2: Просим добавить комментарий (агент помнит ID задачи из предыдущего шага)
curl -X 'POST' 'http://localhost:8000/ask' -H 'Content-Type: application/json' \
-d '{"user_id": "alex_123", "query": "Добавь к ней комментарий: обновление запланировано на пятницу"}'
# Ответ: "Комментарий добавлен к задаче TSI-777."

---

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

Настройки проекта управляются через settings.py. Вы можете изменить их, создав файл .env или передав переменные окружения напрямую:

• OLLAMA_MODEL: Языковая модель (по умолчанию llama3.1).
• OLLAMA_EMBEDDING_MODEL: Модель для эмбеддингов (по умолчанию nomic-embed-text).
• DOCS_DIR: Путь к директории с документацией (по умолчанию ./docs).
• LOG_LEVEL: Уровень логирования (по умолчанию INFO).

---

🏗 Архитектура графа (LangGraph)

Агент построен как конечный автомат:

1. Узел agent: LLM анализирует системный промпт, историю сообщений пользователя (user_id) и принимает решение. Если нужен вызов функции, граф переходит к узлу tools. Если ответ готов — граф завершает работу (__end__).
2. Узел tools: Выполняет Python-функцию (например, запросы в векторную БД ChromaDB).
3. Узел update: Извлекает метаданные (например, task_id из ответа инструмента create_task) и обновляет глобальное состояние графа. Затем возвращает управление узлу agent для генерации финального ответа.