chp-core 0.1.0__py3-none-any.whl

chp_core/__init__.py

@@ -0,0 +1,98 @@
+"""CHP v0.1 reference local host."""
+
+from .adapters import (
+    CHP_ADAPTER_GROUP,
+    BaseAdapter,
+    CapabilityAdapter,
+    HostedCapability,
+    SimpleAdapter,
+    auto_register_adapters,
+    discover_adapters,
+    register_adapter,
+    register_capability_once,
+    register_hosted_capabilities,
+)
+from .capabilities import (
+    register_builtin_capabilities,
+    register_evaluate_counterfactual,
+    register_explain_execution,
+    register_trace_execution,
+)
+from .host import CapabilityExecutionContext, LocalCapabilityHost
+from .http import CapabilityHostHTTPServer, create_http_server, serve_http
+from .store import SQLiteEvidenceStore
+from .decorators import capability
+from .codex import (
+    CODEX_CAPABILITY_IDS,
+    record_codex_action,
+    register_codex_observation_capabilities,
+)
+from .otel import evidence_to_otel_span, replay_to_otel_spans
+from .redaction import DEFAULT_SENSITIVE_KEYS, redact_payload
+from .types import (
+    AssuranceMetadata,
+    CapabilityCategory,
+    CapabilityDescriptor,
+    CapabilityIdempotency,
+    CapabilityStatus,
+    CorrelationContext,
+    DenialReason,
+    ExecutionEvidence,
+    ExecutionOutcome,
+    HostDescriptor,
+    HostRequirements,
+    InvariantDescriptor,
+    InvocationEnvelope,
+    InvocationResult,
+    PolicyDescriptor,
+    ReplayQuery,
+    ReplayResult,
+)
+
+__all__ = [
+    "AssuranceMetadata",
+    "BaseAdapter",
+    "CHP_ADAPTER_GROUP",
+    "CODEX_CAPABILITY_IDS",
+    "CapabilityAdapter",
+    "CapabilityCategory",
+    "CapabilityIdempotency",
+    "CapabilityStatus",
+    "CapabilityDescriptor",
+    "CapabilityHostHTTPServer",
+    "CapabilityExecutionContext",
+    "capability",
+    "CorrelationContext",
+    "DEFAULT_SENSITIVE_KEYS",
+    "DenialReason",
+    "ExecutionEvidence",
+    "ExecutionOutcome",
+    "HostedCapability",
+    "HostDescriptor",
+    "HostRequirements",
+    "InvariantDescriptor",
+    "InvocationEnvelope",
+    "InvocationResult",
+    "LocalCapabilityHost",
+    "PolicyDescriptor",
+    "ReplayQuery",
+    "ReplayResult",
+    "SQLiteEvidenceStore",
+    "create_http_server",
+    "evidence_to_otel_span",
+    "redact_payload",
+    "SimpleAdapter",
+    "auto_register_adapters",
+    "discover_adapters",
+    "register_adapter",
+    "register_builtin_capabilities",
+    "register_capability_once",
+    "record_codex_action",
+    "register_codex_observation_capabilities",
+    "register_evaluate_counterfactual",
+    "register_explain_execution",
+    "register_hosted_capabilities",
+    "register_trace_execution",
+    "replay_to_otel_spans",
+    "serve_http",
+]

chp_core/adapters.py

