9ecc1db38d
Targets: make install create .venv and pip install -e ".[dev]" make test pytest inside the venv make test-cov pytest with coverage make lint ruff + black --check make ask run a sample research call make costs show the cost ledger make clean remove venv and caches make docker-build / docker-test parity wrappers for the docker flow Lets contributors get from clone to running CLI in one command without depending on docker. README points at make install as the recommended path; manual venv steps documented as fallback. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
65 lines
No EOL
2.5 KiB
Markdown
65 lines
No EOL
2.5 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 (Makefile shortcut — creates .venv and installs deps)
|
|
make install
|
|
# or manually:
|
|
python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
|
|
|
|
# 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) |