pawbot-ai 0.3.0__tar.gz

pawbot_ai-0.3.0/.gitignore

@@ -0,0 +1,73 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.cache/
+*.egg-info/
+node_modules/
+work/
+sessions/
+run/
+.bun/
+.venv/
+venv/
+webui/dist/
+dist/
+build/
+tmp/
+temp/
+playwright-report/
+test-results/
+.idea/
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Runtime state and local Agent artifacts
+llm_usage.sqlite3*
+.pawbot/
+
+# Personal/private configuration and credentials. Keep local; publish only
+# sanitized *.example.* templates.
+.env
+.env.*
+!.env.example
+config.json
+config.local.json
+config.*.local.json
+render-config.json
+*.secret
+*.secrets
+secrets/
+credentials/
+*.pem
+*.key
+*.p12
+*.pfx
+
+# Local databases, logs, dumps, and diagnostic exports
+*.sqlite
+*.sqlite3
+*.sqlite-*
+*.sqlite3-*
+*.db
+*.db-*
+*.log
+*.dump
+*.bak
+*.orig
+*.log
+.coverage
+coverage.xml
+htmlcov/
+
+# Personal interview and analysis materials. Keep these files on the local
+# machine; they are not part of the public source distribution.
+docs/interview/
+interview-prep/
+
+# Local analysis/design workspaces and generated notes.
+graphify-out/
+.spec-workflow/

pawbot_ai-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Xubin Ren and the nanobot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pawbot_ai-0.3.0/PKG-INFO

