cognitive-engine 0.2.0__py3-none-any.whl

cognitive_engine/core/types.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+import torch
+
+
+@dataclass
+class ProcessedInput:
+    raw_input: Any
+    modality: str
+    normalized_text: str = ""
+    tokens: List[str] = field(default_factory=list)
+    token_tensor: Optional[torch.Tensor] = None
+    attention_mask: Optional[torch.Tensor] = None
+    numeric_tensor: Optional[torch.Tensor] = None
+    operation: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SemanticConcept:
+    label: str
+    weight: float
+    source: str
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SemanticState:
+    raw_input: Any
+    modality: str
+    sequence_embedding: Optional[torch.Tensor]
+    pooled_embedding: torch.Tensor
+    intent: str
+    entities: List[str]
+    concepts: List[SemanticConcept]
+    concept_graph_edges: List[Tuple[str, str, float]]
+    compressed_context: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ImportanceAssessment:
+    novelty: float
+    utility: float
+    frequency: float
+    coherence: float
+    correction_signal: float
+    redundancy: float
+    future_relevance: float
+    contradiction_risk: float
+    importance_score: float
+    confidence_score: float
+    learning_priority: float
+    action: str
+    rationale: str
+
+
+@dataclass
+class CompressedKnowledge:
+    record_id: str
+    source_type: str
+    summary: str
+    concepts: List[str]
+    relations: List[Tuple[str, str, str]]
+    embedding: np.ndarray
+    importance: float
+    confidence: float
+    provenance: Dict[str, Any]
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    reinforced_count: int = 1
+
+
+@dataclass
+class MemoryQuery:
+    embedding: np.ndarray
+    top_k: int = 5
+    modality: Optional[str] = None
+    intent: Optional[str] = None
+    concepts: List[str] = field(default_factory=list)
+
+
+@dataclass
+class MemoryBundle:
+    short_term: List[CompressedKnowledge] = field(default_factory=list)
+    working_memory: Dict[str, Any] = field(default_factory=dict)
+    semantic_long_term: List[CompressedKnowledge] = field(default_factory=list)
+    episodic: List[CompressedKnowledge] = field(default_factory=list)
+
+
+@dataclass
+class RoutingDecision:
+    active_modules: List[str]
+    consult_memories: List[str]
+    update_memory: bool
+    engage_plasticity: bool
+    compute_budget: float
+    rationale: str
+
+
+@dataclass
+class CoreInference:
+    prediction: Any
+    confidence: float
+    explanation: str
+    hidden_state: Optional[torch.Tensor] = None
+    artifacts: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ReplaySample:
+    sample_id: str
+    payload: Dict[str, Any]
+    target: Any
+    priority: float
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+@dataclass
+class TraceEvent:
+    stage: str
+    message: str
+    payload: Dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+@dataclass
+class EngineResponse:
+    text: str
+    semantic_state: SemanticState
+    importance: ImportanceAssessment
+    routing: RoutingDecision
+    memory_bundle: MemoryBundle
+    inference: CoreInference
+    traces: List[TraceEvent]
+    learning_applied: bool
+
+
+@dataclass
+class NumericBatch:
+    features: torch.Tensor
+    operation_ids: torch.Tensor
+    targets: Optional[torch.Tensor] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TrainingMetrics:
+    epoch: int
+    loss: float
+    mae: float
+    accuracy: float
+    replay_ratio: float
+    plastic_norm: float
+    stable_drift: float
+
+
+@dataclass
+class ConsolidationReport:
+    merged_records: int
+    pruned_records: int
+    replay_reweighted: int
+    notes: str
+
+
+@dataclass
+class KnowledgeTriple:
+    subject: str
+    relation: str
+    object: str
+    confidence: float = 0.7
+    evidence: List[str] = field(default_factory=list)
+
+
+@dataclass
+class GraphNode:
+    node_id: str
+    node_type: str
+    label: str
+    namespace: str = ""
+    project_id: str = "global"
+    confidence: float = 0.7
+    version: int = 1
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    valid_from: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    valid_to: Optional[datetime] = None
+
+
+@dataclass
+class GraphEdge:
+    edge_id: str
+    source_id: str
+    target_id: str
+    relation: str
+    weight: float = 1.0
+    confidence: float = 0.7
+    evidence_ids: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class GraphPatch:
+    nodes: List[GraphNode] = field(default_factory=list)
+    edges: List[GraphEdge] = field(default_factory=list)
+    source: str = "unknown"
+
+
+@dataclass
+class GraphQuery:
+    seeds: List[str] = field(default_factory=list)
+    relation_filter: List[str] = field(default_factory=list)
+    project_id: Optional[str] = None
+    max_depth: int = 2
+    top_k: int = 12
+
+
+@dataclass
+class GraphSubgraph:
+    nodes: List[GraphNode] = field(default_factory=list)
+    edges: List[GraphEdge] = field(default_factory=list)
+    rationale: str = ""
+
+
+@dataclass
+class ProcedureMemory:
+    procedure_id: str
+    title: str
+    steps: List[str]
+    domains: List[str]
+    confidence: float
+    evidence_ids: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ProjectMemoryRecord:
+    project_id: str
+    root_path: str
+    files_indexed: int
+    modules: List[str]
+    dependencies: List[str]
+    tests: List[str]
+    commands: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PreferenceRecord:
+    key: str
+    value: str
+    confidence: float
+    source: str
+    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+@dataclass
+class EvidenceRecord:
+    evidence_id: str
+    source: str
+    quote: str
+    confidence: float
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SemanticStateV2(SemanticState):
+    code_symbols: List[str] = field(default_factory=list)
+    graph_candidates: List[GraphPatch] = field(default_factory=list)
+    uncertainty: float = 0.0
+    modality_features: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MemoryQueryV2(MemoryQuery):
+    project_id: Optional[str] = None
+    include_graph: bool = True
+    include_procedures: bool = True
+    include_project: bool = True
+    include_preferences: bool = True
+    graph_query: Optional[GraphQuery] = None
+
+
+@dataclass
+class MemoryBundleV2(MemoryBundle):
+    procedural: List[ProcedureMemory] = field(default_factory=list)
+    project: List[ProjectMemoryRecord] = field(default_factory=list)
+    graph_subgraph: Optional[GraphSubgraph] = None
+    preferences: List[PreferenceRecord] = field(default_factory=list)
+    evidence: List[EvidenceRecord] = field(default_factory=list)
+
+
+@dataclass
+class RoutingDecisionV2(RoutingDecision):
+    selected_specialists: List[str] = field(default_factory=list)
+    memory_plan: Dict[str, float] = field(default_factory=dict)
+    tool_plan: List[str] = field(default_factory=list)
+    context_budget: int = 8192
+    learning_action: str = "observe"
+    consolidation_action: str = "none"
+    confidence: float = 0.5
+    gate_scores: Dict[str, float] = field(default_factory=dict)
+    fallback_plan: str = "heuristic_router"
+
+
+@dataclass
+class CompressionBundle:
+    compressed_knowledge: List[CompressedKnowledge] = field(default_factory=list)
+    triples: List[KnowledgeTriple] = field(default_factory=list)
+    graph_patch: GraphPatch = field(default_factory=GraphPatch)
+    replay_samples: List[ReplaySample] = field(default_factory=list)
+    validation_requests: List[str] = field(default_factory=list)
+    preferences: List[PreferenceRecord] = field(default_factory=list)
+    procedures: List[ProcedureMemory] = field(default_factory=list)
+
+
+@dataclass
+class ContextPackage:
+    prompt: str
+    evidence_ids: List[str]
+    token_estimate: int
+    sections: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class StabilityDecision:
+    approved: bool
+    confidence: float
+    risk_score: float
+    reasons: List[str] = field(default_factory=list)
+
+
+@dataclass
+class EngineResponseV2(EngineResponse):
+    routing_v2: Optional[RoutingDecisionV2] = None
+    memory_bundle_v2: Optional[MemoryBundleV2] = None
+    context_package: Optional[ContextPackage] = None
+    stability_decision: Optional[StabilityDecision] = None
+
+
+def tensor_to_numpy(tensor: torch.Tensor) -> np.ndarray:
+    return tensor.detach().cpu().numpy()

