voxagent 0.1.0__tar.gz

voxagent-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+

voxagent-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: voxagent
+Version: 0.1.0
+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: 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.
+

voxagent-0.1.0/README.md

@@ -0,0 +1,131 @@
+# 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.
+

voxagent-0.1.0/examples/README.md

@@ -0,0 +1,47 @@
+# voxagent Examples
+
+This directory contains working examples demonstrating voxagent features.
+
+## Prerequisites
+
+```bash
+# Install voxagent with all providers
+pip install voxagent[all]
+
+# Or install specific providers
+pip install voxagent[openai]      # For OpenAI examples
+pip install voxagent[anthropic]   # For Anthropic examples
+pip install voxagent[ollama]      # For Ollama examples
+```
+
+## Examples
+
+| File | Description | Provider |
+|------|-------------|----------|
+| `01_openai_streaming.py` | Basic streaming with OpenAI | OpenAI |
+| `02_anthropic_tools.py` | Tool calling with Anthropic | Anthropic |
+| `03_ollama_local.py` | Local models with Ollama | Ollama |
+| `04_mcp_integration.py` | MCP server integration | Any |
+| `05_multi_provider.py` | Provider switching & failover | Multiple |
+
+## Running Examples
+
+```bash
+# Set your API keys
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Run an example
+python 01_openai_streaming.py
+```
+
+## Environment Variables
+
+| Variable | Provider | Required |
+|----------|----------|----------|
+| `OPENAI_API_KEY` | OpenAI | Yes |
+| `ANTHROPIC_API_KEY` | Anthropic | Yes |
+| `GOOGLE_API_KEY` | Google | Yes |
+| `GROQ_API_KEY` | Groq | Yes |
+| (none) | Ollama | No (local) |
+

voxagent-0.1.0/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "voxagent"
+dynamic = ["version"]
+description = "A lightweight, model-agnostic LLM provider abstraction with streaming and tool support"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "voxDomus team" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+keywords = ["ai", "agent", "llm", "openai", "anthropic", "streaming", "mcp", "tools"]
+
+# Core dependencies - minimal footprint
+dependencies = [
+    "pydantic>=2.0",
+    "httpx>=0.25",
+    "anyio>=4.0",
+]
+
+[project.optional-dependencies]
+# Provider-specific dependencies
+openai = [
+    "openai>=1.0",
+    "tiktoken>=0.5",
+]
+anthropic = [
+    "anthropic>=0.25",
+]
+google = [
+    "google-generativeai>=0.5",
+]
+groq = [
+    "groq>=0.4",
+]
+ollama = [
+    "ollama>=0.2",
+]
+# MCP support
+mcp = [
+    "mcp>=1.0",
+]
+# All providers
+all = [
+    "voxagent[openai,anthropic,google,groq,ollama,mcp]",
+]
+# Development dependencies
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lensator/voxagent"
+Documentation = "https://github.com/lensator/voxagent#readme"
+Repository = "https://github.com/lensator/voxagent"
+Issues = "https://github.com/lensator/voxagent/issues"
+Changelog = "https://github.com/lensator/voxagent/blob/main/CHANGELOG.md"
+
+# Hatch configuration for src layout
+[tool.hatch.version]
+path = "src/voxagent/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voxagent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/voxagent/**/*.py",
+    "src/voxagent/py.typed",
+    "README.md",
+    "LICENSE",
+]
+exclude = [
+    "__pycache__",
+    "*.pyc",
+]
+
+# Ruff configuration
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["voxagent"]
+
+# Mypy configuration
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+# Pytest configuration
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-v --tb=short"

voxagent-0.1.0/src/voxagent/__init__.py

