siphrix 1.0.0__py3-none-any.whl

siphrix/__init__.py

@@ -0,0 +1,94 @@
+"""Siphrix — AI Action Firewall & Policy Runtime.
+
+Siphrix sits between what an AI agent wants to do and what it is
+allowed to do: it evaluates every agent action against a policy
+before execution, emits an auditable decision trail, and fails closed
+when in doubt.
+
+CLI first-run path:
+
+    siphrix demo                 # the official three-flow demo
+    python -m siphrix --help     # discover every subcommand
+
+Internally Siphrix is built from four coordinated layers — a policy
+decision layer (``siphrix.policy_runtime``), a runtime enforcement
+layer (``siphrix.runtime``, ``siphrix.exec_intercept``), a
+trust / audit / governance support layer (``siphrix.trust``,
+``siphrix.audit``, ``siphrix.governance``), and an operator
+readiness surface (``siphrix.doctor``, ``siphrix.readiness``,
+the ``siphrix`` CLI). Externally it is one product: the firewall
+at the boundary between agent intent and real-world action.
+
+This module defines the official, product-facing public API. A small
+set of names is promoted here; everything else lives under the
+corresponding subpackage (``siphrix.orchestrator``,
+``siphrix.policy_runtime``, ``siphrix.governance``,
+``siphrix.contracts``, …) and must be imported explicitly.
+
+Official public API
+-------------------
+
+Runtime execution:
+
+    from siphrix import run_pipeline, PipelineResult
+
+    result = run_pipeline("your input")
+    result.outcome      # "proceed" | "block" | "ask_confirm" | "clarify"
+    result.final_text   # generated text when outcome == "proceed"
+
+Policy evaluation:
+
+    from siphrix import PolicyInput, PolicyManager, PolicyDecision
+
+    policy_input = PolicyInput.from_dict({"action_name": "http_get"})
+    decision: PolicyDecision = PolicyManager().decide(policy_input.to_action_context())
+    decision.verdict    # "ALLOW" | "BLOCK" | "ABORT"
+    decision.reason     # stable reason code
+
+Invalid input is surfaced through ``PolicyInputValidationError``.
+
+Agent / tool-calling integration:
+
+    from siphrix import ActionEvaluator
+
+    evaluator = ActionEvaluator()
+    response = evaluator.evaluate({
+        "action_name": "http_get",
+        "resource.domain": "example.com",
+        "effect_type": "READ_ONLY",
+        "risk_level": "LOW",
+    })
+    if response.allowed:
+        perform_action()
+
+Version:
+
+    from siphrix import __version__
+
+Stability
+---------
+The names re-exported here are the stable product surface. Names
+reachable only through deeper module paths (``siphrix.<subpackage>.*``)
+are documented per-subpackage but are not part of this top-level
+contract.
+"""
+
+from siphrix.agent import ActionEvaluationResponse, ActionEvaluator
+from siphrix.orchestrator import PipelineResult, run_pipeline
+from siphrix.policy_runtime.input import PolicyInput, PolicyInputValidationError
+from siphrix.policy_runtime.manager import PolicyManager
+from siphrix.policy_runtime.types import PolicyDecision
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ActionEvaluationResponse",
+    "ActionEvaluator",
+    "PipelineResult",
+    "PolicyDecision",
+    "PolicyInput",
+    "PolicyInputValidationError",
+    "PolicyManager",
+    "__version__",
+    "run_pipeline",
+]

siphrix/__main__.py

@@ -0,0 +1,13 @@
+"""Package entry point for ``python -m siphrix``.
+
+Delegates to the canonical CLI in :mod:`siphrix.cli.app` so that
+``python -m siphrix <cmd>`` and the installed ``siphrix`` console
+script run byte-identical code.
+"""
+
+from __future__ import annotations
+
+from siphrix.cli.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

siphrix/adapters/__init__.py

