omniai-kit 1.0.0__tar.gz → 1.1.0__tar.gz

omniai_kit-1.1.0/PKG-INFO

@@ -0,0 +1,438 @@
+Metadata-Version: 2.4
+Name: omniai-kit
+Version: 1.1.0
+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 & Universal AI Gateway** — providing zero-config multi-provider LLM routing, real-time SSE token streaming, native Pydantic structured outputs, extended reasoning token budgets (`thinking`), background task queues, Custom AI Agents with RAG knowledge bases, scoped API key management, and real-time WebRTC multimodal live voice/video sessions.
+
+---
+
+## ⚡ Key Capabilities
+
+- **Zero-Configuration Setup:** Auto-discovers 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`, `client.agents`, `client.keys`) plus ergonomic top-level shortcuts (`client.chat`, `client.stream`, `client.execute_agent`).
+- **Full Response & Billing Visibility:** Pass `full_response=True` to inspect completion ID, exact micro-dollar request cost (`0.000001`), cumulative API key spend, remaining budget, account tier, and granular prompt token details (`system_tokens`, `input_tokens`).
+- **Extended Reasoning / Thinking Tokens:** Pass `thinking=1024` for reasoning models (e.g. Gemini 3.7 Flash, Claude 3.7 Sonnet, o3-mini) with automatic thinking block handling.
+- **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.
+- **Custom AI Agents & RAG:** Create autonomous agents, upload documents to Qdrant vector knowledge bases, attach dynamic tools, and execute agents with context.
+- **Scoped API Key Management:** Programmatically provision API keys with spending limits (`total_limit`), expiration dates (`expires_at`), and model access control (`allowed_models`).
+- **Enterprise Fault Tolerance:** Built-in exponential backoff with full jitter, honoring upstream `Retry-After` headers on 429 and 5xx errors.
+- **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, caches, and normalizes parameters across the following providers:
+
+| Provider | Schema | Example Models |
+| :--- | :--- | :--- |
+| **Google Gemini** | `gemini:<model>` | `gemini:gemini-2.5-flash`, `gemini:gemini-3.7-flash`, `gemini-3.8-live` |
+| **OpenAI** | `openai:<model>` | `openai:gpt-4o`, `openai:o3-mini`, `openai:gpt-4o-mini` |
+| **Anthropic** | `anthropic:<model>` | `anthropic:claude-3-7-sonnet`, `anthropic:claude-3-5-haiku` |
+| **OpenRouter** | `openrouter:<model>` | `openrouter:inclusionai/ling-3.2-flash:free`, `openrouter:meta-llama/llama-3.3-70b-instruct` |
+| **vLLM (Self-Hosted)** | `vllm:<model>` | `vllm:meta-llama/Llama-3.1-8B-Instruct` |
+| **Ollama (Local)** | `ollama:<model>` | `ollama:qwen2.5-coder:7b` |
+
+---
+
+## 🚀 Usage Guide
+
+### 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. Full Response Envelope & Billing Inspection
+
+Pass `full_response=True` to inspect exact token counts, cache hits, and request cost:
+
+```python
+from omniai import OmniaiClient, ChatCompletionResponse
+
+client = OmniaiClient()
+
+resp: ChatCompletionResponse = client.chat(
+    model="openrouter:inclusionai/ling-3.2-flash:free",
+    prompt="Explain quantum entanglement briefly.",
+    full_response=True,
+)
+
+print(f"Result: {resp.result}")
+print(f"ID: {resp.id}")
+print(f"Cached: {resp.cached}")
+print(f"Tokens: {resp.usage.total_tokens} (prompt={resp.usage.prompt_tokens}, completion={resp.usage.completion_tokens})")
+print(f"  System Tokens: {resp.usage.details.system_tokens}")
+print(f"  User Input Tokens: {resp.usage.details.input_tokens}")
+print(f"Request Cost: ${resp.billing.request_cost:.6f} USD")
+print(f"Key Cumulative Spend: ${resp.billing.api_key.spent:.6f} USD")
+print(f"Account Balance Remaining: ${resp.billing.account.balance_remaining:.6f} USD")
+```
+
+---
+
+### 3. Extended Reasoning / Thinking Budget
+
+Allocate reasoning tokens for models that support chain-of-thought thinking (e.g. Gemini 3.7 Flash, Claude 3.7 Sonnet):
+
+```python
+response = client.chat(
+    model="gemini:gemini-3.7-flash",
+    prompt="How many r's are in strawberry?",
+    thinking=1024,  # Allocates 1,024 reasoning tokens
+)
+print(response)
+```
+
+---
+
+### 4. Real-Time Token Streaming
+
+Stream completions token-by-token with Server-Sent Events (SSE):
+
+```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()
+```
+
+---
+
+### 5. 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}%")
+```
+
+---
+
+### 6. Custom AI Agents & Vector Knowledge Bases
+
+Create autonomous custom agents, ingest reference documents into Qdrant vector memory, and execute queries:
+
+```python
+from omniai import OmniaiClient
+
+client = OmniaiClient()
+
+# 1. Create a custom agent
+agent = client.agents.create(
+    name="Refund Policy Assistant",
+    prompt="You are a refund specialist. Answer user questions strictly based on the company's 30-day guarantee.",
+    model="gemini:gemini-3.8-flash",
+)
+
+# 2. Add document to agent's vectorized knowledge base
+client.agents.knowledge.add(
+    agent_id=agent.id,
+    title="Refund Policy v2",
+    content="Customers can request a 100% refund within 30 days of purchase for unopened items.",
+)
+
+# 3. Execute the agent
+answer = client.execute_agent(
+    agent_id=agent.id,
+    message="What is the refund window for an unopened box?",
+)
+print("Agent:", answer)
+```
+
+---
+
+### 7. Scoped API Key Management
+
+Programmatically provision, monitor, and revoke API keys with spend quotas and allowed models:
+
+```python
+from omniai import OmniaiClient
+
+client = OmniaiClient()
+
+# 1. Create API key with $25 lifetime spend limit and model restrictions
+new_key = client.keys.create(
+    name="staging-bot",
+    total_limit=25.0,  # $25.00 lifetime spending limit
+    allowed_models=["openai:gpt-4o", "gemini:gemini-3.7-flash"],
+    expires_at="2027-12-31T23:59:59Z",
+)
+print(f"Key created: {new_key.name} -> {new_key.key}")
+
+# 2. List all active keys
+keys = client.keys.list()
+for k in keys:
+    print(f"Key: {k.name} | Spent: ${k.current_spend:.4f} / ${k.total_limit or 'Unlimited'}")
+
+# 3. Revoke key
+client.keys.delete(new_key.id)
+```
+
+---
+
+### 8. 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-3.8-live",
+    voice="Aoede",
+    video_input=True,
+)
+
+print(f"LiveKit Server: {session.server_url}")
+print(f"Room:           {session.room_name}")
+print(f"Token:          {session.participant_token}")
+```
+
+---
+
+### 9. 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 with reasoning tokens
+        res = await client.chat(
+            model="gemini:gemini-3.7-flash",
+            prompt="Summarize CQRS in 20 words.",
+            thinking=1024,
+        )
+        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())
+```
+
+---
+
+## 🔑 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 |
+
+---
+
+## 🛡️ 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 Layout
+
+```text
+omniai-sdk/
+├── omniai/
+│   ├── resources/              # Modular resource namespaces
+│   │   ├── chat.py             # Chat completions & SSE streaming
+│   │   ├── agents.py           # Custom AI agents & RAG knowledge
+│   │   ├── keys.py             # Scoped API key management
+│   │   ├── livekit.py          # Multimodal WebRTC voice/video
+│   │   ├── models.py           # Foundation models catalog
+│   │   ├── router.py           # Multi-provider LLM router
+│   │   └── tasks.py            # Celery background tasks
+│   ├── types/                  # Typed Pydantic schemas
+│   │   ├── chat.py             # Response, usage, billing envelopes
+│   │   ├── agents.py           # Agent, tool, knowledge models
+│   │   ├── keys.py             # API key records
+│   │   ├── livekit.py          # Live session credentials
+│   │   ├── models.py           # Foundation model metadata
+│   │   └── tasks.py            # Task handles and job wrappers
+│   ├── __init__.py             # Top-level SDK exports
+│   ├── _base.py                # Base HTTP transport & retry policy
+│   ├── _constants.py           # Default constants & endpoints
+│   ├── _version.py             # Package version (1.1.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
+│   ├── thinking_reasoning.py
+│   ├── custom_agents.py
+│   └── api_keys.py
+├── tests/                      # Unit and integration test suite
+├── test.py                     # Root verification script
+├── pyproject.toml              # PEP 517/621 packaging metadata
+└── README.md                   # Documentation & Guides
+```
+
+---
+
+## 🧪 Testing
+
+Run the test suite with `pytest`:
+
+```bash
+pytest tests
+```
+
+Or run the root verification script:
+
+```bash
+python test.py
+```
+
+---
+
+## 📄 License
+
+MIT © [OmniAI Team](https://omniai.go-agents.app) — Jayed Bin Jahangir