callai-cli 0.9.0__py3-none-any.whl

callai/config.py

@@ -0,0 +1,273 @@
+"""User configuration: ``config.toml``, and model aliases (DESIGN.md §6).
+
+Precedence, applied by the CLI: command-line flag > ``CALLAI_*`` environment variable > this file >
+built-in default. The file is optional; a missing default file is an empty config.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .adapters import HARNESS_NAMES
+from .errors import UsageError
+
+
+class _Invalid(ValueError):
+    """A problem in the config file; :func:`load_config` adds the file name and raises UsageError."""
+
+
+_TOP_KEYS = {"default_harness", "model", "timeout", "harnesses", "aliases"}
+_HARNESS_KEYS = {"binary", "model", "extra_args"}
+
+
+@dataclass(frozen=True)
+class HarnessConfig:
+    """Settings for one harness, from ``[harnesses.<name>]``.
+
+    Attributes:
+        binary: Executable to run instead of the adapter's default (``~`` is expanded).
+        model: Default model for this harness (may be an alias).
+        extra_args: Arguments passed to the harness before any given after ``--``.
+    """
+
+    binary: str | None = None
+    model: str | None = None
+    extra_args: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Config:
+    """Parsed ``config.toml``; every field is optional.
+
+    Attributes:
+        default_harness: Harness used when neither ``-n`` nor ``CALLAI_HARNESS_NAME`` is given.
+        model: Default model for every harness (typically an alias).
+        timeout: Default ``--timeout`` in seconds.
+        harnesses: Per-harness settings, by harness name.
+        aliases: Model alias -> {harness name -> model}.
+    """
+
+    default_harness: str | None = None
+    model: str | None = None
+    timeout: float | None = None
+    harnesses: dict[str, HarnessConfig] = field(default_factory=dict)
+    aliases: dict[str, dict[str, str]] = field(default_factory=dict)
+
+
+def config_path(environ: Mapping[str, str], home: str | None = None) -> tuple[str, bool]:
+    """Where the config file is, and whether the user named it explicitly.
+
+    Args:
+        environ: Environment (``CALLAI_CONFIG``, ``XDG_CONFIG_HOME``).
+        home: Home directory; defaults to the current user's.
+
+    Returns:
+        ``(path, explicit)``: ``explicit`` is true when ``CALLAI_CONFIG`` set it.
+    """
+    if environ.get("CALLAI_CONFIG"):
+        return environ["CALLAI_CONFIG"], True
+    base = environ.get("XDG_CONFIG_HOME") or os.path.join(home or str(Path.home()), ".config")
+    return os.path.join(base, "callai", "config.toml"), False
+
+
+def load_config(environ: Mapping[str, str], home: str | None = None) -> Config:
+    """Read and validate the config file.
+
+    Args:
+        environ: Environment used to find the file.
+        home: Home directory; defaults to the current user's.
+
+    Returns:
+        The config; empty if the default file doesn't exist.
+
+    Raises:
+        UsageError: If an explicit ``CALLAI_CONFIG`` file is missing, or the file is unreadable,
+            not TOML, or has unknown keys or invalid values. The message names the file.
+    """
+    path, explicit = config_path(environ, home)
+    if not os.path.exists(path):
+        if explicit:
+            raise UsageError(f"CALLAI_CONFIG points at {path}, which doesn't exist")
+        return Config()
+    try:
+        with open(path, "rb") as fh:
+            data = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        raise UsageError(f"{path}: invalid TOML ({exc})") from None
+    except OSError as exc:
+        raise UsageError(f"{path}: cannot read config ({exc.strerror or exc})") from None
+    try:
+        return _parse(data)
+    except _Invalid as exc:
+        raise UsageError(f"{path}: {exc}") from None
+
+
+def resolve_model(config: Config, harness_name: str, model: str | None) -> str | None:
+    """Turn a model alias into the harness's own model name; anything else passes through.
+
+    Args:
+        config: The config holding ``[aliases]``.
+        harness_name: Harness the model is for.
+        model: Model or alias, or ``None``.
+
+    Returns:
+        The model to pass to the harness.
+
+    Raises:
+        UsageError: If ``model`` is an alias with no entry for this harness.
+    """
+    if model is None or model not in config.aliases:
+        return model
+    try:
+        return config.aliases[model][harness_name]
+    except KeyError:
+        raise UsageError(f"model alias {model!r} has no entry for {harness_name}") from None
+
+
+# --- validation ---------------------------------------------------------------
+
+
+def _parse(data: dict[str, Any]) -> Config:
+    """Validate a decoded config file.
+
+    Args:
+        data: Decoded TOML.
+
+    Returns:
+        The config.
+
+    Raises:
+        _Invalid: On unknown keys or invalid values.
+    """
+    _check_keys(data, _TOP_KEYS, "")
+    default = data.get("default_harness")
+    if default is not None and default not in HARNESS_NAMES:
+        raise _Invalid(f"default_harness: unknown harness {default!r}; choose from {', '.join(HARNESS_NAMES)}")
+    model = _opt_str(data, "model", "")
+    timeout = data.get("timeout")
+    if timeout is not None and (
+        isinstance(timeout, bool) or not isinstance(timeout, int | float) or not math.isfinite(timeout) or timeout <= 0
+    ):
+        raise _Invalid(f"timeout must be a positive number of seconds, got {timeout!r}")
+    return Config(
+        default_harness=default,
+        model=model,
+        timeout=timeout,
+        harnesses=_parse_harnesses(_table(data, "harnesses")),
+        aliases=_parse_aliases(_table(data, "aliases")),
+    )
+
+
+def _parse_harnesses(raw: dict[str, Any]) -> dict[str, HarnessConfig]:
+    """Validate ``[harnesses.<name>]`` tables.
+
+    Args:
+        raw: The ``harnesses`` table.
+
+    Returns:
+        Settings by harness name.
+
+    Raises:
+        _Invalid: On an unknown harness, unknown key or invalid value.
+    """
+    out = {}
+    for name, table in raw.items():
+        where = f"[harnesses.{name}]"
+        if name not in HARNESS_NAMES:
+            raise _Invalid(f"{where}: unknown harness; choose from {', '.join(HARNESS_NAMES)}")
+        if not isinstance(table, dict):
+            raise _Invalid(f"{where} must be a table")
+        _check_keys(table, _HARNESS_KEYS, where)
+        binary = _opt_str(table, "binary", where)
+        if binary == "":
+            raise _Invalid(f"{where}: binary must be a non-empty string")
+        extra = table.get("extra_args", [])
+        if not isinstance(extra, list) or not all(isinstance(a, str) for a in extra):
+            raise _Invalid(f"{where}: extra_args must be a list of strings")
+        out[name] = HarnessConfig(binary=binary, model=_opt_str(table, "model", where), extra_args=tuple(extra))
+    return out
+
+
+def _parse_aliases(raw: dict[str, Any]) -> dict[str, dict[str, str]]:
+    """Validate ``[aliases]``: each alias maps harness names to model names.
+
+    Args:
+        raw: The ``aliases`` table.
+
+    Returns:
+        Alias -> {harness name -> model}.
+
+    Raises:
+        _Invalid: If an alias isn't a table of strings or names an unknown harness.
+    """
+    out = {}
+    for alias, mapping in raw.items():
+        if not isinstance(mapping, dict) or not all(isinstance(m, str) for m in mapping.values()):
+            raise _Invalid(f"[aliases] {alias} must map harness names to models, e.g. {{ codex = 'o3' }}")
+        for name in mapping:
+            if name not in HARNESS_NAMES:
+                raise _Invalid(f"[aliases] {alias}: unknown harness {name!r}; choose from {', '.join(HARNESS_NAMES)}")
+        out[alias] = dict(mapping)
+    return out
+
+
+def _check_keys(table: dict[str, Any], allowed: set[str], where: str) -> None:
+    """Refuse unknown keys, so a typo doesn't silently do nothing.
+
+    Args:
+        table: A TOML table.
+        allowed: Keys it may have.
+        where: Table name for the message (``""`` for the top level).
+
+    Raises:
+        _Invalid: On the first unknown key.
+    """
+    for key in table:
+        if key not in allowed:
+            prefix = f"{where}: " if where else ""
+            raise _Invalid(f"{prefix}unknown key {key!r}; allowed: {', '.join(sorted(allowed))}")
+
+
+def _table(data: dict[str, Any], key: str) -> dict[str, Any]:
+    """An optional sub-table, ``{}`` if absent.
+
+    Args:
+        data: The parent table.
+        key: Sub-table name.
+
+    Returns:
+        The sub-table.
+
+    Raises:
+        _Invalid: If the key holds something other than a table.
+    """
+    value = data.get(key, {})
+    if not isinstance(value, dict):
+        raise _Invalid(f"{key} must be a table")
+    return value
+
+
+def _opt_str(table: dict[str, Any], key: str, where: str) -> str | None:
+    """An optional string value.
+
+    Args:
+        table: The table.
+        key: The key.
+        where: Table name for the message.
+
+    Returns:
+        The string, or ``None`` if absent.
+
+    Raises:
+        _Invalid: If the value isn't a string.
+    """
+    value = table.get(key)
+    if value is not None and not isinstance(value, str):
+        raise _Invalid(f"{where + ': ' if where else ''}{key} must be a string")
+    return value

callai/errors.py

@@ -0,0 +1,65 @@
+"""Exceptions raised by callai, each carrying the process exit code it maps to (DESIGN.md §8)."""
+
+
+class CallaiError(Exception):
+    """Base class for errors callai reports to the user instead of a traceback."""
+
+    exit_code = 1
+
+
+class UsageError(CallaiError):
+    """Invalid command line, configuration or request (exit code 2)."""
+
+    exit_code = 2
+
+
+class HarnessNotFound(CallaiError):
+    """The harness executable is not on PATH (exit code 127, like a shell)."""
+
+    exit_code = 127
+
+    def __init__(self, binary: str, harness_name: str | None = None, install_url: str | None = None) -> None:
+        """Build the message.
+
+        Args:
+            binary: Executable that was looked up.
+            harness_name: The ``--name`` (harness) that needs it, if known.
+            install_url: Where to get it, if known.
+        """
+        msg = f"harness binary {binary!r} not found on PATH"
+        if harness_name:
+            msg += f" (needed for --name {harness_name})"
+        if install_url:
+            msg += f"; install it: {install_url}"
+        super().__init__(msg)
+
+
+class NoHarnessInstalled(CallaiError):
+    """``-n all`` found none of the supported harnesses on PATH (exit code 127)."""
+
+    exit_code = 127
+
+
+class HarnessTimeout(CallaiError):
+    """The harness ran longer than ``--timeout`` and was killed (exit code 124, like GNU timeout)."""
+
+    exit_code = 124
+
+    def __init__(self, binary: str, timeout: float) -> None:
+        """Build the message.
+
+        Args:
+            binary: Executable that was killed.
+            timeout: The limit, in seconds.
+        """
+        super().__init__(f"{binary!r} timed out after {timeout:g}s and was killed")
+
+
+class Interrupted(CallaiError):
+    """The user interrupted the run (exit code 130, like SIGINT in a shell)."""
+
+    exit_code = 130
+
+    def __init__(self) -> None:
+        """Build the message."""
+        super().__init__("interrupted")

callai/fanout.py

@@ -0,0 +1,166 @@
+"""Fan-out: one prompt through several harnesses (DESIGN.md §3).
+
+``-n a/b/c`` runs them at the same time, ``-n a,b,c`` one after another, ``-n all`` every installed
+harness at the same time. Results come back in the order given, whatever order the runs finish in.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from . import runner
+from .adapters import HARNESS_NAMES, Adapter
+from .api import EventHandler, run_harness
+from .errors import CallaiError, Interrupted, UsageError
+from .request import Request
+from .result import Completed, Result
+
+SINGLE, PARALLEL, SEQUENTIAL, ALL = "single", "parallel", "sequential", "all"
+
+
+def split_harness_names(value: str) -> tuple[list[str], str]:
+    """Split a ``-n`` value into harness names and how to run them.
+
+    Args:
+        value: ``"codex"``, ``"a/b/c"`` (parallel), ``"a,b,c"`` (one after another) or ``"all"``.
+
+    Returns:
+        ``(names, mode)``; mode is ``SINGLE``, ``PARALLEL``, ``SEQUENTIAL`` or ``ALL``. Names aren't
+        checked against the registry here.
+
+    Raises:
+        UsageError: For mixed separators, empty or repeated names, or ``all`` inside a list.
+    """
+    if "/" in value and "," in value:
+        raise UsageError(f"-n {value}: use '/' (parallel) or ',' (one after another), not both")
+    sep = "/" if "/" in value else ","
+    names = [n.strip() for n in value.split(sep)]
+    if any(not n for n in names):
+        raise UsageError(f"-n {value}: empty harness name")
+    if len(names) == 1:
+        return (list(HARNESS_NAMES), ALL) if names[0] == "all" else (names, SINGLE)
+    if "all" in names:
+        raise UsageError(f"-n {value}: 'all' can't be combined with other harnesses")
+    for name in names:
+        if names.count(name) > 1:
+            raise UsageError(f"-n {value}: {name} is listed twice")
+    return names, PARALLEL if sep == "/" else SEQUENTIAL
+
+
+@dataclass(frozen=True)
+class Job:
+    """One harness's part of a fan-out.
+
+    Attributes:
+        adapter: The harness's adapter.
+        req: Its request.
+        argv: Its command line (binary already resolved from the config).
+    """
+
+    adapter: Adapter
+    req: Request
+    argv: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """How one job ended.
+
+    Attributes:
+        result: The normalised result (a timeout is a failed result, exit 124).
+        completed: The raw process outcome, or ``None`` if the run didn't finish.
+    """
+
+    result: Result
+    completed: Completed | None
+
+
+def run_jobs(
+    jobs: Sequence[Job],
+    *,
+    concurrent: bool,
+    verbose: bool = False,
+    event_handler: Callable[[Job], EventHandler | None] = lambda job: None,
+) -> list[Outcome]:
+    """Run every job, at the same time or one after another; one failure doesn't stop the rest.
+
+    Args:
+        jobs: The jobs, in output order.
+        concurrent: Run them all at once (one thread each) instead of in order.
+        verbose: Copy each harness's stderr to ours as it arrives.
+        event_handler: Gives each job its ``-o stream-json`` event callback, or ``None``.
+
+    Returns:
+        One outcome per job, in the same order.
+
+    Raises:
+        Interrupted: On Ctrl-C, after every running harness was stopped.
+    """
+    if not concurrent:
+        return [_run_one(job, verbose, event_handler(job)) for job in jobs]
+    outcomes: list[Outcome | None] = [None] * len(jobs)
+    errors: list[BaseException] = []
+
+    def work(i: int) -> None:
+        """Run job ``i`` in its thread, keeping its outcome or unexpected error.
+
+        Args:
+            i: The job's index.
+        """
+        try:
+            outcomes[i] = _run_one(jobs[i], verbose, event_handler(jobs[i]))
+        except BaseException as exc:  # noqa: BLE001 - re-raised in the main thread below
+            errors.append(exc)
+
+    threads = [threading.Thread(target=work, args=(i,), daemon=True) for i in range(len(jobs))]
+    for t in threads:
+        t.start()
+    try:
+        for t in threads:
+            while t.is_alive():
+                t.join(0.1)  # short joins, so Ctrl-C reaches this thread
+    except KeyboardInterrupt:
+        runner.stop_all()
+        for t in threads:
+            t.join()
+        raise Interrupted() from None
+    if errors:
+        raise errors[0]
+    return [o for o in outcomes if o is not None]
+
+
+def _run_one(job: Job, verbose: bool, on_event: EventHandler | None) -> Outcome:
+    """Run one job; a callai error (e.g. a timeout) becomes a failed result instead of stopping the others.
+
+    Args:
+        job: The job.
+        verbose: Copy the harness's stderr to ours as it arrives.
+        on_event: ``-o stream-json`` event callback, or ``None``.
+
+    Returns:
+        Its outcome.
+
+    Raises:
+        Interrupted: On Ctrl-C while it ran (one after another), so the rest don't start.
+    """
+    try:
+        completed = run_harness(job.adapter, job.req, job.argv, verbose=verbose, on_event=on_event)
+    except Interrupted:
+        raise
+    except CallaiError as exc:
+        result = Result(
+            harness_name=job.adapter.name,
+            model=job.req.model,
+            text=str(exc),
+            exit_code=exc.exit_code,
+            is_error=True,
+            argv=job.argv,
+        )
+        completed = None
+    else:
+        result = job.adapter.parse(completed, job.req)
+    if on_event is not None:
+        on_event({"type": "result", **result.to_dict()})
+    return Outcome(result, completed)

