Metadata-Version: 2.4
Name: ai-query
Version: 0.0.3
Summary: A unified Python SDK for querying AI models from multiple providers
Project-URL: Homepage, https://github.com/Abdulmumin1/ai_query
Project-URL: Repository, https://github.com/Abdulmumin1/ai_query
License: MIT License
        
        Copyright (c) 2026 Abdulmumin Yaqeen
        
        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.
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: aiohttp>=3.9.0
Description-Content-Type: text/markdown

# ai-query

A unified Python SDK for querying AI models from various providers with a consistent interface.

## Installation

Install using `uv` or `pip`:

```bash
# Using uv
uv add ai-query

# Using pip
pip install ai-query
```

## Usage

### Basic Text Generation

The library provides a simple `generate_text` function for non-streaming requests.

```python
import asyncio
from ai_query import generate_text, openai

async def main():
    result = await generate_text(
        model=openai("gpt-4o"),
        prompt="What is the capital of France?"
    )
    print(result.text)

asyncio.run(main())
```

### Streaming Text

For real-time responses, use `stream_text`. It returns a `TextStreamResult` that can be iterated directly.

```python
import asyncio
from ai_query import stream_text, google

async def main():
    result = stream_text(
        model=google("gemini-2.0-flash"),
        prompt="Write a short story about a robot."
    )

    # Stream the text chunks
    async for chunk in result.text_stream:
        print(chunk, end="", flush=True)

    # Access usage statistics after streaming finishes
    usage = await result.usage
    print(f"\nTotal tokens: {usage.total_tokens}")

asyncio.run(main())
```

### Multi-modal Messages

You can pass complex message structures, including files and images.

```python
import asyncio
from ai_query import stream_text, google

async def main():
    result = stream_text(
        model=google("gemini-2.0-flash"),
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Summarize this PDF:"},
                    {
                        "type": "file",
                        "data": "https://example.com/document.pdf",
                        "media_type": "application/pdf"
                    }
                ]
            }
        ]
    )
    async for chunk in result.text_stream:
        print(chunk, end="", flush=True)

asyncio.run(main())
```

### Providers

The library supports various AI providers through a unified interface. Built-in support is available for:

*   **OpenAI**: `openai("model-name")`
*   **Anthropic**: `anthropic("model-name")`
*   **Google**: `google("model-name")`

#### Configuration

You can configure providers using environment variables (recommended) or by passing credentials directly.

**Using Environment Variables:**

By default, providers look for standard environment variables:
*   `OPENAI_API_KEY`
*   `ANTHROPIC_API_KEY`
*   `GOOGLE_API_KEY`

**Passing API Keys Dynamically:**

You can explicitly pass the API key (and other parameters) when initializing a provider.

```python
from ai_query import generate_text, google

async def main():
    # Pass API key directly
    model = google("gemini-2.0-flash", api_key="your_api_key_here")

    result = await generate_text(
        model=model,
        prompt="Explain quantum computing"
    )
    print(result.text)
```

### Provider-Specific Options

You can pass specific parameters to the underlying provider using `provider_options`.

```python
result = await generate_text(
    model=google("gemini-2.0-flash"),
    prompt="Tell me a story",
    provider_options={
        "google": {
            "safety_settings": {"HARM_CATEGORY_VIOLENCE": "BLOCK_NONE"}
        }
    }
)
```
