parcha-agentrun 0.2.0__py3-none-any.whl

agentrun/__init__.py

@@ -0,0 +1,129 @@
+"""AgentRun Python SDK.
+
+Quick start::
+
+    from agentrun import Agent
+
+    agent = Agent(name="Verifier", instructions="Verify the company and cite evidence.")
+    run = agent.run("Verify acme.example")
+    result = agent.wait(run.id)
+    print(result.status, result.markdown)
+
+``Agent`` reads ``AGENTRUN_API_KEY`` from the environment. Use ``AgentRun``
+for direct access to every resource and ``AsyncAgent`` / ``AsyncAgentRun``
+under asyncio or trio.
+"""
+
+from ._batch import BatchCSV, parse_batch_csv
+from ._version import __version__
+from .agent import Agent, AsyncAgent, Skill
+from .client import AgentRun, AsyncAgentRun
+from .errors import (
+    AgentRunError,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BuildError,
+    ConflictError,
+    InternalServerError,
+    InvalidResponseError,
+    NotFoundError,
+    PermissionDeniedError,
+    PollTimeoutError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnprocessableEntityError,
+)
+from .models import (
+    AgentBuild,
+    AgentRecord,
+    AgentSummary,
+    Artifact,
+    Batch,
+    BatchResults,
+    BatchRow,
+    BatchStatus,
+    Campaign,
+    CampaignPortfolio,
+    CancelResult,
+    Effort,
+    InputField,
+    Integration,
+    IntegrationList,
+    Loop,
+    LoopCadence,
+    LoopCreated,
+    LoopDetail,
+    LoopRun,
+    LoopRunNow,
+    Page,
+    Report,
+    RetryResult,
+    Run,
+    RunStatus,
+    RunSummary,
+    SkillContent,
+    SkillList,
+    SkillRecord,
+    SkillSummary,
+    Usage,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "Agent",
+    "AgentBuild",
+    "AgentRecord",
+    "AgentRun",
+    "AgentRunError",
+    "AgentSummary",
+    "Artifact",
+    "AsyncAgent",
+    "AsyncAgentRun",
+    "AuthenticationError",
+    "Batch",
+    "BatchCSV",
+    "BatchResults",
+    "BatchRow",
+    "BatchStatus",
+    "BuildError",
+    "Campaign",
+    "CampaignPortfolio",
+    "CancelResult",
+    "ConflictError",
+    "Effort",
+    "InputField",
+    "Integration",
+    "IntegrationList",
+    "InternalServerError",
+    "InvalidResponseError",
+    "Loop",
+    "LoopCadence",
+    "LoopCreated",
+    "LoopDetail",
+    "LoopRun",
+    "LoopRunNow",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "PollTimeoutError",
+    "RateLimitError",
+    "Report",
+    "RetryResult",
+    "Run",
+    "RunStatus",
+    "RunSummary",
+    "ServiceUnavailableError",
+    "Skill",
+    "SkillContent",
+    "SkillList",
+    "SkillRecord",
+    "SkillSummary",
+    "UnprocessableEntityError",
+    "Usage",
+    "__version__",
+    "parse_batch_csv",
+]

agentrun/_batch.py

