remuda 0.1.0__py3-none-any.whl

remuda/__init__.py

@@ -0,0 +1,128 @@
+"""remuda — bulk LLM inference over pools of free/cheap models.
+
+The herd of spare horses on a cattle drive: ride one until it tires, swap to
+the next. Public API surface lives here; internal module paths are not a
+contract.
+"""
+
+from remuda.api import JobRunOutcome, run, run_job_dir, run_sync
+from remuda.engine.plan import EngineError
+from remuda.engine.progress import ProgressEvent
+from remuda.engine.runner import RowResult, Runner
+from remuda.errors import RemudaError
+from remuda.inspection import (
+    CheckReport,
+    PreviewReport,
+    RenderedPrompt,
+    check_job_dir,
+    preview_job,
+)
+from remuda.ledger import (
+    LedgerEntry,
+    RenderError,
+    RenderRequest,
+    Report,
+    ResumeRefusedError,
+    RunStore,
+    SpecLock,
+    render,
+)
+from remuda.registry import (
+    DiscoverQuery,
+    ModelConfig,
+    Pool,
+    PoolEntry,
+    Provider,
+    Registry,
+    RegistryError,
+    RegistryValidationError,
+    default_config_dirs,
+    load_registry,
+)
+from remuda.rows import RowSourceError, read_columns, read_rows
+from remuda.spec import (
+    ExtractSchema,
+    FieldSpec,
+    GenerateConstraints,
+    InputSpec,
+    Job,
+    MapTable,
+    Precondition,
+    PromptRenderError,
+    PromptSpec,
+    ScoreRange,
+    SpecValidationError,
+)
+from remuda.transport import (
+    CompletionRequest,
+    CompletionResult,
+    PermanentTransportError,
+    RateLimitedError,
+    TransientTransportError,
+    Transport,
+    TransportError,
+    Usage,
+)
+from remuda.validate import Outcome, Verdict, validate_answer
+from remuda.version import __version__
+
+__all__ = [
+    "CheckReport",
+    "CompletionRequest",
+    "CompletionResult",
+    "DiscoverQuery",
+    "EngineError",
+    "ExtractSchema",
+    "FieldSpec",
+    "GenerateConstraints",
+    "InputSpec",
+    "Job",
+    "JobRunOutcome",
+    "LedgerEntry",
+    "MapTable",
+    "ModelConfig",
+    "Outcome",
+    "PermanentTransportError",
+    "Pool",
+    "PoolEntry",
+    "Precondition",
+    "PreviewReport",
+    "ProgressEvent",
+    "PromptRenderError",
+    "PromptSpec",
+    "Provider",
+    "RateLimitedError",
+    "Registry",
+    "RegistryError",
+    "RegistryValidationError",
+    "RemudaError",
+    "RenderError",
+    "RenderRequest",
+    "RenderedPrompt",
+    "Report",
+    "ResumeRefusedError",
+    "RowResult",
+    "RowSourceError",
+    "RunStore",
+    "Runner",
+    "ScoreRange",
+    "SpecLock",
+    "SpecValidationError",
+    "TransientTransportError",
+    "Transport",
+    "TransportError",
+    "Usage",
+    "Verdict",
+    "__version__",
+    "check_job_dir",
+    "default_config_dirs",
+    "load_registry",
+    "preview_job",
+    "read_columns",
+    "read_rows",
+    "render",
+    "run",
+    "run_job_dir",
+    "run_sync",
+    "validate_answer",
+]

remuda/api.py

