dir-core 0.1.0__py3-none-any.whl

dir_core/__init__.py

@@ -0,0 +1,270 @@
+"""
+Decision Intelligence Runtime (DIR) - core package for ROA/DIR.
+
+Core components: DFID, EventBus, DIM, Context Store, models, pluggable storage.
+
+Install::
+
+    pip install dir-runtime
+
+Custom storage backend example::
+
+    from dir_core import AgentRegistry
+    from dir_core.storage import AgentRegistryStorage
+
+    class MyPostgresStorage:
+        def init_schema(self) -> None: ...
+        def upsert_agent(self, agent_id, contract_json, priority,
+                         status, agent_version, session_token) -> None: ...
+        # implement remaining AgentRegistryStorage methods
+
+    registry = AgentRegistry(storage=MyPostgresStorage())
+"""
+
+from .agent_registry import AgentRegistry, HandshakeResult
+from .arbitration import DEFAULT_PRIORITY_MATRIX, select_winner
+from .dim import validate_proposal
+from .data_types import (
+    AgentRegistryStatus,
+    ContractRole,
+    DecisionFlowStatus,
+    DecisionRecordOutcome,
+    DimReasonCode,
+    EscalationSeverity,
+    EventBusBackend,
+    EventType,
+    FlowTimelineEventType,
+    HandshakeRejectionReason,
+    HumanDecision,
+    ValidationReason,
+    ValidationResult,
+    ValidationVerdict,
+)
+from .context_store import ContextStore
+from .runtime import DecisionRuntime
+from .dfid import new_dfid, new_dfid_with_parent
+from .event_bus import (
+    Event,
+    EventBus,
+    EventMetadata,
+    LoggingEventBus,
+    create_event_bus,
+)
+from .escalation import (
+    EscalationManager,
+    EscalationOutcome,
+    ImpactCategory,
+)
+from .idempotency import (
+    IdempotencyGuard,
+    MemoryBackend,
+    SQLiteBackend,
+    idempotency_key,
+)
+from .intent_retry import REASONING_EXHAUSTION, IntentRetryGovernor
+from .lifecycle import FlowStatus, transition
+from .resource_lock import LockResult, ResourceLockManager
+from .jit import JITStateVerifier, verify_drift
+from .ledger import DecisionLedger
+from .models import (
+    AgentState,
+    ContextSnapshot,
+    DecisionAtom,
+    DecisionFlow,
+    DecisionRecord,
+    EscalationRequest,
+    ExecutionIntent,
+    ExplainResult,
+    FlowEvent,
+    Policy,
+    PolicyProposal,
+    ProofCarryingIntent,
+    CompensationAction,
+    ResponsibilityContract,
+    SelfCheckResult,
+)
+from .saga import SagaCompensation
+from .pci import (
+    ProofChecker,
+    compute_evidence_hash,
+    hash_content,
+    proposal_params_for_hash,
+)
+from .wakeup import (
+    WakeupPredicate,
+    is_relevant_instrument,
+    price_change_significant,
+    should_wake,
+    volatility_elevated,
+)
+
+# Storage layer - protocols and built-in backends
+from .storage import (
+    # Protocols (implement these to create a custom backend)
+    AgentRegistryStorage,
+    AuditStore,
+    ContextStorage,
+    DecisionAuditStorage,
+    IdempotencyStorage,
+    SagaStorage,
+    ResourceLockStorage,
+    IntentRetryStorage,
+    EscalationStorage,
+    LifecycleStorage,
+    # Exceptions
+    StorageError,
+    ResourceContentionError,
+    # SQLite backends (default, no extra deps)
+    SqliteAgentRegistryStorage,
+    SqliteContextStorage,
+    SqliteDecisionAuditStorage,
+    SqliteIdempotencyStorage,
+    SqliteSagaStorage,
+    SqliteResourceLockStorage,
+    SqliteIntentRetryStorage,
+    SqliteEscalationStorage,
+    SqliteLifecycleStorage,
+    # Memory backends (testing / ephemeral)
+    MemoryAgentRegistryStorage,
+    MemoryContextStorage,
+    MemoryDecisionAuditStorage,
+    MemoryIdempotencyStorage,
+    MemorySagaStorage,
+    MemoryResourceLockStorage,
+    MemoryIntentRetryStorage,
+    MemoryEscalationStorage,
+    MemoryLifecycleStorage,
+    # Bundles & factories
+    StorageBundle,
+    sqlite_storage,
+    memory_storage,
+)
+
+__all__ = [
+    "DEFAULT_PRIORITY_MATRIX",
+    # DIM (DIR ?6)
+    "validate_proposal",
+    "ValidationVerdict",
+    "ValidationResult",
+    "ValidationReason",
+    "DimReasonCode",
+    "ContractRole",
+    "DecisionRecordOutcome",
+    "EscalationSeverity",
+    "FlowTimelineEventType",
+    "DecisionFlowStatus",
+    "HumanDecision",
+    "AgentRegistryStatus",
+    "HandshakeRejectionReason",
+    "EventBusBackend",
+    "new_dfid",
+    "new_dfid_with_parent",
+    "select_winner",
+    # EventBus (DIR Topologies ?2)
+    "Event",
+    "EventBus",
+    "EventMetadata",
+    "EventType",
+    "LoggingEventBus",
+    "create_event_bus",
+    # EOAM (Topologies ?2)
+    "WakeupPredicate",
+    "price_change_significant",
+    "volatility_elevated",
+    "is_relevant_instrument",
+    "should_wake",
+    # DL+PCI (Topology C)
+    "ProofCarryingIntent",
+    "DecisionLedger",
+    "compute_evidence_hash",
+    "hash_content",
+    "proposal_params_for_hash",
+    "ProofChecker",
+    # Intent Retry Governor (DIR ?6.2)
+    "IntentRetryGovernor",
+    "REASONING_EXHAUSTION",
+    # Lifecycle (DIR ?4.3)
+    "FlowStatus",
+    "transition",
+    # Escalation Manager (DIR ?9)
+    "EscalationManager",
+    "EscalationOutcome",
+    "ImpactCategory",
+    # Resource Locking (DIR ?6.2)
+    "ResourceLockManager",
+    "LockResult",
+    # Agent Registry (DIR ?2.3)
+    "AgentRegistry",
+    "HandshakeResult",
+    # Context Store (DIR ?8)
+    "ContextStore",
+    # Facade (DX)
+    "DecisionRuntime",
+    # Idempotency (DIR ?7)
+    "IdempotencyGuard",
+    "idempotency_key",
+    "SQLiteBackend",
+    "MemoryBackend",
+    # Saga Compensation (DIR ?7)
+    "SagaCompensation",
+    "CompensationAction",
+    # SDS (Topology B)
+    "DecisionAtom",
+    "JITStateVerifier",
+    "verify_drift",
+    # Core models
+    "ResponsibilityContract",
+    "PolicyProposal",
+    "ExecutionIntent",
+    # ROA Lifecycle models
+    "ExplainResult",
+    "Policy",
+    "SelfCheckResult",
+    # Agent state
+    "AgentState",
+    "DecisionRecord",
+    "EscalationRequest",
+    # DecisionFlow (DIR ?5.4)
+    "DecisionFlow",
+    "ContextSnapshot",
+    "FlowEvent",
+    # Storage layer - protocols
+    "AgentRegistryStorage",
+    "AuditStore",
+    "ContextStorage",
+    "DecisionAuditStorage",
+    "IdempotencyStorage",
+    "SagaStorage",
+    "ResourceLockStorage",
+    "IntentRetryStorage",
+    "EscalationStorage",
+    "LifecycleStorage",
+    "StorageError",
+    "ResourceContentionError",
+    # Storage layer - SQLite backends
+    "SqliteAgentRegistryStorage",
+    "SqliteContextStorage",
+    "SqliteDecisionAuditStorage",
+    "SqliteIdempotencyStorage",
+    "SqliteSagaStorage",
+    "SqliteResourceLockStorage",
+    "SqliteIntentRetryStorage",
+    "SqliteEscalationStorage",
+    "SqliteLifecycleStorage",
+    # Storage layer - memory backends
+    "MemoryAgentRegistryStorage",
+    "MemoryContextStorage",
+    "MemoryDecisionAuditStorage",
+    "MemoryIdempotencyStorage",
+    "MemorySagaStorage",
+    "MemoryResourceLockStorage",
+    "MemoryIntentRetryStorage",
+    "MemoryEscalationStorage",
+    "MemoryLifecycleStorage",
+    # Storage bundles & factories
+    "StorageBundle",
+    "sqlite_storage",
+    "memory_storage",
+]
+
+__version__ = "0.1.0"

