Skip to content

usage.en.md

Latest commit

 

History

History
234 lines (151 loc) · 13.1 KB

usage.en.md

File metadata and controls

234 lines (151 loc) · 13.1 KB
Raw

Usage and Contributor Guide

中文 · Back to English README · Architecture guide · Memory and evaluation guide

This guide is for first-time users of the current Web or CLI experience and contributors who want to reproduce the repository's development checks. It covers the trusted-local boundary, configuration, entry points, JSON API, Memory storage, and quality checks. See the Memory and evaluation guide for the separate CUDA workflow behind the LongMemEval Retrieval Baseline.

Read the security boundary first: this is a trusted-local, single-User development tool. It has no production authentication or multi-User isolation. Django uses development settings including DEBUG = True; embedded local Qdrant suits one process, and concurrent Web/CLI access needs a shared service URL. Do not expose the Web app or /api/chat/ to the public internet; the Agent can run shell commands and change files in the selected workspace.

Run the application

Requirements and installation

The project requires Python 3.13+ and uv. Sync the locked dependencies from the repository root:

uv sync --locked

This creates or updates .venv in the project root. Ordinary Web, CLI, and development workflows use the default CPU and development dependencies. The remaining commands use uv run, so manual environment activation is not normally needed.

cuda-eval is a separate optional dependency selection for the pinned Linux CUDA host and conflicts with the ordinary CPU selection. Do not add it to an everyday development environment. To reproduce the LongMemEval Retrieval Baseline, follow the pinned-host workflow in the Memory and evaluation guide.

Configure the environment

Create a local configuration file from the example:

cp .env.example .env

Edit .env with a real model and credentials. Never commit .env, or put credentials in screenshots, issues, or logs:

MODEL_ID=your_model_id
ANTHROPIC_API_KEY=your_api_key
MEMORY_ENABLED=false
# ANTHROPIC_BASE_URL=
# MEMORY_QDRANT_LOCATION=~/.mini-code-agent/qdrant
# MEMORY_QDRANT_COLLECTION=mini_code_agent_memories
# MEMORY_MAX_TOKENS=1200
Variable Purpose and default
MODEL_ID Required; the model ID passed to the Anthropic Messages API.
ANTHROPIC_API_KEY Credential required for ordinary Anthropic API calls.
ANTHROPIC_BASE_URL Optional Anthropic-compatible API base URL.
MEMORY_ENABLED .env.example sets false to skip Memory initialization, recall, and the remember tool; chat, workspace tools, and Conversation Transcript still work. Set true to enable Memory. If unset, the existing enabled behavior is preserved.
MEMORY_QDRANT_LOCATION Optional local path or complete http(s):// Qdrant service URL; defaults to ~/.mini-code-agent/qdrant.
MEMORY_QDRANT_COLLECTION Optional collection name; defaults to mini_code_agent_memories.
MEMORY_MAX_TOKENS Optional Memory-extraction output limit; defaults to 1200.

Database and Web

The SQLite database lives at the repository root as db.sqlite3; templates and static assets live in src/main/resources/. Create the tables, then start the Django development server:

uv run --locked python src/main/python/manage.py migrate
uv run --locked python src/main/python/manage.py runserver

Open http://127.0.0.1:8000/ in a browser, select New conversation, then send a message. With no Conversation selected, the Web entry point creates one for the process's current workspace. With a Conversation selected, the new Conversation inherits that Conversation's workspace. Its sidebar shows the local User's Conversations grouped by Memory Space (workspace). New Turns run in the selected Conversation's workspace.

CLI

The CLI resolves its workspace from the current directory. Without arguments it creates a new Conversation and prints its UUID:

uv run --locked python src/main/python/cli.py

It can list or resume only Conversations in the current Memory Space:

uv run --locked python src/main/python/cli.py --list
uv run --locked python src/main/python/cli.py --resume <conversation-uuid>

Exit with q, exit, an empty line, Ctrl-C, or EOF. Moving or renaming a workspace creates a new Memory Space, so the CLI cannot resume a Conversation from the old path at the new path.

To run the Agent against another workspace while retaining this project's environment, start from the target directory:

cd /path/to/workspace
uv run --project /path/to/mini-code-agent \
  python /path/to/mini-code-agent/src/main/python/cli.py

This binds the Conversation, Memory Space, file tools, and shell to /path/to/workspace, while dependencies still come from mini-code-agent. If a Web-stored workspace no longer exists, its Conversation Transcript remains readable but new Turns and tool execution are unavailable.

Web and JSON API

Use the Web interface

The Web interface is the recommended entry point. It creates and selects Conversations, then issues JSON requests with the page's CSRF token. A Conversation Transcript is durable conversation history; recalled Memory is temporary system context for a Turn, not the same thing. See the architecture guide for Agent Runtime, Memory Context, and tool boundaries.

The Web entry point declines confirmation for potentially destructive bash commands. That is not a security sandbox. Use the CLI in a trusted terminal when interactive confirmation is appropriate, and review the command first.

CSRF-protected JSON API

POST /api/chat/ accepts a JSON object whose conversation_id is an existing Conversation UUID and whose message is a non-empty string. A successful response has ok, conversation_id, title, normalized user, visible assistant text, and the currently fixed-empty tool_trace. Missing or invalid input returns 400; an unknown Conversation returns 404; an unavailable workspace returns 409; model or runtime failures return 5xx.

The API is protected by Django's CSRF middleware. First create a Conversation in the Web interface, then get its UUID from the conversation URL parameter or CLI output. Request the homepage to save a CSRF cookie:

curl -c cookies.txt http://127.0.0.1:8000/

Copy the real csrftoken from cookies.txt, then send both its matching cookie and request header:

