Metadata-Version: 2.4
Name: agentlite-py
Version: 0.2.0
Summary: A small, focused library for building Claude-powered agents in Python.
Project-URL: Homepage, https://github.com/hakansabunis/agentlite
Project-URL: Issues, https://github.com/hakansabunis/agentlite/issues
Author: Hakan Sabunis
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,claude,llm,tool-use
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# agentlite

[![PyPI](https://img.shields.io/pypi/v/agentlite-py.svg)](https://pypi.org/project/agentlite-py/)
[![tests](https://github.com/hakansabunis/agentlite/workflows/tests/badge.svg)](https://github.com/hakansabunis/agentlite/actions)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

> A small, focused library for building Claude-powered agents in Python.
> Minimal abstractions, prompt caching done right, permissions as a first-class concept.

## What does this project do?

**agentlite** is a tiny (~2,000 lines) Python library that turns plain Python functions into tools an LLM can call, then runs the full agent loop for you — sending the request to Claude, executing the tools Claude asks for, feeding the results back, and stopping when Claude is done. It bakes in three things most lightweight agent libraries skip: **prompt caching is on by default** (~80% input cost reduction on repeated requests), **permission gating is first-class** (mark a tool as `requires_confirmation=True` and the user is asked before it runs), and **a `max_turns` safety brake** prevents runaway loops. You write the tools, you write the system prompt, the library handles the orchestration — no chains, no graphs, no 150K lines of framework to debug.

```python
from agentlite import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Return current weather for a city."""
    return f"{city}: 22°C, sunny"

agent = Agent(model="claude-opus-4-7", tools=[get_weather])
agent.run("What's the weather in Istanbul?")
```

## Why agentlite?

If you've ever tried to build a Claude agent in Python you've probably faced this choice:

- **Anthropic SDK directly** → fast but you write the agent loop, retry logic, permission handling, and prompt caching yourself.
- **LangChain** → batteries included but ~150K lines of abstractions to navigate, and debugging often means reading the framework's source.

**agentlite** sits in between: ~2,000 lines of focused code that handles the agent loop, tool definitions, prompt caching, and permissions — and gets out of your way for everything else.

## Status

🚧 **Alpha** (v0.1.0) — under active development. API may change before v1.0.

## Installation

```bash
pip install agentlite-py
```

> The PyPI distribution name is **`agentlite-py`** (the bare `agentlite` is taken by an unrelated package).
> The Python import is still `agentlite`: `from agentlite import Agent, tool`.

Requires Python 3.10+. Get an Anthropic API key from [console.anthropic.com](https://console.anthropic.com).

## Quick start

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

```python
from agentlite import Agent, tool

@tool
def search_files(pattern: str) -> list[str]:
    """Find files matching a glob pattern."""
    from glob import glob
    return glob(pattern)

@tool
def read_file(path: str) -> str:
    """Read a text file's contents."""
    return open(path, encoding="utf-8").read()

agent = Agent(
    model="claude-opus-4-7",
    system="You help users explore their codebase.",
    tools=[search_files, read_file],
)

agent.run("Find all Python files and summarize the largest one.")
```

## Features

- **`@tool` decorator** — type hints become JSON Schema, docstring becomes description.
- **Built-in agent loop** with `max_turns` safety brake.
- **Streaming support** — `agent.stream_text()` for token-by-token output.
- **Prompt caching by default** — system prompt + tools cached automatically;
  typically ~80% input cost reduction on repeated requests.
- **Verifiable caching** — inspect `response.usage.cache_read_input_tokens`
  to confirm hits (no silent failures).
- **Permission system** (planned) — mark tools as `requires_confirmation` or `read_only`.
- **Sub-agent support** (planned) — delegate sub-tasks without polluting context.

## Comparison

| | LangChain | OpenAI Agents | Anthropic SDK (raw) | **agentlite** |
|---|---|---|---|---|
| LoC to read | ~150K | ~5K | — | **~2K** |
| Prompt caching | manual | none | manual | **automatic** |
| Permission model | none | none | none | **first-class** |
| Multi-agent | complex | handoffs | none | **`@subagent`** |
| Learning curve | steep | medium | low | **very low** |

## Documentation

Full docs and design notes at: **https://hakansabunis.com**

## License

MIT © 2026 Hakan Sabunis
