agent-devkit 0.1.6 → 0.2.0

package/runtime/cli/aikit/mini_brain.py

@@ -0,0 +1,227 @@
+"""Mini-brain local model contract and setup helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from cli.aikit.llm import BACKENDS, configure_backend, doctor_backend, load_config, save_config
+from cli.aikit.ollama import ollama_pull, ollama_status
+
+
+MINI_BRAIN_CONFIG_KEY = "mini_brain"
+DEFAULT_HF_MODEL = "Qwen/Qwen3-0.6B"
+DEFAULT_OLLAMA_MODEL = "qwen3:0.6b"
+DEFAULT_PROVIDER = "ollama"
+DEFAULT_BASE_URL = "http://localhost:11434/v1"
+ALLOWED_TASKS = [
+    "setup_help",
+    "wizard_conversation",
+    "intent_classification",
+    "command_explanation",
+    "short_error_summary",
+]
+FORBIDDEN_TASKS = [
+    "external_write_decision",
+    "destructive_operation_approval",
+    "security_review_final",
+    "architecture_decision",
+    "secret_handling",
+    "final_delivery_decision",
+]
+DEFAULT_LIMITS = {
+    "max_context_chars": 6000,
+    "max_response_chars": 2000,
+    "max_llm_calls": 1,
+}
+DEFAULT_GUARDRAILS = [
+    "no_secrets",
+    "low_risk_only",
+    "no_external_writes",
+    "coordinator_review_required",
+]
+
+
+def mini_brain_contract(
+    *,
+    config: dict[str, Any] | None = None,
+    ollama_payload: dict[str, Any] | None = None,
+    ollama_backend: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    config = load_config() if config is None else config
+    stored = config.get(MINI_BRAIN_CONFIG_KEY) if isinstance(config.get(MINI_BRAIN_CONFIG_KEY), dict) else {}
+    enabled = bool(stored.get("enabled"))
+    provider = stored.get("provider") or stored.get("runtime") or DEFAULT_PROVIDER
+    hf_model = stored.get("hf_model") or stored.get("model") or DEFAULT_HF_MODEL
+    ollama_model = stored.get("ollama_model") or DEFAULT_OLLAMA_MODEL
+    ollama_payload = ollama_status() if ollama_payload is None else ollama_payload
+    ollama_backend = doctor_backend(BACKENDS["ollama"], config) if ollama_backend is None else ollama_backend
+    backend_configured = ollama_backend.get("status") == "ok"
+    runtime_available = ollama_payload.get("status") == "ok" or backend_configured
+    available = enabled and provider == DEFAULT_PROVIDER and runtime_available
+    status = "ok" if available else "disabled" if not enabled else "unavailable"
+    return {
+        "kind": "mini-brain",
+        "status": status,
+        "enabled": enabled,
+        "available": available,
+        "configured": enabled and provider == DEFAULT_PROVIDER and backend_configured,
+        "provider": provider,
+        "runtime": provider,
+        "hf_model": hf_model,
+        "model": hf_model,
+        "ollama_model": ollama_model,
+        "allowed_tasks": list_value(stored.get("allowed_tasks"), ALLOWED_TASKS),
+        "forbidden_tasks": list_value(stored.get("forbidden_tasks"), FORBIDDEN_TASKS),
+        "limits": dict_value(stored.get("limits"), DEFAULT_LIMITS),
+        "guardrails": list_value(stored.get("guardrails"), DEFAULT_GUARDRAILS),
+        "stored_secret": False,
+        "ollama": {
+            "status": ollama_payload.get("status"),
+            "daemon": (ollama_payload.get("daemon") or {}).get("status")
+            if isinstance(ollama_payload.get("daemon"), dict)
+            else None,
+            "model_count": ollama_payload.get("model_count"),
+        },
+        "backend": {
+            "status": ollama_backend.get("status"),
+            "model": ollama_backend.get("model"),
+            "base_url": ollama_backend.get("base_url"),
+        },
+    }
+
+
+def setup_mini_brain(
+    *,
+    dry_run: bool = False,
+    yes: bool = False,
+    set_default: bool = False,
+    model: str = DEFAULT_OLLAMA_MODEL,
+) -> dict[str, Any]:
+    if dry_run or not yes:
+        status = "planned" if dry_run else "needs-confirmation"
+        return {
+            "kind": "mini-brain-setup",
+            "status": status,
+            "ok": bool(dry_run),
+            "dry_run": dry_run,
+            "yes": yes,
+            "stored_secret": False,
+            "mini_brain": planned_contract(model=model),
+            "pull": ollama_pull(model, yes=False, dry_run=dry_run),
+            "next_steps": ["agent setup mini-brain --yes"],
+            "message": "Use --yes to pull Qwen3-0.6B with Ollama and enable the mini-brain.",
+        }
+
+    pull = ollama_pull(model, yes=True, dry_run=False)
+    if not pull.get("ok"):
+        return {
+            "kind": "mini-brain-setup",
+            "status": "failed",
+            "ok": False,
+            "dry_run": False,
+            "yes": True,
+            "stored_secret": False,
+            "mini_brain": planned_contract(model=model),
+            "pull": pull,
+            "next_steps": ["Install Ollama or run agent ollama pull qwen3:0.6b --yes"],
+            "message": pull.get("message") or "Could not pull the mini-brain model.",
+        }
+
+    existing_config = load_config()
+    existing_ollama = (
+        existing_config.get("llm", {}).get("backends", {}).get(DEFAULT_PROVIDER)
+        if isinstance(existing_config.get("llm"), dict)
+        else {}
+    )
+    existing_base_url = existing_ollama.get("base_url") if isinstance(existing_ollama, dict) else None
+    configured = configure_backend(
+        DEFAULT_PROVIDER,
+        base_url=existing_base_url or DEFAULT_BASE_URL,
+        model=model,
+        set_default=set_default,
+    )
+    config = load_config()
+    config[MINI_BRAIN_CONFIG_KEY] = stored_config(model=model)
+    written_path = save_config(config)
+    contract = mini_brain_contract(config=config)
+    return {
+        "kind": "mini-brain-setup",
+        "status": "configured",
+        "ok": True,
+        "dry_run": False,
+        "yes": True,
+        "stored_secret": False,
+        "config_path": str(written_path),
+        "mini_brain": contract,
+        "pull": pull,
+        "llm_configure": configured,
+        "next_steps": ["Use low-risk setup, wizard and summary prompts normally."],
+    }
+
+
+def planned_contract(*, model: str = DEFAULT_OLLAMA_MODEL) -> dict[str, Any]:
+    return {
+        "kind": "mini-brain",
+        "status": "planned",
+        "enabled": False,
+        "available": False,
+        "configured": False,
+        "provider": DEFAULT_PROVIDER,
+        "runtime": DEFAULT_PROVIDER,
+        "hf_model": DEFAULT_HF_MODEL,
+        "model": DEFAULT_HF_MODEL,
+        "ollama_model": model,
+        "allowed_tasks": list(ALLOWED_TASKS),
+        "forbidden_tasks": list(FORBIDDEN_TASKS),
+        "limits": dict(DEFAULT_LIMITS),
+        "guardrails": list(DEFAULT_GUARDRAILS),
+        "stored_secret": False,
+    }
+
+
+def stored_config(*, model: str = DEFAULT_OLLAMA_MODEL) -> dict[str, Any]:
+    return {
+        "enabled": True,
+        "provider": DEFAULT_PROVIDER,
+        "runtime": DEFAULT_PROVIDER,
+        "hf_model": DEFAULT_HF_MODEL,
+        "model": DEFAULT_HF_MODEL,
+        "ollama_model": model,
+        "allowed_tasks": list(ALLOWED_TASKS),
+        "forbidden_tasks": list(FORBIDDEN_TASKS),
+        "limits": dict(DEFAULT_LIMITS),
+        "guardrails": list(DEFAULT_GUARDRAILS),
+        "stored_secret": False,
+        "updated_at": now_iso(),
+    }
+
+
+def summarize_mini_brain(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "status": value.get("status"),
+        "enabled": value.get("enabled") is True,
+        "available": value.get("available") is True,
+        "provider": value.get("provider"),
+        "hf_model": value.get("hf_model") or value.get("model"),
+        "ollama_model": value.get("ollama_model"),
+        "stored_secret": value.get("stored_secret") is True,
+    }
+
+
+def list_value(value: Any, default: list[str]) -> list[str]:
+    if not isinstance(value, list):
+        return list(default)
+    return [str(item) for item in value if str(item).strip()]
+
+
+def dict_value(value: Any, default: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return dict(default)
+    return dict(value)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()

package/runtime/cli/aikit/model_router.py

@@ -6,7 +6,9 @@ import re
 from typing import Any
 
 from cli.aikit.llm import BACKENDS, doctor_backend, llm_preference, load_config
+from cli.aikit.mini_brain import mini_brain_contract
 from cli.aikit.ollama import ollama_status
+from cli.aikit.write_policy import normalize_write_policy, write_policy_public_fields
 
 
 OPERATIONAL_PATTERN = re.compile(
@@ -15,51 +17,211 @@ OPERATIONAL_PATTERN = re.compile(
 HIGH_LEVEL_PATTERN = re.compile(
     r"(?i)\b(arquitet|decid|aprovar|reprovar|especifica|requisit|implemente|codigo|c[oó]digo|documento|automac|deploy|seguran)\b"
 )
+HUMAN_PATTERN = re.compile(
+    r"(?i)\b(confirme|autorize|aprovar|aprovação|permiss[aã]o|delete|excluir|destrutiv)\b"
+)
+SENSITIVE_SECRET_ACTION_PATTERN = re.compile(
+    r"(?i)(\b(mostre|exiba|revele|configure|alter[ea]|salve|envie|publique|registre|grave)\b.*\b(credencial|senha|token|segredo)\b|\b(credencial|senha|token|segredo)\b.*\b(mostre|exiba|revele|configure|alter[ea]|salve|envie|publique|registre|grave)\b)"
+)
+
+FORBIDDEN_ACTIONS = [
+    "final-review",
+    "external-write",
+    "permission-decision",
+    "architecture-decision",
+    "pr-approval",
+]
 
 
-def build_model_plan(prompt: str, *, route: dict[str, Any] | None = None) -> dict[str, Any]:
+def build_model_plan(
+    prompt: str,
+    *,
+    route: dict[str, Any] | None = None,
+    routing_decision: dict[str, Any] | None = None,
+    specialist_tasks: list[dict[str, Any]] | None = None,
+    configuration_tasks: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
     config = load_config()
     preference = llm_preference(config)
     ollama = ollama_status()
     ollama_backend = doctor_backend(BACKENDS["ollama"], config)
-    local_available = ollama.get("status") == "ok" or ollama_backend.get("status") == "ok"
+    mini_brain = mini_brain_contract(config=config, ollama_payload=ollama, ollama_backend=ollama_backend)
+    local_available = mini_brain.get("available") is True
     operational = bool(OPERATIONAL_PATTERN.search(prompt))
     high_level = bool(HIGH_LEVEL_PATTERN.search(prompt))
-    use_local = operational and local_available
+    policy = choose_model_strategy(
+        prompt,
+        route=route,
+        routing_decision=routing_decision,
+        specialist_tasks=specialist_tasks or [],
+        configuration_tasks=configuration_tasks or [],
+        operational=operational,
+        high_level=high_level,
+        local_available=local_available,
+    )
+    use_local = policy["strategy"] == "mini-brain" and local_available
     return {
         "kind": "model-plan",
         "status": "planned",
+        "strategy": policy["strategy"],
+        "reason": policy["reason"],
+        "risk": policy["risk"],
+        "confidence": policy["confidence"],
+        "fallback": policy["fallback"],
+        "forbidden_actions": list(policy["forbidden_actions"]),
+        "decision_matrix": policy["decision_matrix"],
+        "max_llm_calls": policy["max_llm_calls"],
         "intent": route.get("intent") if route else "llm",
         "primary_coordinators": coordinator_order(preference),
         "local_llm_role": "operational-worker",
         "local_llm_available": local_available,
-        "local_llm_provider": "ollama",
+        "local_llm_provider": mini_brain.get("provider") or "ollama",
         "local_llm_backend_configured": ollama_backend.get("status") == "ok",
         "local_llm_runtime": {
             "binary_status": ollama.get("status"),
             "backend_status": ollama_backend.get("status"),
-            "model": ollama_backend.get("model"),
+            "model": mini_brain.get("ollama_model") or ollama_backend.get("model"),
             "base_url": ollama_backend.get("base_url"),
         },
+        "mini_brain": mini_brain,
         "local_llm_recommended": operational,
         "local_llm_selected": use_local,
         "delegation": {
-            "allowed": operational,
+            "allowed": policy["strategy"] == "mini-brain",
             "selected": use_local,
-            "reason": local_reason(operational=operational, local_available=local_available, high_level=high_level),
-            "forbidden_actions": [
-                "final-review",
-                "external-write",
-                "permission-decision",
-                "architecture-decision",
-                "pr-approval",
-            ],
+            "reason": local_reason(
+                operational=operational,
+                local_available=local_available,
+                high_level=high_level,
+                strategy=policy["strategy"],
+            ),
+            "forbidden_actions": list(policy["forbidden_actions"]),
         },
         "fallback_order": preference.get("order") or [],
         "route": route,
     }
 
 
+def choose_model_strategy(
+    prompt: str,
+    *,
+    route: dict[str, Any] | None,
+    routing_decision: dict[str, Any] | None,
+    specialist_tasks: list[dict[str, Any]],
+    configuration_tasks: list[dict[str, Any]],
+    operational: bool,
+    high_level: bool,
+    local_available: bool,
+) -> dict[str, Any]:
+    routing_status = (routing_decision or {}).get("status")
+    if routing_status in {"ambiguous", "low-confidence"}:
+        return policy(
+            "human",
+            "Routing is ambiguous or low confidence, so a human must choose the agent/capability.",
+            risk="medium",
+            confidence="low",
+            fallback="ask-user-to-confirm-route",
+            max_llm_calls=0,
+            matrix="Ambigua + risco/side effect -> humano",
+        )
+    if configuration_tasks:
+        return policy(
+            "human",
+            "A provider/source configuration task is required before execution.",
+            risk="medium",
+            confidence="high",
+            fallback="provider-setup-wizard",
+            max_llm_calls=0,
+            matrix="Credencial/config faltante -> humano",
+        )
+    if prompt_requires_human(prompt) or any(task_requires_confirmation(task) for task in specialist_tasks):
+        return policy(
+            "human",
+            "The prompt or selected task requires human confirmation by policy.",
+            risk="high",
+            confidence="high",
+            fallback="ask-human-confirmation",
+            max_llm_calls=0,
+            matrix="Ambigua + risco/side effect -> humano",
+        )
+    if route or has_executable_known_task(specialist_tasks):
+        return policy(
+            "automation",
+            "The task maps to a known deterministic capability with controlled policy.",
+            risk="low",
+            confidence="high",
+            fallback="manual-steps-if-provider-missing",
+            max_llm_calls=0,
+            matrix="Conhecida + estruturada + baixo risco -> automacao",
+        )
+    if operational and not high_level:
+        return policy(
+            "mini-brain" if local_available else "external-llm",
+            "The prompt is operational and low-risk; local mini-brain is preferred when available.",
+            risk="low",
+            confidence="medium" if local_available else "low",
+            fallback="external-llm" if local_available else "configure-local-mini-brain-or-use-external-llm",
+            max_llm_calls=1,
+            matrix="Simples + conversa/setup -> mini cerebro local",
+        )
+    return policy(
+        "external-llm",
+        "The task requires coordinator-level reasoning, synthesis, or open-ended judgment.",
+        risk="medium" if not high_level else "high",
+        confidence="medium",
+        fallback="ask-human-if-review-or-backend-unavailable",
+        max_llm_calls=1,
+        matrix="Aberta + complexa + alto julgamento -> LLM externa",
+    )
+
+
+def policy(
+    strategy: str,
+    reason: str,
+    *,
+    risk: str,
+    confidence: str,
+    fallback: str,
+    max_llm_calls: int,
+    matrix: str,
+) -> dict[str, Any]:
+    return {
+        "strategy": strategy,
+        "reason": reason,
+        "risk": risk,
+        "confidence": confidence,
+        "fallback": fallback,
+        "forbidden_actions": FORBIDDEN_ACTIONS,
+        "max_llm_calls": max_llm_calls,
+        "decision_matrix": {
+            "selected_rule": matrix,
+            "priority": ["deterministic-rule", "local-automation", "mini-brain", "external-llm", "human"],
+        },
+    }
+
+
+def has_executable_known_task(tasks: list[dict[str, Any]]) -> bool:
+    return any(task.get("executable") and is_autonomous_safe_task(task) for task in tasks)
+
+
+def is_autonomous_safe_task(task: dict[str, Any]) -> bool:
+    metadata = task.get("write_policy_metadata") if isinstance(task.get("write_policy_metadata"), dict) else {}
+    if metadata:
+        return bool(metadata.get("autonomous_safe"))
+    return bool(write_policy_public_fields(task.get("write_policy"))["write_policy_metadata"].get("autonomous_safe"))
+
+
+def task_requires_confirmation(task: dict[str, Any]) -> bool:
+    metadata = task.get("write_policy_metadata") if isinstance(task.get("write_policy_metadata"), dict) else {}
+    if not metadata:
+        metadata = write_policy_public_fields(normalize_write_policy(task.get("write_policy")))["write_policy_metadata"]
+    return bool(metadata.get("requires_confirmation") or metadata.get("blocked_by_default"))
+
+
+def prompt_requires_human(prompt: str) -> bool:
+    return bool(HUMAN_PATTERN.search(prompt) or SENSITIVE_SECRET_ACTION_PATTERN.search(prompt))
+
+
 def coordinator_order(preference: dict[str, Any]) -> list[str]:
     order = list(preference.get("order") or [])
     preferred = [item for item in order if item in {"claude-code", "codex-cli"}]
@@ -69,11 +231,13 @@ def coordinator_order(preference: dict[str, Any]) -> list[str]:
     return preferred
 
 
-def local_reason(*, operational: bool, local_available: bool, high_level: bool) -> str:
+def local_reason(*, operational: bool, local_available: bool, high_level: bool, strategy: str) -> str:
+    if strategy != "mini-brain":
+        return "Local LLM delegation is not selected by the model strategy."
     if operational and local_available and high_level:
-        return "Use Ollama for operational preprocessing; coordinator review remains mandatory."
+        return "Use the local mini-brain for operational preprocessing; coordinator review remains mandatory."
     if operational and local_available:
-        return "Task is operational and local Ollama is available."
+        return "Task is operational and the local mini-brain is enabled and available."
     if operational and not local_available:
-        return "Task is operational, but Ollama is not available; coordinator/API fallback should execute."
+        return "Task is operational, but the local mini-brain is not enabled or available; coordinator/API fallback should execute."
     return "Task requires coordinator-level reasoning or review."