thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/reasoning_plus/learning/embeddings.py

@@ -0,0 +1,209 @@
+"""
+thinkstack_core.reasoning_plus.learning.embeddings
+================================================
+Pluggable embedding backends for DRPL relevance.
+
+The default backend is keyword-based (no extra dependencies).  Users can opt
+into dense semantic embeddings by installing the optional ``embeddings`` extra:
+
+    pip install thinkstack-core[embeddings]
+
+and then configuring the backend:
+
+    thinkstack reasoning-plus config \
+        --learning-embedding-backend sentence_transformers \
+        --learning-embedding-model all-MiniLM-L6-v2
+
+Supported backends:
+- ``keyword``           — Jaccard similarity over extracted keywords (default)
+- ``sentence_transformers`` — cosine similarity over dense embeddings (local)
+- ``openai``            — cosine similarity over OpenAI embeddings (remote)
+"""
+from __future__ import annotations
+
+import logging
+import math
+from abc import ABC, abstractmethod
+from typing import Any
+
+from thinkstack_core.reasoning_plus.context import extract_keywords
+
+logger = logging.getLogger("thinkstack.reasoning_plus.learning")
+
+
+# ---------------------------------------------------------------------------
+# Base class
+# ---------------------------------------------------------------------------
+
+class EmbeddingBackend(ABC):
+    """Abstract embedding backend for DRPL relevance scoring."""
+
+    @abstractmethod
+    def encode(self, text: str) -> Any:
+        """Encode *text* into a backend-specific representation."""
+        ...
+
+    @abstractmethod
+    def similarity(self, a: Any, b: Any) -> float:
+        """Return a similarity score in [0, 1] for two encodings."""
+        ...
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier for this backend."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Keyword backend (default, no dependencies)
+# ---------------------------------------------------------------------------
+
+class KeywordEmbeddingBackend(EmbeddingBackend):
+    """Keyword-overlap backend that uses extracted concepts as a sparse vector."""
+
+    def __init__(self, max_keywords: int = 15) -> None:
+        self.max_keywords = max_keywords
+
+    def encode(self, text: str) -> set[str]:
+        return set(extract_keywords(text, max_keywords=self.max_keywords))
+
+    def similarity(self, a: set[str], b: set[str]) -> float:
+        if not a and not b:
+            return 0.0
+        overlap = len(a & b)
+        total = len(a | b)
+        return overlap / total if total else 0.0
+
+    @property
+    def name(self) -> str:
+        return "keyword"
+
+
+# ---------------------------------------------------------------------------
+# Dense-vector helpers
+# ---------------------------------------------------------------------------
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(x * x for x in b))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return max(0.0, min(1.0, dot / (norm_a * norm_b)))
+
+
+# ---------------------------------------------------------------------------
+# Sentence-transformers backend (optional)
+# ---------------------------------------------------------------------------
+
+class SentenceTransformerBackend(EmbeddingBackend):
+    """Local dense embedding backend via sentence-transformers."""
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as exc:
+            raise ImportError(
+                "sentence-transformers is not installed. "
+                "Install the embeddings extra: pip install thinkstack-core[embeddings]"
+            ) from exc
+        self._model = SentenceTransformer(model_name)
+        self._model_name = model_name
+
+    def encode(self, text: str) -> list[float]:
+        import numpy as np
+
+        vector = self._model.encode(text)
+        return vector.tolist()
+
+    def similarity(self, a: list[float], b: list[float]) -> float:
+        return _cosine_similarity(a, b)
+
+    @property
+    def name(self) -> str:
+        return "sentence_transformers"
+
+
+# ---------------------------------------------------------------------------
+# OpenAI backend (optional)
+# ---------------------------------------------------------------------------
+
+class OpenAIEmbeddingBackend(EmbeddingBackend):
+    """Remote dense embedding backend via OpenAI embeddings API."""
+
+    def __init__(
+        self,
+        model_name: str = "text-embedding-3-small",
+        api_key: str | None = None,
+    ) -> None:
+        try:
+            import openai
+        except ImportError as exc:
+            raise ImportError(
+                "openai is not installed. "
+                "Install the wrapper extra: pip install thinkstack-core[wrapper]"
+            ) from exc
+        self._client = openai.OpenAI(api_key=api_key)
+        self._model_name = model_name
+
+    def encode(self, text: str) -> list[float]:
+        response = self._client.embeddings.create(
+            input=text,
+            model=self._model_name,
+        )
+        return response.data[0].embedding
+
+    def similarity(self, a: list[float], b: list[float]) -> float:
+        return _cosine_similarity(a, b)
+
+    @property
+    def name(self) -> str:
+        return "openai"
+
+
+# ---------------------------------------------------------------------------
+# Fake backend (for tests)
+# ---------------------------------------------------------------------------
+
+class FakeEmbeddingBackend(EmbeddingBackend):
+    """Deterministic fake backend for unit tests."""
+
+    def __init__(self, embeddings: dict[str, list[float]] | None = None, dim: int = 8) -> None:
+        self._embeddings: dict[str, list[float]] = embeddings or {}
+        self._dim = dim
+
+    def encode(self, text: str) -> list[float]:
+        return self._embeddings.get(text, [0.0] * self._dim)
+
+    def similarity(self, a: list[float], b: list[float]) -> float:
+        return _cosine_similarity(a, b)
+
+    @property
+    def name(self) -> str:
+        return "fake"
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def get_embedding_backend(
+    name: str | None = None,
+    model_name: str | None = None,
+    max_keywords: int = 15,
+) -> EmbeddingBackend:
+    """
+    Return an embedding backend by name.
+
+    Supported names: ``keyword`` (default), ``sentence_transformers``,
+    ``sentence-transformers``, ``st``, ``openai``.
+    """
+    name = (name or "keyword").lower().strip().replace("-", "_")
+    if name in ("keyword", "keywords"):
+        return KeywordEmbeddingBackend(max_keywords=max_keywords)
+    if name in ("sentence_transformers", "sentence_transformer", "st"):
+        return SentenceTransformerBackend(model_name or "all-MiniLM-L6-v2")
+    if name == "openai":
+        return OpenAIEmbeddingBackend(model_name or "text-embedding-3-small")
+    raise ValueError(f"Unknown embedding backend: {name}")

