h3-harness-sdk 0.1.1__tar.gz

h3_harness_sdk-0.1.1/.gitignore

@@ -0,0 +1,33 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# Hilo — local cache files (rebuildable)
+.vfs/graph/graph.db
+.vfs/graph/graph.db.wal
+.vfs/graph/.last_warm
+.gitreins/tasks.yaml
+.coverage
+
+# Temp audit / inspection scripts (generated by foreman ticks)
+# Anchored to repo root: an unanchored `_*.py` also matched package
+# __init__.py files, which hatchling's gitignore-based wheel file selection
+# then excluded from built wheels (empty namespace package on install).
+/_*.py
+# GitReins verdict history (local)
+.gitreins/history/
+
+# pytest-benchmark cache (regenerated on every run)
+.benchmarks/
+
+# DuckDB board local cache (rebuildable from Parquet)
+.coding-hermes/board/board.db
+.coding-hermes/board/board.db.wal
+.coding-hermes/board/*.parquet
+
+.coding-hermes/board/*.duckdb

h3_harness_sdk-0.1.1/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md — H3 SDK for Python
+
+Python SDK for building H3-compliant agent harnesses.
+
+## Install
+
+```bash
+pip install h3-harness-sdk
+```
+
+### Install fallback (source / git)
+
+If a release isn't published to PyPI yet (or you want the latest unreleased
+changes), install directly from the repository:
+
+```bash
+# From git
+pip install git+https://github.com/get-h3/sdk-python.git
+
+# Editable source install (development)
+git clone https://github.com/get-h3/sdk-python.git
+cd sdk-python
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from h3_harness import (
+    BaseHarness,
+    Decision,
+    DecisionType,
+    End,
+    TextResponse,
+    create_router,
+)
+from fastapi import FastAPI
+
+
+class MyHarness(BaseHarness):
+    async def on_process(self, req):
+        # Echo conversation history from context (battery: history preserved).
+        history = list(req.context.history)
+        # Streaming: "do not finish" in message -> unfinished text.
+        streaming = "do not finish" in req.message.content
+        finished = not streaming
+        return Decision(
+            decision=DecisionType.TEXT,
+            text=TextResponse(
+                content=f"Echo: {req.message.content}",
+                finished=finished,
+            ),
+            history=history,
+        )
+
+    async def on_result(self, req):
+        return Decision(decision=DecisionType.END, end=End(reason="task_complete"))
+
+
+app = FastAPI()
+app.include_router(create_router(MyHarness()))
+```
+
+## Package Structure
+
+- `protocol.py` — Pydantic models (generated from get-h3/protocol JSON Schema)
+- `harness.py` — BaseHarness ABC + FastAPI router
+- `middleware.py` — Request logging middleware via BaseHTTPMiddleware
+- `testbed.py` — MockHermes for pytest
+
+## Development
+
+- GitReins quality gate mandatory
+- Must pass `h3-test` from get-h3/shim before release
+- To score 43/43 on the battery: echo `context.history` in every Decision,
+  never issue `llm_call` when `context.models` is empty, and return
+  `text.finished=false` for "do not finish" prompts. See README → *Passing the
+  battery (h3-test compliance)*. `src/h3_harness/examples/echo.py` is the
+  battery-ready template.
+
+## Reference
+
+Spec: `get-h3/h3` → `specs/04-SDK-Libraries.md`

h3_harness_sdk-0.1.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to the H3 Python SDK.
+
+## [1.0.0] — 2026-07-19
+
+### Added
+- `protocol.py`: Pydantic models generated from H3 JSON Schema
+- `harness.py`: BaseHarness ABC + FastAPI router
+- `middleware.py`: Request logging middleware
+- `testbed.py`: MockHermes for pytest
+- Echo example harness (examples/echo/)
+- Structured access logging
+- Pydantic defaults for optional fields (max_iterations, session_state)
+- response_model_exclude_none=True for wire-compatible JSON
+- GitReins quality gate
+- Hilo code graph

h3_harness_sdk-0.1.1/CODEOWNERS

@@ -0,0 +1,3 @@
+# H3 SDK Python — Code Owners
+
+* @banesullivan

h3_harness_sdk-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the GitHub organization [get-h3](https://github.com/get-h3). All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

h3_harness_sdk-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing to H3 SDK for Python
+
+Python SDK for building H3-compliant agent harnesses. Implements the harness side of the H3 protocol using Pydantic + FastAPI.
+
+## Development Setup
+
+```bash
+cd sdk-python/
+python -m venv .venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+## Package Structure
+
+```
+sdk-python/
+├── src/h3_harness/
+│   ├── protocol.py    # Pydantic models (generated from protocol repo JSON Schema)
+│   ├── harness.py     # BaseHarness ABC + FastAPI router
+│   ├── middleware.py   # Request logging middleware
+│   └── testbed.py     # MockHermes for pytest
+├── tests/
+│   ├── test_protocol.py
+│   ├── test_harness.py
+│   └── test_testbed.py
+└── examples/
+    ├── echo/          # Echo harness (returns messages back)
+    ├── minimal/       # Bare-minimum example
+    └── langchain/     # LangChain integration demo
+```
+
+## Before Making Changes
+
+### Run Tests
+
+```bash
+python -m pytest tests/ -v
+# 34 tests
+```
+
+### Run Lint + Type Check
+
+```bash
+ruff check src/ tests/
+mypy src/
+```
+
+### Run the Test Battery
+
+```bash
+# Start the echo example in one terminal:
+python examples/echo/main.py
+
+# In another terminal, run the compliance test battery:
+h3-test --endpoint http://localhost:9191
+# 43 compliance tests, exit code 0 = compliant
+```
+
+### Sync Protocol Types
+
+If the upstream protocol changed:
+
+```bash
+python scripts/sync_protocol.py
+```
+
+This regenerates `src/h3_harness/protocol.py` from `get-h3/protocol` schemas. Never hand-edit generated Pydantic models.
+
+## Making Changes
+
+### BaseHarness Interface
+
+- `harness.py` defines the `BaseHarness` ABC with `on_process` and `on_result`
+- Changes to the ABC are MAJOR — they break all existing harnesses
+- New optional hooks should use separate mixins
+
+### FastAPI Router
+
+- `create_router()` builds a FastAPI APIRouter with `/v1/health`, `/v1/process`, `/v1/result`
+- Must follow the H3 protocol exactly — see `get-h3/protocol/h3-protocol.yaml`
+- All endpoints log METHOD /path STATUS DURATION via middleware
+
+### Middleware
+
+- `middleware.py` uses FastAPI's `BaseHTTPMiddleware`
+- Logs structured request info without leaking credentials
+
+### Pydantic Models
+
+- Models use `Optional` types for protocol-optional fields
+- Validation must match JSON Schema constraints from `get-h3/protocol/schemas/v1/`
+- `model_dump(exclude_none=True)` for wire format compatibility
+
+## Quality Gates
+
+### Pre-Commit
+
+```bash
+ruff check src/ tests/      # Lint
+ruff format --check src/ tests/  # Format
+mypy src/                   # Type check
+python -m pytest tests/ -v  # Tests (34)
+```
+
+### CI Pipeline
+
+GitHub Actions runs on every PR:
+1. Lint (ruff)
+2. Type check (mypy)
+3. Tests (pytest, 34 tests)
+4. `h3-test --endpoint http://localhost:9191` (against echo example)
+
+All must pass.
+
+## Release
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+# CI publishes to PyPI automatically
+```
+
+## Review Checklist
+
+- [ ] `pytest tests/ -v` passes (34 tests)
+- [ ] `ruff check` passes
+- [ ] `mypy src/` passes
+- [ ] `h3-test --endpoint http://localhost:9191` passes against echo example
+- [ ] New Pydantic fields use `Optional` where appropriate
+- [ ] Protocol changes regenerated via `sync_protocol.py`
+- [ ] No hand-edits to generated types
+
+## Questions?
+
+See the umbrella project at [get-h3/h3](https://github.com/get-h3/h3) for architecture, specs, and the cross-repo task board.

h3_harness_sdk-0.1.1/GOVERNANCE.md

@@ -0,0 +1,31 @@
+# Governance
+
+This document describes the governance model for the H3 Python SDK project.
+
+## Roles
+
+- **Maintainers**: Responsible for reviewing and merging contributions, managing releases, and enforcing the code of conduct.
+- **Contributors**: Anyone who submits patches, documentation, or bug reports.
+
+## Decision Making
+
+Decisions are made through consensus among maintainers. For significant changes (new features, API changes, breaking changes), a design discussion should precede implementation.
+
+## Pull Request Process
+
+1. Open an issue describing the change before submitting a PR (for non-trivial changes).
+2. All PRs must pass CI (tests + lint).
+3. At least one maintainer must approve before merge.
+4. The PR author is responsible for merging after approval.
+
+## Release Process
+
+Releases follow [Semantic Versioning](https://semver.org/). Maintainers publish releases to PyPI.
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+This project is licensed under the terms in [LICENSE](LICENSE).

h3_harness_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 H3 Contributors
+
+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.

h3_harness_sdk-0.1.1/Makefile

@@ -0,0 +1,39 @@
+.PHONY: install build test lint fmt clean generate
+
+VENV := .venv
+PYTHON := $(VENV)/bin/python
+
+$(VENV):
+	python3 -m venv $(VENV)
+	$(PYTHON) -m pip install --upgrade pip
+	$(PYTHON) -m pip install -e ".[dev]"
+
+install: $(VENV)
+
+build:
+	uv build
+	@echo "build: OK — dist/ now contains the wheel (and sdist)"
+
+test:
+	uv run pytest -x --tb=short -q
+
+test-full:
+	uv run pytest -x -v
+
+lint:
+	uv run ruff check src/ tests/
+
+fmt:
+	uv run ruff format src/ tests/
+
+clean:
+	rm -rf $(VENV) __pycache__ src/h3_harness/__pycache__
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+
+all: install lint build test
+
+generate:
+	uv run python scripts/generate-protocol.py
+	uv run ruff check --fix src/h3_harness/protocol.py
+	uv run ruff format src/h3_harness/protocol.py

h3_harness_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: h3-harness-sdk
+Version: 0.1.1
+Summary: Python SDK for building H3-compliant agent harnesses
+Author: Total Windup Flight Systems
+License: MIT
+License-File: LICENSE
+Keywords: agent,h3,harness,hermes
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: uvicorn[standard]>=0.25.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.26; extra == 'dev'
+Requires-Dist: jsonschema>=4.20; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-benchmark>=5.2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# H3 Harness SDK for Python
+
+Python SDK for building H3-compliant agent harnesses.
+
+## Install
+
+```bash
+pip install h3-harness-sdk
+```
+
+### Install fallback (source / git)
+
+If a release isn't published to PyPI yet (or you want the latest unreleased
+changes), install directly from the repository:
+
+```bash
+# From git
+pip install git+https://github.com/get-h3/sdk-python.git
+
+# Editable source install (development)
+git clone https://github.com/get-h3/sdk-python.git
+cd sdk-python
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from h3_harness import (
+    BaseHarness,
+    Decision,
+    DecisionType,
+    End,
+    TextResponse,
+    create_router,
+)
+from fastapi import FastAPI
+
+
+class MyHarness(BaseHarness):
+    async def on_process(self, req):
+        # Echo conversation history from context (battery: history preserved).
+        history = list(req.context.history)
+        # Streaming: "do not finish" in message -> unfinished text.
+        streaming = "do not finish" in req.message.content
+        finished = not streaming
+        return Decision(
+            decision=DecisionType.TEXT,
+            text=TextResponse(
+                content=f"Echo: {req.message.content}",
+                finished=finished,
+            ),
+            history=history,
+        )
+
+    async def on_result(self, req):
+        return Decision(decision=DecisionType.END, end=End(reason="task_complete"))
+
+
+app = FastAPI()
+app.include_router(create_router(MyHarness()))
+```
+
+## Testbed
+
+```python
+from h3_harness.testbed import MockHermes
+from h3_harness.examples.echo import EchoHarness
+
+mock = MockHermes(EchoHarness())
+decision = await mock.send_message("Hello!")
+assert decision.text.content == "Echo: Hello!"
+```
+
+## Examples
+
+- **[echo.py](src/h3_harness/examples/echo.py)** — Echo harness that mirrors user messages
+- **[minimal.py](src/h3_harness/examples/minimal.py)** — Minimal harness with health endpoint, uvicorn runner
+- **[langchain_agent.py](src/h3_harness/examples/langchain_agent.py)** — LangChain integration: LLM call with text response
+
+## Passing the battery (h3-test compliance)
+
+The gate for any H3 harness is the **test battery** (`test_battery.py` from
+[get-h3/shim](https://github.com/get-h3/shim) — 43 tests across 6 categories).
+Run it against any running harness endpoint:
+
+```bash
+# The shim is not yet published to PyPI — install from source (get-h3/shim)
+pip install git+https://github.com/get-h3/shim
+h3-test --endpoint http://localhost:9191   # exit 0 = compliant
+```
+
+The Quickstart harness above implements all three conventions and is fully
+battery-compliant (**43/43**). If you modify it, keep the conventions intact —
+a naive harness that drops them scores **41/43**. The three conventions the
+battery checks (beyond "return a Decision") are:
+
+1. **Echo `context.history` in every Decision.** The battery sends a session
+   with prior history and asserts it flows back through the response
+   (`test_2_8_process_preserves_history`). Pass it through explicitly:
+   ```python
+   history = list(req.context.history)
+   return Decision(..., history=history)
+   ```
+2. **Never issue `llm_call` when `context.models` is empty.** The battery
+   sends `context.models: []` and FAILS any harness that returns an `llm_call`
+   decision (`test_5_8_no_models_available` — "hallucinated model"). Only
+   return `LLM_CALL` when the request actually lists models.
+3. **Return `text.finished=false` for "do not finish" prompts.** The battery
+   sends *"Just start a thought, do not finish it yet."* and asserts the
+   response has `text.finished == False` (`test_2_4_process_text_finished_false`).
+   Detect streaming/unfinished intent and set `finished` accordingly.
+
+The canonical battery-ready template is **[echo.py](src/h3_harness/examples/echo.py)**
+— it implements all three conventions and scores 43/43. Use it as the starting
+point for your own harness.
+
+## Development
+
+```bash
+make install   # create venv + install deps
+make build     # build wheel (and sdist) into dist/
+make test      # run tests
+make lint      # ruff check
+make fmt       # ruff format
+```
+
+## Reference
+
+- Spec: [get-h3/h3 — specs/04-SDK-Libraries.md](https://github.com/get-h3/h3/blob/main/specs/04-SDK-Libraries.md)
+- Protocol: [get-h3/protocol](https://github.com/get-h3/protocol)
+- API reference: [docs/api/index.md](docs/api/index.md)

h3_harness_sdk-0.1.1/README.md

@@ -0,0 +1,132 @@
+# H3 Harness SDK for Python
+
+Python SDK for building H3-compliant agent harnesses.
+
+## Install
+
+```bash
+pip install h3-harness-sdk
+```
+
+### Install fallback (source / git)
+
+If a release isn't published to PyPI yet (or you want the latest unreleased
+changes), install directly from the repository:
+
+```bash
+# From git
+pip install git+https://github.com/get-h3/sdk-python.git
+
+# Editable source install (development)
+git clone https://github.com/get-h3/sdk-python.git
+cd sdk-python
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from h3_harness import (
+    BaseHarness,
+    Decision,
+    DecisionType,
+    End,
+    TextResponse,
+    create_router,
+)
+from fastapi import FastAPI
+
+
+class MyHarness(BaseHarness):
+    async def on_process(self, req):
+        # Echo conversation history from context (battery: history preserved).
+        history = list(req.context.history)
+        # Streaming: "do not finish" in message -> unfinished text.
+        streaming = "do not finish" in req.message.content
+        finished = not streaming
+        return Decision(
+            decision=DecisionType.TEXT,
+            text=TextResponse(
+                content=f"Echo: {req.message.content}",
+                finished=finished,
+            ),
+            history=history,
+        )
+
+    async def on_result(self, req):
+        return Decision(decision=DecisionType.END, end=End(reason="task_complete"))
+
+
+app = FastAPI()
+app.include_router(create_router(MyHarness()))
+```
+
+## Testbed
+
+```python
+from h3_harness.testbed import MockHermes
+from h3_harness.examples.echo import EchoHarness
+
+mock = MockHermes(EchoHarness())
+decision = await mock.send_message("Hello!")
+assert decision.text.content == "Echo: Hello!"
+```
+
+## Examples
+
+- **[echo.py](src/h3_harness/examples/echo.py)** — Echo harness that mirrors user messages
+- **[minimal.py](src/h3_harness/examples/minimal.py)** — Minimal harness with health endpoint, uvicorn runner
+- **[langchain_agent.py](src/h3_harness/examples/langchain_agent.py)** — LangChain integration: LLM call with text response
+
+## Passing the battery (h3-test compliance)
+
+The gate for any H3 harness is the **test battery** (`test_battery.py` from
+[get-h3/shim](https://github.com/get-h3/shim) — 43 tests across 6 categories).
+Run it against any running harness endpoint:
+
+```bash
+# The shim is not yet published to PyPI — install from source (get-h3/shim)
+pip install git+https://github.com/get-h3/shim
+h3-test --endpoint http://localhost:9191   # exit 0 = compliant
+```
+
+The Quickstart harness above implements all three conventions and is fully
+battery-compliant (**43/43**). If you modify it, keep the conventions intact —
+a naive harness that drops them scores **41/43**. The three conventions the
+battery checks (beyond "return a Decision") are:
+
+1. **Echo `context.history` in every Decision.** The battery sends a session
+   with prior history and asserts it flows back through the response
+   (`test_2_8_process_preserves_history`). Pass it through explicitly:
+   ```python
+   history = list(req.context.history)
+   return Decision(..., history=history)
+   ```
+2. **Never issue `llm_call` when `context.models` is empty.** The battery
+   sends `context.models: []` and FAILS any harness that returns an `llm_call`
+   decision (`test_5_8_no_models_available` — "hallucinated model"). Only
+   return `LLM_CALL` when the request actually lists models.
+3. **Return `text.finished=false` for "do not finish" prompts.** The battery
+   sends *"Just start a thought, do not finish it yet."* and asserts the
+   response has `text.finished == False` (`test_2_4_process_text_finished_false`).
+   Detect streaming/unfinished intent and set `finished` accordingly.
+
+The canonical battery-ready template is **[echo.py](src/h3_harness/examples/echo.py)**
+— it implements all three conventions and scores 43/43. Use it as the starting
+point for your own harness.
+
+## Development
+
+```bash
+make install   # create venv + install deps
+make build     # build wheel (and sdist) into dist/
+make test      # run tests
+make lint      # ruff check
+make fmt       # ruff format
+```
+
+## Reference
+
+- Spec: [get-h3/h3 — specs/04-SDK-Libraries.md](https://github.com/get-h3/h3/blob/main/specs/04-SDK-Libraries.md)
+- Protocol: [get-h3/protocol](https://github.com/get-h3/protocol)
+- API reference: [docs/api/index.md](docs/api/index.md)