Metadata-Version: 2.4
Name: monkeybot
Version: 2.2.0
Summary: monkeybot agent harness — FastAPI SSE gateway, owned loop, SQLite, and MCP.
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-ulid>=2.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: aws
Requires-Dist: boto3>=1.34.0; extra == 'aws'
Provides-Extra: bedrock
Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'bedrock'
Requires-Dist: boto3>=1.34.0; extra == 'bedrock'
Provides-Extra: claude
Requires-Dist: anthropic>=0.40.0; extra == 'claude'
Provides-Extra: cli
Requires-Dist: typer>=0.12.0; extra == 'cli'
Requires-Dist: websockets>=14.0; extra == 'cli'
Provides-Extra: cli-realtime
Requires-Dist: pyaudio>=0.2.11; extra == 'cli-realtime'
Requires-Dist: pynput>=1.7.6; extra == 'cli-realtime'
Requires-Dist: typer>=0.12.0; extra == 'cli-realtime'
Requires-Dist: websockets>=14.0; extra == 'cli-realtime'
Provides-Extra: council
Requires-Dist: google-cloud-storage>=2.18.0; extra == 'council'
Provides-Extra: evals
Requires-Dist: deepeval>=3.0.0; extra == 'evals'
Requires-Dist: google-genai>=1.0.0; extra == 'evals'
Requires-Dist: langfuse>=3.0.0; extra == 'evals'
Provides-Extra: firestore
Requires-Dist: google-cloud-firestore>=2.16.0; extra == 'firestore'
Provides-Extra: gcs
Requires-Dist: google-cloud-storage>=2.18.0; extra == 'gcs'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
Provides-Extra: huggingface
Requires-Dist: openai>=1.0; extra == 'huggingface'
Requires-Dist: tiktoken>=0.7.0; extra == 'huggingface'
Provides-Extra: nvidia
Requires-Dist: openai>=1.0; extra == 'nvidia'
Requires-Dist: tiktoken>=0.7.0; extra == 'nvidia'
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.28; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.28; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.62b1; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.28; extra == 'observability'
Provides-Extra: ollama
Requires-Dist: openai>=1.0; extra == 'ollama'
Requires-Dist: tiktoken>=0.7.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Requires-Dist: tiktoken>=0.7.0; extra == 'openai'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
Provides-Extra: realtime
Requires-Dist: websockets>=14.0; extra == 'realtime'
Provides-Extra: realtime-gemini
Requires-Dist: google-genai>=1.0.0; extra == 'realtime-gemini'
Requires-Dist: websockets>=14.0; extra == 'realtime-gemini'
Provides-Extra: sandbox
Requires-Dist: opensandbox>=0.1.7; extra == 'sandbox'
Provides-Extra: scheduler
Requires-Dist: croniter>=2.0; extra == 'scheduler'
Provides-Extra: vertex
Requires-Dist: google-api-python-client>=2.150.0; extra == 'vertex'
Requires-Dist: google-auth>=2.35.0; extra == 'vertex'
Requires-Dist: google-genai>=1.0.0; extra == 'vertex'
Provides-Extra: vertex-claude
Requires-Dist: anthropic[vertex]>=0.40.0; extra == 'vertex-claude'
Provides-Extra: web-search
Requires-Dist: ddgs>=7.0; extra == 'web-search'
Description-Content-Type: text/markdown

# monkeybot

<div align="center">
  <img src="docs/assets/logo.png" alt="monkeybot Logo" width="600" />

  <br />

  *Multi-cloud agent harness — GCP-first docs, portable runtime*

  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

monkeybot is an owned agent runtime for tool-using LLMs: a FastAPI SSE gateway, pluggable storage, MCP tools, skills, and memory. Run locally with zero cloud dependencies, or ship the same container image anywhere Docker runs.

Docs and examples are **GCP-first** (Vertex, GCS, Cloud Run); AWS paths ship in the Pattern guides. See [Cloud deployment — Positioning](docs/cloud-deployment-design.md#positioning).

> [!NOTE]
> Skills under `SKILLS_PATH` execute Python code — only add skills from trusted sources.

## Quick start

Install [uv](https://docs.astral.sh/uv/), then:

```bash
uv tool install monkeybot-cli

monkeybot new --dest ./my-agent --provider openai --yes
cd my-agent
uv sync
cp .env.example .env   # add provider keys
monkeybot doctor
monkeybot chat
```

Upgrade the CLI with `uv tool upgrade monkeybot-cli`. Full walkthrough: **[Getting Started](docs/getting-started.md)**.

## What you get

- **SSE gateway** — sessions, streaming, health; wire your own UI or use the CLI
- **Realtime talk** — WebSocket voice/text via `monkeybot talk`
- **MCP + skills** — stdio/HTTP tools and trusted Python skill bundles
- **Pluggable storage** — SQLite by default; Postgres, Firestore, GCS, S3
- **Multi-provider** — Gemini/Vertex, OpenAI, Anthropic, Bedrock, Ollama, and more

## CLI

| Command | Purpose |
|---|---|
| `monkeybot new` | Scaffold config, workspace, agent `pyproject.toml`, `.env.example` |
| `monkeybot validate` | Check `monkeybot.yaml`, paths, and MCP config |
| `monkeybot doctor` | Verify Python, extras, credentials, and port |
| `monkeybot run` | Start the SSE gateway in the foreground |
| `monkeybot chat` | Talk over SSE (spawns the gateway; `--attach` to join one) |
| `monkeybot talk` | Realtime voice/text over WebSocket (`--text` for typed input) |

```bash
monkeybot chat            # spawn gateway + REPL
monkeybot run             # terminal 1: gateway with logs
monkeybot chat --attach   # terminal 2: attach to it
```

Provider extras live on the **agent** `pyproject.toml` (`monkeybot[<provider>]`), not the global CLI. See [Getting Started](docs/getting-started.md) and [Features — CLI](docs/features.md#16-cli).

## Agent skill

```bash
npx skills add human-plus-machine/monkeybot --skill monkeybot
```

Walks through install, scaffold, config, and first chat. Source: [`cli/skills/monkeybot/`](cli/skills/monkeybot/).

## Documentation

| Guide | Description |
|---|---|
| [Getting Started](docs/getting-started.md) | Install, configure, sessions + SSE from the CLI |
| [Features](docs/features.md) | Architecture, capabilities, CLI, task queue |
| [SSE gateway and custom UI](docs/sse-gateway-ui.md) | HTTP + SSE endpoints, event types, CORS |
| [Skills](docs/skills.md) | Skill directory layout and `SKILL.md` discovery |
| [Model Context Protocol](docs/mcp.md) | MCP config, env interpolation, OAuth2 |
| [Cloud deployment](docs/cloud-deployment-design.md) | Positioning + Patterns A–D index |
| [Live evals](docs/live-evals.md) | Smoke suite, local + CI scorecard |
| [Observability](docs/observability-runbook.md) | OpenTelemetry tracing runbook |

Integrations matrix and roadmap: [CHANGELOG](CHANGELOG.md) · [BACKLOG](BACKLOG.md).

## Contributing

Clone only if you are changing the harness. Setup, checks, and the release workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**. Live eval smoke fixture: [`evals/smoke_agent/`](evals/smoke_agent/).

## Support

Search or open an issue in the [GitHub issue tracker](https://github.com/human-plus-machine/monkeybot/issues).

## License

MIT — see [`LICENSE`](LICENSE).
