devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/wrapper/base.py

@@ -0,0 +1,562 @@
+"""
+devtorch_core.wrapper.base
+==========================
+Core infrastructure shared by all LLM SDK wrappers:
+
+- RACPInjector  — builds the RACP system-prompt prefix for every LLM call.
+- CaptureOrchestrator — fires devtorch commit / sensitivity primitives after
+  an LLM response is received.
+- Helpers: is_disabled(), find_gcc_repo().
+
+All code must degrade gracefully.  If .GCC/ is missing, if devtorch_core
+methods fail, or if parser imports fail, a warning is logged and the caller
+never sees an exception.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("devtorch.wrapper")
+
+DEVTORCH_DISABLE_ENV = "DEVTORCH_DISABLE"
+CONTEXT_CACHE_TTL_SECS = 60
+
+
+def _reasoning_text(thinking_blocks: list) -> str:
+    """Extract text from a list of ThinkingBlock objects."""
+    if not thinking_blocks:
+        return ""
+    return "\n\n".join(getattr(tb, "text", str(tb)) for tb in thinking_blocks)
+
+
+# ---------------------------------------------------------------------------
+# RACP prefix builder
+# ---------------------------------------------------------------------------
+
+class RACPInjector:
+    """Builds the injected prefix for every LLM call."""
+
+    def __init__(self, gcc_repo: Any) -> None:
+        self._repo = gcc_repo
+        self._cache: dict = {}   # keys: "bundle" (dict), "ts" (float)
+        self._augmenter: Any | None = None
+
+    # ------------------------------------------------------------------
+    # Public
+    # ------------------------------------------------------------------
+
+    def build_system_prefix(self, prompt_text: str | None = None) -> str:
+        """
+        Return a string to prepend to the system prompt composed of:
+          1. RACP system prompt from .GCC/prompts/ (if set).
+          2. Θ summary — top-10 concepts by mean_confidence.
+          3. Context bundle summary — artifact names and reasons.
+          4. Reasoning Plus smart context + reasoning directive (if enabled).
+
+        Returns an empty string on any error so callers can safely
+        concatenate without conditional checks.
+        """
+        prefix, _ = self.build_system_prefix_with_provenance(
+            prompt_text=prompt_text,
+        )
+        return prefix
+
+    def build_system_prefix_with_provenance(
+        self,
+        prompt_text: str | None = None,
+        *,
+        session_id: str = "",
+        call_id: str = "",
+        model_name: str = "",
+    ) -> tuple[str, list[str]]:
+        """
+        Build the system prefix and also inject relevant learnings.
+
+        Returns (prefix, injected_learning_ids).  When *call_id* is
+        provided, a provenance record is written so that the observed
+        outcome can later be attributed to the injected learnings.
+
+        Architecture: pure RACP builds the base prefix first (system prompt
+        + Theta + context bundle).  Reasoning Plus decorates that base
+        with smart context, reasoning directive, and DRPL learnings when
+        enabled.  The augmentation never replaces RACP — it wraps it.
+        """
+        # ---- Layer 1: pure RACP (always runs, is the protocol) ----------
+        base_parts = self._build_racp_parts()
+
+        learning_ids: list[str] = []
+
+        # ---- Layer 2: Reasoning Plus decorates RACP (optional) ----------
+        if prompt_text and not is_disabled():
+            try:
+                augmenter = self._get_reasoning_plus_augmenter()
+                if augmenter and augmenter.should_augment():
+                    augmented, learning_ids = augmenter.build_system_prompt_with_learning_context(
+                        base_parts,
+                        prompt_text_for_context=prompt_text,
+                        call_id=call_id,
+                        session_id=session_id,
+                        model_name=model_name,
+                    )
+                    return augmented, learning_ids
+            except Exception as exc:
+                logger.warning("devtorch: Reasoning Plus injection failed — %s", exc)
+
+        return base_parts, learning_ids
+
+    def invalidate_cache(self) -> None:
+        """Invalidate context bundle cache and reasoning-plus smart context cache."""
+        self._cache = {}
+        if self._augmenter is not None:
+            try:
+                self._augmenter.invalidate_cache()
+            except Exception:
+                pass
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    def _build_racp_parts(self) -> str:
+        """Build the classic RACP system-prefix (prompt + Θ + context bundle)."""
+        parts: list[str] = []
+
+        # 1. RACP system prompt artifact
+        try:
+            racp_prompt = self._repo.prompt_get()
+            if racp_prompt:
+                parts.append(racp_prompt.strip())
+        except Exception as exc:
+            logger.warning("devtorch: prompt_get failed — %s", exc)
+
+        # 2. Θ summary
+        try:
+            theta_text = self._theta_summary()
+            if theta_text:
+                parts.append(theta_text)
+        except Exception as exc:
+            logger.warning("devtorch: theta_summary failed — %s", exc)
+
+        # 3. Context bundle summary
+        try:
+            bundle = self._get_context_bundle()
+            artifacts = bundle.get("artifacts", [])
+            if artifacts:
+                lines = ["[DevTorch context bundle]"]
+                for art in artifacts:
+                    path = art.get("path", "?")
+                    reason = art.get("reason", "")
+                    lines.append(f"  - {path}: {reason}" if reason else f"  - {path}")
+                parts.append("\n".join(lines))
+        except Exception as exc:
+            logger.warning("devtorch: context_bundle summary failed — %s", exc)
+
+        return "\n\n".join(parts)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _get_context_bundle(self) -> dict:
+        """Return cached context bundle (CONTEXT_CACHE_TTL_SECS TTL)."""
+        now = time.monotonic()
+        if self._cache and (now - self._cache.get("ts", 0)) < CONTEXT_CACHE_TTL_SECS:
+            return self._cache["bundle"]
+
+        # Respect an override set by the caller (e.g. the benchmark runner).
+        k_tokens = getattr(self._repo, "_context_k_override", None) or 8000
+        bundle = self._repo.context_bundle(
+            k_tokens=k_tokens,
+            policy={"sensitivity_policy": "default"},
+        )
+        self._cache = {"bundle": bundle, "ts": now}
+        return bundle
+
+    def _theta_summary(self) -> str:
+        """Format top-10 Θ entries as compact text (sorted by mean_confidence desc)."""
+        theta = self._repo.get_theta()
+        cv = theta.get("coordination_vector", {})
+        if not cv:
+            return ""
+
+        # Sort by mean_confidence descending; take top 10
+        def _mean_conf(entry: Any) -> float:
+            if isinstance(entry, dict):
+                return float(entry.get("mean_confidence", 0.0))
+            return 0.0
+
+        top = sorted(cv.items(), key=lambda kv: _mean_conf(kv[1]), reverse=True)[:10]
+        if not top:
+            return ""
+
+        lines = ["[DevTorch Θ — top concepts]"]
+        for concept, data in top:
+            conf = _mean_conf(data)
+            lines.append(f"  {concept}: mean_confidence={conf:.3f}")
+        return "\n".join(lines)
+
+    def _get_reasoning_plus_augmenter(self) -> Any | None:
+        """Lazy-initialize the Reasoning Plus augmenter for this repo."""
+        if self._augmenter is None and self._repo is not None:
+            try:
+                from devtorch_core.reasoning_plus.augmenter import ReasoningPlusAugmenter
+
+                repo_path = self._repo.gcc_dir.parent
+                self._augmenter = ReasoningPlusAugmenter(repo_path, gcc_repo=self._repo)
+            except Exception as exc:
+                logger.warning("devtorch: failed to load Reasoning Plus augmenter — %s", exc)
+                self._augmenter = None
+        return self._augmenter
+
+
+# ---------------------------------------------------------------------------
+# Capture orchestrator
+# ---------------------------------------------------------------------------
+
+class CaptureOrchestrator:
+    """Fires devtorch primitives after an LLM response is received."""
+
+    def __init__(self, gcc_repo: Any) -> None:
+        self._repo = gcc_repo
+        self._learning: Any | None = None
+        self._bundle_tokens_cache: Optional[int] = None
+
+    # ------------------------------------------------------------------
+    # Public
+    # ------------------------------------------------------------------
+
+    def record_learning_call(
+        self,
+        *,
+        call_type: str,
+        reasoning: str,
+        session_id: str = "",
+        name: str = "",
+        input: str = "",
+        output: str = "",
+        outcome: str = "unknown",
+        sensitivity: str = "PUBLIC",
+        call_id: str = "",
+        concepts: list[str] | None = None,
+    ) -> None:
+        """
+        Record a reasoning call in the Reasoning Plus Learning (DRPL) layer.
+
+        This is the hook for automatic outcome detection: wrappers can call it
+        with ``outcome="success"`` or ``outcome="failure"`` after an LLM/tool
+        call completes.
+
+        If a *call_id* is provided, it is reused for the call record and any
+        provenance feedback for learnings that were injected into this call.
+        The *concepts* parameter tags the call with RACP concepts so that
+        extracted learnings carry semantic context for relevance scoring.
+        """
+        if not self._repo:
+            return
+        try:
+            if self._learning is None:
+                from devtorch_core.reasoning_plus.learning import ReasoningPlusLearning
+                from devtorch_core.reasoning_plus.config import SettingsStore
+
+                config, _ = SettingsStore(self._repo.gcc_dir).load()
+                self._learning = ReasoningPlusLearning(
+                    gcc_dir=self._repo.gcc_dir,
+                    repo_path=self._repo.gcc_dir.parent,
+                    config=config,
+                )
+
+            recorded_id = self._learning.record_call(
+                call_type=call_type,
+                reasoning=reasoning,
+                session_id=session_id,
+                name=name,
+                input=input,
+                output=output,
+                outcome=outcome,
+                sensitivity=sensitivity,
+                call_id=call_id or None,
+                concepts=concepts,
+            )
+            self._learning.extract_learnings(recorded_id)
+            if call_id and outcome in ("success", "failure", "stale"):
+                self._learning.record_injection_outcome(call_id, outcome)
+        except Exception as exc:
+            logger.warning("devtorch: learning call recording failed — %s", exc)
+
+    def capture(
+        self,
+        response_text: str,
+        thinking_blocks: list,
+        session_id: str,
+        *,
+        prompt_text: str = "",
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+        bundle_tokens: int = 0,
+    ) -> None:
+        """
+        Parse *response_text* and fire devtorch primitives:
+
+        1. If thinking blocks present → commit with conf=1.0.
+        2. Extract RACP blocks from text → commit + sensitivity_add per block.
+        3. If nothing found → infer_sensitivity + extract_decision_summary
+           → commit with conf=0.5.
+        4. Write session metrics (tokens, developer_id) for this session.
+
+        All errors are caught and logged — never raised.
+        """
+        try:
+            self._do_capture(response_text, thinking_blocks, session_id)
+        except Exception as exc:
+            logger.warning("devtorch: capture error (session=%s) — %s", session_id, exc)
+
+        try:
+            self._write_session_metrics(
+                session_id,
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                bundle_tokens=bundle_tokens,
+            )
+        except Exception as exc:
+            logger.warning("devtorch: session metrics write failed (session=%s) — %s", session_id, exc)
+
+    # ------------------------------------------------------------------
+    # Internal capture pipeline
+    # ------------------------------------------------------------------
+
+    def _do_capture(
+        self,
+        response_text: str,
+        thinking_blocks: list,
+        session_id: str,
+    ) -> None:
+        captured_something = False
+
+        # --- 1. Native thinking blocks → commit at conf=1.0 ---
+        if thinking_blocks:
+            try:
+                from devtorch_core.parser.thinking import thinking_to_commit_message
+                msg = thinking_to_commit_message(thinking_blocks)
+                self._do_commit(f"[session={session_id}] {msg}")
+                captured_something = True
+            except Exception as exc:
+                logger.warning("devtorch: thinking capture failed — %s", exc)
+
+        # --- 2. RACP structured blocks (primary protocol) ---
+        commits: list = []
+        sensitivities: list = []
+        try:
+            from devtorch_core.parser.blocks import extract_racp_blocks
+            commits, sensitivities = extract_racp_blocks(response_text)
+        except Exception as exc:
+            logger.warning("devtorch: extract_racp_blocks failed — %s", exc)
+
+        for cb in commits:
+            self._do_commit(cb.message, concepts=cb.concepts)
+            captured_something = True
+
+        for sb in sensitivities:
+            self._do_sensitivity(
+                concept=sb.concept,
+                signal=sb.signal,
+                confidence=sb.confidence,
+                disclosure=sb.disclosure,
+            )
+            captured_something = True
+
+        # --- 3. Inline <thinking> blocks (Reasoning Plus augmentation) ---
+        try:
+            from devtorch_core.reasoning_plus.capture import (
+                commit_reasoning,
+                extract_inline_thinking,
+            )
+
+            inline_thinking = extract_inline_thinking(response_text)
+            if inline_thinking:
+                combined = "\n\n".join(inline_thinking)
+                commit_reasoning(self._repo, combined, session_id)
+                captured_something = True
+        except Exception as exc:
+            logger.warning("devtorch: inline thinking capture failed — %s", exc)
+
+        # --- 4. Fallback: infer + decision summary ---
+        if not captured_something and response_text:
+            summary = ""
+            try:
+                from devtorch_core.parser.inference import extract_decision_summary
+                summary = extract_decision_summary(response_text)
+            except Exception:
+                # inference module may not exist yet
+                summary = response_text[:200]
+
+            try:
+                from devtorch_core.parser.inference import infer_sensitivity
+                inferred = infer_sensitivity(response_text)
+                for item in inferred:
+                    concept = getattr(item, "concept", str(item))
+                    signal = getattr(item, "signal", "inferred")
+                    confidence = float(getattr(item, "confidence", 0.5))
+                    disclosure = getattr(item, "disclosure", "PROTECTED")
+                    self._do_sensitivity(concept, signal, confidence, disclosure)
+            except Exception as exc:
+                logger.warning("devtorch: infer_sensitivity failed — %s", exc)
+
+            commit_msg = (
+                f"[session={session_id}] auto(conf=0.5): {summary[:180]}"
+                if summary
+                else f"[session={session_id}] auto(conf=0.5): response captured"
+            )
+            self._do_commit(commit_msg)
+
+    # ------------------------------------------------------------------
+    # Primitives — each catches its own errors
+    # ------------------------------------------------------------------
+
+    def _do_commit(self, message: str, concepts: list[str] | None = None) -> None:
+        try:
+            self._repo.commit(message=message, concepts=concepts)
+        except Exception as exc:
+            logger.warning("devtorch commit failed: %s", exc)
+
+    def _do_sensitivity(
+        self,
+        concept: str,
+        signal: str,
+        confidence: float,
+        disclosure: str = "PROTECTED",
+    ) -> None:
+        try:
+            from devtorch_core.sensitivity import SensitivityEvent
+
+            ev = SensitivityEvent(
+                source_node="llm_wrapper",
+                target_concept=concept,
+                counterfactuals="",
+                confidence=confidence,
+                disclosure_level=disclosure,
+                message=signal[:200],
+            )
+            self._repo.add_sensitivity(ev)
+        except Exception as exc:
+            logger.warning("devtorch sensitivity add failed: %s", exc)
+
+    def _estimate_bundle_tokens(self) -> int:
+        """Estimate the current context bundle size in tokens.
+
+        This is used when the wrapper did not provide an explicit bundle token
+        count. It is cached per CaptureOrchestrator instance because the
+        context bundle changes slowly relative to the LLM call rate.
+        """
+        if self._bundle_tokens_cache is not None:
+            return self._bundle_tokens_cache
+        try:
+            if self._repo is None:
+                self._bundle_tokens_cache = 0
+            else:
+                bundle = self._repo.context_bundle(k_tokens=8000)
+                self._bundle_tokens_cache = int(bundle.get("approx_tokens_used", 0))
+        except Exception as exc:
+            logger.debug("devtorch: bundle token estimation failed — %s", exc)
+            self._bundle_tokens_cache = 0
+        return self._bundle_tokens_cache
+
+    def _write_session_metrics(
+        self,
+        session_id: str,
+        *,
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+        bundle_tokens: int = 0,
+    ) -> None:
+        """Write/update session metrics for this wrapper session."""
+        from devtorch_core.metrics.session_writer import write_session_metrics
+
+        tokens_used = prompt_tokens + completion_tokens
+        if bundle_tokens <= 0:
+            bundle_tokens = self._estimate_bundle_tokens()
+        full_history_tokens = max(tokens_used, bundle_tokens)
+        tokens_saved = max(0, full_history_tokens - bundle_tokens)
+        latency_speedup_factor = (
+            full_history_tokens / bundle_tokens if bundle_tokens > 0 else 1.0
+        )
+
+        write_session_metrics(
+            self._repo.gcc_dir,
+            session_id,
+            {
+                "tokens_used": tokens_used,
+                "tokens_saved": tokens_saved,
+                "bundle_tokens": bundle_tokens,
+                "full_history_tokens": full_history_tokens,
+                "latency_speedup_factor": round(latency_speedup_factor, 4),
+                "developer_id": _developer_id(),
+            },
+        )
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+def _developer_id() -> str:
+    """Return a developer identifier for the current session.
+
+    Order of preference:
+    1. DEVTORCH_DEVELOPER_ID environment variable.
+    2. git config user.email in the current repository.
+    3. "unknown".
+    """
+    env_id = os.environ.get("DEVTORCH_DEVELOPER_ID", "").strip()
+    if env_id:
+        return env_id
+
+    try:
+        import subprocess
+        result = subprocess.run(
+            ["git", "config", "user.email"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+        email = result.stdout.strip()
+        if email:
+            return email
+    except Exception:
+        pass
+
+    return "unknown"
+
+def is_disabled() -> bool:
+    """Return True if the DEVTORCH_DISABLE env var is set to a truthy value."""
+    return os.environ.get(DEVTORCH_DISABLE_ENV, "").strip().lower() in (
+        "1", "true", "yes"
+    )
+
+
+def find_gcc_repo() -> Any | None:
+    """
+    Walk up from cwd looking for an initialised .GCC/ directory.
+    Returns a GCCRepository instance or None if none found or if
+    devtorch_core is not importable.
+    """
+    try:
+        from devtorch_core import GCCRepository
+    except ImportError:
+        logger.warning("devtorch: devtorch_core not importable — wrapper disabled")
+        return None
+
+    for parent in [Path.cwd()] + list(Path.cwd().parents):
+        try:
+            candidate = GCCRepository.at(parent)
+            if candidate.is_initialized():
+                return candidate
+        except Exception:
+            continue
+    return None