Skip to content

development.md

Latest commit

 

History

History
164 lines (114 loc) · 4.85 KB

development.md

File metadata and controls

164 lines (114 loc) · 4.85 KB
Raw

Development

This guide explains how to build and run each service locally — without Docker — and how to verify changes.

Table of Contents

Prerequisites

Tool Version Used by
Rust / Cargo 1.88+ (edition 2024) sandbox-service, llm-tui
Python 3.12+ llm-service
Docker + Compose 20.10+ / v2+ full stack
Ollama any recent local LLM runtime

mlua uses a vendored Lua build, and tree-sitter-lua compiles from source, so the first Rust build takes a while. No system Lua libraries are required.

Run everything with Docker (fast path)

# Build images and start the full stack
docker compose up --build

# Health check
curl -s http://localhost:8080/health

# Interactive TUI (in another terminal)
docker compose run --rm --no-deps -it llm-tui

# Stop
docker compose down

See the main README and configuration.md for details.

sandbox-service (Rust)

The Rust service depends on nothing external, so it can be built and run standalone.

cd sandbox-service

# Debug build
cargo build

# Release build (used in production images)
cargo build --release

# Run (listens on 0.0.0.0:6778)
cargo run

Optional logging control:

RUST_LOG=debug cargo run

Smoke test:

curl -s http://localhost:6778/health
# ok

curl -sS -X POST http://localhost:6778/pipeline \
  -H "Content-Type: application/json" \
  -d '{"code":"return 1 + 1","execute":true}'

llm-service (Python)

Requires a running Ollama and a running sandbox-service. Start those first.

# Ensure Ollama has the model
ollama pull qwen2.5-coder:7b

cd llm-service
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Point the service at local instances and start with auto-reload
OLLAMA_URL=http://localhost:11434 \
SANDBOX_SERVICE_URL=http://localhost:6778 \
uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

Smoke test:

curl -s http://localhost:8080/health

curl -sS -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"task":"Write a Lua function that doubles a number"}'

Utility scripts

Script Purpose
app/scripts/run_model.py Standalone pipeline run against Ollama (plan + code for a hardcoded sample task).
app/scripts/qdrant_delete.py Deletes the lua_patterns Qdrant collection (run against a local Qdrant on localhost:6333).

llm-tui (Rust)

Requires llm-service to be running.

cd llm-tui

# Point the TUI at a locally running llm-service
LLM_SERVICE_URL=http://localhost:8080 cargo run

Logs are appended to llm-tui.log in the current working directory.

Verifying your changes

  1. Build checks: cargo build (or cargo build --release) for sandbox-service and llm-tui; python -c "import app.main" (or run uvicorn) for llm-service.
  2. Service health: both /health endpoints return ok.
  3. End-to-end session: run the worked example against a locally started stack, including a sandbox rejection (e.g. ask for code using os.execute and confirm the safety error is surfaced as sandbox_feedback).
  4. Sandbox edge cases:
    • Syntax error: submit code with invalid syntax → status: syntax_error.
    • Forbidden call: os.execute('ls') → status: safety_error.
    • Timeout: while true do end with timeout: 1 → status: timeout.
    • Memory limit: allocate a large table → memory_limit.
    • Context: submit context and reference wf.vars in code.

Common issues

Symptom Likely cause / fix
/generate returns 400 "task is required for a new session" A task is required when creating a session; pass one.
Generation hangs or times out Ollama model not pulled yet; run ollama pull qwen2.5-coder:7b.
sandbox-service unreachable from llm-service Wrong SANDBOX_SERVICE_URL (use http://localhost:6778 locally).
RAG produces no context Qdrant or the embeddings endpoint is unreachable — RAG silently falls back to no context. Verify QDRANT_URL/EMBEDDINGS_URL and that the collection exists.
LLM critic blocks all code The critic prompt is strict; check CONFIRM_WORD or disable validation with "llm_validation": false per request.
Rust build fails on a fresh machine Vendored Lua/tree-sitter compile errors are usually toolchain-related; ensure Rust 1.88+ and retry.