Arova

One API. Every model. Zero ceremony.

Arova is a small, typed Python client for calling major hosted and local language-model providers through one stable interface. It uses native adapters where wire formats differ and one universal OpenAI-compatible adapter for the long tail of endpoints.

Quickstart

pip install arova
export OPENAI_API_KEY=sk-...

from arova import completion

response = completion(
    "openai/gpt-5.6-luna",
    [{"role": "user", "content": "Explain zero-copy I/O in one paragraph."}],
)
print(response.text, response.cost)

The model prefix selects a provider. A bare model name uses OpenAI by default, and fallback chains can mix providers: fallbacks=["groq/llama-3.3-70b-versatile", "opencompat/local-model"]. For asynchronous applications, use await arova.acompletion(...) or async for event in arova.astream(...).

Provider coverage

Arova includes native adapters for OpenAI, Anthropic, Gemini, Azure OpenAI, Bedrock, Mistral, Cohere, Groq, DeepSeek, and xAI. It also includes arova.opencompat, which can target any OpenAI-compatible endpoint by setting base_url, model, and key. This covers Together AI, Fireworks AI, OpenRouter, Hugging Face Inference Providers, Ollama, vLLM, LM Studio, Perplexity, Cerebras, SambaNova, NVIDIA NIM, DeepInfra, Novita, and deployment-specific endpoints without adding vendor SDKs. The detailed matrix and source notes are in RESEARCH.md.

from arova.providers.opencompat import OpenCompatProvider
from arova.types import ChatRequest, Message

provider = OpenCompatProvider(
    base_url="https://api.together.xyz/v1",
    api_key="...",
    provider_name="together",
)

Streaming

Streaming yields typed events rather than provider-specific dictionaries. Tool-call arguments may arrive over many deltas and can be reassembled with assemble_tool_calls.

from arova import Arova, TextDelta, Finish

client = Arova()
for event in client.stream("groq/llama-3.3-70b-versatile", [{"role": "user", "content": "Give me three names for a two-faced API."}]):
    if isinstance(event, TextDelta):
        print(event.text, end="", flush=True)
    elif isinstance(event, Finish):
        print(f"\nfinished: {event.reason}")

Tool calling and structured output

The same request types work across native adapters and compatible endpoints. Provider quirks are translated at the boundary.

from arova import completion

response = completion(
    "anthropic/claude-sonnet-4.0",
    [{"role": "user", "content": "What is the weather in Paris?"}],
    tools=[{
        "name": "get_weather",
        "description": "Return current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }],
)
for call in response.tool_calls:
    print(call.name, call.arguments)

A JSON-schema response can be requested with response_format={"type": "json_schema", "name": "answer", "schema": {...}}. Support depends on the upstream model; Arova preserves the request and normalizes the response when the provider supports it.

Retries, fallbacks, and costs

Arova retries transient transport failures, 408/409/429 responses, and 5xx responses with jittered exponential backoff. A numeric Retry-After header takes precedence. A fallback chain is expressed as model strings, for example fallbacks=["groq/llama-3.3-70b-versatile", "opencompat/local"]. Every non-streaming response includes normalized usage and a deterministic cost estimate from the bundled static price table. Prices are a source-controlled snapshot, not a billing authority; see RESEARCH.md.

Error Handling

If a request completely fails (e.g., invalid API key, network error, or all fallbacks exhausted), Arova handles it depending on the method:

• completion / acompletion: Raises an arova.ProviderError which chains the final underlying exception (e.g., httpx.HTTPStatusError) so standard tracebacks reveal the exact upstream failure.
• stream / astream: Yields an ErrorEvent in the stream containing the failure details, rather than throwing an exception that crashes the active generator.

CLI

arova --help
arova models
arova cost groq llama-3.3-70b-versatile --input-tokens 1000 --output-tokens 250
arova chat --model openai/gpt-5.6-luna

Benchmark-note placeholder

A controlled benchmark will compare direct provider calls with Arova using warmed HTTP/2 connections, identical payloads, and separate cold-start measurements. Until that benchmark is added, performance claims are design goals rather than published results. Arova intentionally avoids per-call imports, unnecessary re-validation, mandatory logging, and proxy/server dependencies in the request path.

License

Arova is released under the MIT License. See LICENSE.