cognitive-engine 0.2.0__py3-none-any.whl

cognitive_engine/core/builder.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from cognitive_engine.adapters.plastic_numeric_adapter import PlasticArithmeticModule
+from cognitive_engine.compression.knowledge_compressor import SemanticKnowledgeCompressor
+from cognitive_engine.compression.semantic_compressor_v2 import SemanticCompressorV2
+from cognitive_engine.config.loader import load_engine_config
+from cognitive_engine.config.schema import EngineConfig
+from cognitive_engine.consolidation.engine import BackgroundConsolidationEngine
+from cognitive_engine.consolidation.engine_v2 import CognitiveConsolidationEngineV2
+from cognitive_engine.core.engine import CognitiveEngine
+from cognitive_engine.core.engine_v2 import CognitiveEngineV2
+from cognitive_engine.core.registry import GLOBAL_REGISTRY
+from cognitive_engine.context.long_context import LongContextManager
+from cognitive_engine.memory.graph_memory import CognitiveGraphMemory
+from cognitive_engine.memory.hybrid_memory import HybridCognitiveMemory
+from cognitive_engine.memory.project_memory import ProjectIndexer
+from cognitive_engine.memory.stores import HierarchicalMemorySystem
+from cognitive_engine.models.stable_core import StableReasoningCore
+from cognitive_engine.modules.importance_evaluator import AdaptiveImportanceEvaluator
+from cognitive_engine.modules.input_processing import NumericInputProcessor, TextInputProcessor
+from cognitive_engine.modules.semantic_understanding import HybridSemanticEncoder, NumericSemanticEncoder, TextSemanticEncoder
+from cognitive_engine.replay.buffer import PrioritizedReplayBuffer
+from cognitive_engine.routing.dynamic_router import AdaptiveDynamicRouter
+from cognitive_engine.routing.learned_router import LearnedCognitiveRouter
+from cognitive_engine.specialists.runtime import SpecialistRuntime
+from cognitive_engine.stability.governor import StabilityGovernorV2
+from cognitive_engine.training.online_trainer import OnlineTrainer
+from cognitive_engine.utils.seeding import set_seed
+from cognitive_engine.utils.telemetry import JsonlTelemetrySink
+
+
+class EngineBuilder:
+    def __init__(self, config: EngineConfig | None = None, config_path: str | None = None) -> None:
+        self.config = config or load_engine_config(config_path)
+        self._register_defaults()
+
+    def build(self) -> CognitiveEngine:
+        set_seed(self.config.seed)
+        telemetry = GLOBAL_REGISTRY.create("telemetry", "jsonl", path=Path("artifacts") / "logs" / "engine_trace.jsonl")
+        replay_buffer = GLOBAL_REGISTRY.create("replay", "prioritized", capacity=self.config.memory.replay_capacity)
+        memory_system = GLOBAL_REGISTRY.create("memory", "hierarchical", config=self.config.memory)
+        processors = [
+            GLOBAL_REGISTRY.create("processor", "numeric", device=self.config.device, scale=float(self.config.numeric_demo.max_operand)),
+            GLOBAL_REGISTRY.create("processor", "text", device=self.config.device),
+        ]
+        semantic_encoder = GLOBAL_REGISTRY.create(
+            "semantic_encoder",
+            "hybrid",
+            text_encoder=GLOBAL_REGISTRY.create("semantic_encoder", "text", device=self.config.device),
+            numeric_encoder=GLOBAL_REGISTRY.create("semantic_encoder", "numeric", device=self.config.device),
+        )
+        plastic_learner = GLOBAL_REGISTRY.create(
+            "plasticity",
+            "arithmetic",
+            device=self.config.device,
+            output_scale=float(self.config.numeric_demo.max_operand**2),
+        )
+        trainer = OnlineTrainer(
+            plastic_learner=plastic_learner,
+            replay_buffer=replay_buffer,
+            replay_batch_size=self.config.numeric_demo.replay_batch_size,
+            device=self.config.device,
+        )
+        consolidator = BackgroundConsolidationEngine(memory_system=memory_system, replay_buffer=replay_buffer)
+        return CognitiveEngine(
+            config=self.config,
+            processors=processors,
+            semantic_encoder=semantic_encoder,
+            importance_evaluator=GLOBAL_REGISTRY.create("importance", "adaptive", thresholds=self.config.thresholds),
+            compressor=GLOBAL_REGISTRY.create("compressor", "semantic"),
+            memory_system=memory_system,
+            router=GLOBAL_REGISTRY.create("router", "adaptive"),
+            stable_core=GLOBAL_REGISTRY.create("stable_core", "reasoning", device=self.config.device),
+            plastic_learner=plastic_learner,
+            trainer=trainer,
+            replay_buffer=replay_buffer,
+            consolidator=consolidator,
+            telemetry=telemetry,
+        )
+
+    def build_v2(self) -> CognitiveEngineV2:
+        set_seed(self.config.seed)
+        telemetry = GLOBAL_REGISTRY.create("telemetry", "jsonl", path=Path("artifacts") / "logs" / "engine_trace_v2.jsonl")
+        replay_buffer = GLOBAL_REGISTRY.create("replay", "prioritized", capacity=self.config.memory.replay_capacity)
+        base_memory = GLOBAL_REGISTRY.create("memory", "hierarchical", config=self.config.memory)
+        graph_memory = GLOBAL_REGISTRY.create("memory", "graph")
+        memory_system = GLOBAL_REGISTRY.create("memory", "hybrid_v2", base_memory=base_memory, graph_memory=graph_memory)
+        processors = [
+            GLOBAL_REGISTRY.create("processor", "numeric", device=self.config.device, scale=float(self.config.numeric_demo.max_operand)),
+            GLOBAL_REGISTRY.create("processor", "text", device=self.config.device),
+        ]
+        semantic_encoder = GLOBAL_REGISTRY.create(
+            "semantic_encoder",
+            "hybrid",
+            text_encoder=GLOBAL_REGISTRY.create("semantic_encoder", "text", device=self.config.device),
+            numeric_encoder=GLOBAL_REGISTRY.create("semantic_encoder", "numeric", device=self.config.device),
+        )
+        plastic_learner = GLOBAL_REGISTRY.create(
+            "plasticity",
+            "arithmetic",
+            device=self.config.device,
+            output_scale=float(self.config.numeric_demo.max_operand**2),
+        )
+        trainer = OnlineTrainer(
+            plastic_learner=plastic_learner,
+            replay_buffer=replay_buffer,
+            replay_batch_size=self.config.numeric_demo.replay_batch_size,
+            device=self.config.device,
+        )
+        return CognitiveEngineV2(
+            config=self.config,
+            processors=processors,
+            semantic_encoder=semantic_encoder,
+            importance_evaluator=GLOBAL_REGISTRY.create("importance", "adaptive", thresholds=self.config.thresholds),
+            compressor_v2=GLOBAL_REGISTRY.create("compressor", "semantic_v2"),
+            memory_system=memory_system,
+            router=GLOBAL_REGISTRY.create("router", "learned", device=self.config.device),
+            stable_core=GLOBAL_REGISTRY.create("stable_core", "reasoning", device=self.config.device),
+            plastic_learner=plastic_learner,
+            trainer=trainer,
+            replay_buffer=replay_buffer,
+            consolidator=GLOBAL_REGISTRY.create("consolidator", "cognitive_v2", memory_system=memory_system, replay_buffer=replay_buffer),
+            telemetry=telemetry,
+            specialist_runtime=GLOBAL_REGISTRY.create("specialists", "runtime"),
+            context_manager=GLOBAL_REGISTRY.create("context", "long"),
+            stability_governor=GLOBAL_REGISTRY.create("stability", "governor_v2"),
+            project_indexer=GLOBAL_REGISTRY.create("project", "indexer", graph_memory=graph_memory),
+        )
+
+    def _register_defaults(self) -> None:
+        GLOBAL_REGISTRY.register("telemetry", "jsonl", JsonlTelemetrySink)
+        GLOBAL_REGISTRY.register("replay", "prioritized", PrioritizedReplayBuffer)
+        GLOBAL_REGISTRY.register("memory", "hierarchical", HierarchicalMemorySystem)
+        GLOBAL_REGISTRY.register("memory", "graph", CognitiveGraphMemory)
+        GLOBAL_REGISTRY.register("memory", "hybrid_v2", HybridCognitiveMemory)
+        GLOBAL_REGISTRY.register("processor", "numeric", NumericInputProcessor)
+        GLOBAL_REGISTRY.register("processor", "text", TextInputProcessor)
+        GLOBAL_REGISTRY.register("semantic_encoder", "text", TextSemanticEncoder)
+        GLOBAL_REGISTRY.register("semantic_encoder", "numeric", NumericSemanticEncoder)
+        GLOBAL_REGISTRY.register("semantic_encoder", "hybrid", HybridSemanticEncoder)
+        GLOBAL_REGISTRY.register("importance", "adaptive", AdaptiveImportanceEvaluator)
+        GLOBAL_REGISTRY.register("compressor", "semantic", SemanticKnowledgeCompressor)
+        GLOBAL_REGISTRY.register("compressor", "semantic_v2", SemanticCompressorV2)
+        GLOBAL_REGISTRY.register("router", "adaptive", AdaptiveDynamicRouter)
+        GLOBAL_REGISTRY.register("router", "learned", LearnedCognitiveRouter)
+        GLOBAL_REGISTRY.register("stable_core", "reasoning", StableReasoningCore)
+        GLOBAL_REGISTRY.register("plasticity", "arithmetic", PlasticArithmeticModule)
+        GLOBAL_REGISTRY.register("consolidator", "cognitive_v2", CognitiveConsolidationEngineV2)
+        GLOBAL_REGISTRY.register("specialists", "runtime", SpecialistRuntime)
+        GLOBAL_REGISTRY.register("context", "long", LongContextManager)
+        GLOBAL_REGISTRY.register("stability", "governor_v2", StabilityGovernorV2)
+        GLOBAL_REGISTRY.register("project", "indexer", ProjectIndexer)

