cognitive-engine 0.2.0__py3-none-any.whl

cognitive_engine/__init__.py

@@ -0,0 +1,7 @@
+"""Hybrid cognitive architecture package."""
+
+from cognitive_engine.core.builder import EngineBuilder
+from cognitive_engine.core.engine import CognitiveEngine
+from cognitive_engine.core.engine_v2 import CognitiveEngineV2
+
+__all__ = ["CognitiveEngine", "CognitiveEngineV2", "EngineBuilder"]

cognitive_engine/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Plastic adapters and localized learners."""
+

cognitive_engine/adapters/plastic_numeric_adapter.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Dict, Optional
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+from cognitive_engine.core.types import CoreInference, NumericBatch, SemanticState
+from cognitive_engine.interfaces.base import PlasticLearner
+
+
+class LowRankResidual(nn.Module):
+    def __init__(self, input_dim: int, hidden_dim: int, rank: int = 4, alpha: float = 8.0) -> None:
+        super().__init__()
+        self.frozen = nn.Linear(input_dim, hidden_dim)
+        self.adapter_a = nn.Linear(input_dim, rank, bias=False)
+        self.adapter_b = nn.Linear(rank, hidden_dim, bias=False)
+        self.scale = alpha / rank
+        for parameter in self.frozen.parameters():
+            parameter.requires_grad = False
+
+    def forward(self, inputs: torch.Tensor) -> torch.Tensor:
+        return self.frozen(inputs) + self.adapter_b(self.adapter_a(inputs)) * self.scale
+
+
+class PlasticArithmeticModule(nn.Module, PlasticLearner):
+    name = "plastic_arithmetic_module"
+
+    def __init__(
+        self,
+        input_dim: int = 7,
+        hidden_dim: int = 48,
+        operations: int = 3,
+        output_scale: float = 144.0,
+        device: str = "cpu",
+    ) -> None:
+        super().__init__()
+        self.device = device
+        self.operations = operations
+        self.output_scale = output_scale
+        self.adapter = LowRankResidual(input_dim + operations, hidden_dim)
+        self.hidden = nn.Sequential(nn.Tanh(), nn.Linear(hidden_dim, hidden_dim), nn.Tanh())
+        self.direct_head = nn.Linear(input_dim + operations, operations)
+        self.residual_head = nn.Linear(hidden_dim, operations)
+        self.confidence_head = nn.Linear(hidden_dim, 1)
+        self.loss_fn = nn.SmoothL1Loss()
+        self.to(self.device)
+        self.optimizer = torch.optim.AdamW(self.trainable_parameters(), lr=2e-3, weight_decay=1e-4)
+        self._initial_trainable_state = deepcopy(self._trainable_state_dict())
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name, "operations": self.operations, "trainable_parameters": sum(p.numel() for p in self.trainable_parameters())}
+
+    def predict(self, semantic_state: SemanticState) -> CoreInference:
+        batch = self._batch_from_semantic_state(semantic_state)
+        predictions, confidence = self._forward(batch.features, batch.operation_ids)
+        value = float(predictions.squeeze(0).detach().cpu().item())
+        confidence_score = float(confidence.squeeze(0).detach().cpu().item())
+        return CoreInference(
+            prediction=value,
+            confidence=max(0.01, min(0.999, confidence_score)),
+            explanation=f"Plastic arithmetic pathway predicted {value:.3f} for operation {semantic_state.metadata['operation']}.",
+            artifacts={"raw_prediction": value, "confidence": confidence_score},
+        )
+
+    def train_step(self, batch: NumericBatch, replay_batch: Optional[NumericBatch] = None) -> Dict[str, float]:
+        self.train()
+        features = batch.features
+        operation_ids = batch.operation_ids
+        targets = batch.targets
+        replay_ratio = 0.0
+        if replay_batch is not None and replay_batch.targets is not None:
+            replay_ratio = len(replay_batch.targets) / max(len(targets), 1)
+            features = torch.cat([features, replay_batch.features], dim=0)
+            operation_ids = torch.cat([operation_ids, replay_batch.operation_ids], dim=0)
+            targets = torch.cat([targets, replay_batch.targets], dim=0)
+
+        predictions, confidence = self._forward(features, operation_ids)
+        normalized_targets = targets / self.output_scale
+        main_loss = self.loss_fn(predictions / self.output_scale, normalized_targets)
+        confidence_loss = F.mse_loss(confidence, torch.exp(-torch.abs(predictions - targets) / self.output_scale))
+        stability_penalty = 5e-4 * self.parameter_drift()
+        loss = main_loss + 0.15 * confidence_loss + stability_penalty
+
+        self.optimizer.zero_grad()
+        loss.backward()
+        nn.utils.clip_grad_norm_(list(self.trainable_parameters()), max_norm=1.0)
+        self.optimizer.step()
+
+        mae = torch.mean(torch.abs(predictions - targets)).item()
+        accuracy = torch.mean((torch.abs(predictions - targets) < 0.5).float()).item()
+        return {
+            "loss": float(loss.item()),
+            "mae": float(mae),
+            "accuracy": float(accuracy),
+            "replay_ratio": float(replay_ratio),
+            "plastic_norm": float(self.parameter_drift()),
+            "stable_drift": 0.0,
+        }
+
+    def parameter_drift(self) -> float:
+        initial = self._initial_trainable_state
+        total = 0.0
+        for name, current in self._trainable_state_dict().items():
+            total += torch.norm(current - initial[name]).item()
+        return total
+
+    def trainable_parameters(self):
+        return (parameter for parameter in self.parameters() if parameter.requires_grad)
+
+    def _forward(self, features: torch.Tensor, operation_ids: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        op_one_hot = F.one_hot(operation_ids, num_classes=self.operations).float()
+        merged = torch.cat([features, op_one_hot], dim=-1)
+        hidden = self.hidden(self.adapter(merged))
+        outputs = self.direct_head(merged) + 0.35 * self.residual_head(hidden)
+        gathered = outputs.gather(1, operation_ids.unsqueeze(1)).squeeze(1) * self.output_scale
+        confidence = torch.sigmoid(self.confidence_head(hidden)).squeeze(1)
+        return gathered, confidence
+
+    def _batch_from_semantic_state(self, semantic_state: SemanticState) -> NumericBatch:
+        features = semantic_state.metadata["numeric_features"].float().to(self.device).unsqueeze(0)
+        operation_id = torch.tensor([semantic_state.metadata["operation_id"]], dtype=torch.long, device=self.device)
+        target = semantic_state.metadata.get("target")
+        targets = None
+        if target is not None:
+            targets = torch.tensor([float(target)], dtype=torch.float32, device=self.device)
+        return NumericBatch(features=features, operation_ids=operation_id, targets=targets)
+
+    def _trainable_state_dict(self) -> Dict[str, torch.Tensor]:
+        return {
+            name: tensor.detach().clone()
+            for name, tensor in self.state_dict().items()
+            if self.state_dict()[name].dtype.is_floating_point and self._is_trainable_name(name)
+        }
+
+    def _is_trainable_name(self, name: str) -> bool:
+        if name.startswith("adapter.frozen"):
+            return False
+        return True

cognitive_engine/api/__init__.py

@@ -0,0 +1,2 @@
+"""Service layer interfaces."""
+

cognitive_engine/api/service.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from cognitive_engine.core.engine import CognitiveEngine
+
+
+class CognitiveAPIService:
+    def __init__(self, engine: CognitiveEngine) -> None:
+        self.engine = engine
+
+    def ingest_text(self, text: str) -> Dict[str, Any]:
+        response = self.engine.process(text, allow_learning=True)
+        return self._serialize(response)
+
+    def ask_text(self, text: str) -> Dict[str, Any]:
+        response = self.engine.process(text, allow_learning=False)
+        return self._serialize(response)
+
+    def train_numeric(self, a: float, b: float, operation: str, target: float) -> Dict[str, Any]:
+        response = self.engine.process(
+            {"modality": "numeric", "a": a, "b": b, "operation": operation, "target": target},
+            allow_learning=True,
+        )
+        return self._serialize(response)
+
+    def infer_numeric(self, a: float, b: float, operation: str) -> Dict[str, Any]:
+        response = self.engine.process({"modality": "numeric", "a": a, "b": b, "operation": operation}, allow_learning=False)
+        return self._serialize(response)
+
+    def _serialize(self, response: Any) -> Dict[str, Any]:
+        return {
+            "text": response.text,
+            "importance_action": response.importance.action,
+            "importance_score": response.importance.importance_score,
+            "confidence_score": response.inference.confidence,
+            "learning_applied": response.learning_applied,
+            "trace_count": len(response.traces),
+            "memory_snapshot": self.engine.snapshot(),
+        }
+

cognitive_engine/compression/__init__.py

@@ -0,0 +1,2 @@
+"""Knowledge compression modules."""
+

cognitive_engine/compression/knowledge_compressor.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+from uuid import uuid4
+
+from cognitive_engine.core.types import CompressedKnowledge, ImportanceAssessment, SemanticState, tensor_to_numpy
+from cognitive_engine.interfaces.base import KnowledgeCompressor
+
+
+class SemanticKnowledgeCompressor(KnowledgeCompressor):
+    name = "semantic_knowledge_compressor"
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name}
+
+    def compress(self, semantic_state: SemanticState, importance: ImportanceAssessment) -> CompressedKnowledge:
+        concepts = [concept.label for concept in semantic_state.concepts]
+        relations = self._build_relations(semantic_state, concepts)
+        summary = self._rewrite_summary(semantic_state, concepts, importance.action)
+        return CompressedKnowledge(
+            record_id=str(uuid4()),
+            source_type=semantic_state.modality,
+            summary=summary,
+            concepts=concepts,
+            relations=relations,
+            embedding=tensor_to_numpy(semantic_state.pooled_embedding.float()),
+            importance=importance.importance_score,
+            confidence=importance.confidence_score,
+            provenance={"intent": semantic_state.intent, "compressed_context": semantic_state.compressed_context},
+            metadata={"action": importance.action, "raw_modality": semantic_state.modality},
+        )
+
+    def _build_relations(self, semantic_state: SemanticState, concepts: List[str]) -> List[Tuple[str, str, str]]:
+        if len(concepts) < 2:
+            return [(concepts[0], semantic_state.intent, semantic_state.compressed_context)] if concepts else []
+        root = concepts[0]
+        return [(root, semantic_state.intent, concept) for concept in concepts[1:4]]
+
+    def _rewrite_summary(self, semantic_state: SemanticState, concepts: List[str], action: str) -> str:
+        if semantic_state.modality == "numeric":
+            a = semantic_state.metadata["a"]
+            b = semantic_state.metadata["b"]
+            op = semantic_state.metadata["operation"]
+            return f"Arithmetic pattern observed: {a:g} {op} {b:g} with action={action}"
+        concept_text = ", ".join(concepts[:4]) if concepts else semantic_state.compressed_context
+        if semantic_state.intent == "preference":
+            return f"User preference extracted: {concept_text}"
+        if semantic_state.intent == "correction":
+            return f"Correction compressed: {concept_text}"
+        if semantic_state.intent == "knowledge_share":
+            return f"Knowledge compressed: {concept_text}"
+        return f"Contextual memory: {semantic_state.compressed_context}"
+

cognitive_engine/compression/semantic_compressor_v2.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+from uuid import uuid4
+
+from cognitive_engine.compression.knowledge_compressor import SemanticKnowledgeCompressor
+from cognitive_engine.core.types import (
+    CompressionBundle,
+    GraphEdge,
+    GraphNode,
+    GraphPatch,
+    ImportanceAssessment,
+    KnowledgeTriple,
+    PreferenceRecord,
+    ProcedureMemory,
+    SemanticState,
+)
+
+
+class SemanticCompressorV2(SemanticKnowledgeCompressor):
+    name = "semantic_compressor_v2"
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name, "base": "semantic_knowledge_compressor"}
+
+    def compress_v2(self, semantic_state: SemanticState, importance: ImportanceAssessment, project_id: str = "global") -> CompressionBundle:
+        knowledge = self.compress(semantic_state, importance)
+        concepts = [concept.label for concept in semantic_state.concepts]
+        triples = self._triples(semantic_state, concepts)
+        graph_patch = self._graph_patch(semantic_state, concepts, triples, project_id)
+        preferences = self._preferences(semantic_state, concepts)
+        procedures = self._procedures(semantic_state, concepts)
+        return CompressionBundle(
+            compressed_knowledge=[knowledge],
+            triples=triples,
+            graph_patch=graph_patch,
+            preferences=preferences,
+            procedures=procedures,
+            validation_requests=[] if importance.confidence_score > 0.65 else [f"Validate low confidence memory: {knowledge.summary}"],
+        )
+
+    def _triples(self, semantic_state: SemanticState, concepts: List[str]) -> List[KnowledgeTriple]:
+        triples: List[KnowledgeTriple] = []
+        if not concepts:
+            return triples
+        subject = concepts[0]
+        for concept in concepts[1:5]:
+            triples.append(KnowledgeTriple(subject=subject, relation=semantic_state.intent, object=concept, confidence=0.75))
+        if semantic_state.intent == "preference":
+            triples.append(KnowledgeTriple(subject="user", relation="prefers", object=", ".join(concepts[:4]), confidence=0.82))
+        return triples
+
+    def _graph_patch(self, semantic_state: SemanticState, concepts: List[str], triples: List[KnowledgeTriple], project_id: str) -> GraphPatch:
+        nodes: Dict[str, GraphNode] = {}
+        edges: List[GraphEdge] = []
+
+        def node(label: str, node_type: str) -> GraphNode:
+            key = f"{node_type}:{label}".lower()
+            if key not in nodes:
+                nodes[key] = GraphNode(node_id=str(uuid4()), node_type=node_type, label=label, project_id=project_id, confidence=0.75)
+            return nodes[key]
+
+        intent_node = node(semantic_state.intent, "Concept")
+        for concept in concepts:
+            concept_node = node(concept, "Concept")
+            edges.append(
+                GraphEdge(
+                    edge_id=str(uuid4()),
+                    source_id=intent_node.node_id,
+                    target_id=concept_node.node_id,
+                    relation="mentions",
+                    confidence=0.7,
+                )
+            )
+        for triple in triples:
+            source = node(triple.subject, "Concept")
+            target = node(triple.object, "Concept")
+            edges.append(
+                GraphEdge(
+                    edge_id=str(uuid4()),
+                    source_id=source.node_id,
+                    target_id=target.node_id,
+                    relation=triple.relation,
+                    confidence=triple.confidence,
+                )
+            )
+        return GraphPatch(nodes=list(nodes.values()), edges=edges, source="semantic_compressor_v2")
+
+    def _preferences(self, semantic_state: SemanticState, concepts: List[str]) -> List[PreferenceRecord]:
+        if semantic_state.intent != "preference":
+            return []
+        value = ", ".join(concepts[:5]) if concepts else semantic_state.compressed_context
+        return [PreferenceRecord(key="user.preference", value=value, confidence=0.82, source="semantic_compressor_v2")]
+
+    def _procedures(self, semantic_state: SemanticState, concepts: List[str]) -> List[ProcedureMemory]:
+        lowered = semantic_state.compressed_context.lower()
+        if not any(marker in lowered for marker in ["fix", "debug", "test", "error", "bug", "correccion", "corrige"]):
+            return []
+        title = f"Procedure from {semantic_state.intent}: {', '.join(concepts[:3])}"
+        steps = [
+            "Inspect the relevant project graph nodes.",
+            "Reproduce the observed issue or requirement.",
+            "Apply the smallest compatible change.",
+            "Run focused validation before broad validation.",
+        ]
+        return [
+            ProcedureMemory(
+                procedure_id=str(uuid4()),
+                title=title,
+                steps=steps,
+                domains=concepts[:5],
+                confidence=0.68,
+            )
+        ]
+

cognitive_engine/config/__init__.py

@@ -0,0 +1,2 @@
+"""Configuration schemas and loaders."""
+

cognitive_engine/config/loader.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Dict, Type, TypeVar
+
+import yaml
+
+from cognitive_engine.config.schema import EngineConfig, MemoryConfig, NumericDemoConfig, ThresholdConfig
+
+
+T = TypeVar("T")
+
+
+def _merge_dicts(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _merge_dicts(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _construct(dataclass_type: Type[T], data: Dict[str, Any]) -> T:
+    if dataclass_type is EngineConfig:
+        thresholds = _construct(ThresholdConfig, data.get("thresholds", {}))
+        memory = _construct(MemoryConfig, data.get("memory", {}))
+        numeric_demo = _construct(NumericDemoConfig, data.get("numeric_demo", {}))
+        payload = {**data, "thresholds": thresholds, "memory": memory, "numeric_demo": numeric_demo}
+        return dataclass_type(**payload)
+    return dataclass_type(**data)
+
+
+def load_engine_config(path: str | Path | None = None) -> EngineConfig:
+    defaults = asdict(EngineConfig())
+    if path is None:
+        return EngineConfig()
+
+    config_path = Path(path)
+    override = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    merged = _merge_dicts(defaults, override)
+    return _construct(EngineConfig, merged)
+

cognitive_engine/config/schema.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class ThresholdConfig:
+    learn: float = 0.62
+    reinforce: float = 0.75
+    consolidate: float = 0.82
+    uncertainty: float = 0.45
+    contradiction: float = 0.55
+
+
+@dataclass
+class MemoryConfig:
+    short_term_capacity: int = 24
+    episodic_capacity: int = 128
+    semantic_capacity: int = 512
+    replay_capacity: int = 512
+    retrieval_top_k: int = 5
+    consolidation_interval: int = 10
+
+
+@dataclass
+class NumericDemoConfig:
+    operations: List[str] = field(default_factory=lambda: ["add", "sub", "mul"])
+    max_operand: int = 12
+    train_size: int = 2048
+    val_size: int = 512
+    batch_size: int = 64
+    epochs: int = 25
+    replay_batch_size: int = 32
+
+
+@dataclass
+class EngineConfig:
+    seed: int = 13
+    device: str = "cpu"
+    thresholds: ThresholdConfig = field(default_factory=ThresholdConfig)
+    memory: MemoryConfig = field(default_factory=MemoryConfig)
+    numeric_demo: NumericDemoConfig = field(default_factory=NumericDemoConfig)
+    language_hints: Dict[str, str] = field(default_factory=lambda: {"default": "multilingual-lite"})
+

cognitive_engine/consolidation/__init__.py

@@ -0,0 +1,2 @@
+"""Consolidation services."""
+

cognitive_engine/consolidation/engine.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from cognitive_engine.core.types import ConsolidationReport
+from cognitive_engine.interfaces.base import Consolidator
+
+
+class BackgroundConsolidationEngine(Consolidator):
+    name = "background_consolidation_engine"
+
+    def __init__(self, memory_system: Any, replay_buffer: Any) -> None:
+        self.memory_system = memory_system
+        self.replay_buffer = replay_buffer
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name}
+
+    def run(self) -> ConsolidationReport:
+        report = self.memory_system.consolidate()
+        if hasattr(self.replay_buffer, "rescale"):
+            report.replay_reweighted = self.replay_buffer.rescale()
+        report.notes += " Replay priorities were decayed to maintain balanced rehearsal."
+        return report
+

cognitive_engine/consolidation/engine_v2.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from cognitive_engine.core.types import ConsolidationReport
+from cognitive_engine.interfaces.base import Consolidator
+
+
+class CognitiveConsolidationEngineV2(Consolidator):
+    name = "cognitive_consolidation_engine_v2"
+
+    def __init__(self, memory_system: Any, replay_buffer: Any) -> None:
+        self.memory_system = memory_system
+        self.replay_buffer = replay_buffer
+        self.cycles = 0
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name, "cycles": self.cycles}
+
+    def run(self) -> ConsolidationReport:
+        self.cycles += 1
+        base_report = self.memory_system.consolidate()
+        graph_snapshot = {}
+        if hasattr(self.memory_system, "graph_memory"):
+            graph_snapshot = self.memory_system.graph_memory.snapshot()
+        replay_reweighted = 0
+        if hasattr(self.replay_buffer, "rescale"):
+            replay_reweighted = self.replay_buffer.rescale(0.985)
+        notes = (
+            "V2 light sleep consolidation completed: semantic merge, graph snapshot, replay decay, "
+            f"graph_nodes={graph_snapshot.get('nodes', 0)}, graph_edges={graph_snapshot.get('edges', 0)}."
+        )
+        return ConsolidationReport(
+            merged_records=base_report.merged_records,
+            pruned_records=base_report.pruned_records,
+            replay_reweighted=replay_reweighted,
+            notes=notes,
+        )
+

cognitive_engine/context/__init__.py

@@ -0,0 +1,2 @@
+"""Long-context composition and evidence packaging."""
+

cognitive_engine/context/long_context.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List
+
+from cognitive_engine.core.types import ContextPackage, MemoryBundleV2, SemanticStateV2
+
+
+class LongContextManager:
+    name = "long_context_manager"
+
+    def __init__(self, default_budget: int = 32768) -> None:
+        self.default_budget = default_budget
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": self.name, "default_budget": self.default_budget}
+
+    def compose(self, request: Dict[str, Any]) -> ContextPackage:
+        state: SemanticStateV2 = request["semantic_state"]
+        memory: MemoryBundleV2 = request["memory_bundle"]
+        budget = int(request.get("context_budget", self.default_budget))
+        specialist_context = request.get("specialist_context", [])
+        sections: Dict[str, str] = {}
+        sections["task"] = state.compressed_context
+        sections["working_memory"] = str(memory.working_memory)
+        sections["semantic_memory"] = "\n".join(record.summary for record in memory.semantic_long_term[:8])
+        sections["episodic_memory"] = "\n".join(record.summary for record in memory.episodic[:5])
+        sections["project_memory"] = "\n".join(
+            f"{record.project_id}: files={record.files_indexed}, deps={', '.join(record.dependencies[:8])}"
+            for record in memory.project
+        )
+        sections["procedural_memory"] = "\n".join(
+            f"{procedure.title}: {'; '.join(procedure.steps[:3])}" for procedure in memory.procedural
+        )
+        if memory.graph_subgraph:
+            nodes = ", ".join(f"{node.node_type}:{node.label}" for node in memory.graph_subgraph.nodes[:20])
+            edges = ", ".join(f"{edge.relation}" for edge in memory.graph_subgraph.edges[:20])
+            sections["graph_memory"] = f"nodes={nodes}\nedges={edges}\n{memory.graph_subgraph.rationale}"
+        sections["preferences"] = "\n".join(f"{pref.key}: {pref.value}" for pref in memory.preferences)
+        sections["specialists"] = "\n".join(str(item) for item in specialist_context)
+        prompt = self._fit_budget(sections, budget)
+        return ContextPackage(prompt=prompt, evidence_ids=[], token_estimate=self._estimate_tokens(prompt), sections=sections)
+
+    def _fit_budget(self, sections: Dict[str, str], budget: int) -> str:
+        parts = []
+        remaining = budget
+        for name, content in sections.items():
+            if not content:
+                continue
+            text = f"[{name}]\n{content.strip()}"
+            tokens = self._estimate_tokens(text)
+            if tokens > remaining:
+                approx_chars = max(0, remaining * 4)
+                text = text[:approx_chars]
+                tokens = self._estimate_tokens(text)
+            if tokens <= remaining and text.strip():
+                parts.append(text)
+                remaining -= tokens
+            if remaining <= 0:
+                break
+        return "\n\n".join(parts)
+
+    def _estimate_tokens(self, text: str) -> int:
+        return max(1, len(text) // 4)
+

cognitive_engine/core/__init__.py

@@ -0,0 +1,2 @@
+"""Core engine primitives."""
+