From deb124ed291c890ce8f2b6ee3875e676fbe236f3 Mon Sep 17 00:00:00 2001 From: Jeff Smith Date: Wed, 8 Apr 2026 11:57:15 -0600 Subject: [PATCH] Initial project structure and scaffolding - Directory layout: researchers/web/, orchestrator/, cli/, docs/wiki/ - README with quick start and vision - CONTRIBUTING with workflow and testing guidelines - pyproject.toml with dependencies and build config - .gitignore for Python projects Co-Authored-By: Claude Haiku 4.5 --- .gitignore | 52 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 54 ++++++++++++++++++++++++++++++++ README.md | 50 ++++++++++++++++++++++++++++-- cli/__init__.py | 0 orchestrator/__init__.py | 0 pyproject.toml | 62 +++++++++++++++++++++++++++++++++++++ researchers/__init__.py | 0 researchers/web/__init__.py | 0 8 files changed, 216 insertions(+), 2 deletions(-) create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 cli/__init__.py create mode 100644 orchestrator/__init__.py create mode 100644 pyproject.toml create mode 100644 researchers/__init__.py create mode 100644 researchers/web/__init__.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ef9ebb7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,52 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Virtual environments +venv/ +env/ +ENV/ + +# IDEs +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db + +# Project-specific +~/.marchwarden/ +.env +.env.local +*.log + +# Tests +.pytest_cache/ +.coverage +htmlcov/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a4bedef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing to Marchwarden + +## Workflow + +- **Always branch** — never commit directly to `main` +- **Branch naming**: `feat/`, `fix/`, `refactor/`, `chore/` + description (e.g., `feat/tavily-integration`) +- **One branch, one concern** — don't mix unrelated changes +- **Atomic commits** — each commit is one logical unit; write clear messages +- **Tests required** — all code changes to testable modules must include or update tests +- **Test before PR** — run `pytest tests/` and ensure all pass + +## Branching + +```bash +# Create a feature branch +git checkout -b feat/your-feature-name + +# Commit logically +git commit -m "Implement X because Y" + +# Push +git push origin feat/your-feature-name +``` + +## Testing + +```bash +# Run all tests +pytest tests/ + +# Run with coverage +pytest --cov=. tests/ + +# Run a specific test +pytest tests/test_something.py::test_name +``` + +## MCP Contract + +Before implementing, read [ResearchContract.md](docs/wiki/ResearchContract.md). The `research()` tool signature is the contract; changes require approval. + +## PR process + +1. Push your branch +2. Create a PR on Forgejo +3. Ensure CI passes (tests, linting) +4. Request review +5. Merge via Forgejo API/UI (not locally) +6. Delete the remote branch +7. Sync local `main`: `git checkout main && git pull --ff-only` + +## Questions? + +Check the wiki or open an issue. diff --git a/README.md b/README.md index e79156c..01985c1 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,49 @@ -# marchwarden +# Marchwarden -A network of agentic research specialists coordinated by a principal investigator agent. V1: web-search researcher MCP server + CLI shim. \ No newline at end of file +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/claude-code/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 +``` + +## Documentation + +- **[Architecture](docs/wiki/Architecture.md)** — system design, researcher contract, MCP flow +- **[Development Guide](docs/wiki/DevelopmentGuide.md)** — setup, running tests, debugging +- **[Research Contract](docs/wiki/ResearchContract.md)** — the `research()` tool specification +- **[Contributing](CONTRIBUTING.md)** — branching, commits, PR workflow + +## Status + +- V1 scope: [Issue #1](https://forgejo.labbity.unbiasedgeek.com/claude-code/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) \ No newline at end of file diff --git a/cli/__init__.py b/cli/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/orchestrator/__init__.py b/orchestrator/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..62f9ab4 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,62 @@ +[build-system] +requires = ["setuptools>=45", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "marchwarden" +version = "0.1.0-dev" +description = "Agentic research network: specialists at the frontier, PI orchestrator at the center" +readme = "README.md" +requires-python = ">=3.10" +authors = [ + {name = "archeious"} +] + +dependencies = [ + "anthropic>=0.30.0", + "mcp>=0.1.0", + "pydantic>=2.0", + "tavily-python>=0.3.0", + "httpx>=0.24.0", + "click>=8.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0", + "pytest-cov>=4.0", + "black>=23.0", + "ruff>=0.1.0", + "mypy>=1.0", +] + +[project.scripts] +marchwarden = "cli.main:cli" + +[tool.setuptools.packages.find] +include = ["researchers*", "orchestrator*", "cli*"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] + +[tool.coverage.run] +source = ["researchers", "orchestrator", "cli"] +omit = ["*/tests/*", "*/test_*.py"] + +[tool.black] +line-length = 88 +target-version = ['py310'] + +[tool.ruff] +line-length = 88 +target-version = "py310" +select = ["E", "F", "W", "I001"] + +[tool.mypy] +python_version = "3.10" +warn_return_any = true +warn_unused_configs = true +disallow_untyped_defs = false diff --git a/researchers/__init__.py b/researchers/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/researchers/web/__init__.py b/researchers/web/__init__.py new file mode 100644 index 0000000..e69de29