cognitive_engine/core/engine.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Sequence
+
+from cognitive_engine.config.schema import EngineConfig
+from cognitive_engine.core.types import EngineResponse, MemoryQuery, TraceEvent, tensor_to_numpy
+
+
+class CognitiveEngine:
+    def __init__(
+        self,
+        config: EngineConfig,
+        processors: Sequence[Any],
+        semantic_encoder: Any,
+        importance_evaluator: Any,
+        compressor: Any,
+        memory_system: Any,
+        router: Any,
+        stable_core: Any,
+        plastic_learner: Any,
+        trainer: Any,
+        replay_buffer: Any,
+        consolidator: Any,
+        telemetry: Any,
+    ) -> None:
+        self.config = config
+        self.processors = list(processors)
+        self.semantic_encoder = semantic_encoder
+        self.importance_evaluator = importance_evaluator
+        self.compressor = compressor
+        self.memory_system = memory_system
+        self.router = router
+        self.stable_core = stable_core
+        self.plastic_learner = plastic_learner
+        self.trainer = trainer
+        self.replay_buffer = replay_buffer
+        self.consolidator = consolidator
+        self.telemetry = telemetry
+        self.step_counter = 0
+
+    def process(self, payload: Any, allow_learning: bool = True) -> EngineResponse:
+        traces: List[TraceEvent] = []
+        processed = self._select_processor(payload).process(payload)
+        traces.append(self._trace("input", "Payload processed.", {"modality": processed.modality, "metadata": processed.metadata}))
+
+        semantic_state = self.semantic_encoder.encode(processed)
+        self.memory_system.update_working_memory(semantic_state)
+        traces.append(self._trace("semantic", "Semantic state created.", {"intent": semantic_state.intent, "concepts": [c.label for c in semantic_state.concepts]}))
+
+        route = self.router.route(processed, semantic_state)
+        query = MemoryQuery(
+            embedding=tensor_to_numpy(semantic_state.pooled_embedding.float()),
+            top_k=self.config.memory.retrieval_top_k,
+            modality=processed.modality,
+            intent=semantic_state.intent,
+            concepts=[concept.label for concept in semantic_state.concepts],
+        )
+        memory_bundle = self.memory_system.retrieve(query)
+        traces.append(
+            self._trace(
+                "memory_retrieval",
+                "Memory bundle retrieved.",
+                {
+                    "short_term": len(memory_bundle.short_term),
+                    "semantic_long_term": len(memory_bundle.semantic_long_term),
+                    "episodic": len(memory_bundle.episodic),
+                },
+            )
+        )
+
+        importance = self.importance_evaluator.evaluate(semantic_state, memory_bundle)
+        semantic_state.metadata["importance_action"] = importance.action
+        traces.append(
+            self._trace(
+                "importance",
+                importance.rationale,
+                {
+                    "importance_score": importance.importance_score,
+                    "confidence_score": importance.confidence_score,
+                    "learning_priority": importance.learning_priority,
+                    "action": importance.action,
+                },
+            )
+        )
+
+        plastic_output = None
+        if route.engage_plasticity and processed.modality == "numeric":
+            plastic_output = self.plastic_learner.predict(semantic_state)
+            traces.append(self._trace("plastic_inference", plastic_output.explanation, plastic_output.artifacts))
+
+        inference = self.stable_core.infer(semantic_state, memory_bundle, route, plastic_output)
+        traces.append(self._trace("stable_core", inference.explanation, {"confidence": inference.confidence}))
+
+        learning_applied = False
+        if allow_learning and route.update_memory and importance.action not in {"ignore", "uncertain"}:
+            knowledge = self.compressor.compress(semantic_state, importance)
+            self.memory_system.write(knowledge)
+            learning_applied = True
+            traces.append(self._trace("memory_write", "Compressed knowledge stored.", {"record_id": knowledge.record_id, "summary": knowledge.summary}))
+
+        if allow_learning and processed.modality == "numeric" and semantic_state.metadata.get("target") is not None:
+            training_metrics = self.trainer.observe(semantic_state, priority=importance.learning_priority)
+            if training_metrics is not None:
+                learning_applied = True
+                traces.append(self._trace("online_training", "Plastic module updated.", training_metrics))
+
+        self.step_counter += 1
+        if self.step_counter % self.config.memory.consolidation_interval == 0:
+            report = self.consolidator.run()
+            traces.append(
+                self._trace(
+                    "consolidation",
+                    report.notes,
+                    {
+                        "merged_records": report.merged_records,
+                        "pruned_records": report.pruned_records,
+                        "replay_reweighted": report.replay_reweighted,
+                    },
+                )
+            )
+
+        for event in traces:
+            self.telemetry.emit(event)
+        self.telemetry.flush()
+
+        return EngineResponse(
+            text=str(inference.explanation),
+            semantic_state=semantic_state,
+            importance=importance,
+            routing=route,
+            memory_bundle=memory_bundle,
+            inference=inference,
+            traces=traces,
+            learning_applied=learning_applied,
+        )
+
+    def snapshot(self) -> Dict[str, Any]:
+        return {
+            "steps": self.step_counter,
+            "memory": self.memory_system.snapshot(),
+            "replay_size": len(self.replay_buffer),
+            "plastic_drift": self.plastic_learner.parameter_drift(),
+        }
+
+    def describe_architecture(self) -> Dict[str, Any]:
+        return {
+            "processors": [processor.describe() for processor in self.processors],
+            "semantic_encoder": self.semantic_encoder.describe(),
+            "importance_evaluator": self.importance_evaluator.describe(),
+            "compressor": self.compressor.describe(),
+            "memory_system": self.memory_system.describe(),
+            "router": self.router.describe(),
+            "stable_core": self.stable_core.describe(),
+            "plastic_learner": self.plastic_learner.describe(),
+            "replay_buffer": self.replay_buffer.describe(),
+            "consolidator": self.consolidator.describe(),
+            "telemetry": self.telemetry.describe(),
+        }
+
+    def replace_component(self, slot: str, component: Any) -> Any:
+        if not hasattr(self, slot):
+            raise AttributeError(f"Engine has no component slot named '{slot}'.")
+        previous = getattr(self, slot)
+        setattr(self, slot, component)
+        return previous
+
+    def _select_processor(self, payload: Any) -> Any:
+        for processor in self.processors:
+            if processor.supports(payload):
+                return processor
+        raise TypeError(f"No input processor supports payload type: {type(payload)!r}")
+
+    def _trace(self, stage: str, message: str, payload: Dict[str, Any]) -> TraceEvent:
+        return TraceEvent(stage=stage, message=message, payload=payload)