@@ -0,0 +1,252 @@
+"""Adapter primitives for grouping and registering CHP capabilities."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .decorators import adapt_callable, get_capability_descriptor
+from .host import CapabilityHandler, LocalCapabilityHost
+from .types import CapabilityDescriptor
+
+
+@dataclass(slots=True)
+class HostedCapability:
+    """A capability descriptor and handler supplied by an adapter."""
+
+    descriptor: CapabilityDescriptor
+    handler: CapabilityHandler
+    enabled: bool = True
+
+
+class CapabilityAdapter(Protocol):
+    """Structural protocol for CHP capability adapters.
+
+    Any object with ``adapter_id`` and ``capabilities()`` satisfies this
+    protocol and can be passed to ``register_adapter``.
+    """
+
+    adapter_id: str
+
+    def capabilities(self) -> Iterable[HostedCapability]:
+        """Return hosted capabilities declared by this adapter."""
+
+
+class BaseAdapter:
+    """Base class for CHP capability adapters.
+
+    Subclass this, declare ``adapter_id``, and decorate methods with
+    ``@capability`` from ``chp_core``. All decorated methods are discovered
+    automatically by ``capabilities()``.
+
+    Class attributes for adapter metadata::
+
+        adapter_id          # required — stable identity string
+        adapter_name        # human-readable name (defaults to adapter_id)
+        adapter_description # optional description
+        adapter_version     # semver string, default "1.0.0"
+        adapter_tags        # list of string tags for discovery
+
+    Override ``on_register(host)`` for any setup that requires the host
+    (e.g. registering secondary capabilities, emitting startup evidence).
+
+    Example::
+
+        from chp_core import capability, BaseAdapter, LocalCapabilityHost, register_adapter
+
+        class MathAdapter(BaseAdapter):
+            adapter_id = "math"
+            adapter_name = "Math Capabilities"
+
+            @capability(id="math.add", version="1.0.0", description="Add two numbers.")
+            async def add(self, ctx, payload):
+                return {"sum": payload["a"] + payload["b"]}
+
+            @capability(id="math.mul", version="1.0.0", description="Multiply two numbers.")
+            async def multiply(self, ctx, payload):
+                return {"product": payload["a"] * payload["b"]}
+
+        host = LocalCapabilityHost()
+        register_adapter(host, MathAdapter())
+    """
+
+    adapter_id: str
+    adapter_name: str | None = None
+    adapter_description: str | None = None
+    adapter_version: str = "1.0.0"
+    adapter_tags: list[str] = []
+    adapter_category: str | None = None
+
+    def capabilities(self) -> Iterable[HostedCapability]:
+        """Yield capabilities from all ``@capability``-decorated methods."""
+        for _, method in inspect.getmembers(self, predicate=inspect.ismethod):
+            descriptor = get_capability_descriptor(method.__func__)
+            if descriptor is not None:
+                yield HostedCapability(descriptor=descriptor, handler=adapt_callable(method))
+
+    def on_register(self, host: LocalCapabilityHost) -> None:
+        """Called after all capabilities from this adapter are registered."""
+
+    def metadata(self) -> dict[str, Any]:
+        """Return adapter identity metadata."""
+        return {
+            "adapter_id": self.adapter_id,
+            "adapter_name": self.adapter_name or self.adapter_id,
+            "adapter_description": self.adapter_description,
+            "adapter_version": self.adapter_version,
+            "adapter_tags": list(self.adapter_tags),
+            "adapter_category": self.adapter_category,
+        }
+
+
+class SimpleAdapter(BaseAdapter):
+    """Adapter wrapping a list of ``@capability``-decorated functions.
+
+    Use when you have standalone functions and don't need a class::
+
+        from chp_core import capability, SimpleAdapter, LocalCapabilityHost, register_adapter
+
+        @capability(id="math.add", version="1.0.0", description="Add two numbers.")
+        def add(a: int, b: int):
+            return {"sum": a + b}
+
+        host = LocalCapabilityHost()
+        register_adapter(host, SimpleAdapter("math", [add]))
+    """
+
+    def __init__(
+        self,
+        adapter_id: str,
+        functions: Sequence[Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        version: str = "1.0.0",
+        tags: list[str] | None = None,
+    ) -> None:
+        self.adapter_id = adapter_id
+        self.adapter_name = name
+        self.adapter_description = description
+        self.adapter_version = version
+        self.adapter_tags = tags or []
+        self._functions = list(functions)
+
+    def capabilities(self) -> Iterable[HostedCapability]:
+        for fn in self._functions:
+            descriptor = get_capability_descriptor(fn)
+            if descriptor is not None:
+                yield HostedCapability(descriptor=descriptor, handler=adapt_callable(fn))
+
+
+def register_adapter(
+    host: LocalCapabilityHost,
+    adapter: CapabilityAdapter,
+) -> list[CapabilityDescriptor]:
+    """Register all capabilities from *adapter* with *host*, skipping duplicates.
+
+    Calls ``adapter.on_register(host)`` after registration if the method exists.
+    """
+    registered = register_hosted_capabilities(host, list(adapter.capabilities()))
+    on_register = getattr(adapter, "on_register", None)
+    if callable(on_register):
+        on_register(host)
+    return registered
+
+
+CHP_ADAPTER_GROUP = "chp.adapters"
+"""Entry-point group name for installed CHP adapter packages.
+
+Third-party adapter packages declare their adapter class under this group in
+``pyproject.toml``::
+
+    [project.entry-points."chp.adapters"]
+    linear = "chp_linear:LinearAdapter"
+
+The adapter class must satisfy the ``CapabilityAdapter`` protocol (i.e. expose
+``adapter_id`` and ``capabilities()``). Using ``BaseAdapter`` as the base class
+is the recommended pattern.
+"""
+
+
+def discover_adapters(group: str = CHP_ADAPTER_GROUP) -> dict[str, type]:
+    """Return installed adapter classes keyed by entry-point name.
+
+    Loads all entry points under *group* (default ``chp.adapters``) from the
+    current Python environment. Returns an empty dict if none are installed.
+
+    Example::
+
+        adapters = discover_adapters()
+        # {"linear": <class 'chp_linear.LinearAdapter'>, ...}
+    """
+    from importlib.metadata import entry_points
+
+    return {ep.name: ep.load() for ep in entry_points(group=group)}
+
+
+def auto_register_adapters(
+    host: LocalCapabilityHost,
+    group: str = CHP_ADAPTER_GROUP,
+) -> list[CapabilityDescriptor]:
+    """Instantiate and register all installed adapters in *group* with *host*.
+
+    Each adapter class is instantiated with no arguments, so adapters that
+    require configuration (API keys, etc.) must be registered manually via
+    ``register_adapter`` instead.
+
+    Registration failures per adapter are isolated — one broken adapter will
+    not prevent others from loading. Errors are surfaced as warnings.
+
+    Example::
+
+        host = LocalCapabilityHost()
+        auto_register_adapters(host)
+        # all pip-installed chp.adapters are now registered
+    """
+    import warnings
+
+    registered: list[CapabilityDescriptor] = []
+    for name, adapter_cls in discover_adapters(group).items():
+        try:
+            registered.extend(register_adapter(host, adapter_cls()))
+        except Exception as exc:
+            warnings.warn(
+                f"chp: failed to auto-register adapter {name!r}: {exc}",
+                stacklevel=2,
+            )
+    return registered
+
+
+def register_hosted_capabilities(
+    host: LocalCapabilityHost,
+    capabilities: Sequence[HostedCapability],
+) -> list[CapabilityDescriptor]:
+    registered: list[CapabilityDescriptor] = []
+    for capability in capabilities:
+        descriptor = register_capability_once(
+            host,
+            capability.descriptor,
+            capability.handler,
+            enabled=capability.enabled,
+        )
+        if descriptor is not None:
+            registered.append(descriptor)
+    return registered
+
+
+def register_capability_once(
+    host: LocalCapabilityHost,
+    descriptor: CapabilityDescriptor,
+    handler: CapabilityHandler,
+    *,
+    enabled: bool = True,
+) -> CapabilityDescriptor | None:
+    capability_ids = {
+        capability["id"]
+        for capability in host.discover().get("capabilities", [])
+    }
+    if descriptor.id in capability_ids:
+        return None
+    return host.register(descriptor, handler, enabled=enabled)

chp_core/capabilities.py

@@ -0,0 +1,229 @@
+"""Reference capabilities shipped with the local CHP host."""
+
+from __future__ import annotations
+
+from .host import (
+    CapabilityExecutionContext,
+    LocalCapabilityHost,
+    evaluate_invariant_against_event,
+)
+from .types import CapabilityDescriptor, InvariantDescriptor, JSON, utc_now
+
+
+def trace_execution_descriptor() -> CapabilityDescriptor:
+    return CapabilityDescriptor(
+        id="trace_execution",
+        version="0.1.0",
+        description="Capture and correlate execution events from agents, tools, or systems.",
+        input_schema={
+            "type": "object",
+            "required": ["source_id", "event_type"],
+            "properties": {
+                "source_id": {"type": "string"},
+                "event_type": {"type": "string"},
+                "timestamp": {"type": "string", "format": "date-time"},
+                "correlation_hints": {"type": "object"},
+                "summary": {"type": "string"},
+            },
+        },
+        output_schema={"type": "object"},
+        tags=["observability", "trace"],
+        emits=["execution_started", "execution_observed", "execution_completed", "execution_failed"],
+    )
+
+
+def explain_execution_descriptor() -> CapabilityDescriptor:
+    return CapabilityDescriptor(
+        id="explain_execution",
+        version="0.1.0",
+        description="Produce an evidence-backed explanation of a trace.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "correlation_id": {"type": "string"},
+                "include_inferences": {"type": "boolean"},
+            },
+        },
+        output_schema={"type": "object"},
+        tags=["observability", "explanation"],
+        emits=["execution_started", "execution_completed", "execution_failed"],
+    )
+
+
+def evaluate_counterfactual_descriptor() -> CapabilityDescriptor:
+    return CapabilityDescriptor(
+        id="evaluate_counterfactual",
+        version="0.1.0",
+        description="Evaluate a trace against proposed constraints or invariants.",
+        input_schema={
+            "type": "object",
+            "required": ["correlation_id", "invariant"],
+            "properties": {
+                "correlation_id": {"type": "string"},
+                "invariant": {"type": "object"},
+            },
+        },
+        output_schema={"type": "object"},
+        tags=["observability", "counterfactual"],
+        emits=["execution_started", "execution_completed", "execution_failed"],
+    )
+
+
+async def trace_execution(ctx: CapabilityExecutionContext, payload: JSON) -> JSON:
+    source_id = str(payload["source_id"])
+    external_event_type = str(payload["event_type"])
+    observed_at = payload.get("timestamp") or utc_now()
+    hints = dict(payload.get("correlation_hints") or {})
+
+    event = ctx.emit(
+        "execution_observed",
+        {
+            "source_id": source_id,
+            "external_event_type": external_event_type,
+            "observed_at": observed_at,
+            "summary": payload.get("summary"),
+            "correlation_hints": hints,
+        },
+    )
+
+    return {
+        "accepted": True,
+        "observed_event_id": event.event_id,
+        "correlation_id": ctx.correlation_id,
+    }
+
+
+async def explain_execution(ctx: CapabilityExecutionContext, payload: JSON) -> JSON:
+    correlation_id = str(payload.get("correlation_id") or ctx.correlation_id)
+    include_inferences = bool(payload.get("include_inferences", True))
+    events = ctx.replay(correlation_id)
+
+    facts = [
+        {
+            "event_id": event["event_id"],
+            "event_type": event["event_type"],
+            "timestamp": event["timestamp"],
+            "capability_id": event["capability_id"],
+            "outcome": event.get("outcome"),
+        }
+        for event in events
+    ]
+
+    terminal = [event for event in events if event["event_type"] in {"execution_completed", "execution_failed", "execution_denied"}]
+    failures = [event for event in terminal if event["event_type"] == "execution_failed"]
+    denials = [event for event in terminal if event["event_type"] == "execution_denied"]
+    completed = [event for event in terminal if event["event_type"] == "execution_completed"]
+
+    inferences: list[JSON] = []
+    if include_inferences:
+        if denials:
+            inferences.append(
+                {
+                    "statement": "At least one invocation was denied.",
+                    "confidence": 1.0,
+                    "evidence_ids": [event["event_id"] for event in denials],
+                }
+            )
+        elif failures:
+            inferences.append(
+                {
+                    "statement": "The trace contains failed execution attempts.",
+                    "confidence": 1.0,
+                    "evidence_ids": [event["event_id"] for event in failures],
+                }
+            )
+        elif completed:
+            inferences.append(
+                {
+                    "statement": "Observed invocations in this trace completed without recorded failure or denial.",
+                    "confidence": 0.85,
+                    "evidence_ids": [event["event_id"] for event in completed],
+                }
+            )
+
+    explanation_event = ctx.emit(
+        "explanation_generated",
+        {
+            "target_correlation_id": correlation_id,
+            "fact_count": len(facts),
+            "inference_count": len(inferences),
+        },
+    )
+
+    return {
+        "correlation_id": correlation_id,
+        "facts": facts,
+        "inferences": inferences,
+        "evidence_references": [event["event_id"] for event in events],
+        "explanation_event_id": explanation_event.event_id,
+    }
+
+
+async def evaluate_counterfactual(ctx: CapabilityExecutionContext, payload: JSON) -> JSON:
+    correlation_id = str(payload["correlation_id"])
+    invariant_payload = dict(payload["invariant"])
+    invariant = InvariantDescriptor(
+        id=str(invariant_payload.get("id", "proposed")),
+        kind=str(invariant_payload["kind"]),
+        description=str(invariant_payload.get("description", "")),
+        enforcement=invariant_payload.get("enforcement", "host"),
+        failure_behavior=invariant_payload.get("failure_behavior", "deny"),
+        parameters=dict(invariant_payload.get("parameters") or {}),
+    )
+
+    events = ctx.replay(correlation_id)
+    violations = []
+    for event in events:
+        reason = evaluate_invariant_against_event(invariant, event)
+        if reason:
+            violations.append(
+                {
+                    "event_id": event["event_id"],
+                    "event_type": event["event_type"],
+                    "capability_id": event["capability_id"],
+                    "reason": reason,
+                }
+            )
+
+    counterfactual_event = ctx.emit(
+        "counterfactual_evaluated",
+        {
+            "target_correlation_id": correlation_id,
+            "invariant_id": invariant.id,
+            "violation_count": len(violations),
+        },
+    )
+
+    return {
+        "correlation_id": correlation_id,
+        "invariant": invariant.to_dict(),
+        "would_have_denied": bool(violations) and invariant.failure_behavior == "deny",
+        "would_have_warned": bool(violations) and invariant.failure_behavior == "warn",
+        "would_deny": bool(violations) and invariant.failure_behavior == "deny",
+        "violating_events": violations,
+        "facts": [
+            {
+                "statement": f"Evaluated {len(events)} evidence events against invariant {invariant.id}.",
+                "evidence_ids": [event["event_id"] for event in events],
+            }
+        ],
+        "counterfactual_event_id": counterfactual_event.event_id,
+    }
+
+
+def register_trace_execution(host: LocalCapabilityHost) -> CapabilityDescriptor:
+    return host.register(trace_execution_descriptor(), trace_execution)
+
+
+def register_explain_execution(host: LocalCapabilityHost) -> CapabilityDescriptor:
+    return host.register(explain_execution_descriptor(), explain_execution)
+
+
+def register_evaluate_counterfactual(host: LocalCapabilityHost) -> CapabilityDescriptor:
+    return host.register(evaluate_counterfactual_descriptor(), evaluate_counterfactual)
+
+
+def register_builtin_capabilities(host: LocalCapabilityHost) -> None:
+    register_trace_execution(host)
+    register_explain_execution(host)
+    register_evaluate_counterfactual(host)

chp_core/checks.py

@@ -0,0 +1,39 @@
+"""Shared helpers for local CHP development checks."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .types import JSON
+
+
+def add_check(checks: list[JSON], name: str, passed: bool, details: JSON) -> None:
+    checks.append(
+        {
+            "name": name,
+            "passed": passed,
+            "details": details,
+        }
+    )
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def read_json(path: Path) -> JSON:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def safe_check_name(path: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9]+", "_", path).strip("_")
+
+
+def preview_text(value: str | bytes, limit: int = 1200) -> str:
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", errors="replace")
+    if len(value) <= limit:
+        return value
+    return value[-limit:]