agent-devkit 0.2.0 → 0.3.1

package/runtime/cli/aikit/local_llm.py

@@ -0,0 +1,176 @@
+"""Canonical local-LLM CLI surface over Ollama and mini-brain policy."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+
+from cli.aikit.embedded_mini_brain import EMBEDDED_BACKEND_ID, EMBEDDED_MODEL_ID, embedded_mini_brain_status
+from cli.aikit.mini_brain import DEFAULT_OLLAMA_MODEL, mini_brain_contract
+from cli.aikit.model_router import build_model_plan
+from cli.aikit.ollama import ollama_models, ollama_pull, ollama_status
+
+
+LOCAL_LLM_SCHEMA_VERSION = "agent-devkit.local-llm/v1"
+LOCAL_WORKERS = (
+    ("local-classifier", "intent classification and routing hints"),
+    ("local-summarizer", "short summaries and extraction"),
+    ("local-coder", "mechanical code drafts with coordinator review"),
+    ("local-log-analyzer", "log clustering and evidence extraction"),
+    ("local-sql-helper", "SQL draft assistance with review required"),
+)
+
+
+def local_llm_list() -> dict[str, Any]:
+    status = ollama_status()
+    contract = mini_brain_contract(ollama_payload=status)
+    return {
+        "kind": "local-llm",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ok",
+        "provider": EMBEDDED_BACKEND_ID,
+        "optional_providers": ["ollama"],
+        "embedded": embedded_mini_brain_status(),
+        "mini_brain": contract,
+        "workers": [{"id": worker_id, "purpose": purpose} for worker_id, purpose in LOCAL_WORKERS],
+        "models": {
+            "status": status.get("status"),
+            "count": status.get("model_count", 0),
+        },
+    }
+
+
+def local_llm_doctor() -> dict[str, Any]:
+    status = ollama_status()
+    contract = mini_brain_contract(ollama_payload=status)
+    model_plan = build_model_plan("resuma estes logs operacionais")
+    ok = contract.get("available") is True
+    return {
+        "kind": "local-llm-doctor",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ok" if ok else "partial",
+        "provider": EMBEDDED_BACKEND_ID,
+        "optional_providers": ["ollama"],
+        "embedded": embedded_mini_brain_status(),
+        "ollama": status,
+        "mini_brain": contract,
+        "model_plan": {
+            "strategy": model_plan.get("strategy"),
+            "local_llm_recommended": model_plan.get("local_llm_recommended"),
+            "local_llm_selected": model_plan.get("local_llm_selected"),
+            "local_llm_role": model_plan.get("local_llm_role"),
+            "forbidden_actions": model_plan.get("forbidden_actions") or [],
+        },
+        "next_steps": local_llm_next_steps(status=status, mini_brain=contract),
+    }
+
+
+def local_llm_models() -> dict[str, Any]:
+    payload = ollama_models()
+    embedded = embedded_mini_brain_status()
+    payload["kind"] = "local-llm-models"
+    payload["schema_version"] = LOCAL_LLM_SCHEMA_VERSION
+    payload["provider"] = EMBEDDED_BACKEND_ID
+    payload["embedded"] = {
+        "status": embedded.get("status"),
+        "provider": EMBEDDED_BACKEND_ID,
+        "model": EMBEDDED_MODEL_ID,
+        "installed": embedded.get("model_file_valid") is True,
+        "available": embedded.get("available") is True,
+        "install_command": embedded.get("install_command"),
+    }
+    payload["optional_provider"] = "ollama"
+    return payload
+
+
+def local_llm_install(model: str | None, *, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    model = model or DEFAULT_OLLAMA_MODEL
+    payload = ollama_pull(model, dry_run=dry_run, yes=yes)
+    payload["kind"] = "local-llm-install"
+    payload["schema_version"] = LOCAL_LLM_SCHEMA_VERSION
+    payload["provider"] = "ollama"
+    return payload
+
+
+def local_llm_remove(model: str | None, *, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    model = model or DEFAULT_OLLAMA_MODEL
+    command = ["ollama", "rm", model]
+    binary = shutil.which("ollama")
+    if dry_run or not yes:
+        needs_confirmation = not dry_run and not yes
+        return {
+            "kind": "local-llm-remove",
+            "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "exit_code": 2 if needs_confirmation else 0,
+            "provider": "ollama",
+            "model": model,
+            "binary": binary,
+            "command": command,
+            "dry_run": dry_run,
+            "yes": yes,
+            "message": "Use --yes to remove the local model." if not dry_run and not yes else "Dry-run only.",
+        }
+    if not binary:
+        return {
+            "kind": "local-llm-remove",
+            "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+            "status": "missing",
+            "ok": False,
+            "provider": "ollama",
+            "model": model,
+            "command": command,
+            "message": "Ollama binary not found in PATH.",
+            "exit_code": 2,
+        }
+    process = subprocess.run(command, check=False, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=120)
+    return {
+        "kind": "local-llm-remove",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "provider": "ollama",
+        "model": model,
+        "binary": binary,
+        "command": command,
+        "exit_code": process.returncode,
+        "stdout": process.stdout[-4000:],
+        "stderr": process.stderr[-4000:],
+    }
+
+
+def local_llm_benchmark(model: str | None = None) -> dict[str, Any]:
+    model = model or DEFAULT_OLLAMA_MODEL
+    status = ollama_status()
+    installed = {item.get("name") for item in status.get("models") or [] if isinstance(item, dict)}
+    available = status.get("status") == "ok" and model in installed
+    return {
+        "kind": "local-llm-benchmark",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ready" if available else "planned",
+        "ok": available,
+        "provider": "ollama",
+        "model": model,
+        "checks": [
+            {"id": "ollama-binary", "status": "passed" if status.get("status") == "ok" else "failed"},
+            {"id": "model-installed", "status": "passed" if model in installed else "planned"},
+            {"id": "policy", "status": "passed", "message": "Benchmark is read-only and does not approve final work."},
+        ],
+        "next_steps": [] if available else [f"agent local-llm install {model} --yes"],
+    }
+
+
+def local_llm_next_steps(*, status: dict[str, Any], mini_brain: dict[str, Any]) -> list[str]:
+    steps: list[str] = []
+    if status.get("status") != "ok":
+        install_plan = status.get("install_plan") if isinstance(status.get("install_plan"), dict) else {}
+        command = install_plan.get("command")
+        if command:
+            steps.append(f"Install Ollama: {command}")
+    if not mini_brain.get("enabled"):
+        steps.append("agent setup mini-brain --yes")
+    if status.get("model_count", 0) < 1:
+        steps.append(f"agent local-llm install {DEFAULT_OLLAMA_MODEL} --yes")
+    return steps

package/runtime/cli/aikit/local_llm_operator.py

@@ -24,7 +24,7 @@ FORBIDDEN_DELEGATION_MARKERS = (
 
 
 def maybe_delegate_local_llm(prompt: str, model_plan: dict[str, Any]) -> dict[str, Any]:
-    """Execute a bounded operational task with Ollama when the model plan selected it."""
+    """Execute a bounded operational task with the selected local worker."""
     delegation = model_plan.get("delegation") if isinstance(model_plan.get("delegation"), dict) else {}
     if model_plan.get("strategy") != "mini-brain":
         return skipped(
@@ -38,6 +38,12 @@ def maybe_delegate_local_llm(prompt: str, model_plan: dict[str, Any]) -> dict[st
             "High-risk tasks cannot be delegated to local LLM workers.",
             model_plan=model_plan,
         )
+    if model_plan.get("local_llm_role") != "operational-worker":
+        return skipped(
+            "not-operational-worker",
+            "The embedded mini-brain is acting as the bootstrap coordinator, not as a delegated worker.",
+            model_plan=model_plan,
+        )
     if int(model_plan.get("max_llm_calls") or 0) <= 0:
         return skipped(
             "llm-budget-not-available",
@@ -50,9 +56,10 @@ def maybe_delegate_local_llm(prompt: str, model_plan: dict[str, Any]) -> dict[st
     if any(marker in lowered for marker in FORBIDDEN_DELEGATION_MARKERS):
         return skipped("forbidden", "Prompt contains an action that local LLM workers cannot execute.", model_plan=model_plan)
     delegated_prompt = build_delegated_prompt(prompt, model_plan)
+    provider = str(model_plan.get("local_llm_provider") or "ollama")
     result = invoke_agent_prompt(
         delegated_prompt,
-        "ollama",
+        provider,
         public_name="Local LLM Operator",
         allow_fallback=False,
     )
@@ -64,7 +71,7 @@ def maybe_delegate_local_llm(prompt: str, model_plan: dict[str, Any]) -> dict[st
         "status": "ok" if result.get("ok") else result.get("status", "failed"),
         "ok": bool(result.get("ok")),
         "llm_backend": result.get("llm_backend"),
-        "model_provider": "ollama",
+        "model_provider": provider,
         "mini_brain": summarize_mini_brain(model_plan.get("mini_brain")),
         "strategy": model_plan.get("strategy"),
         "risk": model_plan.get("risk"),
@@ -108,7 +115,7 @@ def enrich_prompt_with_local_result(prompt: str, local_execution: dict[str, Any]
         [
             prompt,
             "",
-            "Contexto operacional produzido pelo local-llm-operator/Ollama:",
+            f"Contexto operacional produzido pelo local-llm-operator/{local_execution.get('model_provider') or local_execution.get('llm_backend') or 'local'}:",
             str(local_execution["response"]),
             "",
             "Use esse contexto apenas como apoio. A decisao, resposta final e revisao continuam sob responsabilidade do coordenador.",
@@ -131,7 +138,10 @@ def skipped(reason: str, message: str, *, model_plan: dict[str, Any]) -> dict[st
         "strategy": model_plan.get("strategy"),
         "risk": model_plan.get("risk"),
         "confidence": model_plan.get("confidence"),
-        "requires_review": bool(model_plan.get("local_llm_recommended") or model_plan.get("local_llm_selected")),
+        "requires_review": bool(
+            model_plan.get("local_llm_role") == "operational-worker"
+            and (model_plan.get("local_llm_recommended") or model_plan.get("local_llm_selected"))
+        ),
     }
 
 

package/runtime/cli/aikit/main.py

@@ -4,7 +4,9 @@
 from __future__ import annotations
 
 import json
+import os
 import sys
+import traceback
 
 from cli.aikit.cli_dispatch import dispatch, format_audit_warning, is_audit_warning, maybe_record_cli_audit
 from cli.aikit.cli_parser import DETERMINISTIC_COMMANDS, LLM_COMMANDS, build_parser
@@ -26,6 +28,19 @@ def main(argv: list[str] | None = None, *, prog: str | None = None) -> int:
             print(format_audit_warning(audit_result), file=sys.stderr)
         print(f"error: {exc}", file=sys.stderr)
         return 1
+    except Exception as exc:  # noqa: BLE001 - CLI boundary must not leak tracebacks by default.
+        if os.environ.get("AI_DEVKIT_DEBUG") == "1":
+            traceback.print_exc(file=sys.stderr)
+        else:
+            print(
+                f"error: internal error: {type(exc).__name__}. "
+                "Run with AI_DEVKIT_DEBUG=1 for traceback.",
+                file=sys.stderr,
+            )
+        audit_result = maybe_record_cli_audit(args, result=None, error=f"{type(exc).__name__}: {exc}")
+        if is_audit_warning(audit_result):
+            print(format_audit_warning(audit_result), file=sys.stderr)
+        return 1
 
     if result is None:
         return 0