Metadata-Version: 2.4
Name: maki-framework
Version: 0.4.6
Summary: A Python framework for multi-agent LLM interactions
Author-email: Bowl of Data <bowlofdata@gmail.com>
License: MIT
Project-URL: Homepage, https://bowlofdata.github.io/maki/
Project-URL: Documentation, https://bowlofdata.github.io/maki/docs/
Project-URL: Source, https://github.com/BowlOfData/maki
Project-URL: Issues, https://github.com/BowlOfData/maki/issues
Project-URL: Changelog, https://github.com/BowlOfData/maki/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: httpx>=0.23.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Requires-Dist: psycopg_pool>=3.2; extra == "postgres"
Provides-Extra: structured
Requires-Dist: pydantic>=2.0; extra == "structured"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: openrouter
Requires-Dist: openai>=1.0; extra == "openrouter"
Provides-Extra: llamacpp
Requires-Dist: openai>=1.0; extra == "llamacpp"
Provides-Extra: vllm
Requires-Dist: openai>=1.0; extra == "vllm"
Provides-Extra: distributed
Requires-Dist: fastapi>=0.100.0; extra == "distributed"
Requires-Dist: uvicorn>=0.20.0; extra == "distributed"
Requires-Dist: pyyaml>=6.0; extra == "distributed"
Provides-Extra: distributed-redis
Requires-Dist: redis>=4.5; extra == "distributed-redis"
Provides-Extra: gui
Requires-Dist: PySide6>=6.7.0; extra == "gui"
Provides-Extra: ftp
Requires-Dist: paramiko>=2.11.0; extra == "ftp"
Provides-Extra: web
Requires-Dist: feedparser>=6.0; extra == "web"
Requires-Dist: readability-lxml>=0.8; extra == "web"
Requires-Dist: html2text>=2020.1.16; extra == "web"
Provides-Extra: trends
Requires-Dist: pytrends>=4.9.0; extra == "trends"
Provides-Extra: alpaca
Requires-Dist: alpaca-py>=0.43.0; extra == "alpaca"
Requires-Dist: feedparser>=6.0; extra == "alpaca"
Requires-Dist: yfinance>=0.2.40; extra == "alpaca"
Provides-Extra: all
Requires-Dist: maki-framework[alpaca,anthropic,distributed,distributed-redis,ftp,gui,llamacpp,openai,openrouter,structured,trends,vllm,web]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/BowlOfData/maki/main/img/logo.png" alt="Maki Logo" width="200" />
</p>

# Maki

