omniai-kit 1.0.0__py3-none-any.whl

omniai_kit-1.0.0.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: omniai-kit
+Version: 1.0.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/blob/main/CHANGELOG.md
+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 Python Client SDK (`omniai`)
+
+[![PyPI version](https://img.shields.io/pypi/v/omniai.svg)](https://pypi.org/project/omniai/)
+[![Python versions](https://img.shields.io/pypi/pyversions/omniai.svg)](https://pypi.org/project/omniai/)
+[![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/)
+
+Official, production-ready Python client SDK for the **OmniAI AI Gateway** and **Dynamic Multi-Provider LLM Router**.
+
+---
+
+## 🏛️ Supported Providers
+
+The OmniAI SDK is strictly engineered and validated for the following **4 model providers**:
+
+| Provider | Identifier Schema | Description & Examples |
+| :--- | :--- | :--- |
+| **OpenAI** | `openai:<model>` | Standard and reasoning models (`openai:gpt-4o`, `openai:o3-mini`) |
+| **Google Gemini** | `gemini:<model>` | Google AI Multimodal models (`gemini:gemini-2.5-flash`, `gemini:gemini-3.7-flash`) |
+| **Anthropic** | `anthropic:<model>` | Claude reasoning & coding models (`anthropic:claude-3-5-sonnet`, `anthropic:claude-3-opus`) |
+| **vLLM (Self-Hosted)** | `vllm:<model>` | High-throughput self-hosted inference servers (`vllm:meta-llama/Llama-3.1-8B-Instruct`) |
+
+---
+
+## 📦 Installation
+
+Install the lightweight client from PyPI:
+
+```bash
+pip install omniai
+```
+
+### Optional Provider Dependencies (for direct local routing)
+If you wish to use the standalone `RouterEngine` directly within your Python process without an external gateway:
+
+```bash
+pip install "omniai[all]"      # Installs all provider SDKs (openai, google-genai)
+pip install "omniai[openai]"   # Installs openai
+pip install "omniai[gemini]"   # Installs google-genai
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Synchronous Client (`OmniaiClient`)
+
+```python
+from omniai import OmniaiClient
+
+# Automatically defaults base_url="https://omniai.go-agents.app"
+# and auto-loads OMNI_API_KEY from your .env file
+client = OmniaiClient()
+
+# Or pass parameters explicitly:
+# client = OmniaiClient(api_key="your-api-key")
+
+# Call flagship model openai:gpt-5.6-luna
+response = client.chat(
+    model="openai:gpt-5.6-luna",
+    prompt="Explain quantum entanglement in 2 sentences.",
+    temperature=0.7,
+)
+print(response)
+```
+
+### 2. Real-Time Token Streaming
+
+The SDK features a resilient Server-Sent Events (SSE) streaming engine with automatic frame filtering and clean termination:
+
+```python
+from omniai import OmniaiClient
+
+client = OmniaiClient()
+
+for token in client.stream(
+    model="openai:gpt-5.6-luna",
+    prompt="Write a haiku about high-availability microservices.",
+):
+    print(token, end="", flush=True)
+```
+
+### 3. Strongly-Typed Structured Outputs with Pydantic
+
+Pass your Pydantic model directly into `response_model`. The SDK extracts JSON schemas automatically, instructs the upstream provider, and parses the returned JSON into a validated Python instance:
+
+```python
+from pydantic import BaseModel, Field
+from omniai import OmniaiClient
+
+class SecurityAudit(BaseModel):
+    summary: str = Field(..., description="High-level assessment")
+    vulnerabilities: list[str] = Field(..., description="Discovered vulnerability IDs")
+    passed: bool = Field(..., description="Overall security compliance status")
+
+client = OmniaiClient()
+
+audit: SecurityAudit = client.chat(
+    model="openai:gpt-5.6-luna",
+    prompt="Audit this configuration: CORS allowed * with credentials enabled.",
+    response_model=SecurityAudit,
+)
+
+print(audit.summary)
+print(f"Passed: {audit.passed}")
+```
+
+### 4. Self-Hosted vLLM Inference
+
+Connect seamlessly to any self-hosted or cloud vLLM server:
+
+```python
+from omniai import OmniaiClient
+
+# Point to your internal vLLM cluster (or route through OmniAI Gateway)
+client = OmniaiClient(
+    base_url="http://vllm-node.internal:8000/v1",
+    api_key="EMPTY",
+)
+
+response = client.chat(
+    model="vllm:meta-llama/Llama-3.1-8B-Instruct",
+    prompt="Hello from OmniAI!",
+)
+print(response)
+```
+
+### 5. Asynchronous Client (`AsyncOmniaiClient`)
+
+Full `async`/`await` parity for high-concurrency applications:
+
+```python
+import asyncio
+from omniai import AsyncOmniaiClient
+
+async def main():
+    async with AsyncOmniaiClient() as client:
+        # Async chat
+        result = await client.chat(
+            model="openai:gpt-5.6-luna",
+            prompt="Hello async world!",
+        )
+        print(result)
+
+        # Async streaming
+        async for chunk in client.stream(model="openai:gpt-5.6-luna", prompt="Count to 3."):
+            print(chunk, end="", flush=True)
+
+asyncio.run(main())
+```
+
+### 6. Fault-Tolerant Background Celery Tasks
+
+Queue long-running jobs to the background Celery cluster with automatic polling resilience:
+
+```python
+from omniai import OmniaiClient
+
+client = OmniaiClient()
+
+# Submit task asynchronously to the queue
+job = client.submit_task(
+    model="openai:gpt-5.6-luna",
+    prompt="Analyze 50 pages of financial records.",
+)
+print(f"Dispatched task ID: {job.task_id}")
+
+# Fault-tolerant polling that survives temporary network dropouts
+result = job.wait(timeout=180.0, interval=2.0)
+print(result)
+```
+
+### 7. LiveKit Multimodal Real-Time Voice & Video
+
+Generate signed WebRTC credentials on the fly:
+
+```python
+from omniai import OmniaiClient
+
+client = OmniaiClient()
+
+session = client.create_live_session(
+    model="gemini:gemini-3.1-flash-live-preview",
+    voice="Aoede",
+    participant_identity="agent-caller-01",
+)
+print(f"Connect to room '{session.room_name}' at {session.server_url}")
+print(f"JWT Token: {session.participant_token}")
+```
+
+---
+
+## 🛡️ Production Reliability & Fault Tolerance
+
+The SDK includes enterprise resilience patterns built-in:
+
+1. **Exponential Backoff with Full Jitter**:
+   - Automatically retries transient failures: HTTP 429 (Rate Limit), 500, 502, 503, 504, connection timeouts, and connection reset errors.
+   - Respects upstream `Retry-After` headers.
+   - Configurable via `max_retries: int = 3` and `backoff_factor: float = 0.5`.
+
+2. **Connection Pooling**:
+   - Pre-configured with `httpx.Limits(max_keepalive_connections=20, max_connections=100)`.
+   - Supports explicit lifecycle management via `client.close()` and context managers (`with OmniaiClient() as client:`).
+
+3. **Granular Exception Hierarchy**:
+   - `OmniaiAuthError`: HTTP 401 / 403 invalid or expired credentials.
+   - `OmniaiPaymentRequiredError`: HTTP 402 insufficient prepaid balance.
+   - `OmniaiRateLimitError`: HTTP 429 rate limit exceeded (includes `.retry_after` attribute).
+   - `OmniaiExecutionError`: HTTP 5xx or upstream LLM provider error.
+   - `OmniaiValidationError`: Model output failed schema validation.
+   - `OmniaiTimeoutError`: Polling or network timeout.
+   - `OmniaiConnectionError`: Network drops, DNS resolution failures.
+   - `OmniaiUnsupportedProviderError`: Raised if attempting to route to an unsupported provider.
+
+
+---
+
+## 📄 License
+
+MIT © [OmniAI Team](https://omniai.go-agents.app)

omniai_kit-1.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+omniai/__init__.py,sha256=t_uUXIm27J5XZb12JRqckN3QSGIr86LvID1yBppzCqs,2774
+omniai/_base.py,sha256=mwLKH0OWlr7kgew2axLCayF6U1u_VO9PncoIr3ILQBQ,13996
+omniai/_constants.py,sha256=2XLcrHO8DxkihSgjDAs1Cnetrge0ebBDE6mKBmj9XHE,817
+omniai/_version.py,sha256=c2dQwvLmdQVXd3WsuiCvlH6b19EsU_UwlAA64M1hSlE,78
+omniai/client.py,sha256=ZD70h5-AOgHfygLjYBT-pcqp4-tGQBH203OpLrmd1jc,10257
+omniai/exceptions.py,sha256=3U_9JD0a4yWluSsWmSBvTY-Wbz5hYsxXwZOsKK_DUAE,3333
+omniai/py.typed,sha256=9DkxTFnD5zEW5X5VVNnWT_8k2LgKipvgY_rjy6XFiO8,37
+omniai/resources/__init__.py,sha256=_WI8PNLTgk96RO17izT-MKEoucyMNp0tATZKlXDrY4g,736
+omniai/resources/chat.py,sha256=vfuEhnvYaADim3mw0gkrlfsbcYzJsDhrFS6L1NTcsQo,15078
+omniai/resources/livekit.py,sha256=4m03d_MXXfPiSrgu_fAkPP0bQWoYK_fmVlqI8F3Yce4,2168
+omniai/resources/models.py,sha256=vx9YOTCLYEX5fdct7ht8n9P_JIFXb9_7nSJ_YNR5lxI,2313
+omniai/resources/router.py,sha256=Stjj08BkHDsOXXKjvd96qJGMNsOi2S2gm13kmNBupjU,43286
+omniai/resources/tasks.py,sha256=fTEi-5a_sK0OShzVb7AWEIIDsFjTDTeZ1bwKQHK0dzo,6215
+omniai/types/__init__.py,sha256=AL28TGnjsRyyDZWa3qeVnu4-ABSWA3ns3cDx9jyZkzM,677
+omniai/types/chat.py,sha256=2iZ3W9AIIomSYJLXDH5nqTmkk76xdgXjVnTBhrJxnPE,1521
+omniai/types/livekit.py,sha256=YrBKuHJrLKtOMr3tN9qg5ivQUg2U2dK1EBFUb5zJ_NU,1009
+omniai/types/models.py,sha256=IVdLz97xOMx23hRxnSAiv5N_qY9WxtticADkmVWCyIE,900
+omniai/types/tasks.py,sha256=pNS194ma_Lbfjxw84Y9eEDAiYPDsYfAVmwZDD0diBYE,8372
+omniai_kit-1.0.0.dist-info/licenses/LICENSE,sha256=aRe0C1CNovyEHPlFulNFl_u7NDK-bJBgstCL6lxem14,1068
+omniai_kit-1.0.0.dist-info/METADATA,sha256=d18Jpo6CSVpLnIvKh6kGZFayZd-k3_xtAx60GbIAbcM,9190
+omniai_kit-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+omniai_kit-1.0.0.dist-info/top_level.txt,sha256=a7OxUMNLeMKwY8jKopgybpSs_uVF-grcmIHkvXwiLqg,7
+omniai_kit-1.0.0.dist-info/RECORD,,

omniai_kit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

omniai_kit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniAI Team
+
+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.

omniai_kit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+omniai