@@ -0,0 +1,143 @@
+"""voxagent - A lightweight, model-agnostic LLM provider abstraction.
+
+voxagent provides:
+- Multi-Provider: Unified interface for OpenAI, Anthropic, Google, Groq, Ollama
+- Streaming: Typed StreamChunk union (TextDelta, ToolUse, MessageEnd, Error)
+- Tool System: @tool decorator, typed definitions, abort signal propagation
+- MCP Integration: First-class Model Context Protocol support
+- Sub-Agent Support: Hierarchical agent composition with depth-limited delegation
+- Session Management: File-based sessions with context compaction
+
+Quick Start:
+    >>> from voxagent import Agent
+    >>> agent = Agent(model="openai:gpt-4o")
+    >>> result = await agent.run("Hello!")
+
+With Tools:
+    >>> from voxagent import Agent
+    >>> from voxagent.tools import tool
+    >>>
+    >>> @tool()
+    ... def get_weather(city: str) -> str:
+    ...     '''Get weather for a city.'''
+    ...     return f"Sunny in {city}"
+    >>>
+    >>> agent = Agent(model="anthropic:claude-3-5-sonnet", tools=[get_weather])
+    >>> result = await agent.run("What's the weather in Paris?")
+
+Streaming:
+    >>> from voxagent import Agent
+    >>> from voxagent.providers import TextDeltaChunk
+    >>>
+    >>> agent = Agent(model="openai:gpt-4o")
+    >>> async for chunk in agent.stream("Tell me a story"):
+    ...     if isinstance(chunk, TextDeltaChunk):
+    ...         print(chunk.delta, end="")
+
+For more information, see: https://github.com/voxdomus/voxagent
+"""
+
+from ._version import __version__, __version_info__
+
+# =============================================================================
+# Lazy imports for top-level convenience
+# =============================================================================
+# We use __getattr__ to avoid importing the full dependency chain on module load.
+# This keeps `import voxagent` fast and allows users to import only what they need.
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for top-level classes."""
+    # Core Agent class
+    if name == "Agent":
+        from .agent import Agent
+
+        return Agent
+
+    # Provider base classes and chunks
+    if name in (
+        "BaseProvider",
+        "StreamChunk",
+        "TextDeltaChunk",
+        "ToolUseChunk",
+        "MessageEndChunk",
+        "ErrorChunk",
+        "AbortSignal",
+    ):
+        from . import providers
+
+        return getattr(providers, name)
+
+    # Tool system
+    if name in ("tool", "ToolDefinition", "ToolContext"):
+        from . import tools
+
+        return getattr(tools, name)
+
+    # Message types
+    if name in ("Message", "ToolCall", "ToolResult"):
+        from . import types
+
+        return getattr(types, name)
+
+    # Sub-agent support
+    if name == "SubAgentDefinition":
+        from .subagent import SubAgentDefinition
+
+        return SubAgentDefinition
+    if name == "SubAgentContext":
+        from .subagent import SubAgentContext
+
+        return SubAgentContext
+    if name == "MaxDepthExceededError":
+        from .subagent import MaxDepthExceededError
+
+        return MaxDepthExceededError
+
+    # MCP
+    if name == "MCPServerManager":
+        from .mcp import MCPServerManager
+
+        return MCPServerManager
+
+    # Registry
+    if name in ("ProviderRegistry", "get_default_registry"):
+        from . import providers
+
+        return getattr(providers, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Version
+    "__version__",
+    "__version_info__",
+    # Core
+    "Agent",
+    # Providers
+    "BaseProvider",
+    "StreamChunk",
+    "TextDeltaChunk",
+    "ToolUseChunk",
+    "MessageEndChunk",
+    "ErrorChunk",
+    "AbortSignal",
+    "ProviderRegistry",
+    "get_default_registry",
+    # Tools
+    "tool",
+    "ToolDefinition",
+    "ToolContext",
+    # Types
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    # Sub-agents
+    "SubAgentDefinition",
+    "SubAgentContext",
+    "MaxDepthExceededError",
+    # MCP
+    "MCPServerManager",
+]
+

voxagent-0.1.0/src/voxagent/_version.py

@@ -0,0 +1,5 @@
+"""Version information for voxagent."""
+
+__version__ = "0.1.0"
+__version_info__ = tuple(int(x) for x in __version__.split("."))
+

voxagent-0.1.0/src/voxagent/agent/__init__.py

@@ -0,0 +1,32 @@
+"""Agent core module for voxagent.
+
+This subpackage provides:
+- Agent class for managing AI agent interactions
+- AbortController for abort signal management
+- TimeoutHandler for timeout-based abort triggering
+- Error recovery and failover handling
+"""
+
+from voxagent.agent.abort import (
+    AbortController,
+    AllProfilesExhausted,
+    FailoverError,
+    FailoverReason,
+    TimeoutHandler,
+    handle_context_overflow,
+)
+from voxagent.agent.core import Agent
+
+# Import providers to ensure they are registered with the default registry
+import voxagent.providers  # noqa: F401
+
+__all__ = [
+    "AbortController",
+    "Agent",
+    "AllProfilesExhausted",
+    "FailoverError",
+    "FailoverReason",
+    "TimeoutHandler",
+    "handle_context_overflow",
+]
+