[![PyPI](https://img.shields.io/pypi/v/maki-framework?logo=pypi&logoColor=white)](https://pypi.org/project/maki-framework/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/BowlOfData/maki/blob/main/LICENSE)
[![CI](https://github.com/BowlOfData/maki/actions/workflows/python-package.yml/badge.svg)](https://github.com/BowlOfData/maki/actions/workflows/python-package.yml)
[![Docs](https://img.shields.io/badge/docs-bowlofdata.github.io-informational)](https://bowlofdata.github.io/maki/docs/)

**Maki is a Python framework for multi-agent LLM applications that run wherever your models do: on your own hardware (through Ollama, llama.cpp or vLLM), on a hosted API (OpenAI, Anthropic, OpenRouter), or a mix of both, with the same agent code.**

It is for developers who want to build and run tool-using agents on local models first, keep the option of moving any task to a hosted model by swapping one object, and have guardrails switched on by default while those agents touch files, the web, or a broker account.

**Documentation: <https://bowlofdata.github.io/maki/docs/>**

## Quickstart

Install [Ollama](https://ollama.com/download), pull a small model, then install Maki:

```bash
ollama pull llama3.2
pip install maki-framework
```

The current release is [0.4.1](https://pypi.org/project/maki-framework/0.4.1/); to pin it, use `pip install maki-framework==0.4.1`.

```python
from maki import MakiLLama
from maki.agents import Agent

agent = Agent(
    name="Reviewer",
    maki_instance=MakiLLama(model="llama3.2"),
    role="code reviewer",
    instructions="Focus on bugs, regressions, and missing validation.",
)

print(agent.execute_task("Review this design: a plugin system with file access."))
```

The package is `maki-framework`; the import is `maki`. To run the same agent on a hosted model, swap the backend object:

```python
from maki import MakiAnthropic   # pip install "maki-framework[anthropic]"

agent = Agent(name="Reviewer", maki_instance=MakiAnthropic(model="claude-sonnet-4-5"), role="code reviewer")
```

Pick a backend from one string, and chain several so a transient failure (network error, timeout, rate limit) moves to the next one:

```python
from maki import FallbackBackend, init_backend

backend = FallbackBackend([
    init_backend("anthropic:claude-sonnet-4-5"),
    "openai:gpt-4o",          # spec strings are built with init_backend
    "ollama:gemma4:26b",      # local last resort
])
agent = Agent(name="Reviewer", maki_instance=backend, role="code reviewer")
```

## Why Maki

- **Local and hosted models are equals.** Ollama, llama.cpp, vLLM, OpenAI, Anthropic and OpenRouter sit behind the same `LLMBackend` contract, and an in-process HuggingFace backend is included. `init_backend("provider:model")` builds any of them from a string, `FallbackBackend` fails over between them (even in the middle of a tool loop), and one conformance suite pins identical behaviour and error mapping across all of them.
- **Guardrails on by default.** Content-derived URLs are checked against private and reserved address ranges at connect time. Plugins are fail-closed, and destructive methods (file writes, FTP transfers, trades) stay disabled until you pass `Agent(allow_dangerous_tools=True)`.
- **Small core.** Three dependencies (`requests`, `httpx`, `python-dotenv`); everything else is an opt-in extra.
- **Agents as services.** `maki serve` exposes any agent over HTTP; `AgentProxy` consumes it remotely.
- **Async-friendly.** `await agent.aexecute_task(...)`, `async for chunk in agent.astream_task(...)` and `await manager.agather_tasks([...])` run agents concurrently without blocking your event loop.
- **Typed, observable tools.** Native tool schemas come from type hints and docstrings, arguments are validated before a method runs, and `ToolPolicy` adds retries with backoff and optional parallel calls (destructive methods are never retried). `AgentCallback` hooks report task, model and tool events.
- **Batteries included.** 18 built-in plugins and a workflow engine with dependency resolution, retries, parallel execution, checkpoint/resume and maker/checker verification.
- **Agents that iterate.** `agent.run_loop(goal, requirements, judge)` keeps an agent working until a separate judge, your tests or your own checks confirm every requirement, with stall detection, token and time budgets, resume and optional human approval; it runs locally, over HTTP and inside workflows.
- **Memory that stays useful.** An opt-in `MemoryPolicy` shortens old turns, pins the facts that must never be lost and clips oversized tool output; an optional summary tier folds evicted turns into a running summary instead of dropping them (in the same live test it recalled 4/4 early facts where dropping recalled 0/4). In a live test on a local `gemma4:26b`, the default setup forgot a fact stated at the start of a 13-message chat while the policy setting answered correctly, with about 45% less text sent.


## Documentation

| | |
|---|---|
| [Quickstart](https://bowlofdata.github.io/maki/docs/quickstart/) | Install to first agent in 5 minutes |
| [Installation and extras](https://bowlofdata.github.io/maki/docs/installation/) | Optional dependencies per backend and plugin |
| [Backends](https://bowlofdata.github.io/maki/docs/backends/) | Ollama, llama.cpp, vLLM, OpenAI, Anthropic, OpenRouter, HuggingFace |
| [Agents](https://bowlofdata.github.io/maki/docs/agents/) | Memory, reasoning, streaming, tools |
| [Workflows](https://bowlofdata.github.io/maki/docs/workflows/) | Multi-agent pipelines and verified tasks |
| [Agent memory](https://bowlofdata.github.io/maki/docs/agent-memory/) | Keep long conversations correct and prompts small |
| [Agent loops](https://bowlofdata.github.io/maki/docs/loops/) | Iterate an agent until its requirements are met |
| [Plugins](https://bowlofdata.github.io/maki/docs/plugins/) | Built-in plugins and the safety model |
| [Serving agents](https://bowlofdata.github.io/maki/docs/serving/) | `maki serve` and `AgentProxy` |
| [Configuration](https://bowlofdata.github.io/maki/docs/configuration/) | Environment variables |

## Contributing

Bug fixes, documentation, new plugins and suggestions are welcome. Open an issue or pull request on [GitHub](https://github.com/BowlOfData/maki). Maki is part of [Bowl of Data](https://bowlofdata.net/), an open-source AI research community.

## License

[MIT](https://github.com/BowlOfData/maki/blob/main/LICENSE)