@@ -0,0 +1,275 @@
+"""The embedding surface (FR-7).
+
+A host application runs the same jobs remuda's CLI runs: rows from any
+source, results delivered per completed row, the same ladder and the same
+report object. No files are required — pass rows in, get a Report back.
+"""
+
+import asyncio
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from remuda.catalog.resolve import ResolvedPool, resolve_pool
+from remuda.engine.progress import ProgressCallback
+from remuda.engine.runner import LedgerWriter, RowResult, Runner, Sink, TransportFactory
+from remuda.errors import RemudaError
+from remuda.inline import one_shot_job, one_shot_row
+from remuda.ledger.models import LedgerEntry, Report
+from remuda.ledger.resume import OpenedRun, build_lock, open_run
+from remuda.ledger.store import RUNS_DIRNAME, RunStore, new_run_id
+from remuda.preflight import preflight_opencode
+from remuda.registry.registry import Registry
+from remuda.rows import read_rows
+from remuda.spec.models import Job
+from remuda.transport.openai_compat import build_transport
+from remuda.version import __version__
+
+
+@dataclass(frozen=True)
+class JobRunOutcome:
+    """A file-backed run: what happened, and where it was recorded."""
+
+    report: Report
+    store: RunStore
+    is_resumed: bool
+    announcements: tuple[str, ...] = ()
+
+
+async def run(
+    job: Job,
+    rows: Sequence[Mapping[str, Any]],
+    registry: Registry,
+    *,
+    pool: str | None = None,
+    only: Sequence[str] | None = None,
+    sink: Sink | None = None,
+    progress: ProgressCallback | None = None,
+    write: LedgerWriter | None = None,
+    done: Mapping[tuple[str, str], LedgerEntry] | None = None,
+    run_id: str | None = None,
+    resolved_pools: Mapping[str, ResolvedPool] | None = None,
+    transport_factory: TransportFactory = build_transport,
+) -> Report:
+    """Derive every selected field for every row.
+
+    Args:
+        job: the job definition — from a directory or built in code.
+        rows: plain mappings; every column rides through untouched.
+        registry: providers, models and pools by name.
+        pool: overrides the pool every field names.
+        only: field selection; dependencies must be included.
+        sink: called once per row, when all its fields are decided.
+        progress: called once per chunk (FR-6).
+        write: called for every decided result — the ledger's append.
+        done: results a resume must not recompute.
+        run_id: identifies the run in the report.
+        resolved_pools: pools already materialized for this run (FR-3).
+        transport_factory: how a provider becomes a transport.
+
+    Raises:
+        EngineError: the run cannot be planned.
+    """
+    resolved_pools = await _ensure_resolved_pools(job, registry, pool, resolved_pools)
+    runner = Runner(
+        job=job,
+        registry=registry,
+        run_id=run_id or new_run_id(),
+        version=__version__,
+        pool=pool,
+        only=only,
+        transport_factory=transport_factory,
+        progress=progress,
+        sink=sink,
+        write=write,
+        done=done,
+        resolved_pools=resolved_pools,
+    )
+    return await runner.run(rows)
+
+
+def run_sync(
+    job: Job,
+    rows: Sequence[Mapping[str, Any]],
+    registry: Registry,
+    **options: Any,
+) -> Report:
+    """Blocking wrapper around `run()` for callers with no event loop."""
+    return asyncio.run(run(job, rows, registry, **options))
+
+
+async def run_job_dir(
+    job_dir: Path,
+    registry: Registry,
+    *,
+    runs_root: Path | None = None,
+    fresh: bool = False,
+    limit: int | None = None,
+    pool: str | None = None,
+    only: Sequence[str] | None = None,
+    fill_missing: str | None = None,
+    sink: Sink | None = None,
+    progress: ProgressCallback | None = None,
+    transport_factory: TransportFactory = build_transport,
+) -> JobRunOutcome:
+    """Run a job directory, recording everything in a run directory.
+
+    Raises:
+        SpecValidationError: the job directory is misdeclared.
+        ResumeRefusedError: the previous run used a different job or input.
+        EngineError: the run cannot be planned.
+    """
+    job = Job.from_dir(job_dir)
+    input_path = Path(job_dir) / job.input.path
+    rows = read_rows(input_path, job.input.format, limit=limit)
+    if fill_missing:
+        rows = [row for row in rows if not str(row.get(fill_missing, "")).strip()]
+
+    opened = open_run(
+        runs_root=runs_root or Path(job_dir) / RUNS_DIRNAME,
+        lock=build_lock(job, input_path, __version__),
+        fresh=fresh,
+    )
+    opened.store.write_job(job)
+    resolved = await _resolved_pools(job, registry, opened, pool)
+    announcements = await preflight_opencode(registry, resolved.values())
+    report = await _run_into(
+        opened,
+        job=job,
+        rows=rows,
+        registry=registry,
+        resolved_pools=resolved,
+        pool=pool,
+        only=only,
+        sink=sink,
+        progress=progress,
+        transport_factory=transport_factory,
+    )
+    return JobRunOutcome(
+        report=report,
+        store=opened.store,
+        is_resumed=opened.is_resumed,
+        announcements=tuple(announcements),
+    )
+
+
+async def _run_into(opened: OpenedRun, **options: Any) -> Report:
+    """Run into an opened run directory, always closing and reporting."""
+    store = opened.store
+    try:
+        report = await run(
+            run_id=store.run_id,
+            write=store.append,
+            done=opened.done,
+            **options,
+        )
+    finally:
+        store.close()
+    store.write_report(report)
+    return report
+
+
+async def _ensure_resolved_pools(
+    job: Job,
+    registry: Registry,
+    pool_override: str | None,
+    given: Mapping[str, ResolvedPool] | None,
+) -> Mapping[str, ResolvedPool] | None:
+    """Materialize catalog-backed pools the run needs but was not handed.
+
+    Statically declared pools resolve from the registry inside the engine;
+    only pools with discover queries need a catalog round-trip before
+    planning. This makes them work in every run shape — one-shot and inline
+    included — not just the job-directory path, which snapshots its own.
+    """
+    wanted = {pool_override or field.pool for field in job.fields}
+    resolved = dict(given or {})
+    pending = sorted(
+        name
+        for name in wanted
+        if name is not None
+        and name not in resolved
+        and registry.pool(name).discover_queries
+    )
+    if not pending:
+        return given
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        for name in pending:
+            resolved[name] = await resolve_pool(registry.pool(name), registry, client)
+    return resolved
+
+
+async def _resolved_pools(
+    job: Job,
+    registry: Registry,
+    opened: OpenedRun,
+    pool_override: str | None,
+) -> dict[str, ResolvedPool]:
+    """Materialize every pool the run needs, reusing a resume's snapshot.
+
+    A resumed run must keep the models it started with: free-tier membership
+    churns, and re-resolving would silently change who answered the run.
+    """
+    snapshot = opened.store.read_resolved_pools()
+    wanted = {
+        pool_override or field.pool
+        for field in job.fields
+        if (pool_override or field.pool) is not None
+    }
+    resolved: dict[str, ResolvedPool] = {}
+    pending = [name for name in wanted if name is not None and name not in snapshot]
+    if pending:
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            for name in sorted(pending):
+                resolved[name] = await resolve_pool(
+                    registry.pool(name), registry, client
+                )
+    resolved.update(snapshot)
+    if resolved:
+        opened.store.write_resolved_pools(list(resolved.values()))
+    return resolved
+
+
+class OneShotFailedError(RemudaError):
+    """A one-shot request produced no valid answer (FR-11)."""
+
+
+async def one_shot(
+    prompt: str,
+    registry: Registry,
+    *,
+    pool: str,
+    vocabulary: Sequence[str] | None = None,
+    piped: str | None = None,
+    progress: ProgressCallback | None = None,
+    transport_factory: TransportFactory = build_transport,
+) -> str:
+    """Answer one ad-hoc request through the ordinary ladder (FR-11).
+
+    Nothing is written: no run directory, no ledger, no report.
+
+    Raises:
+        OneShotFailedError: the pool produced no valid answer. The caller
+            must not print anything to stdout in that case.
+        EngineError: the request cannot be planned.
+    """
+    job = one_shot_job(prompt, pool=pool, vocabulary=vocabulary)
+    answers: list[RowResult] = []
+    report = await run(
+        job,
+        [one_shot_row(piped)],
+        registry,
+        sink=answers.append,
+        progress=progress,
+        transport_factory=transport_factory,
+    )
+    if not report.is_successful or not answers:
+        reason = report.failures[0].reason if report.failures else "no answer"
+        raise OneShotFailedError(reason or "the pool produced no valid answer")
+    value = answers[0].value(job.fields[0].name)
+    if value is None:
+        raise OneShotFailedError("the pool produced no valid answer")
+    return str(value)

