forgex-cli 0.1.0__py3-none-any.whl

forgex/models/base.py

@@ -0,0 +1,112 @@
+"""Model provider contract (spec section 13).
+
+Agents never touch provider SDKs — they talk to the ModelRouter, which
+talks to adapters implementing this ABC.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Message(BaseModel):
+    """One chat message (wire format for OpenAI-compatible APIs)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    role: str  # system | user | assistant | tool
+    content: str | None = None
+    name: str | None = None
+    tool_call_id: str | None = None
+    tool_calls: list[dict[str, Any]] | None = None
+
+
+ChatMessage = Message
+
+
+class ToolCall(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    id: str = ""
+    name: str
+    arguments: Any = ""
+
+
+class ModelUsage(BaseModel):
+    """Usage as reported by the provider (None = not reported)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+
+    def __init__(self, **data: Any) -> None:
+        if "input_tokens" in data and "prompt_tokens" not in data:
+            data["prompt_tokens"] = data.pop("input_tokens")
+        if "output_tokens" in data and "completion_tokens" not in data:
+            data["completion_tokens"] = data.pop("output_tokens")
+        super().__init__(**data)
+
+    @property
+    def input_tokens(self) -> int | None:
+        return self.prompt_tokens
+
+    @property
+    def output_tokens(self) -> int | None:
+        return self.completion_tokens
+
+
+class ModelRequest(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    model: str
+    messages: list[Message]
+    system: str | None = None
+    tools: list[dict[str, Any]] | None = None
+    tool_choice: str | None = None
+    response_format: dict[str, str] | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+
+
+class ModelResponse(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    content: str | None = None
+    model: str = "default"
+    provider: str = "default"
+    usage: ModelUsage | None = None
+    attempts: int = 1
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+
+
+class ProviderHealth(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str
+    ok: bool
+    detail: str
+    latency_ms: float | None = None
+
+
+class ModelProvider(ABC):
+    @abstractmethod
+    async def generate(self, request: ModelRequest) -> ModelResponse:
+        pass
+
+    @abstractmethod
+    def stream(self, request: ModelRequest) -> AsyncIterator[str]:
+        pass
+
+    @abstractmethod
+    async def health(self) -> ProviderHealth:
+        pass
+
+    @abstractmethod
+    async def aclose(self) -> None:
+        pass

forgex/models/capabilities.py

@@ -0,0 +1,21 @@
+"""Model capability metadata (spec section 31).
+
+Never assume a model supports a feature: the router reads these and
+adapts requests (drops tools / response_format when unsupported).
+Unknown models get conservative defaults — honest "unknown", not guesses.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ModelCapabilities(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    model: str
+    context_window: int | None = None  # None = unknown
+    supports_tools: bool = False
+    supports_json: bool = False
+    supports_streaming: bool = False
+    known: bool = False  # False = inferred conservative defaults, not verified

forgex/models/factory.py

@@ -0,0 +1,66 @@
+"""Provider factory: config → provider instance (spec sections 13, 26, 46, 73)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from forgex.config.schema import ForgexConfig, ProviderConfig
+from forgex.models.base import ModelProvider
+from forgex.models.groq import DEFAULT_API_KEY_ENV as GROQ_KEY_ENV
+from forgex.models.groq import DEFAULT_BASE_URL as GROQ_BASE_URL
+from forgex.models.groq import GroqProvider
+from forgex.models.local import LocalProvider
+from forgex.models.openai_compatible import OpenAICompatibleProvider
+from forgex.schemas.error import ConfigError, ProviderError
+
+
+def resolve_api_key(config: ProviderConfig) -> str | None:
+    env_name = config.api_key_env
+    if env_name is None and config.type == "groq":
+        env_name = GROQ_KEY_ENV
+    if not env_name:
+        return None
+    return os.environ.get(env_name) or None
+
+
+def build_provider(
+    name: str,
+    config: ProviderConfig,
+    *,
+    http_client: Any = None,
+) -> ModelProvider:
+    """Build the provider instance for a configured provider entry."""
+    if os.environ.get("FORGEX_OFFLINE") == "1" and config.type != "local":
+        msg = (
+            f"offline mode: remote provider '{name}' is disabled "
+            "(--offline / FORGEX_OFFLINE=1) — configure a local provider"
+        )
+        raise ProviderError(msg)
+
+    kwargs: dict[str, Any] = {
+        "api_key": resolve_api_key(config),
+        "timeout_seconds": config.timeout_seconds,
+        "max_retries": config.max_retries,
+    }
+    if http_client is not None:
+        kwargs["http_client"] = http_client
+
+    if config.type == "groq":
+        return GroqProvider(base_url=config.base_url or GROQ_BASE_URL, **kwargs)
+    if config.type == "local":
+        if not config.base_url:
+            msg = (
+                f"Provider '{name}' (local) needs a base_url, "
+                "e.g. http://localhost:11434/v1"
+            )
+            raise ConfigError(msg)
+        return LocalProvider(base_url=config.base_url, **kwargs)
+    if not config.base_url:
+        msg = f"Provider '{name}' (openai_compatible) needs a base_url"
+        raise ConfigError(msg)
+    return OpenAICompatibleProvider(name, base_url=config.base_url, **kwargs)
+
+
+def provider_names(config: ForgexConfig) -> list[str]:
+    return sorted(config.providers)

forgex/models/groq.py

@@ -0,0 +1,13 @@
+"""Groq adapter — the OpenAI-compatible protocol with Groq defaults."""
+
+from __future__ import annotations
+
+from forgex.models.openai_compatible import OpenAICompatibleProvider
+
+DEFAULT_BASE_URL = "https://api.groq.com/openai/v1"
+DEFAULT_API_KEY_ENV = "FORGEX_GROQ_API_KEY"
+
+
+class GroqProvider(OpenAICompatibleProvider):
+    def __init__(self, *, base_url: str | None = None, api_key: str | None = None, **kwargs) -> None:
+        super().__init__("groq", base_url=base_url or DEFAULT_BASE_URL, api_key=api_key, **kwargs)

forgex/models/local.py

@@ -0,0 +1,10 @@
+"""Local model provider — any local OpenAI-compatible server."""
+
+from __future__ import annotations
+
+from forgex.models.openai_compatible import OpenAICompatibleProvider
+
+
+class LocalProvider(OpenAICompatibleProvider):
+    def __init__(self, *, base_url: str, api_key: str | None = None, **kwargs) -> None:
+        super().__init__("local", base_url=base_url, api_key=api_key, **kwargs)

forgex/models/openai_compatible.py

@@ -0,0 +1,233 @@
+"""OpenAI-compatible chat-completions adapter.
+
+Works with any server implementing POST /chat/completions and GET /models
+(OpenAI, Groq, llama.cpp, Ollama, vLLM, LM Studio, ...).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from forgex.models.base import (
+    ModelProvider,
+    ModelRequest,
+    ModelResponse,
+    ModelUsage,
+    ProviderHealth,
+    ToolCall,
+)
+from forgex.orchestration.retry import RetryPolicy, run_with_retries
+from forgex.schemas.error import AuthenticationError, ProviderError, RateLimitError
+from forgex.utils.redact import redact
+
+logger = logging.getLogger("forgex.models")
+
+
+def parse_sse_content(line: str) -> str | None:
+    """Parse one SSE line: content delta, '' for [DONE], None to skip."""
+    if not line.startswith("data:"):
+        return None
+    data = line[len("data:") :].strip()
+    if not data:
+        return None
+    if data == "[DONE]":
+        return ""
+    try:
+        chunk = json.loads(data)
+    except ValueError:
+        return None
+    choices = chunk.get("choices") or []
+    if not choices:
+        return None
+    content = (choices[0].get("delta") or {}).get("content")
+    return content if content else None
+
+
+class OpenAICompatibleProvider(ModelProvider):
+    """Adapter for OpenAI-compatible HTTP APIs."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        timeout_seconds: float = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.name = name
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+        self.max_retries = max_retries
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout_seconds)
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _redact_error(self, message: str) -> str:
+        secrets = [self.api_key] if self.api_key else []
+        return redact(message, secrets)
+
+    async def generate(self, request: ModelRequest) -> ModelResponse:
+        url = f"{self.base_url}/chat/completions"
+
+        messages_payload: list[dict[str, Any]] = []
+        if request.system:
+            messages_payload.append({"role": "system", "content": request.system})
+
+        for msg in request.messages:
+            item: dict[str, Any] = {"role": msg.role, "content": msg.content}
+            if msg.name:
+                item["name"] = msg.name
+            if msg.tool_call_id:
+                item["tool_call_id"] = msg.tool_call_id
+            if msg.tool_calls:
+                item["tool_calls"] = msg.tool_calls
+            messages_payload.append(item)
+
+        body: dict[str, Any] = {
+            "model": request.model,
+            "messages": messages_payload,
+        }
+
+        if request.tools:
+            body["tools"] = request.tools
+            body["tool_choice"] = request.tool_choice or "auto"
+        if request.response_format:
+            body["response_format"] = request.response_format
+        if request.temperature is not None:
+            body["temperature"] = request.temperature
+        if request.max_tokens is not None:
+            body["max_tokens"] = request.max_tokens
+
+        async def _call() -> httpx.Response:
+            try:
+                resp = await self._client.post(url, headers=self._headers(), json=body)
+            except httpx.TimeoutException as exc:
+                msg = self._redact_error(f"Timeout calling {self.name}: {exc}")
+                raise ProviderError(msg, retryable=True) from exc
+            except httpx.NetworkError as exc:
+                msg = self._redact_error(f"Network error calling {self.name}: {exc}")
+                raise ProviderError(msg, retryable=True) from exc
+            except OSError as exc:
+                msg = self._redact_error(f"Connection error calling {self.name}: {exc}")
+                raise ProviderError(msg, retryable=True) from exc
+
+            if resp.status_code in (401, 403):
+                msg = self._redact_error(f"Authentication failed for {self.name}: {resp.text}")
+                raise AuthenticationError(msg)
+            elif resp.status_code == 429:
+                msg = self._redact_error(f"Rate limited by {self.name}: {resp.text}")
+                raise RateLimitError(msg)
+            elif resp.status_code >= 500:
+                msg = self._redact_error(f"Server error from {self.name} ({resp.status_code}): {resp.text}")
+                raise ProviderError(msg, retryable=True)
+            elif resp.status_code != 200:
+                msg = self._redact_error(f"Error from {self.name} ({resp.status_code}): {resp.text}")
+                raise ProviderError(msg, retryable=False)
+
+            return resp
+
+        policy = RetryPolicy(max_attempts=self.max_retries + 1, initial_delay=1.0)
+        try:
+            http_resp, attempts = await run_with_retries(_call, policy=policy)
+        except ProviderError as exc:
+            exc.attempts = getattr(exc, "attempts", 1)
+            raise
+
+        data = http_resp.json()
+        choices = data.get("choices") or []
+        first_choice = choices[0] if choices else {}
+        message_data = first_choice.get("message") or {}
+
+        content = message_data.get("content")
+
+        # Parse tool calls
+        tool_calls: list[ToolCall] = []
+        raw_tcs = message_data.get("tool_calls") or []
+        for raw_tc in raw_tcs:
+            fn = raw_tc.get("function") or {}
+            tool_calls.append(
+                ToolCall(
+                    id=raw_tc.get("id", ""),
+                    name=fn.get("name", ""),
+                    arguments=fn.get("arguments", ""),
+                )
+            )
+
+        # Parse usage
+        usage_data = data.get("usage")
+        usage = None
+        if usage_data:
+            usage = ModelUsage(
+                prompt_tokens=usage_data.get("prompt_tokens"),
+                completion_tokens=usage_data.get("completion_tokens"),
+                total_tokens=usage_data.get("total_tokens"),
+            )
+
+        return ModelResponse(
+            content=content,
+            model=data.get("model", request.model),
+            provider=self.name,
+            usage=usage,
+            attempts=attempts,
+            tool_calls=tool_calls,
+        )
+
+    async def stream(self, request: ModelRequest) -> AsyncIterator[str]:
+        url = f"{self.base_url}/chat/completions"
+
+        messages_payload: list[dict[str, Any]] = []
+        if request.system:
+            messages_payload.append({"role": "system", "content": request.system})
+        for msg in request.messages:
+            messages_payload.append({"role": msg.role, "content": msg.content})
+
+        body: dict[str, Any] = {
+            "model": request.model,
+            "messages": messages_payload,
+            "stream": True,
+        }
+        if request.temperature is not None:
+            body["temperature"] = request.temperature
+
+        async with self._client.stream("POST", url, headers=self._headers(), json=body) as response:
+            if response.status_code != 200:
+                text = await response.aread()
+                err_msg = self._redact_error(f"Stream error {response.status_code}: {text.decode('utf-8', 'replace')}")
+                raise ProviderError(err_msg)
+            async for line in response.aiter_lines():
+                content = parse_sse_content(line)
+                if content:
+                    yield content
+
+    async def health(self) -> ProviderHealth:
+        start = time.perf_counter()
+        try:
+            url = f"{self.base_url}/models"
+            resp = await self._client.get(url, headers=self._headers(), timeout=10.0)
+            latency = (time.perf_counter() - start) * 1000
+            if resp.status_code == 200:
+                return ProviderHealth(provider=self.name, ok=True, detail="available", latency_ms=latency)
+            msg = self._redact_error(f"HTTP {resp.status_code}")
+            return ProviderHealth(provider=self.name, ok=False, detail=msg, latency_ms=latency)
+        except Exception as exc:  # noqa: BLE001
+            latency = (time.perf_counter() - start) * 1000
+            msg = self._redact_error(str(exc))
+            return ProviderHealth(provider=self.name, ok=False, detail=msg, latency_ms=latency)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()

forgex/models/registry.py

@@ -0,0 +1,81 @@
+"""Model registry (spec sections 14, 31, 65).
+
+The built-in catalog is an ADVISORY snapshot — model IDs go stale. Actual
+selection always comes from user configuration; the catalog only informs
+capability adaptation.
+"""
+
+from __future__ import annotations
+
+from forgex.models.capabilities import ModelCapabilities
+
+_DEFAULT_CATALOG: dict[str, ModelCapabilities] = {
+    # Groq models
+    "llama-3.3-70b-versatile": ModelCapabilities(
+        model="llama-3.3-70b-versatile",
+        context_window=131072,
+        supports_tools=True,
+        supports_json=True,
+        supports_streaming=True,
+        known=True,
+    ),
+    "llama-3.1-8b-instant": ModelCapabilities(
+        model="llama-3.1-8b-instant",
+        context_window=131072,
+        supports_tools=True,
+        supports_json=True,
+        supports_streaming=True,
+        known=True,
+    ),
+    # OpenAI models
+    "gpt-4o": ModelCapabilities(
+        model="gpt-4o",
+        context_window=128000,
+        supports_tools=True,
+        supports_json=True,
+        supports_streaming=True,
+        known=True,
+    ),
+    "gpt-4o-mini": ModelCapabilities(
+        model="gpt-4o-mini",
+        context_window=128000,
+        supports_tools=True,
+        supports_json=True,
+        supports_streaming=True,
+        known=True,
+    ),
+    "o1-mini": ModelCapabilities(
+        model="o1-mini",
+        context_window=128000,
+        supports_tools=False,
+        supports_json=True,
+        supports_streaming=False,
+        known=True,
+    ),
+}
+
+
+class ModelRegistry:
+    def __init__(self, overrides: dict[str, ModelCapabilities] | None = None) -> None:
+        self._catalog = dict(_DEFAULT_CATALOG)
+        if overrides:
+            for k, cap in overrides.items():
+                if not cap.known:
+                    cap = cap.model_copy(update={"known": True})
+                self._catalog[k] = cap
+
+    def lookup(self, model: str) -> ModelCapabilities:
+        if model in self._catalog:
+            return self._catalog[model]
+        # Conservative defaults for unknown models
+        return ModelCapabilities(
+            model=model,
+            context_window=None,
+            supports_tools=False,
+            supports_json=False,
+            supports_streaming=False,
+            known=False,
+        )
+
+    def catalog(self) -> list[ModelCapabilities]:
+        return sorted(self._catalog.values(), key=lambda c: c.model)