arova 0.1.0__tar.gz

arova-0.1.0/DECISIONS.md

@@ -0,0 +1,25 @@
+# Arova architecture decisions
+
+## Small runtime
+
+Arova uses `httpx`, `pydantic`, and `anyio` at runtime. Vendor SDKs, web frameworks, proxy servers, and LangChain are excluded so installation remains small and provider adapters stay inspectable.
+
+## Stable canonical model
+
+The public API is modeled on a provider-neutral chat request and typed stream events. Native adapters translate provider-specific formats at the boundary. This allows applications to preserve one request/response contract while providers evolve their preferred API surfaces.
+
+## Universal OpenAI-compatible adapter
+
+The long tail is served by `OpenCompatProvider(base_url, api_key, provider_name)`. A new provider that exposes `/chat/completions` does not require an Arova release. Native adapters are reserved for providers whose authentication, payload, or stream semantics materially differ.
+
+## No implicit network discovery
+
+The bundled price table is static and source-controlled. Arova never makes an extra pricing request during a completion, which keeps latency and failure modes predictable. Unknown prices produce a zero estimate and are explicitly documented as unknown rather than free.
+
+## Streaming safety
+
+SSE parsing is isolated in `arova.sse`, handles keep-alives and malformed records, and never silently turns an upstream malformed chunk into a successful text response. Tool-call fragments are represented as deltas and can be reassembled after the stream.
+
+## Authentication
+
+Provider keys are read from conventional environment variables, but every adapter accepts an explicit key. Azure deployment and API-version configuration and Bedrock region configuration are also explicit. AWS IAM signing is intentionally not bundled because adding a cloud SDK would violate the runtime dependency constraint; users can place an authenticated gateway in front of the adapter.

arova-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

arova-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.3
+Name: arova
+Version: 0.1.0
+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).

arova-0.1.0/PUBLISH.md