cognitive_engine/core/engine_v2.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Sequence
+
+from cognitive_engine.config.schema import EngineConfig
+from cognitive_engine.core.types import (
+    EngineResponseV2,
+    GraphQuery,
+    MemoryQueryV2,
+    SemanticState,
+    SemanticStateV2,
+    TraceEvent,
+    tensor_to_numpy,
+)
+
+
+class CognitiveEngineV2:
+    def __init__(
+        self,
+        config: EngineConfig,
+        processors: Sequence[Any],
+        semantic_encoder: Any,
+        importance_evaluator: Any,
+        compressor_v2: Any,
+        memory_system: Any,
+        router: Any,
+        stable_core: Any,
+        plastic_learner: Any,
+        trainer: Any,
+        replay_buffer: Any,
+        consolidator: Any,
+        telemetry: Any,
+        specialist_runtime: Any,
+        context_manager: Any,
+        stability_governor: Any,
+        project_indexer: Any,
+    ) -> None:
+        self.config = config
+        self.processors = list(processors)
+        self.semantic_encoder = semantic_encoder
+        self.importance_evaluator = importance_evaluator
+        self.compressor_v2 = compressor_v2
+        self.memory_system = memory_system
+        self.router = router
+        self.stable_core = stable_core
+        self.plastic_learner = plastic_learner
+        self.trainer = trainer
+        self.replay_buffer = replay_buffer
+        self.consolidator = consolidator
+        self.telemetry = telemetry
+        self.specialist_runtime = specialist_runtime
+        self.context_manager = context_manager
+        self.stability_governor = stability_governor
+        self.project_indexer = project_indexer
+        self.step_counter = 0
+
+    def process(self, payload: Any, allow_learning: bool = True, project_path: str | None = None, project_id: str | None = None) -> EngineResponseV2:
+        traces: List[TraceEvent] = []
+        if project_path:
+            project_record = self.project_indexer.index_project(project_path, project_id)
+            self.memory_system.add_project_record(project_record)
+            project_id = project_record.project_id
+            traces.append(self._trace("project_index", "Project indexed into graph memory.", project_record.__dict__))
+
+        processed = self._select_processor(payload).process(payload)
+        traces.append(self._trace("input_v2", "Payload processed.", {"modality": processed.modality, "metadata": processed.metadata}))
+
+        base_state = self.semantic_encoder.encode(processed)
+        semantic_state = self._upgrade_state(base_state)
+        self.memory_system.update_working_memory(semantic_state)
+        traces.append(
+            self._trace(
+                "semantic_v2",
+                "SemanticStateV2 created.",
+                {
+                    "intent": semantic_state.intent,
+                    "concepts": [concept.label for concept in semantic_state.concepts],
+                    "code_symbols": semantic_state.code_symbols,
+                },
+            )
+        )
+
+        runtime_context = {
+            "project_id": project_id,
+            "has_project_memory": bool(self.memory_system.project_records),
+            "long_context": len(str(payload)) > 4000 or bool(project_path),
+        }
+        routing = self.router.route_v2(semantic_state, runtime_context)
+        traces.append(self._trace("routing_v2", routing.rationale, routing.gate_scores))
+
+        query = MemoryQueryV2(
+            embedding=tensor_to_numpy(semantic_state.pooled_embedding.float()),
+            top_k=self.config.memory.retrieval_top_k,
+            modality=processed.modality,
+            intent=semantic_state.intent,
+            concepts=[concept.label for concept in semantic_state.concepts] + semantic_state.code_symbols,
+            project_id=project_id,
+            graph_query=GraphQuery(
+                seeds=[concept.label for concept in semantic_state.concepts] + semantic_state.code_symbols,
+                project_id=project_id,
+                top_k=16,
+            ),
+        )
+        memory_bundle = self.memory_system.retrieve_v2(query)
+        traces.append(
+            self._trace(
+                "memory_v2",
+                "Hybrid memory bundle retrieved.",
+                {
+                    "semantic": len(memory_bundle.semantic_long_term),
+                    "episodic": len(memory_bundle.episodic),
+                    "procedural": len(memory_bundle.procedural),
+                    "project": len(memory_bundle.project),
+                    "graph_nodes": len(memory_bundle.graph_subgraph.nodes) if memory_bundle.graph_subgraph else 0,
+                },
+            )
+        )
+
+        specialist_context = self.specialist_runtime.prepare_context(semantic_state, memory_bundle, routing.selected_specialists)
+        context_package = self.context_manager.compose(
+            {
+                "semantic_state": semantic_state,
+                "memory_bundle": memory_bundle,
+                "specialist_context": specialist_context,
+                "context_budget": routing.context_budget,
+            }
+        )
+        traces.append(
+            self._trace(
+                "context_v2",
+                "Context package composed.",
+                {"token_estimate": context_package.token_estimate, "sections": list(context_package.sections)},
+            )
+        )
+
+        importance = self.importance_evaluator.evaluate(semantic_state, memory_bundle)
+        semantic_state.metadata["importance_action"] = importance.action
+        stability = self.stability_governor.validate_update(
+            {
+                "confidence": importance.confidence_score,
+                "contradiction_risk": importance.contradiction_risk,
+                "plastic_drift": self.plastic_learner.parameter_drift(),
+            }
+        )
+        traces.append(self._trace("stability_v2", "Stability decision computed.", stability.__dict__))
+
+        plastic_output = None
+        if routing.engage_plasticity and processed.modality == "numeric":
+            plastic_output = self.plastic_learner.predict(semantic_state)
+            traces.append(self._trace("plastic_v2", plastic_output.explanation, plastic_output.artifacts))
+
+        inference = self.stable_core.infer(semantic_state, memory_bundle, routing, plastic_output)
+        if context_package.sections.get("specialists"):
+            inference.explanation = f"{inference.explanation}\n\nSpecialist context: {context_package.sections['specialists']}"
+        traces.append(self._trace("stable_core_v2", inference.explanation, {"confidence": inference.confidence}))
+
+        learning_applied = False
+        if (
+            allow_learning
+            and routing.update_memory
+            and routing.learning_action == "learn"
+            and importance.action not in {"ignore", "uncertain"}
+            and stability.approved
+        ):
+            compression = self.compressor_v2.compress_v2(semantic_state, importance, project_id=project_id or "global")
+            self.memory_system.write_v2(compression)
+            learning_applied = True
+            traces.append(
+                self._trace(
+                    "memory_write_v2",
+                    "CompressionBundle written to hybrid memory.",
+                    {
+                        "knowledge": len(compression.compressed_knowledge),
+                        "triples": len(compression.triples),
+                        "graph_nodes": len(compression.graph_patch.nodes),
+                        "procedures": len(compression.procedures),
+                        "preferences": len(compression.preferences),
+                    },
+                )
+            )
+
+        if allow_learning and processed.modality == "numeric" and semantic_state.metadata.get("target") is not None:
+            training_metrics = self.trainer.observe(semantic_state, priority=importance.learning_priority)
+            if training_metrics is not None:
+                learning_applied = True
+                traces.append(self._trace("online_training_v2", "Plastic module updated.", training_metrics))
+
+        self.step_counter += 1
+        if self.step_counter % self.config.memory.consolidation_interval == 0 or routing.consolidation_action != "none":
+            report = self.consolidator.run()
+            traces.append(self._trace("consolidation_v2", report.notes, report.__dict__))
+
+        for event in traces:
+            self.telemetry.emit(event)
+        self.telemetry.flush()
+
+        return EngineResponseV2(
+            text=str(inference.explanation),
+            semantic_state=semantic_state,
+            importance=importance,
+            routing=routing,
+            memory_bundle=memory_bundle,
+            inference=inference,
+            traces=traces,
+            learning_applied=learning_applied,
+            routing_v2=routing,
+            memory_bundle_v2=memory_bundle,
+            context_package=context_package,
+            stability_decision=stability,
+        )
+
+    def snapshot(self) -> Dict[str, Any]:
+        return {
+            "version": "v2",
+            "steps": self.step_counter,
+            "memory": self.memory_system.snapshot(),
+            "router": self.router.describe(),
+            "specialists": self.specialist_runtime.describe(),
+            "context_manager": self.context_manager.describe(),
+            "stability": self.stability_governor.describe(),
+            "replay_size": len(self.replay_buffer),
+            "plastic_drift": self.plastic_learner.parameter_drift(),
+        }
+
+    def describe_architecture(self) -> Dict[str, Any]:
+        return {
+            "version": "v2",
+            "processors": [processor.describe() for processor in self.processors],
+            "semantic_encoder": self.semantic_encoder.describe(),
+            "router": self.router.describe(),
+            "memory_system": self.memory_system.describe(),
+            "compressor": self.compressor_v2.describe(),
+            "specialists": self.specialist_runtime.describe(),
+            "context_manager": self.context_manager.describe(),
+            "stability_governor": self.stability_governor.describe(),
+            "stable_core": self.stable_core.describe(),
+            "plastic_learner": self.plastic_learner.describe(),
+            "consolidator": self.consolidator.describe(),
+        }
+
+    def _upgrade_state(self, state: SemanticState) -> SemanticStateV2:
+        text = str(state.raw_input)
+        code_symbols = self._extract_code_symbols(text)
+        return SemanticStateV2(
+            raw_input=state.raw_input,
+            modality=state.modality,
+            sequence_embedding=state.sequence_embedding,
+            pooled_embedding=state.pooled_embedding,
+            intent=state.intent,
+            entities=state.entities,
+            concepts=state.concepts,
+            concept_graph_edges=state.concept_graph_edges,
+            compressed_context=state.compressed_context,
+            metadata=dict(state.metadata),
+            code_symbols=code_symbols,
+            graph_candidates=[],
+            uncertainty=max(0.0, 1.0 - min(1.0, len(state.concepts) / 6.0)),
+            modality_features={"contains_code": bool(code_symbols), "raw_length": len(text)},
+        )
+
+    def _extract_code_symbols(self, text: str) -> List[str]:
+        symbols = []
+        for raw in text.replace("(", " ").replace(")", " ").replace(":", " ").replace(".", " ").split():
+            token = raw.strip("`'\"")
+            if not token:
+                continue
+            if token.endswith(".py") or token in {"class", "def", "pytest", "import"}:
+                symbols.append(token)
+            elif "_" in token or (token[:1].isupper() and len(token) > 2):
+                symbols.append(token)
+        return list(dict.fromkeys(symbols))[:12]
+
+    def _select_processor(self, payload: Any) -> Any:
+        for processor in self.processors:
+            if processor.supports(payload):
+                return processor
+        raise TypeError(f"No input processor supports payload type: {type(payload)!r}")
+
+    def _trace(self, stage: str, message: str, payload: Dict[str, Any]) -> TraceEvent:
+        return TraceEvent(stage=stage, message=message, payload=payload)

cognitive_engine/core/registry.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any, Callable, Dict
+
+
+Factory = Callable[..., Any]
+
+
+class ComponentRegistry:
+    def __init__(self) -> None:
+        self._factories: Dict[str, Dict[str, Factory]] = defaultdict(dict)
+
+    def register(self, category: str, name: str, factory: Factory) -> None:
+        self._factories[category][name] = factory
+
+    def create(self, category: str, name: str, **kwargs: Any) -> Any:
+        try:
+            factory = self._factories[category][name]
+        except KeyError as exc:
+            raise KeyError(f"Component '{name}' is not registered in category '{category}'.") from exc
+        return factory(**kwargs)
+
+    def available(self, category: str) -> Dict[str, Factory]:
+        return dict(self._factories.get(category, {}))
+
+
+GLOBAL_REGISTRY = ComponentRegistry()
+