40d0725497
Reproducible Python 3.12-slim container that installs the project editable with dev deps. Adds pytest-asyncio to dev deps so async tests run cleanly inside the container (host had it installed out-of-band). scripts/docker-test.sh provides build, test, ask, replay, and shell subcommands. The ask/replay/shell commands mount ~/secrets read-only and ~/.marchwarden read-write so end-to-end runs persist traces back to the host. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
63 lines
No EOL
2.4 KiB
Markdown
63 lines
No EOL
2.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/wiki/Architecture)** — system design, researcher contract, MCP flow
|
|
- **[Development Guide](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/wiki/DevelopmentGuide)** — setup, running tests, debugging
|
|
- **[Research Contract](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/wiki/ResearchContract)** — the `research()` tool specification
|
|
- **[Contributing](CONTRIBUTING.md)** — branching, commits, PR workflow
|
|
|
|
## Status
|
|
|
|
- V1 scope: [Issue #1](https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden/issues/1)
|
|
- Branch: `main` (development)
|
|
- Tests: `pytest tests/`
|
|
|
|
## Stack
|
|
|
|
- **Language**: Python 3.10+
|
|
- **Agent framework**: [Anthropic Claude Agent SDK](https://github.com/anthropics/anthropic-sdk-python)
|
|
- **MCP server**: [Model Context Protocol](https://modelcontextprotocol.io)
|
|
- **Web search**: Tavily API
|
|
|
|
## License
|
|
|
|
(TBD) |