callai/request.py

@@ -0,0 +1,70 @@
+"""The harness-independent request every adapter turns into a command line."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .errors import UsageError
+
+OUTPUT_FORMATS = ("text", "json", "stream-json", "raw")
+PERMISSIONS = ("default", "read-only", "auto", "bypass")
+
+
+@dataclass(frozen=True)
+class Request:
+    """One non-interactive prompt to run through a harness.
+
+    Attributes:
+        harness_name: Harness name, e.g. ``"claude-code"`` (validated by the adapter registry).
+        prompt: Final prompt text, after stdin has been merged in.
+        model: Model passed to the harness verbatim, or ``None`` for its default.
+        output_format: How callai prints the result (not how the harness is invoked).
+        cwd: Working directory for the harness, or ``None`` for the current directory.
+        timeout: Seconds before the harness is killed, or ``None`` for no limit.
+        permission: Harness-neutral permission level (DESIGN.md §7).
+        system_prompt: Optional system prompt, where the harness supports one.
+        extra_args: Arguments passed through to the harness unchanged.
+        resume: Session id to continue (the ``session_id`` a previous run reported), or ``None``.
+        continue_session: Continue the harness's most recent session instead of starting a new one.
+    """
+
+    harness_name: str
+    prompt: str
+    model: str | None = None
+    output_format: str = "text"
+    cwd: str | None = None
+    timeout: float | None = None
+    permission: str = "default"
+    system_prompt: str | None = None
+    extra_args: tuple[str, ...] = ()
+    resume: str | None = None
+    continue_session: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate fields and normalise ``extra_args`` to a tuple.
+
+        Raises:
+            UsageError: If any field has an invalid value.
+        """
+        if not isinstance(self.prompt, str):
+            raise UsageError("prompt must be a string")
+        if self.output_format not in OUTPUT_FORMATS:
+            raise UsageError(f"invalid output format {self.output_format!r}; choose from {', '.join(OUTPUT_FORMATS)}")
+        if self.permission not in PERMISSIONS:
+            raise UsageError(f"invalid permission {self.permission!r}; choose from {', '.join(PERMISSIONS)}")
+        if self.timeout is not None and (
+            isinstance(self.timeout, bool) or not isinstance(self.timeout, int | float) or self.timeout <= 0
+        ):
+            raise UsageError(f"timeout must be a positive number of seconds, got {self.timeout!r}")
+        if isinstance(self.extra_args, str) or not all(isinstance(a, str) for a in self.extra_args):
+            raise UsageError("extra_args must be a sequence of strings")
+        object.__setattr__(self, "extra_args", tuple(self.extra_args))
+        if self.resume is not None:
+            if not isinstance(self.resume, str):
+                raise UsageError("resume must be a session id string")
+            if not self.resume:
+                raise UsageError("--resume: empty session id")
+            if self.resume.startswith("-"):
+                raise UsageError("--resume: a session id can't start with '-' (the harness would read it as an option)")
+            if self.continue_session:
+                raise UsageError("use --resume or --continue, not both")

