agent-devkit 0.1.0 → 0.1.6

package/runtime/cli/aikit/model_router.py

@@ -0,0 +1,79 @@
+"""Task-to-model routing decisions for Agent DevKit."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from cli.aikit.llm import BACKENDS, doctor_backend, llm_preference, load_config
+from cli.aikit.ollama import ollama_status
+
+
+OPERATIONAL_PATTERN = re.compile(
+    r"(?i)\b(resum\w*|sumari\w*|classifi\w*|extra(?:i|ir|ia|cao|ção)\w*|normaliz\w*|compar\w*|logs?|rascunho|agrupe|agrupar)\b"
+)
+HIGH_LEVEL_PATTERN = re.compile(
+    r"(?i)\b(arquitet|decid|aprovar|reprovar|especifica|requisit|implemente|codigo|c[oó]digo|documento|automac|deploy|seguran)\b"
+)
+
+
+def build_model_plan(prompt: str, *, route: 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"
+    operational = bool(OPERATIONAL_PATTERN.search(prompt))
+    high_level = bool(HIGH_LEVEL_PATTERN.search(prompt))
+    use_local = operational and local_available
+    return {
+        "kind": "model-plan",
+        "status": "planned",
+        "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_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"),
+            "base_url": ollama_backend.get("base_url"),
+        },
+        "local_llm_recommended": operational,
+        "local_llm_selected": use_local,
+        "delegation": {
+            "allowed": operational,
+            "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",
+            ],
+        },
+        "fallback_order": preference.get("order") or [],
+        "route": route,
+    }
+
+
+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"}]
+    for item in ("claude-code", "codex-cli"):
+        if item not in preferred:
+            preferred.append(item)
+    return preferred
+
+
+def local_reason(*, operational: bool, local_available: bool, high_level: bool) -> str:
+    if operational and local_available and high_level:
+        return "Use Ollama for operational preprocessing; coordinator review remains mandatory."
+    if operational and local_available:
+        return "Task is operational and local Ollama is available."
+    if operational and not local_available:
+        return "Task is operational, but Ollama is not available; coordinator/API fallback should execute."
+    return "Task requires coordinator-level reasoning or review."

package/runtime/cli/aikit/ollama.py

@@ -0,0 +1,237 @@
+"""Ollama local LLM discovery and model management."""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+OLLAMA_TIMEOUT_SECONDS = 120
+DEFAULT_BASE_URL = "http://localhost:11434"
+
+
+def ollama_status(*, base_url: str = DEFAULT_BASE_URL) -> dict[str, Any]:
+    binary = shutil.which("ollama")
+    version = command_output(["ollama", "--version"]) if binary else None
+    daemon = daemon_status(base_url) if binary else {"status": "unknown", "message": "Ollama binary is not installed."}
+    models = list_local_models(binary_available=bool(binary))
+    status = "ok" if binary else "missing"
+    return {
+        "kind": "ollama-status",
+        "status": status,
+        "binary": binary,
+        "version": first_line(version),
+        "base_url": base_url,
+        "daemon": daemon,
+        "models": models,
+        "model_count": len(models),
+        "install_plan": install_plan() if not binary else None,
+    }
+
+
+def ollama_models() -> dict[str, Any]:
+    binary = shutil.which("ollama")
+    items = list_local_models(binary_available=bool(binary))
+    return {
+        "kind": "ollama-models",
+        "status": "ok" if binary else "missing",
+        "binary": binary,
+        "items": items,
+        "recommended": recommended_models(installed={item["name"] for item in items}),
+    }
+
+
+def ollama_pull(model: str | None, *, yes: bool = False, dry_run: bool = False) -> dict[str, Any]:
+    if not model:
+        raise ValueError("ollama pull requires a model name")
+    binary = shutil.which("ollama")
+    command = ["ollama", "pull", model]
+    if dry_run or not yes:
+        return {
+            "kind": "ollama-pull",
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "model": model,
+            "binary": binary,
+            "command": command,
+            "dry_run": dry_run,
+            "yes": yes,
+            "message": "Use --yes to pull the model." if not dry_run and not yes else "Dry-run only.",
+        }
+    if not binary:
+        return {
+            "kind": "ollama-pull",
+            "status": "missing",
+            "ok": False,
+            "model": model,
+            "command": command,
+            "message": "Ollama binary not found in PATH.",
+            "install_plan": install_plan(),
+            "exit_code": 2,
+        }
+    process = run_command(command, timeout=OLLAMA_TIMEOUT_SECONDS * 5)
+    return {
+        "kind": "ollama-pull",
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "model": model,
+        "binary": binary,
+        "command": command,
+        "exit_code": process.returncode,
+        "stdout": safe_tail(process.stdout),
+        "stderr": safe_tail(process.stderr),
+    }
+
+
+def ollama_update(*, yes: bool = False, dry_run: bool = False) -> dict[str, Any]:
+    command = update_command()
+    if dry_run or not yes:
+        return {
+            "kind": "ollama-update",
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "command": command,
+            "dry_run": dry_run,
+            "yes": yes,
+            "message": "Use --yes to run the update command." if not dry_run and not yes else "Dry-run only.",
+        }
+    process = run_command(command, timeout=OLLAMA_TIMEOUT_SECONDS * 5, shell=True)
+    return {
+        "kind": "ollama-update",
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "command": command,
+        "exit_code": process.returncode,
+        "stdout": safe_tail(process.stdout),
+        "stderr": safe_tail(process.stderr),
+    }
+
+
+def list_local_models(*, binary_available: bool) -> list[dict[str, Any]]:
+    if not binary_available:
+        return []
+    output = command_output(["ollama", "list"])
+    if not output:
+        return []
+    return parse_ollama_list(output)
+
+
+def parse_ollama_list(output: str) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    for line in output.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.lower().startswith("name "):
+            continue
+        parts = stripped.split()
+        if not parts:
+            continue
+        items.append(
+            {
+                "name": parts[0],
+                "id": parts[1] if len(parts) > 1 else None,
+                "size": parts[2] if len(parts) > 2 else None,
+                "modified": " ".join(parts[3:]) if len(parts) > 3 else None,
+            }
+        )
+    return items
+
+
+def recommended_models(*, installed: set[str]) -> list[dict[str, Any]]:
+    catalog = [
+        ("qwen2.5-coder", "coding", "operational code reading and generation"),
+        ("deepseek-coder", "coding", "code analysis and mechanical refactors"),
+        ("deepseek-r1", "reasoning", "local reasoning drafts with mandatory review"),
+        ("llama3.2", "general", "general local summaries and classification"),
+        ("mistral", "general", "lightweight operational summaries"),
+        ("gemma", "classification", "small extraction and classification tasks"),
+    ]
+    return [
+        {
+            "name": name,
+            "family": family,
+            "recommended_for": recommended_for,
+            "installed": any(item == name or item.startswith(f"{name}:") for item in installed),
+        }
+        for name, family, recommended_for in catalog
+    ]
+
+
+def daemon_status(base_url: str) -> dict[str, Any]:
+    url = base_url.rstrip("/") + "/api/tags"
+    try:
+        with urllib.request.urlopen(url, timeout=2) as response:  # noqa: S310 - local configurable daemon URL.
+            raw = response.read().decode("utf-8", errors="replace")
+    except urllib.error.URLError as exc:
+        return {"status": "unavailable", "message": str(exc.reason)}
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return {"status": "unknown", "message": "Ollama daemon returned non-JSON response."}
+    return {"status": "ok", "models": len(payload.get("models") or []) if isinstance(payload, dict) else None}
+
+
+def install_plan() -> dict[str, Any]:
+    system = platform.system().lower()
+    if system == "darwin":
+        command = "brew install ollama"
+    elif system.startswith("win"):
+        command = "winget install Ollama.Ollama"
+    else:
+        command = "curl -fsSL https://ollama.com/install.sh | sh"
+    return {"platform": platform_key(), "command": command, "requires_opt_in": True}
+
+
+def update_command() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "brew upgrade ollama"
+    if system.startswith("win"):
+        return "winget upgrade Ollama.Ollama"
+    return "curl -fsSL https://ollama.com/install.sh | sh"
+
+
+def platform_key() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "darwin"
+    if system.startswith("win"):
+        return "windows"
+    return "linux"
+
+
+def command_output(command: list[str]) -> str | None:
+    try:
+        process = run_command(command, timeout=10)
+    except OSError:
+        return None
+    if process.returncode != 0:
+        return None
+    return process.stdout.strip() or process.stderr.strip()
+
+
+def run_command(command: list[str] | str, *, timeout: int, shell: bool = False) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        shell=shell,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        timeout=timeout,
+    )
+
+
+def safe_tail(value: str | None, *, limit: int = 4000) -> str:
+    text = value or ""
+    return text[-limit:]
+
+
+def first_line(value: str | None) -> str | None:
+    if not value:
+        return None
+    return value.splitlines()[0]