mira-engine 0.0.0__tar.gz

mira_engine-0.0.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.*
+.coverage
+coverage.xml
+htmlcov/

mira_engine-0.0.0/LICENSE

@@ -0,0 +1,11 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2026 MIRA Intelligence contributors
+
+This project is licensed under the GNU General Public License v3.0 or
+(at your option) any later version.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see:
+https://www.gnu.org/licenses/gpl-3.0.txt

mira_engine-0.0.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: mira-engine
+Version: 0.0.0
+Summary: A lightweight personal AI assistant framework
+Author: mira contributors
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: agent,ai,chatbot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: chardet<6.0.0,>=3.0.2
+Requires-Dist: croniter<7.0.0,>=6.0.0
+Requires-Dist: ddgs<10.0.0,>=9.0.0
+Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: json-repair<1.0.0,>=0.57.0
+Requires-Dist: lark-oapi<2.0.0,>=1.5.0
+Requires-Dist: litellm<2.0.0,>=1.81.5
+Requires-Dist: loguru<1.0.0,>=0.7.3
+Requires-Dist: mcp<2.0.0,>=1.26.0
+Requires-Dist: msgpack<2.0.0,>=1.1.0
+Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.3
+Requires-Dist: openai>=2.8.0
+Requires-Dist: prompt-toolkit<4.0.0,>=3.0.50
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
+Requires-Dist: pydantic<3.0.0,>=2.12.0
+Requires-Dist: python-socketio<6.0.0,>=5.16.0
+Requires-Dist: python-socks[asyncio]<3.0.0,>=2.8.0
+Requires-Dist: python-telegram-bot[socks]<23.0,>=22.6
+Requires-Dist: qq-botpy<2.0.0,>=1.2.0
+Requires-Dist: readability-lxml<1.0.0,>=0.8.4
+Requires-Dist: rich<15.0.0,>=14.0.0
+Requires-Dist: slack-sdk<4.0.0,>=3.39.0
+Requires-Dist: slackify-markdown<1.0.0,>=0.2.0
+Requires-Dist: socksio<2.0.0,>=1.0.0
+Requires-Dist: typer<1.0.0,>=0.20.0
+Requires-Dist: websocket-client<2.0.0,>=1.9.0
+Requires-Dist: websockets<17.0,>=16.0
+Provides-Extra: dev
+Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'dev'
+Requires-Dist: matrix-nio[e2e]>=0.25.2; extra == 'dev'
+Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'dev'
+Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'dev'
+Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: matrix
+Requires-Dist: matrix-nio[e2e]>=0.25.2; extra == 'matrix'
+Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'matrix'
+Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'matrix'
+Description-Content-Type: text/markdown
+
+# <img src="icon.ico" width="40" height="40" align="top"> Mira
+
+[![Tests](https://github.com/MIRA-Intelligence/mira/actions/workflows/tests.yml/badge.svg)](https://github.com/MIRA-Intelligence/mira/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/MIRA-Intelligence/mira/graph/badge.svg)](https://codecov.io/gh/MIRA-Intelligence/mira)
+
+An open-source, ultra-lightweight AI assistant tailored specifically for **Medical AI Research**.
+
+Powered by an underlying micro-agent framework, Mira is designed to execute complex medical imaging pipelines, from raw DICOM data processing to deep learning tasks, traditional radiomics, and survival analysis.
+
+## 🔬 Built-in Medical Skills
+
+Mira comes pre-loaded with specialized medical skills:
+1. **`medical-image-dl-pipeline`**: End-to-end deep learning pipeline (classification, segmentation, detection) built on MONAI and PyTorch. Features robust 5-Fold Cross-Validation and early stopping.
+2. **`radiomics`**: High-dimensional radiomic feature extraction using PyRadiomics, combined with LASSO/mRMR feature selection.
+3. **`survival-analysis`**: Time-to-event statistical modeling, Kaplan-Meier curves, and Cox Proportional Hazards models via lifelines.
+
+*Mira can also be leveraged for comprehensive literature reviews and academic manuscript writing.*
+
+## 🛡️ Core Agent Features
+
+Mira goes beyond standard AI wrappers by implementing a robust, production-ready agent architecture:
+- **Intelligent Model Routing**: Dynamically routes sub-tasks, agent reasoning, and tool calls to the most appropriate AI models based on task complexity and context, ensuring optimal performance and cost-efficiency.
+- **Strict Workspace Sandboxing (Read/Write Separation)**: The agent operates within a highly secure, confined workspace directory. Built-in filesystem and shell execution guards actively block path traversals (e.g., `cd ..`, `../`) and unauthorized updates to external paths, guaranteeing the safety of the host system. Crucially, it employs a sophisticated Read/Write separation model—allowing the agent securely to read system-level built-in skills without permitting any unauthorized edits to framework source code.
+
+## 🚀 Quick Start
+
+**1. Install**
+```bash
+git clone https://github.com/MIRA-Intelligence/mira.git
+cd Mira
+pip install -e .
+```
+
+**2. Configure**
+Run `mira onboard` to initialize the `config.json` and your workspace (defaults to `~/.mira`).
+```bash
+mira onboard
+```
+
+Then, configure your model settings and API keys in `~/.mira/config.json`:
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.mira/",
+      "model": "",
+      "provider": "custom",
+      "maxTokens": 8192,
+      "temperature": 0.6,
+      "maxToolIterations": 40,
+      "memoryWindow": 100,
+      "reasoningEffort": null
+    }
+  },
+  "providers": {
+    "custom": {
+      "apiKey": "",
+      "apiBase": null,
+      "extraHeaders": null
+    },
+    "azureOpenai": {
+      "apiKey": "",
+      "apiBase": null,
+      "extraHeaders": null
+    },
+    "anthropic": {
+      "apiKey": "",
+      "apiBase": null,
+      "extraHeaders": null
+    }
+  }
+}
+```
+
+## 💻 CLI Commands Reference
+
+Mira provides a comprehensive CLI for managing your sessions and configurations:
+
+- **`mira onboard`**
+  Initialize your configuration file and local workspace directory (`~/.mira` by default). This is the first command you should run after installation.
+
+- **`mira agent`**
+  Start an interactive AI chat session directly in your terminal. You can optionally pass a prompt instantly via the `-m` flag:
+  ```bash
+  mira agent -m "I have 77 MRI Dixon cases. Please set up a 3D classification pipeline to predict expiration vs. inspiration."
+  ```
+
+- **`mira status`**
+  Check the current status of your Mira configuration, agent defaults, and workspace environment.
+
+- OAuth providers (e.g., `openai-codex`, `github-copilot`) are now configured directly inside `mira onboard`.
+
+- **`mira gateway`**
+  Launch the background gateway service. This enables external API endpoints and multi-channel traffic. 
+
+### Local Engine Service CLI
+
+For desktop/local deployment workflows, use `mira-engine`:
+
+```bash
+mira-engine install-service
+mira-engine start
+mira-engine status
+mira-engine logs
+mira-engine doctor
+mira-engine doctor --export
+mira-engine upgrade --package mira
+mira-engine stop
+mira-engine uninstall-service
+```
+
+On macOS, `install-service` registers a user LaunchAgent at:
+
+```bash
+~/Library/LaunchAgents/com.projectmira.engine.plist
+```
+
+On Linux, `install-service` registers a user systemd unit:
+
+```bash
+~/.config/systemd/user/mira-engine.service
+```
+
+On Windows, `install-service` registers service name:
+
+```bash
+MiraEngine
+```
+
+Local engine logs and diagnostics:
+
+- Logs: `~/.mira/logs/agent-service.log` (+ rotated files)
+- Diagnostics bundles: `~/.mira/runtime/diagnostics/`
+
+## 🔗 Release Compatibility Mapping
+
+Mira tracks UI/Agent release compatibility in `compatibility.json`.
+
+- `release_train`: release window in `YYYY.MM` format
+- `ui`: supported UI minor range (e.g. `0.1.x`)
+- `agent`: supported agent minor range (e.g. `0.1.x`)
+- `api_contract`: API contract version (e.g. `v1`)
+- `min_agent_for_ui`: minimum compatible agent patch version
+
+Validate updates locally before opening a PR:
+
+```bash
+python scripts/validate_compatibility.py --file compatibility.json
+```
+
+## 📦 Agent Release Pipeline
+
+Tagging `v*` triggers `.github/workflows/agent-release.yml` to:
+
+- build/test the project on Linux/macOS/Windows
+- publish `mira` package artifacts (wheel/sdist)
+- build standalone `mira-engine` executables with checksums
+
+Use `.github/workflows/release-train.yml` (`workflow_dispatch`) to validate an
+`agent_tag + ui_tag` pair and run smoke checks before announcing a combined release.
+
+## 🏗️ Optional Self-hosted Path
+
+Docker-related files are in `deploy/`:
+
+- `deploy/docker-compose.yml`
+- `deploy/Dockerfile`
+- `deploy/entrypoint.sh`
+- `deploy/.env.example`
+
+Compose services include:
+- local build/run services: `mira-gateway`, `mira-api`, `mira-cli`
+- self-hosted release services (profile `self-hosted`): `mira-engine`, `mira-ui`
+
+Operator guide:
+
+- `docs/self-hosted-docker.md`
+
+## 💬 Multi-Channel Deployment (Coming Soon)
+Features to deploy Mira seamlessly to platforms like Telegram, Discord, Feishu, or Slack to assist your research team in real-time are in active development.
+
+## 🤝 Contributing / CLA
+
+All external contributions require acceptance of the Contributor License Agreement.
+See `CLA.md` for details. By submitting a PR, you confirm acceptance of this CLA.
+
+## 🙏 Acknowledgments
+
+The foundational CLI framework of Mira is built heavily upon the [mira](https://github.com/MIRA-Intelligence/mira). We sincerely thank the HKUDS team for their excellent open-source contribution to the community.
+
+---
+*Developed for researchers, by ECNU SKMR Lab.*

mira_engine-0.0.0/README.md

@@ -0,0 +1,192 @@
+# <img src="icon.ico" width="40" height="40" align="top"> Mira
+
+[![Tests](https://github.com/MIRA-Intelligence/mira/actions/workflows/tests.yml/badge.svg)](https://github.com/MIRA-Intelligence/mira/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/MIRA-Intelligence/mira/graph/badge.svg)](https://codecov.io/gh/MIRA-Intelligence/mira)
+
+An open-source, ultra-lightweight AI assistant tailored specifically for **Medical AI Research**.
+
+Powered by an underlying micro-agent framework, Mira is designed to execute complex medical imaging pipelines, from raw DICOM data processing to deep learning tasks, traditional radiomics, and survival analysis.
+
+## 🔬 Built-in Medical Skills
+
+Mira comes pre-loaded with specialized medical skills:
+1. **`medical-image-dl-pipeline`**: End-to-end deep learning pipeline (classification, segmentation, detection) built on MONAI and PyTorch. Features robust 5-Fold Cross-Validation and early stopping.
+2. **`radiomics`**: High-dimensional radiomic feature extraction using PyRadiomics, combined with LASSO/mRMR feature selection.
+3. **`survival-analysis`**: Time-to-event statistical modeling, Kaplan-Meier curves, and Cox Proportional Hazards models via lifelines.
+
+*Mira can also be leveraged for comprehensive literature reviews and academic manuscript writing.*
+
+## 🛡️ Core Agent Features
+
+Mira goes beyond standard AI wrappers by implementing a robust, production-ready agent architecture:
+- **Intelligent Model Routing**: Dynamically routes sub-tasks, agent reasoning, and tool calls to the most appropriate AI models based on task complexity and context, ensuring optimal performance and cost-efficiency.
+- **Strict Workspace Sandboxing (Read/Write Separation)**: The agent operates within a highly secure, confined workspace directory. Built-in filesystem and shell execution guards actively block path traversals (e.g., `cd ..`, `../`) and unauthorized updates to external paths, guaranteeing the safety of the host system. Crucially, it employs a sophisticated Read/Write separation model—allowing the agent securely to read system-level built-in skills without permitting any unauthorized edits to framework source code.
+
+## 🚀 Quick Start
+
+**1. Install**
+```bash
+git clone https://github.com/MIRA-Intelligence/mira.git
+cd Mira
+pip install -e .
+```
+
+**2. Configure**
+Run `mira onboard` to initialize the `config.json` and your workspace (defaults to `~/.mira`).
+```bash
+mira onboard
+```
+
+Then, configure your model settings and API keys in `~/.mira/config.json`:
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.mira/",
+      "model": "",
+      "provider": "custom",
+      "maxTokens": 8192,
+      "temperature": 0.6,
+      "maxToolIterations": 40,
+      "memoryWindow": 100,
+      "reasoningEffort": null
+    }
+  },
+  "providers": {
+    "custom": {
+      "apiKey": "",
+      "apiBase": null,
+      "extraHeaders": null
+    },
+    "azureOpenai": {
+      "apiKey": "",
+      "apiBase": null,
+      "extraHeaders": null
+    },
+    "anthropic": {
+      "apiKey": "",
+      "apiBase": null,
+      "extraHeaders": null
+    }
+  }
+}
+```
+
+## 💻 CLI Commands Reference
+
+Mira provides a comprehensive CLI for managing your sessions and configurations:
+
+- **`mira onboard`**
+  Initialize your configuration file and local workspace directory (`~/.mira` by default). This is the first command you should run after installation.
+
+- **`mira agent`**
+  Start an interactive AI chat session directly in your terminal. You can optionally pass a prompt instantly via the `-m` flag:
+  ```bash
+  mira agent -m "I have 77 MRI Dixon cases. Please set up a 3D classification pipeline to predict expiration vs. inspiration."
+  ```
+
+- **`mira status`**
+  Check the current status of your Mira configuration, agent defaults, and workspace environment.
+
+- OAuth providers (e.g., `openai-codex`, `github-copilot`) are now configured directly inside `mira onboard`.
+
+- **`mira gateway`**
+  Launch the background gateway service. This enables external API endpoints and multi-channel traffic. 
+
+### Local Engine Service CLI
+
+For desktop/local deployment workflows, use `mira-engine`:
+
+```bash
+mira-engine install-service
+mira-engine start
+mira-engine status
+mira-engine logs
+mira-engine doctor
+mira-engine doctor --export
+mira-engine upgrade --package mira
+mira-engine stop
+mira-engine uninstall-service
+```
+
+On macOS, `install-service` registers a user LaunchAgent at:
+
+```bash
+~/Library/LaunchAgents/com.projectmira.engine.plist
+```
+
+On Linux, `install-service` registers a user systemd unit:
+
+```bash
+~/.config/systemd/user/mira-engine.service
+```
+
+On Windows, `install-service` registers service name:
+
+```bash
+MiraEngine
+```
+
+Local engine logs and diagnostics:
+
+- Logs: `~/.mira/logs/agent-service.log` (+ rotated files)
+- Diagnostics bundles: `~/.mira/runtime/diagnostics/`
+
+## 🔗 Release Compatibility Mapping
+
+Mira tracks UI/Agent release compatibility in `compatibility.json`.
+
+- `release_train`: release window in `YYYY.MM` format
+- `ui`: supported UI minor range (e.g. `0.1.x`)
+- `agent`: supported agent minor range (e.g. `0.1.x`)
+- `api_contract`: API contract version (e.g. `v1`)
+- `min_agent_for_ui`: minimum compatible agent patch version
+
+Validate updates locally before opening a PR:
+
+```bash
+python scripts/validate_compatibility.py --file compatibility.json
+```
+
+## 📦 Agent Release Pipeline
+
+Tagging `v*` triggers `.github/workflows/agent-release.yml` to:
+
+- build/test the project on Linux/macOS/Windows
+- publish `mira` package artifacts (wheel/sdist)
+- build standalone `mira-engine` executables with checksums
+
+Use `.github/workflows/release-train.yml` (`workflow_dispatch`) to validate an
+`agent_tag + ui_tag` pair and run smoke checks before announcing a combined release.
+
+## 🏗️ Optional Self-hosted Path
+
+Docker-related files are in `deploy/`:
+
+- `deploy/docker-compose.yml`
+- `deploy/Dockerfile`
+- `deploy/entrypoint.sh`
+- `deploy/.env.example`
+
+Compose services include:
+- local build/run services: `mira-gateway`, `mira-api`, `mira-cli`
+- self-hosted release services (profile `self-hosted`): `mira-engine`, `mira-ui`
+
+Operator guide:
+
+- `docs/self-hosted-docker.md`
+
+## 💬 Multi-Channel Deployment (Coming Soon)
+Features to deploy Mira seamlessly to platforms like Telegram, Discord, Feishu, or Slack to assist your research team in real-time are in active development.
+
+## 🤝 Contributing / CLA
+
+All external contributions require acceptance of the Contributor License Agreement.
+See `CLA.md` for details. By submitting a PR, you confirm acceptance of this CLA.
+
+## 🙏 Acknowledgments
+
+The foundational CLI framework of Mira is built heavily upon the [mira](https://github.com/MIRA-Intelligence/mira). We sincerely thank the HKUDS team for their excellent open-source contribution to the community.
+
+---
+*Developed for researchers, by ECNU SKMR Lab.*

mira_engine-0.0.0/bridge/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mira-whatsapp-bridge",
+  "version": "0.1.0",
+  "description": "WhatsApp bridge for mira using Baileys",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js"
+  },
+  "dependencies": {
+    "@whiskeysockets/baileys": "7.0.0-rc.9",
+    "ws": "^8.17.1",
+    "qrcode-terminal": "^0.12.0",
+    "pino": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

mira_engine-0.0.0/bridge/src/index.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * mira WhatsApp Bridge
+ * 
+ * This bridge connects WhatsApp Web to mira's Python backend
+ * via WebSocket. It handles authentication, message forwarding,
+ * and reconnection logic.
+ * 
+ * Usage:
+ *   npm run build && npm start
+ *   
+ * Or with custom settings:
+ *   BRIDGE_PORT=3001 AUTH_DIR=~/.mira/whatsapp npm start
+ */
+
+// Polyfill crypto for Baileys in ESM
+import { webcrypto } from 'crypto';
+if (!globalThis.crypto) {
+  (globalThis as any).crypto = webcrypto;
+}
+
+import { BridgeServer } from './server.js';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const PORT = parseInt(process.env.BRIDGE_PORT || '3001', 10);
+const AUTH_DIR = process.env.AUTH_DIR || join(homedir(), '.mira', 'whatsapp-auth');
+const TOKEN = process.env.BRIDGE_TOKEN?.trim();
+
+if (!TOKEN) {
+  console.error('BRIDGE_TOKEN is required. Start the bridge via mira so it can provision a local secret automatically.');
+  process.exit(1);
+}
+
+console.log('🐈 mira WhatsApp Bridge');
+console.log('========================\n');
+
+const server = new BridgeServer(PORT, AUTH_DIR, TOKEN);
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('\n\nShutting down...');
+  await server.stop();
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  await server.stop();
+  process.exit(0);
+});
+
+// Start the server
+server.start().catch((error) => {
+  console.error('Failed to start bridge:', error);
+  process.exit(1);
+});

