pythonclaw 0.3.3__tar.gz → 0.6.0__tar.gz

{pythonclaw-0.3.3/pythonclaw.egg-info → pythonclaw-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonclaw
-Version: 0.3.3
+Version: 0.6.0
 Summary: OpenClaw reimagined in pure Python — autonomous AI agent with memory, RAG, skills, web dashboard, and multi-channel support.
 Author-email: Eric Wang <wangchen2007915@gmail.com>
 License: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/ericwang915/PythonClaw
 Project-URL: Documentation, https://github.com/ericwang915/PythonClaw#readme
 Project-URL: Repository, https://github.com/ericwang915/PythonClaw
 Project-URL: Issues, https://github.com/ericwang915/PythonClaw/issues
-Keywords: llm,agent,ai,autonomous,memory,rag,skills,telegram,chatbot,framework
+Keywords: llm,agent,ai,autonomous,memory,rag,skills,telegram,discord,whatsapp,chatbot,framework
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
@@ -27,6 +27,7 @@ Requires-Dist: anthropic
 Requires-Dist: google-generativeai
 Requires-Dist: python-telegram-bot[job-queue]>=20.0
 Requires-Dist: discord.py>=2.3
+Requires-Dist: pywa[fastapi]>=2.8
 Requires-Dist: apscheduler>=3.10
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: fastapi>=0.100
@@ -77,15 +78,18 @@ Dynamic: license-file
 | | Feature | Details |
 |---|---------|---------|
 | 🧠 | **Provider-agnostic** | DeepSeek, Grok, Claude, Gemini, Kimi, GLM — or any OpenAI-compatible API |
-| 🛠️ | **Three-tier skills** | Progressive loading: metadata → instructions → resources. Community marketplace via [SkillHub](https://www.skillhub.club) |
+| 🛠️ | **Three-tier skills** | Progressive loading: metadata → instructions → resources. Community marketplace via [ClawHub](https://clawhub.com) (13K+ free skills) |
 | 💾 | **Persistent memory** | Markdown-based long-term memory with daily logs and semantic recall |
 | 🔍 | **Hybrid RAG** | BM25 + dense embeddings + RRF fusion + LLM re-ranking |
 | 🌐 | **Web dashboard** | Browser UI for chat, config, skill catalog, identity editing, and marketplace |
 | 🎙️ | **Voice input** | Deepgram speech-to-text in the web chat |
 | ⏰ | **Cron jobs** | Schedule tasks via YAML or let the agent create its own |
-| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord — same agent, different interfaces |
+| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord, WhatsApp — same agent, different interfaces |
 | 🔄 | **Daemon mode** | PID-managed background process with `start` / `stop` / `status` |
 | 🧬 | **Soul + Persona** | Separate core identity from swappable role presentation |
+| 🔧 | **TOOLS.md** | Local environment notes — your cheat sheet for the agent |
+| 🔒 | **Per-group isolation** | Each chat session gets its own memory (optional) |
+| 🔁 | **Concurrency control** | Per-session locks + global semaphore prevent interleaving |
 
 ---
 
@@ -112,7 +116,7 @@ pythonclaw stop
 ```bash
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
-pip install -e ".[all]"
+pip install -e .
 pythonclaw onboard
 ```
 
@@ -125,11 +129,11 @@ pythonclaw onboard
 | `pythonclaw onboard` | Interactive setup wizard — choose LLM provider, enter API key |
 | `pythonclaw start` | Start the agent as a background daemon |
 | `pythonclaw start -f` | Start in foreground (no daemonize) |
-| `pythonclaw start --channels telegram discord` | Start with messaging channels |
+| `pythonclaw start --channels telegram discord whatsapp` | Start with messaging channels |
 | `pythonclaw stop` | Stop the running daemon |
 | `pythonclaw status` | Show daemon status (PID, uptime, port) |
 | `pythonclaw chat` | Interactive CLI chat (foreground REPL) |
-| `pythonclaw skill search <query>` | Search skills on [SkillHub](https://www.skillhub.club) |
+| `pythonclaw skill search <query>` | Search skills on [ClawHub](https://clawhub.com) |
 | `pythonclaw skill browse` | Browse top-rated skills |
 | `pythonclaw skill install <id>` | Install a community skill |
 | `pythonclaw skill info <id>` | View skill details |
@@ -170,24 +174,25 @@ $ pythonclaw start
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────┐
-│                       PythonClaw                         │
-├──────────┬───────────┬───────────┬───────────────────────┤
-│ CLI      │ Daemon    │ Sessions  │      Core             │
-│          │           │           │                       │
-│ onboard  │ start /   │ Store(MD) │ Agent                 │
-│ chat     │ stop /    │ Manager   │ ├─ Memory (Markdown)  │
-│ skill …  │ status    │           │ ├─ RAG (Hybrid)       │
-│          │           │           │ ├─ Skills (3-tier)    │
-│ Web UI ◄─┤ Channels  │           │ ├─ Compaction         │
-│ Voice In │ Telegram  │           │ ├─ Soul + Persona     │
-│          │ Discord   │           │ └─ Tool Execution     │
-├──────────┴───────────┴───────────┴───────────────────────┤
-│             LLM Provider Abstraction Layer               │
-│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM          │
-├──────────────────────────────────────────────────────────┤
-│            SkillHub Marketplace (skillhub.club)          │
-└──────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                         PythonClaw                            │
+├──────────┬────────────┬───────────┬──────────────────────────┤
+│ CLI      │ Daemon     │ Sessions  │      Core                │
+│          │            │           │                          │
+│ onboard  │ start /    │ Store(MD) │ Agent                    │
+│ chat     │ stop /     │ Manager   │ ├─ Memory (Markdown)     │
+│ skill …  │ status     │ Locks +   │ ├─ RAG (Hybrid)          │
+│          │            │ Semaphore │ ├─ Skills (3-tier)        │
+│ Web UI ◄─┤ Channels   │           │ ├─ Compaction            │
+│ Voice In │ Telegram   │ Per-group │ ├─ Soul + Persona        │
+│          │ Discord    │ Isolation │ ├─ Group Context          │
+│          │ WhatsApp   │           │ └─ Tool Execution        │
+├──────────┴────────────┴───────────┴──────────────────────────┤
+│               LLM Provider Abstraction Layer                 │
+│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM              │
+├──────────────────────────────────────────────────────────────┤
+│              ClawHub Marketplace (clawhub.com)               │
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -199,7 +204,7 @@ Start with `pythonclaw start` and open **http://localhost:7788**.
 - **Dashboard** — agent status, soul/persona preview, tool list
 - **Chat** — real-time chat with voice input (Deepgram)
 - **Skill Catalog** — browse installed skills by category
-- **Marketplace** — search and install skills from [SkillHub](https://www.skillhub.club)
+- **Marketplace** — search and install skills from [ClawHub](https://clawhub.com)
 - **Configuration** — edit LLM provider, API keys, and settings in-browser
 
 ---
@@ -220,8 +225,11 @@ See [`pythonclaw.example.json`](pythonclaw.example.json) for the full template.
   "web":      { "host": "0.0.0.0", "port": 7788 },
   "channels": {
     "telegram": { "token": "" },
-    "discord":  { "token": "" }
-  }
+    "discord":  { "token": "" },
+    "whatsapp": { "phoneNumberId": "", "token": "", "verifyToken": "pythonclaw_verify" }
+  },
+  "isolation":   { "perGroup": false },
+  "concurrency": { "maxAgents": 4 }
 }
 ```
 
@@ -235,8 +243,8 @@ Environment variables (e.g. `DEEPSEEK_API_KEY`, `TAVILY_API_KEY`) override JSON
 |----------|---------------|---------------|
 | **DeepSeek** | `deepseek-chat` | — |
 | **Grok (xAI)** | `grok-3` | — |
-| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | `pip install pythonclaw[anthropic]` |
-| **Gemini (Google)** | `gemini-2.0-flash` | `pip install pythonclaw[gemini]` |
+| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | — (included) |
+| **Gemini (Google)** | `gemini-2.0-flash` | — (included) |
 | **Kimi (Moonshot)** | `moonshot-v1-128k` | — |
 | **GLM (Zhipu)** | `glm-4-flash` | — |
 | Any OpenAI-compatible | Custom | — |
@@ -264,9 +272,9 @@ description: Execute Python code safely in an isolated subprocess.
 Run `python {skill_path}/run_code.py "expression"`
 ```
 
-### SkillHub Marketplace
+### ClawHub Marketplace
 
-Browse and install 22,000+ community skills from [skillhub.club](https://www.skillhub.club):
+Browse and install 13,000+ community skills from [ClawHub](https://clawhub.com) — free, no API key required:
 
 ```bash
 pythonclaw skill search "database backup"
@@ -282,11 +290,28 @@ Also accessible from the web dashboard **Marketplace** tab.
 ### Markdown Memory
 
 ```
-context/memory/
+~/.pythonclaw/context/memory/
 ├── MEMORY.md           # Curated long-term memory
 └── 2026-02-23.md       # Daily append-only log
 ```
 
+When **per-group isolation** is enabled (`"isolation": { "perGroup": true }` in config),
+each session (Telegram chat, Discord channel, etc.) gets its own `memory/`, `persona/`,
+and `soul/` under `~/.pythonclaw/context/groups/<session-id>/`, while global memories
+remain accessible via read-through fallback.
+
+### TOOLS.md — Local Notes
+
+```
+~/.pythonclaw/context/tools/
+└── TOOLS.md              # Your environment-specific cheat sheet
+```
+
+Skills define *how* tools work. `TOOLS.md` stores *your* specifics — SSH hosts, device
+nicknames, project paths, preferred defaults, API endpoints. Keeping them apart means
+you can update skills without losing your notes, and share skills without leaking your
+infrastructure. Editable from the web dashboard.
+
 ### Hybrid RAG Pipeline
 
 ```
@@ -326,14 +351,14 @@ PythonClaw/
 │   │   ├── agent.py           # Core reasoning loop
 │   │   ├── tools.py           # Tool schemas and execution
 │   │   ├── skill_loader.py    # Three-tier skill system
-│   │   ├── skillhub.py        # SkillHub marketplace client
+│   │   ├── skillhub.py        # ClawHub marketplace client
 │   │   ├── persistent_agent.py
 │   │   ├── compaction.py      # Context compaction
 │   │   ├── llm/               # Provider adapters
 │   │   ├── memory/            # Markdown memory
 │   │   ├── knowledge/         # Knowledge-base RAG
 │   │   └── retrieval/         # BM25 + dense + fusion + reranker
-│   ├── channels/              # Telegram, Discord
+│   ├── channels/              # Telegram, Discord, WhatsApp
 │   ├── scheduler/             # Cron jobs, heartbeat
 │   ├── web/                   # FastAPI dashboard + static assets
 │   └── templates/             # Built-in skill templates
@@ -351,7 +376,7 @@ PythonClaw/
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[all]"
+pip install -e .
 pytest tests/ -v
 ```
 
@@ -372,8 +397,8 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 | CLI | `openclaw start/stop` | `pythonclaw start/stop/status` |
 | Dashboard | Web UI | Web UI (localhost:7788) |
 | Memory | Markdown | Markdown (long-term + daily) |
-| Skills | Plugin system | Three-tier + SkillHub marketplace |
-| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord |
+| Skills | Plugin system | Three-tier + ClawHub marketplace |
+| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord, WhatsApp |
 | Voice | — | Deepgram STT |
 | LLM Providers | OpenAI, Anthropic, Gemini | DeepSeek, Grok, Claude, Gemini, Kimi, GLM |
 | Daemon | Background process | PID-managed (`start`/`stop`/`status`) |

{pythonclaw-0.3.3 → pythonclaw-0.6.0}/README.md

@@ -36,15 +36,18 @@
 | | Feature | Details |
 |---|---------|---------|
 | 🧠 | **Provider-agnostic** | DeepSeek, Grok, Claude, Gemini, Kimi, GLM — or any OpenAI-compatible API |
-| 🛠️ | **Three-tier skills** | Progressive loading: metadata → instructions → resources. Community marketplace via [SkillHub](https://www.skillhub.club) |
+| 🛠️ | **Three-tier skills** | Progressive loading: metadata → instructions → resources. Community marketplace via [ClawHub](https://clawhub.com) (13K+ free skills) |
 | 💾 | **Persistent memory** | Markdown-based long-term memory with daily logs and semantic recall |
 | 🔍 | **Hybrid RAG** | BM25 + dense embeddings + RRF fusion + LLM re-ranking |
 | 🌐 | **Web dashboard** | Browser UI for chat, config, skill catalog, identity editing, and marketplace |
 | 🎙️ | **Voice input** | Deepgram speech-to-text in the web chat |
 | ⏰ | **Cron jobs** | Schedule tasks via YAML or let the agent create its own |
-| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord — same agent, different interfaces |
+| 📡 | **Multi-channel** | CLI, Web, Telegram, Discord, WhatsApp — same agent, different interfaces |
 | 🔄 | **Daemon mode** | PID-managed background process with `start` / `stop` / `status` |
 | 🧬 | **Soul + Persona** | Separate core identity from swappable role presentation |
+| 🔧 | **TOOLS.md** | Local environment notes — your cheat sheet for the agent |
+| 🔒 | **Per-group isolation** | Each chat session gets its own memory (optional) |
+| 🔁 | **Concurrency control** | Per-session locks + global semaphore prevent interleaving |
 
 ---
 
@@ -71,7 +74,7 @@ pythonclaw stop
 ```bash
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
-pip install -e ".[all]"
+pip install -e .
 pythonclaw onboard
 ```
 
@@ -84,11 +87,11 @@ pythonclaw onboard
 | `pythonclaw onboard` | Interactive setup wizard — choose LLM provider, enter API key |
 | `pythonclaw start` | Start the agent as a background daemon |
 | `pythonclaw start -f` | Start in foreground (no daemonize) |
-| `pythonclaw start --channels telegram discord` | Start with messaging channels |
+| `pythonclaw start --channels telegram discord whatsapp` | Start with messaging channels |
 | `pythonclaw stop` | Stop the running daemon |
 | `pythonclaw status` | Show daemon status (PID, uptime, port) |
 | `pythonclaw chat` | Interactive CLI chat (foreground REPL) |
-| `pythonclaw skill search <query>` | Search skills on [SkillHub](https://www.skillhub.club) |
+| `pythonclaw skill search <query>` | Search skills on [ClawHub](https://clawhub.com) |
 | `pythonclaw skill browse` | Browse top-rated skills |
 | `pythonclaw skill install <id>` | Install a community skill |
 | `pythonclaw skill info <id>` | View skill details |
@@ -129,24 +132,25 @@ $ pythonclaw start
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────┐
-│                       PythonClaw                         │
-├──────────┬───────────┬───────────┬───────────────────────┤
-│ CLI      │ Daemon    │ Sessions  │      Core             │
-│          │           │           │                       │
-│ onboard  │ start /   │ Store(MD) │ Agent                 │
-│ chat     │ stop /    │ Manager   │ ├─ Memory (Markdown)  │
-│ skill …  │ status    │           │ ├─ RAG (Hybrid)       │
-│          │           │           │ ├─ Skills (3-tier)    │
-│ Web UI ◄─┤ Channels  │           │ ├─ Compaction         │
-│ Voice In │ Telegram  │           │ ├─ Soul + Persona     │
-│          │ Discord   │           │ └─ Tool Execution     │
-├──────────┴───────────┴───────────┴───────────────────────┤
-│             LLM Provider Abstraction Layer               │
-│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM          │
-├──────────────────────────────────────────────────────────┤
-│            SkillHub Marketplace (skillhub.club)          │
-└──────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                         PythonClaw                            │
+├──────────┬────────────┬───────────┬──────────────────────────┤
+│ CLI      │ Daemon     │ Sessions  │      Core                │
+│          │            │           │                          │
+│ onboard  │ start /    │ Store(MD) │ Agent                    │
+│ chat     │ stop /     │ Manager   │ ├─ Memory (Markdown)     │
+│ skill …  │ status     │ Locks +   │ ├─ RAG (Hybrid)          │
+│          │            │ Semaphore │ ├─ Skills (3-tier)        │
+│ Web UI ◄─┤ Channels   │           │ ├─ Compaction            │
+│ Voice In │ Telegram   │ Per-group │ ├─ Soul + Persona        │
+│          │ Discord    │ Isolation │ ├─ Group Context          │
+│          │ WhatsApp   │           │ └─ Tool Execution        │
+├──────────┴────────────┴───────────┴──────────────────────────┤
+│               LLM Provider Abstraction Layer                 │
+│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM              │
+├──────────────────────────────────────────────────────────────┤
+│              ClawHub Marketplace (clawhub.com)               │
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -158,7 +162,7 @@ Start with `pythonclaw start` and open **http://localhost:7788**.
 - **Dashboard** — agent status, soul/persona preview, tool list
 - **Chat** — real-time chat with voice input (Deepgram)
 - **Skill Catalog** — browse installed skills by category
-- **Marketplace** — search and install skills from [SkillHub](https://www.skillhub.club)
+- **Marketplace** — search and install skills from [ClawHub](https://clawhub.com)
 - **Configuration** — edit LLM provider, API keys, and settings in-browser
 
 ---
@@ -179,8 +183,11 @@ See [`pythonclaw.example.json`](pythonclaw.example.json) for the full template.
   "web":      { "host": "0.0.0.0", "port": 7788 },
   "channels": {
     "telegram": { "token": "" },
-    "discord":  { "token": "" }
-  }
+    "discord":  { "token": "" },
+    "whatsapp": { "phoneNumberId": "", "token": "", "verifyToken": "pythonclaw_verify" }
+  },
+  "isolation":   { "perGroup": false },
+  "concurrency": { "maxAgents": 4 }
 }
 ```
 
@@ -194,8 +201,8 @@ Environment variables (e.g. `DEEPSEEK_API_KEY`, `TAVILY_API_KEY`) override JSON
 |----------|---------------|---------------|
 | **DeepSeek** | `deepseek-chat` | — |
 | **Grok (xAI)** | `grok-3` | — |
-| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | `pip install pythonclaw[anthropic]` |
-| **Gemini (Google)** | `gemini-2.0-flash` | `pip install pythonclaw[gemini]` |
+| **Claude (Anthropic)** | `claude-sonnet-4-20250514` | — (included) |
+| **Gemini (Google)** | `gemini-2.0-flash` | — (included) |
 | **Kimi (Moonshot)** | `moonshot-v1-128k` | — |
 | **GLM (Zhipu)** | `glm-4-flash` | — |
 | Any OpenAI-compatible | Custom | — |
@@ -223,9 +230,9 @@ description: Execute Python code safely in an isolated subprocess.
 Run `python {skill_path}/run_code.py "expression"`
 ```
 
-### SkillHub Marketplace
+### ClawHub Marketplace
 
-Browse and install 22,000+ community skills from [skillhub.club](https://www.skillhub.club):
+Browse and install 13,000+ community skills from [ClawHub](https://clawhub.com) — free, no API key required:
 
 ```bash
 pythonclaw skill search "database backup"
@@ -241,11 +248,28 @@ Also accessible from the web dashboard **Marketplace** tab.
 ### Markdown Memory
 
 ```
-context/memory/
+~/.pythonclaw/context/memory/
 ├── MEMORY.md           # Curated long-term memory
 └── 2026-02-23.md       # Daily append-only log
 ```
 
+When **per-group isolation** is enabled (`"isolation": { "perGroup": true }` in config),
+each session (Telegram chat, Discord channel, etc.) gets its own `memory/`, `persona/`,
+and `soul/` under `~/.pythonclaw/context/groups/<session-id>/`, while global memories
+remain accessible via read-through fallback.
+
+### TOOLS.md — Local Notes
+
+```
+~/.pythonclaw/context/tools/
+└── TOOLS.md              # Your environment-specific cheat sheet
+```
+
+Skills define *how* tools work. `TOOLS.md` stores *your* specifics — SSH hosts, device
+nicknames, project paths, preferred defaults, API endpoints. Keeping them apart means
+you can update skills without losing your notes, and share skills without leaking your
+infrastructure. Editable from the web dashboard.
+
 ### Hybrid RAG Pipeline
 
 ```
@@ -285,14 +309,14 @@ PythonClaw/
 │   │   ├── agent.py           # Core reasoning loop
 │   │   ├── tools.py           # Tool schemas and execution
 │   │   ├── skill_loader.py    # Three-tier skill system
-│   │   ├── skillhub.py        # SkillHub marketplace client
+│   │   ├── skillhub.py        # ClawHub marketplace client
 │   │   ├── persistent_agent.py
 │   │   ├── compaction.py      # Context compaction
 │   │   ├── llm/               # Provider adapters
 │   │   ├── memory/            # Markdown memory
 │   │   ├── knowledge/         # Knowledge-base RAG
 │   │   └── retrieval/         # BM25 + dense + fusion + reranker
-│   ├── channels/              # Telegram, Discord
+│   ├── channels/              # Telegram, Discord, WhatsApp
 │   ├── scheduler/             # Cron jobs, heartbeat
 │   ├── web/                   # FastAPI dashboard + static assets
 │   └── templates/             # Built-in skill templates
@@ -310,7 +334,7 @@ PythonClaw/
 git clone https://github.com/ericwang915/PythonClaw.git
 cd PythonClaw
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[all]"
+pip install -e .
 pytest tests/ -v
 ```
 
@@ -331,8 +355,8 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 | CLI | `openclaw start/stop` | `pythonclaw start/stop/status` |
 | Dashboard | Web UI | Web UI (localhost:7788) |
 | Memory | Markdown | Markdown (long-term + daily) |
-| Skills | Plugin system | Three-tier + SkillHub marketplace |
-| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord |
+| Skills | Plugin system | Three-tier + ClawHub marketplace |
+| Channels | Discord, Telegram, WhatsApp | CLI, Web, Telegram, Discord, WhatsApp |
 | Voice | — | Deepgram STT |
 | LLM Providers | OpenAI, Anthropic, Gemini | DeepSeek, Grok, Claude, Gemini, Kimi, GLM |
 | Daemon | Background process | PID-managed (`start`/`stop`/`status`) |

{pythonclaw-0.3.3 → pythonclaw-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonclaw"
-version = "0.3.3"
+version = "0.6.0"
 description = "OpenClaw reimagined in pure Python — autonomous AI agent with memory, RAG, skills, web dashboard, and multi-channel support."
 readme = "README.md"
 license = {text = "MIT"}
@@ -12,7 +12,7 @@ requires-python = ">=3.10"
 authors = [
     {name = "Eric Wang", email = "wangchen2007915@gmail.com"},
 ]
-keywords = ["llm", "agent", "ai", "autonomous", "memory", "rag", "skills", "telegram", "chatbot", "framework"]
+keywords = ["llm", "agent", "ai", "autonomous", "memory", "rag", "skills", "telegram", "discord", "whatsapp", "chatbot", "framework"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -31,6 +31,7 @@ dependencies = [
     "google-generativeai",
     "python-telegram-bot[job-queue]>=20.0",
     "discord.py>=2.3",
+    "pywa[fastapi]>=2.8",
     "apscheduler>=3.10",
     "pyyaml>=6.0",
     "fastapi>=0.100",
@@ -58,6 +59,7 @@ include = ["pythonclaw*"]
 [tool.setuptools.package-data]
 pythonclaw = [
     "templates/**/*.py",
+    "templates/**/*.sh",
     "templates/**/*.yaml",
     "templates/**/*.md",
     "web/static/**/*",
@@ -65,3 +67,15 @@ pythonclaw = [
 
 [tool.setuptools.exclude-package-data]
 "*" = ["__pycache__", "*.pyc", "*.pyo"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

{pythonclaw-0.3.3 → pythonclaw-0.6.0}/pythonclaw/__init__.py

@@ -6,7 +6,7 @@ from .core.llm.base import LLMProvider
 from .core.llm.openai_compatible import OpenAICompatibleProvider
 from .init import init
 
-__version__ = "0.3.3"
+__version__ = "0.5.0"
 __all__ = [
     "Agent",
     "LLMProvider",

{pythonclaw-0.3.3 → pythonclaw-0.6.0}/pythonclaw/channels/discord_bot.py

@@ -1,7 +1,7 @@
 """
 Discord channel for PythonClaw.
 
-Session IDs: "discord:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
+Session IDs: "discord:dm:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
 
 Commands
 --------
@@ -9,21 +9,29 @@ Commands
   !status         — show session info
   !compact [hint] — compact conversation history
   <text>          — forwarded to Agent.chat(), reply sent back
+  <image>         — image attachments sent to LLM for analysis
 
 The bot responds to:
   - Direct messages (always)
-  - Channel mentions (@bot message) in guilds
-  - Optionally all messages in whitelisted channels
+  - Channel mentions (@bot message) in guilds (when requireMention=true)
+  - All messages in whitelisted channels (when requireMention=false)
 
 Access control
 --------------
 Set DISCORD_ALLOWED_USERS to a comma-separated list of Discord user IDs.
 Set DISCORD_ALLOWED_CHANNELS to restrict which guild channels the bot listens in.
 Leave empty to allow all.
+
+Group behaviour
+---------------
+Set ``channels.discord.requireMention`` to ``true`` to require @bot mention
+in guild channels. Default is ``false`` (respond when mentioned OR in
+whitelisted channels).
 """
 
 from __future__ import annotations
 
+import base64
 import logging
 from typing import TYPE_CHECKING
 
@@ -52,11 +60,13 @@ class DiscordBot:
         token: str,
         allowed_users: list[int] | None = None,
         allowed_channels: list[int] | None = None,
+        require_mention: bool = False,
     ) -> None:
         self._sm = session_manager
         self._token = token
         self._allowed_users: set[int] = set(allowed_users) if allowed_users else set()
         self._allowed_channels: set[int] = set(allowed_channels) if allowed_channels else set()
+        self._require_mention = require_mention
 
         intents = discord.Intents.default()
         intents.message_content = True
@@ -113,20 +123,27 @@ class DiscordBot:
             is_dm = isinstance(message.channel, discord.DMChannel)
             is_mentioned = client.user in message.mentions if not is_dm else False
 
-            # In guilds, only respond to mentions or whitelisted channels
-            if not is_dm and not is_mentioned and not self._is_allowed_channel(message.channel.id):
-                return
+            if not is_dm:
+                if self._require_mention and not is_mentioned:
+                    return
+                if not self._require_mention and not is_mentioned:
+                    if not self._is_allowed_channel(message.channel.id):
+                        return
 
             if not self._is_allowed_user(message.author.id):
                 await message.reply("Sorry, you are not authorised to use this bot.")
                 return
 
             content = message.content.strip()
-            # Remove bot mention from the beginning
             if is_mentioned and client.user:
                 content = content.replace(f"<@{client.user.id}>", "").strip()
 
-            if not content:
+            has_image = any(
+                a.content_type and a.content_type.startswith("image/")
+                for a in message.attachments
+            )
+
+            if not content and not has_image:
                 return
 
             # Command dispatch
@@ -141,7 +158,35 @@ class DiscordBot:
                 await self._cmd_compact(message, is_dm, hint)
                 return
 
-            await self._handle_chat(message, content, is_dm)
+            chat_input = content or ""
+            if has_image:
+                chat_input = await self._build_image_input(
+                    message, content or "What's in this image?"
+                )
+
+            await self._handle_chat(message, chat_input, is_dm)
+
+    # ── Image handling ────────────────────────────────────────────────────────
+
+    @staticmethod
+    async def _build_image_input(message: discord.Message, caption: str) -> list:
+        """Download image attachments and build multimodal content array."""
+        parts: list[dict] = [{"type": "text", "text": caption}]
+        for att in message.attachments:
+            if att.content_type and att.content_type.startswith("image/"):
+                try:
+                    data = await att.read()
+                    b64 = base64.b64encode(data).decode()
+                    media_type = att.content_type.split(";")[0]
+                    parts.append({
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:{media_type};base64,{b64}",
+                        },
+                    })
+                except Exception:
+                    logger.warning("[Discord] Failed to download attachment %s", att.filename)
+        return parts
 
     # ── Command implementations ───────────────────────────────────────────────
 
@@ -180,12 +225,24 @@ class DiscordBot:
         for chunk in self._split_message(result or "(no result)"):
             await message.reply(chunk)
 
-    async def _handle_chat(self, message: discord.Message, content: str, is_dm: bool) -> None:
+    async def _handle_chat(
+        self,
+        message: discord.Message,
+        content: str | list,
+        is_dm: bool,
+    ) -> None:
         sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
         agent = self._sm.get_or_create(sid)
+
+        if self._sm.is_locked(sid):
+            await message.reply("Processing previous message\u2026")
+
         async with message.channel.typing():
             try:
-                response = agent.chat(content)
+                async with self._sm.acquire(sid):
+                    import asyncio
+                    loop = asyncio.get_event_loop()
+                    response = await loop.run_in_executor(None, agent.chat, content)
             except Exception as exc:
                 logger.exception("[Discord] Agent.chat() raised an exception")
                 response = f"Sorry, something went wrong: {exc}"
@@ -219,11 +276,15 @@ def create_bot(session_manager: "SessionManager") -> "DiscordBot":
     allowed_channels = config.get_int_list(
         "channels", "discord", "allowedChannels", env="DISCORD_ALLOWED_CHANNELS",
     )
+    require_mention = config.get_bool(
+        "channels", "discord", "requireMention", default=False,
+    )
     return DiscordBot(
         session_manager=session_manager,
         token=token,
         allowed_users=allowed_users or None,
         allowed_channels=allowed_channels or None,
+        require_mention=require_mention,
     )