cfa-kernel 0.1.0__py3-none-any.whl

cfa/__init__.py

@@ -0,0 +1,39 @@
+"""
+CFA — Contextual Flux Architecture
+===================================
+Governed execution for AI agents and data systems.
+"""
+
+from cfa._lazy import LazyLoader
+
+__version__ = "0.1.0"
+
+__getattr__ = LazyLoader({
+    "KernelOrchestrator": ("cfa.core.kernel", "KernelOrchestrator"),
+    "KernelConfig": ("cfa.core.kernel", "KernelConfig"),
+    "PipelinePhase": ("cfa.core.kernel", "PipelinePhase"),
+    "DecisionState": ("cfa.types", "DecisionState"),
+    "StateSignature": ("cfa.types", "StateSignature"),
+    "KernelResult": ("cfa.types", "KernelResult"),
+    "TargetLayer": ("cfa.types", "TargetLayer"),
+    "Fault": ("cfa.types", "Fault"),
+    "FaultFamily": ("cfa.types", "FaultFamily"),
+    "FaultSeverity": ("cfa.types", "FaultSeverity"),
+    "PolicyAction": ("cfa.types", "PolicyAction"),
+    "ContextRegistry": ("cfa.audit.context", "ContextRegistry"),
+    "JsonFileContextStorage": ("cfa.audit.context", "JsonFileContextStorage"),
+    "AuditTrail": ("cfa.audit.trail", "AuditTrail"),
+    "JsonLinesAuditStorage": ("cfa.audit.trail", "JsonLinesAuditStorage"),
+    "BackendAdapter": ("cfa.backends", "BackendAdapter"),
+    "BackendCapabilities": ("cfa.backends", "BackendCapabilities"),
+    "BackendRegistry": ("cfa.backends", "BackendRegistry"),
+    "PySparkBackend": ("cfa.backends.pyspark", "PySparkBackend"),
+    "evaluate": ("cfa.testing.evaluate", "evaluate"),
+    "EvaluationResult": ("cfa.testing.evaluate", "EvaluationResult"),
+    "BehaviorSpec": ("cfa.behavior.spec", "BehaviorSpec"),
+    "BehaviorTaxonomy": ("cfa.behavior.spec", "BehaviorTaxonomy"),
+    "Systematizer": ("cfa.behavior.systematizer", "Systematizer"),
+    "RuntimeGate": ("cfa.runtime.gate", "RuntimeGate"),
+    "GateConfig": ("cfa.runtime.gate", "GateConfig"),
+    "GovernanceViolation": ("cfa.runtime.gate", "GovernanceViolation"),
+})

cfa/_lazy.py

