readyagentsdev 0.8.2__py3-none-any.whl

readyagents/llm/openai_provider.py

@@ -0,0 +1,70 @@
+"""OpenAI Chat Completions provider."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from readyagents.errors import LLMError
+from readyagents.llm.base import CompletionResult, Message
+from readyagents.llm.tool_calls import (
+    messages_to_openai,
+    openai_tools_payload,
+    tool_calls_from_openai_message,
+)
+
+
+class OpenAIProvider:
+    name = "openai"
+
+    def __init__(self, api_key: str, *, base_url: str | None = None) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+
+    def complete(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> CompletionResult:
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise LLMError(
+                "The OpenAI extra is not installed. Run: pip install 'readyagents[openai]'"
+            ) from exc
+        try:
+            client_kwargs: dict[str, Any] = {"api_key": self._api_key}
+            if self._base_url:
+                client_kwargs["base_url"] = self._base_url
+            client = OpenAI(**client_kwargs)
+            payload: dict[str, Any] = {
+                "model": model,
+                "messages": messages_to_openai(messages),
+            }
+            openai_tools = openai_tools_payload(tools)
+            if openai_tools:
+                payload["tools"] = openai_tools
+            payload.update({k: v for k, v in kwargs.items() if v is not None})
+            response = client.chat.completions.create(**payload)
+            choice = response.choices[0]
+            text = (choice.message.content or "").strip()
+            usage: dict[str, Any] = {}
+            if response.usage:
+                usage = {
+                    "prompt_tokens": response.usage.prompt_tokens,
+                    "completion_tokens": response.usage.completion_tokens,
+                    "total_tokens": response.usage.total_tokens,
+                }
+            return CompletionResult(
+                text=text,
+                model=model,
+                raw=response,
+                usage=usage,
+                tool_calls=tool_calls_from_openai_message(choice.message),
+            )
+        except LLMError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            raise LLMError(f"OpenAI request failed: {exc}") from exc

readyagents/llm/registry.py

@@ -0,0 +1,112 @@
+"""Resolve an LLM provider from settings / model ref."""
+
+from __future__ import annotations
+
+from readyagents.config import Settings, get_settings, require_api_key
+from readyagents.errors import LLMError
+from readyagents.llm.anthropic_provider import AnthropicProvider
+from readyagents.llm.base import LLMProvider, parse_model_ref
+from readyagents.llm.openai_compat import OpenAICompatProvider
+from readyagents.llm.openai_provider import OpenAIProvider
+from readyagents.logging import get_logger
+
+log = get_logger("llm")
+
+_COMPAT_NAMES = {"openai-compat", "openai_compat", "compat", "groq", "ollama"}
+
+# Documented defaults from .env.example / docs/configuration.md
+_FALLBACK_MODELS = {
+    "openai": "gpt-4o-mini",
+    "anthropic": "claude-sonnet-4-5",
+    "openai-compat": "llama-3.1-8b-instant",
+    "groq": "llama-3.1-8b-instant",
+    "ollama": "llama3",
+}
+
+
+def _has_key(settings: Settings, provider_name: str, secrets: object = None) -> bool:
+    from readyagents.secrets import secret_for_provider
+
+    if provider_name == "openai":
+        name = "openai"
+    elif provider_name == "anthropic":
+        name = "anthropic"
+    elif provider_name in _COMPAT_NAMES:
+        name = "openai-compat"
+    else:
+        return False
+    return bool(secret_for_provider(name, settings=settings, secrets=secrets))
+
+
+def _implicit_fallback_ref(settings: Settings, secrets: object = None) -> str | None:
+    """First provider that actually has a key. None if BYOK is empty."""
+    from readyagents.secrets import secret_for_provider
+
+    if secret_for_provider("openai", settings=settings, secrets=secrets):
+        return f"openai:{_FALLBACK_MODELS['openai']}"
+    if secret_for_provider("anthropic", settings=settings, secrets=secrets):
+        return f"anthropic:{_FALLBACK_MODELS['anthropic']}"
+    if secret_for_provider("openai-compat", settings=settings, secrets=secrets):
+        if settings.openai_compat_base_url:
+            return f"openai-compat:{_FALLBACK_MODELS['openai-compat']}"
+        return f"groq:{_FALLBACK_MODELS['groq']}"
+    return None
+
+
+def get_provider(
+    model_ref: str | None = None,
+    *,
+    settings: Settings | None = None,
+    implicit: bool = False,
+    secrets: object = None,
+) -> tuple[LLMProvider, str]:
+    """Return `(provider, model_id)` for a `provider:model` string.
+
+    When ``implicit`` is true (agent node has no ``model:``), a missing key
+    for the default provider falls back to whichever BYOK key is set.
+    An explicit model ref never falls back.
+    """
+    settings = settings or get_settings()
+    ref = model_ref or settings.default_model
+    provider_name, model_id = parse_model_ref(ref)
+
+    if implicit and not _has_key(settings, provider_name, secrets):
+        fallback = _implicit_fallback_ref(settings, secrets)
+        if fallback:
+            new_provider, new_model = parse_model_ref(fallback)
+            log.info(
+                "No API key for default provider '%s'; using %s:%s",
+                provider_name,
+                new_provider,
+                new_model,
+            )
+            provider_name, model_id = new_provider, new_model
+
+    if provider_name == "openai":
+        key = require_api_key("openai", settings, secrets=secrets)
+        return OpenAIProvider(key), model_id
+
+    if provider_name == "anthropic":
+        key = require_api_key("anthropic", settings, secrets=secrets)
+        return AnthropicProvider(key), model_id
+
+    if provider_name in _COMPAT_NAMES:
+        key = require_api_key("openai-compat", settings, secrets=secrets)
+        base = settings.openai_compat_base_url
+        if not base:
+            if provider_name == "groq":
+                base = "https://api.groq.com/openai/v1"
+            elif provider_name == "ollama":
+                base = "http://127.0.0.1:11434/v1"
+            else:
+                raise LLMError(
+                    "OpenAI-compatible provider requires OPENAI_COMPAT_BASE_URL "
+                    "(for example https://api.groq.com/openai/v1 or http://127.0.0.1:11434/v1)."
+                )
+        api_key = key or "not-needed"
+        return OpenAICompatProvider(api_key, base_url=base), model_id
+
+    raise LLMError(
+        f"Unknown LLM provider '{provider_name}'. "
+        "Use openai, anthropic, or openai-compat (Groq/Ollama)."
+    )

readyagents/llm/resilience.py

@@ -0,0 +1,179 @@
+"""Budget, model fallback, circuit breaker, and token-cost helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, NoReturn
+
+from readyagents.errors import BudgetExceeded, CircuitOpen, LLMError
+from readyagents.llm.base import parse_model_ref
+from readyagents.logging import get_logger
+
+log = get_logger("llm.resilience")
+
+# USD per million tokens (prompt, completion). Approximate public list prices.
+_RATES_PER_MILLION: dict[str, tuple[float, float]] = {
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4o": (2.50, 10.00),
+    "claude-sonnet-4-5": (3.00, 15.00),
+    "claude-3-5-sonnet": (3.00, 15.00),
+    "llama-3.1-8b-instant": (0.05, 0.08),
+    "default": (0.15, 0.60),
+}
+
+
+def cost_micros(
+    model: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    *,
+    rates: Mapping[str, tuple[float, float]] | None = None,
+) -> int:
+    """USD cost as integer millionths of a dollar (exact to sum)."""
+    table = rates or _RATES_PER_MILLION
+    key = (model or "").split(":")[-1].strip() or "default"
+    prompt_rate, completion_rate = table.get(key) or table.get("default") or (0.15, 0.60)
+    usd = (prompt_tokens / 1_000_000) * prompt_rate + (
+        completion_tokens / 1_000_000
+    ) * completion_rate
+    return int(round(usd * 1_000_000))
+
+
+def normalize_usage(raw: Mapping[str, Any] | None, *, model: str = "") -> dict[str, int]:
+    data = dict(raw or {})
+    prompt_raw = data.get("prompt_tokens")
+    if prompt_raw is None:
+        prompt_raw = data.get("input_tokens")
+    prompt = _as_int(prompt_raw)
+    completion = _as_int(
+        data.get("completion_tokens")
+        if data.get("completion_tokens") is not None
+        else data.get("output_tokens")
+    )
+    total = _as_int(data.get("total_tokens")) or (prompt + completion)
+    micros = _as_int(data.get("cost_micros"))
+    if micros == 0 and (prompt or completion):
+        micros = cost_micros(model, prompt, completion)
+    out = {
+        "prompt_tokens": prompt,
+        "completion_tokens": completion,
+        "total_tokens": total,
+        "cost_micros": micros,
+    }
+    extra = _as_int(data.get("estimated_tokens"))
+    if extra:
+        out["estimated_tokens"] = extra
+    hits = _as_int(data.get("cache_hits"))
+    if hits:
+        out["cache_hits"] = hits
+    return out
+
+
+def _as_int(raw: Any) -> int:
+    if raw is None:
+        return 0
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return 0
+
+
+def usage_nonzero(usage: Mapping[str, int]) -> bool:
+    return any(int(v) for v in usage.values())
+
+
+class CircuitBreaker:
+    """Process-local breaker keyed by model ref. Not distributed."""
+
+    def __init__(
+        self,
+        *,
+        failure_threshold: int = 3,
+        cooldown_seconds: float = 60.0,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        import time
+
+        self.failure_threshold = max(1, int(failure_threshold))
+        self.cooldown_seconds = max(0.0, float(cooldown_seconds))
+        self._clock = clock or time.monotonic
+        self._fail_count: dict[str, int] = {}
+        self._open_until: dict[str, float] = {}
+
+    def allow(self, model: str) -> bool:
+        until = self._open_until.get(model)
+        if until is None:
+            return True
+        if self._clock() >= until:
+            self._open_until.pop(model, None)
+            self._fail_count[model] = 0
+            return True
+        return False
+
+    def record_success(self, model: str) -> None:
+        self._fail_count[model] = 0
+        self._open_until.pop(model, None)
+
+    def record_failure(self, model: str) -> None:
+        n = self._fail_count.get(model, 0) + 1
+        self._fail_count[model] = n
+        if n >= self.failure_threshold:
+            self._open_until[model] = self._clock() + self.cooldown_seconds
+
+    def is_open(self, model: str) -> bool:
+        return not self.allow(model)
+
+
+def model_candidates(
+    primary: str | None,
+    *fallback_groups: Sequence[str] | None,
+) -> list[str]:
+    seen: list[str] = []
+    for group in ((primary,) if primary else (), *(fallback_groups or ())):
+        if not group:
+            continue
+        for item in group:
+            ref = str(item).strip()
+            if ref and ref not in seen:
+                seen.append(ref)
+    return seen
+
+
+def model_id_for(ref: str) -> str:
+    if not ref:
+        return "mock"
+    if ":" in ref:
+        return parse_model_ref(ref)[1]
+    return ref
+
+
+def check_budget(
+    usage: Mapping[str, int],
+    *,
+    max_tokens: int | None = None,
+    max_cost_micros: int | None = None,
+) -> None:
+    tokens = int(usage.get("total_tokens") or 0) + int(usage.get("estimated_tokens") or 0)
+    if max_tokens is not None and tokens >= max_tokens:
+        raise BudgetExceeded("tokens", tokens, max_tokens)
+    cost = int(usage.get("cost_micros") or 0)
+    if max_cost_micros is not None and cost >= max_cost_micros:
+        raise BudgetExceeded("cost_micros", cost, max_cost_micros)
+
+
+def usd_to_micros(value: float | int | None) -> int | None:
+    if value is None:
+        return None
+    return int(round(float(value) * 1_000_000))
+
+
+def raise_exhausted(
+    tried: Sequence[str], skipped: Sequence[str], last: BaseException | None
+) -> NoReturn:
+    if skipped and not tried:
+        raise CircuitOpen(skipped[0])
+    if last is not None:
+        raise last
+    if skipped:
+        raise CircuitOpen(skipped[0])
+    raise LLMError("No LLM model was available")

readyagents/llm/tool_calls.py

@@ -0,0 +1,286 @@
+"""Pure mapping between vendor tool-call payloads and engine ToolCall objects."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Any
+
+from readyagents.llm.base import Message, ToolCall
+
+
+def parse_json_arguments(raw: Any) -> dict[str, Any]:
+    if raw is None:
+        return {}
+    if isinstance(raw, dict):
+        return dict(raw)
+    if isinstance(raw, str):
+        stripped = raw.strip()
+        if not stripped:
+            return {}
+        try:
+            parsed = json.loads(stripped)
+        except json.JSONDecodeError:
+            return {"_raw": raw}
+        if isinstance(parsed, dict):
+            return parsed
+        return {"value": parsed}
+    return {"value": raw}
+
+
+def spec_from_tool(tool: Any) -> dict[str, Any]:
+    raw = getattr(tool, "schema", None)
+    if isinstance(raw, dict) and raw:
+        schema = dict(raw)
+    else:
+        schema = {"type": "object", "properties": {}}
+    return {
+        "name": str(getattr(tool, "name", "")),
+        "description": str(getattr(tool, "description", "") or ""),
+        "schema": schema,
+    }
+
+
+def openai_tools_payload(tools: Sequence[dict[str, Any]] | None) -> list[dict[str, Any]] | None:
+    if not tools:
+        return None
+    out: list[dict[str, Any]] = []
+    for spec in tools:
+        if spec.get("type") == "function" and isinstance(spec.get("function"), dict):
+            out.append(dict(spec))
+            continue
+        name = spec.get("name")
+        if not name:
+            fn = spec.get("function") if isinstance(spec.get("function"), dict) else {}
+            name = fn.get("name")
+            if not name:
+                continue
+            out.append(
+                {
+                    "type": "function",
+                    "function": {
+                        "name": name,
+                        "description": fn.get("description") or spec.get("description") or "",
+                        "parameters": fn.get("parameters")
+                        or spec.get("schema")
+                        or {"type": "object", "properties": {}},
+                    },
+                }
+            )
+            continue
+        schema = (
+            spec.get("schema") or spec.get("parameters") or {"type": "object", "properties": {}}
+        )
+        out.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": name,
+                    "description": spec.get("description") or "",
+                    "parameters": schema,
+                },
+            }
+        )
+    return out or None
+
+
+def anthropic_tools_payload(tools: Sequence[dict[str, Any]] | None) -> list[dict[str, Any]] | None:
+    if not tools:
+        return None
+    out: list[dict[str, Any]] = []
+    for spec in tools:
+        if spec.get("input_schema") and spec.get("name") and spec.get("type") != "function":
+            out.append(
+                {
+                    "name": spec["name"],
+                    "description": spec.get("description") or "",
+                    "input_schema": spec["input_schema"],
+                }
+            )
+            continue
+        if spec.get("type") == "function":
+            fn = spec.get("function") if isinstance(spec.get("function"), dict) else {}
+            name = fn.get("name")
+            if not name:
+                continue
+            out.append(
+                {
+                    "name": name,
+                    "description": fn.get("description") or spec.get("description") or "",
+                    "input_schema": fn.get("parameters")
+                    or spec.get("schema")
+                    or {"type": "object", "properties": {}},
+                }
+            )
+            continue
+        name = spec.get("name")
+        if not name:
+            continue
+        out.append(
+            {
+                "name": name,
+                "description": spec.get("description") or "",
+                "input_schema": spec.get("schema")
+                or spec.get("parameters")
+                or {"type": "object", "properties": {}},
+            }
+        )
+    return out or None
+
+
+def tool_calls_from_openai_message(message: Any) -> list[ToolCall]:
+    raw_calls = getattr(message, "tool_calls", None)
+    if raw_calls is None and isinstance(message, dict):
+        raw_calls = message.get("tool_calls")
+    if not raw_calls:
+        return []
+    out: list[ToolCall] = []
+    for index, call in enumerate(raw_calls):
+        if isinstance(call, dict):
+            cid = str(call.get("id") or f"call_{index}")
+            fn = call.get("function") if isinstance(call.get("function"), dict) else {}
+            name = str(fn.get("name") or call.get("name") or "")
+            args = parse_json_arguments(fn.get("arguments") if fn else call.get("arguments"))
+        else:
+            cid = str(getattr(call, "id", None) or f"call_{index}")
+            fn = getattr(call, "function", None)
+            name = str(getattr(fn, "name", None) or getattr(call, "name", "") or "")
+            args_raw = (
+                getattr(fn, "arguments", None)
+                if fn is not None
+                else getattr(call, "arguments", None)
+            )
+            args = parse_json_arguments(args_raw)
+        if name:
+            out.append(ToolCall(id=cid, name=name, arguments=args))
+    return out
+
+
+def tool_calls_from_anthropic_content(blocks: Any) -> list[ToolCall]:
+    if not blocks:
+        return []
+    out: list[ToolCall] = []
+    for index, block in enumerate(blocks):
+        if isinstance(block, dict):
+            btype = block.get("type")
+            name = block.get("name")
+            cid = block.get("id")
+            inp = block.get("input")
+        else:
+            btype = getattr(block, "type", None)
+            name = getattr(block, "name", None)
+            cid = getattr(block, "id", None)
+            inp = getattr(block, "input", None)
+        if str(btype) != "tool_use" or not name:
+            continue
+        out.append(
+            ToolCall(
+                id=str(cid or f"call_{index}"),
+                name=str(name),
+                arguments=parse_json_arguments(inp),
+            )
+        )
+    return out
+
+
+def messages_to_openai(messages: Sequence[Message]) -> list[dict[str, Any]]:
+    payload: list[dict[str, Any]] = []
+    for message in messages:
+        if message.role == "tool":
+            row: dict[str, Any] = {
+                "role": "tool",
+                "content": message.content or "",
+                "tool_call_id": message.tool_call_id or "",
+            }
+            if message.name:
+                row["name"] = message.name
+            payload.append(row)
+            continue
+        row = {"role": message.role, "content": message.content}
+        if message.tool_calls:
+            row["tool_calls"] = [
+                {
+                    "id": call.id,
+                    "type": "function",
+                    "function": {
+                        "name": call.name,
+                        "arguments": json.dumps(call.arguments, ensure_ascii=False),
+                    },
+                }
+                for call in message.tool_calls
+            ]
+        payload.append(row)
+    return payload
+
+
+def messages_to_anthropic(messages: Sequence[Message]) -> tuple[str, list[dict[str, Any]]]:
+    system_parts: list[str] = []
+    chat: list[dict[str, Any]] = []
+    pending: list[dict[str, Any]] = []
+
+    def flush_tool_results() -> None:
+        if pending:
+            chat.append({"role": "user", "content": list(pending)})
+            pending.clear()
+
+    for message in messages:
+        if message.role == "system":
+            if message.content:
+                system_parts.append(message.content)
+            continue
+        if message.role == "tool":
+            pending.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": message.tool_call_id or "",
+                    "content": message.content or "",
+                }
+            )
+            continue
+        flush_tool_results()
+        if message.role == "assistant" and message.tool_calls:
+            blocks: list[dict[str, Any]] = []
+            if message.content:
+                blocks.append({"type": "text", "text": message.content})
+            for call in message.tool_calls:
+                blocks.append(
+                    {
+                        "type": "tool_use",
+                        "id": call.id,
+                        "name": call.name,
+                        "input": call.arguments,
+                    }
+                )
+            chat.append({"role": "assistant", "content": blocks})
+        else:
+            role = "assistant" if message.role == "assistant" else "user"
+            chat.append({"role": role, "content": message.content})
+    flush_tool_results()
+    return "\n".join(system_parts).strip(), chat
+
+
+def tool_calls_to_json(calls: Sequence[ToolCall] | None) -> list[dict[str, Any]]:
+    return [
+        {"id": call.id, "name": call.name, "arguments": dict(call.arguments)}
+        for call in (calls or [])
+    ]
+
+
+def tool_calls_from_json(raw: Any) -> list[ToolCall]:
+    if not isinstance(raw, list):
+        return []
+    out: list[ToolCall] = []
+    for index, item in enumerate(raw):
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "")
+        if not name:
+            continue
+        out.append(
+            ToolCall(
+                id=str(item.get("id") or f"call_{index}"),
+                name=name,
+                arguments=parse_json_arguments(item.get("arguments")),
+            )
+        )
+    return out