superlocalmemory 3.2.2 → 3.3.0

package/src/superlocalmemory/parameterization/prompt_injector.py

@@ -0,0 +1,216 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3.3
+
+"""PromptInjector — Inject soft prompts into context with token budget.
+
+Priority: soft prompts > regular memories (soft prompts come first).
+Token budget split: prompt_budget (500 default) + memory_budget (1500 default).
+Dedup with existing context.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.storage.database import DatabaseManager
+    from superlocalmemory.core.config import ParameterizationConfig
+
+from superlocalmemory.parameterization.soft_prompt_generator import (
+    SoftPromptGenerator,
+    SoftPromptTemplate,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PromptInjector:
+    """Inject soft prompts into conversation context.
+
+    Handles retrieval from DB, token budget enforcement, and
+    combination with regular memory context.
+    """
+
+    def __init__(
+        self,
+        db: DatabaseManager,
+        generator: SoftPromptGenerator,
+        config: ParameterizationConfig,
+    ) -> None:
+        self._db = db
+        self._generator = generator
+        self._config = config
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_injection_context(self, profile_id: str) -> str:
+        """Retrieve stored soft prompts, assemble for injection.
+
+        Args:
+            profile_id: Profile to load prompts for.
+
+        Returns:
+            Assembled soft prompt text, or "" if disabled/empty.
+        """
+        if not self._config.enabled:
+            return ""
+
+        rows = self._db.execute(
+            "SELECT prompt_id, category, content, confidence, "
+            "token_count, retention_score, profile_id, "
+            "source_pattern_ids, effectiveness, active, version "
+            "FROM soft_prompt_templates "
+            "WHERE profile_id = ? AND active = 1 AND retention_score >= 0.1 "
+            "ORDER BY confidence DESC",
+            (profile_id,),
+        )
+
+        if not rows:
+            return ""
+
+        templates: list[SoftPromptTemplate] = []
+        for row in rows:
+            raw_ids = row.get("source_pattern_ids", "[]")
+            try:
+                source_ids = json.loads(raw_ids) if isinstance(raw_ids, str) else raw_ids
+            except (json.JSONDecodeError, TypeError):
+                source_ids = []
+
+            templates.append(SoftPromptTemplate(
+                prompt_id=row["prompt_id"],
+                profile_id=row.get("profile_id", profile_id),
+                category=row["category"],
+                content=row["content"],
+                source_pattern_ids=source_ids,
+                confidence=row["confidence"],
+                effectiveness=row.get("effectiveness", 0.5),
+                token_count=row.get("token_count", 0),
+                retention_score=row.get("retention_score", 1.0),
+                active=bool(row.get("active", 1)),
+                version=row.get("version", 1),
+            ))
+
+        # Budget enforcement
+        total = sum(t.token_count for t in templates)
+        if total > self._config.max_prompt_tokens:
+            selected: list[SoftPromptTemplate] = []
+            accumulated = 0
+            for t in templates:  # Already sorted by confidence DESC
+                if accumulated + t.token_count > self._config.max_prompt_tokens:
+                    break
+                selected.append(t)
+                accumulated += t.token_count
+            templates = selected
+
+        return self._generator.assemble(templates)
+
+    def inject_into_context(
+        self,
+        soft_prompt_text: str,
+        memory_context: str,
+        total_budget: int | None = None,
+    ) -> str:
+        """Combine soft prompts with regular memory context.
+
+        Args:
+            soft_prompt_text: Assembled soft prompt text.
+            memory_context: Regular memory recall context.
+            total_budget: Optional total token budget override.
+
+        Returns:
+            Combined context string with soft prompts first.
+        """
+        budget = total_budget or (
+            self._config.max_prompt_tokens + self._config.max_memory_tokens
+        )
+        prompt_budget = self._config.max_prompt_tokens
+        memory_budget = self._config.max_memory_tokens
+
+        # Trim soft prompt to its budget
+        if soft_prompt_text:
+            soft_tokens = SoftPromptGenerator._estimate_tokens(soft_prompt_text)
+            if soft_tokens > prompt_budget:
+                soft_prompt_text = SoftPromptGenerator._trim_to_tokens(
+                    soft_prompt_text, prompt_budget,
+                )
+
+        # Trim memory context to its budget
+        if memory_context:
+            mem_tokens = SoftPromptGenerator._estimate_tokens(memory_context)
+            if mem_tokens > memory_budget:
+                memory_context = SoftPromptGenerator._trim_to_tokens(
+                    memory_context, memory_budget,
+                )
+
+        if not soft_prompt_text:
+            return memory_context
+        if not memory_context:
+            return soft_prompt_text
+
+        return f"{soft_prompt_text}\n\n{memory_context}"
+
+    def store_prompts(
+        self, templates: list[SoftPromptTemplate],
+    ) -> int:
+        """Persist generated soft prompts, deactivating old versions.
+
+        Args:
+            templates: Generated templates to store.
+
+        Returns:
+            Number of templates stored.
+        """
+        count = 0
+        for template in templates:
+            # Deactivate existing for same (profile_id, category)
+            self._db.execute(
+                "UPDATE soft_prompt_templates SET active = 0, "
+                "updated_at = datetime('now') "
+                "WHERE profile_id = ? AND category = ? AND active = 1",
+                (template.profile_id, template.category),
+            )
+
+            # Get max version for this (profile_id, category)
+            version_rows = self._db.execute(
+                "SELECT COALESCE(MAX(version), 0) AS max_version "
+                "FROM soft_prompt_templates "
+                "WHERE profile_id = ? AND category = ?",
+                (template.profile_id, template.category),
+            )
+            max_version = 0
+            if version_rows:
+                max_version = version_rows[0].get("max_version", 0) or 0
+            new_version = max_version + 1
+
+            # Insert new prompt
+            self._db.execute(
+                "INSERT INTO soft_prompt_templates "
+                "(prompt_id, profile_id, category, content, "
+                "source_pattern_ids, confidence, effectiveness, "
+                "token_count, retention_score, active, version, "
+                "created_at, updated_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, "
+                "datetime('now'), datetime('now'))",
+                (
+                    template.prompt_id,
+                    template.profile_id,
+                    template.category,
+                    template.content,
+                    json.dumps(template.source_pattern_ids),
+                    template.confidence,
+                    template.effectiveness,
+                    template.token_count,
+                    template.retention_score,
+                    new_version,
+                ),
+            )
+            count += 1
+
+        return count

package/src/superlocalmemory/parameterization/prompt_lifecycle.py

@@ -0,0 +1,275 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3.3
+
+"""PromptLifecycleManager — Ebbinghaus decay and effectiveness for soft prompts.
+
+Applies Ebbinghaus forgetting curve to soft prompts. Higher effectiveness
+and more versions (evidence proxy) slow decay. 48h floor prevents cold-start death.
+
+[AUDIT FIX F-2] 48h floor on prompt strength.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.storage.database import DatabaseManager
+    from superlocalmemory.math.ebbinghaus import EbbinghausCurve
+    from superlocalmemory.core.config import ParameterizationConfig
+
+from superlocalmemory.parameterization.pattern_extractor import (
+    PatternAssertion,
+)
+
+logger = logging.getLogger(__name__)
+
+# Minimum prompt strength floor — prevents cold-start death
+_PROMPT_STRENGTH_FLOOR = 48.0
+
+
+class PromptLifecycleManager:
+    """Manage soft prompt lifecycle: effectiveness tracking + Ebbinghaus decay.
+
+    Effectiveness is updated via session feedback signals.
+    Retention decays via Ebbinghaus curve with strength derived from
+    effectiveness * version (evidence proxy).
+    """
+
+    def __init__(
+        self,
+        db: DatabaseManager,
+        ebbinghaus: EbbinghausCurve,
+        config: ParameterizationConfig,
+    ) -> None:
+        self._db = db
+        self._ebbinghaus = ebbinghaus
+        self._config = config
+
+    # ------------------------------------------------------------------
+    # Effectiveness tracking
+    # ------------------------------------------------------------------
+
+    def update_effectiveness(
+        self,
+        profile_id: str,
+        category: str,
+        signals: dict[str, float],
+    ) -> float:
+        """Update prompt effectiveness from feedback signals.
+
+        Signals: followed, session_success (positive),
+                 corrected, session_failure (negative).
+        Uses exponential moving average: 0.7 * raw + 0.3 * current.
+
+        Args:
+            profile_id: Target profile.
+            category: Prompt category to update.
+            signals: Feedback signal dict.
+
+        Returns:
+            New effectiveness score in [0.0, 1.0].
+        """
+        rows = self._db.execute(
+            "SELECT prompt_id, effectiveness, retention_score "
+            "FROM soft_prompt_templates "
+            "WHERE profile_id = ? AND category = ? AND active = 1",
+            (profile_id, category),
+        )
+        if not rows:
+            return 0.5
+
+        row = rows[0]
+        current_effectiveness = row.get("effectiveness", 0.5)
+        prompt_id = row["prompt_id"]
+
+        # Compute signal summary
+        positive = (
+            signals.get("followed", 0.0)
+            + signals.get("session_success", 0.0)
+        )
+        negative = (
+            signals.get("corrected", 0.0)
+            + signals.get("session_failure", 0.0)
+        )
+        total = positive + negative + 1.0  # Laplace smoothing
+
+        raw_score = positive / total
+        new_effectiveness = 0.7 * raw_score + 0.3 * current_effectiveness
+        new_effectiveness = max(0.0, min(1.0, new_effectiveness))
+
+        self._db.execute(
+            "UPDATE soft_prompt_templates "
+            "SET effectiveness = ?, updated_at = datetime('now') "
+            "WHERE prompt_id = ?",
+            (new_effectiveness, prompt_id),
+        )
+
+        return new_effectiveness
+
+    # ------------------------------------------------------------------
+    # Ebbinghaus decay
+    # ------------------------------------------------------------------
+
+    def compute_prompt_retention(self, prompt_id: str) -> float:
+        """Compute Ebbinghaus retention for a soft prompt.
+
+        Strength = max(48h floor, 2 * effectiveness * version).
+        R(t) = e^(-t/S) via EbbinghausCurve.
+
+        Args:
+            prompt_id: Prompt to compute retention for.
+
+        Returns:
+            Retention score in [0.0, 1.0], or 0.0 if not found.
+        """
+        rows = self._db.execute(
+            "SELECT prompt_id, effectiveness, retention_score, "
+            "version, created_at, updated_at "
+            "FROM soft_prompt_templates WHERE prompt_id = ?",
+            (prompt_id,),
+        )
+        if not rows:
+            return 0.0
+
+        row = rows[0]
+        effectiveness = row.get("effectiveness", 0.5)
+        version = max(1, row.get("version", 1))
+        updated_at = row.get("updated_at", "")
+
+        # Compute hours since last update
+        now = datetime.now(timezone.utc)
+        try:
+            last_update = datetime.fromisoformat(updated_at)
+            if last_update.tzinfo is None:
+                last_update = last_update.replace(tzinfo=timezone.utc)
+            hours = (now - last_update).total_seconds() / 3600.0
+        except (ValueError, TypeError):
+            hours = 0.0
+
+        # Prompt strength: effectiveness * version proxy
+        s_raw = 2.0 * effectiveness * version
+        s_prompt = max(_PROMPT_STRENGTH_FLOOR, s_raw)
+
+        retention = self._ebbinghaus.retention(hours, s_prompt)
+        return retention
+
+    # ------------------------------------------------------------------
+    # Lifecycle review
+    # ------------------------------------------------------------------
+
+    def run_lifecycle_review(self, profile_id: str) -> dict:
+        """Periodic review: decay prompts, deactivate dead ones.
+
+        Args:
+            profile_id: Profile to review.
+
+        Returns:
+            Stats dict: {reviewed, decayed, removed, refreshed}.
+        """
+        rows = self._db.execute(
+            "SELECT prompt_id, category, effectiveness, retention_score, "
+            "version, created_at, updated_at "
+            "FROM soft_prompt_templates "
+            "WHERE profile_id = ? AND active = 1",
+            (profile_id,),
+        )
+
+        stats = {"reviewed": 0, "decayed": 0, "removed": 0, "refreshed": 0}
+
+        for row in rows:
+            prompt_id = row["prompt_id"]
+            old_retention = row.get("retention_score", 1.0)
+            stats["reviewed"] += 1
+
+            new_retention = self.compute_prompt_retention(prompt_id)
+
+            if new_retention < 0.1:
+                # Deactivate
+                self._db.execute(
+                    "UPDATE soft_prompt_templates "
+                    "SET active = 0, retention_score = ?, "
+                    "updated_at = datetime('now') WHERE prompt_id = ?",
+                    (new_retention, prompt_id),
+                )
+                stats["removed"] += 1
+                logger.info(
+                    "Prompt %s (category=%s) deactivated: retention %.3f < 0.1",
+                    prompt_id, row.get("category", "?"), new_retention,
+                )
+            else:
+                # Update retention score
+                self._db.execute(
+                    "UPDATE soft_prompt_templates "
+                    "SET retention_score = ?, updated_at = datetime('now') "
+                    "WHERE prompt_id = ?",
+                    (new_retention, prompt_id),
+                )
+                delta = abs(new_retention - old_retention)
+                if delta > 0.1:
+                    stats["decayed"] += 1
+
+        return stats
+
+    # ------------------------------------------------------------------
+    # Evolution
+    # ------------------------------------------------------------------
+
+    def evolve_prompt(
+        self,
+        profile_id: str,
+        category: str,
+        new_pattern: PatternAssertion,
+    ) -> str:
+        """Handle preference evolution: new pattern vs existing prompt.
+
+        Args:
+            profile_id: Target profile.
+            category: Category being evolved.
+            new_pattern: New pattern assertion to compare.
+
+        Returns:
+            "new" | "replaced" | "kept_existing" | "user_review_needed"
+        """
+        rows = self._db.execute(
+            "SELECT prompt_id, category, confidence, effectiveness "
+            "FROM soft_prompt_templates "
+            "WHERE profile_id = ? AND category = ? AND active = 1",
+            (profile_id, category),
+        )
+
+        if not rows:
+            return "new"
+
+        current = rows[0]
+        current_confidence = current.get("confidence", 0.0)
+
+        if new_pattern.confidence > current_confidence + 0.1:
+            # New pattern clearly better — replace
+            self._db.execute(
+                "UPDATE soft_prompt_templates "
+                "SET active = 0, updated_at = datetime('now') "
+                "WHERE prompt_id = ?",
+                (current["prompt_id"],),
+            )
+            return "replaced"
+
+        if new_pattern.confidence < current_confidence - 0.1:
+            logger.info(
+                "Keeping existing prompt for %s (conf=%.2f > new=%.2f)",
+                category, current_confidence, new_pattern.confidence,
+            )
+            return "kept_existing"
+
+        # Close confidence — needs user review
+        logger.warning(
+            "Equal confidence conflict in %s for %s. User review needed.",
+            category, new_pattern.key,
+        )
+        return "user_review_needed"