readyagentsdev 0.8.2__py3-none-any.whl

readyagents/config.py

@@ -0,0 +1,264 @@
+"""BYOK settings: environment, then `.env`, then `.env-ai`."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from pydantic import AliasChoices, Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from readyagents.errors import ConfigError, LLMError
+
+DEFAULT_MCP_TOKEN_ENV = "READYAGENTS_MCP_TOKEN"
+MAX_CONCURRENT_RUNS_HARD = 32
+MAX_PENDING_RUNS_HARD = 256
+MAX_HTTP_BODY_BYTES = 1_048_576
+LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "0:0:0:0:0:0:0:1"})
+
+
+def _env_files() -> tuple[Path, ...]:
+    """Lowest-priority first: `.env-ai` then `.env`. OS env still wins."""
+    cwd = Path.cwd()
+    files: list[Path] = []
+    for name in (".env-ai", ".env"):
+        path = cwd / name
+        if path.is_file():
+            files.append(path)
+    return tuple(files)
+
+
+class Settings(BaseSettings):
+    """Runtime settings. Secrets are never logged by this class."""
+
+    model_config = SettingsConfigDict(
+        extra="ignore",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        populate_by_name=True,
+    )
+
+    openai_api_key: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("OPENAI_API_KEY", "READYAGENTS_OPENAI_API_KEY"),
+    )
+    anthropic_api_key: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("ANTHROPIC_API_KEY", "READYAGENTS_ANTHROPIC_API_KEY"),
+    )
+    openai_compat_api_key: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "OPENAI_COMPAT_API_KEY",
+            "READYAGENTS_OPENAI_COMPAT_API_KEY",
+            "GROQ_API_KEY",
+        ),
+    )
+    openai_compat_base_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "OPENAI_COMPAT_BASE_URL",
+            "READYAGENTS_OPENAI_COMPAT_BASE_URL",
+        ),
+    )
+    default_model: str = Field(
+        default="openai:gpt-4o-mini",
+        validation_alias=AliasChoices("READYAGENTS_DEFAULT_MODEL", "DEFAULT_MODEL"),
+    )
+    allow_http: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("READYAGENTS_ALLOW_HTTP"),
+    )
+    workspace: Path | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_WORKSPACE"),
+    )
+    home: Path = Field(
+        default=Path(".readyagents"),
+        validation_alias=AliasChoices("READYAGENTS_HOME"),
+    )
+    log_level: str = Field(
+        default="INFO",
+        validation_alias=AliasChoices("READYAGENTS_LOG_LEVEL"),
+    )
+    log_format: str = Field(
+        default="text",
+        validation_alias=AliasChoices("READYAGENTS_LOG_FORMAT"),
+    )
+    max_tokens: int | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_MAX_TOKENS"),
+    )
+    max_cost_usd: float | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_MAX_COST_USD"),
+    )
+    fallback_models: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_FALLBACK_MODELS"),
+    )
+    circuit_failure_threshold: int = Field(
+        default=3,
+        validation_alias=AliasChoices("READYAGENTS_CIRCUIT_FAILURE_THRESHOLD"),
+    )
+    circuit_cooldown_seconds: float = Field(
+        default=60.0,
+        validation_alias=AliasChoices("READYAGENTS_CIRCUIT_COOLDOWN_SECONDS"),
+    )
+    llm_cache: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("READYAGENTS_LLM_CACHE"),
+    )
+    redact: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("READYAGENTS_REDACT"),
+    )
+    redact_literals: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_REDACT_LITERALS"),
+    )
+    redact_patterns: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_REDACT_PATTERNS"),
+    )
+    actor: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_ACTOR"),
+    )
+    pause_notify_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("READYAGENTS_PAUSE_NOTIFY_URL"),
+    )
+    mcp_http_host: str = Field(
+        default="127.0.0.1",
+        validation_alias=AliasChoices("READYAGENTS_MCP_HTTP_HOST"),
+    )
+    mcp_http_port: int = Field(
+        default=8765,
+        ge=1,
+        le=65535,
+        validation_alias=AliasChoices("READYAGENTS_MCP_HTTP_PORT"),
+    )
+    mcp_max_concurrent_runs: int = Field(
+        default=4,
+        ge=1,
+        validation_alias=AliasChoices("READYAGENTS_MCP_MAX_CONCURRENT_RUNS"),
+    )
+    mcp_max_pending_runs: int = Field(
+        default=32,
+        ge=1,
+        validation_alias=AliasChoices("READYAGENTS_MCP_MAX_PENDING_RUNS"),
+    )
+
+    def fallback_model_list(self) -> list[str]:
+        if not self.fallback_models:
+            return []
+        return [part.strip() for part in self.fallback_models.split(",") if part.strip()]
+
+    def redact_literal_list(self) -> list[str]:
+        if not self.redact_literals:
+            return []
+        return [part.strip() for part in self.redact_literals.split(",") if part.strip()]
+
+    def redact_pattern_list(self) -> list[str]:
+        if not self.redact_patterns:
+            return []
+        return [part.strip() for part in self.redact_patterns.split(",") if part.strip()]
+
+    def cache_dir(self) -> Path:
+        return self.home_path() / "cache"
+
+    def audit_dir(self) -> Path:
+        return self.home_path() / "audit"
+
+    @field_validator("openai_api_key", "anthropic_api_key", "openai_compat_api_key", mode="before")
+    @classmethod
+    def _empty_to_none(cls, value: Any) -> Any:
+        if value is None:
+            return None
+        if isinstance(value, str) and not value.strip():
+            return None
+        return value
+
+    @field_validator("mcp_max_concurrent_runs", mode="after")
+    @classmethod
+    def _clamp_mcp_max_concurrent_runs(cls, value: int) -> int:
+        if value > MAX_CONCURRENT_RUNS_HARD:
+            return MAX_CONCURRENT_RUNS_HARD
+        return value
+
+    @field_validator("mcp_max_pending_runs", mode="after")
+    @classmethod
+    def _clamp_mcp_max_pending_runs(cls, value: int) -> int:
+        if value > MAX_PENDING_RUNS_HARD:
+            return MAX_PENDING_RUNS_HARD
+        return value
+
+    def workspace_path(self) -> Path:
+        return (self.workspace or Path.cwd()).expanduser().resolve()
+
+    def home_path(self) -> Path:
+        path = self.home
+        if not path.is_absolute():
+            path = Path.cwd() / path
+        return path.expanduser().resolve()
+
+    def runs_dir(self) -> Path:
+        return self.home_path() / "runs"
+
+    def api_key_for(self, provider: str) -> str | None:
+        provider = provider.lower()
+        if provider in {"openai"}:
+            return self.openai_api_key
+        if provider in {"anthropic"}:
+            return self.anthropic_api_key
+        if provider in {"openai-compat", "openai_compat", "compat", "groq", "ollama"}:
+            return self.openai_compat_api_key or self.openai_api_key
+        return None
+
+
+def load_settings(*, env_file: tuple[Path, ...] | None = None) -> Settings:
+    """Load settings from OS env, then `.env`, then `.env-ai`."""
+    files = env_file if env_file is not None else _env_files()
+    try:
+        return Settings(_env_file=files)  # type: ignore[call-arg]
+    except Exception as exc:  # noqa: BLE001
+        raise ConfigError(f"Failed to load settings: {exc}") from exc
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return load_settings()
+
+
+def clear_settings_cache() -> None:
+    get_settings.cache_clear()
+
+
+def require_api_key(
+    provider: str,
+    settings: Settings | None = None,
+    *,
+    secrets: Any = None,
+) -> str:
+    settings = settings or get_settings()
+    key = settings.api_key_for(provider)
+    if not key and secrets is not None:
+        from readyagents.secrets import secret_for_provider
+
+        key = secret_for_provider(provider, settings=None, secrets=secrets)
+    if key:
+        return key
+    hints = {
+        "openai": ("Set OPENAI_API_KEY or READYAGENTS_OPENAI_API_KEY (copy .env.example to .env)."),
+        "anthropic": (
+            "Set ANTHROPIC_API_KEY or READYAGENTS_ANTHROPIC_API_KEY (copy .env.example to .env)."
+        ),
+        "openai-compat": (
+            "Set OPENAI_COMPAT_API_KEY (and OPENAI_COMPAT_BASE_URL) "
+            "or OPENAI_API_KEY for a compatible endpoint."
+        ),
+    }
+    hint = hints.get(provider.lower(), f"Set an API key for provider '{provider}'.")
+    raise LLMError(f"No API key configured for provider '{provider}'. ReadyAgents is BYOK — {hint}")

readyagents/errors.py

@@ -0,0 +1,129 @@
+"""Typed errors for ReadyAgents Core."""
+
+from __future__ import annotations
+
+
+class ReadyAgentsError(Exception):
+    """Base error for all ReadyAgents failures."""
+
+    run_id: str | None = None
+    state: object | None = None
+
+
+class ConfigError(ReadyAgentsError):
+    """Invalid configuration, missing settings, or unreadable files."""
+
+
+class WorkflowError(ReadyAgentsError):
+    """Invalid workflow definition or graph execution problem."""
+
+
+class NodeError(ReadyAgentsError):
+    """A single node failed after retries / timeout."""
+
+    def __init__(self, node_id: str, message: str, *, cause: BaseException | None = None) -> None:
+        self.node_id = node_id
+        self.cause = cause
+        super().__init__(f"Node '{node_id}': {message}")
+
+
+class LLMError(ReadyAgentsError):
+    """LLM provider, model, or API-key failure."""
+
+
+class MCPError(ReadyAgentsError):
+    """MCP client or server failure."""
+
+
+class TemplateError(ReadyAgentsError):
+    """Template interpolation failed (missing variable or bad path)."""
+
+
+class ToolError(ReadyAgentsError):
+    """Builtin or MCP tool invocation failed."""
+
+
+class ApprovalRequired(ReadyAgentsError):
+    """An approval node is waiting for an explicit operator decision."""
+
+    def __init__(
+        self,
+        node_id: str,
+        run_id: str,
+        prompt: str,
+        *,
+        state: object | None = None,
+    ) -> None:
+        self.node_id = node_id
+        self.run_id = run_id
+        self.prompt = prompt
+        self.state = state
+        super().__init__(
+            f"Approval required at node '{node_id}' (run {run_id}). {prompt} "
+            f"Resume with: readyagents resume {run_id} --approve {node_id} "
+            f"(or --reject {node_id})"
+        )
+
+
+class BudgetExceeded(ReadyAgentsError):
+    """An LLM call was blocked because the run is over its token or cost budget."""
+
+    def __init__(self, kind: str, used: int, limit: int) -> None:
+        self.kind = kind
+        self.used = used
+        self.limit = limit
+        super().__init__(f"Budget exceeded: {kind} used={used} limit={limit}")
+
+
+class AuthorizationError(ReadyAgentsError):
+    """An RBAC hook denied run, resume, approve, or reject."""
+
+    def __init__(self, actor: str | None, action: str, resource: str) -> None:
+        self.actor = actor
+        self.action = action
+        self.resource = resource
+        who = actor if actor else "(anonymous)"
+        super().__init__(f"Actor '{who}' is not allowed to {action} '{resource}'")
+
+
+class StructuredOutputError(NodeError):
+    """An agent node's LLM output did not match its Pydantic/JSON schema."""
+
+
+class CircuitOpen(LLMError):
+    """A model is skipped because its circuit breaker is open."""
+
+    def __init__(self, model: str) -> None:
+        self.model = model
+        super().__init__(f"Circuit breaker open for model '{model}'")
+
+
+class CancellationRequested(ReadyAgentsError):
+    """Cooperative cancellation reached an engine safe point."""
+
+    def __init__(
+        self,
+        message: str = "Run cancellation requested",
+        *,
+        run_id: str | None = None,
+        reason: str | None = None,
+    ) -> None:
+        self.reason = reason
+        super().__init__(message)
+        self.run_id = run_id
+
+
+class RunConflict(ReadyAgentsError):
+    """Run cannot accept this mutation (wrong status, in-flight resume, idempotency mismatch)."""
+
+
+class HttpAuthError(MCPError):
+    """Missing or invalid HTTP bearer credentials."""
+
+
+class HttpRequestError(MCPError):
+    """Malformed HTTP extension request (bad JSON, unknown fields, bad id, limits)."""
+
+    def __init__(self, message: str, *, status_code: int = 400) -> None:
+        self.status_code = status_code
+        super().__init__(message)

