llm-transport

Run a prompt through the claude CLI in print mode, or straight through the Anthropic Messages API - directly, or via a LiteLLM gateway in front of Bedrock, Vertex and the rest - with one environment switch and one result shape.

import llm_transport

env = llm_transport.run(
    "Read notes.md and reply with a one-line summary.",
    cwd=".",
    allowed_tools="Read,Grep,Glob",
)
if env["is_error"]:
    raise RuntimeError(env["result"])
print(env["result"], env["total_cost_usd"], env["num_turns"])

env is the JSON envelope claude -p --output-format json prints (result, is_error, subtype, stop_reason, api_error_status, num_turns, usage, total_cost_usd) plus a warnings list - in both modes. Code that already parses the CLI's output can switch transport without touching its error handling.

Install

pip install llm-transport              # CLI mode only: no dependencies
pip install "llm-transport[anthropic]" # adds the anthropic SDK for API mode

Python 3.12+.

Configuration

LLM_API_KEY and LLM_API_URL drive both transports: in CLI mode they are passed to claude as ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL, unless those are already set.

Why the Anthropic Messages format, not OpenAI's

Behind LiteLLM you could speak the OpenAI chat format instead. This package doesn't, because for Claude that format drops what matters most in a tool loop: prompt caching (cache_control), which keeps a turn from re-paying for the whole prompt; thinking blocks, which must go back unchanged between tool turns; server-side web search; effort; refusal details; and cache token accounting.

Tools in API mode

Grants use the CLI's own --allowed-tools / --disallowed-tools / --tools syntax and meaning, so one grant string works in both modes:

llm_transport.run(prompt, cwd=repo,
                  allowed_tools="Read,Grep,Bash(python scripts/lookup.py*),WebFetch,WebSearch",
                  disallowed_tools="Write,Edit",
                  tools=None)   # None: derive from the grant; "": no tools at all

Deny beats allow. Tools the CLI has but API mode does not (Write, Edit, ...) are left out with a note in warnings. In API mode this package is the permission boundary; in CLI mode the CLI is.

API mode does not load .claude/rules/, CLAUDE.md or skills the way the CLI does from its working directory. Inline what the prompt needs.

Limits and cost

llm_transport.run(prompt, cwd=".", timeout_s=900, max_usd=2.0)

• timeout_s bounds the call (CLI: the process tree is killed; API: checked between turns and as the request timeout).
• max_usd is --max-budget-usd in CLI mode (dropped, and listed in dropped_flags, if the installed build lacks it) and is checked between turns in API mode, ending with subtype: "error_max_budget_usd".
• total_cost_usd in API mode is LiteLLM's x-litellm-response-cost when the gateway sends it, otherwise an estimate at first-party list prices (llm_transport.PRICES). Bedrock and Vertex bill at their own rates. A model the table cannot price is recorded at $0 with a warning.

Errors

run, run_api and run_cli never raise on a model or transport failure: the envelope has is_error: true, api_error_status (HTTP status, when there was one) and a readable result such as API error 401: authentication_error: .... Classify on those. Lower-level pieces (run_cli_raw, spawn_kwargs, kill_process_tree, cli_env) are public for callers that drive the CLI themselves.

License

MIT