LocalScript

LocalScript turns natural-language descriptions into validated, ready-to-use Lua scripts — entirely on your own infrastructure.

Every generation runs through a human-in-the-loop workflow: the LLM proposes a plan, you approve it (or request edits), the LLM writes the code, the code is checked by a multi-layered sandbox and an optional LLM critic, and only then do you approve the final result. No untested, unvalidated code ever reaches your workflow.

Built for the True Tech Hack 2026.

---

Key Features

• Step-by-step confirmation workflow — a session state machine guides you through plan → plan approval → code → code approval → done, with revision loops at every step.
• Auto-fix loop — if sandbox validation or the LLM critic finds problems, the code is regenerated with targeted feedback (up to 20 sandbox retries).
• Multi-layered Lua security:
  • Static analysis with a tree-sitter AST — syntax validation, dangerous pattern detection, and forbidden call checks (os, io, package, debug, dynamic loading, …).
  • Runtime sandbox powered by mlua — 8 MB memory limit, configurable timeout with an instruction hook, and disabled privileged globals (os/io/package/debug/coroutine).
• Optional RAG context — plan chunks are embedded (bge-m3) and matched against a Qdrant vector collection to enrich code generation and critique.
• TUI client — a Ratatui-based terminal client with an interactive chat interface, clipboard copy, and one-click export of the generated Lua/JSON.
• 100% local — no cloud APIs; everything runs in Docker Compose on your machine.

---

Architecture

┌──────────┐    ┌─────────────────┐    ┌───────────────┐    ┌─────────────────┐
│  curl /  │───▶│   llm-service   │───▶│     Ollama    │───▶│  sandbox-service│
│   TUI    │    │  FastAPI  :8080 │    │ qwen2.5-coder │    │  Axum  :6778    │
│          │    │  state machine  │    │     :11434    │    │  AST + sandbox  │
└──────────┘    └────────┬────────┘    └───────────────┘    └────────┬────────┘
                         │                                           │
                         └──────── Plan / Code ──── User ────────────┘
                                                          │
                                                   (optional)
                                                          │
                                                   ┌──────▼───────┐
                                                   │   Qdrant     │
                                                   │  :6333 (RAG) │
                                                   └──────────────┘

Component	Language / Stack	Port	Role
llm-service	Python (FastAPI)	8080	HTTP API, orchestration, session state machine
sandbox-service	Rust (Axum, mlua, tree-sitter)	6778	AST checks + Lua runtime sandbox
ollama	—	11434	Local LLM (plan, code generation, critique)
qdrant	—	6333	Vector DB for RAG (optional)
llm-tui	Rust (Ratatui, Crossterm)	—	Terminal client

Full architectural details: docs/architecture.md

---

Quick Start (Docker Compose)

Requirements: Docker 20.10+, Docker Compose v2+.

# Start the full stack (builds images, starts Ollama, Qdrant, sandbox, API)
docker compose up --build

# In another terminal — verify health
curl -s http://localhost:8080/health

The first start downloads the qwen2.5-coder:7b model (a separate ollama-init container handles this). This can take several minutes depending on your connection.

Try it with curl

# 1. New session → the service returns a plan
curl -sS -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"task":"Write a Lua function that filters a table of orders by total >= 100"}'

# 2. Approve the plan (reuse the session_id from the response) → validated code
curl -sS -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<id>","user_response":"approve"}'

# 3. Approve the code → session is done
# (code approval currently accepts the exact word "подтвердить")
curl -sS -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<id>","user_response":"подтвердить"}'

Try it with the TUI

# Stack must be running; launch the TUI in a separate terminal
docker compose run --rm --no-deps -it llm-tui

Stop the stack

docker compose down

---

Documentation

Document	Contents
docs/architecture.md	System architecture, session state machine, generation & validation pipeline, RAG flow
docs/api-reference.md	Full HTTP API reference for llm-service and sandbox-service, with JSON examples
docs/configuration.md	All environment variables and Docker Compose options
docs/sandbox-security.md	Lua security model: AST checks, forbidden calls, runtime limits, error taxonomy
docs/development.md	Local development, building, and running each service without Docker
docs/tui.md	TUI client usage, key bindings, and export features
docs/README.md	Documentation index

---

Repository Layout

.
├── docker-compose.yml         # Orchestration of all services
├── llm-service/               # FastAPI orchestrator (Python)
│   └── app/
│       ├── api/               # Request/response schemas + session state machine
│       ├── core/              # Generation pipeline + prompt templates
│       ├── clients/           # Ollama, sandbox, and RAG/Qdrant clients
│       ├── utils/             # Task JSON-context parser and helpers
│       └── scripts/           # Standalone utility scripts
├── sandbox-service/           # Lua AST validation + runtime sandbox (Rust)
│   └── src/
│       ├── ast/               # tree-sitter parsing, call extraction, safety rules
│       ├── executor/          # mlua-based runtime sandbox
│       └── routes/            # HTTP endpoints (/pipeline, /health)
├── llm-tui/                   # Terminal client (Rust / Ratatui)
└── docs/                      # Documentation

---

Contributing

Contributions are welcome! Please:

1. Fork the repository and create a feature branch.
2. Keep changes focused and add/update documentation in docs/ when behavior changes.
3. Verify your changes — see docs/development.md for local setup.

---

License

Licensed under the Apache License 2.0.