@geravant/sinain 1.0.1

package/sinain-memory/demo_knowledge_transfer.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# demo_knowledge_transfer.sh — Demonstrates sinain knowledge transfer flow.
+#
+# Scenario: Expert workspace has extracted a module → export it → import into
+# a fresh (novice) workspace → verify the module stack and attribution.
+#
+# Usage:
+#   ./demo_knowledge_transfer.sh <expert-workspace> <novice-workspace> <module-id>
+#
+# Example:
+#   ./demo_knowledge_transfer.sh /mnt/openclaw-state /tmp/novice-workspace ocr-vision-pipeline
+
+set -euo pipefail
+
+EXPERT_WS="${1:?Usage: $0 <expert-workspace> <novice-workspace> <module-id>}"
+NOVICE_WS="${2:?Usage: $0 <expert-workspace> <novice-workspace> <module-id>}"
+MODULE_ID="${3:?Usage: $0 <expert-workspace> <novice-workspace> <module-id>}"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BUNDLE_PATH="/tmp/${MODULE_ID}.sinain-module.json"
+
+echo "=== sinain Knowledge Transfer Demo ==="
+echo ""
+echo "Expert workspace:  $EXPERT_WS"
+echo "Novice workspace:  $NOVICE_WS"
+echo "Module to transfer: $MODULE_ID"
+echo ""
+
+# Step 1: Show expert's module info
+echo "--- Step 1: Expert's module info ---"
+python3 "$SCRIPT_DIR/module_manager.py" \
+  --modules-dir "$EXPERT_WS/modules" info "$MODULE_ID"
+echo ""
+
+# Step 2: Export from expert workspace
+echo "--- Step 2: Export module as portable bundle ---"
+python3 "$SCRIPT_DIR/module_manager.py" \
+  --modules-dir "$EXPERT_WS/modules" export "$MODULE_ID" \
+  --output "$BUNDLE_PATH"
+echo ""
+echo "Bundle size: $(wc -c < "$BUNDLE_PATH") bytes"
+echo ""
+
+# Step 3: Ensure novice workspace has modules directory
+echo "--- Step 3: Prepare novice workspace ---"
+mkdir -p "$NOVICE_WS/modules" "$NOVICE_WS/memory"
+echo "Created $NOVICE_WS/modules/"
+echo ""
+
+# Step 4: Import into novice workspace with activation
+echo "--- Step 4: Import into novice workspace (with --activate) ---"
+python3 "$SCRIPT_DIR/module_manager.py" \
+  --modules-dir "$NOVICE_WS/modules" import "$BUNDLE_PATH" --activate
+echo ""
+
+# Step 5: Fire KG ingestion (optional, may fail if triple store not configured)
+echo "--- Step 5: KG ingestion (optional) ---"
+python3 "$SCRIPT_DIR/triple_ingest.py" \
+  --memory-dir "$NOVICE_WS/memory" \
+  --ingest-module "$MODULE_ID" \
+  --modules-dir "$NOVICE_WS/modules" \
+  --embed 2>/dev/null || echo "(triple store not available — skipped)"
+echo ""
+
+# Step 6: Verify module stack
+echo "--- Step 6: Verify novice module stack ---"
+python3 "$SCRIPT_DIR/module_manager.py" \
+  --modules-dir "$NOVICE_WS/modules" stack
+echo ""
+
+# Step 7: Show imported module details
+echo "--- Step 7: Imported module details ---"
+python3 "$SCRIPT_DIR/module_manager.py" \
+  --modules-dir "$NOVICE_WS/modules" info "$MODULE_ID"
+echo ""
+
+echo "=== Transfer complete ==="
+echo ""
+echo "The novice workspace now has the expert's '$MODULE_ID' module active."
+echo "When sinain runs a heartbeat in the novice workspace, it will:"
+echo "  1. Include transferred patterns in the effective playbook"
+echo "  2. Tag them with [Transferred knowledge: ...]"
+echo "  3. Cite the origin in suggestions and insights"
+echo ""
+echo "Bundle file: $BUNDLE_PATH"

