Metadata-Version: 2.4
Name: open-pawlet
Version: 0.4.0
Summary: OpenPawlet console with embedded OpenPawlet AI assistant framework
Project-URL: Homepage, https://github.com/JackLuguibin/OpenPawlet
Project-URL: Documentation, https://github.com/JackLuguibin/OpenPawlet/blob/main/README.md
Project-URL: Repository, https://github.com/JackLuguibin/OpenPawlet
Author: open-pawlet contributors
License: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: agent,ai,chatbot
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
Requires-Python: >=3.11
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: anthropic<1.0.0,>=0.45.0
Requires-Dist: chardet<6.0.0,>=3.0.2
Requires-Dist: croniter<7.0.0,>=6.0.0
Requires-Dist: ddgs<10.0.0,>=9.5.5
Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0
Requires-Dist: dulwich<1.0.0,>=0.22.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: filelock>=3.25.2
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: jinja2<4.0.0,>=3.1.0
Requires-Dist: json-repair<1.0.0,>=0.57.0
Requires-Dist: lark-oapi<2.0.0,>=1.5.0
Requires-Dist: loguru<1.0.0,>=0.7.3
Requires-Dist: mcp<2.0.0,>=1.26.0
Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.3
Requires-Dist: openai>=2.8.0
Requires-Dist: openpyxl<4.0.0,>=3.1.0
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.50
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
Requires-Dist: pydantic<3.0.0,>=2.12.0
Requires-Dist: pypdf<6.0.0,>=5.0.0
Requires-Dist: python-docx<2.0.0,>=1.1.0
Requires-Dist: python-pptx<2.0.0,>=1.0.0
Requires-Dist: python-socketio<6.0.0,>=5.16.0
Requires-Dist: python-socks[asyncio]<3.0.0,>=2.8.0; sys_platform != 'win32'
Requires-Dist: python-telegram-bot[socks]<23.0,>=22.6
Requires-Dist: pyyaml<7.0.0,>=6.0
Requires-Dist: qq-botpy<2.0.0,>=1.2.0
Requires-Dist: questionary<3.0.0,>=2.0.0
Requires-Dist: readability-lxml<1.0.0,>=0.8.4
Requires-Dist: rich<15.0.0,>=14.0.0
Requires-Dist: slack-sdk<4.0.0,>=3.39.0
Requires-Dist: slackify-markdown<1.0.0,>=0.2.0
Requires-Dist: socksio<2.0.0,>=1.0.0
Requires-Dist: tiktoken<1.0.0,>=0.12.0
Requires-Dist: typer<1.0.0,>=0.20.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: websocket-client<2.0.0,>=1.9.0
Requires-Dist: websockets<17.0,>=16.0
Provides-Extra: api
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: packaging>=24; extra == 'dev'
Requires-Dist: pymupdf>=1.25.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: discord
Requires-Dist: discord-py<3.0.0,>=2.5.2; extra == 'discord'
Provides-Extra: langsmith
Requires-Dist: langsmith>=0.1.0; extra == 'langsmith'
Provides-Extra: matrix
Requires-Dist: matrix-nio[e2e]>=0.25.2; (sys_platform != 'win32') and extra == 'matrix'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'matrix'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'matrix'
Provides-Extra: msteams
Requires-Dist: cryptography>=41.0; extra == 'msteams'
Requires-Dist: pyjwt<3.0,>=2.0; extra == 'msteams'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.25.0; extra == 'pdf'
Provides-Extra: wecom
Requires-Dist: wecom-aibot-sdk-python>=0.1.5; extra == 'wecom'
Provides-Extra: weixin
Requires-Dist: pycryptodome>=3.20.0; extra == 'weixin'
Requires-Dist: qrcode[pil]>=8.0; extra == 'weixin'
Description-Content-Type: text/markdown

# OpenPawlet

**Languages:** [中文说明](README.zh.md)

## What it is

OpenPawlet (PyPI package name `open-pawlet`) is a **single-process web console** for the **OpenPawlet** ecosystem. It exposes an HTTP API, a browser UI, an OpenAI-compatible `/v1/*` surface and the embedded agent runtime (agent loop, channels, cron, heartbeat) over a single FastAPI port so you can manage bot-related resources locally or in deployment.

**Stack:** FastAPI backend (consistent error envelope and OpenAPI; Swagger/ReDoc/`openapi.json` are served by default at `/docs`, `/redoc`, `/openapi.json` — set each `*_url` to empty to hide) and a Vite frontend under `src/console/web` (HMR in development, production build supported).

## Feature areas

The console roughly covers the areas below (see the UI and OpenAPI for the exact surface):

