Metadata-Version: 2.5
Name: teotl
Version: 0.2.2
Summary: Autonomous agent framework with a planner-worker architecture, built-in guardrails, and multi-provider support (Claude, GPT, Gemini, Ollama).
Project-URL: Homepage, https://github.com/keithdit4e/teotl
Project-URL: Documentation, https://github.com/keithdit4e/teotl/blob/main/docs
Project-URL: Repository, https://github.com/keithdit4e/teotl
Project-URL: Issues, https://github.com/keithdit4e/teotl/issues
Project-URL: Changelog, https://github.com/keithdit4e/teotl/blob/main/CHANGELOG.md
Author: Keith Foster
Maintainer: Keith Foster
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,ai-agents,anthropic,autonomous,claude,cost-optimization,framework,gemini,guardrails,llm,mcp,memory,ollama,openai,planner-worker
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: ulid-py>=1.1
Provides-Extra: all
Requires-Dist: aiohttp>=3.9; extra == 'all'
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: browser-use>=0.1; extra == 'all'
Requires-Dist: cryptography>=43.0; extra == 'all'
Requires-Dist: google-generativeai>=0.8; extra == 'all'
Requires-Dist: keyring>=25.0; extra == 'all'
Requires-Dist: litellm>=1.50; extra == 'all'
Requires-Dist: ollama>=0.4; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Requires-Dist: sqlite-vec>=0.1; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Provides-Extra: browser
Requires-Dist: browser-use>=0.1; extra == 'browser'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.8; extra == 'google'
Provides-Extra: litellm
Requires-Dist: litellm>=1.50; extra == 'litellm'
Provides-Extra: memory
Requires-Dist: sentence-transformers>=3.0; extra == 'memory'
Requires-Dist: sqlite-vec>=0.1; extra == 'memory'
Provides-Extra: ollama
Requires-Dist: ollama>=0.4; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Provides-Extra: security
Requires-Dist: cryptography>=43.0; extra == 'security'
Requires-Dist: keyring>=25.0; extra == 'security'
Provides-Extra: web
Requires-Dist: aiohttp>=3.9; extra == 'web'
Description-Content-Type: text/markdown

# Teotl

**An autonomous agent framework for Python: planner-worker execution, built-in guardrails, and any LLM provider.**

