Metadata-Version: 2.3
Name: arova
Version: 0.1.2
Summary: One API for every LLM provider, with zero ceremony.
Author: Arova Contributors
License: MIT License
        
        Copyright (c) 2026 Arova Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,anthropic,gemini,inference,llm,openai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: anyio<5,>=4
Requires-Dist: httpx[http2]<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# Arova

[![PyPI](https://img.shields.io/pypi/v/arova.svg)](https://pypi.org/project/arova/)
[![Python](https://img.shields.io/pypi/pyversions/arova.svg)](https://pypi.org/project/arova/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> **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

```bash
pip install arova
export OPENAI_API_KEY=sk-...
```

```python
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](RESEARCH.md).

| Adapter | Provider examples | Wire format |
|---|---|---|
| Native | OpenAI, Anthropic, Gemini, Azure OpenAI, Bedrock, Mistral, Cohere, Groq, DeepSeek, xAI | Provider-specific translation and streaming |
| `opencompat` | Together, Fireworks, OpenRouter, Ollama, vLLM, LM Studio, Perplexity, Cerebras, SambaNova, self-hosted gateways | `/chat/completions` |

```python
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`.

```python
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.

```python
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](RESEARCH.md).

## CLI

```bash
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](LICENSE).
