meta-reasoning 0.0.1__py3-none-any.whl

meta_reasoning/__init__.py

@@ -0,0 +1,41 @@
+"""
+Meta-Reasoning SDK
+
+Reasoning is not a property of the model —
+it is an emergent dynamic of external control.
+"""
+
+from .controller import CognitiveController
+from .engine import CognitiveEngine, CycleResult, EngineResult
+from .ledger import EpistemicLedger
+from .metrics import compute_metrics
+from .mutations import generate_mutations
+from .substrate import LLMBackend, Substrate
+from .types import (
+    CognitiveMetrics,
+    CognitiveMove,
+    LedgerEntry,
+    Mutation,
+    MutationType,
+    ReasoningTrace,
+    StructuredOutput,
+)
+
+__all__ = [
+    "CognitiveController",
+    "CognitiveEngine",
+    "CognitiveMetrics",
+    "CognitiveMove",
+    "CycleResult",
+    "EngineResult",
+    "EpistemicLedger",
+    "LedgerEntry",
+    "LLMBackend",
+    "Mutation",
+    "MutationType",
+    "ReasoningTrace",
+    "StructuredOutput",
+    "Substrate",
+    "compute_metrics",
+    "generate_mutations",
+]

meta_reasoning/controller.py

@@ -0,0 +1,97 @@
+"""
+Cognitive Controller (Level 2) — the heart of the SDK.
+
+The controller is semantically blind. It does NOT evaluate whether
+a response is "correct". It observes:
+  - form
+  - trajectory
+  - redundancy
+  - stall
+  - premature convergence
+
+It is a conductor, a coach, a theatre director.
+It does not play the instrument.
+"""
+
+from __future__ import annotations
+
+from .ledger import EpistemicLedger
+from .metrics import compute_metrics
+from .mutations import generate_mutations
+from .types import (
+    CognitiveMetrics,
+    LedgerEntry,
+    Mutation,
+    ReasoningTrace,
+    StructuredOutput,
+)
+
+
+class CognitiveController:
+    """Semantically-blind governor of reasoning dynamics."""
+
+    def __init__(
+        self,
+        ledger: EpistemicLedger | None = None,
+        max_violations: int = 2,
+    ) -> None:
+        self._ledger = ledger or EpistemicLedger()
+        self._max_violations = max_violations
+        self._cycle = 0
+        self._active_mutations: list[Mutation] = []
+
+    @property
+    def ledger(self) -> EpistemicLedger:
+        return self._ledger
+
+    @property
+    def cycle(self) -> int:
+        return self._cycle
+
+    @property
+    def active_mutations(self) -> list[Mutation]:
+        return list(self._active_mutations)
+
+    def observe(self, output: StructuredOutput) -> CognitiveMetrics:
+        """Observe an LLM output and compute cognitive metrics."""
+        history = [e.trace for e in self._ledger.entries]
+        return compute_metrics(output.reasoning_trace, history, self._active_mutations)
+
+    def decide(self, output: StructuredOutput, metrics: CognitiveMetrics) -> str:
+        """Decide the outcome: 'continued', 'failed', or 'terminated'.
+        Record the cycle in the ledger. Return the outcome."""
+        self._cycle += 1
+        failure_reason = None
+
+        if metrics.constraint_violations > self._max_violations:
+            outcome = "failed"
+            failure_reason = f"Too many constraint violations ({metrics.constraint_violations})"
+        elif metrics.strategy_repetition >= 1.0 and self._cycle > 2:
+            outcome = "failed"
+            failure_reason = "Complete strategy repetition — cognitive stall"
+        else:
+            outcome = "continued"
+
+        entry = LedgerEntry(
+            cycle=self._cycle,
+            trace=output.reasoning_trace,
+            metrics=metrics,
+            mutations_applied=list(self._active_mutations),
+            outcome=outcome,
+            failure_reason=failure_reason,
+        )
+        self._ledger.record(entry)
+
+        # Generate next mutations based on what we observed
+        self._active_mutations = generate_mutations(metrics, self._cycle)
+
+        return outcome
+
+    def get_mutations(self) -> list[Mutation]:
+        """Return the current set of mutations to impose on the next generation."""
+        return list(self._active_mutations)
+
+    def reset(self) -> None:
+        """Reset cycle counter and mutations (ledger is preserved)."""
+        self._cycle = 0
+        self._active_mutations = []