@@ -0,0 +1,98 @@
+"""Adapter domain surfaces for planners, context ingestion, and future frameworks.
+
+This package root is a thin PEP 562 lazy facade. Public names are
+owned by the sibling submodules listed in ``_ROUTES`` below; they are
+resolved on first attribute access and cached into ``globals()`` for
+subsequent O(1) dict hits. Behaviour is identical to the previous
+eager re-export module: ``from siphrix.adapters import <name>`` still
+works for every historical public name.
+"""
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+_ROUTES: dict[str, str] = {
+    # from .registry
+    'AdapterLookupError': 'registry',
+    'AdapterRegistrationError': 'registry',
+    'AdapterSelectionError': 'registry',
+    'ContextAdapterRequirements': 'registry',
+    'ExecutorAdapterRequirements': 'registry',
+    'FrameworkAdapterRequirements': 'registry',
+    'IntegrationRegistry': 'registry',
+    'PlannerAdapterRequirements': 'registry',
+    'build_default_integration_registry': 'registry',
+    # from .frameworks
+    'AgentRuntimeAdapter': 'frameworks',
+    'OrchestrationAdapter': 'frameworks',
+    'WorkflowAdapter': 'frameworks',
+    # from .planners
+    'AnthropicPlanner': 'planners',
+    'CustomPlanner': 'planners',
+    'GeminiPlanner': 'planners',
+    'LocalPlanner': 'planners',
+    'MockPlanner': 'planners',
+    'OllamaPlanner': 'planners',
+    'OpenAIPlanner': 'planners',
+    # from .context
+    'CompositeContextAdapter': 'context',
+    'EnvironmentContextAdapter': 'context',
+    'RoleContextAdapter': 'context',
+    'SessionContextAdapter': 'context',
+    'TenantContextAdapter': 'context',
+    # from .executors
+    'EmailExecutor': 'executors',
+    'FilesystemExecutor': 'executors',
+    'NetworkExecutor': 'executors',
+    'SandboxExecutor': 'executors',
+    'ShellExecutor': 'executors',
+    'StubExecutor': 'executors',
+}
+
+__all__ = [
+    'AdapterLookupError',
+    'AdapterRegistrationError',
+    'AdapterSelectionError',
+    'AgentRuntimeAdapter',
+    'AnthropicPlanner',
+    'CompositeContextAdapter',
+    'ContextAdapterRequirements',
+    'CustomPlanner',
+    'EmailExecutor',
+    'EnvironmentContextAdapter',
+    'ExecutorAdapterRequirements',
+    'FilesystemExecutor',
+    'FrameworkAdapterRequirements',
+    'GeminiPlanner',
+    'IntegrationRegistry',
+    'LocalPlanner',
+    'MockPlanner',
+    'NetworkExecutor',
+    'OllamaPlanner',
+    'OpenAIPlanner',
+    'OrchestrationAdapter',
+    'PlannerAdapterRequirements',
+    'RoleContextAdapter',
+    'SandboxExecutor',
+    'SessionContextAdapter',
+    'ShellExecutor',
+    'StubExecutor',
+    'TenantContextAdapter',
+    'WorkflowAdapter',
+    'build_default_integration_registry',
+]
+
+
+def __getattr__(name: str) -> Any:
+    sub = _ROUTES.get(name)
+    if sub is None:
+        raise AttributeError(f"module 'siphrix.adapters' has no attribute {name!r}")
+    module = importlib.import_module(f".{sub}", 'siphrix.adapters')
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_ROUTES))

siphrix/adapters/context/__init__.py

@@ -0,0 +1,15 @@
+"""Canonical context adapters for Siphrix integration boundaries."""
+
+from siphrix.adapters.context.composite_context import CompositeContextAdapter
+from siphrix.adapters.context.environment_context import EnvironmentContextAdapter
+from siphrix.adapters.context.role_context import RoleContextAdapter
+from siphrix.adapters.context.session_context import SessionContextAdapter
+from siphrix.adapters.context.tenant_context import TenantContextAdapter
+
+__all__ = [
+    "CompositeContextAdapter",
+    "EnvironmentContextAdapter",
+    "RoleContextAdapter",
+    "SessionContextAdapter",
+    "TenantContextAdapter",
+]

siphrix/adapters/context/base.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+"""Shared base helpers for canonical context adapters."""
+
+from typing import Iterable, Mapping, Optional
+
+from siphrix.adapters.context.normalizer import merge_context_fragments, normalize_context_mapping
+from siphrix.contracts.adapter_capability import (
+    AdapterCapability,
+    AdapterDescriptor,
+    AdapterExecutionSemantics,
+)
+from siphrix.contracts.context import IntegrationContext
+
+
+class ContextAdapterBase:
+    provider_name = "context"
+    adapter_kind = "context"
+    supported_context_fields: tuple[str, ...] = ()
+    supports_merge = False
+    supports_partial_context = True
+    preserves_provenance = True
+
+    def describe_capabilities(self) -> AdapterDescriptor:
+        return AdapterDescriptor(
+            adapter_id=f"context:{self.provider_name}",
+            domain="context",
+            provider_name=self.provider_name,
+            adapter_kind=self.adapter_kind,
+            metadata={
+                "supports_merge": str(self.supports_merge).lower(),
+                "supports_partial_context": str(self.supports_partial_context).lower(),
+                "supports_field_provenance": str(self.preserves_provenance).lower(),
+                "supports_override_trail": str(self.preserves_provenance).lower(),
+                "primary_output": "IntegrationContext",
+            },
+            capabilities=(
+                AdapterCapability(
+                    name=f"{self.provider_name}-context",
+                    supported_context_fields=self.supported_context_fields,
+                    execution_semantics=AdapterExecutionSemantics.SYNC,
+                    preserves_raw_output=False,
+                    produces_structured_actions=False,
+                    validates_payloads=True,
+                    supports_provenance=self.preserves_provenance,
+                    metadata={
+                        "kind": self.adapter_kind,
+                        "supports_merge": str(self.supports_merge).lower(),
+                        "supports_partial_context": str(self.supports_partial_context).lower(),
+                        "supports_field_provenance": str(self.preserves_provenance).lower(),
+                        "supports_override_trail": str(self.preserves_provenance).lower(),
+                        "primary_output": "IntegrationContext",
+                    },
+                ),
+            ),
+        )
+
+    def build_context_from_mapping(
+        self,
+        payload: Mapping[str, object],
+        *,
+        source_name: str,
+        defaults: Optional[Mapping[str, object]] = None,
+        source_system: Optional[str] = None,
+    ) -> IntegrationContext:
+        fragment = normalize_context_mapping(
+            payload,
+            source_name=source_name,
+            supported_fields=self.supported_context_fields,
+            defaults=defaults,
+            source_adapter=self.provider_name,
+            source_system=source_system,
+        )
+        return merge_context_fragments((fragment,), source_adapter=self.provider_name, source_system=source_system)
+
+    def compose_context(self, fragments: Iterable, *, source_system: Optional[str] = None) -> IntegrationContext:
+        return merge_context_fragments(
+            fragments,
+            source_adapter=self.provider_name,
+            source_system=source_system,
+        )

