agent-toolkit-cli 1.0.3__py3-none-any.whl

agent_toolkit/runner/dispatcher.py

@@ -0,0 +1,164 @@
+"""LLM dispatcher for the dev-companion runner.
+
+Selects the best available LLM provider, constrained by an :class:`LLMPolicy`
+that captures client-driven privacy/billing requirements (allowlist, denylist,
+pinned provider/model, fail-closed ``strict`` mode).
+
+When no policy is supplied, behaviour is backwards-compatible: providers are
+ordered by their hard-coded ``get_priority()`` and the first available one is
+selected.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+import sys
+from pathlib import Path as _Path
+
+sys.path.insert(0, str(_Path(__file__).parent))
+
+from policy import LLMPolicy
+from providers import (
+    AnthropicProvider,
+    LLMProvider,
+    LLMResponse,
+    OllamaProvider,
+    OpenAIProvider,
+    OpenCodeProvider,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LLMDispatcher:
+    """Pick a provider that satisfies the active :class:`LLMPolicy`.
+
+    The dispatcher never silently falls back to a denied provider: if the
+    policy filters every provider out and ``strict`` is set, the caller gets
+    an explicit ``policy_no_provider_available`` error. Non-strict mode keeps
+    the previous behaviour (returns ``None``; caller can use a skeleton plan).
+    """
+
+    POLICY_VIOLATION = "policy_no_provider_available"
+
+    def __init__(self, policy: LLMPolicy | None = None) -> None:
+        self._policy: LLMPolicy = policy or LLMPolicy.empty()
+        self._providers: list[LLMProvider] = []
+        self._candidates: list[LLMProvider] = []
+        self._selected: Optional[LLMProvider] = None
+        self._initialize_providers()
+
+    @property
+    def policy(self) -> LLMPolicy:
+        return self._policy
+
+    def _initialize_providers(self) -> None:
+        all_providers: list[LLMProvider] = [
+            OpenCodeProvider(),
+            OllamaProvider(),
+            AnthropicProvider(),
+            OpenAIProvider(),
+        ]
+        # Stable hard-coded ordering for the unfiltered case.
+        all_providers.sort(key=lambda p: p.get_priority())
+        self._providers = all_providers
+        self._candidates = self._policy.filter(all_providers)
+
+    def list_candidates(self) -> list[dict]:
+        """Detailed status for every candidate after policy filtering, without
+        executing the model. Used by the ``llm-status`` diagnostic."""
+        return [
+            {
+                "name": p.name,
+                "model": p.get_model_name(),
+                "available": p.is_available(),
+                "is_local": getattr(p, "is_local", False),
+                "is_free": getattr(p, "is_free", False),
+                "priority": p.get_priority(),
+            }
+            for p in self._candidates
+        ]
+
+    def list_all_providers(self) -> list[dict]:
+        """Status for every known provider, regardless of policy. Useful for
+        operators who need to see what was filtered out and why."""
+        candidate_names = {p.name for p in self._candidates}
+        return [
+            {
+                "name": p.name,
+                "model": p.get_model_name(),
+                "available": p.is_available(),
+                "is_local": getattr(p, "is_local", False),
+                "is_free": getattr(p, "is_free", False),
+                "priority": p.get_priority(),
+                "in_policy": p.name in candidate_names,
+            }
+            for p in self._providers
+        ]
+
+    def get_available_provider(self) -> Optional[LLMProvider]:
+        if not self._candidates:
+            logger.warning(
+                "LLM policy filtered out every provider (allowlist=%s, deny=%s, pinned=%s)",
+                list(self._policy.allowlist) if self._policy.allowlist else None,
+                list(self._policy.denylist),
+                self._policy.pinned_provider,
+            )
+            return None
+        for provider in self._candidates:
+            if provider.is_available():
+                logger.info(
+                    "Selected provider: %s (model: %s)",
+                    provider.name,
+                    provider.get_model_name(),
+                )
+                self._selected = provider
+                return provider
+        logger.warning(
+            "No allowed LLM provider is available (strict=%s)",
+            self._policy.strict,
+        )
+        return None
+
+    def get_selected(self) -> Optional[LLMProvider]:
+        return self._selected
+
+    def list_providers(self) -> list[dict]:
+        # Backwards-compatible alias used by ``dots_ai_devcompanion_runner``.
+        return self.list_candidates() or self.list_all_providers()
+
+    def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        repo_path: Optional[Path] = None,
+        timeout_sec: int = 300,
+    ) -> tuple[Optional[LLMResponse], Optional[str]]:
+        provider = self.get_selected()
+        if not provider:
+            if self._policy.strict:
+                return None, self.POLICY_VIOLATION
+            return None, "no_provider"
+
+        try:
+            response = provider.generate(
+                prompt=prompt,
+                system_prompt=system_prompt,
+                repo_path=repo_path,
+                timeout_sec=timeout_sec,
+            )
+            return response, None
+        except Exception as exc:  # pragma: no cover - safety net
+            logger.error("Provider %s failed: %s", provider.name, exc)
+            return None, str(exc)
+
+
+def create_dispatcher(policy: LLMPolicy | None = None) -> LLMDispatcher:
+    debug = os.environ.get("DOTS_WORKSTATION_LLM_DEBUG", "").lower() in ("1", "true", "yes", "on")
+    if debug:
+        logging.basicConfig(level=logging.DEBUG)
+    return LLMDispatcher(policy=policy)

agent_toolkit/runner/policy.py

@@ -0,0 +1,345 @@
+"""LLM execution policy for the agent-toolkit dev-companion runner.
+
+Defines which LLM providers are allowed to run, in what order, and whether
+the runner is required to fail closed when no allowed provider is available
+(for client engagements that mandate a single billing/data identity).
+
+Policy sources, in order of precedence — each layer can only RESTRICT the
+prior one, never widen it:
+
+1. Global environment variables (machine baseline / engagement env file).
+2. Optional JSON config file at ``~/.config/agent-toolkit/devcompanion-llm.json``
+   (path overridable with ``DOTS_WORKSTATION_DEVCOMPANION_LLM_CONFIG``).
+3. Per-job ``llm`` object inside the ``.job`` JSON.
+
+A job may further restrict (subset of ``allowlist``, additional ``denylist``
+entries, ``strict: true``) but cannot expand the global allowlist or relax
+strict mode that was set globally.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+logger = logging.getLogger(__name__)
+
+KNOWN_PROVIDERS: tuple[str, ...] = ("opencode", "ollama", "anthropic", "openai")
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "agent-toolkit" / "devcompanion-llm.json"
+
+
+class PolicyError(ValueError):
+    """Raised when policy values are inconsistent (for example a job tries to widen
+    the globally allowed set, or a pinned provider is denied)."""
+
+
+def _truthy(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return False
+    return str(value).strip().lower() in ("1", "true", "yes", "on")
+
+
+def _split_list(value: Any) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        items: list[str] = [s.strip() for s in value.split(",")]
+    elif isinstance(value, Iterable) and not isinstance(value, (bytes, bytearray)):
+        items = [str(s).strip() for s in value]
+    else:
+        return ()
+    return tuple(item.lower() for item in items if item)
+
+
+def _normalize_name(name: Any) -> str | None:
+    if name is None:
+        return None
+    text = str(name).strip().lower()
+    return text or None
+
+
+@dataclass(frozen=True)
+class LLMPolicy:
+    """Effective execution policy for the LLM dispatcher.
+
+    ``allowlist`` preserves order: when set, the dispatcher keeps providers in
+    that order rather than the implementation's hard-coded priority. This lets
+    operators express "prefer Anthropic first, then OpenAI" explicitly.
+
+    ``sources`` is for audit only; it lists which layers contributed to the
+    effective policy (``env``, ``file``, ``job``).
+    """
+
+    allowlist: tuple[str, ...] | None = None
+    denylist: tuple[str, ...] = ()
+    pinned_provider: str | None = None
+    pinned_model: str | None = None
+    strict: bool = False
+    sources: tuple[str, ...] = ()
+    warnings: tuple[str, ...] = field(default_factory=tuple)
+
+    # ── loaders ────────────────────────────────────────────────────────────
+    @classmethod
+    def empty(cls) -> "LLMPolicy":
+        return cls()
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> "LLMPolicy":
+        env = os.environ if env is None else env
+        allow = _split_list(env.get("DOTS_WORKSTATION_DEVCOMPANION_LLM_ALLOWLIST"))
+        deny = _split_list(env.get("DOTS_WORKSTATION_DEVCOMPANION_LLM_DENYLIST"))
+        pinned = _normalize_name(env.get("DOTS_WORKSTATION_DEVCOMPANION_LLM_PINNED_PROVIDER"))
+        pinned_model_raw = env.get("DOTS_WORKSTATION_DEVCOMPANION_LLM_PINNED_MODEL")
+        pinned_model = (
+            pinned_model_raw.strip() if isinstance(pinned_model_raw, str) and pinned_model_raw.strip() else None
+        )
+        strict = _truthy(env.get("DOTS_WORKSTATION_DEVCOMPANION_LLM_STRICT"))
+
+        warnings = list(_unknown_warnings("env", allow, deny, pinned))
+        sources = ("env",) if (allow or deny or pinned or pinned_model or strict) else ()
+        return cls(
+            allowlist=allow or None,
+            denylist=deny,
+            pinned_provider=pinned,
+            pinned_model=pinned_model,
+            strict=strict,
+            sources=sources,
+            warnings=tuple(warnings),
+        )
+
+    @classmethod
+    def from_file(cls, path: Path | str | None = None) -> "LLMPolicy":
+        env_override = os.environ.get("DOTS_WORKSTATION_DEVCOMPANION_LLM_CONFIG")
+        if path is None:
+            path = Path(env_override) if env_override else DEFAULT_CONFIG_PATH
+        path = Path(path).expanduser()
+        if not path.is_file():
+            return cls.empty()
+
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            return cls(
+                warnings=(f"failed to parse policy file {path}: {exc}",),
+            )
+
+        if not isinstance(data, Mapping):
+            return cls(
+                warnings=(f"policy file {path} must contain a JSON object",),
+            )
+
+        allow = _split_list(data.get("allowlist"))
+        deny = _split_list(data.get("denylist"))
+        pinned = _normalize_name(data.get("pinned_provider") or data.get("provider"))
+        pinned_model = data.get("pinned_model") or data.get("model")
+        if isinstance(pinned_model, str):
+            pinned_model = pinned_model.strip() or None
+        else:
+            pinned_model = None
+        strict = _truthy(data.get("strict"))
+        warnings = list(_unknown_warnings(f"file {path}", allow, deny, pinned))
+        sources = (f"file:{path}",) if (allow or deny or pinned or pinned_model or strict) else ()
+        return cls(
+            allowlist=allow or None,
+            denylist=deny,
+            pinned_provider=pinned,
+            pinned_model=pinned_model,
+            strict=strict,
+            sources=sources,
+            warnings=tuple(warnings),
+        )
+
+    @classmethod
+    def from_job(cls, job_llm: Any) -> "LLMPolicy":
+        if job_llm is None or isinstance(job_llm, bool):
+            return cls.empty()
+        if not isinstance(job_llm, Mapping):
+            return cls.empty()
+
+        allow = _split_list(job_llm.get("allowlist"))
+        deny = _split_list(job_llm.get("denylist"))
+        pinned = _normalize_name(job_llm.get("provider") or job_llm.get("pinned_provider"))
+        pinned_model = job_llm.get("model") or job_llm.get("pinned_model")
+        if isinstance(pinned_model, str):
+            pinned_model = pinned_model.strip() or None
+        else:
+            pinned_model = None
+        strict = _truthy(job_llm.get("strict"))
+        warnings = list(_unknown_warnings("job", allow, deny, pinned))
+        sources = ("job",) if (allow or deny or pinned or pinned_model or strict) else ()
+        return cls(
+            allowlist=allow or None,
+            denylist=deny,
+            pinned_provider=pinned,
+            pinned_model=pinned_model,
+            strict=strict,
+            sources=sources,
+            warnings=tuple(warnings),
+        )
+
+    @classmethod
+    def load(
+        cls,
+        *,
+        env: Mapping[str, str] | None = None,
+        config_path: Path | str | None = None,
+        job_llm: Any | None = None,
+    ) -> "LLMPolicy":
+        """Compose ``env`` → ``file`` → ``job`` and validate that later layers only
+        restrict (never widen) earlier ones. Raises :class:`PolicyError` when a job
+        tries to escape the global allowlist."""
+        base = merge_policies(cls.from_env(env), cls.from_file(config_path))
+        if job_llm is None:
+            return base
+        job = cls.from_job(job_llm)
+        return merge_policies(base, job, _validate_restriction=True)
+
+    # ── filtering ──────────────────────────────────────────────────────────
+    def filter(self, providers: Iterable[Any]) -> list[Any]:
+        """Return providers permitted by the policy, ordered by preference.
+
+        Mutates the ``model`` attribute on a pinned provider when ``pinned_model``
+        is set, so the caller can use the pinned model without changing the
+        provider classes.
+        """
+        by_name: dict[str, Any] = {}
+        for p in providers:
+            name = _provider_name(p)
+            if name:
+                by_name[name] = p
+
+        if self.pinned_provider:
+            if self.pinned_provider in self.denylist:
+                return []
+            provider = by_name.get(self.pinned_provider)
+            if provider is None:
+                return []
+            if self.pinned_model and hasattr(provider, "model"):
+                try:
+                    setattr(provider, "model", self.pinned_model)
+                except Exception:
+                    logger.debug("Could not set pinned model on provider %s", self.pinned_provider)
+            return [provider]
+
+        denied = set(self.denylist)
+        if self.allowlist:
+            ordered: list[Any] = []
+            for name in self.allowlist:
+                if name in denied:
+                    continue
+                provider = by_name.get(name)
+                if provider is not None:
+                    ordered.append(provider)
+            return ordered
+
+        sorted_providers = sorted(by_name.values(), key=lambda p: getattr(p, "get_priority", lambda: 100)())
+        return [p for p in sorted_providers if _provider_name(p) not in denied]
+
+    # ── audit ──────────────────────────────────────────────────────────────
+    def to_audit(self) -> dict[str, Any]:
+        return {
+            "allowlist": list(self.allowlist) if self.allowlist else None,
+            "denylist": list(self.denylist),
+            "pinned_provider": self.pinned_provider,
+            "pinned_model": self.pinned_model,
+            "strict": self.strict,
+            "sources": list(self.sources),
+            "warnings": list(self.warnings),
+        }
+
+
+def _provider_name(provider: Any) -> str:
+    return str(getattr(provider, "name", "")).strip().lower()
+
+
+def _unknown_warnings(
+    layer: str,
+    allow: tuple[str, ...],
+    deny: tuple[str, ...],
+    pinned: str | None,
+) -> Iterable[str]:
+    for name in allow:
+        if name not in KNOWN_PROVIDERS:
+            yield f"{layer}: allowlist contains unknown provider '{name}'"
+    for name in deny:
+        if name not in KNOWN_PROVIDERS:
+            yield f"{layer}: denylist contains unknown provider '{name}'"
+    if pinned and pinned not in KNOWN_PROVIDERS:
+        yield f"{layer}: pinned provider '{pinned}' is unknown"
+
+
+def merge_policies(
+    base: LLMPolicy,
+    overlay: LLMPolicy,
+    *,
+    _validate_restriction: bool = False,
+) -> LLMPolicy:
+    """Merge ``overlay`` on top of ``base``.
+
+    When ``_validate_restriction`` is true (job over global), ``overlay`` may only
+    restrict ``base``. Attempting to widen raises :class:`PolicyError`.
+    """
+    # Allowlist
+    if overlay.allowlist is None:
+        merged_allow = base.allowlist
+    elif base.allowlist is None:
+        merged_allow = overlay.allowlist
+    else:
+        if _validate_restriction:
+            extras = [name for name in overlay.allowlist if name not in base.allowlist]
+            if extras:
+                raise PolicyError(
+                    "job allowlist tries to add provider(s) not allowed globally: "
+                    + ", ".join(extras)
+                )
+        # Keep overlay order, but only entries also in base.
+        merged_allow = tuple(name for name in overlay.allowlist if name in base.allowlist)
+        if not merged_allow:
+            raise PolicyError(
+                "job allowlist is empty after intersecting with global allowlist"
+            )
+
+    # Denylist (always additive)
+    merged_deny = tuple(sorted(set(base.denylist) | set(overlay.denylist)))
+
+    # Pinned provider/model
+    merged_pin_provider = overlay.pinned_provider or base.pinned_provider
+    merged_pin_model = overlay.pinned_model or base.pinned_model
+
+    if _validate_restriction and overlay.pinned_provider:
+        if base.allowlist and overlay.pinned_provider not in base.allowlist:
+            raise PolicyError(
+                f"job pins provider '{overlay.pinned_provider}' but it is not in the global allowlist"
+            )
+        if overlay.pinned_provider in merged_deny:
+            raise PolicyError(
+                f"job pins provider '{overlay.pinned_provider}' but it is denied by policy"
+            )
+
+    # Strict can only escalate (False -> True). A job cannot lower a globally-strict policy.
+    merged_strict = base.strict or overlay.strict
+    if _validate_restriction and base.strict and overlay.strict is False and "job" in overlay.sources:
+        # Job explicitly set strict=false but base is strict: warn, keep True.
+        warnings = list(base.warnings) + list(overlay.warnings) + [
+            "job tried to set strict=false while global policy is strict; keeping strict=true",
+        ]
+    else:
+        warnings = list(base.warnings) + list(overlay.warnings)
+
+    sources = tuple(dict.fromkeys(list(base.sources) + list(overlay.sources)))
+
+    return LLMPolicy(
+        allowlist=merged_allow,
+        denylist=merged_deny,
+        pinned_provider=merged_pin_provider,
+        pinned_model=merged_pin_model,
+        strict=merged_strict,
+        sources=sources,
+        warnings=tuple(warnings),
+    )

agent_toolkit/runner/providers/__init__.py

@@ -0,0 +1,21 @@
+"""
+agent-toolkit dev-companion LLM providers.
+
+Provider-agnostic abstraction layer for LLM generation.
+Supports local (free) and cloud (paid) providers with automatic fallback.
+"""
+
+from .base import LLMProvider, LLMResponse
+from .opencode_provider import OpenCodeProvider
+from .ollama_provider import OllamaProvider
+from .anthropic_provider import AnthropicProvider
+from .openai_provider import OpenAIProvider
+
+__all__ = [
+    "LLMProvider",
+    "LLMResponse",
+    "OpenCodeProvider",
+    "OllamaProvider",
+    "AnthropicProvider",
+    "OpenAIProvider",
+]

agent_toolkit/runner/providers/anthropic_provider.py

@@ -0,0 +1,109 @@
+"""
+Anthropic provider for dev-companion.
+
+Uses Anthropic API (Claude) as optional paid provider.
+Requires: ANTHROPIC_API_KEY environment variable.
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+from .base import LLMProvider, LLMResponse
+
+
+class AnthropicProvider(LLMProvider):
+    name = "anthropic"
+    is_local = False
+    is_free = False
+
+    def __init__(self, model: str = "claude-3-5-haiku-20241022"):
+        self.model = model
+
+    def is_available(self) -> bool:
+        return bool(os.environ.get("ANTHROPIC_API_KEY"))
+
+    def supports_directory_context(self) -> bool:
+        return False
+
+    def get_model_name(self) -> str:
+        return self.model
+
+    def get_priority(self) -> int:
+        return 10
+
+    def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        repo_path: Optional[Path] = None,
+        timeout_sec: int = 300,
+    ) -> LLMResponse:
+        import urllib.request
+        import urllib.error
+
+        start_time = time.time()
+
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": os.environ["ANTHROPIC_API_KEY"],
+            "anthropic-version": "2023-06-01",
+        }
+
+        messages = [{"role": "user", "content": prompt}]
+        if system_prompt:
+            messages[0] = {
+                "role": "user",
+                "content": f"{system_prompt}\n\n---\n\n{prompt}",
+            }
+
+        data = {
+            "model": self.model,
+            "messages": messages,
+            "max_tokens": 4096,
+        }
+
+        try:
+            req = urllib.request.Request(
+                "https://api.anthropic.com/v1/messages",
+                data=json.dumps(data).encode(),
+                headers=headers,
+                method="POST",
+            )
+
+            with urllib.request.urlopen(req, timeout=timeout_sec) as response:
+                result = json.loads(response.read().decode())
+
+            duration = time.time() - start_time
+
+            content = ""
+            for block in result.get("content", []):
+                if block.get("type") == "text":
+                    content += block.get("text", "")
+
+            usage = result.get("usage", {})
+
+            return LLMResponse(
+                content=content,
+                model=self.model,
+                provider=self.name,
+                tokens_used=usage.get("output_tokens"),
+                duration_sec=duration,
+            )
+
+        except urllib.error.HTTPError as e:
+            return LLMResponse(
+                content=f"HTTP Error: {e.code} - {e.reason}",
+                model=self.model,
+                provider=self.name,
+                duration_sec=time.time() - start_time,
+            )
+        except Exception as e:
+            return LLMResponse(
+                content=f"Error: {str(e)}",
+                model=self.model,
+                provider=self.name,
+                duration_sec=time.time() - start_time,
+            )

agent_toolkit/runner/providers/base.py

@@ -0,0 +1,53 @@
+"""
+Base interface for LLM providers.
+
+All providers must implement this interface to be used by the dev-companion runner.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class LLMResponse:
+    content: str
+    model: str
+    provider: str
+    tokens_used: Optional[int] = None
+    duration_sec: Optional[float] = None
+
+
+class LLMProvider(ABC):
+    name: str
+    is_local: bool = False
+    is_free: bool = False
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the provider is available (installed, configured, etc.)"""
+        pass
+
+    @abstractmethod
+    def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        repo_path: Optional[Path] = None,
+        timeout_sec: int = 300,
+    ) -> LLMResponse:
+        """Generate a response from the LLM"""
+        pass
+
+    def get_priority(self) -> int:
+        """Lower = higher priority. Local free providers should have priority over cloud paid ones."""
+        return 100
+
+    def supports_directory_context(self) -> bool:
+        """Whether the provider can operate in a specific directory context"""
+        return False
+
+    def get_model_name(self) -> str:
+        """Return the model name used by this provider"""
+        return "unknown"