readyagents/llm/__init__.py

@@ -0,0 +1,11 @@
+from readyagents.llm.base import CompletionResult, LLMProvider, Message, ToolCall, parse_model_ref
+from readyagents.llm.registry import get_provider
+
+__all__ = [
+    "CompletionResult",
+    "LLMProvider",
+    "Message",
+    "ToolCall",
+    "get_provider",
+    "parse_model_ref",
+]

readyagents/llm/anthropic_provider.py

@@ -0,0 +1,72 @@
+"""Anthropic Messages 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 (
+    anthropic_tools_payload,
+    messages_to_anthropic,
+    tool_calls_from_anthropic_content,
+)
+
+
+class AnthropicProvider:
+    name = "anthropic"
+
+    def __init__(self, api_key: str) -> None:
+        self._api_key = api_key
+
+    def complete(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> CompletionResult:
+        try:
+            from anthropic import Anthropic
+        except ImportError as exc:
+            raise LLMError(
+                "The Anthropic extra is not installed. Run: pip install 'readyagents[anthropic]'"
+            ) from exc
+        system, chat = messages_to_anthropic(messages)
+        if not chat:
+            raise LLMError("Anthropic requires at least one non-system message")
+        try:
+            client = Anthropic(api_key=self._api_key)
+            payload: dict[str, Any] = {"model": model, "messages": chat, "max_tokens": 4096}
+            if system:
+                payload["system"] = system
+            anth_tools = anthropic_tools_payload(tools)
+            if anth_tools:
+                payload["tools"] = anth_tools
+            payload.update({k: v for k, v in kwargs.items() if v is not None and k != "max_tokens"})
+            if kwargs.get("max_tokens") is not None:
+                payload["max_tokens"] = kwargs["max_tokens"]
+            response = client.messages.create(**payload)
+            parts = []
+            for block in response.content:
+                text = getattr(block, "text", None)
+                if text:
+                    parts.append(text)
+            usage: dict[str, Any] = {}
+            if getattr(response, "usage", None):
+                usage = {
+                    "input_tokens": getattr(response.usage, "input_tokens", None),
+                    "output_tokens": getattr(response.usage, "output_tokens", None),
+                }
+            return CompletionResult(
+                text="".join(parts).strip(),
+                model=model,
+                raw=response,
+                usage=usage,
+                tool_calls=tool_calls_from_anthropic_content(response.content),
+            )
+        except LLMError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            raise LLMError(f"Anthropic request failed: {exc}") from exc

readyagents/llm/base.py

@@ -0,0 +1,57 @@
+"""Thin LLM provider interface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+@dataclass
+class ToolCall:
+    """One model-requested tool invocation (id + name + JSON arguments)."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Message:
+    role: str
+    content: str
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str | None = None
+    name: str | None = None
+
+
+@dataclass
+class CompletionResult:
+    text: str
+    model: str
+    raw: Any = None
+    usage: dict[str, Any] = field(default_factory=dict)
+    tool_calls: list[ToolCall] = field(default_factory=list)
+
+
+class LLMProvider(Protocol):
+    name: str
+
+    def complete(
+        self,
+        messages: list[Message],
+        *,
+        model: str,
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> CompletionResult: ...
+
+
+def parse_model_ref(ref: str) -> tuple[str, str]:
+    """Split `provider:model` (or bare model → openai)."""
+    ref = ref.strip()
+    if not ref:
+        raise ValueError("Empty model reference")
+    if ":" in ref:
+        provider, model = ref.split(":", 1)
+        return provider.strip().lower(), model.strip()
+    return "openai", ref

readyagents/llm/cache.py

@@ -0,0 +1,86 @@
+"""Local, opt-in LLM response cache. File-backed, skippable, no network."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from readyagents.llm.base import CompletionResult, Message
+from readyagents.llm.tool_calls import tool_calls_from_json, tool_calls_to_json
+
+
+class LLMCache:
+    """Content-addressed completions under ``$READYAGENTS_HOME/cache/``."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root)
+        self.hits = 0
+        self.misses = 0
+
+    def key(
+        self,
+        model: str,
+        messages: list[Message],
+        tools: list[dict[str, Any]] | None = None,
+    ) -> str:
+        payload = {
+            "model": model,
+            "messages": [_message_payload(m) for m in messages],
+            "tools": list(tools or []),
+        }
+        blob = json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")
+        return hashlib.sha256(blob).hexdigest()
+
+    def get(self, key: str) -> CompletionResult | None:
+        path = self.root / f"{key}.json"
+        if not path.is_file():
+            self.misses += 1
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            self.misses += 1
+            return None
+        if not isinstance(data, dict) or "text" not in data:
+            self.misses += 1
+            return None
+        self.hits += 1
+        usage = data.get("usage") if isinstance(data.get("usage"), dict) else {}
+        return CompletionResult(
+            text=str(data.get("text") or ""),
+            model=str(data.get("model") or ""),
+            usage=dict(usage),
+            tool_calls=tool_calls_from_json(data.get("tool_calls")),
+        )
+
+    def put(self, key: str, result: CompletionResult) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        path = self.root / f"{key}.json"
+        tmp = self.root / f".{key}.{uuid4().hex}.tmp"
+        payload: dict[str, Any] = {
+            "text": result.text,
+            "model": result.model,
+            "usage": dict(result.usage or {}),
+            "tool_calls": tool_calls_to_json(result.tool_calls),
+        }
+        try:
+            tmp.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+            os.replace(tmp, path)
+        finally:
+            if tmp.exists():
+                tmp.unlink(missing_ok=True)
+
+
+def _message_payload(message: Message) -> dict[str, Any]:
+    row: dict[str, Any] = {"role": message.role, "content": message.content}
+    if message.tool_call_id:
+        row["tool_call_id"] = message.tool_call_id
+    if message.name:
+        row["name"] = message.name
+    if message.tool_calls:
+        row["tool_calls"] = tool_calls_to_json(message.tool_calls)
+    return row

readyagents/llm/openai_compat.py

@@ -0,0 +1,12 @@
+"""OpenAI-compatible endpoints (Groq, Ollama, Together, vLLM, …)."""
+
+from __future__ import annotations
+
+from readyagents.llm.openai_provider import OpenAIProvider
+
+
+class OpenAICompatProvider(OpenAIProvider):
+    name = "openai-compat"
+
+    def __init__(self, api_key: str, *, base_url: str) -> None:
+        super().__init__(api_key, base_url=base_url)