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>/, orschema/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.
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
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
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.
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.
uv run pytest
or python -m http.server smoke output into the PR body. For
MCP changes: tool count + test count. For schema changes: row counts
before/after.plan/EXECUTION-STATUS-PHASE-1-2.md when relevant. Any
PR that closes a roadmap item or unblocks a downstream agent should
tick the corresponding line and add a verification cell.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:
vectorsurv_*, kg_*, mag_*, az211_*, gattc_*,
nws_*, whispers_*, inat_*, adhs_*, sms_*, wearable_*).
The agents/ orchestrator dispatches on the prefix; collisions
silently break Scenario A/C/D end-to-end runs.os.environ.get("<SERVER>_BASE_URL") with a sensible
default. If the upstream has no API today (e.g. ADHS, MAG supply,
211 dispatch, Great AZ Tick Check), ship a mock backend behind the
same env-var contract so swapping is a one-line change.openapi/ and reference it from the
README. PRs that bump the snapshot are the changelog the MCP client
reacts to.canned_data.py or mock_data.py)
and silently fall back on connection errors.mcp/README.md — one row in the index table.schema/deep/mcp_servers.sql —
a mcp_server node + per-tool nodes.plan/02-mcp-integration.md —
if the server unlocks a new agent → MCP route.agents/src/onehealth_agents/mcp_client.py — if any of the eight
agents calls a tool on it.Use schema/deep/pathogens.sql as the
template — it shows the full pattern (nodes → edges → properties →
cross-references → views).
Required conventions:
pathogen.west_nile,
county.maricopa, tribe.tohono_oodham). Renames break every
downstream join; coordinate via PR before renaming.counties.sql 10000-10999,
tribes.sql 11000-11999, pathogens.sql 12000-12999,
outbreaks.sql 13000-13999, standards.sql 14000-14999,
datasets_apis.sql 15000-15999, mcp_servers.sql 16000-16999,
application.sql 17000-17999, followups.sql 30000-30199, etc.).
Pick the next free range and document it in your PR.-- source: <URL or doc path> comments
on rows whose values came from a published agency report. Reviewers
will ask for citations on anything that looks like a magic number.value_text, value_num, or
value_json consistently. Lat/lon, ordinals, counts go in
value_num. URLs, names, slugs go in value_text.README.md and (where applicable)
mcp/knowledge-graph-mcp/ if your seed has FK dependencies on
another seed.import / export. No JSX, no
TypeScript, no transpilation. Files end in .js and run in modern
browsers untouched.BaseModels. Async via httpx.AsyncClient.black defaults + ruff defaults. Run
uv run ruff check . and uv run black --check . before pushing.
Line length defaults (88 / 88). One module per concern.tests/,
named test_<unit>.py. Async tests use the pytest.mark.asyncio
decorator. Network is forbidden in unit tests — use the canned
fallback or respx mocks.Walk this on every PR that touches observation data. If any box fails, the PR is blocked.
tribe.* nodes, ZCTAs intersecting a reservation),
the default behaviour is suppression. Opt-in is per-tribe and
per-data-source, configured in consent_profile rows in the kg.consent_profile is consulted at write time. Validation
Agent (agents/src/onehealth_agents/validation.py) is the single
enforcement point. Bypassing it is a hard reviewer-block.dashboard/ or today/ has been aggregated or suppressed per the
rules in plan/03-agentic-architecture.md.agent_run rows. The audit log captures
input/output digests (SHA-256 of canonicalized JSON), never raw
observations..env.example next to each MCP
server documents what is required; the .env itself is
.gitignored.knowledge-graph-mcp kg_sql tool parses for write keywords and
rejects them; do not weaken that filter.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).