siphrix/adapters/context/composite_context.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from siphrix.adapters.context.base import ContextAdapterBase
+from siphrix.adapters.context.environment_context import EnvironmentContextAdapter
+from siphrix.adapters.context.normalizer import normalize_context_mapping
+from siphrix.adapters.context.role_context import RoleContextAdapter
+from siphrix.adapters.context.session_context import SessionContextAdapter
+from siphrix.adapters.context.tenant_context import TenantContextAdapter
+from siphrix.contracts.context import IntegrationContext
+
+
+class CompositeContextAdapter(ContextAdapterBase):
+    provider_name = "composite_context"
+    supported_context_fields = (
+        "role",
+        "tenant",
+        "environment",
+        "session",
+        "actor_id",
+        "actor_display_name",
+        "runtime_channel",
+        "source_system",
+        "source_adapter",
+    )
+    supports_merge = True
+
+    def __init__(self) -> None:
+        self.role_adapter = RoleContextAdapter()
+        self.tenant_adapter = TenantContextAdapter()
+        self.environment_adapter = EnvironmentContextAdapter()
+        self.session_adapter = SessionContextAdapter()
+
+    def normalize(
+        self,
+        *,
+        role_context: Optional[Mapping[str, object]] = None,
+        tenant_context: Optional[Mapping[str, object]] = None,
+        environment_context: Optional[Mapping[str, object]] = None,
+        session_context: Optional[Mapping[str, object]] = None,
+        defaults: Optional[Mapping[str, object]] = None,
+        source_system: Optional[str] = None,
+    ) -> IntegrationContext:
+        fragments = []
+        if defaults:
+            fragments.append(
+                normalize_context_mapping(
+                    {},
+                    source_name="defaults",
+                    supported_fields=self.supported_context_fields,
+                    defaults=defaults,
+                    source_system=source_system,
+                )
+            )
+        if tenant_context is not None:
+            fragments.append(self.tenant_adapter.normalize_fragment(tenant_context, source_system=source_system))
+        if environment_context is not None:
+            fragments.append(self.environment_adapter.normalize_fragment(environment_context, source_system=source_system))
+        if session_context is not None:
+            fragments.append(self.session_adapter.normalize_fragment(session_context, source_system=source_system))
+        if role_context is not None:
+            fragments.append(self.role_adapter.normalize_fragment(role_context, source_system=source_system))
+        return self.compose_context(fragments, source_system=source_system)
+
+    def normalize_mapping(
+        self,
+        payload: Mapping[str, object],
+        *,
+        defaults: Optional[Mapping[str, object]] = None,
+        source_system: Optional[str] = None,
+    ) -> IntegrationContext:
+        return self.normalize(
+            role_context=payload,
+            tenant_context=payload,
+            environment_context=payload,
+            session_context=payload,
+            defaults=defaults,
+            source_system=source_system,
+        )

siphrix/adapters/context/environment_context.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from siphrix.adapters.context.base import ContextAdapterBase
+from siphrix.adapters.context.normalizer import NormalizedContextFragment, normalize_context_mapping
+from siphrix.contracts.context import IntegrationContext
+
+
+class EnvironmentContextAdapter(ContextAdapterBase):
+    provider_name = "environment_context"
+    supported_context_fields = ("environment", "runtime_channel", "source_system", "source_adapter")
+
+    def normalize(
+        self,
+        payload: Mapping[str, object],
+        *,
+        defaults: Optional[Mapping[str, object]] = None,
+        source_system: Optional[str] = None,
+    ) -> IntegrationContext:
+        return self.build_context_from_mapping(payload, source_name="environment_context", defaults=defaults, source_system=source_system)
+
+    def normalize_fragment(
+        self,
+        payload: Mapping[str, object],
+        *,
+        defaults: Optional[Mapping[str, object]] = None,
+        source_system: Optional[str] = None,
+    ) -> NormalizedContextFragment:
+        return normalize_context_mapping(
+            payload,
+            source_name="environment_context",
+            supported_fields=self.supported_context_fields,
+            defaults=defaults,
+            source_adapter=self.provider_name,
+            source_system=source_system,
+        )