Metadata-Version: 2.4
Name: xima-ai
Version: 2.1.0
Summary: Python client library for the XimaAI API
Home-page: https://github.com/0xXimaAi/xima_python_sdk
Author: XimaAI
License: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: typing_extensions<5.0,>=4.7.1
Requires-Dist: pydantic>=1.10.8
Requires-Dist: anyio<5,>=3.5.0
Requires-Dist: distro<2,>=1.7.0
Requires-Dist: sniffio
Requires-Dist: cached-property
Requires-Dist: tqdm>4
Requires-Dist: types-requests
Requires-Dist: jiter<1,>=0.4.0
Provides-Extra: dev
Requires-Dist: mypy<2.0,>=0.991; extra == "dev"
Requires-Dist: black==23.7.0; extra == "dev"
Requires-Dist: pytest==7.4.2; extra == "dev"
Requires-Dist: python-dotenv==1.0.0; extra == "dev"
Requires-Dist: ruff==0.0.292; extra == "dev"
Requires-Dist: pytest-asyncio==0.23.5; extra == "dev"
Provides-Extra: langchain-callback
Requires-Dist: langchain-core; extra == "langchain-callback"
Provides-Extra: llama-index-callback
Requires-Dist: llama-index; extra == "llama-index-callback"
Provides-Extra: instrumentation
Requires-Dist: opentelemetry-sdk<2.0,>=1.29.0; extra == "instrumentation"
Requires-Dist: opentelemetry-instrumentation<1.0,>=0.50b0; extra == "instrumentation"
Requires-Dist: wrapt<2.0,>=1.17.0; extra == "instrumentation"
Provides-Extra: strands
Requires-Dist: strands-agents>=0.0.0; extra == "strands"
Provides-Extra: adk
Requires-Dist: google-adk; extra == "adk"
Requires-Dist: google-genai; extra == "adk"
Dynamic: license-file

## Control Panel for AI Apps

## Features

The XimaAi SDK is built on top of the OpenAI SDK, allowing you to seamlessly integrate XimaAi's advanced features while retaining full compatibility with OpenAI methods. With XimaAi, you can enhance your interactions with OpenAI or any other OpenAI-like provider by leveraging robust monitoring, reliability, prompt management, and more features - without modifying much of your existing code.

### AI Gateway

<table>
    <tr>
        <td width=50%><b>Unified API Signature</b><br />If you've used OpenAI, you already know how to use XimaAi with any other provider.</td>
        <td><b>Interoperability</b><br />Write once, run with any provider. Switch between any model from_any provider seamlessly. </td>
    </tr>
    <tr>
        <td width=50%><b>Automated Fallbacks & Retries</b><br />Ensure your application remains functional even if a primary service fails.</td>
        <td><b>Load Balancing</b><br />Efficiently distribute incoming requests among multiple models.</td>
    </tr>
    <tr>
        <td width=50%><b>Semantic Caching</b><br />Reduce costs and latency by intelligently caching results.</td>
        <td><b>Virtual Keys</b><br />Secure your LLM API keys by storing them in XimaAi vault and using disposable virtual keys.</td>
    </tr>
    <tr>
        <td width=50%><b>Request Timeouts</b><br />Manage unpredictable LLM latencies effectively by setting custom request timeouts on requests.</td>
    </tr>
</table>

### Observability

<table width=100%>
    <tr>
        <td width=50%><b>Logging</b><br />Keep track of all requests for monitoring and debugging.</td>
        <td width=50%><b>Requests Tracing</b><br />Understand the journey of each request for optimization.</td>
    </tr>
    <tr>
        <td width=50%><b>Custom Metadata</b><br />Segment and categorize requests for better insights.</td>
        <td width=50%><b>Feedbacks</b><br />Collect and analyse weighted feedback on requests from users.</td>
    </tr>
    <tr>
        <td width=50%><b>Analytics</b><br />Track your app & LLM's performance with 40+ production-critical metrics in a single place.</td>
    </tr>
</table>

## Usage

#### Prerequisites

