Сервис генерации Lua-кода по описанию на естественном языке с пошаговым подтверждением плана и кода, многоуровневой валидацией в изолированной песочнице и опциональным RAG-контекстом.
Проект создан для True Tech Hack 2026.
- Ключевые особенности
- Архитектура
- Быстрый старт (Docker Compose)
- HTTP API
- Контекст задачи (JSON)
- Конфигурация
- Операционные заметки
- Структура репозитория
- Локальная разработка
- Лицензия
- Session-based state machine — сессия проходит состояния: план → подтверждение плана → код → подтверждение кода → готово
- Автоисправление — при ошибках sandbox или LLM-критика код перегенерируется с фидбеком (до 20 попыток)
- Многоуровневая безопасность Lua:
- статический AST-анализ (опасные паттерны, запрещённые вызовы)
- runtime-песочница (ограничение памяти, таймаут, отключение
os/io/package/debug/coroutine)
- RAG-контекст — опциональное обогащение критики через Qdrant + эмбеддинги (
bge-m3) - TUI-клиент — терминальный интерфейс на Ratatui для интерактивной работы
┌──────────┐ ┌───────────────┐ ┌───────────────┐ ┌─────────────┐
│ curl / │───▶│ llm-service │───▶│ Ollama │───▶│ sandbox-svc │
│ TUI │ │ FastAPI:8080 │ │ qwen2.5-coder │ │ Rust:6778 │
│ │ │ state machine │ │ :11434 │ │ AST+sandbox │
└──────────┘ └───────┬───────┘ └───────────────┘ └──────┬──────┘
│ │
└────── Plan / Code ──── User ──────────┘
│
(опционально)
│
┌───────▼───────┐
│ Qdrant │
│ :6333 (RAG) │
└───────────────┘
| Компонент | Язык / Стек | Порт | Роль |
|---|---|---|---|
llm-service |
Python (FastAPI) | 8080 |
HTTP API, оркестрация, state machine |
sandbox-service |
Rust (Axum, mlua, tree-sitter) | 6778 |
AST-проверки + runtime-песочница Lua |
ollama |
— | 11434 |
Локальный LLM (генерация + критика) |
qdrant |
— | 6333 |
Векторная БД для RAG (опционально) |
llm-tui |
Rust (Ratatui, Crossterm) | — | Терминальный клиент |
Поток выполнения:
- Клиент отправляет задачу →
llm-serviceгенерирует план - Пользователь подтверждает план (или вносит правки → перегенерация)
llm-serviceгенерирует Lua-код → отправляет вsandbox-serviceна валидацию- При
llm_validation: true— дополнительное LLM-ревью кода - Пользователь подтверждает код → сессия переходит в
done
Требования: Docker 20.10+, Docker Compose v2+
# Запуск всего стека
docker compose up --build
# Проверка готовности (в другом терминале)
curl -s http://localhost:8080/healthПервый запуск скачивает модель Ollama (qwen2.5-coder:7b) — может занять время.
# Стек уже поднят, запускаем TUI
docker compose run --rm --no-deps -it llm-tuidocker compose downБазовый URL: http://localhost:8080
| Метод | Путь | Описание |
|---|---|---|
GET |
/health |
Проверка состояния сервиса |
POST |
/generate |
Создание/продолжение сессии генерации |
| Состояние | Описание |
|---|---|
awaiting_plan_confirmation |
Сгенерирован план, ожидается подтверждение / правки |
awaiting_code_approval |
Сгенерирован код (прошёл проверки), ожидается подтверждение / правки |
done |
Код одобрен, сессия завершена |
Краткий пример:
# 1. Новая сессия → план
curl -sS -X POST http://localhost:8080/generate \
-H "Content-Type: application/json" \
-d '{"task":"Напиши Lua-функцию для фильтрации таблицы"}'
# 2. Подтвердить план → получить код (тот же session_id)
curl -sS -X POST http://localhost:8080/generate \
-H "Content-Type: application/json" \
-d '{"session_id":"<id>","user_response":"Подтвердить"}'
# 3. Подтвердить код → done
curl -sS -X POST http://localhost:8080/generate \
-H "Content-Type: application/json" \
-d '{"session_id":"<id>","user_response":"Подтвердить"}'Полные примеры с правками и опциями: docs/api-examples.md
В поле task можно передать JSON-контекст. llm-service извлекает его, парсит и передаёт в sandbox-service как таблицу wf.
Очисти значения переменных ID, ENTITY_ID, CALL
{"wf": {"vars": {"RESTbody": {"result": [{"ID": 123}]}}, "initVariables": {}}}
Переменные окружения для llm-service (см. llm-service/.env.example). Docker Compose использует значения по умолчанию, кастомизация — через .env в корне проекта.
| Переменная | По умолчанию | Описание |
|---|---|---|
GENERATION_MODEL |
qwen2.5-coder:7b |
Модель Ollama для генерации |
EMBEDDING_MODEL |
bge-m3 |
Модель для эмбеддингов (RAG) |
OLLAMA_URL |
http://ollama:11434 |
Адрес Ollama |
SANDBOX_SERVICE_URL |
http://sandbox-service:6778 |
Адрес sandbox |
CONFIRM_WORD |
CODE_OK |
Кодовое слово одобрения от LLM-критика |
CODE_RETRIES_SANDBOX |
20 |
Попыток автофикса после ошибок sandbox |
CODE_RETRIES_MODEL |
2 |
Попыток перегенерации после ошибок модели |
QDRANT_URL |
http://qdrant:6333 |
Адрес Qdrant (опционально) |
QDRANT_COLLECTION |
lua_patterns |
Коллекция Qdrant |
EMBEDDINGS_URL |
http://embeddings:8000/v1/embeddings |
Сервис эмбеддингов (опционально) |
- Сессии хранятся в памяти
llm-service— при рестарте контейнера они теряются sandbox-serviceзапускается cprivileged: true— не публикуйте наружу без оценки рисков- Qdrant использует bind-mount
./qdrant_data— данные сохраняются между рестартами - Первый запуск стягивает модель Ollama (отдельный init-контейнер
ollama-init)
.
├── docker-compose.yml # Оркестрация всех сервисов
├── llm-service/ # FastAPI-оркестратор (Python)
│ └── app/
│ ├── api/ # Схемы + state machine
│ ├── core/ # Pipeline + промпты
│ ├── clients/ # Ollama, Sandbox, Qdrant клиенты
│ ├── utils/ # Парсеры
│ └── scripts/ # Утилиты
├── sandbox-service/ # Sandbox-валидатор Lua (Rust)
├── llm-tui/ # TUI-клиент (Rust/Ratatui)
└── docs/ # Документация (C4, pipeline, примеры, README.en.md)
llm-service (нужны запущенные Ollama и sandbox-service):
cd llm-service
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
OLLAMA_URL=http://localhost:11434 \
SANDBOX_SERVICE_URL=http://localhost:6778 \
uvicorn app.main:app --host 0.0.0.0 --port 8080 --reloadllm-tui:
cd llm-tui
LLM_SERVICE_URL=http://localhost:8080 cargo run