polyrob 0.5.0__tar.gz

polyrob-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The POLYROB Authors
+
+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.

polyrob-0.5.0/MANIFEST.in

@@ -0,0 +1,7 @@
+graft data/prompts
+graft webview/static
+graft webview/templates
+graft avatar
+recursive-include agents/personality/characters *.json
+include config/*.template
+include README.md LICENSE

polyrob-0.5.0/PKG-INFO

@@ -0,0 +1,482 @@
+Metadata-Version: 2.4
+Name: polyrob
+Version: 0.5.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.0.0
+Requires-Dist: anthropic>=0.20.0
+Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: aiohttp>=3.8.0
+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>=40.0.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: apsw>=3.46
+Requires-Dist: sqlite-vec>=0.1.6
+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: python-docx>=0.8.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: markdown>=3.5.0
+Requires-Dist: markdownify>=0.11.0
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: imageio>=2.37.0
+Requires-Dist: python-magic>=0.4.27
+Requires-Dist: nltk>=3.9.0
+Requires-Dist: anysite-cli>=0.3
+Requires-Dist: pyyaml>=6
+Provides-Extra: server
+Requires-Dist: fastapi==0.123.9; extra == "server"
+Requires-Dist: starlette==0.50.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"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40.0; extra == "browser"
+Provides-Extra: memory-vector
+Requires-Dist: sentence-transformers>=3.0.0; extra == "memory-vector"
+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: telegram
+Requires-Dist: aiogram>=3.17.0; extra == "telegram"
+Provides-Extra: twitter
+Requires-Dist: tweepy>=4.14.0; extra == "twitter"
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.0.0; extra == "voice"
+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[browser,crypto,memory-vector,server,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) and fails over between them automatically,
+remembers what it learns across sessions, and reaches you wherever you are — your terminal, a web
+dashboard, 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`) that transparently degrades to keyword search if 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.
+
+Skills use the open [agentskills.io](https://agentskills.io) `SKILL.md` format — the same format as
+Claude Code, read straight from `~/.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 20+ slash commands (`/compact`, `/usage`, `/memory`, `/model`, `/self`, `/replay`, `/autonomy`).
+- **Web dashboard** — a real-time Socket.IO console: watch the agent work, browse its workspace, preview files and browser screenshots, inspect memory and the goal board.
+- **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.
+- **Chat surfaces** — Telegram (live incremental streaming + voice-note transcription), email (IMAP/SMTP), and WhatsApp.
+
+## 🧠 Multi-provider intelligence
+
+- **Six providers, one agent** — OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter (Grok/Kimi/Qwen/GLM), NVIDIA NIM — behind a native LLM layer with **no third-party agent framework**.
+- **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** — cuts token cost on long sessions, with cached-token metrics surfaced per provider.
+- **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+**.
+
+```bash
+# 1. Install (with all optional features)
+pipx install "polyrob[all]"
+
+# 2. Install the browser engine (for web automation)
+python -m playwright install chromium
+
+# 3. Configure (writes ~/.polyrob/.env)
+polyrob init
+
+# 4. Sanity-check your setup
+polyrob doctor
+
+# 5. Start it
+polyrob
+```
+
+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 personal-agent mode** to unlock the self-evolving and goal-seeking loops (skills, curator,
+goal board, self-wake, episodic memory):
+
+```bash
+# ~/.polyrob/.env  — single-user, on your own machine
+POLYROB_LOCAL=true
+```
+
+<details>
+<summary>Optional: web dashboard & REST API</summary>
+
+```bash
+polyrob dashboard   # single-user web UI  → 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` | LLM-compresses the context window (e.g. 8,432 → 3,210 tokens) mid-session |
+| `/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 |
+
+Named toolsets (`minimal · research · coding · browser · full · safe`) let you scope exactly what
+the agent can touch. A handful of management subcommands round it out — `polyrob doctor` (preflight),
+`polyrob kb add/search` (local knowledge base), and `polyrob update --apply` (self-update with
+snapshot → guarded migrate → verify → **auto-rollback** on failure).
+
+---
+
+## 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`), tenant-scoped |
+| Reflective memory | phase-organized, LLM-consolidated, importance-based forgetting |
+| Adaptive context | LLM-synthesis compaction in the 85–95% band, with anti-thrash cooldown |
+| Prompt caching | per-provider, with cached-token cost metrics |
+| 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, 20+ slash commands, resumable sessions |
+| Web dashboard | real-time Socket.IO feed, file browser, live screenshots |
+| 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 |
+| Chat surfaces | Telegram, email, WhatsApp — 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** ·
+voice transcription (**faster-whisper**) · **A2A** · OpenAI-compatible `/v1` · **agentskills.io**
+skills · **sqlite-vec** + **sentence-transformers** local RAG.
+
+---
+
+## Safe autonomy by design
+
+An autonomous agent that touches the web, your files, and other people needs guardrails. POLYROB
+treats untrusted input as data — never as commands — with the core protections **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 isolation** | Subprocess (or hardened Docker) isolation, no inherited API keys | On when code-exec enabled |
+| **3-tier access** | OWNER / CORRESPONDENT / DENIED routing for chat surfaces | Opt-in (`CORRESPONDENT_ACCESS_ENABLED`) |
+| **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 **3-tier 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 · **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, and never expose public group chats without understanding
+> the risks.
+
+---
+
+## Crypto & web3 *(optional, off by default)*
+
+POLYROB can act as an economic agent when you want it to — all of it gated behind flags and off by
+default:
+
+- **x402 pay-per-request** — anonymous USDC micropayments (Base, Avalanche, IoTeX) via the Coinbase facilitator; the agent can both charge for its API and pay for external resources.
+- **Native agent wallet** — an EOA wallet with per-transaction and rolling 24h spend caps; testnet by default.
+- **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
+MEMORY_BACKEND=sqlite          # keyword FTS5 (default, no extra deps)
+# MEMORY_BACKEND=local_vector  # semantic vector recall (pip install "polyrob[memory-vector]")
+
+# Personal-agent mode — turns on skills/curator/goal-board/self-wake as a group
+POLYROB_LOCAL=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)**.
+
+---
+
+## Installation options
+
+```bash
+pipx install "polyrob[all]"     # recommended — everything
+pip install polyrob             # core agent + keyword memory + CLI  (~50 MB, zero cloud deps)
+pip install "polyrob[browser]"  # add Playwright browser automation
+pip install "polyrob[server]"   # add FastAPI REST API + WebView
+```
+
+| Extra | What it adds |
+|-------|--------------|
+| *(none)* | Core agent, keyword memory, CLI |
+| `server` | FastAPI REST API + WebView (Socket.IO) |
+| `browser` | Playwright browser automation |
+| `memory-vector` | Semantic vector recall (sentence-transformers + sqlite-vec) |
+| `crypto` | Web3, x402 pay-per-request, Hyperliquid |
+| `telegram` | Telegram surface (aiogram) |
+| `twitter` | Twitter/X integration (tweepy) |
+| `voice` | Voice transcription (faster-whisper) |
+| `dev` | Testing, linting, type-checking |
+| `all` | Everything above |
+
+### 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 dashboard), 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)
+├── cron/      # Durable scheduled runs + goal board
+└── webview/   # Optional single-user web dashboard
+```
+
+```bash
+git clone https://github.com/theselfruleorg/polyrob
+cd polyrob
+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/api.md](docs/guide/api.md) | REST + A2A + OpenAI-compatible API |
+| [docs/guide/configuration.md](docs/guide/configuration.md) | Configuration guide |
+| [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 dashboard — capabilities & payments |
+| [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>
+</content>