curl -X POST http://127.0.0.1:8000/api/chat/ \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <csrftoken-from-cookies.txt>" \
  -d '{"conversation_id":"<conversation-uuid>","message":"hello"}'

Do not disable CSRF for scripting and do not commit local cookies or credentials. The browser interface already handles this flow.

Memory and Qdrant

Model loading and caches

Quick Start disables Memory in .env. To enable cross-conversation Memory, set MEMORY_ENABLED=true and restart the application. If the first message keeps waiting, set it to false to verify the chat model connection before preparing Memory model caches.

Memory combines E5 dense, BM25 keyword, and BGE Reranking. Initial Memory construction loads E5 and BM25, downloading them if their caches are missing. BAAI/bge-reranker-v2-m3 is lazily loaded by BGEReranker: its model downloads on the first Memory recall that has candidates to rerank, or during BGE evaluation. Reserve several GB of disk before the first Memory-enabled run; later runs reuse the local cache.

If Memory initialization or retrieval fails, the current Agent Runtime logs the error and continues without recalled Memory. That does not show that model configuration or persistent storage is correct. Check environment variables, network access, model cache, and Qdrant location first.

Local and service-backed Qdrant

The default MEMORY_QDRANT_LOCATION is local ~/.mini-code-agent/qdrant, which suits one process. When Web and CLI need concurrent access, use a shared Qdrant service URL that includes a scheme, for example:

MEMORY_QDRANT_LOCATION=http://127.0.0.1:6333

If a local Qdrant service is subject to a system proxy, bypass it for loopback traffic:

export NO_PROXY=localhost,127.0.0.1

Qdrant retains a Memory's current Source Text; it does not replace Django's durable Conversation Transcript. See the Memory and evaluation guide for Scope, User Memory, and Space Memory behavior.

Safety and limitations

Trusted-local boundary

Version 0.2 automatically creates one local User with an unusable password. Web and CLI share it so ownership of Conversations, Memory Spaces, and User Memory remains stable. The version has no login, API tokens, client-supplied user_id, multi-User isolation, or remote-deployment authentication.

Django currently uses development settings, including DEBUG = True and an empty ALLOWED_HOSTS. That is appropriate for local development, not production deployment. Do not publish the current Web service, JSON API, or SQLite/Qdrant data to the public internet.

Tool and workspace risks

The Agent Runtime binds bash, read_file, write_file, and edit_file to the selected Conversation's workspace. File tools reject paths that resolve outside the workspace, but write_file and edit_file can still change files inside it.

bash uses subprocess.run(..., shell=True). Its current denylist blocks only a few explicit patterns, and potentially destructive commands rely on each entry point's confirmation policy. It is not a complete sandbox. Use it only in local workspaces you trust, and review what it may read, write, or execute.

Contribute and verify

Everyday quality checks

After installation, these commands use the development tools defined by the lockfile:

uv run --locked ruff format --check .
uv run --locked ruff check .
uv run --locked mypy
uv run --locked python src/main/python/manage.py test tests.chat tests.memory

Without test labels, uv run --locked python src/main/python/manage.py test also discovers all tests under src/test/python/tests/.

Install the Git hook and run all hooks manually:

uv run --locked pre-commit install
uv run --locked pre-commit run --all-files

pre-commit runs Ruff (which can fix or format files) and mypy when committing. If a hook changes files, the commit stops; inspect the changes, stage them again, and commit again.

Coverage and CI

Generate a terminal coverage report:

uv run --locked coverage erase
uv run --locked coverage run src/main/python/manage.py test tests.chat tests.memory
uv run --locked coverage report -m

Generate an HTML coverage report:

uv run --locked coverage html

The report is written to htmlcov/index.html. Coverage measures src/main/python/core and src/main/python/chat, excluding migrations; it does not cover the complete CLI, evaluation scripts, or repository. mypy currently checks core. GitHub Actions uses uv sync --locked --dev for dependency sync, then runs Ruff format/check, mypy, coverage-backed tests, and the coverage report with Python 3.13 on pushes, pull requests, and manual dispatches.

Real-model smoke

The default tests skip the smoke test that requires a real E5 model. Enabling it loads the model cache or downloads missing files:

RUN_E5_SMOKE=1 uv run --locked python src/main/python/manage.py test \
  tests.memory.test_embedder_smoke

This checks real E5 embeddings, Qdrant retrieval, and User Scope. It does not call the outer chat model or replace BGE or formal CUDA evaluation.

Troubleshooting and current limits

Check before startup

The first message may wait for Memory model downloads before any chat API request starts; fallback only happens after initialization raises an exception. Existing .env files do not receive new settings automatically: add MEMORY_ENABLED=false and restart Web or CLI to skip this stage. Model API failures distinguish HTTP status codes, connection errors, and timeouts; for example, HTTP 401 points to ANTHROPIC_API_KEY, while HTTP 404 points to MODEL_ID and ANTHROPIC_BASE_URL.

If the CLI or Web app cannot call the model, first check MODEL_ID and ANTHROPIC_API_KEY in .env, then confirm that optional ANTHROPIC_BASE_URL is a complete address for the intended service. Use --help to check the current CLI entry point instead of reusing an old path:

uv run --locked python src/main/python/cli.py --help

If Memory is unavailable, check disk space for BGE, the Qdrant path or service URL, proxy bypass, and model/API credentials. Memory's fallback only means the Agent Runtime may continue; it does not mean Memory is configured correctly.

Current product limits

  • Model responses are not streamed.
  • There is no complete tool-call trace visualization.
  • Memory UPDATE, DELETE, Memory Event integration, and automatic index recovery are incomplete.
  • Workspace-path changes do not automatically migrate or rebind the prior Memory Space.
  • Remote, multi-User, or production use needs real authentication, isolation, and a stronger tool sandbox; the current version does not provide them.