1. [Sign up on XimaAi](https://app.XimaAi.ai/) and grab your XimaAi API Key
2. Add your [OpenAI key](https://platform.openai.com/api-keys) to XimaAi's Virtual Keys page and keep it handy

```bash
# Installing the SDK

$ pip install XimaAi-ai
$ export XimaAi_API_KEY=XimaAi_API_KEY
```

#### Making a Request to OpenAI

- XimaAi fully adheres to the OpenAI SDK signature. You can instantly switch to XimaAi and start using our production features right out of the box. <br />
- Just replace `from openai import OpenAI` with `from XimaAi_ai import XimaAi`:

```py
from XimaAi_ai import XimaAi

XimaAi = XimaAi(
    api_key="XimaAi_API_KEY",
    virtual_key="VIRTUAL_KEY"
)

chat_completion = XimaAi.chat.completions.create(
    messages = [{ "role": 'user', "content": 'Say this is a test' }],
    model = 'gpt-4'
)

print(chat_completion)
```

#### Async Usage

- Use `AsyncXimaAi` instead of `XimaAi` with `await`:

```py
import asyncio
from XimaAi_ai import AsyncXimaAi

XimaAi = AsyncXimaAi(
    api_key="XimaAi_API_KEY",
    virtual_key="VIRTUAL_KEY"
)

async def main():
    chat_completion = await XimaAi.chat.completions.create(
        messages=[{'role': 'user', 'content': 'Say this is a test'}],
        model='gpt-4'
    )

    print(chat_completion)

asyncio.run(main())
```

### Strands Agents Integration (optional)

Installation:

```bash
pip install 'XimaAi-ai[strands]'
```

Usage with Strands:

```python
from strands.agent import Agent
from XimaAi_ai.integrations.strands import XimaAiStrands

model = XimaAiStrands(
    api_key="XimaAi_API_KEY",
    model_id="@openai/gpt-4o-mini",
#   base_url="https://api.XimaAi.ai/v1",  ## Optional
)

agent = Agent(model=model)

import asyncio

async def main():
    result = await agent.invoke_async("Tell me a short programming joke.")
    print(getattr(result, "text", result))

asyncio.run(main())
```

### Google ADK Integration (optional)

Installation:

```bash
pip install 'XimaAi-ai[adk]'
```

Usage with ADK:

```python
import asyncio
from google.adk.models.llm_request import LlmRequest
from google.genai import types
from XimaAi_ai.integrations.adk import XimaAiAdk

llm = XimaAiAdk(
    api_key="XimaAi_API_KEY",
    model="@openai/gpt-4o-mini",
#   base_url="https://api.XimaAi.ai/v1",  ## Optional
)

req = LlmRequest(
    model="@openai/gpt-4o-mini",
    contents=[
        types.Content(
            role="user",
            parts=[types.Part.from_text(text="Tell me a short programming joke.")],
        )
    ],
)

async def main():
    # Print only partial chunks to avoid duplicate final output
    async for resp in llm.generate_content_async(req, stream=True):
        if getattr(resp, "partial", False) and resp.content and resp.content.parts:
            for p in resp.content.parts:
                if getattr(p, "text", None):
                    print(p.text, end="")
    print()

asyncio.run(main())
```

Non-streaming example (single final response):

```python
import asyncio
from google.adk.models.llm_request import LlmRequest
from google.genai import types
from XimaAi_ai.integrations.adk import XimaAiAdk

llm = XimaAiAdk(
    api_key="XimaAi_API_KEY",
    model="@openai/gpt-4o-mini",
)

req = LlmRequest(
    model="@openai/gpt-4o-mini",
    contents=[
        types.Content(
            role="user",
            parts=[types.Part.from_text(text="Give me a one-line programming joke (final only).")],
        )
    ],
)

async def main():
    final_text = []
    async for resp in llm.generate_content_async(req, stream=False):
        if resp.content and resp.content.parts:
            for p in resp.content.parts:
                if getattr(p, "text", None):
                    final_text.append(p.text)
    print("".join(final_text))

asyncio.run(main())
```

Configuration notes:

- **system_role**: By default, the adapter sends the system instruction as a `developer` role message to align with ADK. If your provider expects a strict `system` role, pass `system_role="system"` when constructing `XimaAiAdk`.

  ```python
  llm = XimaAiAdk(
      model="@openai/gpt-4o-mini",
      api_key="XimaAi_API_KEY",
      system_role="system",  # switch from default "developer"
  )
  ```

- **Tools**: When tools are present in the ADK request, the adapter sets `tool_choice="auto"` to enable function calling by default (mirrors the Strands adapter behavior).

## Compatibility with OpenAI SDK

XimaAi currently supports all the OpenAI methods, including the legacy ones.

| Methods                                                                                                         | OpenAI<br>V1.26.0 | XimaAi<br>V1.3.1 |
| :-------------------------------------------------------------------------------------------------------------- | :---------------- | :--------------- |
| [Audio](https://XimaAi.ai/docs/product/ai-gateway-streamline-llm-integrations/multimodal-capabilities/vision-1) | ✅                | ✅               |
| [Chat](https://XimaAi.ai/docs/api-reference/chat-completions)                                                   | ✅                | ✅               |
| [Embeddings](https://XimaAi.ai/docs/api-reference/embeddings)                                                   | ✅                | ✅               |
| [Images](https://XimaAi.ai/docs/api-reference/completions-1)                                                    | ✅                | ✅               |
| Fine-tuning                                                                                                     | ✅                | ✅               |
| Batch                                                                                                           | ✅                | ✅               |
| Files                                                                                                           | ✅                | ✅               |
| Models                                                                                                          | ✅                | ✅               |
| Moderations                                                                                                     | ✅                | ✅               |
| Assistants                                                                                                      | ✅                | ✅               |
| Threads                                                                                                         | ✅                | ✅               |
| Thread - Messages                                                                                               | ✅                | ✅               |
| Thread - Runs                                                                                                   | ✅                | ✅               |
| Thread - Run - Steps                                                                                            | ✅                | ✅               |
| Vector Store                                                                                                    | ✅                | ✅               |
| Vector Store - Files                                                                                            | ✅                | ✅               |
| Vector Store - Files Batches                                                                                    | ✅                | ✅               |
| Generations                                                                                                     | ❌ (Deprecated)   | ✅               |
| Completions                                                                                                     | ❌ (Deprecated)   | ✅               |

### XimaAi-Specific Methods

| Methods                                                   | XimaAi<br>V1.3.1 |
| :-------------------------------------------------------- | :--------------- |
| [Feedback](https://XimaAi.ai/docs/api-reference/feedback) | ✅               |
| [Prompts](https://XimaAi.ai/docs/api-reference/prompts)   | ✅               |

---

#### [Check out XimaAi docs for the full list of supported providers](https://XimaAi.ai/docs/welcome/what-is-XimaAi#ai-providers-supported)

<a href="https://twitter.com/intent/follow?screen_name=XimaAiai"><img src="https://img.shields.io/twitter/follow/XimaAiai?style=social&logo=twitter" alt="follow on Twitter"></a>
<a href="https://discord.gg/sDk9JaNfK8" target="_blank"><img src="https://img.shields.io/discord/1143393887742861333?logo=discord" alt="Discord"></a>

#### Contributing

Get started by checking out Github issues. Email us at support@XimaAi.ai or just ping on Discord to chat.