cognitive_engine/interfaces/__init__.py

@@ -0,0 +1,2 @@
+"""Public interfaces and contracts."""
+

cognitive_engine/interfaces/base.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Iterable, List, Optional
+
+from cognitive_engine.core.types import (
+    CompressedKnowledge,
+    ConsolidationReport,
+    CoreInference,
+    ImportanceAssessment,
+    MemoryBundle,
+    MemoryQuery,
+    NumericBatch,
+    ProcessedInput,
+    ReplaySample,
+    RoutingDecision,
+    RoutingDecisionV2,
+    SemanticState,
+    SemanticStateV2,
+    TraceEvent,
+)
+
+
+class ConfigurableComponent(ABC):
+    name: str
+
+    @abstractmethod
+    def describe(self) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+class InputProcessor(ConfigurableComponent, ABC):
+    @abstractmethod
+    def supports(self, payload: Any) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def process(self, payload: Any) -> ProcessedInput:
+        raise NotImplementedError
+
+
+class SemanticEncoder(ConfigurableComponent, ABC):
+    @abstractmethod
+    def encode(self, processed: ProcessedInput) -> SemanticState:
+        raise NotImplementedError
+
+
+class ImportanceEvaluator(ConfigurableComponent, ABC):
+    @abstractmethod
+    def evaluate(self, semantic_state: SemanticState, memory_bundle: MemoryBundle) -> ImportanceAssessment:
+        raise NotImplementedError
+
+
+class KnowledgeCompressor(ConfigurableComponent, ABC):
+    @abstractmethod
+    def compress(self, semantic_state: SemanticState, importance: ImportanceAssessment) -> CompressedKnowledge:
+        raise NotImplementedError
+
+
+class MemoryStore(ConfigurableComponent, ABC):
+    @abstractmethod
+    def write(self, knowledge: CompressedKnowledge) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def search(self, query: MemoryQuery) -> List[CompressedKnowledge]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def snapshot(self) -> List[CompressedKnowledge]:
+        raise NotImplementedError
+
+
+class WorkingMemory(ConfigurableComponent, ABC):
+    @abstractmethod
+    def update(self, semantic_state: SemanticState) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def snapshot(self) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+class Router(ConfigurableComponent, ABC):
+    @abstractmethod
+    def route(self, processed: ProcessedInput, semantic_state: Optional[SemanticState] = None) -> RoutingDecision:
+        raise NotImplementedError
+
+
+class StableCore(ConfigurableComponent, ABC):
+    @abstractmethod
+    def infer(
+        self,
+        semantic_state: SemanticState,
+        memory_bundle: MemoryBundle,
+        routing: RoutingDecision,
+        plastic_output: Optional[CoreInference] = None,
+    ) -> CoreInference:
+        raise NotImplementedError
+
+
+class PlasticLearner(ConfigurableComponent, ABC):
+    @abstractmethod
+    def predict(self, semantic_state: SemanticState) -> CoreInference:
+        raise NotImplementedError
+
+    @abstractmethod
+    def train_step(self, batch: NumericBatch, replay_batch: Optional[NumericBatch] = None) -> Dict[str, float]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def parameter_drift(self) -> float:
+        raise NotImplementedError
+
+
+class ReplayBuffer(ConfigurableComponent, ABC):
+    @abstractmethod
+    def add(self, sample: ReplaySample) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def sample(self, batch_size: int) -> List[ReplaySample]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __len__(self) -> int:
+        raise NotImplementedError
+
+
+class Consolidator(ConfigurableComponent, ABC):
+    @abstractmethod
+    def run(self) -> ConsolidationReport:
+        raise NotImplementedError
+
+
+class TelemetrySink(ConfigurableComponent, ABC):
+    @abstractmethod
+    def emit(self, event: TraceEvent) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def flush(self) -> None:
+        raise NotImplementedError
+
+
+class LearnedRouter(Router, ABC):
+    @abstractmethod
+    def route_v2(self, semantic_state: SemanticStateV2, runtime_context: Dict[str, Any]) -> RoutingDecisionV2:
+        raise NotImplementedError
+
+
+class GraphMemoryStore(ConfigurableComponent, ABC):
+    @abstractmethod
+    def apply_patch(self, patch: Any) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def query_subgraph(self, query: Any) -> Any:
+        raise NotImplementedError
+
+
+class Specialist(ConfigurableComponent, ABC):
+    @abstractmethod
+    def can_handle(self, semantic_state: SemanticStateV2) -> float:
+        raise NotImplementedError
+
+    @abstractmethod
+    def prepare_context(self, semantic_state: SemanticStateV2, memory_bundle: Any) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+class LongContextManager(ConfigurableComponent, ABC):
+    @abstractmethod
+    def compose(self, request: Dict[str, Any]) -> Any:
+        raise NotImplementedError
+
+
+class StabilityGovernor(ConfigurableComponent, ABC):
+    @abstractmethod
+    def validate_update(self, update: Dict[str, Any]) -> Any:
+        raise NotImplementedError