| Area | Capabilities |
|------|--------------|
| **Bots & agents** | Inspect and manage bots and agents |
| **Chat & channels** | Sessions, chat, channels; debug with gateway WebSocket and realtime events |
| **Config & env** | Console and bot configuration, environment variables, bot file access (e.g. `bot_files`) |
| **Tools & extensions** | Tools, MCP servers, skills, memory |
| **Automation** | Cron jobs |
| **Ops & observability** | Status, health, health audit, usage, alerts, activity; control endpoints where applicable |
| **Workspace** | Workspace browsing and management |
| **Session transcripts** | Optional append-only JSONL logs (OpenPawlet) under workspace `transcripts/` when `agents.defaults.persistSessionTranscript` is true; `transcriptIncludeFullToolResults` controls full tool payloads in the log |

**Typical use:** start `console start`; the embedded OpenPawlet runtime comes up in the same process so you can immediately inspect status, debug sessions, and manage these resources from the console without supervising a separate gateway.

## Screenshots

The **OpenPawlet** web UI (branded “OpenPawlet · AI Assistant” in the console) provides a sidebar for Chat, Control, Agent, and Management areas, plus a top bar for workspace selection, language, theme, and gateway status.

### Dashboard overview

The overview page surfaces key metrics (status, uptime, active sessions, messages, tokens, cost), the **current model**, and charts such as daily token usage and usage by model—useful for at-a-glance monitoring in local or deployed setups.

![OpenPawlet dashboard overview](docs/screenshots/dashboard-overview.png)

### Chat

The chat view supports **multiple sessions** (list with message counts and last activity), streaming-style replies with optional **thinking** / progress indicators, and an input area with token budget hints. Navigation to channels, MCP, memory, workspace, agents, skills, and related tools stays one click away in the sidebar.

![OpenPawlet chat](docs/screenshots/chat.png)

### Channels

**Channels** lists integrations for your bot (for example WebSocket, Weixin, DingTalk, Discord, Email, Feishu, Matrix, MoChat, Microsoft Teams, QQ, Slack, Telegram, WeCom, and WhatsApp). You can enable or edit each channel from the grid; the UI notes that changes are saved to `config.json` and that you should **restart the bot** for them to take effect.

![OpenPawlet channels management](docs/screenshots/channels.png)

## Architecture notes

- **Backend:** FastAPI-based OpenPawlet service with a consistent error envelope and OpenAPI documentation.
- **Frontend:** Vite app under `src/console/web`, with HMR in development and a production build path.

## Tech stack

| Layer | Technology |
|-------|------------|
| Runtime | Python ≥ 3.11 |
| Backend | FastAPI, Uvicorn, Pydantic v2, Loguru |
| OpenPawlet agent framework | Bundled in this repo (`src/openpawlet`); installed as part of `open-pawlet` |
| Frontend | Node.js + npm (see `src/console/web`) |
| Single-process entrypoint | `console start` (unified FastAPI service) |

## Quick start

### 1. Virtual environment and install

A project-local `.venv` is recommended:

```bash
python3.11 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -e ".[dev]"
```

The `openpawlet` Python package ships inside this repository; `pip install -e ".[dev]"` installs the console and agent framework together.

### 2. Frontend dependencies

```bash
cd src/console/web && npm install && cd ../../..
```

### 3. Run

> `console` and `open-pawlet` are the **same command** (both entry points map
> to `console.cli:main`). Use whichever name you prefer; the examples below use
> the shorter `console` alias.
>
> Since 0.3.x **all services are collapsed into a single FastAPI process**:
> REST API, SPA, OpenAI-compatible `/v1/*`, queues admin `/queues/*`,
> WebSocket `/openpawlet-ws/*` and the embedded OpenPawlet runtime (AgentLoop,
> Channels, Cron, Heartbeat) share the same event loop and expose **one HTTP
> port**. The legacy standalone `gateway` / `serve` commands,
> `open-pawlet-queue-manager`, `Procfile` and `honcho` entrypoints have all
> been removed.

#### Single-command production (recommended for local use)

```bash
npm --prefix src/console/web run build
console start   # open http://localhost:8000
```

`console start` runs the unified FastAPI server, mounts the prebuilt SPA
from `src/console/web/dist` (so the UI and `/api/v1/*` share a single origin
and port) and **starts the OpenPawlet runtime in the same event loop** (no
subprocess fork; no ZeroMQ broker). All WebSocket / channel / cron tasks
live inside the FastAPI lifespan. On first launch run `openpawlet onboard` once
if `~/.openpawlet/config.json` is missing. Press Ctrl+C to gracefully stop the
process.

