lean-agents 0.0.2
A lightweight Python library for building AI agents with function calling capabilities
License: MIT
Requires Python: >=3.10
Keywords: agent, ai, function-calling, llm, openai

# Lean Agents

A lightweight Python library for building AI agents with function calling capabilities using OpenAI's API.

## Features

- **Separation of Concerns** - Agent configuration separate from execution logic
- **Async/Await Support** - Built with asyncio for efficient concurrent operations
- **Automatic Schema Generation** - Convert Python functions to OpenAI function calling schemas
- **Multiple Tools** - Support for multiple tools/functions per agent
- **Type-Safe** - Full type hints support for better IDE integration
- **Streaming Responses** - Real-time response processing

## Installation

```bash
# Using uv (recommended)
uv add lean-agents

# Using pip
pip install lean-agents
```

## Quick Start

```python
import asyncio
from lean_agents import Agent, Runner

def add(a: int, b: int) -> int:
    """Add two numbers together and return the result."""
    return int(a) + int(b)

async def main():
    # Create an agent configuration
    agent = Agent(
        instructions="You are a helpful assistant that can handle adding numbers with tool `add`.",
        tools=[add],
        model="gpt-4o-mini"
    )

    # Run the agent (async)
    result = await Runner.run(agent, "What is 123 + 456?")
    print(result.final_output)

asyncio.run(main())
```

## Usage

### Defining Tools

Tools are simple Python functions with type hints and docstrings:

```python
def multiply(a: int, b: int) -> int:
    """Multiply two numbers together."""
    return int(a) * int(b)

def get_weather(city: str) -> str:
    """Get the weather for a city."""
    # Your implementation here
    return f"Weather in {city}: Sunny, 25°C"
```

### Creating an Agent

```python
agent = Agent(
    instructions="Your system instructions here",
    tools=[multiply, get_weather],
    model="gpt-4o-mini",  # Optional: defaults to gpt-4o-mini
    api_key="your-api-key"  # Optional: uses OPENAI_API_KEY env var if not provided
)
```

### Running the Agent

Lean Agents provides both async and sync execution methods, similar to OpenAI's agents SDK:

**Async execution (recommended):**
```python
async def run_example():
    # Execute agent asynchronously
    result = await Runner.run(agent, "What is 15 times 23?")

    # Access the final answer
    print(result.final_output)

    # Access all interaction items (messages, function calls, etc.)
    for item in result.items:
        print(item)
```

**Sync execution:**
```python
def run_example_sync():
    # Execute agent synchronously
    result = Runner.run_sync(agent, "What is 15 times 23?")

    # Access the final answer
    print(result.final_output)
```

## Examples

See the `examples/` directory for more examples:

- `basic_example.py` - Simple addition example
- `advanced_example.py` - Multiple tools and complex interactions

To run an example:

```bash
cd examples
python basic_example.py
```

## API Reference

### Agent

Agent configuration object that holds instructions, tools, and model settings.

```python
Agent(
    instructions: str,
    tools: list[Callable],
    model: str = "gpt-4o-mini",
    api_key: str | None = None
)
```

**Parameters:**
- `instructions`: System instructions that guide the agent's behavior
- `tools`: List of callable functions that the agent can use
- `model`: OpenAI model name (default: "gpt-4o-mini")
- `api_key`: OpenAI API key (if not provided, uses OPENAI_API_KEY env var)

### Runner

Static executor class for running agents. Provides both async and sync methods.

**Static Methods:**

#### `async run(agent: Agent, input: str) -> RunResult`

Run the agent asynchronously with user input.

**Parameters:**
- `agent`: The Agent configuration to execute
- `input`: The user's input text

**Returns:** `RunResult` object with:
- `final_output`: The final text response from the agent
- `items`: List of all response items (messages, function calls, reasoning, etc.)

**Example:**
```python
result = await Runner.run(agent, "Your question here")
print(result.final_output)
```

#### `run_sync(agent: Agent, input: str) -> RunResult`

Run the agent synchronously with user input.

**Parameters:**
- `agent`: The Agent configuration to execute
- `input`: The user's input text

**Returns:** `RunResult` object (same as async version)

**Example:**
```python
result = Runner.run_sync(agent, "Your question here")
print(result.final_output)
```

### RunResult

Result object returned by Runner methods.

**Attributes:**
- `final_output` (str): The final text response from the agent
- `items` (list): List of all response items

## Requirements

- Python >= 3.10
- openai >= 1.0.0

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/lean-agents.git
cd lean-agents

# Install with development dependencies
uv sync --extra dev

# Run tests
pytest

# Format code
black src/

# Lint code
ruff check src/
```

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.