cognitive_engine/memory/__init__.py

@@ -0,0 +1,2 @@
+"""Hierarchical memory subsystems."""
+

cognitive_engine/memory/graph_memory.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Dict, List
+from uuid import uuid4
+
+import networkx as nx
+
+from cognitive_engine.core.types import GraphEdge, GraphNode, GraphPatch, GraphQuery, GraphSubgraph
+from cognitive_engine.interfaces.base import GraphMemoryStore
+
+
+class CognitiveGraphMemory(GraphMemoryStore):
+    name = "cognitive_graph_memory"
+
+    def __init__(self) -> None:
+        self.graph = nx.MultiDiGraph()
+        self.nodes: Dict[str, GraphNode] = {}
+        self.edges: Dict[str, GraphEdge] = {}
+        self.label_index: Dict[str, str] = {}
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name, "nodes": len(self.nodes), "edges": len(self.edges)}
+
+    def upsert_node(
+        self,
+        label: str,
+        node_type: str,
+        namespace: str = "",
+        project_id: str = "global",
+        confidence: float = 0.75,
+        metadata: Dict[str, Any] | None = None,
+    ) -> GraphNode:
+        key = self._key(label, node_type, namespace, project_id)
+        existing_id = self.label_index.get(key)
+        if existing_id:
+            node = self.nodes[existing_id]
+            node.confidence = max(node.confidence, confidence)
+            node.version += 1
+            node.metadata.update(metadata or {})
+            self.graph.nodes[existing_id].update(asdict(node))
+            return node
+
+        node = GraphNode(
+            node_id=str(uuid4()),
+            node_type=node_type,
+            label=label,
+            namespace=namespace,
+            project_id=project_id,
+            confidence=confidence,
+            metadata=metadata or {},
+        )
+        self.nodes[node.node_id] = node
+        self.label_index[key] = node.node_id
+        self.graph.add_node(node.node_id, **asdict(node))
+        return node
+
+    def upsert_edge(
+        self,
+        source: GraphNode,
+        target: GraphNode,
+        relation: str,
+        weight: float = 1.0,
+        confidence: float = 0.75,
+        evidence_ids: List[str] | None = None,
+        metadata: Dict[str, Any] | None = None,
+    ) -> GraphEdge:
+        for edge_id, edge in self.edges.items():
+            if edge.source_id == source.node_id and edge.target_id == target.node_id and edge.relation == relation:
+                edge.weight = max(edge.weight, weight)
+                edge.confidence = max(edge.confidence, confidence)
+                edge.evidence_ids = list(dict.fromkeys(edge.evidence_ids + (evidence_ids or [])))
+                edge.metadata.update(metadata or {})
+                self.graph[source.node_id][target.node_id][edge_id].update(asdict(edge))
+                return edge
+
+        edge = GraphEdge(
+            edge_id=str(uuid4()),
+            source_id=source.node_id,
+            target_id=target.node_id,
+            relation=relation,
+            weight=weight,
+            confidence=confidence,
+            evidence_ids=evidence_ids or [],
+            metadata=metadata or {},
+        )
+        self.edges[edge.edge_id] = edge
+        self.graph.add_edge(source.node_id, target.node_id, key=edge.edge_id, **asdict(edge))
+        return edge
+
+    def apply_patch(self, patch: GraphPatch) -> None:
+        id_map: Dict[str, GraphNode] = {}
+        for node in patch.nodes:
+            upserted = self.upsert_node(
+                label=node.label,
+                node_type=node.node_type,
+                namespace=node.namespace,
+                project_id=node.project_id,
+                confidence=node.confidence,
+                metadata=node.metadata,
+            )
+            id_map[node.node_id] = upserted
+        for edge in patch.edges:
+            source = id_map.get(edge.source_id) or self.nodes.get(edge.source_id)
+            target = id_map.get(edge.target_id) or self.nodes.get(edge.target_id)
+            if source and target:
+                self.upsert_edge(source, target, edge.relation, edge.weight, edge.confidence, edge.evidence_ids, edge.metadata)
+
+    def query_subgraph(self, query: GraphQuery) -> GraphSubgraph:
+        if not self.nodes:
+            return GraphSubgraph(rationale="Graph is empty.")
+
+        seeds = self._resolve_seeds(query)
+        visited = set(seeds)
+        frontier = set(seeds)
+        for _ in range(max(query.max_depth, 0)):
+            next_frontier = set()
+            for node_id in frontier:
+                neighbors = set(self.graph.successors(node_id)) | set(self.graph.predecessors(node_id))
+                next_frontier.update(neighbors)
+            next_frontier -= visited
+            visited.update(next_frontier)
+            frontier = next_frontier
+
+        nodes = [self.nodes[node_id] for node_id in visited if self._matches_project(self.nodes[node_id], query)]
+        node_ids = {node.node_id for node in nodes}
+        edges = [
+            edge
+            for edge in self.edges.values()
+            if edge.source_id in node_ids
+            and edge.target_id in node_ids
+            and (not query.relation_filter or edge.relation in query.relation_filter)
+        ]
+        nodes = nodes[: query.top_k]
+        node_ids = {node.node_id for node in nodes}
+        edges = [edge for edge in edges if edge.source_id in node_ids and edge.target_id in node_ids]
+        return GraphSubgraph(nodes=nodes, edges=edges, rationale=f"Expanded {len(seeds)} seed nodes to {len(nodes)} nodes.")
+
+    def snapshot(self) -> Dict[str, Any]:
+        type_counts: Dict[str, int] = {}
+        relation_counts: Dict[str, int] = {}
+        for node in self.nodes.values():
+            type_counts[node.node_type] = type_counts.get(node.node_type, 0) + 1
+        for edge in self.edges.values():
+            relation_counts[edge.relation] = relation_counts.get(edge.relation, 0) + 1
+        return {"nodes": len(self.nodes), "edges": len(self.edges), "node_types": type_counts, "relations": relation_counts}
+
+    def _resolve_seeds(self, query: GraphQuery) -> List[str]:
+        if not query.seeds:
+            return list(self.nodes)[: query.top_k]
+        resolved = []
+        normalized_seeds = [seed.lower() for seed in query.seeds]
+        for node_id, node in self.nodes.items():
+            label = node.label.lower()
+            if any(seed in label or label in seed for seed in normalized_seeds):
+                if self._matches_project(node, query):
+                    resolved.append(node_id)
+        return resolved[: query.top_k] or list(self.nodes)[: min(query.top_k, len(self.nodes))]
+
+    def _matches_project(self, node: GraphNode, query: GraphQuery) -> bool:
+        return query.project_id is None or node.project_id in {query.project_id, "global"}
+
+    def _key(self, label: str, node_type: str, namespace: str, project_id: str) -> str:
+        return f"{project_id}:{namespace}:{node_type}:{label}".lower()
+