Metadata-Version: 2.4
Name: ollama-agent-base
Version: 0.1.1
Summary: Simple ollama ai agent base for allowing a ai to run python functions
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: ollama>=0.6.2

# ollama_agent_base

A lightweight tool-calling agent framework for Ollama.

This project provides a simple way to create AI agents that can call Python functions ("tools"), execute actions, and maintain conversation history.

## Features

* Simple tool registration
* Automatic tool argument inspection
* Multi-step agent execution loop
* JSON-based tool calling
* Conversation memory
* Custom system prompts
* Configurable Ollama model and host

---

## Installation

```bash
pip install ollama_base_agent
```

---

## Quick Start

### Create a Tool

```python
from ollama_agent_base import Tool

def print_tool(message: str):
    print(message)

    return {
        "printed": message
    }

print_to_terminal_tool = Tool(
    name="print",
    func=print_tool,
    description="Send a message to the user via terminal output"
)
```

### Register Tools

```python
from ollama_agent_base import register_tools
import tools

register_tools([
    tools.print_to_terminal_tool
])
```

### Create an Agent

```python
from ollama_agent_base import Agent

agent = Agent(
    system_prompt=None,
    model="gemma3"
)

agent.reset()
```

### Ask a Question

```python
agent.ask(
    "What programming language is easiest to print in?"
)
```

---

## Tool Definition

Tools are regular Python functions wrapped in a `Tool` object.

```python
def add(a: int, b: int):
    return {
        "result": a + b
    }

add_tool = Tool(
    name="add",
    func=add,
    description="Add two numbers together"
)
```

Arguments are automatically detected from the function signature.

Example:

```python
def greet(name: str, times: int = 1):
    ...
```

Produces:

```json
{
  "name": "str",
  "times": "int (default=1)"
}
```

---

## Tool Registration

Single tool:

```python
register_tools(
    my_tool
)
```

Multiple tools:

```python
register_tools(
    tool_a,
    tool_b,
    tool_c
)
```

Or:

```python
register_tools(*tool_list)
```

---

## Agent Configuration

```python
agent = Agent(
    model="gemma3",
    host="http://127.0.0.1:11434",
    max_steps=10
)
```

### Parameters

| Parameter | Description             |
| --------- | ----------------------- |
| model     | Ollama model name       |
| host      | Ollama server URL       |
| max_steps | Maximum tool iterations |

---

## Environment Variables

Supported environment variables:

```bash
OLLAMA_MODEL=gemma3
OLLAMA_HOST=http://127.0.0.1:11434
```

---

## Example Project Structure

```text
project/
│
├── main.py
├── tools.py
│
└── src/
    └── ollama_agent_base/
        ├── __init__.py
        └── agent.py
```

---

## Example

```python
from ollama_agent_base import Agent, register_tools
import tools

register_tools(
    tools.print_to_terminal_tool
)

agent = Agent(
    system_prompt=None
)

agent.reset()

agent.ask(
    "Say hello"
)
```

---

## How It Works

1. User sends a message.
2. Agent sends conversation history and tool definitions to Ollama.
3. Model responds with a JSON tool call.
4. Tool executes.
5. Result is added to conversation history.
6. Process repeats until completion.

---

## Goals

This project aims to be:

* Lightweight
* Easy to understand
* Minimal dependencies
* Easy to extend
* Compatible with local Ollama models

It is intentionally much smaller than frameworks such as LangChain while still supporting tool-calling workflows.