dir_core/agent_registry.py

@@ -0,0 +1,209 @@
+"""
+Agent Registry: contract, handshake, lookup by agent_id.
+
+DIR §2.3. Maintains a registry of active agents, their capability contracts, and metadata.
+Handshake with SemVer alignment; schema serving for Context compilation.
+"""
+
+import json
+import re
+import uuid
+import logging
+import warnings
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .data_types import AgentRegistryStatus, HandshakeRejectionReason
+from .storage.base import AgentRegistryStorage
+from .storage.sqlite import SqliteAgentRegistryStorage
+
+logger = logging.getLogger(__name__)
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)(?:\.(\d+))?(?:[-+].*)?$")
+
+
+@dataclass
+class HandshakeResult:
+    """Result of agent handshake (DIR §2.3)."""
+
+    accepted: bool
+    session_token: Optional[str] = None
+    reason: Optional[str] = None
+
+
+def _parse_version(v: str) -> Optional[tuple]:
+    """Parse semver string to (major, minor, patch)."""
+    m = SEMVER_RE.match(v.strip())
+    if not m:
+        return None
+    major, minor, patch = int(m.group(1)), int(m.group(2)), int(m.group(3) or 0)
+    return (major, minor, patch)
+
+
+def _version_compatible(agent_ver: str, supported: str) -> bool:
+    """
+    Check if agent_ver is compatible with supported (e.g. "1.x" or "1.2").
+    """
+    av = _parse_version(agent_ver)
+    if not av:
+        return False
+    if supported.endswith(".x"):
+        prefix = supported[:-2]
+        sv = _parse_version(prefix + ".0")
+        if not sv:
+            return False
+        return av[0] == sv[0]
+    sv = _parse_version(supported)
+    if not sv:
+        return False
+    return av[0] == sv[0] and av[1] >= sv[1]
+
+
+class AgentRegistry:
+    """Registry of active agents with SemVer handshake (DIR §2.3).
+
+    Storage backend is pluggable. Pass ``storage=`` for a custom backend, or
+    ``db_path=`` to use the built-in SQLite backend (default behaviour).
+
+    Args:
+        db_path: Path to SQLite database. Used when ``storage`` is not provided.
+        supported_versions: SemVer constraint for handshake (e.g. ``"1.x"``).
+        storage: Custom :class:`~dir_core.storage.AgentRegistryStorage` backend.
+            When provided, ``db_path`` is ignored.
+
+    Raises:
+        ValueError: When neither ``db_path`` nor ``storage`` is supplied.
+    """
+
+    def __init__(
+        self,
+        db_path: Optional[str] = None,
+        supported_versions: str = "1.x",
+        *,
+        storage: Optional[AgentRegistryStorage] = None,
+    ):
+        self.supported_versions = supported_versions
+        if storage is not None:
+            self._storage: AgentRegistryStorage = storage
+        elif db_path is not None:
+            self.db_path = db_path  # kept for backward compatibility
+            self._storage = SqliteAgentRegistryStorage(db_path)
+        else:
+            raise ValueError(
+                "Provide either 'db_path' (SQLite) or 'storage' (custom backend)."
+            )
+
+    def handshake(
+        self,
+        agent_id: str,
+        contract: Dict[str, Any],
+        agent_version: str,
+        priority: int = 0,
+    ) -> HandshakeResult:
+        """
+        Handshake with version check. REJECT on VERSION_MISMATCH.
+        Returns ACCEPTED with session_token or REJECTED with reason.
+        """
+        if not _version_compatible(agent_version, self.supported_versions):
+            return HandshakeResult(
+                accepted=False,
+                reason=HandshakeRejectionReason.VERSION_MISMATCH.value,
+            )
+        token = str(uuid.uuid4())
+        self._storage.upsert_agent(
+            agent_id=agent_id,
+            contract_json=json.dumps(contract),
+            priority=priority,
+            status=AgentRegistryStatus.ACTIVE,
+            agent_version=agent_version,
+            session_token=token,
+        )
+        logger.info("Handshake: agent_id=%s ver=%s accepted", agent_id, agent_version)
+        return HandshakeResult(accepted=True, session_token=token)
+
+    def get_schema(
+        self, agent_id: str, schema_kind: Optional[str] = None
+    ) -> Optional[dict]:
+        """Return schema from contract: schema_kind=None -> contract['schema'];
+        else -> contract['schemas'][kind] or contract['schema']."""
+        contract = self.get_agent_contract(agent_id)
+        if not contract:
+            return None
+        if schema_kind is not None and "schemas" in contract and schema_kind in contract["schemas"]:
+            return contract["schemas"][schema_kind]
+        return contract.get("schema")
+
+    def register_agent(
+        self,
+        agent_id: str,
+        contract: Dict[str, Any],
+        priority: int = 0,
+    ) -> None:
+        """Register or update an agent with capability contract.
+
+        Deprecated: Use handshake() for version checking and session tokens (DIR §2.3).
+        register_agent does not enforce SemVer compatibility.
+        """
+        warnings.warn(
+            "register_agent is deprecated; use handshake() for version checking (DIR §2.3)",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self._storage.upsert_agent(
+            agent_id=agent_id,
+            contract_json=json.dumps(contract),
+            priority=priority,
+            status=AgentRegistryStatus.ACTIVE,
+            agent_version=None,
+            session_token=None,
+        )
+        logger.info("Registered agent: %s (priority=%d)", agent_id, priority)
+
+    def get_agent_contract(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Retrieve agent capability contract."""
+        rec = self._storage.get_agent(agent_id)
+        return rec["contract"] if rec else None
+
+    def get_agent_manifest(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Retrieve agent capability contract. Deprecated: use get_agent_contract."""
+        return self.get_agent_contract(agent_id)
+
+    def get_agent_priority(self, agent_id: str) -> int:
+        """Retrieve agent priority (default 0)."""
+        rec = self._storage.get_agent(agent_id)
+        return rec["priority"] if rec else 0
+
+    def list_agents(self) -> List[str]:
+        """List all active agent IDs."""
+        return self._storage.list_active_agents()
+
+    def set_agent_status(
+        self,
+        agent_id: str,
+        status: str,
+        suspension_reason: Optional[str] = None,
+    ) -> bool:
+        """
+        Transition agent lifecycle status (e.g. ACTIVE -> SUSPENDED).
+
+        Args:
+            agent_id: Registered agent identifier.
+            status: New status value (e.g. 'SUSPENDED', 'ACTIVE').
+            suspension_reason: Optional machine-oriented reason (audit / ops).
+
+        Returns:
+            True if a row was updated.
+        """
+        updated = self._storage.update_status(agent_id, status, suspension_reason)
+        if updated:
+            logger.info(
+                "Agent status: agent_id=%s status=%s reason=%s",
+                agent_id,
+                status,
+                suspension_reason,
+            )
+        return updated
+
+    def get_agent_status(self, agent_id: str) -> Optional[tuple]:
+        """Return (status, suspension_reason) if the agent exists, else None."""
+        return self._storage.get_status(agent_id)

dir_core/arbitration.py

@@ -0,0 +1,53 @@
+"""
+Priority-Based Arbitration (DIR Topologies §2.4).
+
+Selects the winning proposal from parallel agents using a priority matrix.
+Lower priority number = higher precedence (e.g. Risk > Strategy).
+"""
+
+from typing import Dict, List, Optional
+
+from .models import PolicyProposal
+
+DEFAULT_PRIORITY_MATRIX: Dict[str, int] = {
+    "RISK_ALERT": 1,
+    "CLOSE_LONG": 2,
+    "CLOSE": 2,
+    "OPEN_LONG": 3,
+    "TAKE_PROFIT": 3,
+    "ADJUST_STOP": 4,
+    "SENTIMENT_BULLISH": 4,
+    "SENTIMENT_BEARISH": 4,
+    "RISK_OK": 5,
+    "OPEN_POSITION": 5,
+    "NEWS_QUALIFIED": 6,
+    "SENTIMENT_NEUTRAL": 7,
+    "HOLD": 10,
+}
+
+
+def select_winner(
+    proposals: List[PolicyProposal],
+    priority_matrix: Optional[Dict[str, int]] = None,
+) -> Optional[PolicyProposal]:
+    """Select winning proposal using Priority Matrix (Topologies §2.4).
+
+    Lower priority number = higher precedence. If no matrix provided,
+    uses DEFAULT_PRIORITY_MATRIX. Unknown policy_kind gets priority 10.
+
+    Args:
+        proposals: List of policy proposals from parallel agents.
+        priority_matrix: Optional mapping policy_kind -> priority (lower = higher).
+
+    Returns:
+        The winning proposal, or None if proposals list is empty.
+    """
+    if not proposals:
+        return None
+
+    matrix = priority_matrix or DEFAULT_PRIORITY_MATRIX
+
+    def get_priority(p: PolicyProposal) -> int:
+        return matrix.get(p.policy_kind, 10)
+
+    return min(proposals, key=get_priority)

dir_core/context_store.py

@@ -0,0 +1,110 @@
+"""
+Context Store (DIR §8) - Manages multi-layered context for agents.
+
+Layers:
+1. Session (Ephemeral): Context specific to the current DecisionFlow (dfid).
+2. State (Authoritative): Long-lived agent state (policy versions, trajectory).
+3. Memory (Long-term): Vector DB or archival storage (Stub for MVP).
+4. Artifacts (Reference): Static docs/rules (Stub).
+
+Provides `compile_working_context` to assemble a frozen view for decision making.
+
+Implementation note: Memory and Artifacts layers are stubs (return {}).
+Full implementation requires: Memory (vector DB / archival), Artifacts (RAG / static docs).
+See DIR §8.1, ROA §7.2 for layer definitions.
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional
+
+from .storage.base import ContextStorage
+from .storage.sqlite import SqliteContextStorage
+
+logger = logging.getLogger(__name__)
+
+
+class ContextStore:
+    """Multi-layered context store for agent state (DIR §8).
+
+    Storage backend is pluggable. Pass ``storage=`` for a custom backend, or
+    ``db_path=`` to use the built-in SQLite backend (default behaviour).
+
+    Args:
+        db_path: Path to SQLite database. Used when ``storage`` is not provided.
+        storage: Custom :class:`~dir_core.storage.ContextStorage` backend.
+            When provided, ``db_path`` is ignored.
+
+    Raises:
+        ValueError: When neither ``db_path`` nor ``storage`` is supplied.
+    """
+
+    def __init__(
+        self,
+        db_path: Optional[str] = None,
+        *,
+        storage: Optional[ContextStorage] = None,
+    ):
+        if storage is not None:
+            self._storage: ContextStorage = storage
+        elif db_path is not None:
+            self.db_path = db_path  # kept for backward compatibility
+            self._storage = SqliteContextStorage(db_path)
+        else:
+            raise ValueError(
+                "Provide either 'db_path' (SQLite) or 'storage' (custom backend)."
+            )
+
+    # -------------------------------------------------------------------------
+    # Layer 1: Session (Ephemeral)
+    # -------------------------------------------------------------------------
+
+    def get_session(self, dfid: str) -> Dict[str, Any]:
+        raw = self._storage.get_session(dfid)
+        return json.loads(raw) if raw else {}
+
+    def update_session(self, dfid: str, updates: Dict[str, Any]) -> None:
+        """Merge updates into existing session."""
+        current = self.get_session(dfid)
+        current.update(updates)
+        self._storage.set_session(dfid, json.dumps(current))
+
+    # -------------------------------------------------------------------------
+    # Layer 2: State (Authoritative)
+    # -------------------------------------------------------------------------
+
+    def get_state(self, agent_id: str) -> Dict[str, Any]:
+        raw = self._storage.get_state(agent_id)
+        return json.loads(raw) if raw else {}
+
+    def update_state(self, agent_id: str, updates: Dict[str, Any]) -> None:
+        """Merge updates into existing state."""
+        current = self.get_state(agent_id)
+        current.update(updates)
+        self._storage.set_state(agent_id, json.dumps(current))
+
+    # -------------------------------------------------------------------------
+    # Compiler
+    # -------------------------------------------------------------------------
+
+    def compile_working_context(self, agent_id: str, dfid: str) -> Dict[str, Any]:
+        """
+        Assemble all layers into a single Working Context.
+        Returns immutable dictionary (snapshot).
+        """
+        session_data = self.get_session(dfid)
+        state_data = self.get_state(agent_id)
+
+        # In a real system, we'd fetch Memory and Artifacts here too.
+
+        return {
+            "meta": {
+                "agent_id": agent_id,
+                "dfid": dfid,
+                "source": "ContextStore",
+            },
+            "session": session_data,
+            "state": state_data,
+            "memory": {},    # Stub
+            "artifacts": {}  # Stub
+        }