Contributing

Thanks for wanting to extend the EpiHack Arizona 2026 One Health Sentinel stack. This repository was bootstrapped during the EpiHack Arizona 2026 event hosted by the Ending Pandemics Academy and the University of Arizona Global Health Institute, and is now maintained by a multi-agency review board (see GOVERNANCE.md) for continued community use.

The repo is intentionally small, agent-friendly, and bundler-free. Most of what you need to know lives in the file paths themselves; this guide just calls out the conventions reviewers expect.

Before opening any PR that touches observation data (anything flowing through agents/, mcp/<server>/, or schema/deep/*.sql) walk the Privacy + data-sovereignty checklist at the bottom of this file. PRs that fail the checklist are blocked regardless of code-review status.

Local environment setup

Everything runs on a laptop. There is no Kubernetes, no Docker compose, no build step.

# 1. Python 3.11+ (3.11 is the floor; 3.12 works)
python3.11 --version

# 2. uv (https://docs.astral.sh/uv/) for per-package envs
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. duckdb CLI for the knowledge graph
#    https://duckdb.org/docs/installation/
duckdb --version

Per-package install

Each mcp/<server>/ and the agents/ package are independent uv workspaces with their own pyproject.toml. Install only what you need:

cd mcp/vectorsurv-mcp && uv sync                      # any MCP server
cd agents          && uv sync                     # orchestrator
cd mcp/knowledge-graph-mcp && uv sync             # kg query server

Static site (figures, map, graph, dashboard, today, app)

The site has no JS bundler. Open from the repo root:

cd /path/to/epihack-2026
python -m http.server 8000
# then visit http://localhost:8000/

GitHub Pages serves the same files with Jekyll; the _config.yml preserves the directory layout.

Knowledge-graph bootstrap

duckdb
INSTALL ducklake;  INSTALL postgres;
LOAD    ducklake;  LOAD    postgres;
ATTACH 'ducklake:postgres:dbname=epihack host=localhost user=epihack'
  AS epihack (DATA_PATH 's3://epihack/ducklake/');
USE epihack;
.read schema/knowledge_graph.sql
.read schema/system_designs.sql
.read schema/world_cafe.sql
.read schema/wildlife_vectors.sql
.read schema/heat.sql
.read schema/deep/standards.sql        -- load first
.read schema/deep/pathogens.sql        -- load second
.read schema/deep/counties.sql
.read schema/deep/tribes.sql
.read schema/deep/outbreaks.sql
.read schema/deep/datasets_apis.sql
.read schema/deep/application.sql
.read schema/deep/followups.sql

Load order matters: standards.sql and pathogens.sql must precede the rest of deep/*.sql so SNOMED/ICD-10 cross-references and pathogen FKs find their parents.

Pull-request workflow

Contribution templates

Adding a new MCP server

Use mcp/vectorsurv-mcp/ as the template — it is the most complete reference and follows every convention reviewers expect.

mcp/<your-server>/
├── README.md                  # what / why / tool table / auth / env vars
├── pyproject.toml             # FastMCP + httpx + pydantic v2; uv workspace
├── src/<your_server>/
│   ├── __init__.py
│   ├── __main__.py            # `python -m <your_server>` entry point
│   ├── server.py              # FastMCP() instance + @mcp.tool definitions
│   └── client.py              # httpx wrapper; env-overridable base URL
├── examples/
│   └── claude_desktop_config.json
└── tests/
    └── test_*.py              # uv run pytest

Required conventions:

Adding a knowledge-graph schema seed

Use schema/deep/pathogens.sql as the template — it shows the full pattern (nodes → edges → properties → cross-references → views).

Required conventions:

Coding style

Privacy + data-sovereignty checklist

Walk this on every PR that touches observation data. If any box fails, the PR is blocked.

If you are unsure whether your change crosses any of these lines, ask in the PR description — a reviewer from the standing board will weigh in (see GOVERNANCE.md).