meta_reasoning/engine.py

@@ -0,0 +1,106 @@
+"""
+Cognitive Engine — the governed reasoning loop.
+
+This is NOT an agent. There is no autonomous decision-making.
+There is a governed cognitive loop where linguistic generation is
+continuously deformed by external control that does not participate
+in semantic production.
+
+Loop:
+  1. Substrate generates structured output under constraints
+  2. Controller observes the cognitive form (not content)
+  3. Controller decides: continue, fail, or terminate
+  4. Controller generates mutations for the next cycle
+  5. Repeat until termination or max cycles
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .controller import CognitiveController
+from .ledger import EpistemicLedger
+from .substrate import LLMBackend, Substrate
+from .types import CognitiveMetrics, StructuredOutput
+
+
+@dataclass
+class CycleResult:
+    """Result of a single cognitive cycle."""
+    cycle: int
+    output: StructuredOutput
+    metrics: CognitiveMetrics
+    outcome: str
+
+
+@dataclass
+class EngineResult:
+    """Result of a complete reasoning session."""
+    cycles: list[CycleResult] = field(default_factory=list)
+    final_outcome: str = "not_started"
+
+    @property
+    def final_output(self) -> StructuredOutput | None:
+        return self.cycles[-1].output if self.cycles else None
+
+
+class CognitiveEngine:
+    """Orchestrates the governed cognitive loop."""
+
+    def __init__(
+        self,
+        backend: LLMBackend,
+        max_cycles: int = 6,
+        max_violations: int = 2,
+    ) -> None:
+        self._substrate = Substrate(backend)
+        self._ledger = EpistemicLedger()
+        self._controller = CognitiveController(
+            ledger=self._ledger,
+            max_violations=max_violations,
+        )
+        self._max_cycles = max_cycles
+
+    @property
+    def ledger(self) -> EpistemicLedger:
+        return self._ledger
+
+    @property
+    def controller(self) -> CognitiveController:
+        return self._controller
+
+    def run(self, task: str) -> EngineResult:
+        """Execute the full governed reasoning loop on a task."""
+        result = EngineResult()
+
+        for _ in range(self._max_cycles):
+            mutations = self._controller.get_mutations()
+            history_summary = self._ledger.summary_for_prompt()
+
+            output = self._substrate.generate(
+                task=task,
+                mutations=mutations,
+                history_summary=history_summary or None,
+            )
+
+            metrics = self._controller.observe(output)
+            outcome = self._controller.decide(output, metrics)
+
+            cycle_result = CycleResult(
+                cycle=self._controller.cycle,
+                output=output,
+                metrics=metrics,
+                outcome=outcome,
+            )
+            result.cycles.append(cycle_result)
+
+            if outcome == "failed":
+                result.final_outcome = "failed"
+                return result
+
+            if outcome == "terminated":
+                result.final_outcome = "terminated"
+                return result
+
+        result.final_outcome = "max_cycles_reached"
+        return result

meta_reasoning/ledger.py

@@ -0,0 +1,67 @@
+"""
+Epistemic Ledger (Level 3) — structural memory.
+
+Not "memory" in the RAG sense. This is:
+- a trace of cognitive transformations
+- a history of strategies used
+- a map of failures
+
+Its purpose: never return to the same mental state.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .types import CognitiveMove, LedgerEntry
+
+
+class EpistemicLedger:
+    """Append-only cognitive trajectory store."""
+
+    def __init__(self) -> None:
+        self._entries: list[LedgerEntry] = []
+
+    @property
+    def entries(self) -> list[LedgerEntry]:
+        return list(self._entries)
+
+    @property
+    def size(self) -> int:
+        return len(self._entries)
+
+    def record(self, entry: LedgerEntry) -> None:
+        self._entries.append(entry)
+
+    def failures(self) -> list[LedgerEntry]:
+        return [e for e in self._entries if e.outcome == "failed"]
+
+    def strategies_tried(self) -> list[tuple[CognitiveMove, ...]]:
+        return [tuple(e.trace.moves) for e in self._entries]
+
+    def summary_for_prompt(self, max_entries: int = 5) -> str:
+        """Generate a concise summary for the substrate to avoid repetition."""
+        if not self._entries:
+            return ""
+        recent = self._entries[-max_entries:]
+        lines = []
+        for e in recent:
+            moves_str = ", ".join(m.value for m in e.trace.moves)
+            status = e.outcome
+            if e.failure_reason:
+                status += f" ({e.failure_reason})"
+            lines.append(f"  Cycle {e.cycle}: [{moves_str}] → {status}")
+        return "\n".join(lines)
+
+    def save(self, path: str | Path) -> None:
+        path = Path(path)
+        data = [e.model_dump(mode="json") for e in self._entries]
+        path.write_text(json.dumps(data, indent=2))
+
+    def load(self, path: str | Path) -> None:
+        path = Path(path)
+        if not path.exists():
+            return
+        data = json.loads(path.read_text())
+        self._entries = [LedgerEntry.model_validate(d) for d in data]

