Metadata-Version: 2.4
Name: omniai-kit
Version: 1.0.1
Summary: Official Python client SDK for OmniAI Gateway and Dynamic Multi-Provider LLM Router
Author-email: OmniAI Team <dev@omniai.ai>, Jayed Bin Jahangir <jayedbinjahangir@gmail.com>
Maintainer-email: Jayed Bin Jahangir <jayedbinjahangir@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://omniai.go-agents.app
Project-URL: Documentation, https://omniai.go-agents.app/docs
Project-URL: Repository, https://github.com/jayeeed/omniai-sdk
Project-URL: Issues, https://github.com/jayeeed/omniai-sdk/issues
Project-URL: Changelog, https://github.com/jayeeed/omniai-sdk
Keywords: omniai,llm,ai,gateway,router,openai,gemini,anthropic,vllm,livekit,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: google-genai>=0.1.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.1.0; extra == "gemini"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: vllm
Requires-Dist: openai>=1.0.0; extra == "vllm"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# OmniAI Kit (`omniai-kit`) 🚀

[![PyPI version](https://img.shields.io/pypi/v/omniai-kit.svg?color=blue)](https://pypi.org/project/omniai-kit/)
[![GitHub repository](https://img.shields.io/badge/GitHub-omniai--sdk-181717?logo=github)](https://github.com/jayeeed/omniai-sdk)
[![Python versions](https://img.shields.io/pypi/pyversions/omniai-kit.svg)](https://pypi.org/project/omniai-kit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Type Checked: PEP 561](https://img.shields.io/badge/typing-PEP%20561-blue.svg)](https://peps.python.org/pep-0561/)
[![Status: Production/Stable](https://img.shields.io/badge/status-production-success.svg)](https://omniai.go-agents.app)

Official Python Client SDK for the **OmniAI Platform & AI Gateway** — providing zero-config multi-provider LLM routing, real-time token streaming, native Pydantic structured outputs, background task queues, and WebRTC multimodal live voice/video sessions.

---

## ⚡ Features

- **Zero-Configuration Setup:** Automatically loads credentials (`OMNIAI_API_KEY`, `OMNI_API_KEY`, `X_API_KEY`) and defaults to `https://omniai.go-agents.app`.
- **Modern Resource Architecture:** Clean OpenAI-style resource hierarchy (`client.chat.completions.create`, `client.models.list`, `client.tasks.submit`, `client.livekit.create_session`) plus ergonomic top-level shortcuts (`client.chat`, `client.stream`).
- **Synchronous & Asynchronous:** Identical API surfaces for both synchronous (`OmniaiClient`) and async (`AsyncOmniaiClient`) applications.
- **Strongly Typed Pydantic Schemas:** Pass Pydantic models directly to `response_model` for guaranteed schema validation and markdown JSON stripping.
- **Resilient Real-Time Streaming:** Server-Sent Events (SSE) streaming engine with auto-reconnect and keep-alive handling.
- **Enterprise Fault Tolerance:** Built-in exponential backoff with full jitter, honoring upstream `Retry-After` headers on 429 and 5xx errors.
- **Background Tasks:** Submit compute-heavy completions to the Celery background queue and poll reliably with `job.wait()`.
- **LiveKit Multimodal Sessions:** Generate signed WebRTC access tokens for ultra-low latency Gemini Live audio and video agents.

---

## 📦 Installation

```bash
pip install omniai-kit
```

### Optional Provider Dependencies (for direct standalone routing)
```bash
pip install "omniai-kit[all]"        # Installs all upstream provider SDKs
pip install "omniai-kit[openai]"     # Installs OpenAI SDK
pip install "omniai-kit[gemini]"     # Installs Google GenAI SDK
pip install "omniai-kit[anthropic]"  # Installs Anthropic SDK
```

---

## 🏛️ Supported Model Providers

OmniAI natively routes and normalizes parameters across the following providers:

| Provider | Schema | Example Models |
| :--- | :--- | :--- |
| **OpenAI** | `openai:<model>` | `openai:gpt-4o`, `openai:o3-mini`, `openai:gpt-4o-mini` |
| **Google Gemini** | `gemini:<model>` | `gemini:gemini-2.5-flash`, `gemini:gemini-3.7-flash` |
| **Anthropic** | `anthropic:<model>` | `anthropic:claude-3-5-sonnet-20241022`, `anthropic:claude-3-opus` |
| **vLLM (Self-Hosted)** | `vllm:<model>` | `vllm:meta-llama/Llama-3.1-8B-Instruct` |
| **OpenRouter** | `openrouter:<model>` | `openrouter:anthropic/claude-3.5-sonnet` |
| **Ollama (Local)** | `ollama:<model>` | `ollama:qwen2.5-coder:7b` |

---

## 🚀 Quickstart

### 1. Basic Chat Completion

```python
from omniai import OmniaiClient

# Automatically discovers OMNIAI_API_KEY from environment or .env
client = OmniaiClient()

response = client.chat(
    model="gemini:gemini-2.5-flash",
    prompt="Explain distributed event streaming in two concise sentences.",
)
print(response)
```

Both direct shortcut and resource styles are supported:
```python
# Shortcut style
response = client.chat(model="gemini:gemini-2.5-flash", prompt="Hello!")

# Resource hierarchy style (OpenAI-compatible)
response = client.chat.completions.create(model="gemini:gemini-2.5-flash", prompt="Hello!")
```

---

### 2. Real-Time Token Streaming

```python
from omniai import OmniaiClient

client = OmniaiClient()

print("Assistant: ", end="", flush=True)
for token in client.stream(
    model="gemini:gemini-2.5-flash",
    prompt="List 3 key architectural benefits of event-driven microservices.",
):
    print(token, end="", flush=True)
print()
```

---

### 3. Strongly Typed Structured Outputs (Pydantic V2)

Pass any Pydantic class to `response_model`. The SDK extracts JSON schema, enforces structured output from the model, and automatically parses and validates the response into your Python model:

```python
from typing import List
from pydantic import BaseModel, Field
from omniai import OmniaiClient

class ServiceArchitecture(BaseModel):
    service_name: str = Field(description="Name of the service")
    patterns: List[str] = Field(description="Design patterns applied")
    availability_sla: float = Field(description="Target SLA percentage")

client = OmniaiClient()

analysis: ServiceArchitecture = client.chat(
    model="gemini:gemini-2.5-flash",
    prompt="Design a high-throughput payment processing service.",
    response_model=ServiceArchitecture,
)

print(f"Service: {analysis.service_name}")
print(f"Patterns: {analysis.patterns}")
print(f"Target SLA: {analysis.availability_sla}%")
```

---

### 4. Asynchronous Client (`AsyncOmniaiClient`)

Full async/await parity for high-concurrency microservices, FastAPI, and async workers:

```python
import asyncio
from omniai import AsyncOmniaiClient

async def main():
    async with AsyncOmniaiClient() as client:
        # Async chat
        res = await client.chat(
            model="gemini:gemini-2.5-flash",
            prompt="Summarize CQRS in 20 words.",
        )
        print("Response:", res)

        # Async streaming
        print("Streaming: ", end="", flush=True)
        async for chunk in client.stream(
            model="gemini:gemini-2.5-flash",
            prompt="Count from 1 to 5.",
        ):
            print(chunk, end="", flush=True)
        print()

asyncio.run(main())
```

---

### 5. Background Task Queue (Celery Integration)

Queue long-running jobs to the background Celery cluster with fault-tolerant polling that survives transient network dropouts:

```python
from omniai import OmniaiClient
from pydantic import BaseModel

class ComprehensiveAudit(BaseModel):
    vulnerabilities: list[str]
    risk_score: int

client = OmniaiClient()

# 1. Submit task asynchronously
job = client.submit_task(
    model="gemini:gemini-2.5-flash",
    prompt="Perform in-depth threat modeling for an open S3 bucket with public access.",
    response_model=ComprehensiveAudit,
)
print(f"Dispatched Celery Task ID: {job.task_id}")

# 2. Poll until complete with automatic error-tolerance
result: ComprehensiveAudit = job.wait(timeout=120.0, interval=2.0)
print("Task finished successfully!")
print(f"Risk Score: {result.risk_score}")
```

---

### 6. LiveKit Multimodal Real-Time Voice & Video

Create WebRTC sessions for sub-second bidirectional voice and vision agents:

```python
from omniai import OmniaiClient

client = OmniaiClient()

session = client.create_live_session(
    model="gemini:gemini-2.5-flash",
    voice="Aoede",
    video_input=True,
)

print(f"LiveKit Server: {session.server_url}")
print(f"Room:           {session.room_name}")
print(f"Token:          {session.participant_token}")
```

---

### 7. Model Discovery & Catalog

Query available models dynamically from the gateway:

```python
from omniai import OmniaiClient

client = OmniaiClient()

models = client.models.list()
print(f"Total available models: {len(models.data)}")
for m in models.data[:5]:
    print(f"  • {m.id} (provider: {m.provider}, release: {m.release_date})")
```

---

## 🔑 Authentication & Configuration

`OmniaiClient` and `AsyncOmniaiClient` resolve configuration in the following order:

| Setting | 1. Explicit Argument | 2. Environment Variables (`.env`) | 3. Default Fallback |
| :--- | :--- | :--- | :--- |
| **`api_key`** | `OmniaiClient(api_key="...")` | `OMNIAI_API_KEY` &rarr; `OMNI_API_KEY` &rarr; `X_API_KEY` | `""` |
| **`base_url`** | `OmniaiClient(base_url="...")` | `OMNIAI_BASE_URL` &rarr; `OMNI_BASE_URL` &rarr; `GATEWAY_URL` | `"https://omniai.go-agents.app"` |
| **`timeout`** | `OmniaiClient(timeout=30.0)` | — | `60.0` seconds |
| **`max_retries`**| `OmniaiClient(max_retries=5)`| — | `3` attempts |

Create a `.env` file in your project directory:
```env
OMNIAI_API_KEY=sk-or-v1-your-api-key-here
```

---

## 🛡️ Exception Hierarchy

All SDK exceptions inherit from `OmniaiError`:

```text
OmniaiError
├── OmniaiAuthError             # HTTP 401 / 403 (Invalid or revoked API key)
├── OmniaiPaymentRequiredError  # HTTP 402 (Prepaid credit balance exhausted)
├── OmniaiNotFoundError         # HTTP 404 (Resource or model not found)
├── OmniaiRateLimitError        # HTTP 429 (Rate limit exceeded; includes .retry_after)
├── OmniaiTimeoutError          # Request or polling timeout
├── OmniaiConnectionError       # DNS, connection drop, network failure
├── OmniaiExecutionError        # HTTP 5xx or upstream provider execution failure
├── OmniaiValidationError      # Output failed Pydantic schema validation
└── OmniaiUnsupportedProviderError # Request for an unsupported provider prefix
```

---

## 📂 Repository Directory Pattern

```text
omniai-sdk/
├── .github/
│   └── workflows/
│       └── pypi-publish.yml    # PyPI publishing workflow
├── omniai/
│   ├── resources/              # Modular resource namespaces
│   │   ├── chat.py
│   │   ├── livekit.py
│   │   ├── models.py
│   │   ├── router.py
│   │   └── tasks.py
│   ├── types/                  # Typed Pydantic schemas
│   │   ├── chat.py
│   │   ├── livekit.py
│   │   ├── models.py
│   │   └── tasks.py
│   ├── __init__.py             # Top-level exports
│   ├── _base.py                # Base HTTP transport & retry policy
│   ├── _constants.py           # Default constants & endpoints
│   ├── _version.py             # Package version (1.0.0)
│   ├── client.py               # OmniaiClient & AsyncOmniaiClient
│   ├── exceptions.py           # Typed exception hierarchy
│   └── py.typed                # PEP 561 typing compliance
├── examples/
│   ├── quickstart.py
│   ├── streaming.py
│   ├── structured_output.py
│   └── async_chat.py
├── tests/                      # Unit and integration test suite
├── .env.example
├── .gitignore
├── LICENSE                     # MIT License
├── README.md                   # Documentation & Guides
├── pyproject.toml              # PEP 517/621 packaging metadata
├── requirements.txt            # Core dependencies (httpx, pydantic)
└── test.py                     # Root test script for quick validation
```

---

## 🧪 Testing

Run the test suite with `pytest`:

```bash
pytest tests
```

Or run the quick root validation script:

```bash
python test.py
```

---

## 📄 License

MIT © [OmniAI Team](https://omniai.go-agents.app) — Jayed Bin Jahangir
