Metadata-Version: 2.4
Name: pyagents-ai
Version: 0.1.1
Summary: A simple framework for building AI agents in Python.
Project-URL: Homepage, https://github.com/abhishekjain/pyagents
Project-URL: Documentation, https://github.com/abhishekjain/pyagents#readme
Project-URL: Repository, https://github.com/abhishekjain/pyagents
Project-URL: Issues, https://github.com/abhishekjain/pyagents/issues
Author-email: Abhishek Jain <ajain@toorakcapital.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,anthropic,automation,framework,llm,multi-agent,openai
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.10
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.10
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

# PyAgents

**A lightweight, Pythonic framework for building AI agents.**

Build intelligent agents with tool use, memory, planning, and multi-agent orchestration — in just a few lines of code.

[![PyPI version](https://badge.fury.io/py/pyagents-ai.svg)](https://pypi.org/project/pyagents-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## Why PyAgents?

Existing agent frameworks are either too complex (LangChain) or too limited. PyAgents hits the sweet spot:

- **5-line quickstart** — Get a working agent running immediately
- **Decorator-based tools** — `@tool` decorator with auto-generated schemas from type hints
- **Async-first** — Native `async/await` for concurrent tool execution
- **Pluggable everything** — Swap LLM backends, memory, planners without changing agent code
- **Multi-agent teams** — Orchestrate agents working sequentially, in parallel, or with routing
- **Built-in guardrails** — Cost limits, content filtering, and output validation
- **Zero lock-in** — Works with OpenAI, Anthropic, or any OpenAI-compatible API

## Installation

```bash
# Core (no LLM backend)
pip install pyagents-ai

# With OpenAI support
pip install pyagents-ai[openai]

# With Anthropic support
pip install pyagents-ai[anthropic]

# Everything
pip install pyagents-ai[all]
```

## Quick Start

### 1. Your First Agent (5 lines)

```python
import asyncio
from pyagents import Agent, tool
from pyagents.llm.openai import OpenAIBackend

@tool(description="Add two numbers together")
def add(a: int, b: int) -> int:
    return a + b

@tool(description="Multiply two numbers")
def multiply(a: int, b: int) -> int:
    return a * b

agent = Agent(
    llm=OpenAIBackend(model="gpt-4o"),
    tools=[add, multiply],
    system_prompt="You are a helpful math assistant. Use tools for calculations.",
)

result = asyncio.run(agent.run("What is (12 + 8) * 3?"))
print(result.output)
# → "The result of (12 + 8) × 3 is 60."
```

### 2. Using Anthropic Claude

```python
from pyagents import Agent
from pyagents.llm.anthropic import AnthropicBackend

agent = Agent(
    llm=AnthropicBackend(model="claude-sonnet-4-20250514"),
    system_prompt="You are a helpful assistant.",
)

result = asyncio.run(agent.run("Explain quantum computing in simple terms."))
print(result.output)
```

### 3. Tools with Async Support

```python
import httpx
from pyagents import tool

@tool(description="Fetch the content of a webpage")
async def fetch_url(url: str) -> str:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text[:2000]

@tool(description="Search for information on a topic")
async def web_search(query: str, max_results: int = 3) -> str:
    # Your search implementation here
    return f"Results for: {query}"
```

### 4. Multi-Agent Teams

```python
from pyagents import Agent, Orchestrator, TeamConfig
from pyagents.orchestrator import DelegationStrategy

researcher = Agent(
    llm=llm,
    name="Researcher",
    tools=[web_search],
    system_prompt="You research topics thoroughly and provide detailed findings.",
)

writer = Agent(
    llm=llm,
    name="Writer",
    system_prompt="You write clear, engaging content based on research provided to you.",
)

team = Orchestrator(
    agents=[researcher, writer],
    config=TeamConfig(
        name="Content Team",
        strategy=DelegationStrategy.SEQUENTIAL,
        shared_context=True,
    ),
)

result = asyncio.run(team.run("Write a blog post about the future of AI agents"))
print(result.final_output)
```

### 5. Guardrails

```python
from pyagents import Agent, CostGuardrail, ContentGuardrail

agent = Agent(
    llm=llm,
    guardrails=[
        CostGuardrail(max_tokens=100_000, max_cost_usd=1.0),
        ContentGuardrail(
            blocked_terms=["password", "secret_key"],
            redact=True,  # Replaces with [REDACTED] instead of raising error
        ),
    ],
)
```

### 6. Memory

```python
from pyagents import Agent
from pyagents.memory.sqlite import SQLiteMemory

# Persistent memory across sessions
agent = Agent(
    llm=llm,
    memory=SQLiteMemory(db_path="my_agent_memory.db"),
    system_prompt="You remember previous conversations.",
)

# First conversation
await agent.run("My name is Abhishek and I work in finance.")

# Later conversation — agent remembers!
result = await agent.run("What do you know about me?")
# → "You told me your name is Abhishek and you work in finance."
```

### 7. Observability & Logging

```python
from pyagents.logging import setup_logging, ExecutionTracer
import logging

# Enable colored console logging
setup_logging(level=logging.DEBUG)

# Or JSON logging for production
setup_logging(json_mode=True)

# Trace execution
tracer = ExecutionTracer()
with tracer.span("agent_run", agent="my_agent"):
    result = await agent.run("Do something complex")

print(tracer.report())
# → {"total_duration_ms": 1234.56, "spans": [...], "span_count": 1}
```

## Architecture

```
pyagents/
├── agent.py          # Core Agent class with run loop
├── tools.py          # @tool decorator & ToolRegistry
├── orchestrator.py   # Multi-agent orchestration
├── guardrails.py     # Input/output validation & cost limits
├── logging.py        # Structured logging & tracing
├── llm/
│   ├── base.py       # Abstract LLM backend interface
│   ├── openai.py     # OpenAI / GPT backend
│   └── anthropic.py  # Anthropic / Claude backend
├── memory/
│   ├── base.py       # Abstract memory interface
│   ├── local.py      # In-memory storage
│   └── sqlite.py     # SQLite persistent storage
└── planner/
    ├── base.py       # Abstract planner interface
    └── react.py      # ReAct & Plan-and-Execute strategies
```

## Roadmap

- [ ] Streaming responses
- [ ] Built-in tool library (web search, file I/O, code execution)
- [ ] Redis memory backend
- [ ] Embedding-based semantic memory
- [ ] OpenTelemetry integration
- [ ] Agent-to-agent communication protocol
- [ ] Web UI dashboard for monitoring
- [ ] LiteLLM backend for 100+ model providers

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# Clone the repo
git clone https://github.com/abhishekjain/pyagents.git
cd pyagents

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/
mypy src/
```

## License

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