meta_reasoning/metrics.py

@@ -0,0 +1,99 @@
+"""
+Cognitive Metrics — the semantically-blind observation layer.
+
+These metrics do NOT measure accuracy, correctness, or truth.
+They measure form, trajectory, redundancy, stall, and premature convergence.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+
+from .types import CognitiveMetrics, CognitiveMove, Mutation, MutationType, ReasoningTrace
+
+
+def compute_metrics(
+    trace: ReasoningTrace,
+    history: list[ReasoningTrace],
+    active_mutations: list[Mutation],
+) -> CognitiveMetrics:
+    """Compute all cognitive metrics for a single reasoning trace."""
+    return CognitiveMetrics(
+        entropy=_move_entropy(trace.moves),
+        strategy_repetition=_strategy_repetition(trace, history),
+        depth_without_novelty=_depth_without_novelty(trace, history),
+        constraint_violations=_count_violations(trace, active_mutations),
+        premature_closure=_premature_closure(trace),
+        dominant_move=_dominant_move(trace.moves),
+    )
+
+
+def _move_entropy(moves: list[CognitiveMove]) -> float:
+    if not moves:
+        return 0.0
+    counts = Counter(moves)
+    total = len(moves)
+    return -sum((c / total) * math.log2(c / total) for c in counts.values())
+
+
+def _strategy_repetition(trace: ReasoningTrace, history: list[ReasoningTrace]) -> float:
+    if not history:
+        return 0.0
+    current = tuple(trace.moves)
+    matches = sum(1 for h in history if tuple(h.moves) == current)
+    return matches / len(history)
+
+
+def _depth_without_novelty(trace: ReasoningTrace, history: list[ReasoningTrace]) -> int:
+    if not history:
+        return 0
+    seen_types = set()
+    for h in history:
+        seen_types.update(h.moves)
+    novel = set(trace.moves) - seen_types
+    if novel:
+        return 0
+    # count consecutive history entries also without novelty (backwards)
+    streak = 1
+    all_seen = set()
+    for h in reversed(history):
+        all_seen.update(h.moves)
+        remaining = set(trace.moves) - all_seen
+        if not remaining:
+            streak += 1
+        else:
+            break
+    return streak
+
+
+def _count_violations(trace: ReasoningTrace, mutations: list[Mutation]) -> int:
+    violations = 0
+    for m in mutations:
+        if m.type == MutationType.BAN and m.target in trace.moves:
+            violations += 1
+        if m.type == MutationType.REQUIRE and m.target not in trace.moves:
+            violations += 1
+        if m.type == MutationType.LIMIT_DEPTH and isinstance(m.parameter, int):
+            if trace.depth > m.parameter:
+                violations += 1
+    return violations
+
+
+def _premature_closure(trace: ReasoningTrace) -> float:
+    if not trace.moves:
+        return 0.0
+    unique_ratio = len(set(trace.moves)) / len(CognitiveMove)
+    depth_factor = min(trace.depth / 5, 1.0)
+    # high closure = low diversity + low depth
+    return max(0.0, 1.0 - (unique_ratio * 0.6 + depth_factor * 0.4))
+
+
+def _dominant_move(moves: list[CognitiveMove]) -> CognitiveMove | None:
+    if not moves:
+        return None
+    counts = Counter(moves)
+    most_common, freq = counts.most_common(1)[0]
+    if freq / len(moves) > 0.5:
+        return most_common
+    return None

meta_reasoning/mutations.py

@@ -0,0 +1,98 @@
+"""
+Mutation Engine — generates cognitive mutations from observed metrics.
+
+The controller does not say "reason better".
+It says: "deduction is banned", "analogy is required", "compress to 2 concepts".
+Every mutation is a formal operator, not a suggestion.
+"""
+
+from __future__ import annotations
+
+from .types import CognitiveMetrics, CognitiveMove, Mutation, MutationType
+
+
+def generate_mutations(metrics: CognitiveMetrics, cycle: int) -> list[Mutation]:
+    """Produce a list of mutations based on current cognitive metrics.
+    Pressure increases with cycle count — improvisation through constraint."""
+    mutations: list[Mutation] = []
+
+    # Ban dominant strategy
+    if metrics.dominant_move:
+        mutations.append(Mutation(
+            type=MutationType.BAN,
+            target=metrics.dominant_move,
+            reason=f"Move '{metrics.dominant_move.value}' dominates ({cycle=})",
+        ))
+
+    # Low entropy → require a move not yet seen
+    if metrics.entropy < 1.5:
+        forced = _pick_absent_move(metrics)
+        if forced:
+            mutations.append(Mutation(
+                type=MutationType.REQUIRE,
+                target=forced,
+                reason=f"Low entropy ({metrics.entropy:.2f}), forcing diversity",
+            ))
+
+    # Strategy repetition → force inversion + ban most frequent move
+    if metrics.strategy_repetition > 0.0:
+        mutations.append(Mutation(
+            type=MutationType.INVERT_CAUSALITY,
+            reason=f"Strategy repetition ({metrics.strategy_repetition:.2f}), forcing inversion",
+        ))
+        mutations.append(Mutation(
+            type=MutationType.FORCE_COMPRESSION,
+            parameter=2,
+            reason=f"Strategy repetition — compress to break pattern",
+        ))
+
+    # Premature closure → require contradiction search
+    if metrics.premature_closure > 0.6:
+        mutations.append(Mutation(
+            type=MutationType.REQUIRE_CONTRADICTION,
+            reason=f"Premature closure score {metrics.premature_closure:.2f}",
+        ))
+
+    # Depth without novelty → compress
+    if metrics.depth_without_novelty >= 2:
+        mutations.append(Mutation(
+            type=MutationType.FORCE_COMPRESSION,
+            parameter=2,
+            reason=f"Depth without novelty = {metrics.depth_without_novelty}",
+        ))
+
+    # Progressive pressure: tighten depth limit over cycles
+    if cycle >= 2:
+        max_depth = max(2, 6 - cycle)
+        mutations.append(Mutation(
+            type=MutationType.LIMIT_DEPTH,
+            parameter=max_depth,
+            reason=f"Progressive pressure at {cycle=}",
+        ))
+
+    # Every cycle after the first: always perturb to prevent stasis
+    if cycle >= 1 and not mutations:
+        mutations.append(Mutation(
+            type=MutationType.REQUIRE,
+            target=_pick_absent_move(metrics) or CognitiveMove.NARRATIVE_SIMULATION,
+            reason="Baseline perturbation — no cycle without mutation",
+        ))
+
+    return mutations
+
+
+def _pick_absent_move(metrics: CognitiveMetrics) -> CognitiveMove | None:
+    """Pick a cognitive move that hasn't been dominant."""
+    candidates = [m for m in CognitiveMove if m != metrics.dominant_move]
+    # Prefer structurally disruptive moves
+    priority = [
+        CognitiveMove.CONTRADICTION,
+        CognitiveMove.ANALOGY,
+        CognitiveMove.ABDUCTION,
+        CognitiveMove.COMPRESSION,
+        CognitiveMove.INDUCTION,
+    ]
+    for p in priority:
+        if p in candidates:
+            return p
+    return candidates[0] if candidates else None

