A network of agentic research specialists coordinated by a principal investigator agent. V1: web-search researcher MCP server + CLI shim.
0d957336f5
Adds an append-only JSONL ledger of every research() call at ~/.marchwarden/costs.jsonl, supplementing (not replacing) the per-call cost_metadata field returned to callers. The ledger is the operator-facing source of truth for spend tracking, queryable via the upcoming `marchwarden costs` command (M2.5.3). Fields per entry: timestamp, trace_id, question (truncated 200ch), model_id, tokens_used, tokens_input, tokens_output, iterations_run, wall_time_sec, tavily_searches, estimated_cost_usd, budget_exhausted, confidence. Cost estimation reads ~/.marchwarden/prices.toml, which is auto-created with seed values for current Anthropic + Tavily rates on first run. Operators are expected to update prices.toml manually when upstream rates change — there is no automatic fetching. Existing files are never overwritten. Unknown models log a WARN and record estimated_cost_usd: null instead of crashing. Each ledger write also emits a structured `cost_recorded` log line via the M2.5.1 logger, so cost data ships to OpenSearch alongside the ledger file with no extra plumbing. Tracking changes in agent.py: - Track tokens_input / tokens_output split (not just total) - Count tavily_searches across iterations - _synthesize now returns (result, synth_in, synth_out) so the caller can attribute synthesis tokens to the running counters - Ledger.record() called after research_completed log; failures are caught and warn-logged so a ledger write can never poison a successful research call Tests cover: price table seeding, no-overwrite of existing files, cost estimation for known/unknown models, tavily-only cost, ledger appends, question truncation, env var override. End-to-end verified with a real Anthropic+Tavily call: 9107 input + 1140 output tokens, 1 tavily search, $0.049 estimated. 104/104 tests passing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| cli | ||
| obs | ||
| orchestrator | ||
| researchers | ||
| scripts | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| pyproject.toml | ||
| README.md | ||
Marchwarden
A network of agentic research specialists coordinated by a principal investigator agent.
Marchwarden researchers are stationed at the frontier of knowledge — they watch, search, synthesize, and report back what they find. Each specialist is self-contained, fault-tolerant, and exposed via MCP. The PI agent orchestrates them to answer complex, multi-domain questions.
V1: Single web-search researcher + CLI shim for development.
V2+: Multiple specialists (arxiv, database, internal docs, etc.) + PI orchestrator.
Quick start
# Clone
git clone https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden.git
cd marchwarden
# Install
pip install -e .
# Ask a question
marchwarden ask "What are ideal crops for a garden in Utah?"
# Replay a research session
marchwarden replay <trace_id>
Docker test environment
A reproducible container is available for running the test suite and the CLI without depending on the host's Python install:
scripts/docker-test.sh build # build the image
scripts/docker-test.sh test # run pytest
scripts/docker-test.sh ask "question" # run `marchwarden ask` end-to-end
# (mounts ~/secrets ro and ~/.marchwarden rw)
scripts/docker-test.sh replay <id> # replay a trace from ~/.marchwarden/traces
scripts/docker-test.sh shell # interactive bash in the container
Documentation
- Architecture — system design, researcher contract, MCP flow
- Development Guide — setup, running tests, debugging
- Research Contract — the
research()tool specification - Contributing — branching, commits, PR workflow
Status
- V1 scope: Issue #1
- Branch:
main(development) - Tests:
pytest tests/
Stack
- Language: Python 3.10+
- Agent framework: Anthropic Claude Agent SDK
- MCP server: Model Context Protocol
- Web search: Tavily API
License
(TBD)