@@ -0,0 +1,86 @@
+"""Validate batch inputs and parse CSV files into questions plus row data."""
+
+from __future__ import annotations
+
+import csv
+import io
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO, Any
+
+MAX_INPUTS = 100
+MAX_INPUT_CHARS = 8_000
+MAX_CSV_BYTES = 1_000_000
+
+
+@dataclass(frozen=True)
+class BatchCSV:
+    """A CSV source for a batch. One column holds the input for each row.
+
+    ``source`` may be CSV text, UTF-8 bytes, a path, or an open file. The other
+    columns are sent as ``row_data`` and come back with each result.
+    """
+
+    source: str | bytes | Path | IO[str] | IO[bytes]
+    input_column: str = "input"
+
+    def text(self) -> str:
+        raw: str | bytes
+        if isinstance(self.source, Path):
+            raw = self.source.read_bytes()
+        elif isinstance(self.source, (str, bytes)):
+            raw = self.source
+        else:
+            raw = self.source.read()
+        if isinstance(raw, bytes):
+            if len(raw) > MAX_CSV_BYTES:
+                raise ValueError("CSV must be at most 1 MB.")
+            return raw.decode("utf-8-sig")
+        if len(raw.encode("utf-8")) > MAX_CSV_BYTES:
+            raise ValueError("CSV must be at most 1 MB.")
+        return raw.lstrip("")
+
+
+def parse_batch_csv(text: str, input_column: str) -> tuple[list[str], list[dict[str, str]]]:
+    """Return ``(questions, rows)`` from CSV text. Rows that are entirely blank are skipped."""
+    reader = csv.reader(io.StringIO(text.lstrip("\ufeff"), newline=""))
+    try:
+        headers = next(reader)
+    except StopIteration:
+        raise ValueError("CSV is empty.") from None
+    if any(not h.strip() for h in headers) or len(set(headers)) != len(headers):
+        raise ValueError("CSV headers must be unique and non-blank.")
+    if input_column not in headers:
+        raise ValueError(f"CSV has no {input_column!r} column. Headers are: {', '.join(headers)}.")
+    rows: list[dict[str, str]] = []
+    for values in reader:
+        if not any(v.strip() for v in values):
+            continue
+        if len(values) != len(headers):
+            raise ValueError(
+                f"CSV row {len(rows) + 2} has {len(values)} cells but there are {len(headers)} headers."
+            )
+        rows.append(dict(zip(headers, values, strict=True)))
+        if len(rows) > MAX_INPUTS:
+            raise ValueError(f"A batch accepts at most {MAX_INPUTS} inputs.")
+    return [row[input_column] for row in rows], rows
+
+
+def prepare_inputs(inputs: str | Sequence[str] | BatchCSV) -> tuple[list[str], list[dict[str, Any]] | None]:
+    """Normalise anything ``batch``/``loop`` accepts into ``(questions, rows)`` and enforce limits."""
+    rows: list[dict[str, Any]] | None = None
+    if isinstance(inputs, BatchCSV):
+        questions, rows = parse_batch_csv(inputs.text(), inputs.input_column)
+    elif isinstance(inputs, str):
+        questions = [inputs]
+    else:
+        questions = list(inputs)
+    if not 1 <= len(questions) <= MAX_INPUTS:
+        raise ValueError(f"Provide between 1 and {MAX_INPUTS} inputs.")
+    for index, value in enumerate(questions):
+        if not isinstance(value, str) or not value.strip():  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ValueError(f"Input {index} is blank.")
+        if len(value) > MAX_INPUT_CHARS:
+            raise ValueError(f"Input {index} is longer than {MAX_INPUT_CHARS} characters.")
+    return questions, rows

agentrun/_http.py