@@ -0,0 +1,39 @@
+"""Reusable lazy import helper for package __init__.py files.
+
+Usage::
+
+    from cfa._lazy import LazyLoader
+
+    __getattr__ = LazyLoader({
+        "KernelOrchestrator": ("cfa.core.kernel", "KernelOrchestrator"),
+        "KernelConfig": ("cfa.core.kernel", "KernelConfig"),
+    })
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+class LazyLoader:
+    """Callable that resolves symbols lazily from a mapping.
+
+    Replace ``__getattr__`` in any package ``__init__.py``::
+
+        from cfa._lazy import LazyLoader
+        __getattr__ = LazyLoader({"Symbol": ("package.module", "Symbol")})
+    """
+
+    __slots__ = ("_map",)
+
+    def __init__(self, mapping: dict[str, tuple[str, str]]) -> None:
+        self._map = mapping
+
+    def __call__(self, name: str) -> Any:
+        entry = self._map.get(name)
+        if entry is None:
+            raise AttributeError(f"module has no attribute {name!r}")
+        module_path, attr = entry
+        module = importlib.import_module(module_path)
+        return getattr(module, attr)

cfa/adapters/__init__.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from collections.abc import Callable  # noqa: F401
+from functools import wraps
+from typing import Any
+
+from cfa.core.kernel import KernelConfig, KernelOrchestrator
+
+
+class CFAGuard:
+    """Base governance guard for any callable.
+
+    Wraps a function with CFA policy validation before execution.
+    The function's first argument or a provided intent string is
+    evaluated against the policy engine.
+
+    Usage:
+        guard = CFAGuard(policy_bundle="prod-v1", catalog=my_catalog)
+
+        @guard("aggregate sales data")
+        def my_pipeline(): ...
+
+        @guard  # uses function name/docstring as intent
+        def another_pipeline(): ...
+    """
+
+    def __init__(
+        self,
+        policy_bundle: str = "v1.0",
+        catalog: dict[str, Any] | None = None,
+        backend: str = "pyspark",
+        mode: str = "block",  # block | warn | audit
+        **kernel_kwargs: Any,
+    ) -> None:
+        self._config = KernelConfig(
+            policy_bundle_version=policy_bundle,
+            backend=backend,
+            warnings_are_blocking=(mode == "block"),
+        )
+        self._catalog = catalog
+        self._mode = mode
+        self._kernel_kwargs = kernel_kwargs
+
+    def __call__(self, fn_or_intent):
+        if isinstance(fn_or_intent, str):
+            intent = fn_or_intent
+            def decorator(fn):
+                @wraps(fn)
+                def wrapper(*args, **kwargs):
+                    self._check(intent)
+                    return fn(*args, **kwargs)
+                return wrapper
+            return decorator
+
+        fn = fn_or_intent
+        intent = fn.__doc__ or fn.__name__ if hasattr(fn, "__doc__") else str(fn)
+
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            self._check(intent)
+            return fn(*args, **kwargs)
+        return wrapper
+
+    def guard(self, intent: str):
+        """Explicit guard with intent string."""
+        def decorator(fn):
+            @wraps(fn)
+            def wrapper(*args, **kwargs):
+                self._check(intent)
+                return fn(*args, **kwargs)
+            return wrapper
+        return decorator
+
+    def _check(self, intent: str) -> None:
+        kernel = KernelOrchestrator(
+            catalog=self._catalog, config=self._config, **self._kernel_kwargs
+        )
+        result = kernel.process(intent)
+        if not result.is_executable and self._mode == "block":
+            raise PermissionError(
+                f"CFA blocked intent '{intent[:80]}': {result.blocked_reason}"
+            )
+
+
+def cfa_guard(
+    intent: str | None = None,
+    *,
+    policy_bundle: str = "v1.0",
+    catalog: dict[str, Any] | None = None,
+    mode: str = "block",
+    **kwargs: Any,
+):
+    """Universal CFA governance guard for any callable or agent tool.
+
+    Args:
+        intent: Intent string to validate. If None, uses function docstring/name.
+        policy_bundle: Policy bundle version or path to YAML file.
+        catalog: Data catalog with dataset metadata.
+        mode: 'block' (raise), 'warn' (log), or 'audit' (silent record).
+    """
+    guard = CFAGuard(policy_bundle=policy_bundle, catalog=catalog, mode=mode, **kwargs)
+    if intent:
+        return guard.guard(intent)
+    return guard

cfa/adapters/autogen.py

@@ -0,0 +1,19 @@
+"""AutoGen adapter — CFA governance for agent functions.
+
+Usage::
+
+    from cfa.adapters.autogen import cfa_agent_guard
+
+    @cfa_agent_guard("analyze customer data without raw PII",
+                      policy_bundle="compliance-strict-v1")
+    def analyze(state):
+        ...
+
+The decorator is equivalent to ``cfa.adapters.cfa_guard``.
+"""
+
+from __future__ import annotations
+
+from ..adapters import cfa_guard as _cfa_guard
+
+cfa_agent_guard = _cfa_guard

cfa/adapters/crewai.py

@@ -0,0 +1,19 @@
+"""CrewAI adapter — CFA governance for crew tasks.
+
+Usage::
+
+    from cfa.adapters.crewai import cfa_crew_guard
+
+    @cfa_crew_guard("extract financial data from Silver layer",
+                     policy_bundle="finops-strict-v1")
+    def extract_task():
+        ...
+
+The decorator is equivalent to ``cfa.adapters.cfa_guard``.
+"""
+
+from __future__ import annotations
+
+from ..adapters import cfa_guard as _cfa_guard
+
+cfa_crew_guard = _cfa_guard

cfa/adapters/dspy.py

@@ -0,0 +1,19 @@
+"""DSPy adapter — CFA governance for DSPy modules.
+
+Usage::
+
+    from cfa.adapters.dspy import cfa_module_guard
+
+    @cfa_module_guard("classify transactions with PII protected",
+                       policy_bundle="prod-v1")
+    class TransactionClassifier(dspy.Module):
+        ...
+
+The decorator is equivalent to ``cfa.adapters.cfa_guard``.
+"""
+
+from __future__ import annotations
+
+from ..adapters import cfa_guard as _cfa_guard
+
+cfa_module_guard = _cfa_guard

cfa/adapters/langgraph.py

@@ -0,0 +1,19 @@
+"""LangGraph adapter — CFA governance for LangGraph agent nodes.
+
+CFA validates the node's declared intent before every invocation. Usage::
+
+    from cfa.adapters.langgraph import cfa_guard
+
+    @cfa_guard("aggregate sales with PII protected", policy_bundle="prod-v1")
+    def my_node(state: dict) -> dict:
+        ...
+
+The decorator works identically to ``cfa.adapters.cfa_guard``. It raises
+``PermissionError`` when the policy blocks the intent (``mode="block"``).
+"""
+
+from __future__ import annotations
+
+from ..adapters import cfa_guard as _cfa_guard
+
+cfa_guard = _cfa_guard

cfa/adapters/openai_agents.py

@@ -0,0 +1,19 @@
+"""OpenAI Agents SDK adapter — CFA governance for tool functions.
+
+Usage::
+
+    from cfa.adapters.openai_agents import cfa_tool_guard
+
+    @cfa_tool_guard("query customer data with PII masked", policy_bundle="prod-v1")
+    def query_customers(region: str) -> str:
+        ...
+
+The decorator is equivalent to ``cfa.adapters.cfa_guard``. Before every tool
+call, CFA validates the declared intent against the active policy bundle.
+"""
+
+from __future__ import annotations
+
+from ..adapters import cfa_guard as _cfa_guard
+
+cfa_tool_guard = _cfa_guard

cfa/audit/__init__.py

@@ -0,0 +1,15 @@
+"""CFA Audit — trail, context, and hashing."""
+from cfa._lazy import LazyLoader
+
+__getattr__ = LazyLoader({
+    "AuditTrail": ("cfa.audit.trail", "AuditTrail"),
+    "AuditEvent": ("cfa.audit.trail", "AuditEvent"),
+    "AuditStorageBackend": ("cfa.audit.trail", "AuditStorageBackend"),
+    "InMemoryAuditStorage": ("cfa.audit.trail", "InMemoryAuditStorage"),
+    "JsonLinesAuditStorage": ("cfa.audit.trail", "JsonLinesAuditStorage"),
+    "ContextRegistry": ("cfa.audit.context", "ContextRegistry"),
+    "InMemoryContextStorage": ("cfa.audit.context", "InMemoryContextStorage"),
+    "JsonFileContextStorage": ("cfa.audit.context", "JsonFileContextStorage"),
+    "hash_governance_artifact": ("cfa.audit.hashing", "hash_governance_artifact"),
+    "hash_file_content": ("cfa.audit.hashing", "hash_file_content"),
+})

cfa/audit/context.py

@@ -0,0 +1,205 @@
+"""
+CFA Context Registry
+====================
+Live model of the environment state.
+Not an execution log — represents "what state is the data in right now".
+
+Phase 1: in-memory implementation.
+Phase 4: persistent backend (JSON file) + snapshot versioning.
+
+The Context Registry is consulted before every intent (Invariant I3)
+and updated after every execution (Invariant I4).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from cfa.types import _utcnow
+
+# ── Storage Backend ─────────────────────────────────────────────────────────
+
+
+class ContextStorageBackend(ABC):
+    """Extension point: pluggable persistence for the Context Registry."""
+
+    @abstractmethod
+    def load(self) -> dict[str, Any]:
+        """Load full state from storage. Returns empty dict if no state exists."""
+        ...
+
+    @abstractmethod
+    def save(self, state: dict[str, Any]) -> None:
+        """Persist full state to storage."""
+        ...
+
+    @abstractmethod
+    def save_snapshot(self, version_id: str, state: dict[str, Any]) -> None:
+        """Save a versioned snapshot (Invariant I8 — reproducibility)."""
+        ...
+
+    @abstractmethod
+    def load_snapshot(self, version_id: str) -> dict[str, Any] | None:
+        """Load a specific snapshot by version_id."""
+        ...
+
+    @abstractmethod
+    def list_snapshots(self) -> list[str]:
+        """List all available snapshot version_ids."""
+        ...
+
+
+class InMemoryContextStorage(ContextStorageBackend):
+    """In-memory storage for testing."""
+
+    def __init__(self) -> None:
+        self._state: dict[str, Any] = {}
+        self._snapshots: dict[str, dict[str, Any]] = {}
+
+    def load(self) -> dict[str, Any]:
+        return dict(self._state)
+
+    def save(self, state: dict[str, Any]) -> None:
+        self._state = dict(state)
+
+    def save_snapshot(self, version_id: str, state: dict[str, Any]) -> None:
+        self._snapshots[version_id] = dict(state)
+
+    def load_snapshot(self, version_id: str) -> dict[str, Any] | None:
+        return self._snapshots.get(version_id)
+
+    def list_snapshots(self) -> list[str]:
+        return list(self._snapshots.keys())
+
+
+class JsonFileContextStorage(ContextStorageBackend):
+    """
+    JSON file-based persistent storage.
+    - Current state: {base_path}/context_state.json
+    - Snapshots: {base_path}/snapshots/{version_id}.json
+    """
+
+    def __init__(self, base_path: str | Path) -> None:
+        self.base_path = Path(base_path)
+        self.base_path.mkdir(parents=True, exist_ok=True)
+        self._snapshots_dir = self.base_path / "snapshots"
+        self._snapshots_dir.mkdir(exist_ok=True)
+
+    def _state_file(self) -> Path:
+        return self.base_path / "context_state.json"
+
+    def load(self) -> dict[str, Any]:
+        path = self._state_file()
+        if not path.exists():
+            return {}
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def save(self, state: dict[str, Any]) -> None:
+        self._state_file().write_text(
+            json.dumps(state, indent=2, default=str), encoding="utf-8"
+        )
+
+    def save_snapshot(self, version_id: str, state: dict[str, Any]) -> None:
+        path = self._snapshots_dir / f"{version_id}.json"
+        path.write_text(json.dumps(state, indent=2, default=str), encoding="utf-8")
+
+    def load_snapshot(self, version_id: str) -> dict[str, Any] | None:
+        path = self._snapshots_dir / f"{version_id}.json"
+        if not path.exists():
+            return None
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def list_snapshots(self) -> list[str]:
+        return sorted(p.stem for p in self._snapshots_dir.glob("*.json"))
+
+
+# ── Context Registry ────────────────────────────────────────────────────────
+
+
+@dataclass
+class ContextRegistry:
+    """
+    Context Registry for the CFA Kernel.
+
+    Consulted by the Intent Normalizer before every intent (Invariant I3).
+    Updated by the State Projection Protocol after every execution (Invariant I4).
+
+    Supports pluggable persistence backends and snapshot versioning.
+    """
+
+    _datasets: dict[str, dict[str, Any]] = field(default_factory=dict)
+    _execution_history: list[dict[str, Any]] = field(default_factory=list)
+    _version_id: str = "v_initial"
+    _storage: ContextStorageBackend = field(default_factory=InMemoryContextStorage)
+
+    def __post_init__(self) -> None:
+        # Try to restore from persistent storage
+        saved = self._storage.load()
+        if saved:
+            self._datasets = saved.get("datasets", {})
+            self._execution_history = saved.get("execution_history", [])
+            self._version_id = saved.get("version_id", self._version_id)
+
+    @property
+    def version_id(self) -> str:
+        return self._version_id
+
+    def get_environment_state(self) -> dict[str, Any]:
+        return {
+            "datasets": dict(self._datasets),
+            "execution_history": list(self._execution_history),
+            "version_id": self._version_id,
+        }
+
+    def get_dataset_state(self, name: str) -> dict[str, Any] | None:
+        return self._datasets.get(name)
+
+    def set_dataset_state(self, name: str, state: dict[str, Any]) -> None:
+        self._datasets[name] = state
+        self._bump_version()
+        self._persist()
+
+    def record_execution(
+        self, intent_id: str, outcome: str, signature_hash: str
+    ) -> None:
+        self._execution_history.append(
+            {
+                "intent_id": intent_id,
+                "outcome": outcome,
+                "signature_hash": signature_hash,
+                "timestamp": _utcnow().isoformat(),
+                "version_id": self._version_id,
+            }
+        )
+        self._persist()
+
+    def snapshot(self) -> str:
+        """Create a versioned snapshot of the current state (Invariant I8)."""
+        state = self.get_environment_state()
+        self._storage.save_snapshot(self._version_id, state)
+        return self._version_id
+
+    def restore_snapshot(self, version_id: str) -> bool:
+        """Restore state from a specific snapshot. Returns False if not found."""
+        saved = self._storage.load_snapshot(version_id)
+        if saved is None:
+            return False
+        self._datasets = saved.get("datasets", {})
+        self._execution_history = saved.get("execution_history", [])
+        self._version_id = saved.get("version_id", version_id)
+        self._persist()
+        return True
+
+    def list_snapshots(self) -> list[str]:
+        return self._storage.list_snapshots()
+
+    def _bump_version(self) -> None:
+        self._version_id = f"v_{uuid.uuid4().hex[:8]}"
+
+    def _persist(self) -> None:
+        self._storage.save(self.get_environment_state())

cfa/audit/hashing.py

@@ -0,0 +1,41 @@
+"""Deterministic content-addressable hashing for CFA governance artifacts.
+
+Every artifact that participates in a governed decision (catalog, policy bundle,
+signature) MUST be hashable so the audit trail can cryptographically bind a
+decision to its exact inputs.
+
+Hashes are computed on canonical JSON serializations of the artifact data,
+ensuring the same content always produces the same hash regardless of formatting
+or field order in the original YAML/JSON file.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def hash_governance_artifact(data: dict[str, Any] | None) -> str:
+    """Return a deterministic SHA-256 hash for a governance artifact.
+
+    The artifact is serialized to JSON with sorted keys so that the same logical
+    content always produces the same hash.
+
+    Returns an empty string when data is None.
+    """
+    if data is None:
+        return ""
+    canonical = json.dumps(data, sort_keys=True, default=str, ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def hash_file_content(path: str) -> str:
+    """Return the SHA-256 hash of a file's raw content.
+
+    Unlike ``hash_governance_artifact`` this hashes the bytes on disk, which is
+    useful for verifying that a file has not changed even if its logical content
+    (after parsing) is identical.
+    """
+    with open(path, "rb") as f:
+        return hashlib.sha256(f.read()).hexdigest()