Metadata-Version: 2.4
Name: aiclient-llm
Version: 0.2.0
Summary: A minimal, generic client for AI models (OpenAI, Anthropic, Google, xAI) with middleware support.
Project-URL: Homepage, https://github.com/rarenicks/aiclient
Project-URL: Documentation, https://github.com/rarenicks/aiclient/tree/main/docs
Project-URL: Repository, https://github.com/rarenicks/aiclient
Project-URL: Issues, https://github.com/rarenicks/aiclient/issues
Project-URL: Changelog, https://github.com/rarenicks/aiclient/blob/main/CHANGELOG.md
Author-email: Avdhesh Singh Chouhan <ai.avdhesh@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,anthropic,client,gemini,llm,openai
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# aiclient-llm

[![PyPI version](https://img.shields.io/pypi/v/aiclient-llm.svg)](https://pypi.org/project/aiclient-llm/)
[![Python Versions](https://img.shields.io/pypi/pyversions/aiclient-llm.svg)](https://pypi.org/project/aiclient-llm/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Downloads](https://pepy.tech/badge/aiclient-llm)](https://pepy.tech/project/aiclient-llm)

**A minimal, unified, and resilient Python client for modern LLMs.**

Supports **OpenAI**, **Anthropic** (Claude 3), **Google** (Gemini), and **xAI** (Grok) with a single, consistent interface.



## Documentation

- [**Getting Started**](https://github.com/rarenicks/aiclient/blob/main/docs/getting_started.md): Installation, Configuration, Basic Usage.
- [**Features Guide**](https://github.com/rarenicks/aiclient/blob/main/docs/features.md): Agents, Multimodal, Local LLMs (Ollama), Structured Output.
- [**Middleware**](https://github.com/rarenicks/aiclient/blob/main/docs/middleware.md): Cost tracking, logging, resilience, and custom middleware.
- [**Memory**](https://github.com/rarenicks/aiclient/blob/main/docs/memory.md): Conversation history management and persistence.
- [**Testing**](https://github.com/rarenicks/aiclient/blob/main/docs/testing.md): Mock providers and testing utilities.
- [**Error Handling**](https://github.com/rarenicks/aiclient/blob/main/docs/errors.md): Exception types and debugging.
- [**Examples**](https://github.com/rarenicks/aiclient/blob/main/examples/): Runnable demo scripts for new features.

## Key Features

- 🦄 **Unified API**: Works with OpenAI, Anthropic, Google Gemini, and Ollama.
- ⚡ **Streaming Support**: Real-time responses with a simple iterator interface.
- 👁️ **Multimodal (Vision)**: Send images (paths, URLs, base64) to vision-capable models.
- 🚀 **Prompt Caching**: Native support for Anthropic Prompt Caching headers.
- 🏗️ **Structured Outputs**: Native strict JSON Schema support for OpenAI.
- 🛡️ **Resilient**: Circuit Breakers, Rate Limiters, and automatic retries.
- 🔭 **Observability**: Tracing and OpenTelemetry hooks.
- 🤖 **Agent Primitives**: Built-in ReAct loop for tool-using agents.
- 🔌 **Model Context Protocol (MCP)**: Connect to 16K+ external tools (GitHub, Postgres, filesystem).
- 📊 **Middleware**: Inspect requests, track costs, or log data.
- 🧠 **Memory Management**: Built-in conversation history with token-aware truncation
- 🧪 **Testing Utilities**: Mock providers for deterministic unit tests
- 📦 **Batch Processing**: Efficiently process thousands of requests concurrently
- 🛡️ **Type-Safe Errors**: Specific exception types for better error handling

## Installation

```bash
pip install aiclient-llm
```

## Quick Start

### Basic Chat

```python
from aiclient import Client

client = Client(
    api_key_openai="sk-...", 
    api_key_anthropic="sk-ant-..."
)

# Call OpenAI
response = client.chat("gpt-4o").generate("Hello!")
print(response.text)

# Call Claude
response = client.chat("claude-3-opus-20240229").generate("Hello!")
print(response.text)
```

### Multimodal (Vision)

```python
from aiclient.data_types import UserMessage, Text, Image

msg = UserMessage(content=[
    Text(text="What's in this image?"),
    Image(path="./image.png") # Handles base64 automatically
])

response = client.chat("gpt-4o").generate([msg])
print(response.text)
```

### Agents (Tool Use)

```python
from aiclient.agent import Agent

def get_weather(location: str):
    return "Sunny in " + location

agent = Agent(
    model=client.chat("gpt-4o"),
    tools=[get_weather]
)

print(agent.run("Weather in SF?"))
```

### MCP Integration 🔌

Connect to external tools using the Model Context Protocol.

```python
agent = Agent(
    model=client.chat("gpt-4o"),
    mcp_servers={
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
        }
    }
)

# Agent can now use file system tools!
print(agent.run("List all Python files in the current directory"))
```

### Local LLMs (Ollama) 🏠

Use the `provider:model` syntax to route requests to local models (e.g., via Ollama).

```python
# Connects to http://localhost:11434/v1 by default
client.chat("ollama:llama3").generate("Why is the sky blue?")

# Connect to custom URL (e.g. LMStudio)
client = Client(ollama_base_url="http://localhost:1234/v1")
client.chat("ollama:mistral").generate("Hi")
```

### Streaming

```python
for chunk in client.chat("gpt-4o").stream("Write a poem"):
    print(chunk.text, end="", flush=True)
```

## Configuration

### Retries

```python
# Retries up to 3 times with backoff
client = Client(max_retries=3, retry_delay=1.0)
```

## License

Apache-2.0