meta_reasoning/substrate.py

@@ -0,0 +1,119 @@
+"""
+Generative Substrate (Level 1) — the LLM interface.
+
+The model is stateless by design. It does not decide objectives, strategies,
+or validity. It is a linguistic machine, not a mind.
+This module handles prompt construction and structured output parsing.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol
+
+from .types import (
+    CognitiveMove,
+    Mutation,
+    ReasoningTrace,
+    StructuredOutput,
+)
+
+# ---------------------------------------------------------------------------
+# System prompt that enforces the structured output protocol
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """You are a generative substrate. You produce structured reasoning output.
+
+EVERY response MUST be valid JSON with this exact schema:
+{
+  "content": "<your answer>",
+  "reasoning_trace": {
+    "moves": ["<move1>", "<move2>", ...],
+    "depth": <integer>,
+    "confidence_markers": <integer>,
+    "abstraction_level": "<low|medium|high>"
+  }
+}
+
+Valid moves: assumption, deduction, induction, abduction, analogy, contradiction, enumeration, compression, narrative_simulation.
+
+You MUST classify every reasoning step you take using these moves.
+Do NOT add any text outside the JSON object."""
+
+
+class LLMBackend(Protocol):
+    """Protocol for any LLM backend (OpenAI, Anthropic, local, mock)."""
+    def generate(self, messages: list[dict[str, str]]) -> dict[str, Any]: ...
+
+
+class Substrate:
+    """Wraps an LLM backend, enforcing structured output and cognitive constraints."""
+
+    def __init__(self, backend: LLMBackend) -> None:
+        self._backend = backend
+
+    def generate(
+        self,
+        task: str,
+        mutations: list[Mutation] | None = None,
+        history_summary: str | None = None,
+    ) -> StructuredOutput:
+        messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+        if history_summary:
+            messages.append({
+                "role": "system",
+                "content": f"Cognitive history (avoid repeating these patterns):\n{history_summary}",
+            })
+
+        constraint_block = self._build_constraints(mutations or [])
+        user_content = f"{constraint_block}\n\nTask: {task}" if constraint_block else f"Task: {task}"
+        messages.append({"role": "user", "content": user_content})
+
+        raw = self._backend.generate(messages)
+        return self._parse(raw)
+
+    @staticmethod
+    def _build_constraints(mutations: list[Mutation]) -> str:
+        if not mutations:
+            return ""
+        lines = ["COGNITIVE CONSTRAINTS (you MUST obey these):"]
+        for i, m in enumerate(mutations, 1):
+            lines.append(f"  {i}. {m.to_prompt_constraint()}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _parse(raw: dict[str, Any]) -> StructuredOutput:
+        text = raw.get("content", "") or raw.get("text", "") or ""
+        # Try to extract JSON from the response
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            # Fallback: wrap raw text as unstructured output
+            return StructuredOutput(
+                content=text,
+                reasoning_trace=ReasoningTrace(
+                    moves=[CognitiveMove.ASSUMPTION],
+                    depth=1,
+                    confidence_markers=0,
+                    abstraction_level="low",
+                ),
+                raw=raw,
+            )
+
+        moves_raw = data.get("reasoning_trace", {}).get("moves", [])
+        valid_moves = []
+        for m in moves_raw:
+            try:
+                valid_moves.append(CognitiveMove(m))
+            except ValueError:
+                continue
+
+        trace = ReasoningTrace(
+            moves=valid_moves or [CognitiveMove.ASSUMPTION],
+            depth=data.get("reasoning_trace", {}).get("depth", 1),
+            confidence_markers=data.get("reasoning_trace", {}).get("confidence_markers", 0),
+            abstraction_level=data.get("reasoning_trace", {}).get("abstraction_level", "low"),
+        )
+
+        return StructuredOutput(content=data.get("content", text), reasoning_trace=trace, raw=raw)