helio-client 0.1.0__tar.gz

helio_client-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+**/node_modules/
+.pnpm-store/
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+dist/
+dist
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# misc local untracked files
+.local/
+docs/.local/
+# local Claude Code state, except the shared project config
+.claude/*
+!/.claude/settings.json
+
+# generated benchmark report (machine-specific)
+docs/benchmark-results.md
+
+# runtime-generated audit databases
+helio-audit.db
+*.db
+*.db-wal
+*.db-shm
+
+# python
+packages/python-sdk/src/helio/_version.py
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.Python
+pip-log.txt
+pip-delete-this-directory.txt
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hatch/
+*.pyo
+*.pyd
+.python-version
+
+
+.gstack/

helio_client-0.1.0/AGENTS.md

@@ -0,0 +1,134 @@
+# helio (Python SDK)
+
+Thin Python client for the Helio MCP governance proxy. Communicates with the proxy's sideband HTTP API to report evidence and context. The SDK NEVER makes governance decisions — that is always the proxy's job.
+
+**Hard constraint: total source must stay under 500 lines** for hand-written SDK modules (`__init__.py`, `types.py`, `client.py`, `context.py`). Governance logic belongs in the proxy, not here.
+
+## Package Layout
+
+```
+src/helio/
+├── __init__.py     → Public API surface (re-exports HelioClient, HelioContext, HelioError, types, __version__)
+├── types.py        → Frozen dataclasses: EvidenceEntry, CompletedTool, SessionState, EvidenceStateReport
+├── client.py       → HelioClient: low-level sync httpx client mapping to sideband API + HelioError
+├── context.py      → HelioContext: high-level wrapper with local requirement tracking (thread-safe)
+├── _version.py     → Auto-generated by hatch-vcs (NOT hand-written; excluded from the 500-line budget)
+└── py.typed        → PEP 561 marker
+
+tests/
+├── __init__.py                 → Marks the tests package
+├── conftest.py                 → Shared fixtures
+├── test_client.py              → HelioClient unit tests (respx for HTTP mocking)
+├── test_context.py             → HelioContext unit tests (respx for HTTP mocking)
+└── test_context_threading.py   → Concurrency tests for require_evidence (the _lock invariant)
+```
+
+## Key Classes
+
+**`HelioClient`** — Low-level HTTP client wrapping the proxy sideband API. Constructor: `HelioClient(proxy_url="http://127.0.0.1:3200", session_id=None, *, timeout=5.0)`.
+- `mark_evidence(tool_name, evidence_key, data, ttl=300)` → `POST /evidence`
+- `set_context(key, value)` → `POST /context`
+- `get_session_state()` → `GET /session/:session_id/state` → returns `SessionState`
+- `close()` + context manager support (`with HelioClient(...) as client:`)
+- `session_id` / `proxy_url` read-only properties
+- Auto-generates session ID (`uuid.uuid4().hex`) when not provided
+- **Reads `HELIO_SDK_TOKEN` from the environment at construction** and, if set, attaches `Authorization: Bearer <token>` to every request. The token is bound for the client's lifetime — rotate by restarting the process (matches the proxy's per-boot token model). An empty/unset value means no `Authorization` header (open-mode local dev).
+- Transport/status failures are normalized into `HelioError` (`ConnectError` → "Cannot connect…", `TimeoutException` → "…timed out", `HTTPStatusError` → "…failed: HTTP <code>" with `status_code`); `POST /evidence` errors additionally surface the proxy's structured `code`/`key`/`allowed_keys` details.
+
+**`HelioError`** — Base exception for all SDK errors; carries an optional `status_code`.
+
+**`HelioContext`** — Primary public API wrapping `HelioClient`. Same constructor signature as `HelioClient`.
+- `mark_evidence(tool_name, evidence_key, data, ttl=300)` — mark tool output as evidence (delegates to the client)
+- `require_evidence(keys)` — declare local requirements (accepts a `str` or `list[str]`; informational only, never raises)
+- `set(key, value)` — set session context
+- `get_evidence_state()` → `EvidenceStateReport` with satisfied/missing comparison
+- `client` property (access the underlying `HelioClient`), `session_id` property, `close()` + context manager support
+- **Thread-safe:** a `threading.Lock` guards `_required_keys`; `get_evidence_state()` snapshots required keys under the lock, then does the network call outside it.
+
+**`EvidenceStateReport`** — Frozen dataclass mirroring `SessionState`'s fields (`session_id`, `evidence`, `context`, `completed_tools`) plus `satisfied` and `missing` lists computed by comparing proxy evidence against locally declared requirements.
+
+## Dependencies & Build
+
+- `httpx>=0.27` — sync HTTP client (the only runtime dependency)
+- `pytest==9.0.2` + `respx==0.22.0` — testing (dev extra: `helio[dev]`)
+- Build backend: `hatchling` + `hatch-vcs` — the version is derived dynamically from git tags (`raw-options.root = "../.."`) and written to `src/helio/_version.py` at build time. There is no static version in `pyproject.toml`.
+- `requires-python = ">=3.10"`
+
+## Commands
+
+```bash
+# From repo root:
+pip install -e ./packages/python-sdk          # Install SDK in editable mode
+pip install -e './packages/python-sdk[dev]'   # With test dependencies
+
+# Run tests (either works):
+cd packages/python-sdk && pytest
+pnpm test:python-sdk                           # from repo root — runs `python3 -m pytest packages/python-sdk/tests`
+
+# Line count check for hand-written modules (must stay under 500 total):
+wc -l src/helio/{__init__,types,client,context}.py
+```
+
+## Security Standards
+
+The SDK communicates with the proxy over localhost HTTP. Even though this is a local-only channel, the SDK handles evidence data that influences governance decisions. Security matters.
+
+### Data Integrity
+
+- **Evidence data is passed through as-is to the proxy.** The SDK does not validate, transform, or cache evidence content. The proxy is the single source of truth for evidence validation and enforcement.
+- **Session IDs are generated securely.** When not provided, the SDK generates a UUID hex string using Python's `uuid.uuid4()`. Never generate session IDs from predictable or user-controllable sources.
+- **The SDK never stores evidence or governance state on disk.** All state is in-memory and tied to the client/context instance lifetime.
+
+### Network Safety
+
+- **The SDK connects only to localhost by default** (`http://127.0.0.1:3200`). The `proxy_url` is operator-configurable but should never point to an untrusted host.
+- **The SDK authenticates with the sideband Bearer token.** It reads `HELIO_SDK_TOKEN` from the environment at construction; the proxy prints this token to stderr on `helio start` when `sdk.enabled` is true. Operators are responsible for passing it to the SDK process. The token is read once and bound for the client's lifetime — rotation means restarting the process.
+- **HTTP errors from the proxy are raised as `HelioError`.** The SDK does not silently swallow connection failures, timeouts, or error responses — callers must handle them.
+- **No retries with backoff.** The SDK is a thin client. Retry logic belongs in the calling application, not here. Adding retry logic would obscure failures and increase complexity beyond the 500-line budget.
+
+### Input Handling
+
+- **All public method parameters are type-annotated.** Type checkers catch misuse at development time.
+- **Frozen dataclasses for all types.** Data returned by the SDK is immutable. Callers cannot accidentally modify evidence state or session data.
+- **JSON serialization uses httpx's built-in encoder.** Never manually construct JSON strings.
+
+### Scope Discipline
+
+- **The SDK must never make governance decisions.** No caching of policy results, no local evaluation of rules, no "smart" behavior that second-guesses the proxy. The SDK reports data; the proxy decides.
+- **The SDK must never grow beyond 500 lines.** If a feature requires more code, it belongs in the proxy, not the SDK. This constraint exists to minimize the attack surface and keep the SDK auditable.
+
+## Testing Standards
+
+- **pytest** with **respx** for mocking httpx requests — no real HTTP calls in unit tests
+- Fixtures in `conftest.py` provide pre-configured mock routes
+- Tests verify both the HTTP call shape (URL, body, method) and the parsed return types
+- E2E test lives in the proxy package: `packages/proxy/src/__tests__/e2e-python-sdk-sideband.test.ts` — Vitest spawns a Python subprocess with `PYTHONPATH` pointing at SDK source
+- **Test error paths:** connection refused, HTTP 4xx/5xx, malformed JSON responses
+- **Test session ID generation:** verify UUIDs are valid and unique across instances
+
+## Code Standards
+
+- Python 3.10+ (`from __future__ import annotations` for forward refs)
+- Frozen dataclasses for all types (`@dataclass(frozen=True)`)
+- Type hints on all public APIs
+- Docstrings on all public classes and methods (Google style)
+- No default exports — explicit `__all__` in `__init__.py`
+- **snake_case everywhere** — in Python types *and* in the JSON sent to / parsed from the proxy. The sideband API speaks snake_case on the wire (`session_id`, `tool_name`, `evidence_key`, `evidence_data`, `ttl_seconds`, `completed_tools`, …), so response objects splat straight into their dataclass constructors with no key-rename layer. Do not reintroduce a camelCase translation step.
+
+## Sideband API Endpoints (proxy side)
+
+The SDK talks to these endpoints on the proxy's sideband server (default port 3200 on `127.0.0.1`; the bind host is configurable via `sdk.host`). When the proxy has a sideband token configured, every request except `GET /healthz` must carry `Authorization: Bearer <HELIO_SDK_TOKEN>`; the sideband also rejects any request with an `Origin` header and blocks `OPTIONS` preflights.
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET`  | `/healthz` | Liveness probe (always unauthenticated) |
+| `POST` | `/evidence` | Report evidence from tool output |
+| `POST` | `/context` | Set arbitrary session context |
+| `GET`  | `/session/:session_id/state` | Fetch combined evidence + context + completed tools |
+
+## Design Constraints
+
+- SDK is a **thin client only** — no caching, no policy evaluation, no decision-making
+- All governance enforcement happens in the proxy; the SDK just reports data
+- Session ID is the correlation key between SDK calls and proxy-side evidence/dependency tracking
+- The `require_evidence()` method is purely local bookkeeping for developer convenience; the proxy enforces evidence requirements via policy rules

helio_client-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: helio-client
+Version: 0.1.0
+Summary: Thin Python SDK for the Helio MCP governance proxy
+Project-URL: Homepage, https://github.com/gethelio/helio
+Project-URL: Repository, https://github.com/gethelio/helio
+Project-URL: Documentation, https://github.com/gethelio/helio/tree/main/docs
+Project-URL: Issues, https://github.com/gethelio/helio/issues
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Requires-Dist: respx==0.22.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Helio Python SDK
+
+Thin Python client for the [Helio MCP governance proxy](https://github.com/gethelio/helio). Communicates with the proxy's sideband HTTP API to report evidence and context. The SDK never makes governance decisions — that is always the proxy's job.
+
+## Install
+
+```bash
+pip install helio-client
+```
+
+> **`helio-client` is only the PyPI distribution name** — the string you `pip install`. This package is the **Helio Python SDK**; the distribution name differs solely because the bare `helio` name on PyPI is held by an unrelated abandoned project. It changes nothing about how you use the SDK — the import path stays `helio` (`from helio import HelioContext`), and these docs refer to it as the Helio Python SDK throughout.
+
+## Quick Start
+
+The proxy prints a per-boot SDK token to stderr on startup (`SDK token (pass as HELIO_SDK_TOKEN env var to your SDK clients): ...`). Export it in the environment where your SDK client runs — the client reads `HELIO_SDK_TOKEN` automatically and attaches it as `Authorization: Bearer <token>` on every sideband call. Without it, requests to the proxy sideband are rejected with `401`.
+
+```bash
+export HELIO_SDK_TOKEN=<token-from-proxy-startup-logs>
+```
+
+```python
+from helio import HelioContext
+
+with HelioContext(proxy_url="http://127.0.0.1:3200") as ctx:
+    # Declare what evidence this session needs
+    ctx.require_evidence("orders.lookup")
+
+    # Mark tool output as evidence under the required key
+    ctx.mark_evidence("get_order", "orders.lookup", {"orderId": 42})
+
+    # Set arbitrary session context
+    ctx.set("agent_id", "support-bot")
+
+    # Check what evidence the proxy has
+    report = ctx.get_evidence_state()
+    print(report.satisfied)  # ['orders.lookup']
+    print(report.missing)    # []
+```
+
+## API
+
+### HelioContext
+
+High-level wrapper with local requirement tracking.
+
+| Method | Description |
+|--------|-------------|
+| `mark_evidence(tool_name, evidence_key, data, ttl=300)` | Report evidence from a tool output |
+| `require_evidence(keys)` | Declare local requirements (informational) |
+| `set(key, value)` | Set arbitrary session context |
+| `get_evidence_state()` | Get evidence state with satisfied/missing comparison |
+
+### HelioClient
+
+Low-level HTTP client mapping to the sideband API.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `mark_evidence(tool_name, evidence_key, data, ttl=300)` | `POST /evidence` | Report evidence |
+| `set_context(key, value)` | `POST /context` | Set session context |
+| `get_session_state()` | `GET /session/:session_id/state` | Fetch combined state |
+
+### HelioError
+
+All SDK methods raise `HelioError` on failure instead of raw HTTP exceptions. The error includes an actionable message and an optional `status_code` attribute.
+
+```python
+from helio import HelioContext, HelioError
+
+try:
+    with HelioContext() as ctx:
+        ctx.mark_evidence("tool", "key", "data")
+except HelioError as e:
+    print(e)              # "POST /evidence failed: HTTP 400"
+    print(e.status_code)  # 400
+```
+
+Caught error types:
+- **Connection errors** — proxy unreachable (`"Cannot connect to proxy at ..."`)
+- **Timeout errors** — proxy did not respond in time (`"Proxy request timed out: ..."`)
+- **HTTP errors** — proxy returned 4xx/5xx (`"POST /evidence failed: HTTP 400"`)
+- **Serialization errors** — request payload is not JSON-serializable for POST calls (for example, `{"v": object()}`), normalized to `HelioError` with endpoint context (`"Failed to serialize POST /evidence payload as JSON: ..."`).
+- **Evidence allowlist errors** — `POST /evidence` may return `code=evidence_key_not_in_policy_allowlist` when `evidence_key` does not match any policy `evidence.requires` key. The SDK includes the rejected key and configured-key preview in `HelioError` for quick diagnosis.
+- **Malformed sideband responses** — invalid JSON or missing fields from `GET /session/:session_id/state` are normalized to `HelioError` (`"... returned malformed response payload"`).
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `proxy_url` | `http://127.0.0.1:3200` | Sideband API base URL |
+| `session_id` | Auto-generated UUID | Correlation key for evidence/context |
+| `timeout` | `5.0` | HTTP request timeout in seconds |
+
+## Constraints
+
+- **Under 500 lines** — governance logic belongs in the proxy, not the SDK
+- **Thin client only** — no caching, no policy evaluation, no decision-making
+- **Python 3.10+** required
+
+## License
+
+Apache 2.0

helio_client-0.1.0/README.md

@@ -0,0 +1,102 @@
+# Helio Python SDK
+
+Thin Python client for the [Helio MCP governance proxy](https://github.com/gethelio/helio). Communicates with the proxy's sideband HTTP API to report evidence and context. The SDK never makes governance decisions — that is always the proxy's job.
+
+## Install
+
+```bash
+pip install helio-client
+```
+
+> **`helio-client` is only the PyPI distribution name** — the string you `pip install`. This package is the **Helio Python SDK**; the distribution name differs solely because the bare `helio` name on PyPI is held by an unrelated abandoned project. It changes nothing about how you use the SDK — the import path stays `helio` (`from helio import HelioContext`), and these docs refer to it as the Helio Python SDK throughout.
+
+## Quick Start
+
+The proxy prints a per-boot SDK token to stderr on startup (`SDK token (pass as HELIO_SDK_TOKEN env var to your SDK clients): ...`). Export it in the environment where your SDK client runs — the client reads `HELIO_SDK_TOKEN` automatically and attaches it as `Authorization: Bearer <token>` on every sideband call. Without it, requests to the proxy sideband are rejected with `401`.
+
+```bash
+export HELIO_SDK_TOKEN=<token-from-proxy-startup-logs>
+```
+
+```python
+from helio import HelioContext
+
+with HelioContext(proxy_url="http://127.0.0.1:3200") as ctx:
+    # Declare what evidence this session needs
+    ctx.require_evidence("orders.lookup")
+
+    # Mark tool output as evidence under the required key
+    ctx.mark_evidence("get_order", "orders.lookup", {"orderId": 42})
+
+    # Set arbitrary session context
+    ctx.set("agent_id", "support-bot")
+
+    # Check what evidence the proxy has
+    report = ctx.get_evidence_state()
+    print(report.satisfied)  # ['orders.lookup']
+    print(report.missing)    # []
+```
+
+## API
+
+### HelioContext
+
+High-level wrapper with local requirement tracking.
+
+| Method | Description |
+|--------|-------------|
+| `mark_evidence(tool_name, evidence_key, data, ttl=300)` | Report evidence from a tool output |
+| `require_evidence(keys)` | Declare local requirements (informational) |
+| `set(key, value)` | Set arbitrary session context |
+| `get_evidence_state()` | Get evidence state with satisfied/missing comparison |
+
+### HelioClient
+
+Low-level HTTP client mapping to the sideband API.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `mark_evidence(tool_name, evidence_key, data, ttl=300)` | `POST /evidence` | Report evidence |
+| `set_context(key, value)` | `POST /context` | Set session context |
+| `get_session_state()` | `GET /session/:session_id/state` | Fetch combined state |
+
+### HelioError
+
+All SDK methods raise `HelioError` on failure instead of raw HTTP exceptions. The error includes an actionable message and an optional `status_code` attribute.
+
+```python
+from helio import HelioContext, HelioError
+
+try:
+    with HelioContext() as ctx:
+        ctx.mark_evidence("tool", "key", "data")
+except HelioError as e:
+    print(e)              # "POST /evidence failed: HTTP 400"
+    print(e.status_code)  # 400
+```
+
+Caught error types:
+- **Connection errors** — proxy unreachable (`"Cannot connect to proxy at ..."`)
+- **Timeout errors** — proxy did not respond in time (`"Proxy request timed out: ..."`)
+- **HTTP errors** — proxy returned 4xx/5xx (`"POST /evidence failed: HTTP 400"`)
+- **Serialization errors** — request payload is not JSON-serializable for POST calls (for example, `{"v": object()}`), normalized to `HelioError` with endpoint context (`"Failed to serialize POST /evidence payload as JSON: ..."`).
+- **Evidence allowlist errors** — `POST /evidence` may return `code=evidence_key_not_in_policy_allowlist` when `evidence_key` does not match any policy `evidence.requires` key. The SDK includes the rejected key and configured-key preview in `HelioError` for quick diagnosis.
+- **Malformed sideband responses** — invalid JSON or missing fields from `GET /session/:session_id/state` are normalized to `HelioError` (`"... returned malformed response payload"`).
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `proxy_url` | `http://127.0.0.1:3200` | Sideband API base URL |
+| `session_id` | Auto-generated UUID | Correlation key for evidence/context |
+| `timeout` | `5.0` | HTTP request timeout in seconds |
+
+## Constraints
+
+- **Under 500 lines** — governance logic belongs in the proxy, not the SDK
+- **Thin client only** — no caching, no policy evaluation, no decision-making
+- **Python 3.10+** required
+
+## License
+
+Apache 2.0

helio_client-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "helio-client"
+dynamic = ["version"]
+description = "Thin Python SDK for the Helio MCP governance proxy"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest==9.0.2",
+  "respx==0.22.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gethelio/helio"
+Repository = "https://github.com/gethelio/helio"
+Documentation = "https://github.com/gethelio/helio/tree/main/docs"
+Issues = "https://github.com/gethelio/helio/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/helio/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/helio"]

helio_client-0.1.0/src/helio/__init__.py

@@ -0,0 +1,22 @@
+"""Helio Python SDK — thin client for the MCP governance proxy."""
+
+from ._version import __version__
+from .client import HelioClient, HelioError
+from .context import HelioContext
+from .types import (
+    CompletedTool,
+    EvidenceEntry,
+    EvidenceStateReport,
+    SessionState,
+)
+
+__all__ = [
+    "__version__",
+    "HelioClient",
+    "HelioContext",
+    "HelioError",
+    "CompletedTool",
+    "EvidenceEntry",
+    "EvidenceStateReport",
+    "SessionState",
+]

helio_client-0.1.0/src/helio/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None