callai/result.py

@@ -0,0 +1,95 @@
+"""What a harness run produced: the raw process outcome and the normalised result."""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Completed:
+    """Raw outcome of running a harness process (filled in by the runner).
+
+    Attributes:
+        argv: The exact command line that ran.
+        exit_code: The harness's exit status.
+        stdout: Captured standard output.
+        stderr: Captured standard error.
+        duration_ms: Wall-clock run time in milliseconds, if measured.
+    """
+
+    argv: Sequence[str]
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: int | None = None
+
+
+@dataclass(frozen=True)
+class Result:
+    """Harness-independent result of one run; ``to_dict()`` is the ``-o json`` schema (DESIGN.md §5).
+
+    Attributes:
+        harness_name: Harness name.
+        text: The final assistant answer.
+        exit_code: The harness's exit status.
+        is_error: Whether the run failed, per the harness's own error signal.
+        model: Model the harness reports it used, else the requested one.
+        duration_ms: Wall-clock run time in milliseconds.
+        session_id: Harness session id, if reported.
+        usage: ``{"input_tokens": ..., "output_tokens": ...}``; input includes cached tokens.
+        cost_usd: Reported cost in US dollars.
+        argv: The command line that ran.
+        raw_stdout: Unparsed harness stdout (for ``-o raw``; not part of ``to_dict()``).
+        raw_stderr: Unparsed harness stderr (not part of ``to_dict()``).
+    """
+
+    harness_name: str
+    text: str
+    exit_code: int
+    is_error: bool
+    model: str | None = None
+    duration_ms: int | None = None
+    session_id: str | None = None
+    usage: dict[str, int] | None = None
+    cost_usd: float | None = None
+    argv: tuple[str, ...] = ()
+    raw_stdout: str = field(default="", repr=False)
+    raw_stderr: str = field(default="", repr=False)
+
+    def __post_init__(self) -> None:
+        """Normalise ``argv`` to a tuple."""
+        object.__setattr__(self, "argv", tuple(self.argv))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the JSON-serialisable result, in the stable key order of DESIGN.md §5.
+
+        Returns:
+            A new dict; mutating it does not affect this result.
+        """
+        return {
+            "harness_name": self.harness_name,
+            "model": self.model,
+            "text": self.text,
+            "exit_code": self.exit_code,
+            "is_error": self.is_error,
+            "duration_ms": self.duration_ms,
+            "session_id": self.session_id,
+            "usage": copy.deepcopy(self.usage),
+            "cost_usd": self.cost_usd,
+            "argv": list(self.argv),
+        }
+
+    def with_updates(self, **changes: Any) -> Result:
+        """Return a copy with some fields replaced.
+
+        Args:
+            **changes: Field names and their new values.
+
+        Returns:
+            The updated copy.
+        """
+        return dataclasses.replace(self, **changes)