PyHall

The Union Hall Metaphor

Install

pip install pyhall-wcp==0.3.0

Quick Start

import uuid
from pyhall import make_decision, RouteInput, Registry, load_rules
# Load routing rules and enrolled workers
rules = load_rules("rules.json")
registry = Registry(registry_dir="enrolled/")
# Build a capability request
inp = RouteInput(
 capability_id="cap.doc.summarize",
 env="dev",
 data_label="INTERNAL",
 tenant_risk="low",
 qos_class="P2",
 tenant_id="acme-corp",
 correlation_id=str(uuid.uuid4()),
)
# Ask the Hall
decision = make_decision(
 inp=inp,
 rules=rules,
 registry_controls_present=registry.controls_present(),
 registry_worker_available=registry.worker_available,
)
if decision.denied:
 print(f"Denied: {decision.deny_reason_if_denied}")
else:
 print(f"Dispatch to: {decision.selected_worker_species_id}")
 # -> "wrk.doc.summarizer"

What PyHall Gives You

WCP Compliance Levels

CLI

# Route a capability request
pyhall route --capability cap.doc.summarize --env dev --rules rules.json
# Validate all test fixtures against routing rules
pyhall validate rules.json tests.json
# Show registry status
pyhall status --registry-dir enrolled/
# Enroll a worker
pyhall enroll my_worker/registry_record.json --registry-dir enrolled/
# Scaffold a new worker package
pyhall scaffold my_worker/
# Version
pyhall version

Package Attestation (v0.3.0)

Worker Package Layout

worker-package/
 code/
 worker_logic.py — business logic
 bootstrap.py — entrypoint (calls worker_logic.run())
 requirements.lock — pinned dependencies
 config.schema.json — JSON Schema for worker config
 manifest.json — signed manifest (written by build_manifest/write_manifest)

Scaffold a Package

from pathlib import Path
from pyhall import scaffold_package
scaffold_package(
 package_root=Path("my-worker/"),
 worker_logic_file=Path("src/my_logic.py"), # optional — stub written if omitted
)

Sign and Build a Manifest

import os
from pathlib import Path
from pyhall import build_manifest, write_manifest
manifest = build_manifest(
 package_root=Path("my-worker/"),
 worker_id="org.example.my-worker.instance-1",
 worker_species_id="wrk.example.my-worker",
 worker_version="1.0.0",
 signing_secret=os.environ["WCP_ATTEST_HMAC_KEY"],
 build_source="ci", # 'local' | 'ci' | 'agent'
)
write_manifest(manifest, Path("my-worker/manifest.json"))

Verify at Runtime

from pathlib import Path
from pyhall import PackageAttestationVerifier
verifier = PackageAttestationVerifier(
 package_root=Path("/opt/workers/my-worker"),
 manifest_path=Path("/opt/workers/my-worker/manifest.json"),
 worker_id="org.example.my-worker.instance-1",
 worker_species_id="wrk.example.my-worker",
 # secret_env defaults to "WCP_ATTEST_HMAC_KEY"
)
ok, deny_code, meta = verifier.verify()
if not ok:
 raise SystemExit(f"Attestation denied: {deny_code}")
# meta["package_hash"] — embed in evidence receipts
# meta["trust_statement"] — canonical namespace-key trust claim
# meta["verified_at_utc"] — UTC ISO 8601

Compute the Package Hash Directly

from pathlib import Path
from pyhall import canonical_package_hash
h = canonical_package_hash(Path("my-worker/"))
print(h) # 64-char lowercase hex SHA-256

Attestation Deny Codes

from pyhall import (
 ATTEST_MANIFEST_MISSING,
 ATTEST_MANIFEST_ID_MISMATCH,
 ATTEST_HASH_MISMATCH,
 ATTEST_SIGNATURE_MISSING,
 ATTEST_SIG_INVALID,
)

Signing Model

Registry Client

from pyhall import RegistryClient, RegistryRateLimitError
client = RegistryClient()
# Verify a worker's attestation status
r = client.verify("org.example.my-worker.instance-1")
print(r.status) # 'active' | 'revoked' | 'banned' | 'unknown'
print(r.current_hash) # 64-char hex or None
print(r.banned) # bool
print(r.ai_generated) # bool — was this package AI-assisted?
# Submit a full-package attestation (requires bearer token)
resp = client.submit_attestation(
 worker_id="org.example.my-worker.instance-1",
 package_hash=h,
 label="v1.0.0 release",
 ai_generated=True,
 ai_service="claude",
 ai_model="claude-sonnet-4-6",
 ai_session_id="session-fingerprint",
 bearer_token="your-jwt-token",
)
print(resp.id) # attestation record ID
print(resp.sha256) # confirmed hash
# Check the ban-list
banned = client.is_hash_banned(h)
# Report a bad hash (requires session token)
client.report_hash(h, reason="Backdoored dependency", evidence_url="https://...")
# Pre-populate cache before make_decision()
client.prefetch(["org.example.worker-a", "org.example.worker-b"])
callback = client.get_worker_hash # use as registry_get_worker_hash in make_decision()

The Five-Worker Pipeline

cap.web.fetch -> cap.doc.chunk -> cap.ml.embed -> cap.doc.hash -> cap.research.register
 web_fetcher (blast: 1, reversible) — fetch URL, extract text
 doc_chunker (blast: 0, reversible) — semantic chunking ~500 tokens
 embedder (blast: 1, reversible) — embed with nomic-embed-text
 doc_hasher (blast: 0, deterministic) — SHA-256 + optional signing
 research_registrar (blast: 2, reversible) — register to knowledge store
Total chain blast: 4 (within WCP-Standard threshold for dev/INTERNAL)
correlation_id: propagated through all 5 workers and all telemetry events

Architecture

Agent (Claude, GPT, local LLM)
 |
 | capability request (RouteInput)
 v
 +------------------+
 | PyHall / Hall |
 | |
 | 1. Rule match | <- routing_rules.json
 | 2. Controls | <- Registry.controls_present()
 | 3. Blast radius | <- computed or pre-scored
 | 4. Policy gate | <- PolicyGate.evaluate()
 | 5. Worker select| <- Registry.worker_available()
 | 6. Telemetry | <- 3 mandatory events
 +------------------+
 |
 | RouteDecision (evidence receipt)
 v
 selected_worker_species_id
 telemetry_envelopes
 required_controls_effective

Project Layout

pyhall/
 __init__.py — public API
 router.py — make_decision() — the core routing engine
 models.py — RouteInput, RouteDecision (Pydantic v2)
 rules.py — Rule, load_rules, route_first_match
 registry.py — Registry class, worker enrollment
 policy_gate.py — PolicyGate stub (replace with your engine)
 telemetry.py — mandatory telemetry event builders
 conformance.py — conformance validation for CI
 common.py — shared utilities (timestamps, response envelopes)
 attestation.py — PackageAttestationVerifier, build_manifest, write_manifest,
 scaffold_package, canonical_package_hash, ATTEST_* deny codes
 registry_client.py — RegistryClient (HTTP client for api.pyhall.dev)
workers/examples/
 README.md — examples moved to github.com/pyhall/pyhall-examples
tests/
 test_router.py — WCP compliance test suite
WCP spec — see https://github.com/workerclassprotocol/wcp

License

Contributing