Metadata-Version: 2.4
Name: voxagent
Version: 0.2.3
Summary: A lightweight, model-agnostic LLM provider abstraction with streaming and tool support
Project-URL: Homepage, https://github.com/lensator/voxagent
Project-URL: Documentation, https://github.com/lensator/voxagent#readme
Project-URL: Repository, https://github.com/lensator/voxagent
Project-URL: Issues, https://github.com/lensator/voxagent/issues
Project-URL: Changelog, https://github.com/lensator/voxagent/blob/main/CHANGELOG.md
Author: voxDomus team
License-Expression: MIT
Keywords: agent,ai,anthropic,llm,mcp,openai,streaming,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.11
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: anthropic>=0.25; extra == 'all'
Requires-Dist: google-generativeai>=0.5; extra == 'all'
Requires-Dist: groq>=0.4; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: ollama>=0.2; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: tiktoken>=0.5; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: code
Requires-Dist: restrictedpython>=7.0; extra == 'code'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.5; extra == 'google'
Provides-Extra: groq
Requires-Dist: groq>=0.4; extra == 'groq'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: ollama
Requires-Dist: ollama>=0.2; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Requires-Dist: tiktoken>=0.5; extra == 'openai'
Description-Content-Type: text/markdown

# voxagent

[![PyPI version](https://badge.fury.io/py/voxagent.svg)](https://badge.fury.io/py/voxagent)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Typed](https://img.shields.io/badge/typed-yes-green.svg)](https://peps.python.org/pep-0561/)

A lightweight, model-agnostic LLM provider abstraction with streaming and tool support.

## Features

- **Multi-Provider**: Unified interface for OpenAI, Anthropic, Google, Groq, Ollama
- **Streaming**: Typed `StreamChunk` union (TextDelta, ToolUse, MessageEnd, Error)
- **Tool System**: `@tool` decorator for easy function-to-tool conversion
- **MCP Integration**: First-class Model Context Protocol support
- **Type Safe**: Full type hints with `py.typed` marker
- **Minimal Dependencies**: Core requires only `pydantic`, `httpx`, `anyio`

## Installation

```bash
# Core only (no provider SDKs)
pip install voxagent

# With specific providers
pip install voxagent[openai]
pip install voxagent[anthropic]
pip install voxagent[google]
pip install voxagent[ollama]

# All providers
pip install voxagent[all]
```

## Quick Start

```python
import asyncio
from voxagent import Agent

async def main():
    agent = Agent(model="openai:gpt-4o")
    result = await agent.run("Hello, world!")
    print(result.output)

asyncio.run(main())
```

## Streaming

```python
from voxagent import Agent
from voxagent.providers import TextDeltaChunk

agent = Agent(model="anthropic:claude-3-5-sonnet")

async for chunk in agent.stream("Tell me a story"):
    if isinstance(chunk, TextDeltaChunk):
        print(chunk.delta, end="", flush=True)
```

## Tools

```python
from voxagent import Agent
from voxagent.tools import tool

@tool()
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Sunny, 72°F in {city}"

agent = Agent(
    model="openai:gpt-4o",
    tools=[get_weather],
)

result = await agent.run("What's the weather in Paris?")
```

## Supported Providers

| Provider | Model Format | Example |
|----------|--------------|---------|
| OpenAI | `openai:model` | `openai:gpt-4o` |
| Anthropic | `anthropic:model` | `anthropic:claude-3-5-sonnet` |
| Google | `google:model` | `google:gemini-1.5-pro` |
| Groq | `groq:model` | `groq:llama-3.1-70b` |
| Ollama | `ollama:model` | `ollama:llama3.2` |

## API Reference

### Agent

```python
from voxagent import Agent

agent = Agent(
    model="provider:model",      # Required: provider:model string
    system_prompt="...",         # Optional: system instructions
    tools=[...],                 # Optional: list of tools
    temperature=0.7,             # Optional: sampling temperature
)

# Single response
result = await agent.run("prompt")

# Streaming
async for chunk in agent.stream("prompt"):
    ...
```

### StreamChunk Types

```python
from voxagent.providers import (
    TextDeltaChunk,    # Text content
    ToolUseChunk,      # Tool invocation
    MessageEndChunk,   # End of message
    ErrorChunk,        # Error occurred
)
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

