@heytherevibin/skillforge 0.10.0 → 0.11.7

package/python/app/agent_cli.py

@@ -0,0 +1,334 @@
+"""
+``skillforge agent`` — OpenAI-compatible chat completions + Skillforge MCP tool handlers.
+
+Requires ``openai`` and a reachable ``/v1`` API (Ollama, LiteLLM, OpenAI, etc.).
+Read-only MCP tools only (no writes) for v1.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+
+TOOLS: list[dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "route_skills",
+            "description": "Route prompts to SKILL.md snippets (MCP parity). Supports host-mode two-step if ROUTER_MODE=host.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "prompt": {"type": "string"},
+                    "project_root": {"type": "string"},
+                    "session_id": {"type": "string"},
+                    "user_id": {"type": "string"},
+                    "picked_names": {"type": "array", "items": {"type": "string"}},
+                    "include_project_rag": {"type": "boolean"},
+                },
+                "required": ["prompt"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "search_skills",
+            "description": "Embedding-only similarity shortlist.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string"},
+                    "limit": {"type": "integer"},
+                    "project_root": {"type": "string"},
+                    "user_id": {"type": "string"},
+                },
+                "required": ["query"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "explain_route",
+            "description": "Routing diagnostics without session commits.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "prompt": {"type": "string"},
+                    "limit": {"type": "integer"},
+                    "project_root": {"type": "string"},
+                    "user_id": {"type": "string"},
+                },
+                "required": ["prompt"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_skill",
+            "description": "Fetch one SKILL by catalog id.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "skill_name": {"type": "string"},
+                    "format": {"type": "string", "enum": ["card", "summary", "full"]},
+                    "max_chars": {"type": "integer"},
+                },
+                "required": ["skill_name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_skills",
+            "description": "List catalog skills plus usage weights.",
+            "parameters": {"type": "object", "properties": {"project_root": {"type": "string"}, "user_id": {"type": "string"}}},
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "capabilities",
+            "description": "Package + MCP semver + advertised tools bundle.",
+            "parameters": {"type": "object", "properties": {}},
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_router_status",
+            "description": "Read-only routing env snapshot.",
+            "parameters": {"type": "object", "properties": {}},
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "project_index_status",
+            "description": "Project RAG sqlite stats.",
+            "parameters": {
+                "type": "object",
+                "properties": {"project_root": {"type": "string"}},
+                "required": ["project_root"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "events_recent",
+            "description": "Recent orchestrator SQLite events.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "integer"},
+                    "event_type": {"type": "string"},
+                    "project_root": {"type": "string"},
+                    "user_id": {"type": "string"},
+                },
+            },
+        },
+    },
+]
+
+
+def _tool_payload_text(payload: dict[str, Any], *, limit: int) -> str:
+    parts: list[str] = []
+    for b in payload.get("content") or []:
+        if isinstance(b, dict) and b.get("type") == "text":
+            parts.append(str(b.get("text") or ""))
+    txt = "\n".join(parts).strip()
+    if payload.get("isError"):
+        txt = "(tool_error)\n" + txt
+    if len(txt) > limit:
+        return txt[: limit - 80] + "\n… [truncated for context budget]"
+    return txt
+
+
+def _assistant_message_dict(msg: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {"role": "assistant"}
+    if msg.content:
+        out["content"] = msg.content
+    if getattr(msg, "tool_calls", None):
+        tc_list = []
+        for tc in msg.tool_calls:
+            fn = getattr(tc, "function", None)
+            if fn:
+                tc_list.append({
+                    "id": getattr(tc, "id", ""),
+                    "type": "function",
+                    "function": {
+                        "name": getattr(fn, "name", "") or "",
+                        "arguments": getattr(fn, "arguments", "") or "",
+                    },
+                })
+        out["tool_calls"] = tc_list
+    return out
+
+
+def _inject_project_root(args_dict: dict[str, Any], pr: str) -> dict[str, Any]:
+    merged = dict(args_dict)
+    existing = merged.get("project_root")
+    if isinstance(existing, str):
+        stripped = existing.strip()
+        merged["project_root"] = (stripped or pr) if pr else stripped
+        return merged
+    if pr:
+        merged["project_root"] = pr
+    return merged
+
+async def run_agent_round(
+    *,
+    server: MCPServer,
+    client: Any,
+    model: str,
+    messages: list[dict[str, Any]],
+    default_project_root: str,
+    inner_cap: int,
+    max_rounds: int = 14,
+) -> tuple[str | None, list[dict[str, Any]]]:
+    reply: str | None = None
+    for _ in range(max_rounds):
+        resp = await client.chat.completions.create(
+            model=model,
+            messages=messages,
+            tools=TOOLS,
+            tool_choice="auto",
+            temperature=0.2,
+        )
+        msg = resp.choices[0].message
+        messages.append(_assistant_message_dict(msg))
+
+        tc_list = getattr(msg, "tool_calls", None)
+        if not tc_list:
+            reply = msg.content if msg.content else None
+            return reply, messages
+
+        for tc in tc_list:
+            fn = getattr(tc, "function", None)
+            name = (getattr(fn, "name", None) or "").strip()
+            raw_args = getattr(fn, "arguments", None) if fn else "{}"
+            try:
+                parsed = json.loads(raw_args or "{}")
+            except json.JSONDecodeError:
+                parsed = {}
+            merged = _inject_project_root(parsed, default_project_root)
+            payload = await server.handle_tools_call({"name": name, "arguments": merged})
+            text = _tool_payload_text(payload, limit=inner_cap)
+            messages.append({
+                "role": "tool",
+                "tool_call_id": getattr(tc, "id", "") or "",
+                "content": text,
+            })
+    reply = "(max_tool_rounds_reached)"
+    return reply, messages
+
+
+async def async_main() -> int:
+    p = argparse.ArgumentParser(description="Skillforge standalone agent · OpenAI-compatible tools surface.")
+    p.add_argument("--model", metavar="MODEL", default=os.getenv("SKILLFORGE_AGENT_MODEL", "").strip() or "")
+    p.add_argument("--base-url", metavar="URL", default=os.getenv("OPENAI_API_BASE", "").strip() or "")
+    p.add_argument(
+        "--api-key",
+        metavar="KEY",
+        default=os.getenv("SKILLFORGE_AGENT_API_KEY") or os.getenv("OPENAI_API_KEY", ""),
+    )
+    p.add_argument("--project-root", metavar="PATH", default=os.getenv("SKILLFORGE_PROJECT_ROOT", "").strip() or "")
+    p.add_argument("--prompt", metavar="TEXT", default="", help="One-shot user message then exit.")
+    ns = p.parse_args()
+
+    try:
+        from openai import AsyncOpenAI
+    except ImportError:
+        sys.stderr.write(
+            "Missing `openai` package — run `skillforge install` to refresh ~/.skillforge/venv deps, "
+            "or pip install `openai` into that venv.\n",
+        )
+        return 2
+
+    base = ns.base_url or os.getenv("SKILLFORGE_AGENT_API_BASE") or os.getenv("OPENAI_API_BASE", "").strip() or "http://localhost:11434/v1"
+    api_key = (ns.api_key or "").strip() or "ollama"
+    model = (ns.model or "").strip() or os.getenv("SKILLFORGE_AGENT_MODEL", "").strip() or os.getenv(
+        "SKILLFORGE_OPENAI_ROUTER_MODEL", "").strip() or "llama3.2"
+
+    inner_cap = max(2048, int(os.getenv("SKILLFORGE_AGENT_TOOL_CHAR_CAP", "12000")))
+    proj = ns.project_root.strip()
+
+    sys.stderr.write("[skillforge-agent] Starting MCP-backed tool runtime...\n")
+    sys.stderr.flush()
+    server = MCPServer()
+    await server.setup()
+
+    system = (
+        "You are the Skillforge terminal agent.\n"
+        "Use MCP tools (`route_skills`, `search_skills`, …) instead of hallucinating SKILL content.\n"
+        "Prefer `route_skills` after `search_skills` when narrowing which skills matter.\n"
+        "Honor host-mode Skillforge: repeat `route_skills` with `picked_names` when the UI lists a shortlist.\n"
+        "Keep answers actionable and cite retrieved skill excerpts only after calling tools.\n"
+    )
+    messages: list[dict[str, Any]] = [{"role": "system", "content": system}]
+
+    client = AsyncOpenAI(api_key=api_key, base_url=base.rstrip("/"))
+
+    if ns.prompt.strip():
+        user_line = ns.prompt.strip()
+        messages.append({"role": "user", "content": user_line})
+        reply, messages = await run_agent_round(
+            server=server,
+            client=client,
+            model=model,
+            messages=messages,
+            default_project_root=proj,
+            inner_cap=inner_cap,
+        )
+        if reply:
+            sys.stdout.write(reply.strip() + "\n")
+            sys.stdout.flush()
+        return 0
+
+    if not sys.stdin.isatty():  # pragma: no cover
+        sys.stderr.write("Interactive mode requires a TTY (pipe --prompt=… instead).\n")
+        return 2
+
+    while True:
+        try:
+            line = input("\nYou> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if not line:
+            continue
+        if line.lower() in ("quit", "/quit", ":q", "/exit"):
+            return 0
+        messages.append({"role": "user", "content": line})
+        reply, messages = await run_agent_round(
+            server=server,
+            client=client,
+            model=model,
+            messages=messages,
+            default_project_root=proj,
+            inner_cap=inner_cap,
+        )
+        if reply:
+            print("\nAssistant>\n", reply.strip(), sep="")
+        else:
+            print("\nAssistant> (empty)")
+        if len(messages) > 140:
+            trim = [{"role": "system", "content": system}]
+            trim.extend(messages[-120:])
+            messages = trim
+
+
+def main() -> None:
+    raise SystemExit(asyncio.run(async_main()))
+
+
+if __name__ == "__main__":
+    main()

package/python/app/explain_route.py

@@ -0,0 +1,170 @@
+"""Shared ``explain_route`` logic (MCP ``explain_route`` + ``skillforge route --explain``)."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from app.main import MAX_ACTIVE_SKILLS, Router
+from app.mcp_contract import MCP_RESPONSE_SCHEMA_VERSION
+from app.pick_diversify import diversify_picked_names
+from app.redaction import redaction_enabled, redact_display_path
+from app.route_policies import (
+    build_routing_overlay_payload,
+    load_route_policies_config,
+    merge_policy_includes,
+    merge_project_notes_into_route_query,
+    parse_routing_overlay,
+)
+from app.routing_signals import build_route_query_text
+
+
+def sanitize_explain_payload(explain: dict[str, Any]) -> dict[str, Any]:
+    """Make explain meta JSON-safe (numpy scalars → Python floats)."""
+
+    import numpy as np
+
+    def _walk(o: Any) -> Any:
+        if isinstance(o, dict):
+            return {str(k): _walk(v) for k, v in o.items()}
+        if isinstance(o, list):
+            return [_walk(x) for x in o]
+        if isinstance(o, (str, bool, type(None))):
+            return o
+        if isinstance(o, (int,)):
+            return o
+        if isinstance(o, (float,)):
+            return o
+        if isinstance(o, np.floating):
+            return float(o)
+        if isinstance(o, np.integer):
+            return int(o)
+        if isinstance(o, np.ndarray):
+            return o.tolist()
+        try:
+            return float(o)
+        except (TypeError, ValueError):
+            return str(o)
+
+    return _walk(explain)
+
+
+async def compute_explain_route(
+    router: Router,
+    con: sqlite3.Connection,
+    *,
+    prompt: str,
+    conversation: list[Any],
+    limit: int,
+    user_id: str,
+    project_root: str | None,
+    db_path: Path,
+) -> tuple[str, dict[str, Any]]:
+    """Return Markdown body + ``_meta`` shape matching MCP ``explain_route`` (does not touch sessions/events)."""
+    policies_cfg = load_route_policies_config(project_root)
+    overlay_audit: list[Any] = []
+    exclude_skills, routing_boosts, project_notes = parse_routing_overlay(
+        policies_cfg,
+        by_name=router._by_name,
+        audit_out=overlay_audit,
+    )
+    route_query = merge_project_notes_into_route_query(
+        build_route_query_text(prompt, conversation),
+        project_notes,
+        project_root,
+    )
+    facets = router.shortlist_with_facets(
+        route_query,
+        con,
+        k=limit,
+        user_id=user_id,
+        exclude_skills=exclude_skills,
+        routing_boosts=routing_boosts,
+    )
+    candidates = router.shortlist(
+        route_query,
+        con,
+        limit,
+        user_id,
+        exclude_skills=exclude_skills,
+        routing_boosts=routing_boosts,
+    )
+    candidates = await router.rerank_candidates_haiku(route_query, conversation, candidates)
+    picked_router, reasoning = await router.pick_final(
+        prompt,
+        conversation,
+        candidates,
+        route_query=route_query,
+    )
+    picked_before_pol, div_meta = diversify_picked_names(list(picked_router), router._by_name)
+    merged, policy_audit = merge_policy_includes(
+        prompt,
+        picked_before_pol,
+        policies_cfg,
+        router._by_name,
+        con,
+        user_id,
+        max_active=MAX_ACTIVE_SKILLS,
+    )
+    router_mode = "full" if router.router_llm else "embedding-only"
+    notes_effective = bool(project_notes.strip() and (project_root or "").strip())
+    routing_ov = build_routing_overlay_payload(
+        project_root=project_root or "",
+        exclude_skills=exclude_skills,
+        routing_boosts=routing_boosts,
+        project_notes_applied=notes_effective,
+        project_notes_len=len(project_notes) if project_notes else 0,
+        audit=overlay_audit,
+    )
+    explain_raw: dict[str, Any] = {
+        "schema_version": MCP_RESPONSE_SCHEMA_VERSION,
+        "tool": "explain_route",
+        "orchestrator_db": redact_display_path(db_path) if redaction_enabled() else str(db_path),
+        "router_mode": router_mode,
+        "embedding_shortlist": facets,
+        "picked_router": picked_router,
+        "picked_before_policy": picked_before_pol,
+        "picked_after_policy": merged,
+        "pick_diversify": div_meta,
+        "router_reasoning": reasoning,
+        "policy": {
+            "rules_loaded": len(policies_cfg.get("rules") or [])
+            if isinstance(policies_cfg.get("rules"), list)
+            else 0,
+            "audit": policy_audit,
+        },
+    }
+    if routing_ov is not None:
+        explain_raw["routing_overlay"] = routing_ov
+
+    explain = sanitize_explain_payload(explain_raw)
+
+    lines = [
+        "# explain_route — routing diagnostics (no session writes)",
+        "",
+        f"**Router:** {router_mode}",
+        f"**Picked (router):** {', '.join(picked_router) if picked_router else '_(none)_'}",
+    ]
+    if div_meta.get("applied"):
+        lines.append(
+            f"**After pick_diversify:** {', '.join(picked_before_pol) if picked_before_pol else '_(none)_'}"
+        )
+    lines.extend(
+        [
+            f"**After policies:** {', '.join(merged) if merged else '_(none)_'}",
+            f"**Reasoning:** {reasoning}" if reasoning else "**Reasoning:** _(n/a)_",
+            "",
+            "## Shortlist (embedding)",
+        ]
+    )
+    for f in facets[:15]:
+        lines.append(
+            f"- `{f['name']}` cos={f['cosine_similarity']} weight={f['learned_weight']} "
+            f"score={f['routing_score']}"
+        )
+    if policy_audit:
+        lines.extend(["", "## Policy audit"])
+        for row in policy_audit[:30]:
+            lines.append(f"- {row}")
+    body = "\n".join(lines)
+    return body, explain

package/python/app/health_cli.py

@@ -79,6 +79,14 @@ def run_health(*, quick: bool, project_root: str, json_out: bool) -> int:
         "error": u_err,
     })
 
+    env_profile = Path.home() / ".skillforge" / "env"
+    checks.append({
+        "name": "user_env_profile",
+        "ok": True,
+        "path": str(env_profile),
+        "present": env_profile.is_file(),
+    })
+
     pr = (project_root or "").strip() or None
     db_path = resolve_orchestrator_db(pr)
     db_ok = True
@@ -142,6 +150,11 @@ def run_health(*, quick: bool, project_root: str, json_out: bool) -> int:
                 print(f"    SKILL.md count: {c['skill_md_count']}", file=sys.stderr)
             if c.get("skill_count") is not None:
                 print(f"    router skills: {c['skill_count']}", file=sys.stderr)
+            if c.get("present") is not None:
+                if c["present"]:
+                    print(f"    present: yes", file=sys.stderr)
+                else:
+                    print(f"    present: no · optional (`skillforge config init`)", file=sys.stderr)
             if c.get("error"):
                 print(f"    error: {c['error']}", file=sys.stderr)
         print("health: ok" if not failed else "health: failed", file=sys.stderr)