Metadata-Version: 2.4
Name: pulpo-lib
Version: 0.1.0
Summary: Pulpo — bot orchestration engine with CLI, lib, API, and UI interfaces
Project-URL: Source, https://github.com/josetabuyo/pulpo
Author-email: José Tabuyo <josetabuyo@gmail.com>
License: MIT
Keywords: automation,bot,cli,telegram,whatsapp,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: greenlet>=3.0.0
Requires-Dist: groq>=0.11.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-groq>=1.1.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: langgraph>=1.1.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: playwright>=1.49.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-telegram-bot>=21.10.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: teli-lib>=0.1.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: wavi-lib>=0.2.0
Description-Content-Type: text/markdown

# 🐙 Pulpo

**Automatizá la atención de tu negocio por WhatsApp y Telegram.**

Pulpo conecta tus canales de mensajería a un sistema de bots inteligentes: respuesta automática, historial de conversaciones y gestión desde un portal propio. Sin código, sin complicaciones.

---

## ✨ ¿Qué hace Pulpo?

- **Respuesta automática** — tu bot responde al instante cuando no estás disponible
- **Multi-canal** — WhatsApp y Telegram desde un solo lugar
- **Portal de bot** — cada cliente gestiona sus canales, ve conversaciones y responde inline
- **Panel admin** — control total: agregar bots, ver estado de bots, monitorear en tiempo real

---

## 🚀 Empezar ahora

Accedé al portal público:

**[https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot](https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot)**

- ¿Ya tenés una cuenta? Ingresá con tu clave de bot.
- ¿Primera vez? → **[Crear bot nueva](https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot/nueva)**

---

## 📲 Conectar Telegram paso a paso

Para agregar un bot de Telegram a tu bot en Pulpo:

### 1. Crear el bot en Telegram

1. Abrí Telegram y buscá **@BotFather**
2. Enviá `/newbot`
3. Elegí un nombre para tu bot (ej: `Soporte Herrería`)
4. Elegí un username (debe terminar en `bot`, ej: `herreria_soporte_bot`)
5. BotFather te va a dar un **token** con este formato:
   ```
   123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
   ```
6. Guardalo — lo vas a necesitar en el paso siguiente

### 2. Agregar el bot a Pulpo

1. Entrá a tu portal: [https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot](https://unbuoyant-surgeless-micheal.ngrok-free.dev/bot)
2. En la sección **Telegram**, pegá el token en el campo y hacé click en **+ Agregar**
3. Listo — el bot ya está activo y respondiendo

### 3. Activar el bot

Compartí el link de tu bot (`t.me/herreria_soporte_bot`) con tus clientes. Cuando te escriban, Pulpo:
- Responde automáticamente con tu mensaje configurado
- Registra la conversación en tu portal
- Te permite responder manualmente desde el chat inline

---

## 📱 Conectar WhatsApp

1. En la sección **WhatsApp** del portal, ingresá tu número (formato internacional sin `+`, ej: `5491155612767`)
2. Click en **+ Agregar** → aparece un código QR
3. En tu WhatsApp móvil: **Dispositivos vinculados → Vincular dispositivo** → escaneá el QR
4. En 10-20 segundos el estado pasa a **Conectado**

> El bot mantiene la sesión activa. Si se desconecta, podés reconectar desde el portal sin perder el historial.

---

## 🛠️ Stack técnico

| Componente    | Tecnología                                      |
|---------------|-------------------------------------------------|
| API REST      | FastAPI + uvicorn                               |
| Frontend      | React + Vite                                    |
| Base de datos | SQLite async (`data/messages.db`)               |
| WhatsApp      | Playwright headless (perfil Chrome persistente) |
| Telegram      | python-telegram-bot v21                         |
| Exposición    | ngrok (etapa 1) → Cloudflare Tunnel (etapa 2)  |

---

## ⚡ Desarrollo local

### Requisitos

- Python 3.11+
- Node 18+
- `phones.json` con la configuración de bots

### Arrancar

```bash
./start.sh        # levanta backend (uvicorn) + frontend (vite)
```

Los puertos se leen del `.env` en la raíz:

```env
BACKEND_PORT=8000
FRONTEND_PORT=5173
ADMIN_PASSWORD=...
```

### Tests

```bash
# Backend (requiere server corriendo)
cd backend
pytest tests/ -v

# Frontend Playwright (requiere server corriendo)
cd frontend
node_modules/.bin/playwright test
```

---

## 🗂️ Estructura del proyecto

```
_/
├── backend/
│   ├── main.py              # FastAPI app, lifespan, routers
│   ├── sim.py               # Simulador (activo cuando ENABLE_BOTS=false)
│   ├── state.py             # clients dict + wa_session singleton
│   ├── config.py            # lee phones.json
│   ├── db.py                # SQLite async
│   ├── api/                 # routers: auth, bots, phones, whatsapp,
│   │                        #          telegram, messages, sim, bot, logs
│   ├── automation/
│   │   └── whatsapp.py      # lógica WA Web con Playwright
│   ├── bots/
│   │   └── telegram_bot.py  # bot de Telegram
│   └── tests/               # pytest: auth, logs, sim
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── DashboardPage.jsx    # panel admin
│   │   │   ├── BotPage.jsx      # portal de bot (login + dashboard)
│   │   │   └── NewBotPage.jsx # onboarding nueva bot
│   │   └── components/
│   │       ├── ChatWidget.jsx       # chat inline reutilizable
│   │       └── MonitorPanel.jsx     # drawer de monitoring en tiempo real
│   └── tests/               # Playwright: login, monitor
├── management/              # planes, visión, arquitectura
├── phones.json              # config de bots y teléfonos (gitignoreado)
├── data/                    # DB y sesiones Chrome (gitignoreado)
└── start.sh                 # arranque unificado
```

---

## 🔀 Worktrees (flujo de desarrollo)

Cada feature se desarrolla en su propio worktree — un servidor independiente con DB propia, sin tocar producción.

| Worktree     | Backend | Frontend | Estado     |
|--------------|---------|----------|------------|
| `_` (master) | 8000    | 5173     | Producción |
| dev-1        | 8001    | 5174     | Libre      |
| dev-2        | 8002    | 5175     | Libre      |

Ver `CLAUDE.md` para el flujo completo de creación de worktrees, symlinks y setup.

---

## 🗺️ Roadmap

- [x] Bots de WhatsApp (Playwright headless)
- [x] Bots de Telegram (python-telegram-bot)
- [x] Respuesta automática configurable por bot
- [x] Portal de bot — gestión de canales + chat inline
- [x] Alta de bot nueva (onboarding autogestionable)
- [x] Panel admin con monitoring en tiempo real
- [x] Exposición pública via ngrok
- [ ] Autenticación segura (OAuth / tokens)
- [ ] Dominio propio + Cloudflare Tunnel
- [ ] Reconexión automática de sesiones WA