Flags:

- `--no-spa` — skip mounting the prebuilt SPA. Useful for headless API-only
  deployments where the UI is hosted elsewhere.

Re-run `npm run build` (or `console web build`) after frontend changes.

#### Frontend dev mode (hot reload)

Run the unified server and the Vite dev server in two terminals:

```bash
console start         # single process: FastAPI + embedded OpenPawlet, on http://localhost:8000
console web dev       # Vite dev server on http://localhost:3000 (open this for the UI)
```

Open the **Vite URL** (`http://localhost:3000`); Vite proxies `/api/*`,
`/v1/*`, `/queues/*` and `/openpawlet-ws/*` to `:8000`. You no longer need a
separate gateway or queue-manager process.

#### Cross-platform notes

- The single-process layout runs unchanged on **Windows and Linux**; the
  CLI flips to `WindowsSelectorEventLoopPolicy` automatically on Windows.
- Signal handling lives in `console.server.signals`: Linux uses
  `loop.add_signal_handler`, Windows falls back to `signal.signal`.
- `pytest -q` passes on both platforms (only one ExecTool case unrelated to
  this repository is skipped on Windows because `sleep` is not on `PATH`).

#### Configuration

Settings are resolved with the following **priority (highest first)**:

1. Environment variables prefixed with `OPENPAWLET_SERVER_` (e.g.
   `OPENPAWLET_SERVER_PORT=9000`)
2. Optional `.env` file in the working directory
3. `~/.openpawlet/openpawlet_web.json` under the top-level `server` key
4. Built-in defaults (see `console.server.config.schema.ServerSettings`)

The JSON file is **opt-in**: it is no longer written automatically on first
boot. Create a starter file with `console init-config` when you want to
persist non-default values to disk.

## Version history (timeline)


Major releases for the `open-pawlet` PyPI package (matches `[project] version` in the root `pyproject.toml`). The console is built for the **OpenPawlet** stack; the agent framework lives under `src/openpawlet` and ships with each install. **Newest at the top; older entries below.** Add new rows at the **top** when you cut a release.

```text
2026-04-26 ──●── 0.3.0  Unified single-process FastAPI: console + OpenPawlet OpenAI API + queues admin + gateway collapsed into one entrypoint; ZMQ broker / Procfile / honcho removed; in-process MessageBus; cross-platform Win/Linux hardening; new unified-app end-to-end tests
              │
2026-04-20 ──●── 0.2.2  OpenPawlet WebSocket (session lifecycle, delta stream, busy state); tests/docs; UI & dashboard
              │
2026-04-19 ──●── 0.2.1  Aligned versions (pyproject, API schema, web); OpenPawlet framework + console version metadata
              │
2026-04-19 ──●── 0.2.0  Deps & packaging; README; bundled OpenPawlet framework; WhatsApp bridge under bridge/
              │
2026-04-19 ──●── 0.1.0  First release: FastAPI console for the OpenPawlet agent, CLI, workspace, README / Procfile
```

| Date | Version | Summary |
|------|---------|---------|
| 2026-04-26 | **0.3.0** | **Architecture collapse:** all services (REST / SPA / OpenAI-compatible `/v1/*` / queues admin / WebSocket / OpenPawlet runtime) merged into a single FastAPI process; removed legacy standalone `gateway` / `serve`, `open-pawlet-queue-manager`, `Procfile` and the ZeroMQ broker; in-process MessageBus replaces ZMQ; unified Win/Linux event-loop policy and signal handling; introduced `EmbeddedOpenPawlet` runtime and unified-app end-to-end tests. |
| 2026-04-20 | **0.2.2** | **OpenPawlet:** WebSocket session lifecycle, delta streaming, and busy-state handling in gateway and UI; broader framework test coverage and channel docs. Console: dashboard/charts, activity filters, workspace and bot-profile flows, ErrorBoundary, layout and control tweaks; CI and Vitest hardening. |
| 2026-04-19 | **0.2.1** | Single source of truth for version strings (Python package, server API version, frontend `package.json`) so **OpenPawlet** installs report consistent versions end-to-end. |
| 2026-04-19 | **0.2.0** | Dependency and optional extras cleanup, install docs; **OpenPawlet** framework bundled in-repo; `bridge/` (including WhatsApp-related pieces). |
| 2026-04-19 | **0.1.0** | Initial OpenPawlet web **console**: FastAPI backend, `console` CLI, workspace features, docs, and Honcho/Procfile entry points. |

## License

MIT — see [LICENSE](LICENSE) in the repository root.
