continuum-toolkit 1.0.0__py3-none-any.whl

core/enums.py

@@ -0,0 +1,130 @@
+"""
+Project Continuum - Canonical Enums and Ontological Types
+=========================================================
+Defines the core enumerations, evidence types, evidence hierarchy levels,
+status states, node types, and relationship types across the system.
+"""
+
+from enum import Enum, IntEnum, auto
+
+
+class Status(str, Enum):
+    """
+    Standard status system used across all entities in Project Continuum.
+    Represents the verified lifecycle state of components, tasks, and requirements.
+    """
+    PENDING = "PENDING"
+    IN_PROGRESS = "IN_PROGRESS"
+    PARTIAL = "PARTIAL"
+    VERIFIED = "VERIFIED"
+    UNVERIFIED = "UNVERIFIED"
+    BLOCKED = "BLOCKED"
+    FAILED = "FAILED"
+    STALE = "STALE"
+    UNKNOWN = "UNKNOWN"
+
+    @classmethod
+    def is_terminal_success(cls, status: "Status") -> bool:
+        return status == cls.VERIFIED
+
+    @classmethod
+    def is_actionable(cls, status: "Status") -> bool:
+        return status in {cls.PENDING, cls.IN_PROGRESS, cls.PARTIAL, cls.BLOCKED, cls.FAILED, cls.STALE}
+
+
+class EvidenceType(str, Enum):
+    """
+    Canonical types of evidence harvested from the workspace, environment,
+    verification pipelines, or conversations.
+    """
+    SOURCE_CODE = "SOURCE_CODE"
+    AST_SYMBOL = "AST_SYMBOL"
+    GIT_COMMIT = "GIT_COMMIT"
+    GIT_DIFF = "GIT_DIFF"
+    GIT_STATUS = "GIT_STATUS"
+    TEST_RUN = "TEST_RUN"
+    BUILD_LOG = "BUILD_LOG"
+    CONFIG_FILE = "CONFIG_FILE"
+    DOCUMENTATION = "DOCUMENTATION"
+    RUNTIME_LOG = "RUNTIME_LOG"
+    CONVERSATION_ASSERTION = "CONVERSATION_ASSERTION"
+    USER_REQUIREMENT = "USER_REQUIREMENT"
+    AGENT_CLAIM = "AGENT_CLAIM"
+
+
+class EvidenceLevel(IntEnum):
+    """
+    The Evidence Hierarchy Matrix:
+    Strict seniority ranking for truth arbitration.
+    Lower numerical value indicates HIGHER priority / ground truth authority.
+    
+    Level 1: Runtime status & automated test execution exit codes (Highest)
+    Level 2: AST structure, symbol exports, and physical source files
+    Level 3: Git working tree diffs, staged index, and commit history
+    Level 4: Architecture documentation, inline comments, and READMEs
+    Level 5: Conversational statements and agent assertions (Lowest)
+    """
+    LEVEL_1_RUNTIME_TEST = 1
+    LEVEL_2_CODE_AST = 2
+    LEVEL_3_GIT_STATE = 3
+    LEVEL_4_DOCUMENTATION = 4
+    LEVEL_5_CONVERSATION = 5
+
+    @classmethod
+    def get_level_for_type(cls, evidence_type: EvidenceType) -> "EvidenceLevel":
+        """Maps an evidence type to its fundamental hierarchy seniority level."""
+        mapping = {
+            EvidenceType.TEST_RUN: cls.LEVEL_1_RUNTIME_TEST,
+            EvidenceType.BUILD_LOG: cls.LEVEL_1_RUNTIME_TEST,
+            EvidenceType.RUNTIME_LOG: cls.LEVEL_1_RUNTIME_TEST,
+            EvidenceType.SOURCE_CODE: cls.LEVEL_2_CODE_AST,
+            EvidenceType.AST_SYMBOL: cls.LEVEL_2_CODE_AST,
+            EvidenceType.CONFIG_FILE: cls.LEVEL_2_CODE_AST,
+            EvidenceType.GIT_COMMIT: cls.LEVEL_3_GIT_STATE,
+            EvidenceType.GIT_DIFF: cls.LEVEL_3_GIT_STATE,
+            EvidenceType.GIT_STATUS: cls.LEVEL_3_GIT_STATE,
+            EvidenceType.DOCUMENTATION: cls.LEVEL_4_DOCUMENTATION,
+            EvidenceType.CONVERSATION_ASSERTION: cls.LEVEL_5_CONVERSATION,
+            EvidenceType.USER_REQUIREMENT: cls.LEVEL_5_CONVERSATION,
+            EvidenceType.AGENT_CLAIM: cls.LEVEL_5_CONVERSATION,
+        }
+        return mapping.get(evidence_type, cls.LEVEL_5_CONVERSATION)
+
+
+class NodeType(str, Enum):
+    """
+    Types of entities present in the Canonical State Graph (DAG).
+    """
+    MILESTONE = "MILESTONE"
+    PHASE = "PHASE"
+    REQUIREMENT = "REQUIREMENT"
+    MODULE = "MODULE"
+    SERVICE = "SERVICE"
+    API = "API"
+    TASK = "TASK"
+    TEST = "TEST"
+    COMPONENT = "COMPONENT"
+
+
+class RelationType(str, Enum):
+    """
+    Directed relationship types connecting nodes in the Canonical State Graph.
+    """
+    DEPENDS_ON = "DEPENDS_ON"
+    IMPLEMENTS = "IMPLEMENTS"
+    VERIFIES = "VERIFIES"
+    BLOCKS = "BLOCKS"
+    IMPORTS = "IMPORTS"
+    REQUIRES = "REQUIRES"
+    INVALIDATES = "INVALIDATES"
+
+
+class TargetModel(str, Enum):
+    """
+    Target AI model families supported by specialized handoff adapters.
+    """
+    CLAUDE = "CLAUDE"
+    CODEX_GPT = "CODEX_GPT"
+    GEMINI = "GEMINI"
+    LOCAL_LLM = "LOCAL_LLM"
+    UNIVERSAL = "UNIVERSAL"

