polyrob 1.0.3__tar.gz → 1.2.0__tar.gz

polyrob-1.2.0/MANIFEST.in

@@ -0,0 +1,25 @@
+graft data/prompts
+graft data/characters
+graft webview/static
+graft webview/templates
+prune webview/templates/__pycache__
+# The invoice card fonts. modules/cards/cards.py reads assets/fonts/dejavu/*.ttf
+# by path at runtime; without this the sdist omits them and card rendering
+# degrades to PIL's default font. The wheel already carried them via
+# package-data; the sdist did not.
+graft assets
+recursive-include agents/personality/characters *.json
+include config/*.template
+# 058: the lock ships in the SDIST so a source install can pin its lazy
+# installs (core/lazy_deps.py) exactly as the deploy does; a wheel has none.
+include requirements.lock
+include README.md LICENSE
+# 030 WS-F6 (E7): ship the user guide + flag SSOT in the SDIST so a pip
+# source install has the documentation its docstrings reference. (Wheels are
+# unchanged: no runtime code path reads docs/ — the agent-facing copy ships in
+# data/prompts/skills/polyrob-user-guide/.)
+graft docs/guide
+include docs/CONFIGURATION.md
+# 042: the audited token template's source, beside its compiled bytes.
+include core/wallet/contracts/*.sol
+global-exclude *.pyc *.pyo

polyrob-1.2.0/PKG-INFO

@@ -0,0 +1,606 @@
+Metadata-Version: 2.4
+Name: polyrob
+Version: 1.2.0
+Summary: POLYROB — autonomous AI agent framework
+Author: The POLYROB Authors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/theselfruleorg/polyrob
+Project-URL: Repository, https://github.com/theselfruleorg/polyrob
+Project-URL: Issues, https://github.com/theselfruleorg/polyrob/issues
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: openai>=1.26.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: aiohttp>=3.14.3
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: requests>=2.30.0
+Requires-Dist: certifi>=2024.0.0
+Requires-Dist: cryptography>=50.0.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt_toolkit>=3.0.43
+Requires-Dist: click>=8.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: markdown>=3.5.0
+Requires-Dist: markdownify>=0.11.0
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: httplib2>=0.32.0
+Requires-Dist: pyasn1>=0.6.4
+Requires-Dist: pyyaml>=6
+Requires-Dist: packaging>=23.2
+Requires-Dist: h2>=4.4.1
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.8.0; extra == "gemini"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
+Provides-Extra: server
+Requires-Dist: fastapi==0.141.1; extra == "server"
+Requires-Dist: starlette==1.6.0; extra == "server"
+Requires-Dist: uvicorn[standard]==0.38.0; extra == "server"
+Requires-Dist: Jinja2==3.1.6; extra == "server"
+Requires-Dist: python-socketio>=5.11.0; extra == "server"
+Requires-Dist: python-multipart>=0.0.6; extra == "server"
+Requires-Dist: watchfiles>=1.0.0; extra == "server"
+Requires-Dist: argon2-cffi>=23.1.0; extra == "server"
+Requires-Dist: python-magic>=0.4.27; extra == "server"
+Provides-Extra: docs
+Requires-Dist: pypdf>=6.16.1; extra == "docs"
+Requires-Dist: python-docx>=0.8.0; extra == "docs"
+Provides-Extra: anysite
+Requires-Dist: anysite-cli>=0.3; extra == "anysite"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40.0; extra == "browser"
+Requires-Dist: psutil>=5.9.0; extra == "browser"
+Provides-Extra: memory-vector
+Requires-Dist: sentence-transformers>=3.0.0; extra == "memory-vector"
+Requires-Dist: apsw>=3.46; extra == "memory-vector"
+Requires-Dist: sqlite-vec>=0.1.6; extra == "memory-vector"
+Requires-Dist: numpy>=1.24.0; extra == "memory-vector"
+Provides-Extra: media
+Requires-Dist: numpy>=1.24.0; extra == "media"
+Requires-Dist: imageio>=2.37.0; extra == "media"
+Requires-Dist: qrcode>=7.4; extra == "media"
+Provides-Extra: crypto
+Requires-Dist: web3>=6.0.0; extra == "crypto"
+Requires-Dist: eth-account>=0.10.0; extra == "crypto"
+Requires-Dist: x402>=2.13.0; extra == "crypto"
+Requires-Dist: fastapi-x402>=0.1.8; extra == "crypto"
+Requires-Dist: hyperliquid-python-sdk>=0.21.0; extra == "crypto"
+Requires-Dist: py-clob-client-v2>=0.1.0; extra == "crypto"
+Provides-Extra: solana
+Requires-Dist: solders>=0.21; extra == "solana"
+Requires-Dist: x402[svm]>=2.16.0; extra == "solana"
+Requires-Dist: solana<0.40,>=0.36; extra == "solana"
+Requires-Dist: httpx2>=2.12.0; extra == "solana"
+Requires-Dist: httpcore2>=2.10.0; extra == "solana"
+Provides-Extra: telegram
+Requires-Dist: aiogram>=3.17.0; extra == "telegram"
+Provides-Extra: twitter
+Requires-Dist: tweepy>=4.14.0; extra == "twitter"
+Requires-Dist: chatxdk>=0.5.0; extra == "twitter"
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.0.0; extra == "voice"
+Provides-Extra: feishu
+Requires-Dist: lark-oapi<2,>=1.4; extra == "feishu"
+Provides-Extra: hf
+Requires-Dist: huggingface_hub>=0.20.0; extra == "hf"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: all
+Requires-Dist: polyrob[anthropic,anysite,browser,crypto,docs,feishu,gemini,hf,media,memory-vector,server,solana,telegram,twitter,voice]; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/polyrob-logo.png" alt="POLYROB" width="440">
+
+### A self-hosted autonomous AI agent that pursues goals, learns from experience, and runs entirely on your own machine.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/polyrob.svg)](https://pypi.org/project/polyrob/)
+[![CI](https://github.com/theselfruleorg/polyrob/actions/workflows/ci.yml/badge.svg)](https://github.com/theselfruleorg/polyrob/actions)
+[![Stars](https://img.shields.io/github/stars/theselfruleorg/polyrob?style=social)](https://github.com/theselfruleorg/polyrob)
+
+**[Quick Start](#quick-start) · [Docs](#documentation) · [Examples](docs/examples.md) · [Comparison](docs/comparison.md)**
+
+</div>
+
+POLYROB is a self-hosted autonomous AI agent that runs on your own machine. You give it a goal in
+plain language and it does the rest — planning the work into steps, browsing the web, reading and
+writing files, running code and shell commands, calling external tools and APIs, and recovering
+from its own errors until the goal is done. It works with every major LLM provider (OpenAI, Anthropic, Google, DeepSeek,
+OpenRouter, NVIDIA NIM, twenty more flat-rate and regional rows, six OAuth subscription plans,
+and any endpoint you declare) and fails over between them automatically,
+remembers what it learns across sessions, and reaches you wherever you are — your terminal, the web
+console, a REST API, or chat surfaces like Telegram and email. Switch it into personal-agent mode
+and it becomes durably autonomous: it keeps a backlog of goals that survives restarts, writes and
+curates its own skills from experience, wakes itself to follow up on unfinished work, and refines
+an evolving model of how you work.
+
+> **Self-hosted, not a SaaS.** POLYROB runs on your own machine or server. There is no hosted
+> version — your keys, your data, your control. The core install is ~50 MB with zero cloud
+> dependencies; everything beyond LLM calls stays on your box unless you opt in.
+
+---
+
+## 🎯 Give it a goal and walk away
+
+POLYROB doesn't just answer — it *works*, and it keeps working when you're not watching.
+
+- **Durable goal board** — a cross-session backlog in SQLite with atomic claims and a circuit breaker that survives process restarts, so long-running or unattended work isn't lost to a reboot.
+- **Cron in natural language** — the agent schedules its own recurring runs (`"every monday 09:00"`, `"30m"`, cron syntax), and can deliver results out-of-band to Telegram, email, or X.
+- **Self-wake** — re-enters idle sessions to continue or follow up, with depth and backoff guards so it never loops.
+- **Background review + curator** — a cheap aux model reviews what worked every few turns and can distill a new skill; unused skills are retired automatically and revived when relevant again.
+- **Parallel delegation** — `delegate_task` spawns least-privilege sub-agents for concurrent workstreams (no money/comms/code-exec, can't re-delegate), sync or detached in the background.
+
+## 🧬 It learns and gets better with use
+
+Run POLYROB as your personal agent (`POLYROB_LOCAL=true`) and it turns experience into durable
+capability instead of forgetting it when the task ends.
+
+- **Reflective, hierarchical memory** — findings are organized into phases, consolidated by an LLM, and forgotten by *importance* (`recency + relevance + frequency`), not just age.
+- **Cross-session recall** — SQLite FTS5 keyword search out of the box (zero extra deps), or optional hybrid keyword+vector recall (`sqlite-vec`, the `[memory-vector]` extra) that transparently degrades to keyword search if the extra is absent or the extension can't load — the agent keeps working either way.
+- **Episodic activity log** — a durable "what happened last time" ledger bridges each new session so it never starts cold.
+- **Writes its own skills** — authored through a scanned, quarantined pipeline; every self-modification is reviewed before it takes effect, so a background turn can never silently rewrite a skill or the agent's identity.
+- **Evolving identity** — a per-user self-doc the agent updates (owner-gated) as it learns how you work.
+- **Named profiles** — run several isolated bots on one machine (`polyrob -P scout`), each with its own persona, memory, keys and daemons; export a profile or install one from a git repo. See [docs/guide/profiles.md](docs/guide/profiles.md).
+
+Skills use the open [agentskills.io](https://agentskills.io) `SKILL.md` format — the same format as
+Claude Code, discovered straight from `~/.agents/skills/` (and `~/.claude/skills/`). Install from a local folder, a GitHub repo, or
+a `SKILL.md` URL: `polyrob skill install <spec>` threat-scans, quarantines, and waits for your
+explicit approval. See **[docs/guide/skills.md](docs/guide/skills.md)**.
+
+## 🛠️ A real toolbox
+
+- **Web, two ways** — a lightweight `web_fetch` returns any URL as clean markdown with **no browser install needed**, or full **Playwright** automation (navigate/click/type/screenshot/DOM extract, anti-detection) when you need it.
+- **MCP client** — connect any Model Context Protocol server over **STDIO, SSE, HTTP, or Streamable HTTP**, with auto tool-discovery, per-server circuit breakers, encrypted secrets, and live resource subscriptions.
+- **Structured web data** — the AnySite tool pulls structured data from **200+ sites and platforms**; Perplexity-backed search; Twitter/X and Gmail tools.
+- **Code & files** — file/CSV/JSON handling, built-in coding tools (`str_replace` / `apply_patch` / `run_tests` / grep), git & GitHub tools, and opt-in sandboxed code execution.
+- **Vision** — reasons over screenshots and images.
+
+## 🔌 Use it from anywhere
+
+One agent core, many front doors:
+
+- **Terminal** — run `polyrob` to talk to the agent: live tool transcripts, secret-scrubbed output, resumable sessions, and nearly sixty slash commands (`/inbox`, `/goals`, `/model`, `/memory`, `/pause`, `/autonomy`, `/config`; the full list is in [docs/guide/cli.md](docs/guide/cli.md)).
+- **Web console** — five clear destinations for Chat, Inbox, Work, Money, and Rob (the agent itself). Watch live work, resolve approvals, manage standing jobs and apps, reconcile the agent's ledger, and change its capabilities from one owner surface.
+- **REST API + SSE streaming**, plus a drop-in **OpenAI-compatible `/v1`** endpoint — point any OpenAI SDK at `localhost:9000/v1`.
+- **A2A protocol** — Google's Agent-to-Agent standard (Agent Card discovery, JSON-RPC, SSE) so other agents can discover and delegate to yours.
+- **MCP server** — expose polyrob to Claude Desktop, Cursor, or any MCP client as a read-only tool provider (`POST /mcp`, off by default) — it's an MCP client *and* server.
+- **Chat surfaces** — Telegram (live incremental streaming + voice-note transcription), email (IMAP/SMTP), WhatsApp, Discord, Slack, Signal, Feishu / Lark, DingTalk, and X (Twitter) DMs.
+
+## 🖥️ One console for the whole agent
+
+The POLYROB Console keeps conversation, unattended work, owner decisions, money, and agent policy in
+one place. It uses the same goal board, approval queue, wallet ledger, and configuration primitives as
+the CLI and API, so a decision made in one surface is visible in the others.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/chat-running.png" alt="POLYROB Console showing a completed autonomous app build and deployment waiting for owner approval" width="100%">
+</p>
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/inbox-decisions.png" alt="POLYROB Inbox showing owner decisions and non-blocking follow-ups" width="100%"><br>
+      <strong>Inbox</strong> — see only what needs you, with the reason, consequence, and available decision in plain language.
+    </td>
+    <td width="50%" valign="top">
+      <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/work-autonomy.png" alt="POLYROB Work view showing running and queued autonomous work" width="100%"><br>
+      <strong>Work</strong> — follow what is running now, what comes next, scheduled jobs, and delegated helpers.
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/money-book.png" alt="POLYROB Money view reconciling its ledger with on-chain positions" width="100%"><br>
+      <strong>Money</strong> — reconcile the agent's book with its chains, inspect cash and invoices, and keep spend limits visible.
+    </td>
+    <td width="50%" valign="top">
+      <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/agent-control.png" alt="POLYROB Agent view showing autonomy controls, capabilities, and health" width="100%"><br>
+      <strong>Rob</strong> — inspect identity, memory, capabilities, health, and the rules that bound autonomous action.
+    </td>
+  </tr>
+  <tr>
+    <td colspan="2" valign="top">
+      <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/apps.png" alt="POLYROB Work Apps view showing running, staged, and published applications" width="100%"><br>
+      <strong>Apps</strong> — inside Work, review what the agent built, approve a first deployment, read logs, or take an app down.
+    </td>
+  </tr>
+</table>
+
+Run it with <code>polyrob dashboard</code> and open <code>http://localhost:5050</code>. See the
+<strong><a href="docs/guide/console.md">console guide</a></strong> for deployment postures, owner login,
+read-only mode, and the actions each screen exposes.
+
+## 🧠 Multi-provider intelligence
+
+- **One agent, every provider** — six built-ins plus flat-rate rows, OAuth subscription plans and your own endpoint, behind a native LLM layer with **no third-party agent framework**. The live list and how to pick one: [docs/guide/configuration.md §3](docs/guide/configuration.md#4-providers-and-models).
+- **Bring your own endpoint** — declare any OpenAI- or Anthropic-compatible provider in `~/.polyrob/providers.yaml` with **zero code**: a local Ollama/vLLM/LM Studio, Groq/Together/Fireworks, a z.ai GLM Coding Plan, or a corporate gateway. Declared models list and route like built-ins; hostile rows (secret-exfil `env_key`s, metadata endpoints) are refused at load.
+- **Automatic failover** — a rate-limited or failing provider silently retries on a fallback.
+- **Live model switching** — `/model <provider> <model>` mid-session, or per-request override on the `/v1` surface.
+- **Cross-provider prompt caching, on by default** — the prompt is assembled as a stable *prefix*: tool schemas sorted by name, the autonomous tool set held still, the rendered foundation replayed byte-for-byte after a restart. Providers serve the leading bytes from cache instead of re-billing them. Anthropic gets a 5-minute or 1-hour cache window chosen from the session class; OpenRouter, Gemini, OpenAI and DeepSeek each get the treatment their API supports. Cached **and written** tokens are priced, recorded and shown — live as `cache N%` in the status bar, after the fact in `polyrob doctor`.
+- **Optional extended thinking** — per-provider reasoning budgets (Anthropic thinking blocks, DeepSeek CoT, OpenAI reasoning effort), plus a scrubber that keeps leaked reasoning prose out of your history and output.
+
+---
+
+## Quick Start
+
+POLYROB targets **Python 3.11+**. One line, on Linux, macOS or WSL2:
+
+```bash
+curl -fsSL https://polyrob.dev/install.sh | bash
+```
+
+It finds Python, clones the source into `~/.polyrob/src`, builds a virtualenv, puts a `polyrob`
+command on your `PATH`, and runs the setup wizard — the wizard reads `/dev/tty`, so it asks you for
+your provider key right inside the pipe. Prefer to read a script before running it (you should):
+
+```bash
+curl -fsSL https://polyrob.dev/install.sh -o install.sh && less install.sh && bash install.sh
+```
+
+Flags: `--extras server,browser` · `--browser` / `--no-browser` · `--no-setup` · `--no-prompt`
+(fully scripted) · `--branch` / `--commit` (pin a version) · `--uninstall`.
+
+<details>
+<summary>Already a Python user? Install from PyPI instead</summary>
+
+```bash
+# 1. Install (with all optional features)
+pipx install "polyrob[all]"
+
+# 2. Browser engine (optional — only needed for web automation).
+#    pipx isolates the venv, so run playwright FROM polyrob's venv:
+"$(pipx environment --value PIPX_LOCAL_VENVS)/polyrob/bin/playwright" install chromium
+
+# 3. Configure (keys, model, persona, owner, autonomy, chat surface)
+polyrob setup
+
+# 4. Sanity-check your setup
+polyrob doctor
+
+# 5. Start it
+polyrob
+```
+
+> Plain `pip install polyrob` into your own venv? Then step 2 is just
+> `python -m playwright install chromium` in that venv — and the core agent
+> runs fine without the browser at all.
+
+</details>
+
+Keep it running after you close the terminal with `polyrob service install` (a systemd user unit or
+a launchd agent). Update with `polyrob update --apply`; remove it with `polyrob uninstall`.
+
+Run `polyrob` and you're talking to the agent. Give it a task in plain language and it plans, works,
+and reports back; ask a follow-up and it keeps going. `polyrob doctor` is a real preflight — it
+reports which provider keys resolve, the exact model it will pick, your active memory backend, and
+workspace isolation.
+
+**Turn on autonomy** to unlock the self-evolving and goal-seeking loops (skills, curator,
+goal board, self-wake, episodic memory):
+
+```bash
+polyrob autonomy on --global     # writes AUTONOMY_ENABLED=true to ~/.polyrob/.env; `polyrob init` also asks
+```
+
+The four axes, what each one moves and how to stop it again:
+[docs/guide/configuration.md §5](docs/guide/configuration.md#6-the-autonomy-dial).
+
+<details>
+<summary>Optional: web console & REST API</summary>
+
+```bash
+polyrob dashboard   # web console         → http://localhost:5050
+polyrob serve       # local REST API      → http://localhost:9000
+polyrob gateway     # run all enabled chat surfaces (Telegram/email/…) in one process
+```
+</details>
+
+For a full walkthrough see **[docs/guide/getting-started.md](docs/guide/getting-started.md)**.
+Want to contribute? See **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+---
+
+## A taste of what it can do
+
+```
+"Research competitors in the AI automation space and write a report
+ with pricing, features, and positioning."
+
+"Monitor this webpage daily and alert me when the price drops below $500."
+
+"Log into my dashboard, export the monthly report, and email it to my team."
+
+"Scrape these 50 product pages, extract pricing, and build a CSV."
+```
+
+More real-world examples → **[docs/examples.md](docs/examples.md)**
+
+---
+
+## The terminal, done right
+
+Run `polyrob` and you're in the agent. From inside the session, slash commands give you full control:
+
+| In-session command | What it does |
+|---|---|
+| `/compact` | Ages old tool results to a one-line pointer first, then LLM-compresses what is left (e.g. 8,432 → 3,210 tokens) mid-session |
+| `/context` | What is in the window right now: per-slot tokens, one-shot ephemerals, and the provider's own last-request prompt / cached / written split |
+| `/usage` | Authoritative token + cost accounting from the local DB |
+| `/model <provider> <model>` | Hot-swap the model without losing the conversation |
+| `/memory search <q>` | Search cross-session memory inline |
+| `/self` | View the agent's SOUL (identity) and evolving SELF doc |
+| `/replay` | Visually replay a past session |
+| `/autonomy` | Inspect goals, cron, and the autonomy loops |
+
+Twelve named toolsets (`minimal`, `safe`, `research`, `coding`, `development`, `browser`, `social`,
+`full` and more) let you scope exactly what the agent can touch. Management subcommands round it
+out — `polyrob doctor` (preflight), `polyrob kb add/search` (local knowledge base), `polyrob auth`
+(provider sign-in), `polyrob keys` (API access), `polyrob profile` (several bots on one machine),
+and `polyrob update` (self-update with snapshot, guarded migration, verify and **auto-rollback**;
+`--apply` for git installs, a hint for pipx).
+
+---
+
+## Full capabilities
+
+**Core automation**
+
+| Capability | Detail |
+|---|---|
+| Web reading | `web_fetch` URL→markdown, no browser needed |
+| Browser automation | Playwright with anti-detection, vision over screenshots |
+| Files & data | text / JSON / CSV / markdown read + write |
+| Code | built-in coding tools + git/GitHub + opt-in sandboxed execution |
+| Planning | multi-step decomposition with automatic error recovery |
+
+**Intelligence & memory**
+
+| Capability | Detail |
+|---|---|
+| Cross-session recall | SQLite FTS5 (default) or hybrid vector (`sqlite-vec`, `[memory-vector]`), tenant-scoped |
+| Reflective memory | phase-organized, LLM-consolidated, importance-based forgetting |
+| Adaptive context | A 70 / 85 / 95 % ladder — a log line, then a deterministic pass that demotes old tool results, then LLM-synthesis compaction, then a non-LLM emergency prune. Eight-step cooldown with a ≥5 % progress rule and an anti-thrash counter |
+| Prompt caching | On by default per provider, over a prompt prefix guarded by a CI ratchet; Anthropic cache windows chosen by session class; cached *and written* tokens priced and recorded |
+| Extended thinking | optional per-provider reasoning budgets + reasoning-prose scrubber |
+
+**Autonomy** *(personal-agent mode)*
+
+| Capability | Detail |
+|---|---|
+| Durable goal board | SQLite, atomic claims, circuit breaker, daily quota — survives restarts |
+| Cron | natural-language schedules + out-of-band delivery (Telegram/email/X) |
+| Self-wake | re-enters idle sessions with depth/backoff guards |
+| Self-authored skills | background review → scan → quarantine → owner approval |
+| Skill curator | retires unused skills, revives on reuse |
+| Delegation | least-privilege sub-agents, sync or detached background |
+
+**Interfaces & interop**
+
+| Capability | Detail |
+|---|---|
+| Terminal | `polyrob` opens the agent — live tool transcripts, ~60 slash commands, resumable sessions |
+| Web console | Chat, Inbox, Work, Money, and Rob over a real-time Socket.IO surface |
+| REST API | session lifecycle + mid-run guidance injection + SSE streaming |
+| OpenAI-compatible | drop-in `/v1/chat/completions` + `/v1/models` |
+| A2A protocol | Agent Card discovery, JSON-RPC, SSE — agent-to-agent delegation |
+| MCP client | STDIO / SSE / HTTP / Streamable HTTP, live resource subscriptions |
+| MCP server | expose polyrob's read-only tools to Claude Desktop / Cursor (`POST /mcp`, off by default) |
+| Chat surfaces | Telegram, email, WhatsApp, Discord, Slack, Signal, X DMs — one agent core, many channels |
+
+---
+
+## Integrations
+
+Multi-provider LLM (**OpenAI · Anthropic · Google Gemini · DeepSeek · OpenRouter · NVIDIA NIM**) ·
+**Playwright** browser · **MCP** (STDIO/SSE/HTTP/Streamable) · **AnySite** (200+ sites) ·
+**Perplexity** search · **Twitter/X** · **Gmail / IMAP-SMTP** · **Telegram** · **WhatsApp** ·
+**Discord** · **Slack** · **Signal** ·
+voice transcription (**faster-whisper**) · **A2A** · OpenAI-compatible `/v1` · **agentskills.io**
+skills · **sqlite-vec** + **sentence-transformers** local RAG (the `[memory-vector]` extra).
+
+---
+
+## Safe autonomy by design
+
+An autonomous agent that touches the web, your files, and other people needs guardrails. POLYROB
+marks external content as untrusted data and layers capability, authority, approval, and containment
+checks around it. The core protections below are **on by default**:
+
+| Layer | Protection | Default |
+|-------|------------|---------|
+| **Untrusted-input wrapping** | Web pages, emails, and tool results framed as data, not instructions | **On** |
+| **Least-privilege delegation** | Sub-agents get narrowed toolsets (no money/comms/code-exec), no re-delegation | **On** |
+| **Schema sanitization** | Hostile tool-schema constructs fixed before they reach a provider | **On** |
+| **SSRF confinement** | `web_fetch` re-validates every redirect hop; blocks loopback/metadata/private targets | **On** |
+| **Self-modification review** | New skills / identity edits are quarantined and reviewed before taking effect | **On** |
+| **Code-exec containment** | Hardened Docker container by default on a server; the local subprocess backend is a convenience, not a sandbox, and a server refuses it; no inherited API keys | On when code-exec enabled |
+| **Run budget** | Cap a session's provider spend; the run halts honestly at the ceiling rather than claiming success | Opt-in (`RUN_BUDGET_USD`) |
+| **Four-tier access** | OWNER / CORRESPONDENT / GROUP MEMBER / DENIED routing for chat surfaces | Opt-in (`CORRESPONDENT_ACCESS_ENABLED`; on under `AUTONOMY_MODE=autonomous`) |
+| **Group chats (rooms)** | Allowlisted room + per-chat role; every room turn runs a read-only, audience-bounded toolset (never money/exec/delegation) in a session that carries no owner state | Opt-in (`GROUP_CHAT_ENABLED`; on under `AUTONOMY_MODE=autonomous`) |
+| **Memory threat-scan** | Rejects injected jailbreak/persona-rewrite patterns on write | Opt-in (`MEMORY_THREAT_SCAN`) |
+
+When you expose the agent to other people, the **access model** keeps a stranger's message as
+*data*: **OWNER** steers the agent · **CORRESPONDENT** (a third party the agent contacted) can only
+return data, never command · **GROUP MEMBER** is answered in an allowed room from a read-only toolset ·
+**DENIED** is blocked. A correspondent-tainted session has high-impact
+tools (money, comms, code-exec) gated off until a genuine owner turn.
+
+> **Chat surfaces are off by default for a reason.** When you enable them, treat inbound DMs as
+> untrusted input — use pairing/approval. A public group chat is a documented, supported feature
+> ([docs/guide/groups.md](docs/guide/groups.md)) with its own allowlist, per-chat roles and a
+> read-only room toolset — read that guide before turning `GROUP_CHAT_ENABLED` on.
+
+---
+
+## Crypto & web3 *(optional; nothing that spends is on by default)*
+
+POLYROB can act as an economic agent when you want it to. Read-only token and wallet reads
+(`token_info`, `/check`) are on by default; everything that spends or signs is gated behind flags
+and off by default:
+
+- **x402 pay-per-request** — USDC micropayments on Base (opt-in Solana settlement) via the x402 protocol; the agent can both charge for its API and pay for external resources, and invoices settle facilitator-free by on-chain detection.
+- **Native agent wallet** — one seed derives per-venue EVM keys *and* a Solana address, with per-transaction and rolling 24h spend caps; testnet by default.
+- **On-chain token sight** — a read-only tool (14 verbs, NFTs included) for token identity, price, liquidity, a safety screen, pool discovery, and the agent's own portfolio across Base, Ethereum, Arbitrum, Polygon and Solana — plus `reconcile`, which diffs the agent's position ledger against actual chain balances. Address is the only identity (a ticker is never resolved for you), and unknown is never rendered as zero.
+- **Guarded on-chain trading** — transfers, exact-amount approvals/revokes and swaps (local Uniswap V3 first, opt-in aggregator fallback) go through one choke point that *simulates* the transaction, measures its real asset and allowance deltas, and refuses unless they match a declared intent. `dry_run` by default, fail-closed gates, and a spend the agent starts above a configurable ceiling waits for an owner approval and is sent once approved; the owner's own `/send`, `/swap` and `/bridge` (typed, or built and confirmed with buttons) pass the ceiling but stay inside the per-transaction and daily caps. Solana swaps (Jupiter) run the same guard order with an authority-grant refusal in place of the allowance check.
+- **Venue trading** — Hyperliquid (perps) and Polymarket (prediction markets) tools, dry-run by default behind a master + per-venue live switch and per-venue caps.
+- **ERC-8004 trustless agents** — optional on-chain agent identity + portable reputation.
+- **SIWE** wallet auth for the multi-tenant posture.
+
+> ⚠️ **Crypto features are unaudited.** The wallet, signing, and payment code (`crypto` extra) has
+> **not** had any independent security audit. It ships **as-is with no warranty** and can lose
+> funds. Enable it only at your own risk, and prefer testnets. See
+> [SECURITY.md](SECURITY.md#crypto--wallet--payment-features).
+
+---
+
+## Configuration essentials
+
+```bash
+# ~/.polyrob/.env — set any providers you have keys for
+OPENROUTER_API_KEY=sk-or-...   # recommended: one key reaches every model
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GEMINI_API_KEY=...
+
+# Memory backend: local_vector is the CLI default (hybrid recall; needs the [memory-vector]
+# extra, degrades to keyword FTS5 without it). Server default: sqlite
+MEMORY_BACKEND=local_vector
+
+# The CLI sets POLYROB_LOCAL for you (interactive tools). Autonomy is a second switch:
+# AUTONOMY_ENABLED=true
+```
+
+POLYROB falls back across providers automatically on billing or rate-limit errors; switch
+mid-session with `/model <provider> <model>` (or `<provider>/<model>`). Configuration guide →
+**[docs/guide/configuration.md](docs/guide/configuration.md)** · full environment-flag reference
+(SSOT) → **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**.
+
+Everything crypto — the agent wallet, paying for resources (x402), getting paid
+(invoicing, branded QR cards, on-chain settlement), watchtower subscriptions, on-chain
+token sight and guarded transfers, ERC-8004 reputation, credits, and the trading
+tools — is documented end-to-end (all OFF by default) in
+**[docs/guide/payments.md](docs/guide/payments.md)**.
+
+---
+
+## Installation options
+
+```bash
+pipx install "polyrob[all]"     # recommended — everything
+pip install polyrob             # core agent + keyword memory + CLI + the OpenAI SDK (~50 MB)
+pip install "polyrob[gemini]"   # the Gemini SDK (anthropic / docs / media / anysite likewise)
+pip install "polyrob[browser]"  # add Playwright browser automation
+pip install "polyrob[server]"   # add FastAPI REST API + web console
+```
+
+Base carries ONE provider SDK (`openai`, which also serves OpenRouter, NVIDIA and every
+OpenAI-compatible endpoint). On your own machine an optional capability installs itself
+on first use — set a Gemini key and the SDK arrives; on a server the miss names the extra.
+
+Every extra, what it adds and what it costs you in disk:
+[docs/guide/getting-started.md](docs/guide/getting-started.md#extras).
+
+### Self-hosting & deployment
+
+Run it three ways, and the posture auto-derives from how you bind it: **`local`** (loopback, no
+auth — the default), **`own_ops`** (public host with owner login; `--host 0.0.0.0` auto-upgrades to
+this so you can't accidentally expose a no-auth console), or **`multitenant`** (wallet/SIWE +
+billing). One `docker compose up` builds the server + browser + vector memory and persists
+memory/sessions/skills across restarts. See
+**[docs/guide/self-hosting.md](docs/guide/self-hosting.md)**.
+
+---
+
+## For developers
+
+```
+polyrob/
+├── agents/    # Task automation framework (agent loop, memory, skills, goals)
+├── api/       # FastAPI HTTP + A2A + OpenAI /v1
+├── cli/       # Terminal-native `polyrob` agent
+├── core/      # DI, config, permissions, instance/identity, autonomy runtime
+├── modules/   # LLM, Memory, Database, Auth, Credits
+├── tools/     # Browser, MCP, Email, Twitter, code-exec
+├── surfaces/  # Chat-surface adapters (Telegram, Email, WhatsApp, Discord, Slack, Signal, X)
+├── cron/      # Durable scheduled runs + goal board
+└── webview/   # Optional web console
+```
+
+```bash
+git clone https://github.com/theselfruleorg/polyrob
+cd polyrob
+bash install.sh          # installs THIS tree: venv + editable install + the wizard
+# — or manually:
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev,all]"
+python -m playwright install chromium
+
+pytest tests/unit -q     # fast unit suite
+ruff check .             # lint
+```
+
+Architecture overview → **[docs/guide/architecture.md](docs/guide/architecture.md)** · API reference
+→ **[docs/guide/api.md](docs/guide/api.md)** · deep architecture & contributor guide →
+**[AGENTS.md](AGENTS.md)** (every layer also has its own `README.md`)
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [docs/guide/getting-started.md](docs/guide/getting-started.md) | Install & first run |
+| [docs/guide/cli.md](docs/guide/cli.md) | Terminal agent commands |
+| [docs/guide/skills.md](docs/guide/skills.md) | Skills — install, author, and manage |
+| [docs/guide/packs.md](docs/guide/packs.md) | Packs — the index, install, enable/disable, the kill list, third-party rules |
+| [docs/guide/api.md](docs/guide/api.md) | REST + A2A + OpenAI-compatible API |
+| [docs/guide/configuration.md](docs/guide/configuration.md) | Configuring the agent — providers, memory, the autonomy dial, tools, surfaces, preferences |
+| [docs/guide/owner-controls.md](docs/guide/owner-controls.md) | Stop, pause and resume from any seat; approvals and the inbox |
+| [docs/guide/groups.md](docs/guide/groups.md) | Group chats (rooms) — allowlist, roles, per-chat policy, the room service job |
+| [docs/guide/profiles.md](docs/guide/profiles.md) | Named profiles — several isolated bots on one machine |
+| [docs/guide/instances.md](docs/guide/instances.md) | Instance identity — SOUL, character, avatar |
+| [docs/guide/upgrading.md](docs/guide/upgrading.md) | Upgrading an existing install |
+| [docs/guide/migration/](docs/guide/migration/README.md) | Migrating from another agent framework |
+| [docs/guide/architecture.md](docs/guide/architecture.md) | Architecture overview |
+| [docs/guide/self-hosting.md](docs/guide/self-hosting.md) | Self-hosting / deployment |
+| [docs/guide/deployment-postures.md](docs/guide/deployment-postures.md) | Deployment postures (local / own_ops / multitenant) |
+| [docs/guide/console.md](docs/guide/console.md) | Web console — the five destinations, owner actions, posture |
+| [docs/guide/payments.md](docs/guide/payments.md) | Payments, wallet & crypto — the complete money reference |
+| [docs/guide/security-model.md](docs/guide/security-model.md) | Honest trust model — heuristic gates vs. the OS/container boundary |
+| [docs/guide/streams.md](docs/guide/streams.md) | Goals and standing work — the goal board, objectives, fair dispatch, cron |
+| [docs/comparison.md](docs/comparison.md) | Comparison with other frameworks |
+| [docs/examples.md](docs/examples.md) | Real-world usage examples |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Environment-flag reference (SSOT) |
+| [AGENTS.md](AGENTS.md) | Deep architecture, invariants & contributor guide |
+| [CHANGELOG.md](CHANGELOG.md) | Notable changes |
+
+---
+
+## Contributing & security
+
+- **Contributions welcome** — see [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Report vulnerabilities** — see [SECURITY.md](SECURITY.md)
+- **License** — MIT ([LICENSE](LICENSE)) · brand/name use in [TRADEMARK.md](TRADEMARK.md) · third-party attributions in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)
+
+---
+
+<div align="center">
+
+**POLYROB** — by [The Selfrule Organization](https://theselfrule.org)
+
+</div>