Metadata-Version: 2.4
Name: health_agent_infra
Version: 0.1.1
Summary: Governed runtime + skills for a multi-domain personal health agent (recovery, running, sleep, stress, strength, nutrition).
Author: Dom Colligan
License: MIT License
        
        Copyright (c) 2026 Dom
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/dtcolligan/health_agent_infra
Project-URL: Source, https://github.com/dtcolligan/health_agent_infra
Project-URL: Issues, https://github.com/dtcolligan/health_agent_infra/issues
Keywords: health,agents,cli,claude,skills
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: keyring>=24.0
Requires-Dist: garminconnect>=0.2
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Dynamic: license-file

# Health Agent Infra

**A governed local agent runtime for personal health data.**
Claude Code + Garmin today; MCP-portable and multi-source on the roadmap.

A Claude Code agent reads your own health data, emits per-domain proposals
bounded by codified rules, and commits auditable recommendations you review
the next day. Every decision is logged to a local SQLite database on your
machine; nothing leaves your device.

**For** technical users comfortable with a CLI who use Claude Code and want
agent recommendations they can audit, reproduce, and keep local.

- **Local-first.** State lives in a SQLite file under your home directory. No
  cloud, no account, no remote telemetry.
- **Governed, not generative.** Python owns mechanical decisions
  (classification bands, policy rules, transactional commits); markdown
  skills own rationale and uncertainty. Skills never change an action; code
  never writes prose.
- **Auditable by construction.** Pulls, proposals, rule firings, synthesis,
  and final recommendations all land in typed tables. Inspect anytime with
  `hai doctor`, `hai explain`, `hai stats`, or plain SQL.

## Install

```bash
pipx install health-agent-infra                      # or: pip install -e .
hai init --with-auth --with-first-pull               # scaffolds state + config + skills,
                                                     # prompts for Garmin credentials,
                                                     # backfills the last 7 days
hai daily                                            # tomorrow morning: pull → clean → propose → synthesize → commit
hai stats                                            # local funnel: syncs, recent runs, daily streak
```

Prefer the non-interactive path? Run `hai init` on its own, then `hai auth
garmin` separately. `hai init` is idempotent and safe to re-run. Full CLI
surface in
[`reporting/docs/agent_cli_contract.md`](reporting/docs/agent_cli_contract.md).

## Six domains in v1

**recovery · running · sleep · stress · strength · nutrition**

Each domain ships its own schemas, classification bands, policy rules, and a
readiness skill, and is wired into the synthesis X-rule catalogue that
reconciles across domains. Nutrition is macros-only in v1 — see
[`reporting/docs/non_goals.md`](reporting/docs/non_goals.md).

## Local-first runtime at a glance

```
pull / intake  →  projectors  →  accepted_*_state_daily tables
                                        │
                                        ▼
                         hai state snapshot --as-of <date>
                                        │
                                        ▼
                 domain skills emit DomainProposal × 6
                                        │ hai propose
                                        ▼
                              proposal_log
                                        │
                                        ▼
   Phase A X-rules (X1–X7) → runtime applies mutations to drafts
                                        │
                                        ▼
             daily-plan-synthesis skill overlays rationale
                                        │
                                        ▼
         Phase B X-rules (X9) → action_detail adjustments
                                        │
                                        ▼
  ATOMIC COMMIT: daily_plan + x_rule_firings + N recommendations
                                        │
                                        ▼
             hai review schedule / record / summary
```

- **Local state memory** — ``accepted_*_state_daily`` tables hold the
  canonical per-domain day-level state the runtime reasons over.
- **Decision memory** — ``proposal_log``, ``daily_plan``, ``x_rule_firing``,
  and ``recommendation_log`` preserve what the agent proposed, what synthesis
  changed, and what was finally committed.
- **Outcome memory** — ``review_event`` and ``review_outcome`` record how the
  plan went, so the full decision/outcome history stays on-device.

See [`reporting/docs/architecture.md`](reporting/docs/architecture.md) for the
full pipeline and the code-vs-skill boundary.

## Roadmap

- **Runtime portability via MCP.** Expose the agent-safe CLI surface as an
  MCP server so any agentic runtime (Claude Code, Codex, others) can drive
  it. Today the project is Claude Code–native; the CLI contract is already
  annotated agent-safe vs. interactive, which maps cleanly onto MCP tool
  schemas.
- **Multi-source wearables.** Apple Health, Oura, Whoop. The adapter
  protocol (`core/pull/protocol.py`) is already source-agnostic; the
  per-domain evidence contract needs to broaden before additional sources
  land. Community adapters welcome — see
  [`reporting/docs/how_to_add_a_pull_adapter.md`](reporting/docs/how_to_add_a_pull_adapter.md).
- **Skill-narration eval harness.** Currently deferred; see
  `safety/evals/skill_harness_blocker.md`.

## What this is not

- Not a medical device, not hosted, not multi-user, not an ML loop. See
  [`reporting/docs/non_goals.md`](reporting/docs/non_goals.md).