thinkstack_core/reasoning_plus/learning/evolution.py

@@ -0,0 +1,119 @@
+"""
+thinkstack_core.reasoning_plus.learning.evolution
+================================================
+Learning evolution helpers: goal-change detection and confidence decay.
+
+Learnings change over time. A learning from week 1 may be superseded by a
+learning from week 3. When the project goal shifts, an older high-confidence
+learning may no longer be valid. And learnings that receive no feedback for
+extended periods should decay in confidence and eventually be marked stale.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+
+from thinkstack_core.reasoning_plus.learning.models import Learning
+
+logger = logging.getLogger("thinkstack.reasoning_plus.learning")
+
+
+# ---------------------------------------------------------------------------
+# Goal change detection
+# ---------------------------------------------------------------------------
+
+_GOAL_PATTERN = "GOAL:"
+
+
+def goal_changed_since(learning_id: str, gcc_dir: Path | str) -> bool:
+    """Return True if a goal-setting commit appears in the GCC event log.
+
+    Goal-setting commits are detected by the ``GOAL:`` prefix in the commit
+    message (the convention is ``thinkstack commit -m "GOAL: ..."``). The
+    ``learning_id`` is accepted for forward-compatibility (per-learning goal
+    tracking) but the current implementation checks for *any* goal commit in
+    the event log, which is sufficient for the resolution matrix.
+
+    If the event log exists but cannot be read (permissions, lock contention),
+    the function returns ``True`` as a conservative default — this ensures
+    conflicts are flagged for human review rather than auto-resolved with
+    stale information.
+    """
+    gcc_dir = Path(gcc_dir)
+    events_path = gcc_dir / "events.log.jsonl"
+    if not events_path.exists():
+        return False
+    try:
+        for line in events_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            message = event.get("message", "") or ""
+            if isinstance(message, str) and message.upper().startswith(_GOAL_PATTERN):
+                return True
+    except Exception as exc:
+        logger.warning("thinkstack: failed to read events log for goal change — %s", exc)
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Confidence decay
+# ---------------------------------------------------------------------------
+
+_DECAY_WEEKLY_AMOUNT = 0.05     # confidence -= 0.05 per week without feedback
+_DECAY_THRESHOLD_DAYS = 7       # start decaying after 7 days
+_STALE_THRESHOLD_DAYS = 30      # mark stale after 30 days
+
+
+def _days_since(ts: str) -> float:
+    """Return days elapsed since an ISO timestamp string."""
+    try:
+        dt = datetime.fromisoformat(ts)
+    except (TypeError, ValueError):
+        return 0.0
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return (datetime.now(timezone.utc) - dt).total_seconds() / 86400.0
+
+
+def apply_confidence_decay(
+    learning: Learning,
+    *,
+    now: datetime | None = None,
+) -> Learning:
+    """Apply time-based confidence decay to a learning in-place and return it.
+
+    Rules:
+    - ``"canon"`` learnings are immune (human-endorsed canonical rules).
+    - Already deprecated learnings are left as-is.
+    - After ``_STALE_THRESHOLD_DAYS`` (30) days without feedback: validity
+      becomes ``"stale"``.
+    - After ``_DECAY_THRESHOLD_DAYS`` (7) days: confidence decays by
+      ``_DECAY_WEEKLY_AMOUNT`` (0.05) per elapsed week, floored at 0.0.
+    """
+    if learning.type == "canon":
+        return learning
+    if learning.validity == "deprecated":
+        return learning
+
+    now = now or datetime.now(timezone.utc)
+    days = _days_since(learning.updated_at)
+
+    if days < _DECAY_THRESHOLD_DAYS:
+        return learning
+
+    weeks = int(days // 7)
+    learning.confidence = max(0.0, learning.confidence - weeks * _DECAY_WEEKLY_AMOUNT)
+
+    if days > _STALE_THRESHOLD_DAYS:
+        learning.validity = "stale"
+
+    learning.updated_at = now.isoformat()
+    return learning

thinkstack_core/reasoning_plus/learning/extractor.py

@@ -0,0 +1,271 @@
+"""
+thinkstack_core.reasoning_plus.learning.extractor
+===============================================
+Distill ReasoningCall records into reusable Learning objects.
+
+Two strategies are supported:
+
+1. **Rule-based** (default, no dependencies) — pair captured reasoning with the
+   observed outcome and synthesize a compact learning sentence.
+2. **LLM-based** (optional) — pass the reasoning, input, output, outcome, and
+   enriched extraction context to a small LLM prompt that returns a concise
+   learning summary.  The caller supplies the LLM client, so the core library
+   remains dependency-free.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+from thinkstack_core.reasoning_plus.context import extract_keywords
+from thinkstack_core.reasoning_plus.learning.context_collector import ExtractionContext
+from thinkstack_core.reasoning_plus.learning.models import Learning, ReasoningCall
+
+logger = logging.getLogger("thinkstack.reasoning_plus.learning")
+
+DEFAULT_EXTRACTION_PROMPT = """\
+You are distilling a previous reasoning step into a short, reusable insight.
+Given the reasoning, the action's input, its output, and the observed outcome,
+write one concise sentence that another AI agent could reuse when facing a
+similar situation.
+
+Outcome: {outcome}
+Name: {name}
+Input: {input}
+Output: {output}
+Reasoning: {reasoning}
+
+Insight:"""
+
+CONTEXT_AWARE_EXTRACTION_PROMPT = """\
+You are extracting learnings from an AI agent's reasoning step. The agent
+may have changed files, added or removed imports, and used specific libraries.
+
+{context_section}
+
+Agent reasoning:
+{reasoning}
+
+Extract what another AI agent should learn from this step. Classify as:
+- "prescription": Concrete, actionable recommendation (use library X, version Y, configure Z)
+- "pattern": General pattern that emerged (structuring code, error handling, etc.)
+- "avoid": Something that should NOT be done
+- "insight": Non-obvious observation about the codebase, architecture, or approach
+- "correction": A mistake that was made and then fixed
+- "confirm": A previously uncertain approach that proved correct
+
+Return a JSON object with the following structure:
+{{
+  "type": "<type>",
+  "content": "<one concise, actionable sentence>",
+  "trigger_concepts": ["<concept1>", "<concept2>"],
+  "confidence": <0.0-1.0>
+}}
+
+If the context shows a concrete library, framework, or tool being used,
+include "prescription" as the type and specify the exact library, version,
+and usage pattern in the content."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _type_for_outcome(outcome: str, context: ExtractionContext | None = None) -> str:
+    if context and context.is_significant():
+        if context.imports_added or context.libraries_used:
+            return "prescription"
+    if outcome == "success":
+        return "confirm"
+    if outcome == "failure":
+        return "correction"
+    if outcome == "partial":
+        return "insight"
+    return "insight"
+
+
+def _extract_concepts(call: ReasoningCall, context: ExtractionContext | None = None) -> list[str]:
+    concepts = set(extract_keywords(call.reasoning, max_keywords=10))
+    # Add import symbols as concepts for better cross-task matching.
+    # File names are intentionally NOT added — they cause near-identical
+    # learnings to diverge on file path alone, defeating deduplication.
+    if context:
+        for imp in context.imports_added[:3]:
+            concept = imp.rsplit(".", 1)[-1]
+            concepts.add(concept)
+    # Ensure we always have at least some concepts
+    if not concepts:
+        concepts = set(extract_keywords(call.input + " " + call.output, max_keywords=5))
+    return sorted(concepts)
+
+
+def _fallback_reasoning(call: ReasoningCall) -> str:
+    """When the call has no captured reasoning, synthesize a short summary."""
+    if call.outcome not in ("success", "failure"):
+        return ""
+    name = call.name or call.call_type
+    if call.outcome == "failure":
+        return f"{name} failed. Input: {call.input}. Output: {call.output}."
+    return f"{name} succeeded. Input: {call.input}. Output: {call.output}."
+
+
+def _compose_content_from_reasoning(call: ReasoningCall, reasoning: str, context: ExtractionContext | None = None) -> str:
+    reasoning = reasoning.strip().replace("\n", " ")
+    # Truncate very long reasoning: keep first 200 + last 200 chars
+    if len(reasoning) > 400:
+        reasoning = reasoning[:197].rstrip() + " ... " + reasoning[-200:].lstrip()
+
+    name = call.name or call.call_type
+
+    # Return clean reasoning content — no boilerplate prefixes.
+    # Context metadata (files, imports, libraries) goes into trigger_concepts.
+    return reasoning
+
+
+def _build_learning(call: ReasoningCall, reasoning: str, context: ExtractionContext | None = None) -> Learning:
+    """Build a single Learning object from a reasoning summary and optional extraction context."""
+    learning_type = _type_for_outcome(call.outcome, context)
+    content = _compose_content_from_reasoning(call, reasoning, context)
+    concepts = _extract_concepts(call, context)
+
+    # Start with moderate confidence so feedback can raise or lower it.
+    base_confidence = min(call.confidence, 0.8)
+
+    meta: dict[str, str] = {"call_type": call.call_type, "name": call.name, "outcome": call.outcome}
+    if context and context.is_significant():
+        meta["context_files"] = ",".join(context.files_changed[:5])
+        meta["context_imports"] = ",".join(context.imports_added[:5])
+
+    return Learning(
+        content=content,
+        type=learning_type,
+        trigger_concepts=concepts,
+        state_hash=call.state_hash,
+        confidence=base_confidence,
+        source_reasoning_ids=[call.id],
+        sensitivity=call.sensitivity,
+        meta=meta,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Rule-based extractor
+# ---------------------------------------------------------------------------
+
+class LearningExtractor:
+    """Extract learnings from a single reasoning call using lightweight rules."""
+
+    def extract(self, call: ReasoningCall, context: ExtractionContext | None = None) -> list[Learning]:
+        """
+        Return one or more Learning objects derived from the call.
+
+        If extraction context is provided, the rule-based extractor uses it to
+        determine whether the learning should be classified as a "prescription"
+        (when concrete imports, libraries, or file changes are detected).
+        """
+        reasoning = call.reasoning.strip()
+        if not reasoning:
+            reasoning = _fallback_reasoning(call)
+
+        if not reasoning:
+            return []
+
+        return [_build_learning(call, reasoning, context)]
+
+
+# Backwards-compatible alias
+RuleBasedLearningExtractor = LearningExtractor
+
+
+# ---------------------------------------------------------------------------
+# LLM-based extractor
+# ---------------------------------------------------------------------------
+
+class LLMBasedLearningExtractor(LearningExtractor):
+    """
+    Extract learnings by asking an LLM to summarize a reasoning call.
+
+    The caller supplies ``client``, a callable that takes a prompt string and
+    returns a completion string.  This keeps the core library free of any LLM
+    SDK dependency.
+
+    When ``context`` is provided (an ``ExtractionContext`` with files, imports,
+    and libraries), the extractor uses a richer prompt that generates concrete,
+    prescriptive learnings.
+    """
+
+    def __init__(
+        self,
+        client: Callable[[str], str],
+        prompt_template: str | None = None,
+        context_prompt_template: str | None = None,
+    ) -> None:
+        self._client = client
+        self._prompt_template = prompt_template or DEFAULT_EXTRACTION_PROMPT
+        self._context_prompt_template = context_prompt_template or CONTEXT_AWARE_EXTRACTION_PROMPT
+
+    def extract(self, call: ReasoningCall, context: ExtractionContext | None = None) -> list[Learning]:
+        """Use an LLM to summarize the reasoning; fall back to rule-based if the LLM fails."""
+        reasoning = call.reasoning.strip()
+        if not reasoning:
+            reasoning = _fallback_reasoning(call)
+
+        if not reasoning:
+            return []
+
+        prompt = self._build_prompt(call, reasoning, context)
+
+        try:
+            summary = self._client(prompt).strip()
+        except Exception as exc:
+            logger.warning("thinkstack: LLM-based extraction failed — %s", exc)
+            return [_build_learning(call, reasoning, context)]
+
+        if not summary:
+            return []
+
+        return [_build_learning(call, summary, context)]
+
+    def _build_prompt(self, call: ReasoningCall, reasoning: str, context: ExtractionContext | None) -> str:
+        """Build the extraction prompt, selecting context-aware or default template."""
+        if context and context.is_significant():
+            template = self._context_prompt_template
+            context_section = context.to_prompt_context()
+            return template.format(
+                context_section=context_section,
+                reasoning=reasoning,
+            )
+
+        return self._prompt_template.format(
+            reasoning=reasoning,
+            input=call.input,
+            output=call.output,
+            outcome=call.outcome,
+            name=call.name or call.call_type,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def make_extractor(
+    strategy: str = "rule",
+    llm_client: Callable[[str], str] | None = None,
+    context_prompt_template: str | None = None,
+) -> LearningExtractor:
+    """
+    Build a learning extractor for the given strategy.
+
+    Strategies:
+    - ``rule`` (default): lightweight rule-based extraction.
+    - ``llm``: LLM-based extraction; requires a ``llm_client`` callable.
+
+    If ``llm`` is requested but no client is provided, falls back to rule-based.
+    """
+    if strategy == "llm" and llm_client is not None:
+        return LLMBasedLearningExtractor(
+            llm_client,
+            context_prompt_template=context_prompt_template or CONTEXT_AWARE_EXTRACTION_PROMPT,
+        )
+    return LearningExtractor()

thinkstack_core/reasoning_plus/learning/filter_five_layer.py

@@ -0,0 +1,95 @@
+"""
+thinkstack_core.reasoning_plus.learning.filter_five_layer
+========================================================
+Five-layer cross-project learning relevance filter.
+
+Only learnings that pass all five layers are eligible for injection
+into a target project's agent workflow:
+
+1. **Concept mismatch** — the target project must share at least one
+   trigger concept with the learning.
+2. **Scope gate** — ``scope: "project"`` and ``scope: "branch"``
+   learnings are excluded from cross-project injection.
+3. **Deny list** — per-project ``.GCC/learning_config.json`` can
+   exclude specific concepts or learning IDs.
+4. **Relevance score** — similarity between the learning's content and
+   the current prompt must exceed ``learning_relevance_threshold``.
+5. **Human promotion** — auto-applied learnings must have ``scope: "org"``
+   and ``type: "canon"``; others require explicit opt-in.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from thinkstack_core.reasoning_plus.learning.deny_list import (
+    DenyList,
+    load_deny_list,
+)
+from thinkstack_core.reasoning_plus.learning.models import Learning
+
+logger = logging.getLogger("thinkstack.reasoning_plus.learning")
+
+
+def five_layer_filter(
+    learning: Learning,
+    *,
+    target_project_root: Path | str,
+    prompt_context: str = "",
+    relevance_score: float = 0.0,
+    deny_list: DenyList | None = None,
+    min_relevance: float = 0.3,
+) -> tuple[bool, str]:
+    """Return (allowed, reason) after evaluating all five layers.
+
+    Returns ``(True, "ALLOWED")`` if the learning passes every layer.
+    Returns ``(False, reason_string)`` identifying the first failing layer.
+    """
+    target = Path(target_project_root)
+
+    # Layer 1: Concept mismatch
+    target_concepts = _load_project_concepts(target)
+    if target_concepts:
+        overlap = set(c.lower() for c in learning.trigger_concepts) & set(c.lower() for c in target_concepts)
+
+        has_any_concept = len(overlap) > 0
+    else:
+        has_any_concept = len(learning.trigger_concepts) > 0
+        # No target concepts defined — allow through rather than block.
+
+    if not has_any_concept:
+        return False, "CONCEPT_MISMATCH"
+
+    # Layer 2: Scope gate — only org-scope learnings cross projects
+    if learning.scope in ("project", "branch"):
+        return False, f"SCOPE_GATE:{learning.scope}"
+
+    # Layer 3: Deny list
+    dl = deny_list or load_deny_list(target)
+    if learning.id in dl.excluded_learnings:
+        return False, "DENY_LIST:learning_id"
+    for concept in learning.trigger_concepts:
+        if concept.lower() in (c.lower() for c in dl.excluded_concepts):
+            return False, f"DENY_LIST:concept:{concept}"
+
+    # Layer 4: Relevance threshold
+    if relevance_score < min_relevance:
+        return False, f"RELEVANCE_THRESHOLD:{relevance_score:.2f}<{min_relevance:.2f}"
+
+    # Layer 5: Human promotion gate
+    # Auto-apply only if org-scope + canon type; everything else needs explicit
+    if learning.scope == "org" and learning.type == "canon":
+        return True, "ALLOWED"
+    return False, "PROMOTION_REQUIRED"
+
+
+def _load_project_concepts(project_root: Path) -> list[str]:
+    concepts_dir = project_root / ".GCC" / "concepts"
+    if not concepts_dir.exists():
+        return []
+    concepts: list[str] = []
+    for f in concepts_dir.iterdir():
+        if f.suffix in (".md", ".json") and f.is_file():
+            concepts.append(f.stem)
+    return concepts