remuda/catalog/__init__.py

@@ -0,0 +1,52 @@
+"""Per-provider catalog discovery behind `discover:` (FR-3)."""
+
+from remuda.catalog.adapters import (
+    ADAPTERS,
+    OLLAMA,
+    OPENAI_COMPAT,
+    OPENROUTER,
+    CatalogAdapter,
+    OllamaCatalog,
+    OpenAICompatCatalog,
+    OpenRouterCatalog,
+    adapter_for,
+)
+from remuda.catalog.errors import CatalogError, UnsupportedFilterError
+from remuda.catalog.models import (
+    FULL_CAPABILITIES,
+    NAME_ONLY_CAPABILITIES,
+    CatalogModel,
+)
+from remuda.catalog.resolve import (
+    ResolvedMember,
+    ResolvedPool,
+    apply_query,
+    member_to_model,
+    requested_filters,
+    resolve_pool,
+    to_model_configs,
+)
+
+__all__ = [
+    "ADAPTERS",
+    "FULL_CAPABILITIES",
+    "NAME_ONLY_CAPABILITIES",
+    "OLLAMA",
+    "OPENAI_COMPAT",
+    "OPENROUTER",
+    "CatalogAdapter",
+    "CatalogError",
+    "CatalogModel",
+    "OllamaCatalog",
+    "OpenAICompatCatalog",
+    "OpenRouterCatalog",
+    "ResolvedMember",
+    "ResolvedPool",
+    "UnsupportedFilterError",
+    "adapter_for",
+    "apply_query",
+    "member_to_model",
+    "requested_filters",
+    "resolve_pool",
+    "to_model_configs",
+]