@@ -0,0 +1,184 @@
+"""HTTP plumbing shared by the sync and async clients.
+
+An ``Op`` describes one API call without performing it. The transports send
+an ``Op`` and decode the response into the record type it names. Nothing here
+retries, follows redirects, or logs the API key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+from urllib.parse import urlsplit
+
+import httpx2
+from pydantic import BaseModel, ValidationError
+
+from ._version import __version__
+from .errors import APIConnectionError, APITimeoutError, InvalidResponseError, error_for_status
+from .models import Artifact
+
+DEFAULT_BASE_URL = "https://api.grep.ai/api/v2"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = f"agentrun-python/{__version__}"
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class Op(Generic[T]):
+    """One API call: where to send it, what to send, and what comes back."""
+
+    method: str
+    path: str
+    model: type[T]
+    params: Mapping[str, Any] | None = None
+    json: Mapping[str, Any] | None = None
+    idempotency_key: str | None = None
+    raw: bool = False
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: str
+    base_url: str
+    timeout: float
+
+    @classmethod
+    def resolve(cls, api_key: str | None, base_url: str | None, timeout: float | None) -> Config:
+        """Fill missing values from ``AGENTRUN_API_KEY`` and ``AGENTRUN_BASE_URL``, then validate."""
+        key = api_key if api_key is not None else os.environ.get("AGENTRUN_API_KEY", "")
+        if not key.strip():
+            raise ValueError("An API key is required. Pass api_key= or set AGENTRUN_API_KEY.")
+        url = base_url if base_url is not None else os.environ.get("AGENTRUN_BASE_URL") or DEFAULT_BASE_URL
+        seconds = DEFAULT_TIMEOUT if timeout is None else timeout
+        if seconds <= 0:
+            raise ValueError("timeout must be a positive number of seconds.")
+        return cls(api_key=key, base_url=_validate_base_url(url), timeout=seconds)
+
+
+def _validate_base_url(value: str) -> str:
+    parts = urlsplit(value)
+    if parts.username or parts.password or parts.query or parts.fragment or not parts.hostname:
+        raise ValueError("base_url must be a plain URL with no credentials, query string, or fragment.")
+    if parts.scheme != "https" and not (parts.scheme == "http" and parts.hostname in _LOCAL_HOSTS):
+        raise ValueError("base_url must use HTTPS. Plain HTTP is only allowed for localhost.")
+    return value.rstrip("/")
+
+
+def _clean(values: Mapping[str, Any]) -> dict[str, Any]:
+    """Drop ``None`` so optional fields are omitted instead of sent as null."""
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def build_kwargs(op: Op[Any], config: Config) -> dict[str, Any]:
+    headers = {
+        "Authorization": f"Bearer {config.api_key}",
+        "Accept": "application/json, */*;q=0.5",
+        "User-Agent": USER_AGENT,
+    }
+    if op.idempotency_key:
+        headers["Idempotency-Key"] = op.idempotency_key
+    kwargs: dict[str, Any] = {
+        "method": op.method,
+        "url": op.path,
+        "headers": headers,
+        "params": _clean(op.params or {}),
+    }
+    if op.json is not None:
+        kwargs["json"] = _clean(op.json)
+    return kwargs
+
+
+def decode(op: Op[T], response: httpx2.Response) -> T:
+    """Turn an HTTP response into ``op.model`` or raise the matching SDK error."""
+    request_id = response.headers.get("x-request-id")
+    if response.status_code >= 400:
+        raise error_for_status(response.status_code, _body(response), request_id)
+    if op.raw:
+        artifact = Artifact(
+            content=response.content,
+            content_type=response.headers.get("content-type"),
+            filename=_filename(response.headers.get("content-disposition")),
+        )
+        return artifact  # type: ignore[return-value]
+    body = _body(response)
+    if not isinstance(body, dict):
+        raise InvalidResponseError(
+            f"Expected a JSON object from {op.method} {op.path} but got "
+            f"{response.headers.get('content-type', 'no content type')} (HTTP {response.status_code}). "
+            "Check base_url points at the AgentRun API."
+        )
+    try:
+        return op.model.model_validate(body)
+    except ValidationError as error:
+        raise InvalidResponseError(f"{op.method} {op.path} returned an unexpected shape: {error}") from None
+
+
+def _body(response: httpx2.Response) -> Any:
+    try:
+        return response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return response.text
+
+
+def _filename(disposition: str | None) -> str | None:
+    if not disposition:
+        return None
+    for part in disposition.split(";"):
+        part = part.strip()
+        if part.lower().startswith("filename="):
+            return part[len("filename=") :].strip('"')
+    return None
+
+
+def wrap_transport_error(error: httpx2.HTTPError) -> APIConnectionError:
+    if isinstance(error, httpx2.TimeoutException):
+        return APITimeoutError(f"Request timed out: {error.__class__.__name__}")
+    return APIConnectionError(f"Could not reach the AgentRun API: {error.__class__.__name__}: {error}")
+
+
+class SyncTransport:
+    def __init__(self, config: Config, transport: httpx2.BaseTransport | None = None) -> None:
+        self._client = httpx2.Client(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            follow_redirects=False,
+            transport=transport,
+        )
+        self._config = config
+
+    def send(self, op: Op[T]) -> T:
+        try:
+            response = self._client.request(**build_kwargs(op, self._config))
+        except httpx2.HTTPError as error:
+            raise wrap_transport_error(error) from None
+        return decode(op, response)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport:
+    def __init__(self, config: Config, transport: httpx2.AsyncBaseTransport | None = None) -> None:
+        self._client = httpx2.AsyncClient(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            follow_redirects=False,
+            transport=transport,
+        )
+        self._config = config
+
+    async def send(self, op: Op[T]) -> T:
+        try:
+            response = await self._client.request(**build_kwargs(op, self._config))
+        except httpx2.HTTPError as error:
+            raise wrap_transport_error(error) from None
+        return decode(op, response)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()