mira_engine-0.0.0/bridge/src/server.ts

@@ -0,0 +1,155 @@
+/**
+ * WebSocket server for Python-Node.js bridge communication.
+ * Security: binds to 127.0.0.1 only; requires BRIDGE_TOKEN auth; rejects browser Origin headers.
+ */
+
+import { WebSocketServer, WebSocket } from 'ws';
+import { WhatsAppClient, InboundMessage } from './whatsapp.js';
+
+interface SendCommand {
+  type: 'send';
+  to: string;
+  text: string;
+}
+
+interface SendMediaCommand {
+  type: 'send_media';
+  to: string;
+  filePath: string;
+  mimetype: string;
+  caption?: string;
+  fileName?: string;
+}
+
+type BridgeCommand = SendCommand | SendMediaCommand;
+
+interface BridgeMessage {
+  type: 'message' | 'status' | 'qr' | 'error';
+  [key: string]: unknown;
+}
+
+export class BridgeServer {
+  private wss: WebSocketServer | null = null;
+  private wa: WhatsAppClient | null = null;
+  private clients: Set<WebSocket> = new Set();
+
+  constructor(private port: number, private authDir: string, private token: string) {}
+
+  async start(): Promise<void> {
+    if (!this.token.trim()) {
+      throw new Error('BRIDGE_TOKEN is required');
+    }
+
+    // Bind to localhost only — never expose to external network
+    this.wss = new WebSocketServer({
+      host: '127.0.0.1',
+      port: this.port,
+      verifyClient: (info, done) => {
+        const origin = info.origin || info.req.headers.origin;
+        if (origin) {
+          console.warn(`Rejected WebSocket connection with Origin header: ${origin}`);
+          done(false, 403, 'Browser-originated WebSocket connections are not allowed');
+          return;
+        }
+        done(true);
+      },
+    });
+    console.log(`🌉 Bridge server listening on ws://127.0.0.1:${this.port}`);
+    console.log('🔒 Token authentication enabled');
+
+    // Initialize WhatsApp client
+    this.wa = new WhatsAppClient({
+      authDir: this.authDir,
+      onMessage: (msg) => this.broadcast({ type: 'message', ...msg }),
+      onQR: (qr) => this.broadcast({ type: 'qr', qr }),
+      onStatus: (status) => this.broadcast({ type: 'status', status }),
+    });
+
+    // Handle WebSocket connections
+    this.wss.on('connection', (ws) => {
+      // Require auth handshake as first message
+      const timeout = setTimeout(() => ws.close(4001, 'Auth timeout'), 5000);
+      ws.once('message', (data) => {
+        clearTimeout(timeout);
+        try {
+          const msg = JSON.parse(data.toString());
+          if (msg.type === 'auth' && msg.token === this.token) {
+            console.log('🔗 Python client authenticated');
+            this.setupClient(ws);
+          } else {
+            ws.close(4003, 'Invalid token');
+          }
+        } catch {
+          ws.close(4003, 'Invalid auth message');
+        }
+      });
+    });
+
+    // Connect to WhatsApp
+    await this.wa.connect();
+  }
+
+  private setupClient(ws: WebSocket): void {
+    this.clients.add(ws);
+
+    ws.on('message', async (data) => {
+      try {
+        const cmd = JSON.parse(data.toString()) as BridgeCommand;
+        await this.handleCommand(cmd);
+        ws.send(JSON.stringify({ type: 'sent', to: cmd.to }));
+      } catch (error) {
+        console.error('Error handling command:', error);
+        ws.send(JSON.stringify({ type: 'error', error: String(error) }));
+      }
+    });
+
+    ws.on('close', () => {
+      console.log('🔌 Python client disconnected');
+      this.clients.delete(ws);
+    });
+
+    ws.on('error', (error) => {
+      console.error('WebSocket error:', error);
+      this.clients.delete(ws);
+    });
+  }
+
+  private async handleCommand(cmd: BridgeCommand): Promise<void> {
+    if (!this.wa) return;
+
+    if (cmd.type === 'send') {
+      await this.wa.sendMessage(cmd.to, cmd.text);
+    } else if (cmd.type === 'send_media') {
+      await this.wa.sendMedia(cmd.to, cmd.filePath, cmd.mimetype, cmd.caption, cmd.fileName);
+    }
+  }
+
+  private broadcast(msg: BridgeMessage): void {
+    const data = JSON.stringify(msg);
+    for (const client of this.clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(data);
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    // Close all client connections
+    for (const client of this.clients) {
+      client.close();
+    }
+    this.clients.clear();
+
+    // Close WebSocket server
+    if (this.wss) {
+      this.wss.close();
+      this.wss = null;
+    }
+
+    // Disconnect WhatsApp
+    if (this.wa) {
+      await this.wa.disconnect();
+      this.wa = null;
+    }
+  }
+}