package/sinain-memory/embedder.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""Embedder — dual-strategy embedding generation and vector search.
+
+Primary: OpenRouter text-embedding-3-small (1536-dim, multilingual)
+Fallback: Local all-MiniLM-L6-v2 (384-dim, English-only)
+
+Extends the triplestore.db with an `embeddings` table for vector storage.
+Uses brute-force cosine similarity for search (<1ms for 10K entities).
+
+Usage:
+    from embedder import Embedder
+    embedder = Embedder("memory/triplestore.db")
+    vecs = embedder.embed(["OCR pipeline optimization"])
+    embedder.store_embeddings({"pattern:ocr-opt": "pattern: OCR optimization"})
+    results = embedder.vector_search(vecs[0], top_k=5)
+"""
+
+import hashlib
+import json
+import os
+import sqlite3
+import struct
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+# ── Privacy helpers ───────────────────────────────────────────────────────────
+
+def _openrouter_allowed_for(data_type: str) -> bool:
+    """Return True if the data type is allowed to be sent to OpenRouter for embedding.
+
+    Reads PRIVACY_<DATA_TYPE>_OPENROUTER env var.
+    data_type examples: "AUDIO", "OCR", "METADATA"
+    """
+    key = f"PRIVACY_{data_type.upper()}_OPENROUTER"
+    level = os.environ.get(key, "full")
+    return level not in ("none",)
+
+
+_EMBEDDINGS_SCHEMA = """
+CREATE TABLE IF NOT EXISTS embeddings (
+    entity_id  TEXT PRIMARY KEY,
+    vector     BLOB NOT NULL,
+    text_hash  TEXT NOT NULL,
+    model      TEXT NOT NULL,
+    dimensions INTEGER NOT NULL,
+    created_at TEXT NOT NULL
+);
+"""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _text_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+
+
+def _vec_to_blob(vec: list[float]) -> bytes:
+    """Pack a float vector into a compact binary blob."""
+    return struct.pack(f"{len(vec)}f", *vec)
+
+
+def _blob_to_vec(blob: bytes) -> list[float]:
+    """Unpack a binary blob into a float vector."""
+    n = len(blob) // 4  # 4 bytes per float32
+    return list(struct.unpack(f"{n}f", blob))
+
+
+class Embedder:
+    """Dual-strategy embedder with OpenRouter primary + local MiniLM fallback."""
+
+    def __init__(self, db_path: str | Path) -> None:
+        self.db_path = str(db_path)
+        self._conn = sqlite3.connect(self.db_path, timeout=10)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.executescript(_EMBEDDINGS_SCHEMA)
+        self._conn.commit()
+        self._local_model = None  # lazy-loaded
+
+    def close(self) -> None:
+        self._conn.close()
+
+    # ----- Embedding generation -----
+
+    def embed(self, texts: list[str], data_type: str = "METADATA") -> list[list[float]]:
+        """Generate embeddings for a list of texts.
+
+        Tries OpenRouter first (if allowed by privacy policy), falls back to local model.
+        Returns empty list on total failure.
+
+        Args:
+            texts: List of texts to embed.
+            data_type: Privacy data type key (e.g. "AUDIO", "OCR", "METADATA").
+                       Controls whether OpenRouter is allowed for this data.
+        """
+        if not texts:
+            return []
+
+        # Try OpenRouter first (unless privacy policy blocks it)
+        if _openrouter_allowed_for(data_type):
+            try:
+                return self._embed_openrouter(texts)
+            except Exception as e:
+                print(f"[embed] OpenRouter failed: {e}, trying local model", file=sys.stderr)
+        else:
+            print(f"[embed] OpenRouter blocked by privacy policy for {data_type}, using local model", file=sys.stderr)
+
+        # Fallback to local model
+        try:
+            return self._embed_local(texts)
+        except Exception as e:
+            print(f"[embed] Local model also failed: {e}", file=sys.stderr)
+            return [[] for _ in texts]
+
+    def _embed_openrouter(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings via OpenRouter API."""
+        import requests
+
+        api_key = os.environ.get("OPENROUTER_API_KEY") or os.environ.get("OPENROUTER_API_KEY_REFLECTION")
+        if not api_key:
+            raise RuntimeError("No API key for embeddings")
+
+        resp = requests.post(
+            "https://openrouter.ai/api/v1/embeddings",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "model": "openai/text-embedding-3-small",
+                "input": texts,
+            },
+            timeout=30,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Sort by index to maintain order
+        embeddings = sorted(data.get("data", []), key=lambda x: x.get("index", 0))
+        return [e["embedding"] for e in embeddings]
+
+    def _embed_local(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings using local sentence-transformers model."""
+        if self._local_model is None:
+            from sentence_transformers import SentenceTransformer
+            self._local_model = SentenceTransformer("all-MiniLM-L6-v2")
+
+        embeddings = self._local_model.encode(texts, convert_to_numpy=True)
+        return [vec.tolist() for vec in embeddings]
+
+    # ----- Storage -----
+
+    def store_embeddings(self, entity_texts: dict[str, str]) -> int:
+        """Embed and upsert entities into the embeddings table.
+
+        Deduplicates via text_hash — skips re-embedding if text hasn't changed.
+        Returns count of newly embedded entities.
+        """
+        if not entity_texts:
+            return 0
+
+        # Check which entities need (re-)embedding
+        to_embed: dict[str, str] = {}
+        for entity_id, text in entity_texts.items():
+            th = _text_hash(text)
+            existing = self._conn.execute(
+                "SELECT text_hash FROM embeddings WHERE entity_id = ?",
+                (entity_id,),
+            ).fetchone()
+            if existing and existing["text_hash"] == th:
+                continue  # text unchanged, skip
+            to_embed[entity_id] = text
+
+        if not to_embed:
+            return 0
+
+        # Generate embeddings
+        texts = list(to_embed.values())
+        entity_ids = list(to_embed.keys())
+        vectors = self.embed(texts)
+
+        if not vectors or not vectors[0]:
+            return 0
+
+        # Upsert into table
+        model_name = "unknown"
+        dims = len(vectors[0])
+        if dims >= 1000:
+            model_name = "text-embedding-3-small"
+        elif dims > 0:
+            model_name = "all-MiniLM-L6-v2"
+
+        now = _now_iso()
+        count = 0
+        for entity_id, text, vec in zip(entity_ids, texts, vectors):
+            if not vec:
+                continue
+            self._conn.execute(
+                "INSERT OR REPLACE INTO embeddings "
+                "(entity_id, vector, text_hash, model, dimensions, created_at) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (entity_id, _vec_to_blob(vec), _text_hash(text), model_name, len(vec), now),
+            )
+            count += 1
+        self._conn.commit()
+        return count
+
+    # ----- Vector search -----
+
+    def vector_search(
+        self,
+        query_vec: list[float],
+        top_k: int = 10,
+        entity_types: list[str] | None = None,
+    ) -> list[tuple[str, float]]:
+        """Brute-force cosine similarity search.
+
+        Returns [(entity_id, score)] sorted by score descending.
+        """
+        if not query_vec:
+            return []
+
+        # Load all embeddings (optionally filtered by type)
+        if entity_types:
+            placeholders = ",".join("?" * len(entity_types))
+            # Filter by entity_id prefix
+            conditions = " OR ".join(f"entity_id LIKE ?" for _ in entity_types)
+            params = [f"{t}:%" for t in entity_types]
+            rows = self._conn.execute(
+                f"SELECT entity_id, vector FROM embeddings WHERE {conditions}",
+                params,
+            ).fetchall()
+        else:
+            rows = self._conn.execute(
+                "SELECT entity_id, vector FROM embeddings"
+            ).fetchall()
+
+        if not rows:
+            return []
+
+        # Compute cosine similarity
+        results: list[tuple[str, float]] = []
+        q_norm = _norm(query_vec)
+        if q_norm == 0:
+            return []
+
+        for row in rows:
+            vec = _blob_to_vec(row["vector"])
+            if len(vec) != len(query_vec):
+                continue  # dimension mismatch (mixed models)
+            score = _dot(query_vec, vec) / (q_norm * _norm(vec))
+            results.append((row["entity_id"], score))
+
+        results.sort(key=lambda x: x[1], reverse=True)
+        return results[:top_k]
+
+
+def _dot(a: list[float], b: list[float]) -> float:
+    """Dot product of two vectors."""
+    return sum(x * y for x, y in zip(a, b))
+
+
+def _norm(v: list[float]) -> float:
+    """L2 norm of a vector."""
+    return sum(x * x for x in v) ** 0.5

package/sinain-memory/eval/assertions.py

@@ -0,0 +1,288 @@
+"""Behavioral assertion library for sinain-koog tick evaluation.
+
+Each assertion function validates a runtime invariant of the pipeline.
+Returns ``{"name": str, "passed": bool, "detail": str}``.
+"""
+
+from __future__ import annotations
+
+
+def _result(name: str, passed: bool, detail: str) -> dict:
+    return {"name": name, "passed": passed, "detail": detail}
+
+
+# ---------------------------------------------------------------------------
+# Playbook curator assertions
+# ---------------------------------------------------------------------------
+
+def assert_playbook_under_limit(curator_result: dict, limit: int = 50) -> dict:
+    """Verify playbook body stays under the line limit."""
+    lines = curator_result.get("playbookLines", 0)
+    if lines <= limit:
+        return _result("playbook_under_limit", True, f"body has {lines} lines (limit {limit})")
+    return _result("playbook_under_limit", False, f"body has {lines} lines, exceeds limit of {limit}")
+
+
+def assert_curator_respected_directive(curator_result: dict, directive: str) -> dict:
+    """Check that curator changes align with the curate directive."""
+    changes = curator_result.get("changes", {})
+    added = len(changes.get("added", []))
+    pruned = len(changes.get("pruned", []))
+
+    if directive == "aggressive_prune":
+        # Should have pruned items
+        if pruned > 0:
+            return _result("curator_respected_directive", True,
+                           f"aggressive_prune: pruned {pruned} items")
+        if added == 0 and pruned == 0:
+            return _result("curator_respected_directive", True,
+                           "aggressive_prune: no changes (acceptable if playbook already lean)")
+        return _result("curator_respected_directive", False,
+                       f"aggressive_prune: added {added} but pruned {pruned} — expected pruning")
+
+    if directive == "stability":
+        # Should not aggressively prune established patterns
+        if pruned > added + 2:
+            return _result("curator_respected_directive", False,
+                           f"stability: pruned {pruned} items (only added {added}) — too aggressive for stability mode")
+        return _result("curator_respected_directive", True,
+                       f"stability: added {added}, pruned {pruned} — conservative")
+
+    # normal / insufficient_data — any reasonable mix is fine
+    return _result("curator_respected_directive", True,
+                   f"{directive}: added {added}, pruned {pruned}")
+
+
+# ---------------------------------------------------------------------------
+# Signal analyzer assertions
+# ---------------------------------------------------------------------------
+
+def assert_no_repeat_action(signal_result: dict, recent_logs: list[dict], window: int = 3) -> dict:
+    """Verify recommendedAction doesn't repeat the last N ticks' actions."""
+    action = signal_result.get("recommendedAction")
+    if action is None or action.get("action") == "skip":
+        return _result("no_repeat_action", True, "no action recommended (skip/null)")
+
+    task = (action.get("task") or "").lower().strip()
+    if not task:
+        return _result("no_repeat_action", True, "no task description to compare")
+
+    # Collect recent action tasks
+    recent_tasks: list[str] = []
+    for log in recent_logs[:window]:
+        log_actions = log.get("actionsConsidered", [])
+        for a in log_actions:
+            if a.get("chosen"):
+                recent_tasks.append((a.get("reason") or a.get("task") or "").lower().strip())
+
+    # Check for near-duplicate (substring match to catch rephrasing)
+    for prev_task in recent_tasks:
+        if not prev_task:
+            continue
+        # If >60% of words overlap, consider it a repeat
+        task_words = set(task.split())
+        prev_words = set(prev_task.split())
+        if not task_words or not prev_words:
+            continue
+        overlap = len(task_words & prev_words) / max(len(task_words), len(prev_words))
+        if overlap > 0.6:
+            return _result("no_repeat_action", False,
+                           f"action task '{task[:60]}' overlaps with recent '{prev_task[:60]}' ({overlap:.0%} word overlap)")
+
+    return _result("no_repeat_action", True,
+                   f"action task is distinct from last {window} ticks")
+
+
+def assert_signal_confidence_threshold(signal_result: dict, threshold: float = 0.5) -> dict:
+    """Verify actions are only recommended above the confidence threshold."""
+    action = signal_result.get("recommendedAction")
+    if action is None or action.get("action") == "skip":
+        return _result("signal_confidence_threshold", True, "no action recommended")
+
+    confidence = action.get("confidence")
+    if confidence is None:
+        return _result("signal_confidence_threshold", False,
+                       "action recommended but no confidence value provided")
+
+    if confidence >= threshold:
+        return _result("signal_confidence_threshold", True,
+                       f"confidence {confidence:.2f} >= threshold {threshold}")
+    return _result("signal_confidence_threshold", False,
+                   f"confidence {confidence:.2f} < threshold {threshold}")
+
+
+# ---------------------------------------------------------------------------
+# Insight synthesizer assertions
+# ---------------------------------------------------------------------------
+
+def assert_insight_char_limit(synth_result: dict, limit: int = 500) -> dict:
+    """Verify suggestion+insight stays under the character limit."""
+    if synth_result.get("skip", False):
+        return _result("insight_char_limit", True, "output skipped")
+
+    suggestion = synth_result.get("suggestion", "")
+    insight = synth_result.get("insight", "")
+    total = len(suggestion) + len(insight)
+
+    if total <= limit:
+        return _result("insight_char_limit", True, f"total {total} chars (limit {limit})")
+    return _result("insight_char_limit", False, f"total {total} chars exceeds limit of {limit}")
+
+
+def assert_skip_reason_specific(synth_result: dict) -> dict:
+    """If skip=true, verify the reason is specific (not generic boilerplate)."""
+    if not synth_result.get("skip", False):
+        return _result("skip_reason_specific", True, "output not skipped")
+
+    reason = (synth_result.get("skipReason") or "").strip()
+    if not reason:
+        return _result("skip_reason_specific", False, "skip=true but no skipReason provided")
+
+    # Check against known-generic patterns
+    generic_phrases = [
+        "no new data",
+        "nothing new",
+        "no updates",
+        "insufficient data",
+        "not enough information",
+        "no changes",
+    ]
+    reason_lower = reason.lower()
+    for phrase in generic_phrases:
+        if reason_lower == phrase or (len(reason_lower) < 30 and phrase in reason_lower):
+            return _result("skip_reason_specific", False,
+                           f"skipReason is too generic: '{reason}'")
+
+    return _result("skip_reason_specific", True, f"skipReason is specific ({len(reason)} chars)")
+
+
+# ---------------------------------------------------------------------------
+# Memory miner assertions
+# ---------------------------------------------------------------------------
+
+def assert_miner_references_sources(miner_result: dict, daily_files: list[str]) -> dict:
+    """Verify mining findings reference actual source files that were provided."""
+    mined = miner_result.get("minedSources", [])
+    if not mined:
+        return _result("miner_references_sources", True, "no sources mined (early return)")
+
+    # daily_files contains basenames like "2026-02-21.md"
+    known_basenames = set(daily_files)
+    unknown = [s for s in mined if s not in known_basenames]
+
+    if unknown:
+        return _result("miner_references_sources", False,
+                       f"minedSources references unknown files: {unknown}")
+    return _result("miner_references_sources", True,
+                   f"all {len(mined)} mined sources are valid")
+
+
+# ---------------------------------------------------------------------------
+# Cross-script / structural assertions
+# ---------------------------------------------------------------------------
+
+def assert_schema_valid(script_name: str, output: dict, schema_errors: list[str]) -> dict:
+    """Wrap schema validation result as an assertion."""
+    if not schema_errors:
+        return _result(f"schema_valid_{script_name}", True, "output matches schema")
+    return _result(f"schema_valid_{script_name}", False,
+                   f"{len(schema_errors)} schema errors: {'; '.join(schema_errors[:3])}")
+
+
+def assert_playbook_header_footer_intact(playbook_text: str) -> dict:
+    """Verify the playbook still has its mining-index header and effectiveness footer."""
+    has_header = "<!-- mining-index:" in playbook_text
+    has_footer = "<!-- effectiveness:" in playbook_text
+
+    if has_header and has_footer:
+        return _result("playbook_header_footer_intact", True,
+                       "both mining-index and effectiveness comments present")
+    missing = []
+    if not has_header:
+        missing.append("mining-index")
+    if not has_footer:
+        missing.append("effectiveness")
+    return _result("playbook_header_footer_intact", False,
+                   f"missing playbook comments: {', '.join(missing)}")
+
+
+# ---------------------------------------------------------------------------
+# Trait voice assertions (sinain-core wiring verification)
+# ---------------------------------------------------------------------------
+
+def assert_situation_has_active_voice(
+    situation_content: str, expected_trait: str | None = None
+) -> dict:
+    """Check SITUATION.md contains an Active Voice section (after trait wiring).
+
+    Called by tick_evaluator.py when processing live ticks that have SITUATION.md
+    content and a trait was selected for that tick.
+    """
+    has_section = "## Active Voice" in situation_content
+    if not has_section:
+        return _result("situation_has_active_voice", False, "no '## Active Voice' section")
+    if expected_trait and expected_trait not in situation_content:
+        return _result("situation_has_active_voice", False,
+                       f"section present but '{expected_trait}' not found")
+    return _result("situation_has_active_voice", True, "Active Voice section present")
+
+
+# ---------------------------------------------------------------------------
+# Runner: execute all applicable assertions for a tick
+# ---------------------------------------------------------------------------
+
+def run_tick_assertions(
+    log_entry: dict,
+    recent_logs: list[dict],
+    playbook_text: str,
+    daily_files: list[str],
+) -> list[dict]:
+    """Run all applicable assertions against a single tick's log entry.
+
+    Returns a list of assertion result dicts.
+    """
+    results: list[dict] = []
+
+    # Signal analyzer assertions
+    signals = log_entry.get("signals")
+    if signals is not None:
+        results.append(assert_signal_confidence_threshold(
+            {"signals": signals, "recommendedAction": log_entry.get("recommendedAction")},
+        ))
+        results.append(assert_no_repeat_action(
+            {"signals": signals, "recommendedAction": log_entry.get("recommendedAction")},
+            recent_logs,
+        ))
+
+    # Curator assertions — playbookChanges can be {"note": "skipped"} or full output
+    curator = log_entry.get("playbookChanges")
+    if isinstance(curator, dict) and "changes" in curator:
+        curator_with_lines = {**curator}
+        if "playbookLines" not in curator_with_lines:
+            curator_with_lines["playbookLines"] = curator.get("playbookLines", 0)
+        results.append(assert_playbook_under_limit(curator_with_lines))
+
+        directive = log_entry.get("curateDirective", "normal")
+        results.append(assert_curator_respected_directive(curator_with_lines, directive))
+
+    # Insight synthesizer assertions — output can be null (pipeline-level skip)
+    output = log_entry.get("output")
+    if isinstance(output, dict):
+        results.append(assert_insight_char_limit(output))
+        results.append(assert_skip_reason_specific(output))
+
+    # Mining assertions — log uses miningFindings (str) and minedSources (list)
+    mining = log_entry.get("miningResult")
+    if mining is not None:
+        results.append(assert_miner_references_sources(mining, daily_files))
+    elif log_entry.get("minedSources"):
+        # Reconstruct mining result from flat log fields
+        results.append(assert_miner_references_sources(
+            {"minedSources": log_entry.get("minedSources", [])}, daily_files
+        ))
+
+    # Playbook health (if we have playbook text)
+    if playbook_text:
+        results.append(assert_playbook_header_footer_intact(playbook_text))
+
+    return results