Metadata-Version: 2.4
Name: openpaw-ai
Version: 0.4.4
Summary: OpenPaw - Multi-Channel AI Agent Framework with LangGraph
License: PolyForm Noncommercial 1.0.0
License-File: LICENSE
Keywords: ai,agent,langgraph,telegram,discord,bot
Author: John Sosoka
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Communications :: Chat
Classifier: Framework :: AsyncIO
Provides-Extra: all-builtins
Provides-Extra: documents
Provides-Extra: email
Provides-Extra: mcp
Provides-Extra: memory
Provides-Extra: moonshot
Provides-Extra: ollama
Provides-Extra: researcher
Provides-Extra: voice
Provides-Extra: web
Requires-Dist: apscheduler (>=3.10.0,<4.0.0)
Requires-Dist: discord.py (>=2.6.0,<3.0.0)
Requires-Dist: docling (>=2.72.0,<3.0.0) ; extra == "all-builtins"
Requires-Dist: docling (>=2.72.0,<3.0.0) ; extra == "documents"
Requires-Dist: easyocr (>=1.7.2,<2.0.0) ; extra == "all-builtins"
Requires-Dist: easyocr (>=1.7.2,<2.0.0) ; extra == "documents"
Requires-Dist: elevenlabs (>=1.0.0) ; extra == "all-builtins"
Requires-Dist: elevenlabs (>=1.0.0) ; extra == "voice"
Requires-Dist: fireworks-ai (>=0.16.4,<0.17.0)
Requires-Dist: google-api-python-client (>=2.0.0) ; extra == "all-builtins"
Requires-Dist: google-api-python-client (>=2.0.0) ; extra == "email"
Requires-Dist: google-auth (>=2.0.0) ; extra == "all-builtins"
Requires-Dist: google-auth (>=2.0.0) ; extra == "email"
Requires-Dist: google-auth-httplib2 (>=0.2.0) ; extra == "all-builtins"
Requires-Dist: google-auth-httplib2 (>=0.2.0) ; extra == "email"
Requires-Dist: httpx (>=0.27.0) ; extra == "all-builtins"
Requires-Dist: httpx (>=0.27.0) ; extra == "researcher"
Requires-Dist: langchain (>=1.2.8,<2.0.0)
Requires-Dist: langchain-anthropic (>=1.3.1,<2.0.0)
Requires-Dist: langchain-aws (>=1.0.0,<2.0.0)
Requires-Dist: langchain-community (>=0.4.0) ; extra == "all-builtins"
Requires-Dist: langchain-community (>=0.4.0) ; extra == "web"
Requires-Dist: langchain-fireworks (>=1.3.1,<1.4.0)
Requires-Dist: langchain-mcp-adapters (>=0.3.0,<1.0.0) ; extra == "all-builtins"
Requires-Dist: langchain-mcp-adapters (>=0.3.0,<1.0.0) ; extra == "mcp"
Requires-Dist: langchain-moonshot (>=0.1.0,<1.0.0) ; extra == "all-builtins"
Requires-Dist: langchain-moonshot (>=0.1.0,<1.0.0) ; extra == "moonshot"
Requires-Dist: langchain-ollama (>=1.0.1,<2.0.0) ; extra == "all-builtins"
Requires-Dist: langchain-ollama (>=1.0.1,<2.0.0) ; extra == "ollama"
Requires-Dist: langchain-openai (>=1.1.7,<2.0.0)
Requires-Dist: langchain-xai (>=1.2.2,<2.0.0)
Requires-Dist: langgraph (>=1.0.7,<2.0.0)
Requires-Dist: langgraph-checkpoint-sqlite (>=2.0.0,<4.0.0)
Requires-Dist: openai (>=1.0.0) ; extra == "all-builtins"
Requires-Dist: openai (>=1.0.0) ; extra == "voice"
Requires-Dist: opencv-python-headless (>=4.13.0.92,<5.0.0.0) ; extra == "all-builtins"
Requires-Dist: opencv-python-headless (>=4.13.0.92,<5.0.0.0) ; extra == "documents"
Requires-Dist: playwright (>=1.58.0,<2.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
Requires-Dist: python-telegram-bot[job-queue] (>=22.6,<23.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: sqlite-vec (>=0.1.6) ; extra == "all-builtins"
Requires-Dist: sqlite-vec (>=0.1.6) ; extra == "memory"
Requires-Dist: websockets (>=12.0) ; extra == "all-builtins"
Requires-Dist: websockets (>=12.0) ; extra == "researcher"
Project-URL: Changelog, https://github.com/johnsosoka/OpenPaw/blob/main/CHANGELOG.md
Project-URL: Documentation, https://johnsosoka.github.io/OpenPaw/
Project-URL: Homepage, https://johnsosoka.github.io/OpenPaw/
Project-URL: Issues, https://github.com/johnsosoka/OpenPaw/issues
Project-URL: Repository, https://github.com/johnsosoka/OpenPaw
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/johnsosoka/OpenPaw/main/docs/assets/images/logo.png" alt="OpenPaw" width="400">
  <p><strong>A Friendly <a href="https://langchain-ai.github.io/langgraph/">LangChain/LangGraph</a> Multi-Agent Runner</strong></p>
  <p>
    <a href="https://github.com/johnsosoka/OpenPaw/actions/workflows/ci.yml"><img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
    <a href="https://github.com/johnsosoka/OpenPaw/actions/workflows/docs.yml"><img src="https://github.com/johnsosoka/OpenPaw/actions/workflows/docs.yml/badge.svg?branch=main" alt="Docs"></a>
    <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
    <img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-green" alt="License">
  </p>
</div>

---

> **Alpha Software** -- OpenPaw is in active development and should be considered an alpha release. APIs, configuration formats, and behavior may change between versions. Contributions and feedback are welcome, but expect rough edges.

OpenPaw gives each agent its own workspace -- personality files, custom tools, scheduled tasks -- then gets out of the way. It handles the orchestration so you can focus on what your agents actually do.

Agents can ingest documents, browse the web, search the internet, delegate to specialist sub-agents, and manage their own files -- making them well-suited for research, information processing, and long-running autonomous workflows. Give them a schedule and they'll check in on their own.

> **[Read the full documentation](https://johnsosoka.github.io/OpenPaw/)**

## Highlights

### Composable sub-agent teams

Every primary agent is a team lead. Drop a YAML into `agent/team/` and your agent gains a teammate it can dispatch with `spawn_agent(profile="researcher")`:

```yaml
name: researcher
description: "Web research specialist — searches, cross-references, and cites sources."
system_prompt: |
  You are a focused research specialist. Search, cross-reference, and
  summarize findings with source citations.
model: anthropic:claude-sonnet-4-20250514
allowed_tools: [brave_search, read_file, write_file]
timeout_minutes: 10
max_turns: 20
```

Each teammate gets its own model, tool loadout, skill set, and lifecycle budget. Run several in parallel -- the parent dispatches, they work, results route back when they finish.

### Live in-place status updates

Both your primary agent **and every sub-agent** maintain a single status message that edits in place as work progresses. No chat flood, no scroll-back -- just a live, current view of who's doing what right now. Get actionable insight into your agent teams at a glance. Agents can also call `report_progress` to announce structured milestones with their own emoji.

### Mid-run responsiveness

Send a follow-up while the agent is mid-task and it sees it. Steer the run ("🔄 Redirecting..."), interrupt completely ("🛑 Stopping..."), or let messages batch quietly ("📨 New messages received..."). One-line emoji notifications keep you in the loop without breaking the agent's flow.

Typing indicators run while the agent is processing; emoji reactions on your original message track success (👍) or failure (👎).

### Channels

**Telegram + Discord, simultaneously** -- One workspace, multiple channels. Trigger-based activation (mentions, keywords, or both) lets agents respond appropriately in group chats. On-demand channel history gives them awareness of recent conversation when triggered.

### Workspace identity

Each agent gets its own SOUL (personality), AGENT (capabilities), USER (context), and HEARTBEAT (agent-writable scratchpad) files, plus a sandboxed filesystem. `config/` and `data/` are write-protected from the agent itself; everything else lives under `workspace/`.

**Skills** -- Reusable knowledge blocks (`SKILL.md`) drop into the workspace and can be selectively granted to specific team members.

### Tools that do real work

- **Document processing** -- Docling OCR/ICR turns scanned PDFs, DOCX, and PPTX into markdown automatically. Whisper transcribes voice messages on arrival.
- **Browser automation** -- Playwright-driven web interaction via the accessibility tree. Agents reference elements by number, not CSS selectors.
- **Email integration** -- Send and receive via Gmail with safe-by-default recipient policies. Search, reply with threading, manage attachments.
- **MCP servers** -- Connect any MCP-compatible service (local stdio or remote Streamable HTTP) per workspace. Tools flow into the agent alongside builtins.
- **Deep research** -- Connect to a self-hosted GPT-Researcher instance for multi-source reports with citations.
- **Web search** -- Brave Search and other providers for direct search-and-summarize.
- **Drop-in custom tools** -- Write a `@tool` function, save it to `agent/tools/`, restart. Auto-discovered, no wiring needed.

### Scheduling & autonomy

- **Cron and heartbeats** -- Recurring jobs from YAML, plus proactive check-ins agents can configure themselves.
- **Dynamic scheduling** -- `schedule_at`, `schedule_every`, `request_followup`. Your agent can plan its own future.
- **Auto-compact** -- When the context window fills, the framework summarizes old turns and continues without missing a beat.
- **Runtime model switching** -- `/model anthropic:claude-opus-4-20250514` mid-conversation. No restart.

### Safe by default

- **Approval gates** -- Human-in-the-loop authorization for sensitive operations with configurable timeouts and channel-native UI.
- **Recipient policies** -- Email defaults to deny-all sends; only addresses on your allowlist go through.
- **Sandboxed filesystem** -- Custom tools write to `workspace/` by default; `config/` and `data/` are read-only to agents.

### Multi-provider LLMs

Anthropic, OpenAI, AWS Bedrock, xAI, Fireworks, and any OpenAI-compatible endpoint. Define providers once in global config and reference by name from any workspace.

## Quick Start

> **Recommended:** run your agent on **Telegram** — you get a real chat UI, in-place status updates, and access from your phone. Grab a bot token from [@BotFather](https://core.telegram.org/bots#botfather) (takes a minute); Discord works the same way.

### Install from PyPI

The quickest path — no clone required:

```bash
pip install openpaw-ai
openpaw init my_agent --model anthropic:claude-sonnet-4-20250514 --channel telegram
openpaw -c config.yaml -w my_agent
```

`openpaw init` scaffolds the workspace **and** a starter `config.yaml`, so `run` works right away. Add your LLM provider key and Telegram bot token to `agent_workspaces/my_agent/config/.env` (e.g. `ANTHROPIC_API_KEY=...` and `TELEGRAM_BOT_TOKEN=...`) before running.

Optional capabilities install as extras: `pip install 'openpaw-ai[documents]'` (Docling OCR/PDF), plus `[voice]`, `[web]`, `[memory]`, `[email]`, `[mcp]`, or `[all-builtins]`.

### Install from source (Poetry)

The steps below use the from-source workflow; prefix commands with `poetry run`.

#### 1. Install

```bash
git clone https://github.com/johnsosoka/OpenPaw.git
cd OpenPaw
poetry install
```

#### 2. Scaffold a workspace

```bash
poetry run openpaw init my_agent \
  --model anthropic:claude-sonnet-4-20250514 \
  --channel telegram
```

This also writes a starter `config.yaml` in the current directory (it won't overwrite an existing one). To start from the fully-commented reference instead, copy it first: `cp config.example.yaml config.yaml`.

#### 3. Configure

Add your API keys to `agent_workspaces/my_agent/config/.env`:

```bash
ANTHROPIC_API_KEY=your-key-here
TELEGRAM_BOT_TOKEN=your-token-here
```

#### 4. Run

```bash
poetry run openpaw -c config.yaml -w my_agent
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `openpaw init <name>` | Scaffold a new agent workspace |
| `openpaw init <name> --model <provider:model>` | Scaffold with a pre-configured model |
| `openpaw init <name> --channel telegram` | Scaffold with a channel pre-configured (`telegram` or `discord`) |
| `openpaw list` | List available workspaces |
| `openpaw -c config.yaml -w <name>` | Run a single workspace |
| `openpaw -c config.yaml -w name1,name2` | Run multiple workspaces |
| `openpaw -c config.yaml --all` | Run all discovered workspaces |
| `openpaw -c config.yaml -w <name> -v` | Run with verbose logging |

All commands should be prefixed with `poetry run` when running from the project directory.

## Agent Workspace Structure

Each workspace lives under `agent_workspaces/<name>/` and is organized into five directories:

```
agent_workspaces/my_agent/
├── agent/              # Identity files, custom tools, team profiles, and skills
│   ├── AGENT.md
│   ├── USER.md
│   ├── SOUL.md
│   ├── HEARTBEAT.md
│   ├── tools/
│   ├── team/
│   └── skills/
├── config/             # Configuration and secrets (write-protected)
│   ├── agent.yaml
│   ├── .env
│   └── crons/
├── data/               # Framework-managed state (write-protected)
│   ├── TASKS.yaml
│   ├── uploads/
│   └── ...
├── memory/             # Archived conversations and session logs
│   ├── conversations/
│   └── logs/
│       ├── channel/
│       └── sessions/
└── workspace/          # Agent work area (default write target)
    ├── downloads/
    └── screenshots/
```

The `openpaw init` command scaffolds this structure with starter templates. Customize the identity files in `agent/` to shape your agent's personality and purpose. Configure model, channel, and queue behavior in `config/agent.yaml`.

The `data/` and `config/` directories are write-protected from agent filesystem tools. Write operations default to the `workspace/` directory unless an explicit path is provided.

## In-Chat Commands

Once running, agents respond to framework commands in chat:

| Command | Description |
|---------|-------------|
| `/help` | List available commands |
| `/status` | Show model, context usage, tasks, and token usage |
| `/new` | Archive conversation and start fresh |
| `/compact` | Summarize, archive, and continue with summary |
| `/model <provider:model>` | Switch LLM model at runtime |

## Documentation

- [Getting Started](docs/getting-started.md) -- Installation, first workspace, and troubleshooting
- [Concepts](docs/concepts.md) -- How workspaces, scheduling, queues, and tools fit together
- [Configuration](docs/configuration.md) -- Global and per-workspace configuration reference
- [Workspaces](docs/workspaces.md) -- Workspace structure, identity files, and custom tools
- [Scheduling](docs/scheduling.md) -- Cron jobs, heartbeats, and dynamic scheduling
- [Built-ins](docs/builtins.md) -- Web search, browser automation, email, voice, sub-agents, and more
- [MCP Servers](docs/mcp.md) -- Per-workspace MCP server connections (HTTP and stdio)
- [Channels](docs/channels.md) -- Channel adapters and access control
- [Queue System](docs/queue-system.md) -- Queue modes and message handling
- [Architecture](docs/architecture.md) -- System design, data flows, and architectural decisions

## Contributing

Development follows a GitFlow branching model:

- **`main`** -- Stable releases only. Protected branch, requires CI to pass.
- **`develop`** -- Integration branch. Feature and bugfix PRs target `develop`.
- **Feature branches** -- Branch from `develop` as `feature/`, `bugfix/`, `docs/`, or `chore/`.

See the [Architecture overview](docs/architecture.md) for system design and conventions.

## Prerequisites

- Python 3.11+
- [Poetry 2.0+](https://python-poetry.org/docs/#installation)
- At least one channel bot token: [Telegram](https://core.telegram.org/bots#botfather) or [Discord](https://discord.com/developers/applications)
- At least one model provider API key (Anthropic, OpenAI, or AWS credentials for Bedrock)

## License

[PolyForm Noncommercial 1.0.0](LICENSE)