@@ -0,0 +1,390 @@
+Metadata-Version: 2.5
+Name: pawbot-ai
+Version: 0.3.0
+Summary: A replayable, self-hosted AI agent
+Author: Xubin Ren, the pawbot 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.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: anthropic<1.0.0,>=0.100.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: defusedxml<1.0.0,>=0.7.1
+Requires-Dist: dulwich<1.0.0,>=0.22.0
+Requires-Dist: filelock>=3.25.2
+Requires-Dist: httpx[socks]<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: loguru<1.0.0,>=0.7.3
+Requires-Dist: lxml-html-clean<1.0.0,>=0.4.0
+Requires-Dist: mcp<2.0.0,>=1.26.0
+Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.6
+Requires-Dist: openai>=2.8.0
+Requires-Dist: openpyxl<4.0.0,>=3.1.0
+Requires-Dist: packaging>=24.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: pyyaml<7.0.0,>=6.0
+Requires-Dist: qrcode[pil]>=8.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: setproctitle<2.0.0,>=1.3.7; sys_platform != 'win32'
+Requires-Dist: tiktoken<1.0.0,>=0.12.0
+Requires-Dist: typer<1.0.0,>=0.20.0
+Requires-Dist: tzdata>=2025.2
+Requires-Dist: tzlocal<6.0.0,>=5.3.1
+Requires-Dist: watchfiles<2.0.0,>=1.1.1
+Requires-Dist: websockets<17.0,>=15.0
+Provides-Extra: api
+Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'api'
+Provides-Extra: azure
+Requires-Dist: azure-identity<2.0.0,>=1.19.0; extra == 'azure'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.43.0; extra == 'bedrock'
+Provides-Extra: dev
+Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'dev'
+Requires-Dist: basedpyright<2.0.0,>=1.39.0; extra == 'dev'
+Requires-Dist: msgpack<2.0.0,>=1.1.0; extra == 'dev'
+Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == 'dev'
+Requires-Dist: pymupdf>=1.25.0; extra == 'dev'
+Requires-Dist: pypdf<6.0.0,>=5.0.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-xdist<4.0.0,>=3.8.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
+Requires-Dist: python-docx<2.0.0,>=1.1.0; extra == 'dev'
+Requires-Dist: python-pptx<2.0.0,>=1.0.0; extra == 'dev'
+Requires-Dist: python-socketio<6.0.0,>=5.16.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: documents
+Requires-Dist: defusedxml<1.0.0,>=0.7.1; extra == 'documents'
+Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == 'documents'
+Requires-Dist: pypdf<6.0.0,>=5.0.0; extra == 'documents'
+Requires-Dist: python-docx<2.0.0,>=1.1.0; extra == 'documents'
+Requires-Dist: python-pptx<2.0.0,>=1.0.0; extra == 'documents'
+Provides-Extra: langfuse
+Requires-Dist: langfuse<4.0.0,>=3.0.0; extra == 'langfuse'
+Provides-Extra: olostep
+Requires-Dist: olostep>=0.1.0; (python_version < '3.14') and extra == 'olostep'
+Provides-Extra: pdf
+Requires-Dist: pypdf<6.0.0,>=5.0.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./images/readme-cover-dark.svg" />
+    <img src="./images/readme-cover-light.svg" alt="pawbot" />
+  </picture>
+</p>
+
+# pawbot
+
+### A self-hosted AI agent for your browser, terminal, and chat apps.
+
+Give pawbot a task and it can read and write files, run commands, search the
+web, call MCP tools, remember conversations, and run scheduled work. Use the
+WebUI when you want a visual workspace, the terminal when you want speed, or a
+chat app when you want your agent to be available wherever you are.
+
+The feature that makes pawbot different to develop is **Record & Replay**:
+record one real agent turn, then replay it offline while you change the code —
+without another model request, another token bill, or real tool side effects.
+
+## Start here
+
+| You want to... | Start with... |
+|---|---|
+| Install the released package | [Quick install](#quick-install) |
+| Open the browser workspace | [WebUI](#webui) |
+| Run one request from a terminal | [CLI](#cli) |
+| Connect a chat app | [Channels](#channels-and-integrations) |
+| Understand the replay feature | [Record & Replay](#record--replay) |
+| Change the agent or add a tool | [Development](#development) |
+
+## What can pawbot do?
+
+- Work with files, shell commands, web search, web fetching, documents, images,
+  and other tools.
+- Connect to MCP servers and load extensions without changing the core agent.
+- Keep session history and long-term memory across conversations.
+- Run long tasks and scheduled automations.
+- Use Anthropic, OpenAI-compatible endpoints, local models, fallbacks, and
+  model presets.
+- Reach the same agent from the WebUI, CLI/TUI, API, or supported chat channels.
+- Expose a Python SDK and an OpenAI-compatible API for your own applications.
+
+## Why pawbot?
+
+### One agent, several ways to use it
+
+The WebUI, terminal, API, and chat channels share the same conversations,
+tools, and configuration. Start in the browser and continue from the terminal;
+or keep the agent running behind a gateway and talk to it from a chat app.
+
+### Record an agent once, replay it as often as you need
+
+LLM calls and external tools make agent bugs expensive and difficult to repeat.
+Pawbot records the model responses and tool observations of a turn. Replay then
+runs the current agent code against those recorded inputs:
+
+- no new provider request;
+- no new token cost;
+- no network dependency;
+- no real tool side effects;
+- a structural diff when orchestration changes.
+
+This is useful for debugging, regression tests, and safe refactoring of the
+agent loop.
+
+### Keep your data on your machine
+
+Pawbot is designed for self-hosting. Sessions, configuration, workspaces, and
+recordings stay under your control. Shell commands, file access, network tools,
+and MCP servers are explicit capabilities with documented security boundaries.
+
+## Quick install
+
+### Published package
+
+After the package is published, install and open the WebUI with one command:
+
+macOS / Linux:
+
+```bash
+uv tool install --force --upgrade pawbot-ai && pawbot
+```
+
+Windows PowerShell:
+
+```powershell
+uv tool install --force --upgrade pawbot-ai; pawbot
+```
+
+The repository also includes isolated fallback installers. On a fresh desktop
+install they start the WebUI automatically; use `pawbot agent` when you want the
+terminal/TUI client explicitly:
+
+- [`scripts/install.sh`](scripts/install.sh)
+- [`scripts/install.ps1`](scripts/install.ps1)
+
+For a fresh macOS or Linux desktop, the installer can be run directly from
+GitHub:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/m2dumpling/pawbot/v0.3.0/scripts/install.sh | sh
+```
+
+For native Windows PowerShell:
+
+```powershell
+iex (irm https://raw.githubusercontent.com/m2dumpling/pawbot/v0.3.0/scripts/install.ps1)
+```
+
+The installer selects an active virtual environment, `uv`, `pipx`, or a
+dedicated `~/.pawbot/venv` fallback, then opens the WebUI on a fresh desktop.
+Configure the first Provider and model in **Settings → Models** before sending
+your first task.
+
+### From a source checkout
+
+Requirements: Python 3.11+ and [uv](https://docs.astral.sh/uv/). Bun is only
+needed when developing the WebUI or TUI.
+
+```bash
+uv sync --all-extras --dev
+uv run pawbot --help
+```
+
+Install optional channel dependencies when needed:
+
+```bash
+uv run --no-sync python -m scripts.install_channel_dependencies --all-channels
+```
+
+## Quick start
+
+### WebUI
+
+The browser workspace is the easiest first run:
+
+```bash
+uv run pawbot webui
+```
+
+Configure your first provider and model in **Settings → Models**, start a new
+conversation, and send `Hello!`. The first-run WebUI binds to localhost by
+default.
+
+### CLI
+
+Run `pawbot` without a subcommand to open the WebUI. Use `pawbot agent` when
+you explicitly want the terminal/TUI client.
+
+Run one request and exit:
+
+```bash
+uv run pawbot agent --message "Explain the top-level modules in this repository"
+```
+
+Start the gateway directly when you want a long-running process:
+
+```bash
+uv run pawbot gateway
+```
+
+Keep the gateway in the background:
+
+```bash
+uv run pawbot gateway --background
+uv run pawbot gateway status
+uv run pawbot gateway logs
+```
+
+## Record & Replay
+
+Record a real turn:
+
+```bash
+uv run pawbot agent \
+  --message "Inspect the repository and summarize the agent loop" \
+  --record .pawbot/blackbox/demo
+```
+
+Replay it offline:
+
+```bash
+uv run pawbot agent --replay .pawbot/blackbox/demo
+```
+
+In the WebUI, **Settings → Record & Replay** provides the same workflow:
+click **Start recording**, run tasks across as many chat sessions as needed,
+then click **Stop recording**. The recording window belongs to the agent, so
+all turns before Stop are stored in one sample. Incomplete samples stay visible
+with a reason and can be deleted from the UI instead of failing later on replay.
+
+Pause after an iteration and inspect the reconstructed messages:
+
+```bash
+uv run pawbot agent \
+  --replay .pawbot/blackbox/demo \
+  --break-at 2
+```
+
+The recording contains the provider-response rail, the tool-observation rail,
+and the turn envelope. Replay checks tool ordering, result insertion, context
+governance, continuation, and the final message structure. See
+[docs/record-replay.md](docs/record-replay.md) for the format and privacy
+boundary.
+
+When choosing a model in **Settings → Models**, pawbot also reads capability
+metadata from the provider's `/models` response when available, then applies
+curated metadata for known model IDs. Context length and supported reasoning
+levels are shown before saving; if an API does not advertise them, the UI says
+so and keeps the value manually editable. See the curated
+[model capability registry](docs/model-capabilities.md) for the fallback table
+and context-window migration rules.
+
+## Channels and integrations
+
+Pawbot can be used from its WebUI, terminal, OpenAI-compatible API, Python SDK,
+WebSocket channel, and supported chat channels. MCP servers and extension
+points let you add capabilities without hard-coding them into the agent loop.
+
+## Architecture
+
+```text
+User message
+    ↓
+Channel / WebUI / CLI / API
+    ↓
+AgentLoop: prepare the conversation and run one turn
+    ↓
+AgentRunner: ask the model, call tools, add results, repeat when needed
+    ↓
+Provider + ToolRegistry + MCP
+    ↓
+Answer, saved session, and channel response
+```
+
+The core source is organized around:
+
+- `pawbot/agent/loop.py` — turn orchestration;
+- `pawbot/agent/runner.py` — the model/tool loop;
+- `pawbot/agent/turn/` — turn state and stages;
+- `pawbot/agent/blackbox/` — Record & Replay;
+- `pawbot/agent/tools/` — tool contracts and execution;
+- `pawbot/session/` — conversations, memory, and recovery;
+- `pawbot/providers/` — model adapters and retries.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Record & Replay](docs/record-replay.md)
+- [Release notes](docs/release-notes/0.3.0.md)
+- [Publishing guide](docs/publishing.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Security and privacy
+
+Pawbot can run shell commands, access local files, call network tools, and
+connect to MCP servers. Read [`SECURITY.md`](SECURITY.md) before enabling them.
+
+Never commit:
+
+- `config.json`, `.env*`, provider credentials, or certificates;
+- `.pawbot/` recordings and session data;
+- `work/`, `sessions/`, `run/`, SQLite files, or private logs;
+- prompts, tool results, or local paths containing personal information.
+
+Replay artifacts can contain sensitive prompts and tool output. Sanitize them
+before sharing; use `tests/fixtures/blackbox/` for repository-safe examples.
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run --no-sync python -m scripts.install_channel_dependencies --all-channels
+uv run ruff check pawbot
+uv run basedpyright
+uv run pytest -q
+```
+
+For WebUI changes:
+
+```bash
+cd webui
+bun install --frozen-lockfile
+bun run test
+bun run build
+```
+
+## Project status
+
+Pawbot is an Alpha/Experimental Preview project. It is ready for personal
+self-hosting, development, testing, and small single-node deployments. It does
+not currently promise multi-instance session consistency, durable distributed
+execution, automatic failover, or enterprise high availability.
+
+## License
+
+MIT — see [LICENSE](LICENSE) and
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).