nexo-brain 3.2.0 → 4.0.0

package/src/system_catalog.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 
 import ast
 import importlib.util
+import inspect
 import json
 import os
+import re
 import sys
 from pathlib import Path
 
@@ -28,6 +30,8 @@ SECTION_ORDER = (
     "artifacts",
 )
 
+_DOC_ARG_LINE_RE = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$")
+
 
 def _normalize_text(text: str | None) -> str:
     return str(text or "").strip().lower()
@@ -84,6 +88,287 @@ def _tool_category(name: str) -> str:
     return "general"
 
 
+def _annotation_text_from_ast(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _literal_text(value) -> str:
+    if value is inspect._empty:
+        return ""
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if value is None:
+        return "None"
+    return repr(value)
+
+
+def _default_text_from_ast(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return _literal_text(ast.literal_eval(node))
+    except Exception:
+        try:
+            return ast.unparse(node)
+        except Exception:
+            return "..."
+
+
+def _annotation_text(annotation) -> str:
+    if annotation is inspect._empty:
+        return ""
+    if isinstance(annotation, str):
+        return annotation
+    if getattr(annotation, "__module__", "") == "builtins" and hasattr(annotation, "__name__"):
+        return str(annotation.__name__)
+    text = str(annotation)
+    return text.replace("typing.", "")
+
+
+def _parse_arg_docs(doc: str) -> dict[str, str]:
+    docs: dict[str, str] = {}
+    if not doc.strip():
+        return docs
+    in_args = False
+    current_arg = ""
+    for raw_line in doc.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        if stripped in {"Args:", "Arguments:"}:
+            in_args = True
+            current_arg = ""
+            continue
+        if not in_args:
+            continue
+        if stripped and not raw_line.startswith((" ", "\t")) and stripped.endswith(":"):
+            break
+        if not stripped:
+            current_arg = ""
+            continue
+        match = _DOC_ARG_LINE_RE.match(raw_line)
+        if match:
+            current_arg = match.group(1)
+            docs[current_arg] = match.group(2).strip()
+            continue
+        if current_arg:
+            docs[current_arg] = f"{docs[current_arg]} {stripped}".strip()
+    return docs
+
+
+def _build_signature(name: str, params: list[dict], return_annotation: str = "") -> str:
+    pieces: list[str] = []
+    for param in params:
+        part = param["name"]
+        if param.get("annotation"):
+            part += f": {param['annotation']}"
+        if not param.get("required", False):
+            part += f" = {param.get('default', '')}"
+        pieces.append(part)
+    signature = f"{name}({', '.join(pieces)})"
+    if return_annotation:
+        signature += f" -> {return_annotation}"
+    return signature
+
+
+def _example_value_for_param(param: dict) -> str:
+    name = str(param.get("name", "value"))
+    annotation = str(param.get("annotation", "")).lower()
+    if name == "id" or name.endswith("_id"):
+        return '"..."'
+    if name.endswith("_token") or name == "read_token":
+        return '"TOKEN"'
+    if "bool" in annotation:
+        return "True"
+    if "int" in annotation:
+        return "1"
+    if "float" in annotation:
+        return "1.0"
+    if "list" in annotation or name.endswith("s"):
+        return '["..."]'
+    if "dict" in annotation or "object" in annotation:
+        return '{"key": "value"}'
+    return '"..."'
+
+
+def _generic_example(name: str, params: list[dict]) -> str:
+    required = [param for param in params if param.get("required", False)]
+    if not required:
+        return f"{name}()"
+    pieces = [f"{param['name']}={_example_value_for_param(param)}" for param in required]
+    return f"{name}({', '.join(pieces)})"
+
+
+def _ast_params_for_node(node: ast.FunctionDef, arg_docs: dict[str, str]) -> list[dict]:
+    params: list[dict] = []
+    positional = list(node.args.posonlyargs) + list(node.args.args)
+    positional_defaults = [None] * (len(positional) - len(node.args.defaults)) + list(node.args.defaults)
+    for arg_node, default_node in zip(positional, positional_defaults):
+        if arg_node.arg in {"self", "cls"}:
+            continue
+        params.append(
+            {
+                "name": arg_node.arg,
+                "annotation": _annotation_text_from_ast(arg_node.annotation),
+                "required": default_node is None,
+                "default": "" if default_node is None else _default_text_from_ast(default_node),
+                "description": arg_docs.get(arg_node.arg, ""),
+            }
+        )
+    for arg_node, default_node in zip(node.args.kwonlyargs, node.args.kw_defaults):
+        if arg_node.arg in {"self", "cls"}:
+            continue
+        params.append(
+            {
+                "name": arg_node.arg,
+                "annotation": _annotation_text_from_ast(arg_node.annotation),
+                "required": default_node is None,
+                "default": "" if default_node is None else _default_text_from_ast(default_node),
+                "description": arg_docs.get(arg_node.arg, ""),
+            }
+        )
+    return params
+
+
+def _callable_params(func, arg_docs: dict[str, str]) -> list[dict]:
+    params: list[dict] = []
+    try:
+        signature = inspect.signature(func)
+    except (TypeError, ValueError):
+        return params
+    for name, param in signature.parameters.items():
+        if name in {"self", "cls"}:
+            continue
+        required = param.default is inspect._empty
+        params.append(
+            {
+                "name": name,
+                "annotation": _annotation_text(param.annotation),
+                "required": required,
+                "default": "" if required else _literal_text(param.default),
+                "description": arg_docs.get(name, ""),
+            }
+        )
+    return params
+
+
+def _guide_for_tool(name: str) -> dict[str, list]:
+    if name == "nexo_learning_add":
+        return {
+            "workflow": [
+                "Usa `applies_to` si quieres que el guard recuerde este learning antes de tocar un archivo, directorio o patrón concreto.",
+                "Usa `priority` (`critical`, `high`, `medium`, `low`) para marcar severidad operativa.",
+            ],
+            "examples": [
+                {
+                    "title": "Learning mínimo",
+                    "code": 'nexo_learning_add(category="shopify", title="Hacer pull antes de editar", content="Siempre sincronizar antes de editar el tema live.")',
+                },
+                {
+                    "title": "Learning ligado a archivo o patrón",
+                    "code": 'nexo_learning_add(category="recambios-bmw", title="Pull antes de editar theme", content="El admin puede tocar JSONs live.", applies_to="/abs/path/templates/product.json,templates/*.json,sections/*.liquid", prevention="Ejecutar `shopify theme pull` antes de editar.", priority="high")',
+                },
+            ],
+            "common_errors": [
+                "Usar `severity` en vez de `priority`.",
+                "Olvidar `title`, que es obligatorio.",
+                "No poner `applies_to` cuando quieres que el warning salte antes de tocar archivos concretos.",
+            ],
+        }
+    if name == "nexo_learning_update":
+        return {
+            "workflow": [
+                "Úsalo para completar o endurecer un learning existente cuando descubres nuevos archivos afectados, mejor `prevention` o prioridad distinta.",
+            ],
+            "examples": [
+                {
+                    "title": "Añadir alcance a un learning existente",
+                    "code": 'nexo_learning_update(id=57, applies_to="/abs/path/file.py,src/plugins/*.py", prevention="Leer schema antes del primer uso", priority="high")',
+                },
+            ],
+            "common_errors": [
+                "Intentar recrear el learning desde cero cuando basta con actualizar el existente.",
+            ],
+        }
+    if name == "nexo_reminder_get":
+        return {
+            "workflow": [
+                "Devuelve el `READ_TOKEN` necesario para `update`, `delete`, `restore` y `note` sobre ese reminder.",
+            ],
+            "examples": [
+                {
+                    "title": "Leer reminder y obtener token",
+                    "code": 'nexo_reminder_get(id="R87")',
+                },
+            ],
+            "common_errors": [
+                "Intentar editar o borrar un reminder sin llamar antes a `nexo_reminder_get`.",
+            ],
+        }
+    if name in {"nexo_reminder_update", "nexo_reminder_delete", "nexo_reminder_restore", "nexo_reminder_note"}:
+        return {
+            "workflow": [
+                "Primero llama `nexo_reminder_get(id=\"R87\")` para obtener `READ_TOKEN`.",
+                f"Luego reutiliza ese `READ_TOKEN` en `{name}(...)`.",
+            ],
+            "examples": [
+                {
+                    "title": "1. Obtener token",
+                    "code": 'nexo_reminder_get(id="R87")',
+                },
+                {
+                    "title": "2. Reutilizar READ_TOKEN",
+                    "code": f'{name}(id="R87", read_token="TOKEN")',
+                },
+            ],
+            "common_errors": [
+                "Llamar a esta tool sin `READ_TOKEN` válido.",
+                "Usar un `READ_TOKEN` de otro reminder o de una lectura antigua.",
+            ],
+        }
+    if name == "nexo_followup_get":
+        return {
+            "workflow": [
+                "Devuelve el `READ_TOKEN` necesario para `update`, `delete`, `restore` y `note` sobre ese followup.",
+            ],
+            "examples": [
+                {
+                    "title": "Leer followup y obtener token",
+                    "code": 'nexo_followup_get(id="NF45")',
+                },
+            ],
+            "common_errors": [
+                "Intentar editar o borrar un followup sin llamar antes a `nexo_followup_get`.",
+            ],
+        }
+    if name in {"nexo_followup_update", "nexo_followup_delete", "nexo_followup_restore", "nexo_followup_note"}:
+        return {
+            "workflow": [
+                "Primero llama `nexo_followup_get(id=\"NF45\")` para obtener `READ_TOKEN`.",
+                f"Luego reutiliza ese `READ_TOKEN` en `{name}(...)`.",
+            ],
+            "examples": [
+                {
+                    "title": "1. Obtener token",
+                    "code": 'nexo_followup_get(id="NF45")',
+                },
+                {
+                    "title": "2. Reutilizar READ_TOKEN",
+                    "code": f'{name}(id="NF45", read_token="TOKEN")',
+                },
+            ],
+            "common_errors": [
+                "Llamar a esta tool sin `READ_TOKEN` válido.",
+                "Usar un `READ_TOKEN` de otro followup o de una lectura antigua.",
+            ],
+        }
+    return {}
+
+
 def _parse_core_tools() -> list[dict]:
     if not SERVER_PATH.is_file():
         return []
@@ -103,44 +388,78 @@ def _parse_core_tools() -> list[dict]:
             continue
         doc = ast.get_docstring(node) or ""
         first_line = doc.strip().splitlines()[0].strip() if doc.strip() else ""
+        arg_docs = _parse_arg_docs(doc)
+        params = _ast_params_for_node(node, arg_docs)
         entries.append(
             {
                 "kind": "core_tool",
                 "name": node.name,
                 "description": first_line,
+                "doc": doc,
                 "category": _tool_category(node.name),
                 "path": str(SERVER_PATH),
                 "line": int(getattr(node, "lineno", 0) or 0),
+                "params": params,
+                "signature": _build_signature(
+                    node.name,
+                    params,
+                    _annotation_text_from_ast(node.returns),
+                ),
+                "quick_example": _generic_example(node.name, params),
                 "source": "core",
             }
         )
     return entries
 
 
-def _plugin_module_tools(filename: str, created_by: str) -> dict[str, str]:
+def _plugin_module_tools(filename: str, created_by: str) -> list[dict]:
     module_name = f"plugins.{filename[:-3]}"
     module = sys.modules.get(module_name)
     if module is None:
         plugin_dir = PLUGINS_DIR if created_by == "repo" else PERSONAL_PLUGINS_DIR
         path = Path(plugin_dir) / filename
         if not path.is_file():
-            return {}
+            return []
         try:
             spec = importlib.util.spec_from_file_location(module_name, path)
             if spec is None or spec.loader is None:
-                return {}
+                return []
             module = importlib.util.module_from_spec(spec)
             spec.loader.exec_module(module)
         except Exception:
-            return {}
+            return []
     tools = getattr(module, "TOOLS", []) or []
-    result: dict[str, str] = {}
+    result: list[dict] = []
     for item in tools:
         try:
-            _, name, description = item
+            func, name, description = item
         except Exception:
             continue
-        result[str(name)] = str(description or "")
+        doc = inspect.getdoc(func) or ""
+        arg_docs = _parse_arg_docs(doc)
+        params = _callable_params(func, arg_docs)
+        try:
+            return_annotation = _annotation_text(inspect.signature(func).return_annotation)
+        except (TypeError, ValueError):
+            return_annotation = ""
+        result.append(
+            {
+                "kind": "plugin_tool",
+                "name": str(name),
+                "description": str(description or ""),
+                "doc": doc,
+                "params": params,
+                "signature": _build_signature(
+                    str(name),
+                    params,
+                    return_annotation,
+                ),
+                "quick_example": _generic_example(str(name), params),
+                "plugin": filename,
+                "source": created_by,
+                "category": _tool_category(str(name)),
+            }
+        )
     return result
 
 
@@ -150,14 +469,17 @@ def _plugin_entries() -> list[dict]:
     for row in rows:
         filename = str(row.get("filename") or "")
         created_by = str(row.get("created_by") or row.get("source") or "repo")
-        descriptions = _plugin_module_tools(filename, created_by)
+        plugin_tools = _plugin_module_tools(filename, created_by)
+        if plugin_tools:
+            entries.extend(plugin_tools)
+            continue
         names = str(row.get("tool_names") or "").split(",")
         for name in [n.strip() for n in names if n.strip()]:
             entries.append(
                 {
                     "kind": "plugin_tool",
                     "name": name,
-                    "description": descriptions.get(name, ""),
+                    "description": "",
                     "plugin": filename,
                     "source": created_by,
                     "category": _tool_category(name),
@@ -339,13 +661,20 @@ def explain_tool(name: str) -> dict | None:
     clean = _normalize_text(name)
     if not clean:
         return None
-    exact = search_system_catalog(clean, limit=200)
-    for row in exact:
-        if _normalize_text(row.get("name")) == clean:
-            return row
-    for row in exact:
-        if clean in _normalize_text(row.get("name")):
-            return row
+    candidates = [clean]
+    if clean.startswith("mcp__nexo__"):
+        candidates.append(clean.split("mcp__nexo__", 1)[1])
+    if "__" in clean:
+        candidates.append(clean.split("__")[-1])
+    seen: set[str] = set()
+    for candidate in [item for item in candidates if item and not (item in seen or seen.add(item))]:
+        exact = search_system_catalog(candidate, limit=200)
+        for row in exact:
+            if _normalize_text(row.get("name")) == candidate:
+                return row
+        for row in exact:
+            if candidate in _normalize_text(row.get("name")):
+                return row
     return None
 
 
@@ -386,6 +715,12 @@ def format_catalog(catalog: dict, *, section: str = "", query: str = "", limit:
 def format_tool_explanation(entry: dict | None) -> str:
     if not entry:
         return "Tool/capability not found in the live system catalog."
+    params = entry.get("params") or []
+    required = [param for param in params if param.get("required")]
+    optional = [param for param in params if not param.get("required")]
+    guide = _guide_for_tool(str(entry.get("name") or ""))
+    examples = [{"title": "Quick example", "code": entry["quick_example"]}] if entry.get("quick_example") else []
+    examples.extend(guide.get("examples", []))
     lines = [
         f"CATALOG ENTRY — {entry.get('name') or entry.get('display_name')}",
         f"Section: {entry.get('_section') or entry.get('kind')}",
@@ -416,4 +751,36 @@ def format_tool_explanation(entry: dict | None) -> str:
         lines.append(f"Execution level: {entry['execution_level']}")
     if entry.get("domain"):
         lines.append(f"Domain: {entry['domain']}")
+    if entry.get("signature"):
+        lines.append(f"Signature: {entry['signature']}")
+    if required:
+        lines.append("Required args:")
+        for param in required:
+            detail = param.get("description") or "No description."
+            annotation = f" ({param['annotation']})" if param.get("annotation") else ""
+            lines.append(f"- {param['name']}{annotation}: {detail}")
+    if optional:
+        lines.append("Optional args:")
+        for param in optional:
+            detail = param.get("description") or "Optional."
+            annotation = f" ({param['annotation']})" if param.get("annotation") else ""
+            default = f" Default: {param['default']}." if param.get("default", "") != "" else ""
+            lines.append(f"- {param['name']}{annotation}: {detail}{default}")
+    if guide.get("workflow"):
+        lines.append("Workflow notes:")
+        for item in guide["workflow"]:
+            lines.append(f"- {item}")
+    if examples:
+        lines.append("Examples:")
+        for example in examples:
+            title = str(example.get("title") or "").strip()
+            code = str(example.get("code") or "").strip()
+            if title:
+                lines.append(f"- {title}")
+            if code:
+                lines.append(f"  {code}")
+    if guide.get("common_errors"):
+        lines.append("Common errors:")
+        for item in guide["common_errors"]:
+            lines.append(f"- {item}")
     return "\n".join(lines)

package/src/user_state_model.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+"""Inspectable user-state model built from multiple NEXO signals."""
+
+import json
+from datetime import UTC, datetime, timedelta
+
+import cognitive
+from db import get_db
+from db._hot_context import search_hot_context
+from memory_backends import get_backend
+
+
+def init_tables() -> None:
+    conn = get_db()
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS user_state_snapshots (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            state_label TEXT NOT NULL,
+            confidence REAL DEFAULT 0.0,
+            guidance TEXT DEFAULT '',
+            signals TEXT DEFAULT '{}',
+            backend_key TEXT DEFAULT 'sqlite',
+            created_at TEXT DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_user_state_snapshots_created ON user_state_snapshots(created_at);
+        CREATE INDEX IF NOT EXISTS idx_user_state_snapshots_label ON user_state_snapshots(state_label);
+        """
+    )
+    conn.commit()
+
+
+def _recent_correction_count(days: int) -> int:
+    cutoff = (datetime.now(UTC) - timedelta(days=days)).isoformat()
+    row = cognitive._get_db().execute(
+        "SELECT COUNT(*) FROM memory_corrections WHERE created_at >= ?",
+        (cutoff,),
+    ).fetchone()
+    return int((row[0] if row else 0) or 0)
+
+
+def _recent_trust_event_count(days: int, event_name: str) -> int:
+    cutoff = (datetime.now(UTC) - timedelta(days=days)).isoformat()
+    row = cognitive._get_db().execute(
+        "SELECT COUNT(*) FROM trust_score WHERE created_at >= ? AND event = ?",
+        (cutoff, event_name),
+    ).fetchone()
+    return int((row[0] if row else 0) or 0)
+
+
+def _recent_diary_signal_count(days: int) -> int:
+    cutoff = (datetime.now(UTC) - timedelta(days=days)).isoformat(timespec="seconds")
+    row = get_db().execute(
+        "SELECT COUNT(*) FROM session_diary WHERE created_at >= ? AND user_signals != ''",
+        (cutoff,),
+    ).fetchone()
+    return int((row[0] if row else 0) or 0)
+
+
+def build_user_state(days: int = 7, *, persist: bool = False) -> dict:
+    init_tables()
+    trust = float(cognitive.get_trust_score())
+    history = cognitive.get_trust_history(days=days)
+    sentiments = history.get("sentiment_distribution", {})
+    negative = int((sentiments.get("negative") or {}).get("count", 0) or 0)
+    urgent = int((sentiments.get("urgent") or {}).get("count", 0) or 0)
+    positive = int((sentiments.get("positive") or {}).get("count", 0) or 0)
+    corrections = _recent_correction_count(days)
+    repeated_errors = _recent_trust_event_count(days, "repeated_error")
+    productive_sessions = _recent_trust_event_count(days, "session_productive")
+    delegation_events = _recent_trust_event_count(days, "delegation")
+    diaries_with_signals = _recent_diary_signal_count(days)
+    active_contexts = len(search_hot_context("", hours=min(max(days, 1) * 24, 168), limit=50, state="active"))
+    waiting_contexts = len(search_hot_context("", hours=min(max(days, 1) * 24, 168), limit=50, state="waiting_user"))
+    blocked_contexts = len(search_hot_context("", hours=min(max(days, 1) * 24, 168), limit=50, state="blocked"))
+
+    frustration_score = negative * 1.5 + corrections * 0.8 + repeated_errors * 1.2 + (1 if trust < 45 else 0)
+    flow_score = positive * 1.2 + productive_sessions * 1.0 + delegation_events * 0.8 + (1 if trust > 60 else 0)
+    urgency_score = urgent * 2.0 + blocked_contexts * 0.6
+
+    if urgency_score >= max(2.0, frustration_score, flow_score):
+        label = "urgent"
+        guidance = "Immediate execution. Keep answers short. Avoid speculative detours."
+        confidence = min(0.98, 0.45 + urgency_score * 0.12)
+    elif frustration_score >= max(2.0, flow_score):
+        label = "frustrated"
+        guidance = "Ultra-concise mode. Show concrete progress and avoid avoidable questions."
+        confidence = min(0.98, 0.4 + frustration_score * 0.1)
+    elif flow_score >= 2.5:
+        label = "in_flow"
+        guidance = "Keep momentum. Bias toward execution and only interrupt for real blockers."
+        confidence = min(0.98, 0.4 + flow_score * 0.09)
+    elif waiting_contexts > 0 or active_contexts > 6:
+        label = "loaded"
+        guidance = "Prefer batching, tight summaries, and explicit next actions."
+        confidence = 0.68
+    else:
+        label = "stable"
+        guidance = "Normal mode. Clear, direct execution with selective initiative."
+        confidence = 0.6
+
+    snapshot = {
+        "state_label": label,
+        "confidence": round(confidence, 2),
+        "guidance": guidance,
+        "trust_score": round(trust, 1),
+        "signals": {
+            "negative_sentiment": negative,
+            "urgent_sentiment": urgent,
+            "positive_sentiment": positive,
+            "recent_corrections": corrections,
+            "repeated_errors": repeated_errors,
+            "productive_sessions": productive_sessions,
+            "delegation_events": delegation_events,
+            "diaries_with_user_signals": diaries_with_signals,
+            "active_contexts": active_contexts,
+            "waiting_contexts": waiting_contexts,
+            "blocked_contexts": blocked_contexts,
+        },
+        "backend": get_backend().key,
+    }
+
+    if persist:
+        conn = get_db()
+        conn.execute(
+            "INSERT INTO user_state_snapshots (state_label, confidence, guidance, signals, backend_key) VALUES (?, ?, ?, ?, ?)",
+            (
+                snapshot["state_label"],
+                snapshot["confidence"],
+                snapshot["guidance"],
+                json.dumps(snapshot["signals"], ensure_ascii=True, sort_keys=True),
+                snapshot["backend"],
+            ),
+        )
+        conn.commit()
+
+    return snapshot
+
+
+def list_user_state_snapshots(limit: int = 20) -> list[dict]:
+    init_tables()
+    rows = get_db().execute(
+        "SELECT * FROM user_state_snapshots ORDER BY created_at DESC, id DESC LIMIT ?",
+        (max(1, int(limit or 20)),),
+    ).fetchall()
+    results = []
+    for row in rows:
+        item = dict(row)
+        try:
+            item["signals"] = json.loads(item.get("signals") or "{}")
+        except Exception:
+            item["signals"] = {}
+        results.append(item)
+    return results
+
+
+def user_state_stats(days: int = 30) -> dict:
+    init_tables()
+    cutoff = (datetime.now(UTC) - timedelta(days=days)).isoformat(timespec="seconds")
+    rows = get_db().execute(
+        "SELECT state_label, COUNT(*) AS cnt FROM user_state_snapshots WHERE created_at >= ? GROUP BY state_label",
+        (cutoff,),
+    ).fetchall()
+    return {
+        "window_days": days,
+        "snapshots": sum(int(row["cnt"]) for row in rows),
+        "by_state": {row["state_label"]: row["cnt"] for row in rows},
+        "backend": get_backend().key,
+    }