bhanuj-governance-plugin-api 1.0.0__tar.gz

bhanuj_governance_plugin_api-1.0.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Virtual Environment
+.venv/
+
+# Packaging
+*.egg-info/
+dist/
+build/
+# `build/` ignores generated package output. Keep launcher scripts trackable.
+!scripts/build/
+!scripts/build/*.sh
+.DS_Store
+.pnpm-store/
+
+# Testing
+.pytest_cache/
+.coverage
+
+# IDE
+.vscode/
+
+default.sqlite
+
+# Env
+.env.*
+*.env
+!**/.env.example
+!.env.local.example
+!.env.platform.example
+!keycloak-postgres/.env.keycloak.example
+
+# Database
+*.sqlite
+*.db
+
+# walkthrough
+.ai-governance/walkthroughs/*
+.governance/
+
+# misc
+logs/

bhanuj_governance_plugin_api-1.0.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: bhanuj-governance-plugin-api
+Version: 1.0.0
+Summary: Public, provider-neutral plugin contracts for BHANUJ AI Governance.
+Project-URL: Homepage, https://governance.bhanuj.ai
+Project-URL: Documentation, https://governance.bhanuj.ai/docs
+Project-URL: Repository, https://github.com/Bhanuj-AI/ai-governance-oss
+Author: BHANUJ AI
+License: Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# BHANUJ Governance Plugin API
+
+`bhanuj-governance-plugin-api` is the small, versioned extension contract for
+external BHANUJ runtime plugins. It is not the BHANUJ application SDK: it does
+not contain a control plane, persistence, workers, settings, RBAC, or provider
+implementations.
+
+## Install
+
+```toml
+[project]
+dependencies = ["bhanuj-governance-plugin-api>=1.0,<2"]
+
+[project.entry-points."bhanuj.governance.plugins"]
+my-runtime = "my_runtime.plugin:MyRuntimePlugin"
+```
+
+## Boundary
+
+The package supplies lifecycle metadata, the replay-adapter contribution,
+bounded replay context, and the governed intervention envelope. The host owns
+replay persistence, the canonical workflow execution record, and policy
+evaluation. Plugins return `ReplayExecutionResult`; the host materialises its
+own execution record.
+
+The package has no dependency on `ai-governance` and must never import Core.
+`SPI_VERSION` is currently `"1"`. Plugins declare the major version they
+implement with `PluginMetadata(spi_version="1")`; an unsupported major fails
+host startup explicitly.

bhanuj_governance_plugin_api-1.0.0/README.md

@@ -0,0 +1,29 @@
+# BHANUJ Governance Plugin API
+
+`bhanuj-governance-plugin-api` is the small, versioned extension contract for
+external BHANUJ runtime plugins. It is not the BHANUJ application SDK: it does
+not contain a control plane, persistence, workers, settings, RBAC, or provider
+implementations.
+
+## Install
+
+```toml
+[project]
+dependencies = ["bhanuj-governance-plugin-api>=1.0,<2"]
+
+[project.entry-points."bhanuj.governance.plugins"]
+my-runtime = "my_runtime.plugin:MyRuntimePlugin"
+```
+
+## Boundary
+
+The package supplies lifecycle metadata, the replay-adapter contribution,
+bounded replay context, and the governed intervention envelope. The host owns
+replay persistence, the canonical workflow execution record, and policy
+evaluation. Plugins return `ReplayExecutionResult`; the host materialises its
+own execution record.
+
+The package has no dependency on `ai-governance` and must never import Core.
+`SPI_VERSION` is currently `"1"`. Plugins declare the major version they
+implement with `PluginMetadata(spi_version="1")`; an unsupported major fails
+host startup explicitly.

bhanuj_governance_plugin_api-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "bhanuj-governance-plugin-api"
+version = "1.0.0"
+description = "Public, provider-neutral plugin contracts for BHANUJ AI Governance."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "BHANUJ AI" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://governance.bhanuj.ai"
+Documentation = "https://governance.bhanuj.ai/docs"
+Repository = "https://github.com/Bhanuj-AI/ai-governance-oss"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bhanuj_governance_plugin_api"]

bhanuj_governance_plugin_api-1.0.0/src/bhanuj_governance_plugin_api/__init__.py

@@ -0,0 +1,43 @@
+"""Public, dependency-free contracts for BHANUJ runtime plugins."""
+
+from bhanuj_governance_plugin_api.contracts import ReplayExecutionAdapterContribution
+from bhanuj_governance_plugin_api.metadata import (
+    CANONICAL_PLUGIN_ENTRY_POINT_GROUP,
+    LEGACY_CONTRACT_VERSION,
+    LEGACY_PLUGIN_ENTRY_POINT_GROUP,
+    SPI_VERSION,
+    PluginMetadata,
+    PluginStatus,
+)
+from bhanuj_governance_plugin_api.plugin import (
+    AIGovernancePlugin,
+    PluginContext,
+    ReplayAdapterContributionRegistry,
+)
+from bhanuj_governance_plugin_api.replay import (
+    REPLAY_INTERVENTION_ENVELOPE_SCHEMA_VERSION,
+    ReplayCancellationToken,
+    ReplayExecutionAdapter,
+    ReplayExecutionContext,
+    ReplayExecutionResult,
+    ReplayInterventionEnvelope,
+)
+
+__all__ = [
+    "CANONICAL_PLUGIN_ENTRY_POINT_GROUP",
+    "LEGACY_CONTRACT_VERSION",
+    "LEGACY_PLUGIN_ENTRY_POINT_GROUP",
+    "REPLAY_INTERVENTION_ENVELOPE_SCHEMA_VERSION",
+    "SPI_VERSION",
+    "AIGovernancePlugin",
+    "PluginContext",
+    "PluginMetadata",
+    "PluginStatus",
+    "ReplayAdapterContributionRegistry",
+    "ReplayCancellationToken",
+    "ReplayExecutionAdapter",
+    "ReplayExecutionAdapterContribution",
+    "ReplayExecutionContext",
+    "ReplayExecutionResult",
+    "ReplayInterventionEnvelope",
+]

bhanuj_governance_plugin_api-1.0.0/src/bhanuj_governance_plugin_api/contracts.py

@@ -0,0 +1,35 @@
+"""Public plugin contributions with no BHANUJ Core imports."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from bhanuj_governance_plugin_api.replay import ReplayExecutionAdapter
+
+_REPLAY_ADAPTER_COMPONENT = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$")
+
+
+@dataclass(frozen=True)
+class ReplayExecutionAdapterContribution:
+    """One versioned external adapter contributed by a runtime plugin."""
+
+    adapter_id: str
+    adapter_version: str
+    adapter: ReplayExecutionAdapter
+
+    def __post_init__(self) -> None:
+        if not _REPLAY_ADAPTER_COMPONENT.fullmatch(
+            self.adapter_id
+        ) or not _REPLAY_ADAPTER_COMPONENT.fullmatch(self.adapter_version):
+            raise ValueError(
+                "Replay adapter contribution requires lowercase, hyphen-delimited adapter ID and version."
+            )
+        if self.adapter.name != self.name:
+            raise ValueError(
+                "Replay adapter contribution identity must match adapter.name."
+            )
+
+    @property
+    def name(self) -> str:
+        return f"{self.adapter_id}/{self.adapter_version}"

bhanuj_governance_plugin_api-1.0.0/src/bhanuj_governance_plugin_api/metadata.py

@@ -0,0 +1,57 @@
+"""Versioned identity and compatibility declarations for runtime plugins."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+SPI_VERSION = "1"
+"""The supported major version of the independently released Plugin API."""
+
+LEGACY_CONTRACT_VERSION = "v1"
+"""Compatibility spelling retained for diagnostics emitted by existing hosts."""
+
+CANONICAL_PLUGIN_ENTRY_POINT_GROUP = "bhanuj.governance.plugins"
+"""The Python packaging entry-point group for new BHANUJ plugins."""
+
+LEGACY_PLUGIN_ENTRY_POINT_GROUP = "ai_governance.plugins"
+"""Temporarily supported entry-point group for pre-Plugin-API extensions."""
+
+
+class PluginStatus(StrEnum):
+    """Lifecycle state reported by a BHANUJ plugin host."""
+
+    DISCOVERED = "discovered"
+    REGISTERED = "registered"
+    ACTIVE = "active"
+    DISABLED = "disabled"
+    FAILED = "failed"
+    INCOMPATIBLE = "incompatible"
+
+
+@dataclass(frozen=True)
+class PluginMetadata:
+    """Immutable identity, host compatibility, and Plugin API compatibility."""
+
+    name: str
+    version: str
+    required_ai_governance_version: str
+    capabilities: tuple[str, ...] = ()
+    spi_version: str = SPI_VERSION
+    contract_version: str = LEGACY_CONTRACT_VERSION
+
+    def __post_init__(self) -> None:
+        if not self.name.strip() or not self.version.strip():
+            raise ValueError("Plugin metadata requires a name and version.")
+        if not self.required_ai_governance_version.strip():
+            raise ValueError(
+                "Plugin metadata requires an AI Governance Control Plane version range."
+            )
+        if not self.spi_version.isdigit() or int(self.spi_version) < 1:
+            raise ValueError("Plugin metadata spi_version must be a positive major.")
+        if self.contract_version != f"v{self.spi_version}":
+            raise ValueError(
+                "Plugin metadata contract_version must match its SPI major version."
+            )
+        if len(set(self.capabilities)) != len(self.capabilities):
+            raise ValueError("Plugin capabilities must be unique.")

bhanuj_governance_plugin_api-1.0.0/src/bhanuj_governance_plugin_api/plugin.py

@@ -0,0 +1,39 @@
+"""Structural lifecycle contracts implemented by external runtime plugins."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol
+
+from bhanuj_governance_plugin_api.contracts import ReplayExecutionAdapterContribution
+from bhanuj_governance_plugin_api.metadata import PluginMetadata
+
+
+class ReplayAdapterContributionRegistry(Protocol):
+    """The bounded host registration surface needed by runtime plugins."""
+
+    def replay_execution_adapters(
+        self, items: Iterable[ReplayExecutionAdapterContribution]
+    ) -> None: ...
+
+
+class PluginContext(Protocol):
+    """Plugin-bound context exposed by a host during lifecycle callbacks."""
+
+    @property
+    def contributions(self) -> ReplayAdapterContributionRegistry: ...
+
+
+class AIGovernancePlugin(Protocol):
+    """Stable lifecycle protocol for an independently installed plugin."""
+
+    @property
+    def metadata(self) -> PluginMetadata: ...
+
+    def validate(self, context: PluginContext) -> None: ...
+
+    def register(self, context: PluginContext) -> None: ...
+
+    def start(self, context: PluginContext) -> None: ...
+
+    def stop(self, context: PluginContext) -> None: ...

bhanuj_governance_plugin_api-1.0.0/src/bhanuj_governance_plugin_api/replay.py

@@ -0,0 +1,204 @@
+"""Provider-neutral, governed replay contracts for external runtime plugins."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime
+from types import MappingProxyType
+from typing import Any, Protocol
+
+REPLAY_INTERVENTION_ENVELOPE_SCHEMA_VERSION = "replay-intervention-envelope/v1"
+_STRATEGIES = frozenset({"NULLIFY", "REPLACE", "PERTURB"})
+
+
+class ReplayCancellationToken(Protocol):
+    """Cooperative cancellation visible to an adapter at safe boundaries."""
+
+    @property
+    def is_cancelled(self) -> bool: ...
+
+
+@dataclass(frozen=True)
+class ReplayInterventionEnvelope:
+    """The fixed, reference-only policy authorization for a controlled replay."""
+
+    policy_id: str
+    policy_version: int
+    external_execution_id: str
+    runtime_tool_call_id: str
+    intervention_provider: str
+    intervention_provider_version: str
+    strategy: str
+    original_evidence_digest: str
+    counterfactual_reference: str
+    counterfactual_digest: str
+    intervention_digest: str
+    schema_version: str = REPLAY_INTERVENTION_ENVELOPE_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("policy_id", self.policy_id),
+            ("external_execution_id", self.external_execution_id),
+            ("runtime_tool_call_id", self.runtime_tool_call_id),
+            ("intervention_provider", self.intervention_provider),
+            ("intervention_provider_version", self.intervention_provider_version),
+            ("original_evidence_digest", self.original_evidence_digest),
+            ("counterfactual_reference", self.counterfactual_reference),
+            ("counterfactual_digest", self.counterfactual_digest),
+            ("intervention_digest", self.intervention_digest),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"Replay intervention envelope {name} is required.")
+        if (
+            not isinstance(self.policy_version, int)
+            or isinstance(self.policy_version, bool)
+            or self.policy_version < 1
+        ):
+            raise ValueError(
+                "Replay intervention envelope policy_version must be positive."
+            )
+        if self.strategy not in _STRATEGIES:
+            raise ValueError("Replay intervention envelope strategy is unsupported.")
+        if self.schema_version != REPLAY_INTERVENTION_ENVELOPE_SCHEMA_VERSION:
+            raise ValueError(
+                f"Unsupported Replay intervention envelope schema version: {self.schema_version!r}."
+            )
+
+    def to_payload(self) -> dict[str, object]:
+        """Serialise precisely the v1 reference-only wire shape."""
+        return {
+            "schema_version": self.schema_version,
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "external_execution_id": self.external_execution_id,
+            "runtime_tool_call_id": self.runtime_tool_call_id,
+            "intervention_provider": self.intervention_provider,
+            "intervention_provider_version": self.intervention_provider_version,
+            "strategy": self.strategy,
+            "original_evidence_digest": self.original_evidence_digest,
+            "counterfactual_reference": self.counterfactual_reference,
+            "counterfactual_digest": self.counterfactual_digest,
+            "intervention_digest": self.intervention_digest,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, object]) -> ReplayInterventionEnvelope:
+        """Parse only a complete v1 envelope and reject unknown fields."""
+        expected = set(cls.__dataclass_fields__)
+        if set(payload) != expected:
+            raise ValueError(
+                "Replay intervention envelope payload has an unsupported shape."
+            )
+        return cls(
+            policy_id=_required_string(payload, "policy_id"),
+            policy_version=_required_version(payload),
+            external_execution_id=_required_string(payload, "external_execution_id"),
+            runtime_tool_call_id=_required_string(payload, "runtime_tool_call_id"),
+            intervention_provider=_required_string(payload, "intervention_provider"),
+            intervention_provider_version=_required_string(
+                payload, "intervention_provider_version"
+            ),
+            strategy=_required_string(payload, "strategy"),
+            original_evidence_digest=_required_string(
+                payload, "original_evidence_digest"
+            ),
+            counterfactual_reference=_required_string(
+                payload, "counterfactual_reference"
+            ),
+            counterfactual_digest=_required_string(payload, "counterfactual_digest"),
+            intervention_digest=_required_string(payload, "intervention_digest"),
+            schema_version=_required_string(payload, "schema_version"),
+        )
+
+
+@dataclass(frozen=True)
+class ReplayExecutionContext:
+    """Host-owned attempt metadata exposed to a runtime adapter."""
+
+    replay_id: str
+    source_execution_id: str
+    new_execution_id: str
+    organization_id: str
+    project_id: str
+    actor_id: str
+    request_id: str
+    correlation_id: str | None
+    attempt: int
+    cancellation_token: ReplayCancellationToken
+    metadata: Mapping[str, Any]
+    controlled_evidence_intervention: object | None = None
+    intervention_envelope: ReplayInterventionEnvelope | None = None
+
+
+@dataclass(frozen=True)
+class ReplayExecutionResult:
+    """Runtime-produced data that Core materialises as its workflow execution."""
+
+    execution_status: str
+    input: Mapping[str, Any] = field(default_factory=dict)
+    final_state: Mapping[str, Any] = field(default_factory=dict)
+    events: Sequence[Mapping[str, Any]] = ()
+    artifact_refs: Sequence[str] = ()
+    runtime_parameters: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    created_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.execution_status, str)
+            or not self.execution_status.strip()
+        ):
+            raise ValueError("Replay execution result status is required.")
+        object.__setattr__(self, "input", MappingProxyType(dict(self.input)))
+        object.__setattr__(
+            self, "final_state", MappingProxyType(dict(self.final_state))
+        )
+        object.__setattr__(
+            self, "events", tuple(MappingProxyType(dict(item)) for item in self.events)
+        )
+        object.__setattr__(self, "artifact_refs", tuple(self.artifact_refs))
+        object.__setattr__(
+            self, "runtime_parameters", MappingProxyType(dict(self.runtime_parameters))
+        )
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+
+
+class ReplayExecutionAdapter(Protocol):
+    """A runtime adapter selected by its versioned persisted name.
+
+    The source execution and frozen replay configuration are host-owned values.
+    Plugin code must not import Core models to implement this protocol. External
+    adapters return :class:`ReplayExecutionResult`; hosts may retain temporary
+    compatibility for their own legacy in-process adapters.
+    """
+
+    @property
+    def name(self) -> str: ...
+
+    def validate_configuration(
+        self, source_execution: object, configuration: object
+    ) -> None: ...
+
+    def replay(
+        self,
+        source_execution: object,
+        configuration: object,
+        context: ReplayExecutionContext,
+    ) -> ReplayExecutionResult: ...
+
+
+def _required_string(payload: Mapping[str, object], name: str) -> str:
+    value = payload.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"Replay intervention envelope {name} is required.")
+    return value
+
+
+def _required_version(payload: Mapping[str, object]) -> int:
+    value = payload.get("policy_version")
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise ValueError(
+            "Replay intervention envelope policy_version must be positive."
+        )
+    return value

bhanuj_governance_plugin_api-1.0.0/tests/test_public_contract.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from bhanuj_governance_plugin_api import (
+    SPI_VERSION,
+    PluginMetadata,
+    ReplayExecutionResult,
+    ReplayInterventionEnvelope,
+)
+
+
+def test_plugin_api_has_no_core_imports() -> None:
+    source_root = Path(__file__).parents[1] / "src" / "bhanuj_governance_plugin_api"
+
+    for source in source_root.glob("*.py"):
+        imports = ast.parse(source.read_text()).body
+        assert not any(
+            isinstance(node, ast.Import)
+            and any(
+                alias.name == "ai_governance" or alias.name.startswith("ai_governance.")
+                for alias in node.names
+            )
+            or isinstance(node, ast.ImportFrom)
+            and node.module is not None
+            and (
+                node.module == "ai_governance"
+                or node.module.startswith("ai_governance.")
+            )
+            for node in imports
+        )
+
+
+def test_plugin_metadata_declares_the_supported_spi_major() -> None:
+    metadata = PluginMetadata(
+        name="external-runtime",
+        version="1.0.0",
+        required_ai_governance_version=">=1.1,<2",
+    )
+
+    assert metadata.spi_version == SPI_VERSION == "1"
+    assert metadata.contract_version == "v1"
+
+
+def test_governed_envelope_rejects_unknown_fields_and_raw_payload_growth() -> None:
+    envelope = ReplayInterventionEnvelope(
+        policy_id="policy-1",
+        policy_version=1,
+        external_execution_id="execution-1",
+        runtime_tool_call_id="call-1",
+        intervention_provider="opaque-reference",
+        intervention_provider_version="v1",
+        strategy="REPLACE",
+        original_evidence_digest="sha256:original",
+        counterfactual_reference="runtime://counterfactual",
+        counterfactual_digest="sha256:counterfactual",
+        intervention_digest="sha256:intervention",
+    )
+
+    payload = envelope.to_payload()
+
+    assert ReplayInterventionEnvelope.from_payload(payload) == envelope
+    try:
+        ReplayInterventionEnvelope.from_payload({**payload, "raw_evidence": {}})
+    except ValueError as error:
+        assert "unsupported shape" in str(error)
+    else:  # pragma: no cover - explicit contract guard
+        raise AssertionError("Unknown envelope fields must fail closed.")
+
+
+def test_external_result_is_immutable_and_has_no_core_execution_type() -> None:
+    result = ReplayExecutionResult(
+        execution_status="COMPLETED",
+        final_state={"outcome": 0.0},
+        events=({"type": "EXTERNAL_RUNTIME_REPLAY_COMPLETED"},),
+    )
+
+    assert result.final_state["outcome"] == 0.0
+    assert result.events[0]["type"] == "EXTERNAL_RUNTIME_REPLAY_COMPLETED"