- Not meal-level nutrition in v1 — macros only.
- Not an MCP server yet (see Roadmap).
- Not a skill-narration eval harness yet (see Roadmap).

## Dig deeper

1. **Positioning & role map** — [`reporting/docs/personal_health_agent_positioning.md`](reporting/docs/personal_health_agent_positioning.md)
2. **Query taxonomy** — [`reporting/docs/query_taxonomy.md`](reporting/docs/query_taxonomy.md)
3. **Memory model** — [`reporting/docs/memory_model.md`](reporting/docs/memory_model.md)
4. **Architecture overview** — [`reporting/docs/architecture.md`](reporting/docs/architecture.md)
5. **Explainability surface** — [`reporting/docs/explainability.md`](reporting/docs/explainability.md)
6. **X-rule catalogue** — [`reporting/docs/x_rules.md`](reporting/docs/x_rules.md)
7. **Non-goals (scope discipline)** — [`reporting/docs/non_goals.md`](reporting/docs/non_goals.md)
8. **State schema** — [`reporting/docs/state_model_v1.md`](reporting/docs/state_model_v1.md)
9. **10-minute reading tour** — [`reporting/docs/tour.md`](reporting/docs/tour.md)
10. **Extension path — pull adapter** — [`reporting/docs/how_to_add_a_pull_adapter.md`](reporting/docs/how_to_add_a_pull_adapter.md)
11. **Extension path — new domain** — [`reporting/docs/how_to_add_a_domain.md`](reporting/docs/how_to_add_a_domain.md)
12. **Eval capture** — [`reporting/artifacts/flagship_loop_proof/2026-04-18-multi-domain-evals/`](reporting/artifacts/flagship_loop_proof/2026-04-18-multi-domain-evals/)

## CLI surface

```
# Evidence + intake
hai pull [--live] --date <d>                   # Garmin CSV / live pull
hai clean --evidence-json <p>                  # raw → CleanedEvidence + RawSummary
hai intake gym|exercise|nutrition|stress|note|readiness ...

# State
hai state init | migrate | read | snapshot | reproject

# Per-domain debug
hai classify --domain <d> --evidence-json <p>
hai policy   --domain <d> --evidence-json <p>

# Agent flow (use `hai daily` for the whole loop)
hai daily                                       # morning orchestrator
hai propose  --domain <d> --proposal-json <p>
hai synthesize --as-of <d> --user-id <u>

# Persistence + review
hai writeback --recommendation-json <p>         # recovery-only legacy direct path
hai review schedule | record | summary [--domain <d>]

# Auth + config + helpers
hai auth garmin | status
hai config init | show
hai doctor                                      # freshness + health checks
hai stats                                       # local funnel (sync + command history, daily streak)
hai exercise search --query <free-text>

# Evals
hai eval run --domain <d> | --synthesis [--json]
```

## Repo layout

For a one-page orientation of every top-level entry (active vs historical vs
generated) see [`REPO_MAP.md`](REPO_MAP.md). The package itself:

```
src/health_agent_infra/
├── cli.py                          # hai dispatcher
├── core/
│   ├── schemas.py  validate.py  config.py
│   ├── synthesis.py  synthesis_policy.py
│   ├── writeback/  state/  clean/  pull/  review/
│   ├── memory/  explain/  research/
│   └── intake/
├── domains/
│   ├── recovery/  running/  sleep/  stress/  strength/  nutrition/
│   └── each: schemas.py classify.py policy.py [+ signals/intake]
├── skills/
│   ├── recovery-readiness/  running-readiness/  sleep-quality/
│   ├── stress-regulation/  strength-readiness/  nutrition-alignment/
│   ├── daily-plan-synthesis/  intent-router/  expert-explainer/
│   └── strength-intake/  merge-human-inputs/  writeback-protocol/
│       reporting/  safety/
├── evals/                          # packaged eval runner + scenarios
└── data/garmin/export/              # committed CSV fixture
reporting/                          # see reporting/README.md
├── docs/                            # architecture, x_rules, non_goals, ...
├── artifacts/flagship_loop_proof/   # eval runner captures
├── plans/                           # post-v0.1 roadmap + historical phase docs
└── experiments/                     # frozen Phase 0.5 / 2.5 prototypes
safety/                             # see safety/README.md
├── tests/                           # 1200+ unit + contract + integration
├── evals/                           # eval-doc reference + skill-harness pilot
└── scripts/                         # legacy pre-rebuild demo shim
```

## What's proven in v1

- Six domains end-to-end: classify → policy → skill proposal → synthesis →
  writeback → review.
- Ten X-rule evaluators across two phases with atomic transactional commits.
- Garmin live pull via OS keyring (`hai auth garmin` + `hai pull --live`).
- Idempotent synthesis with optional `--supersede` versioning.
- 28 eval scenarios (18 domain + 10 synthesis); skill-narration axis
  explicitly deferred (see `safety/evals/skill_harness_blocker.md`).
- 1200+ tests covering every band, every R-rule, every X-rule, atomic
  transaction semantics, writeback invariants, and skill-boundary contracts.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md).