remuda/catalog/adapters.py

@@ -0,0 +1,199 @@
+"""One discovery adapter per provider shape (FR-3).
+
+Every adapter answers two questions: what models does this provider serve,
+and which filters can I answer about them. The second is what keeps an
+unanswerable filter a refusal instead of a silent no-op.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+import httpx
+
+from remuda.catalog.errors import CatalogError
+from remuda.catalog.models import (
+    FULL_CAPABILITIES,
+    NAME_ONLY_CAPABILITIES,
+    CatalogModel,
+)
+from remuda.registry.models import Provider
+
+OPENROUTER = "openrouter"
+OPENAI_COMPAT = "openai_compat"
+OLLAMA = "ollama"
+
+
+@runtime_checkable
+class CatalogAdapter(Protocol):
+    """Reads a provider's model list."""
+
+    kind: str
+    capabilities: frozenset[str]
+
+    async def fetch(
+        self, provider: Provider, client: httpx.AsyncClient
+    ) -> list[CatalogModel]:
+        """Return every model the provider currently serves."""
+        ...
+
+
+class OpenRouterCatalog:
+    """`GET /api/v1/models` — pricing, context length and throughput."""
+
+    kind = OPENROUTER
+    capabilities = FULL_CAPABILITIES
+
+    async def fetch(
+        self, provider: Provider, client: httpx.AsyncClient
+    ) -> list[CatalogModel]:
+        """Read OpenRouter's catalog."""
+        payload = await _get_json(client, _root(provider) + "/models", provider)
+        return [_openrouter_model(entry) for entry in _entries(payload, "data")]
+
+
+class OpenAICompatCatalog:
+    """`GET /v1/models` — a bare list of ids, nothing more."""
+
+    kind = OPENAI_COMPAT
+    capabilities = NAME_ONLY_CAPABILITIES
+
+    async def fetch(
+        self, provider: Provider, client: httpx.AsyncClient
+    ) -> list[CatalogModel]:
+        """Read an OpenAI-compatible model list."""
+        payload = await _get_json(client, _root(provider) + "/models", provider)
+        return [
+            CatalogModel(id=str(entry["id"]))
+            for entry in _entries(payload, "data")
+            if entry.get("id")
+        ]
+
+
+class OllamaCatalog:
+    """`GET /api/tags` — locally pulled models, names only."""
+
+    kind = OLLAMA
+    capabilities = NAME_ONLY_CAPABILITIES
+
+    async def fetch(
+        self, provider: Provider, client: httpx.AsyncClient
+    ) -> list[CatalogModel]:
+        """Read the local Ollama model list."""
+        base = _root(provider).removesuffix("/v1")
+        payload = await _get_json(client, f"{base}/api/tags", provider)
+        return [
+            CatalogModel(id=str(entry["name"]))
+            for entry in _entries(payload, "models")
+            if entry.get("name")
+        ]
+
+
+#: Every adapter, by the name a provider declares in `catalog:`.
+ADAPTERS: dict[str, CatalogAdapter] = {
+    OPENROUTER: OpenRouterCatalog(),
+    OPENAI_COMPAT: OpenAICompatCatalog(),
+    OLLAMA: OllamaCatalog(),
+}
+
+
+def adapter_for(provider: Provider) -> CatalogAdapter:
+    """Return the adapter a provider's `catalog` declaration names.
+
+    Raises:
+        CatalogError: the provider names no catalog, or an unknown one.
+    """
+    declared = provider.catalog
+    if declared is None:
+        raise CatalogError(
+            f"provider '{provider.name}' declares no catalog, so its models "
+            "cannot be discovered — set catalog: "
+            + " | ".join(sorted(ADAPTERS))
+            + ", or name the models explicitly in the pool"
+        )
+    adapter = ADAPTERS.get(declared)
+    if adapter is None:
+        raise CatalogError(
+            f"provider '{provider.name}' names unknown catalog '{declared}' — "
+            "known catalogs: " + ", ".join(sorted(ADAPTERS))
+        )
+    return adapter
+
+
+# -- shared HTTP plumbing --------------------------------------------------
+
+
+def _root(provider: Provider) -> str:
+    base = (provider.base_url or "").rstrip("/")
+    if not base:
+        raise CatalogError(f"provider '{provider.name}' has no base_url to read")
+    return base
+
+
+async def _get_json(client: httpx.AsyncClient, url: str, provider: Provider) -> Any:
+    try:
+        response = await client.get(url, headers=_headers(provider))
+    except httpx.TransportError as error:
+        raise CatalogError(
+            f"cannot reach the catalog of provider '{provider.name}' at {url}: {error}"
+        ) from error
+    if response.status_code >= 400:
+        raise CatalogError(
+            f"the catalog of provider '{provider.name}' returned "
+            f"{response.status_code} for {url}"
+        )
+    try:
+        return response.json()
+    except ValueError as error:
+        raise CatalogError(
+            f"the catalog of provider '{provider.name}' returned a non-JSON body"
+        ) from error
+
+
+def _headers(provider: Provider) -> dict[str, str]:
+    # Imported here: the transport module owns credential resolution, and
+    # importing it at module level would tie the catalog to the transport.
+    from remuda.transport.openai_compat import catalog_headers  # noqa: PLC0415
+
+    return catalog_headers(provider)
+
+
+def _entries(payload: Any, key: str) -> Sequence[Mapping[str, Any]]:
+    rows = payload.get(key, []) if isinstance(payload, Mapping) else payload
+    if not isinstance(rows, Sequence):
+        return []
+    return [row for row in rows if isinstance(row, Mapping)]
+
+
+def _openrouter_model(entry: Mapping[str, Any]) -> CatalogModel:
+    pricing = _mapping(entry.get("pricing"))
+    stats = _mapping(entry.get("stats"))
+    return CatalogModel(
+        id=str(entry.get("id", "")),
+        name=_optional_str(entry.get("name")),
+        context_length=_optional_int(entry.get("context_length")),
+        prompt_price_usd=_optional_float(pricing.get("prompt")),
+        completion_price_usd=_optional_float(pricing.get("completion")),
+        throughput=_optional_float(stats.get("throughput") or entry.get("throughput")),
+    )
+
+
+def _mapping(value: Any) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _optional_str(value: Any) -> str | None:
+    return str(value) if value is not None else None
+
+
+def _optional_int(value: Any) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _optional_float(value: Any) -> float | None:
+    try:
+        return float(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None

remuda/catalog/errors.py

@@ -0,0 +1,32 @@
+"""Errors raised while discovering a provider's models."""
+
+from remuda.catalog.models import FILTER_DESCRIPTIONS
+from remuda.errors import RemudaError
+
+
+class CatalogError(RemudaError):
+    """A provider's catalog could not be read."""
+
+
+class UnsupportedFilterError(CatalogError):
+    """A `discover:` filter this catalog cannot answer — refused, not ignored.
+
+    Silently dropping the filter would materialize a pool the operator never
+    asked for: "free models over 32k" quietly becoming "every model".
+    """
+
+    def __init__(self, provider: str, catalog: str, filters: list[str]) -> None:
+        self.provider = provider
+        self.catalog = catalog
+        self.filters: tuple[str, ...] = tuple(filters)
+        super().__init__(self._describe())
+
+    def _describe(self) -> str:
+        named = ", ".join(
+            f"'{name}' ({FILTER_DESCRIPTIONS.get(name, name)})" for name in self.filters
+        )
+        return (
+            f"provider '{self.provider}' has a '{self.catalog}' catalog, which "
+            f"cannot answer {named}. Drop the filter, or name the models "
+            "explicitly in the pool."
+        )