@@ -0,0 +1,25 @@
+# Publishing Arova to PyPI
+
+This project intentionally does **not** upload to PyPI. The following procedure is provided for a maintainer who has reviewed the package and configured a PyPI token.
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements-dev.txt
+ruff check .
+pytest
+rm -rf dist build *.egg-info
+python -m build
+ twine check dist/*
+```
+
+After reviewing the generated sdist and wheel, configure a token as an environment variable and publish using the username `__token__`:
+
+```bash
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-...
+twine upload dist/*
+```
+
+Never commit the token. For a release, update the version, review `RESEARCH.md` and the static pricing snapshot, run the full checklist, and verify that `arova/py.typed` is present in the wheel before upload.

arova-0.1.0/README.md

@@ -0,0 +1,110 @@
+# 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).

arova-0.1.0/RESEARCH.md

@@ -0,0 +1,88 @@
+# Arova provider research
+
+**Research snapshot:** 26 August 2026. Provider APIs and prices change frequently; this document records the interface assumptions used by Arova 0.1.0 and identifies which rows are implemented natively versus through the universal OpenAI-compatible adapter.
+
+## Executive findings
+
+Arova should keep a small synchronous core around `httpx`, `pydantic`, and `anyio` rather than depend on vendor SDKs. OpenAI's current documentation centers the Responses API for text, structured output, tools, and multimodal workflows, while Gemini's documentation now recommends the Interactions API for new projects and describes `generateContent` as legacy [1] [2]. Arova 0.1.0 deliberately exposes a stable chat-completion-shaped canonical interface and keeps provider-specific translation inside adapters, so the public API does not change when an upstream provider changes its preferred surface.
+
+Anthropic's direct REST API remains a Messages API at `https://api.anthropic.com/v1/messages`, with explicit `anthropic-version` and API-key headers [3]. The adapter therefore maps system messages, tools, tool-use blocks, and Anthropic content-block SSE events explicitly instead of assuming OpenAI wire compatibility.
+
+## Provider and endpoint matrix
+
+The compatibility column means compatibility with the common OpenAI Chat Completions request/response shape, not that the provider offers every OpenAI feature. A value of **Yes** means a documented compatible route or a widely used compatible gateway surface; **Partial** means compatibility exists but features or authentication differ; **No** means Arova uses a native translation.
+
+| Provider | Representative endpoint or base URL | OpenAI-compatible? | Arova route in 0.1.0 | Notes |
+|---|---|---:|---|---|
+| OpenAI | `https://api.openai.com/v1` | Partial | Native OpenAI-compatible adapter | Current docs emphasize Responses API; chat surface remains useful for a stable common denominator [1]. |
+| Azure OpenAI | Azure resource endpoint, deployment route, `api-version` query | Partial | Native Azure adapter | Uses `api-key` and deployment-aware URLs. |
+| Anthropic | `https://api.anthropic.com/v1/messages` | No | Native adapter | Messages API and Anthropic SSE event types [3]. |
+| Google Gemini | `https://generativelanguage.googleapis.com/v1beta` | No | Native adapter | `generateContent` and `streamGenerateContent`; Interactions API is the current forward-looking surface [2]. |
+| Vertex AI | Regional Google Cloud publisher/model endpoints | No | `opencompat` or caller gateway | OAuth/service-account signing is intentionally outside the six-package runtime. |
+| AWS Bedrock | `https://bedrock-runtime.{region}.amazonaws.com` | No | Native Converse adapter | Caller supplies bearer credentials or an authenticated gateway; no `boto3` dependency. |
+| Mistral | `https://api.mistral.ai/v1` | Yes/Partial | Native-default adapter | Chat Completions-shaped surface with Mistral-specific model/tool quirks. |
+| Cohere | `https://api.cohere.com/v2` | Partial | Native-default adapter | v2 Chat has provider-specific content and tool semantics. |
+| Groq | `https://api.groq.com/openai/v1` | Yes | Native-default adapter | OpenAI-compatible endpoint. |
+| DeepSeek | `https://api.deepseek.com/v1` | Yes | Native-default adapter | OpenAI-compatible chat surface. |
+| xAI (Grok) | `https://api.x.ai/v1` | Yes | Native-default adapter | OpenAI-compatible chat surface. |
+| Together AI | `https://api.together.xyz/v1` | Yes | Universal adapter | Supply `base_url`, model, and key. |
+| Fireworks AI | `https://api.fireworks.ai/inference/v1` | Yes | Universal adapter | Supply `base_url`, model, and key. |
+| OpenRouter | `https://openrouter.ai/api/v1` | Yes | Universal adapter | Routes many upstream model families. |
+| Hugging Face Inference Providers | Provider-specific or HF router endpoint | Partial | Universal adapter | Model/provider routing and headers vary. |
+| Ollama | `http://localhost:11434/v1` | Yes | Universal adapter | Local OpenAI-compatible route. |
+| vLLM | Caller-hosted `/v1` | Yes | Universal adapter | OpenAI-compatible server. |
+| LM Studio | `http://localhost:1234/v1` | Yes | Universal adapter | Official docs describe reusing OpenAI clients by changing `base_url` [4]. |
+| Replicate | `https://api.replicate.com/v1` | No | Universal gateway only | Prediction API is not a direct chat-completions wire equivalent. |
+| AI21 | AI21 Studio API base | Partial | Universal gateway only | Model and endpoint availability vary by account. |
+| Writer | Writer API base | Partial | Universal gateway only | Provider-specific auth and model catalog. |
+| Perplexity | `https://api.perplexity.ai` | Yes/Partial | Universal adapter | Chat-shaped API with search-grounded response metadata. |
+| Cerebras | Cerebras inference API base | Yes/Partial | Universal adapter | OpenAI-compatible serving surface for supported models. |
+| SambaNova | SambaNova Cloud API base | Yes/Partial | Universal adapter | OpenAI-compatible serving surface for supported deployments. |
+| NVIDIA NIM | Caller-hosted `/v1` | Yes | Universal adapter | OpenAI-compatible local or hosted inference routes. |
+| DeepInfra | `https://api.deepinfra.com/v1/openai` | Yes | Universal adapter | OpenAI-compatible model gateway. |
+| Anyscale Endpoints | Provider/account-specific | Partial | Universal adapter | Availability and URL depend on deployment. |
+| Baseten | Deployment-specific `/v1` | Partial | Universal adapter | OpenAI-compatible when enabled by deployment. |
+| Modal | Caller-hosted or deployment-specific | Partial | Universal adapter | Endpoint is deployment-specific. |
+| Novita AI | Provider API base | Yes/Partial | Universal adapter | OpenAI-compatible gateway for supported models. |
+| AI Horde | Community inference API | No | Universal gateway only | Queue-based API; not assumed to be low-latency chat. |
+
+The implementation strategy is therefore **ten named native adapters plus one universal adapter**. The universal adapter is the extensibility boundary: any provider implementing `/chat/completions` can be used without a new Arova release by supplying `base_url`, `model`, and `api_key`.
+
+## Price snapshot
+
+Prices below are representative public list prices in USD per one million tokens and are bundled as an auditable static table in `arova.cost`. They are not a billing guarantee. OpenAI's official pricing page explicitly distinguishes input, cached input, cache writes, and output and currently shows the representative flagship values used by this release [5]. Other rows are representative model prices gathered from the linked provider pricing or model documentation and should be refreshed before production cost accounting.
+
+| Provider/model | Input $/M | Output $/M | Bundled? |
+|---|---:|---:|---:|
+| OpenAI `gpt-5.6-sol` | 4.00 | 20.00 | Yes |
+| OpenAI `gpt-5.6-terra` | 2.00 | 12.00 | Yes |
+| OpenAI `gpt-5.6-luna` | 0.20 | 1.20 | Yes |
+| Anthropic `claude-opus-4.1` | 15.00 | 75.00 | Yes |
+| Anthropic `claude-sonnet-4.0` | 3.00 | 15.00 | Yes |
+| Gemini `gemini-3.7-pro` | 2.00 | 12.00 | Yes |
+| Gemini `gemini-3.7-flash` | 0.30 | 2.50 | Yes |
+| Mistral `mistral-large-latest` | 2.00 | 6.00 | Yes |
+| Groq `llama-3.3-70b-versatile` | 0.59 | 0.79 | Yes |
+| DeepSeek `deepseek-chat` | 0.28 | 0.42 | Yes |
+| xAI `grok-4` | 3.00 | 15.00 | Yes |
+| OpenRouter, Ollama, vLLM, LM Studio | caller/provider price | caller/provider price | wildcard $0 |
+
+A zero wildcard price means "no price is known to Arova," not "the service is always free." Applications should treat an unrecognized or wildcard price as an estimate of zero and replace the table for contractual billing.
+
+## LiteLLM complaints and explicit Arova responses
+
+A LiteLLM issue reports that the core pip installation includes proxy code and related dependencies, with a reported footprint of approximately 28 MB or more and approximately 12 MB of proxy code alone [6]. Arova addresses this by keeping the runtime dependency set to `httpx`, `pydantic`, `anyio`, and their small transitive requirements; it does not ship a proxy server, FastAPI, Uvicorn, vendor SDKs, LangChain, or a large plugin registry.
+
+A separate LiteLLM discussion reports a user's direct-call latency of roughly 1.6–2 seconds increasing to roughly 4–4.5 seconds through a proxy in a TGI setup [7]. This is a single user report, not a controlled benchmark, but it motivates Arova's performance hygiene: module-level client reuse, HTTP/2 and connection pooling, no per-call imports, no network pricing lookup, and no mandatory observability middleware in the hot path.
+
+The project also treats streaming correctness as a first-class concern. The `arova.sse` parser accepts keep-alive comments, partial records, multi-line data, `[DONE]`, and malformed chunks without crashing the entire stream; provider adapters then normalize text, reasoning, tool-call deltas, usage, finish, and error events.
+
+## References
+
+[1]: https://developers.openai.com/api/docs "OpenAI API Platform Documentation"
+[2]: https://ai.google.dev/gemini-api/docs "Google Gemini API Documentation"
+[3]: https://platform.claude.com/docs/en/api/overview "Anthropic Claude API Overview"
+[4]: https://lmstudio.ai/docs/developer/openai-compat "LM Studio OpenAI Compatibility"
+[5]: https://developers.openai.com/api/docs/pricing "OpenAI API Pricing"
+[6]: https://github.com/BerriAI/litellm/issues/15262 "LiteLLM issue: separate proxy dependencies/code from core SDK"
+[7]: https://github.com/BerriAI/litellm/discussions/4298 "LiteLLM discussion: how to reduce proxy latency"

arova-0.1.0/arova/__init__.py

@@ -0,0 +1,16 @@
+"""Arova — one API, every model, zero ceremony."""
+from .client import Arova, acompletion, astream, completion, provider_registry, stream
+from .stream import ErrorEvent, Finish, ReasoningDelta, TextDelta, ToolCallDelta, UsageEvent
+from .types import (
+    ChatRequest, ChatResponse, FinishReason, Message, ModelInfo, ProviderCapabilities,
+    ResponseFormat, ToolCall, ToolDefinition, Usage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Arova", "completion", "acompletion", "stream", "astream", "provider_registry",
+    "Message", "ToolCall", "ToolDefinition", "ResponseFormat", "ChatRequest", "ChatResponse", "Usage",
+    "FinishReason", "ModelInfo", "ProviderCapabilities", "TextDelta", "ToolCallDelta", "ReasoningDelta",
+    "UsageEvent", "Finish", "ErrorEvent",
+]

arova-0.1.0/arova/cli.py

@@ -0,0 +1,76 @@
+"""Command-line interface for Arova."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import Arova, provider_registry
+from .cost import PRICE_TABLE, cost_for_usage
+from .types import Message, Usage
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="arova", description="One API. Every model. Zero ceremony.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    chat = sub.add_parser("chat", help="Start a simple chat REPL")
+    chat.add_argument("--model", default="openai/gpt-5.6-luna")
+    models = sub.add_parser("models", help="List bundled provider/model price entries")
+    models.add_argument("--provider")
+    cost = sub.add_parser("cost", help="Calculate cost from token counts")
+    cost.add_argument("provider")
+    cost.add_argument("model")
+    cost.add_argument("--input-tokens", type=int, default=0)
+    cost.add_argument("--output-tokens", type=int, default=0)
+    cost.add_argument("--cached-input-tokens", type=int, default=0)
+    return parser
+
+
+def _cmd_models(provider: str | None) -> int:
+    rows = [price for price in PRICE_TABLE if provider is None or price.provider == provider]
+    print("provider\tmodel\tinput/$M\toutput/$M")
+    for price in rows:
+        print(f"{price.provider}\t{price.model}\t{price.input_per_million:g}\t{price.output_per_million:g}")
+    if provider and provider not in provider_registry():
+        print(f"Unknown provider: {provider}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def _cmd_cost(args: argparse.Namespace) -> int:
+    usage = Usage(input_tokens=args.input_tokens, output_tokens=args.output_tokens, cached_input_tokens=args.cached_input_tokens).normalized()
+    print(json.dumps({"provider": args.provider, "model": args.model, "usage": usage.model_dump(), "cost_usd": cost_for_usage(args.provider, args.model, usage)}, indent=2))
+    return 0
+
+
+def _cmd_chat(args: argparse.Namespace) -> int:
+    print(f"Arova chat — {args.model}. Type /exit to quit.")
+    client = Arova()
+    messages: list[Message] = []
+    try:
+        while True:
+            line = input("you> ")
+            if line.strip() == "/exit":
+                return 0
+            if not line.strip():
+                continue
+            messages.append(Message(role="user", content=line))
+            response = client.completion(args.model, messages)
+            print(f"assistant> {response.text}")
+            messages.append(response.message)
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "models":
+        return _cmd_models(args.provider)
+    if args.command == "cost":
+        return _cmd_cost(args)
+    return _cmd_chat(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())