Metadata-Version: 2.4
Name: makoto
Version: 0.1.0
Summary: MAKOTO: Mission Integrity for Autonomous Agent Swarms
Author: Quantryx
License: MIT
Keywords: agents,ai,authorization,audit,control-plane
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="assets/logo.svg" alt="MAKOTO logo" width="720">
</p>

<p align="center">
  <a href="https://github.com/quantryx/makoto/actions/workflows/tests.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/quantryx/makoto/tests.yml?branch=main&label=tests"></a>
  <a href="https://pypi.org/project/makoto/"><img alt="pypi" src="https://img.shields.io/pypi/v/makoto.svg"></a>
  <img alt="python" src="https://img.shields.io/badge/python-3.11%2B-blue">
  <img alt="license" src="https://img.shields.io/badge/license-MIT-green">
</p>

# MAKOTO

**Your AI agent should not be able to deploy production just because it can call a tool.**

MAKOTO gives agents signed, bounded missions. A tool runs only when the agent
brings a valid proof-carrying tool call.

```text
agent: deploy production
tool:  DENIED - missing signed work order
```

MAKOTO is not another agent framework. It is the missing control layer for
agent frameworks.

> Agents do not get broad permissions. They get signed missions.

## Install

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python examples/deploy_denied_demo.py
```

Expected:

```text
DENIED: Tool is explicitly forbidden: deploy_production
BLOCKED BY TOOL: Tool deploy_production requires a MAKOTO proof
```

Or run the one-file copy-paste demo:

```bash
python3 examples/one_file_demo.py
```

## Why This Exists

Most agent frameworks answer:

> How can an agent complete this task?

MAKOTO answers:

> Is this agent allowed to run this tool, for this mission, right now?

That difference matters when agents can merge code, send email, move money,
close accounts, rotate secrets, call APIs, or deploy production.

## What OSS Includes

- `MissionCampaignPermit`
- `SignedWorkOrder`
- `ProofCarryingToolCall`
- `OutcomeRecord`
- signed audit events
- resource conflict locking
- campaign replay
- local SQLite ledger for development
- `@protected_tool(...)` decorator
- dangerous tool catalog with risk scores
- CLI: `makoto demo`, `makoto wrap`, `makoto explain`, `makoto score`, `makoto check`, `makoto init`, `makoto sign`, `makoto verify`, `makoto export-schemas`
- release helpers: `makoto version`, `makoto doctor`
- dependency-free adapters for OpenAI-style, Claude-style, Gemini-style, LangGraph-style, CrewAI-style, and AutoGen-style tool calls

## What MAKOTO Is Not

- Not an agent framework
- Not a sandbox
- Not a production gateway by itself
- Not a compliance certification

MAKOTO OSS is the protocol, SDK, verifier, and local enforcement reference.

## 30-Second Demo

```bash
makoto demo
makoto demo --short
python3 examples/one_file_demo.py
```

The default demo uses a generic pull-request safety workflow: an AI agent may
read CI logs and run tests, but it cannot merge, deploy, or rotate secrets
without a signed work order that allows those tools.

## Create A Quickstart Project

```bash
makoto init my-makoto-demo
cd my-makoto-demo
python app.py
```

## Public Use Cases

The OSS examples are intentionally neutral and useful for most developers:

- CI / Pull Request Safety: read logs and run tests, but do not merge or deploy.
- Research Agent Safety: read notes and write summaries, but do not send email.
- Finance Review Safety: draft approval notes, but do not send payments.
- Customer Support Safety: draft replies, but do not issue refunds.

Run them:

```bash
python3 examples/one_file_demo.py
python3 examples/deploy_denied_demo.py
python3 examples/local_agent_loop.py
python3 examples/ci_safety_demo.py
python3 examples/research_safety_demo.py
python3 examples/finance_safety_demo.py
python3 examples/customer_support_safety_demo.py
python3 examples/openai_style_adapter_demo.py
python3 examples/claude_style_adapter_demo.py
python3 examples/gemini_style_adapter_demo.py
python3 examples/framework_adapter_demo.py
```

## Connect It To Your Agent

MAKOTO works with any setup where your application receives a tool call and then
executes it:

- local Python agents
- local LLMs through Ollama, llama.cpp, vLLM, or custom runners
- OpenAI-style tool calling
- Claude-style tool calling
- Gemini-style function calling
- LangGraph / CrewAI / AutoGen
- MCP servers

Pattern:

```text
model requests tool -> MAKOTO authorizes -> protected tool verifies -> tool runs
```

See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).

## Wrap Any Command

Use `makoto wrap` to put a local command behind a MAKOTO tool check.

Without a signed work order, the command is denied and a denial explanation JSON
is written to `/tmp`:

```bash
makoto wrap --tool deploy_production -- echo "deploying..."
makoto explain /tmp/makoto_denied_deploy_production.json
```

For local demos, `--allow-dev` creates a short-lived development mission first:

```bash
makoto wrap --tool run_tests --allow-dev -- python3 -c "print('tests passed')"
```

Production tools should verify `MAKOTO_PROOF` or use `@protected_tool(...)`
inside the tool boundary.

## Safety Score

Score how much MAKOTO coverage a local project has:

```bash
makoto score
```

The score checks for dangerous tool names, `@protected_tool(...)` usage,
campaigns, signed work orders, proof-carrying tool calls, and recorded outcomes.

## Minimal Code

```python
from makoto import MakotoClient, protected_tool

client = MakotoClient()

# After creating a campaign and signed work order:
proof = client.authorize_tool_call(
    work_order_id=work_order.work_order_id,
    agent_id="ci-agent-01",
    tool_name="run_tests",
    tool_input={"pull_request": 42},
)

@protected_tool("run_tests", client)
def run_tests(*, tool_input):
    return {"passed": True}

run_tests(tool_input={"pull_request": 42}, makoto_proof=proof)
```

## Core Rule

Tools should execute only after verifying a proof-carrying tool call:

```python
if not client.verify_tool_call(proof):
    raise PermissionError("Missing valid MAKOTO proof chain")
```

Or wrap a Python tool directly:

```python
from makoto import protected_tool

@protected_tool("run_tests", client)
def run_tests(*, tool_input):
    return {"passed": True}

run_tests(tool_input={"pull_request": 42}, makoto_proof=proof)
```

## Protocol Verification

The CLI can validate MAKOTO protocol objects without running the enterprise
gateway:

```bash
makoto verify campaign examples/campaign.json
```

If you also provide the development HMAC secret used to sign the object, the CLI
verifies the signature:

```bash
MAKOTO_HMAC_SECRET=dev-secret makoto sign campaign examples/campaign.json --out /tmp/campaign.signed.json
MAKOTO_HMAC_SECRET=dev-secret makoto verify campaign /tmp/campaign.signed.json
```

## Export JSON Schemas

```bash
makoto export-schemas ./schemas
```

## Open-Core Boundary

Open source:

- protocol objects and schema export
- canonical JSON and hashing
- basic local signer/verifier
- local SDK and SQLite development ledger
- `@protected_tool(...)` local enforcement example

Commercial:

- non-bypassable gateway
- Cedar/OPA policy engine
- MCP tool proxy
- enterprise Postgres ledger
- swarm routing, conflict management, and witness orchestration
- ATC dashboard
- regulatory/causal/learning layers

The current default signer is an HMAC development signer so the core runs
without external dependencies. The signer boundary is explicit and can be
replaced with Ed25519/KMS/HSM in production.