[![PyPI](https://img.shields.io/pypi/v/teotl)](https://pypi.org/project/teotl/)
[![Python](https://img.shields.io/pypi/pyversions/teotl)](https://pypi.org/project/teotl/)
[![CI](https://github.com/keithdit4e/teotl/actions/workflows/ci.yml/badge.svg)](https://github.com/keithdit4e/teotl/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Teotl splits agent work between a **planner** (a strong model that runs once to write a step-by-step plan) and a **worker** (a cheaper, faster model that executes each step). Every tool call passes through a policy-based guardrail layer before it runs, and a harness keeps plans, progress, costs, and audit logs on disk so long-running missions can pause, resume, and be inspected.

> **Status:** alpha (v0.2.0). APIs may change between minor versions.

## Features

- **Planner-worker harness**: plan once with a capable model, execute many steps with a cheap one
- **Guardrails**: `minimal` / `standard` / `strict` policies, bash command analysis, prompt-injection checks, rate and cost limits, progressive trust
- **Multi-provider**: Anthropic Claude, OpenAI, Google Gemini, Ollama (local), or LiteLLM
- **Skills**: capabilities defined in `SKILL.md` files, loaded on demand to save context (filesystem, git, GitHub, web, Claude Code, spec-kit, social media)
- **Memory**: optional local vector memory with automatic context compaction
- **Harness artifacts**: `PLAN.md`, `PROGRESS.md`, state checkpoints, cost tracking, append-only audit log
- **Credentials**: OS keyring, encrypted file, or AWS Secrets Manager storage
- **CLI and dashboard**: interactive chat, onboarding wizard, and a web dashboard for monitoring agents

## Installation

```bash
pip install "teotl[anthropic]"
```

Pick the extras you need:

| Extra | Adds |
|-------|------|
| `anthropic` | Claude models |
| `openai` | OpenAI models |
| `google` | Gemini models |
| `ollama` | Local models via Ollama |
| `litellm` | Any provider via LiteLLM |
| `memory` | Vector memory (sentence-transformers, sqlite-vec) |
| `security` | OS keyring and encrypted credential storage |
| `web` | Web dashboard |
| `browser` | Browser automation (browser-use) |
| `aws` | AWS Secrets Manager credential backend |
| `all` | Everything above |

Requires Python 3.11 or newer.

## Quick start

Set an API key:

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

### A single agent

```python
import asyncio

from teotl import Agent
from teotl.core.provider import AnthropicProvider


async def main():
    agent = Agent(
        provider=AnthropicProvider(model="claude-sonnet-5-5"),
        instructions="You are a careful code reviewer.",
        skills=["filesystem", "git"],
        policy="standard",  # or "strict" / "minimal"
    )
    response = await agent.run("Summarize the last 5 commits in this repo.")
    print(response.text)
    print(f"Cost: ${response.cost:.4f}")


asyncio.run(main())
```

### Planner-worker

```python
import asyncio
from pathlib import Path

from teotl.core.provider import AnthropicProvider
from teotl.primitives.harness import PlannerWorkerHarness


async def main():
    harness = PlannerWorkerHarness(
        agent_id="code-quality",
        planner_provider=AnthropicProvider(model="claude-sonnet-5-5"),        # plans once
        worker_provider=AnthropicProvider(model="claude-haiku-4-5"),  # executes each step
        workspace_dir=Path(".teotl/code-quality"),
        worker_skills=["filesystem", "git"],
    )

    plan = await harness.plan(goals="Add type hints and docstrings to public functions in src/.")
    print(f"Plan has {plan.total_steps} steps (see PLAN.md)")

    while not harness.is_complete():
        result = await harness.execute_next_step()
        print(f"Step {result.step.number}: {'ok' if result.success else result.error}")


asyncio.run(main())
```

The harness writes `PLAN.md` and `PROGRESS.md` into the workspace, so you can read, edit, or resume a plan at any point. By default it asks for approval before starting each new execution cycle.

### Other providers

```python
from teotl.core.provider import GeminiProvider, OllamaProvider, OpenAIProvider

GeminiProvider(model="gemini-2.5-flash")   # GOOGLE_API_KEY
OpenAIProvider(model="gpt-4.1")            # OPENAI_API_KEY
OllamaProvider(model="llama3.1")           # local, no key
```

You can mix providers, for example a Claude planner with a local Ollama worker.

## Command line

```bash
teotl --help
teotl onboard      # interactive setup wizard: provider, skills, policy, planner-worker config
teotl chat         # interactive chat with an agent
teotl security     # manage credentials and security settings
```

## Guardrails

Every tool call is classified and checked against a policy **before** it executes. This happens outside the model's context, so a prompt can't talk its way past it.

- `strict`: read-only by default; writes and shell commands need approval
- `standard`: common development actions allowed; destructive or sensitive actions need approval
- `minimal`: for trusted sandboxes

Built-in protections include bash command analysis (for example blocking `rm -rf /` and piping remote scripts to a shell), prompt-injection checks on instructions and incoming messages, per-agent rate and cost limits, and a trust score that grows with repeated safe behavior. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md).

## Skills

A skill is a folder containing a `SKILL.md` file (YAML frontmatter plus instructions). Only each skill's short description sits in context until the agent activates it, which keeps prompts small.

Teotl looks for skills in:

1. the skills bundled with the package
2. `~/.teotl/skills/` (your own skills; the data directory can be moved with `TEOTL_HOME`)
3. any directories listed in `TEOTL_SKILLS_PATH` (colon-separated)

See [docs/SKILLS_GUIDE.md](docs/SKILLS_GUIDE.md) and [docs/CUSTOM_SKILLS_QUICKSTART.md](docs/CUSTOM_SKILLS_QUICKSTART.md).

## Examples

| Example | What it shows |
|---------|---------------|
| [`examples/planner_worker_demo.py`](examples/planner_worker_demo.py) | Planner-worker plan and execute loop |
| [`examples/devops_agent/`](examples/devops_agent/) | Agent that triages GitHub issues and proposes fixes |
| [`examples/supervisor_demo.py`](examples/supervisor_demo.py) | Supervised execution with approvals |
| [`examples/custom_skill_example.py`](examples/custom_skill_example.py) | Writing your own skill |
| [`examples/full_config_reference.yaml`](examples/full_config_reference.yaml) | Every YAML configuration option |
| [`examples/social_media_agent.yaml`](examples/social_media_agent.yaml) | Browser-driven social media skills |

## Documentation

- [Getting started](docs/GETTING_STARTED.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Guardrails](docs/GUARDRAILS.md) and [security guide](docs/SECURITY_GUIDE.md)
- [Memory](docs/MEMORY.md)
- [Model strategy](docs/MODEL_STRATEGY.md)
- [Multi-agent guide](docs/MULTI_AGENT_GUIDE.md)

## Roadmap

- [x] Planner-worker harness
- [x] Guardrails, credential storage, audit log, cost tracking
- [x] Anthropic, OpenAI, Gemini, Ollama, LiteLLM providers
- [x] YAML configuration for multi-agent setups
- [x] Browser automation and social media skills
- [ ] Published benchmark results (GAIA and cost comparisons)
- [ ] More end-to-end examples (code review, test generation)
- [ ] Deeper MCP integration

## Contributing

Bug reports, ideas, and pull requests are welcome.

- Questions and ideas: [Discussions](https://github.com/keithdit4e/teotl/discussions)
- Bugs and feature requests: [Issues](https://github.com/keithdit4e/teotl/issues)
- Code: see [CONTRIBUTING.md](CONTRIBUTING.md)

```bash
git clone https://github.com/keithdit4e/teotl
cd teotl
pip install -e ".[dev,anthropic]"
pytest
```

Report security issues privately. See [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE) © Keith Foster
