↓ Skip to main content
Ishan

lite-ness

·728 words·4 mins

Tags

Agents Llm Python Cli Distributed-Systems

Technologies

Python asyncio LLM ClickHouse
View on GitHub

lite-ness
#

A minimal agent harness: turn/step loop, streaming LLM, tool execution, and an append-only session log.

Install
#

cd lite-ness
pip install -e ".[dev]"

Run (mock LLM, no API key)
#

liteness run "Read README.md and tell me what this repository does."

REPL (interactive)
#

Keep one live session across prompts, with streaming output and control commands. ClickHouse export and the local Docker container start automatically (use --no-clickhouse to disable):

# mock provider, no API key — ClickHouse on by default
liteness repl --provider mock --readme README.md

# live provider with a preset
liteness repl --preset coder --provider openai --model gpt-4o-mini

# durable session (resumable by pointing at the same file)
liteness repl --preset researcher --provider google --session-file ./sessions/repl.jsonl

In the REPL:

  • type a prompt and press Enter to run a turn
  • :tools — list installed tools
  • :history — print session events so far
  • :report — print telemetry trace for the current session
  • :reset — clear the current session in place
  • :preset <name> — switch preset in place (same session)
  • :q / Ctrl+D — quit

Pass --debug at startup to show tool calls, result sizes, streaming chunks, and turn summaries during each prompt. Without it, only the final answer is printed (use :history or :report to inspect the session).

Ctrl+C cancels the in-flight turn and returns to the prompt.

Streaming note: assistant chunks are emitted after each turn’s LLM stream completes (buffered), not token-by-token as the stream progresses. Live token streaming is tracked as a follow-up — it requires emitting assistant/chunk events during iteration inside the agent loop.

Run (OpenAI-compatible API)
#

pip install -e ".[openai]"
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1   # optional
liteness run "Read README.md and tell me what this repository does." --provider openai

Run (Google Gemini)
#

pip install -e ".[google]"
export GOOGLE_API_KEY=...   # or GEMINI_API_KEY
liteness run "Read README.md and summarize." --provider google --model gemini-2.0-flash

Run (Command Code Provider API)
#

Command Code routes Anthropic-shaped models to /messages; this harness uses /chat/completions only. Pick OpenAI or open-source model IDs from Command Code’s model list.

pip install -e ".[openai]"   # Command Code uses the OpenAI-compatible adapter
export COMMANDCODE_API_KEY=...
liteness run "List files in this directory." --provider commandcode --model gpt-4o-mini

Install all providers at once:

pip install -e ".[all-providers]"

Architecture
#

See discussionDocs/ for design notes.

Observability (traces, metrics, CLI report) and control-plane policies (budget, retry):

AgentLoop (control)          TelemetryPlugin (observe)
├── BudgetManager            ├── TraceStore
├── RetryPolicy              ├── MetricsStore
└── CancelToken              └── CLI report

Plugin composition, presets, memory, and RAG:

Preset → Plugins → Context (tools, events, effect)
                         ↓
              AgentLoop → LLM → Session events

Presets
#

# Coder: filesystem + terminal
liteness run --preset coder "Read README.md and summarize."

# Researcher: memory + RAG (index docs first)
liteness index discussionDocs/
liteness run --preset researcher "What does the design say about session recovery?"

# Video editor: resolve URLs, plan edits, ffmpeg tools (uses the same --provider as the agent)
# ffmpeg: auto-downloaded on first use (pip install -e ".[video]") or use system PATH
# pip install -U -e ".[video-download]" for YouTube/HTTP sources (keep yt-dlp updated)
# pip install -e ".[video-whisper]" for local burned subtitles (faster-whisper)
liteness run --preset video_editor --provider commandcode --max-steps 20 \
  "Remove the intro from https://youtube.com/watch?v=..."

# Burned subtitles (local faster-whisper + ffmpeg):
liteness run --preset video_editor --provider openai --max-steps 15 \
  "Add English subtitles to ./my-video.mp4"

Edited videos are written next to the input as {name}_edited_{timestamp}.mp4. Subtitled outputs use {name}_subtitled_{timestamp}.mp4. Downloads and intermediates use ./.liteness-video-temp/.

ClickHouse export (optional)
#

pip install -e ".[clickhouse]"
docker compose -f docker/clickhouse/docker-compose.yml up -d
# set LITENESS_CLICKHOUSE_USER/PASSWORD in .env (see .env.example; matches docker-compose)
liteness run --clickhouse --session-file .sessions/demo.jsonl "Read README.md and summarize."
# inspect: examples/clickhouse/queries.sql
liteness export-clickhouse .sessions/demo.jsonl   # backfill (redacted)

Default export redacts message content and tool arguments. Use --clickhouse-full (or export-clickhouse --full) only on a trusted local warehouse.

Tests
#

pytest

Durable sessions
#

# Run with JSONL log (created automatically, fsync per event)
liteness run "Read README.md and summarize." --session-file ./sessions/demo.jsonl

# Resume a session for another turn
liteness run "Now explain the architecture." --session-file ./sessions/demo.jsonl

# Recover orphan tool/call entries after a crash
liteness recover ./sessions/demo.jsonl

# Replay recorded LLM outputs from the log (no live model)
liteness run "continue" --session-file ./sessions/demo.jsonl --replay

Observability
#

# Print trace tree + metrics after a run
liteness run "Read README.md and summarize." --session-file ./sessions/demo.jsonl --report

# Build report from an existing session log
liteness report ./sessions/demo.jsonl