LocalScript

Сервис генерации 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)	—	Терминальный клиент

Поток выполнения:

1. Клиент отправляет задачу → llm-service генерирует план
2. Пользователь подтверждает план (или вносит правки → перегенерация)
3. llm-service генерирует Lua-код → отправляет в sandbox-service на валидацию
4. При llm_validation: true — дополнительное LLM-ревью кода
5. Пользователь подтверждает код → сессия переходит в done

---

Быстрый старт (Docker Compose)

Требования: Docker 20.10+, Docker Compose v2+

# Запуск всего стека
docker compose up --build

# Проверка готовности (в другом терминале)
curl -s http://localhost:8080/health

Первый запуск скачивает модель Ollama (qwen2.5-coder:7b) — может занять время.

Запуск TUI

# Стек уже поднят, запускаем TUI
docker compose run --rm --no-deps -it llm-tui

Остановка

docker compose down

---

HTTP API

Базовый URL: http://localhost:8080

Метод	Путь	Описание
GET	/health	Проверка состояния сервиса
POST	/generate	Создание/продолжение сессии генерации

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

---

Контекст задачи (JSON)

В поле 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 запускается c privileged: 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 --reload

llm-tui:

cd llm-tui
LLM_SERVICE_URL=http://localhost:8080 cargo run

---

Лицензия

Apache 2.0