# Maki

> A Python framework for building multi-agent LLM applications that run on local models via Ollama, hosted APIs (OpenAI, Anthropic, OpenRouter), or a mix of both.

Maki is a Python framework for multi-agent LLM applications developed by Bowl of Data, an open-source AI research community. It lets developers build tool-using agents that run on local hardware through Ollama, on hosted APIs like OpenAI and Anthropic, or a combination of both — using the same agent code throughout. The project is licensed under MIT and is in early 0.x development, self-described as deliberately small and focused.

## What It Is

Maki sits in the agent framework category: it provides the scaffolding to define role-based agents, wire them to LLM backends, equip them with plugins, and orchestrate them in multi-step workflows. Its distinguishing design choice is treating local inference (Ollama) as a first-class backend equal to hosted APIs, rather than an afterthought. All backends — `MakiLLama`, `MakiOpenAI`, `MakiAnthropic`, `MakiOpenRouter`, and `HFBackend` — implement the same abstract `LLMBackend` contract, so swapping inference providers requires changing only one object.

## Architecture and Core Layers

The framework is organized into four layers on top of a shared infrastructure layer:

- **LLM Backends** — Ollama, OpenAI, Anthropic, OpenRouter, and an in-process HuggingFace Transformers backend (requires manual install of `torch`, `transformers`, `accelerate`)
- **Agent System** — `Agent` composes `PluginHandler` and `ReasoningEngine` mixins; `AgentManager` orchestrates agents via `WorkflowTask` and `WorkflowState` with dependency resolution, retries, parallel batching, and checkpoint/resume
- **Distributed Layer** — `AgentServer` (FastAPI) exposes agents over HTTP via `maki serve`; `AgentProxy` provides a remote-agent client with circuit-breaking; `DistributedAgentManager` mixes local and remote agents in the same workflow
- **Infrastructure** — a hardened `Connector` with URL validation, private-address blocking, and DNS pinning; shared data classes; typed exceptions; runtime config; and structured logging

The base install has only three dependencies: `requests`, `httpx`, and `python-dotenv`. All other capabilities are opt-in extras.

## Security and Guardrails

Maki ships with guardrails enabled by default rather than as an optional add-on. URLs sourced from content (web pages, feeds) are checked against private and reserved address ranges at connect time, including redirect hops. Plugins are fail-closed: a model can only call methods a plugin explicitly declares in `ALLOWED_METHODS`, and destructive operations — file writes, FTP transfers, trades — remain disabled unless the agent is instantiated with `allow_dangerous_tools=True`. The trading plugin runs in paper mode unless live trading is explicitly opted into.

## Built-in Plugins

Maki includes 16 built-in plugins across several categories:

- **File system**: `directory_reader`, `file_reader`, `file_writer`, `json_reader`
- **Web**: `web_search` (RSS, HackerNews, Reddit, GitHub Trending, Lobste.rs), `web_to_md`, `provider_updates`, `trend_search`
- **Market data and trading**: `alpaca_data`, `alpaca_news`, `alpaca_trading`, `alpaca_stream`
- **Memory**: `obsidian_memory` (persistent note-based memory via Obsidian vault), `rag_memory` (retrieval-augmented memory with pluggable vector backends)
- **Vision**: `image_classifier`, `ocr`

## Current Status

The repository was created in May 2025 and was last pushed in September 2026, indicating active development. The project self-identifies as version 0.x and explicitly notes it is young and deliberately small. The README acknowledges it is not suited for teams needing a large catalog of third-party integrations, hosted tracing, or a large ecosystem — positioning it as a focused local-first framework for developers who want control over inference and security defaults. The test suite covers 900+ tests across backends, agents, workflows, plugins, connectors, the distributed layer, and security behavior.

## Features
- Local-first LLM inference via Ollama
- Hosted API backends: OpenAI, Anthropic, OpenRouter
- In-process HuggingFace Transformers backend
- Role-based agents with task execution, memory, and reasoning
- Multi-agent orchestration with AgentManager
- Dependency-aware workflow engine with retries and parallel batching
- Checkpoint/resume for long-running workflows
- 16 built-in plugins (files, web, market data, memory, vision)
- Distributed agent serving via maki serve (FastAPI)
- AgentProxy for remote agent consumption with circuit breaker
- Fail-closed plugin security with ALLOWED_METHODS
- Hardened HTTP connector with private-address blocking
- Native tool-calling for Ollama, OpenAI, and Anthropic
- Token-budgeted ConversationMemory
- RAG memory with pluggable vector backends
- Obsidian vault persistent memory
- Streaming, async, and synchronous chat modes
- PySide6 desktop GUI shell
- Bearer-token auth for agent servers
- Paper trading mode for Alpaca plugin

## Integrations
Ollama, OpenAI, Anthropic, OpenRouter, HuggingFace Transformers, Alpaca (market data and trading), Google Trends (pytrends), FastAPI, Redis (workflow checkpoints), Obsidian, FTP/SFTP (paramiko), PySide6/QML

## Platforms
API, CLI, LINUX, MACOS, WINDOWS

## Pricing
Open Source

## Version
0.x

## Links
- Website: https://github.com/BowlOfData/maki
- Documentation: https://github.com/BowlOfData/maki
- Repository: https://github.com/BowlOfData/maki
- EveryDev.ai: https://www.everydev.ai/tools/maki-framework