core/evidence.py

@@ -0,0 +1,117 @@
+"""
+Project Continuum - Canonical Evidence Model & Provenance
+=========================================================
+Implements the canonical Evidence data structure used by every extractor
+and resolver across Project Continuum.
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+import hashlib
+import json
+from typing import Any, Dict, List, Optional
+import uuid
+
+from core.enums import EvidenceType, EvidenceLevel
+
+
+@dataclass
+class EvidenceProvenance:
+    """
+    Detailed audit trace explaining how and where evidence was obtained.
+    """
+    extractor_name: str
+    source_uri: str
+    locator: str  # e.g., "line:42-88", "symbol:AuthService.verify", "git:a1b2c3d", "turn:4"
+    collected_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    environment_info: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "EvidenceProvenance":
+        return cls(
+            extractor_name=data.get("extractor_name", "unknown_extractor"),
+            source_uri=data.get("source_uri", ""),
+            locator=data.get("locator", ""),
+            collected_at=data.get("collected_at", datetime.now(timezone.utc).isoformat()),
+            environment_info=data.get("environment_info", {})
+        )
+
+
+@dataclass
+class Evidence:
+    """
+    The canonical unit of proof in Project Continuum.
+    Every conclusion, confidence score, and status assessment must be grounded
+    in verifiable Evidence records.
+    """
+    id: str = field(default_factory=lambda: f"ev_{uuid.uuid4().hex[:12]}")
+    type: EvidenceType = EvidenceType.SOURCE_CODE
+    level: EvidenceLevel = EvidenceLevel.LEVEL_2_CODE_AST
+    raw_payload: Dict[str, Any] = field(default_factory=dict)
+    summary: str = ""
+    provenance: Optional[EvidenceProvenance] = None
+    checksum: str = ""
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        # Normalize types if strings were passed
+        if isinstance(self.type, str):
+            self.type = EvidenceType(self.type)
+        if isinstance(self.level, int) and not isinstance(self.level, EvidenceLevel):
+            self.level = EvidenceLevel(self.level)
+        elif self.level is None:
+            self.level = EvidenceLevel.get_level_for_type(self.type)
+
+        # Auto-calculate checksum of raw_payload if empty
+        if not self.checksum:
+            self.checksum = self.calculate_checksum()
+
+    def calculate_checksum(self) -> str:
+        """Calculates deterministic SHA-256 hash of the evidence payload & summary."""
+        normalized_dict = {
+            "type": self.type.value if hasattr(self.type, "value") else str(self.type),
+            "summary": self.summary,
+            "raw_payload": self.raw_payload,
+            "provenance": self.provenance.to_dict() if self.provenance else None
+        }
+        serialized = json.dumps(normalized_dict, sort_keys=True, default=str)
+        return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+    def verify_integrity(self) -> bool:
+        """Checks if current payload matches recorded checksum."""
+        return self.checksum == self.calculate_checksum()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "type": self.type.value,
+            "level": int(self.level.value),
+            "summary": self.summary,
+            "raw_payload": self.raw_payload,
+            "provenance": self.provenance.to_dict() if self.provenance else None,
+            "checksum": self.checksum,
+            "created_at": self.created_at,
+            "metadata": self.metadata
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Evidence":
+        ev_type = EvidenceType(data["type"])
+        ev_level = EvidenceLevel(data.get("level", EvidenceLevel.get_level_for_type(ev_type).value))
+        provenance = EvidenceProvenance.from_dict(data["provenance"]) if data.get("provenance") else None
+
+        return cls(
+            id=data.get("id", f"ev_{uuid.uuid4().hex[:12]}"),
+            type=ev_type,
+            level=ev_level,
+            summary=data.get("summary", ""),
+            raw_payload=data.get("raw_payload", {}),
+            provenance=provenance,
+            checksum=data.get("checksum", ""),
+            created_at=data.get("created_at", datetime.now(timezone.utc).isoformat()),
+            metadata=data.get("metadata", {})
+        )

core/interfaces.py

@@ -0,0 +1,209 @@
+"""
+Project Continuum - Architectural Interfaces and Contracts
+===========================================================
+Defines the abstract Protocols / Interfaces for all major subsystems
+across Project Continuum:
+1. IEvidenceExtractor (Phases 1-5)
+2. IEvidenceResolver (Phase 6)
+3. IContradictionDetector (Phase 7)
+4. IConfidenceCalculator (Phase 8)
+5. IStateGraphManager (Phases 9-11)
+6. IContextSelector (Phases 12-13)
+7. IModelAdapter (Phases 14-15)
+"""
+
+from typing import Any, Dict, List, Optional, Protocol, Tuple, runtime_checkable
+
+from core.enums import EvidenceType, Status, TargetModel
+from core.evidence import Evidence
+from core.state_models import (
+    CanonicalProjectState,
+    ContradictionRecord,
+    GraphEdge,
+    GraphNode,
+    ProjectState,
+    ConversationalState,
+    AgentExecutionState
+)
+
+
+# ==============================================================================
+# 1. EVIDENCE EXTRACTOR INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IEvidenceExtractor(Protocol):
+    """
+    Contract implemented by all evidence extractors (Workspace/AST, Config,
+    Git, Verification/Tests, Conversation).
+    """
+    @property
+    def extractor_name(self) -> str:
+        """Unique identifier for this extractor."""
+        ...
+
+    @property
+    def supported_evidence_types(self) -> List[EvidenceType]:
+        """Evidence types this extractor produces."""
+        ...
+
+    def can_extract(self, target_path_or_input: str) -> bool:
+        """Determines if this extractor is applicable to the target."""
+        ...
+
+    def extract(self, target_path_or_input: str, context: Optional[Dict[str, Any]] = None) -> List[Evidence]:
+        """Harvests verifiable evidence from the target."""
+        ...
+
+
+# ==============================================================================
+# 2. EVIDENCE RESOLUTION INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IEvidenceResolver(Protocol):
+    """
+    Contract for arbitrating conflicting evidence according to the Evidence Hierarchy Matrix.
+    """
+    def resolve_status(
+        self,
+        target_id: str,
+        evidence_list: List[Evidence],
+        claims: Optional[List[Dict[str, Any]]] = None
+    ) -> Tuple[Status, Optional[Evidence], str]:
+        """
+        Resolves candidate evidence into a final status.
+        Returns (Status, WinningEvidence, RationaleExplanation).
+        """
+        ...
+
+
+# ==============================================================================
+# 3. CONTRADICTION DETECTOR INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IContradictionDetector(Protocol):
+    """
+    Contract for finding mismatches between claims/docs and physical reality.
+    """
+    def detect_contradictions(
+        self,
+        project_state: ProjectState,
+        conversational_state: ConversationalState,
+        evidence_pool: Dict[str, Evidence]
+    ) -> List[ContradictionRecord]:
+        """Analyzes all state dimensions and returns detected contradictions."""
+        ...
+
+
+# ==============================================================================
+# 4. CONFIDENCE CALCULATOR INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IConfidenceCalculator(Protocol):
+    """
+    Contract for calculating explainable confidence scores (0.0% to 100.0%)
+    grounded in physical proof and capped by contradictions.
+    """
+    def calculate_node_confidence(
+        self,
+        node: GraphNode,
+        evidence_pool: Dict[str, Evidence],
+        contradictions: List[ContradictionRecord]
+    ) -> Tuple[float, Dict[str, Any]]:
+        """
+        Calculates confidence score for a node and returns (Score, ExplanationDict).
+        """
+        ...
+
+    def calculate_project_confidence(
+        self,
+        canonical_state: CanonicalProjectState
+    ) -> Tuple[float, Dict[str, Any]]:
+        """Calculates global aggregate project confidence."""
+        ...
+
+
+# ==============================================================================
+# 5. STATE GRAPH MANAGER INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IStateGraphManager(Protocol):
+    """
+    Contract for managing the Directed Acyclic Graph (DAG) of the project.
+    """
+    def add_node(self, node: GraphNode) -> None:
+        ...
+
+    def add_edge(self, edge: GraphEdge) -> None:
+        ...
+
+    def get_dependencies(self, node_id: str, recursive: bool = False) -> List[GraphNode]:
+        ...
+
+    def get_dependents(self, node_id: str, recursive: bool = False) -> List[GraphNode]:
+        ...
+
+    def detect_cycles(self) -> List[List[str]]:
+        ...
+
+    def propagate_invalidation(self, changed_node_id: str) -> List[str]:
+        """Marks downstream dependent nodes STALE or BLOCKED and returns affected IDs."""
+        ...
+
+    def export_mermaid(self) -> str:
+        """Generates Mermaid diagram string representing the DAG."""
+        ...
+
+
+# ==============================================================================
+# 6. CONTEXT SELECTOR INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IContextSelector(Protocol):
+    """
+    Contract for pruning unnecessary context and extracting the targeted subgraph
+    for the next task.
+    """
+    def select_context_for_task(
+        self,
+        task_description: str,
+        canonical_state: CanonicalProjectState,
+        token_budget: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Returns targeted subgraph, relevant files, test references, constraints,
+        and an audit of omitted items.
+        """
+        ...
+
+
+# ==============================================================================
+# 7. MODEL ADAPTER INTERFACE
+# ==============================================================================
+
+@runtime_checkable
+class IModelAdapter(Protocol):
+    """
+    Contract for generating model-specific handoff packages (Claude, Codex, Gemini, Local).
+    """
+    @property
+    def target_model(self) -> TargetModel:
+        ...
+
+    def generate_handoff(
+        self,
+        canonical_state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, str]:
+        """
+        Synthesizes the handoff files:
+        - "handoff.md": continuation briefing
+        - "project-context.md": architectural narrative
+        - "project-state.json": machine-readable payload
+        """
+        ...