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

{omniai_kit-1.0.1 → omniai_kit-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omniai-kit
-Version: 1.0.1
+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>
@@ -56,19 +56,21 @@ Dynamic: license-file
 [![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.
+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.
 
 ---
 
-## ⚡ Features
+## ⚡ Key Capabilities
 
-- **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`).
+- **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.
-- **Resilient Real-Time Streaming:** Server-Sent Events (SSE) streaming engine with auto-reconnect and keep-alive handling.
+- **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.
-- **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.
 
 ---
@@ -91,20 +93,20 @@ pip install "omniai-kit[anthropic]"  # Installs Anthropic SDK
 
 ## 🏛️ Supported Model Providers
 
-OmniAI natively routes and normalizes parameters across the following 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` |
-| **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` |
+| **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` |
-| **OpenRouter** | `openrouter:<model>` | `openrouter:anthropic/claude-3.5-sonnet` |
 | **Ollama (Local)** | `ollama:<model>` | `ollama:qwen2.5-coder:7b` |
 
 ---
 
-## 🚀 Quickstart
+## 🚀 Usage Guide
 
 ### 1. Basic Chat Completion
 
@@ -132,7 +134,52 @@ response = client.chat.completions.create(model="gemini:gemini-2.5-flash", promp
 
 ---
 
-### 2. Real-Time Token Streaming
+### 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
@@ -150,7 +197,7 @@ print()
 
 ---
 
-### 3. Strongly Typed Structured Outputs (Pydantic V2)
+### 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:
 
@@ -179,68 +226,69 @@ print(f"Target SLA: {analysis.availability_sla}%")
 
 ---
 
-### 4. Asynchronous Client (`AsyncOmniaiClient`)
+### 6. Custom AI Agents & Vector Knowledge Bases
 
-Full async/await parity for high-concurrency microservices, FastAPI, and async workers:
+Create autonomous custom agents, ingest reference documents into Qdrant vector memory, and execute queries:
 
 ```python
-import asyncio
-from omniai import AsyncOmniaiClient
+from omniai import OmniaiClient
 
-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)
+client = OmniaiClient()
 
-        # 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()
+# 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",
+)
 
-asyncio.run(main())
+# 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)
 ```
 
 ---
 
-### 5. Background Task Queue (Celery Integration)
+### 7. Scoped API Key Management
 
-Queue long-running jobs to the background Celery cluster with fault-tolerant polling that survives transient network dropouts:
+Programmatically provision, monitor, and revoke API keys with spend quotas and allowed models:
 
 ```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,
+# 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"Dispatched Celery Task ID: {job.task_id}")
+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'}")
 
-# 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}")
+# 3. Revoke key
+client.keys.delete(new_key.id)
 ```
 
 ---
 
-### 6. LiveKit Multimodal Real-Time Voice & Video
+### 8. LiveKit Multimodal Real-Time Voice & Video
 
 Create WebRTC sessions for sub-second bidirectional voice and vision agents:
 
@@ -250,7 +298,7 @@ from omniai import OmniaiClient
 client = OmniaiClient()
 
 session = client.create_live_session(
-    model="gemini:gemini-2.5-flash",
+    model="gemini-3.8-live",
     voice="Aoede",
     video_input=True,
 )
@@ -262,19 +310,34 @@ print(f"Token:          {session.participant_token}")
 
 ---
 
-### 7. Model Discovery & Catalog
+### 9. Asynchronous Client (`AsyncOmniaiClient`)
 
-Query available models dynamically from the gateway:
+Full async/await parity for high-concurrency microservices, FastAPI, and async workers:
 
 ```python
-from omniai import OmniaiClient
+import asyncio
+from omniai import AsyncOmniaiClient
 
-client = OmniaiClient()
+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()
 
-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})")
+asyncio.run(main())
 ```
 
 ---
@@ -290,11 +353,6 @@ for m in models.data[:5]:
 | **`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
@@ -316,29 +374,30 @@ OmniaiError
 
 ---
 
-## 📂 Repository Directory Pattern
+## 📂 Repository Directory Layout
 
 ```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
+│   │   ├── 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
-│   │   ├── livekit.py
-│   │   ├── models.py
-│   │   └── tasks.py
-│   ├── __init__.py             # Top-level exports
+│   │   ├── 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.0.0)
+│   ├── _version.py             # Package version (1.1.0)
 │   ├── client.py               # OmniaiClient & AsyncOmniaiClient
 │   ├── exceptions.py           # Typed exception hierarchy
 │   └── py.typed                # PEP 561 typing compliance
@@ -346,15 +405,14 @@ omniai-sdk/
 │   ├── quickstart.py
 │   ├── streaming.py
 │   ├── structured_output.py
-│   └── async_chat.py
+│   ├── async_chat.py
+│   ├── thinking_reasoning.py
+│   ├── custom_agents.py
+│   └── api_keys.py
 ├── tests/                      # Unit and integration test suite
-├── .env.example
-├── .gitignore
-├── LICENSE                     # MIT License
-├── README.md                   # Documentation & Guides
+├── test.py                     # Root verification script
 ├── pyproject.toml              # PEP 517/621 packaging metadata
-├── requirements.txt            # Core dependencies (httpx, pydantic)
-└── test.py                     # Root test script for quick validation
+└── README.md                   # Documentation & Guides
 ```
 
 ---
@@ -367,7 +425,7 @@ Run the test suite with `pytest`:
 pytest tests
 ```
 
-Or run the quick root validation script:
+Or run the root verification script:
 
 ```bash
 python test.py