Metadata-Version: 2.4
Name: openpaw-ai
Version: 0.4.0
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: email
Provides-Extra: memory
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)
Requires-Dist: easyocr (>=1.7.2,<2.0.0)
Requires-Dist: elevenlabs (>=1.0.0) ; extra == "all-builtins"
Requires-Dist: elevenlabs (>=1.0.0) ; extra == "voice"
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: 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.0.0,<2.0.0)
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)
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: 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="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://github.com/johnsosoka/OpenPaw/actions/workflows/ai-code-review.yml/badge.svg" alt="AI Code Review">
    <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>

---

> **Pre-1.0 Release (0.4.0)** — OpenPaw is actively developed. The API may evolve as we work towards a stable 1.0.0 release. Contributions and feedback are welcome.

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, 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

**First Class Document processing** -- Docling OCR/ICR turns scanned PDFs, DOCX, and PPTX into markdown automatically. Whisper transcribes voice messages on arrival.

**Drop-in custom tools** -- Write a `@tool` function, put it in `agent/tools/`, restart. Your agent picks it up with zero wiring.

**Multi-agent spawning** -- Agents spin up background workers for parallel tasks with full lifecycle tracking and result collection.

**Dynamic tool assignment** -- Spawned sub-agents can be given a tailored tool loadout via allow/deny lists, so each worker gets only the capabilities it needs.

**Cron scheduling and heartbeats** -- Recurring jobs, one-shot timers, proactive check-ins. Agents can even self-schedule follow-ups at runtime.

**Browser automation** -- Playwright-driven web interaction via accessibility tree. Agents reference page elements by number, not CSS selectors.

**Email integration** -- Send and receive email via Gmail with safe-by-default recipient policies. Read inbox, search, reply with threading, and manage attachments.

**Deep research** -- Integrate with a self-hosted GPT-Researcher instance for multi-source research reports with citations. Agents submit queries via WebSocket and receive comprehensive markdown reports.

**Approval gates** -- Human-in-the-loop authorization for dangerous operations, with configurable timeouts and channel-native UI.

**Multi-channel support** -- Connect agents to Telegram, Discord, or both simultaneously. Trigger-based activation lets agents respond to @mentions, keyword triggers, or both in group chats. On-demand context fetch gives agents awareness of recent channel history when triggered.

**Session management** -- Conversations auto-reset after inactivity (default 3 hours). Auto-compact rotates context when the window fills. Persistent channel logs give agents searchable message history.

**Workspace isolation** -- Each agent gets its own SOUL.md personality, tools directory, conversation history, channels, and sandboxed filesystem.

**Multi-provider LLM support** -- Anthropic, OpenAI, AWS Bedrock, xAI, and any OpenAI-compatible endpoint. Switch models at runtime with `/model`.

**Memory and observability** -- Vector search for semantic recall, conversation archiving to markdown and JSON, and session logs for every cron, heartbeat, and sub-agent run. Full visibility into what your agents are doing and thinking.

## Quick Start

### 1. Install

```bash
pip install openpaw-ai
```

For development from source:

```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
```

### 3. Configure

```bash
cp config.example.yaml config.yaml
```

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 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 and extensions
│   ├── AGENT.md        # Capabilities and behavior guidelines
│   ├── USER.md         # User context and preferences
│   ├── SOUL.md         # Core personality and values
│   ├── HEARTBEAT.md    # Session state scratchpad (agent-writable)
│   ├── skills/         # Skill directories (SKILL.md format)
│   ├── team/           # Spawn profiles (sub-agent personas)
│   └── tools/          # Custom LangChain @tool functions
├── config/             # Configuration (write-protected)
│   ├── agent.yaml      # Per-workspace settings (model, channel, queue)
│   ├── .env            # API keys and secrets
│   └── crons/          # Scheduled task definitions
├── .openpaw/           # Framework internals (write-protected)
│   ├── conversations.db  # AsyncSqliteSaver checkpoint database
│   ├── sessions.json     # Session/conversation thread state
│   ├── token_usage.jsonl # Token usage metrics (append-only)
│   └── subagents.yaml    # Sub-agent requests and results
├── memory/             # Archived conversations and session logs
│   ├── conversations/  # Conversation exports (markdown + JSON)
│   └── logs/           # Session logs and channel history
│       ├── channel/    # Persistent channel message logs (JSONL)
│       └── sessions/   # Heartbeat, cron, and sub-agent session logs
└── workspace/          # Agent work area (default write target)
    ├── downloads/      # Browser-downloaded files
    └── screenshots/    # Browser 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
- [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 [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.

## AI Code Review

All pull requests are automatically reviewed by GPT-4o via [ai-code-review](https://github.com/AleksandrFurmenkovOfficial/ai-code-review). The AI checks for code quality, security issues, performance concerns, and maintainability.

Reviews run on every PR open and update. Results are posted as inline comments on the pull request.

## 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)

