Metadata-Version: 2.4
Name: pyagentkit
Version: 1.1.0
Summary: Agent toolkit for Ollama
Project-URL: Homepage, https://github.com/TarikEren/pyagentkit
Project-URL: Issues, https://github.com/TarikEren/pyagentkit/issues
Author-email: Tarık Eren Tosun <tarikerentosun@outlook.com>
Maintainer-email: Tarık Eren Tosun <tarikerentosun@outlook.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,agentic,ai,ollama
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: build>=1.4.2
Requires-Dist: ollama>=0.6.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: twine>=6.2.0
Description-Content-Type: text/markdown

# PyAgentKit

A Python library for building tool-calling agents on top of locally-hosted LLMs via [Ollama](https://ollama.com). PyAgentKit gives models that lack native function-calling support the ability to call tools through structured JSON output, retries, dependency injection, and lifecycle hooks.

---

## Features

- **Sync and async agents** — `Agent` for synchronous use, `AsyncAgent` for `asyncio`-based workflows
- **Tool registration** — attach tools at the class level (shared across all instances) or at the instance level (per-agent)
- **Structured JSON responses** — agents respond in a validated, discriminated-union schema (`final` or `tool_call`)
- **Pydantic response models** — extend `AgentResponse` to add your own typed fields to every response
- **Dependency injection** — pass runtime dependencies (database connections, config, etc.) through `AgentDependencies` into tools without polluting tool signatures
- **Retry logic** — configurable retry budgets separately for tool calls and for response validation failures
- **Approval gates** — optionally require human confirmation before any tool is executed
- **Lifecycle hooks** — sync and async callbacks for tool calls, retries, successes, and final responses
- **Validation hook** — supply `on_validate` to run custom response logic and trigger retries or abort
- **Agent composition** — expose any agent as a tool that another agent can call via `.as_tool()`
- **Token usage tracking** — cumulative `TokenUsage` object updated after every LLM call
- **Message history** — persistent within a session, with optional trimming, save, and load
- **Thinking support** — pass `think=True` to enable chain-of-thought reasoning on supported models

---

## Requirements

- Python 3.12+
- [Ollama](https://ollama.com) running locally (or at a reachable URL)
- A model pulled in Ollama

---

## Installation

```bash
pip install pyagentkit
```

---

## Project Structure

```
src/pyagentkit/
├── agent.py          # Synchronous Agent class
├── async_agent.py    # Asynchronous AsyncAgent class
├── definitions.py    # Pydantic models, type aliases, enums
└── exceptions.py     # Exception hierarchy
```

---

## Core Concepts

### Response Schema

Every agent responds in one of two JSON shapes, validated via Pydantic:

```json
{
  "response": {
    "type": "tool_call",
    "message": "<why you're calling the tool>",
    "tool_call": { "name": "my_tool", "params": [{ "name": "x", "value": "42" }] }
  }
}
```

```json
{
  "response": {
    "type": "final",
    "message": "<your answer or result of your operation(s)>"
  }
}
```

### Exception Hierarchy

```
PyAgentKitError
├── ExceptionAgentError          # Recoverable response failure (triggers retry)
├── ExceptionAgentFatal          # Irrecoverable response failure
├── ExceptionToolError           # Recoverable tool failure (triggers retry)
├── ExceptionToolFatal           # Irrecoverable tool failure
├── ExceptionToolRetriesExhausted
├── ExceptionResponseRetriesExhausted
├── ExceptionEnvironmentError    # Ollama unreachable or model not found
├── ExceptionInvalidTool         # Tool missing docstring or malformed
└── ExceptionFatalError          # Wraps any fatal agent or tool exception
ExceptionUnhandledError          # Unhandled runtime exception (not a PyAgentKitError)
```

---

## License

Apache 2.0
