# lite-ness

> A minimal agent harness with turn/step loop, streaming LLM, tool execution, and append-only session logging — built to explore custom agent loops inspired by harnesses like DeepSeek's.
Published: 2026-09-02
Tags: agents, llm, python, cli, distributed-systems

Source: https://hugo-portfolio-teal.vercel.app/projects/lite-harness/

<!-- synced from GitHub README (scripts/sync-readmes.mjs) — edit the repo README, not this file -->

# lite-ness

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

## Install

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

## Run (mock LLM, no API key)

```bash
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):

```bash
# 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)

```bash
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)

```bash
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](https://docs.commandcode.ai).

```bash
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:

```bash
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

```bash
# 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)

```bash
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

```bash
pytest
```

### Durable sessions

```bash
# 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

```bash
# 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
```