pyblock/docs/ROADMAP_AI_BACKEND.md

Roadmap: Astrolexis AI Backend for PyBLOCK

Objetivo

Backend API que actúa como proxy inteligente entre PyBLOCK y los LLM providers (Anthropic, OpenAI). Acceso único: pago en sats via Lightning a través de Astrolexis.

---

Estado Actual

✅ Fase 1: API Gateway MVP — COMPLETADO

Desplegado en producción: https://api.astrolexis.space/v1

Stack: Bun + Hono, SQLite, systemd service

Endpoints operativos:

POST /v1/chat            - Proxy a LLM (streaming SSE) con system prompt Bitcoin
POST /v1/auth/verify     - Verificar token y balance
POST /v1/topup           - Crear invoice Lightning para recargar
GET  /v1/topup/check/:h  - Verificar si invoice fue pagado
GET  /v1/usage           - Consultar uso del usuario
GET  /v1/models          - Modelos disponibles con pricing en sats
GET  /v1/health          - Health check

Infraestructura:

• Cloudflare Tunnel (HTTPS, sin origin cert necesario)
• systemd service (astrolexis-api.service) con auto-restart
• SQLite WAL mode para concurrencia

✅ Fase 2: Pagos Lightning — COMPLETADO

Implementación: AlbyHub via NWC (Nostr Wallet Connect)

• Invoice creation via make_invoice NWC
• Payment listener automático via subscribeNotifications
• Polling fallback via /v1/topup/check/:payment_hash
• Modelo prepago con balance (min 100, max 100,000 sats)
• Lightning node: 03cd787d7bfb97454aa1cd12a51a0c9d89136077187bcbd0b6705ab629e5c5264f
• Lightning address: pyblock@getalby.com

Flujo de recarga:

1. PyBLOCK -> POST /v1/topup {amount: 1000}
2. Gateway -> crea invoice via AlbyHub NWC
3. Gateway <- devuelve bolt11 invoice
4. PyBLOCK -> muestra QR + bolt11 en terminal
5. Usuario paga desde cualquier wallet
6. AlbyHub -> NWC notification -> balance acreditado automáticamente
7. PyBLOCK <- GET /v1/topup/check/{hash} -> confirma en UI

✅ Fase 3: System Prompt Bitcoin — COMPLETADO

System prompt inyectado automáticamente:

You are PyBLOCK AI, a Bitcoin and Lightning Network assistant
running inside PyBLOCK terminal dashboard.
...
Current node context:
{node_context}

Context injection: PyBLOCK envía node_context en cada request, el gateway lo formatea e inyecta en el system prompt antes del proxy.

Pricing en sats (operativo)

                    Costo por query típica (~500 in, ~1000 out tokens)
Claude Sonnet 4.6:  ~4 sats
Claude Haiku 4.5:   ~2 sats
Claude Opus 4.6:    ~18 sats
GPT-4o:             ~3 sats
GPT-4o Mini:        ~1 sat

---

Pendiente

🔲 Fase 4: Seguridad y Rate Limiting (Semana 1-2)

4.1 Rate limiting

Por token:       30 queries/hora, 500/dia
Burst:           Max 5 concurrent requests
Token size:      Max 4096 tokens output por query
Sin balance:     Rechazar con 402 + balance_sats + estimated_cost

4.2 Seguridad

• HTTPS obligatorio (✅ ya via Cloudflare Tunnel)
• No almacenar contenido de queries (privacy) — ✅ ya implementado
• Log solo metadata: timestamp, model, token counts, user_id — ✅ ya implementado
• API keys de Anthropic/OpenAI en env vars del server — ✅ ya implementado
• Rate limit por IP + por token
• Hard limit de gasto diario por usuario

🔲 Fase 5: Dashboard Admin (Semana 2-3)

5.1 Métricas

• Queries por dia/hora
• Revenue en sats (depósitos - costos API)
• Modelos más usados
• Top usuarios
• Costo vs revenue por modelo
• Error rate

5.2 Panel

Web dashboard o Grafana:

• Total revenue
• Active users (7d/30d)
• API cost breakdown
• Margin tracking

---

Integración con PyBLOCK (lado cliente)

Base URL

https://api.astrolexis.space/v1

Documentación completa de integración

Ver: astrolexis-api/docs/PYBLOCK_INTEGRATION.md

Incluye:

• Todos los endpoints con request/response de ejemplo
• Códigos de error y cómo manejarlos
• Implementación completa en Python (client.py, context.py, ui.py)
• Flujo del usuario paso a paso

Módulo pybitblock/ai/

ai/
  __init__.py       - chat(prompt, context) entry point
  client.py         - Astrolexis API client (auth, streaming, topup)
  context.py        - Gather node data for injection
  ui.py             - Terminal chat interface

Configuración del usuario

Una sola variable:

ASTROLEXIS_TOKEN=astrolexis_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Menú en PyBLOCK

Main Menu > AI Assistant

  Powered by Astrolexis KCode
  Balance: 4,521 sats

  Type your question or:
  T. Top Up Balance
  U. Usage History
  Q. Quit

  > "what's happening with my mempool?"

---

Timeline actualizado

Semana 1-2:   API Gateway MVP                    ✅ COMPLETADO
Semana 2-3:   Lightning payments (AlbyHub NWC)   ✅ COMPLETADO
Semana 3-4:   System prompt + context injection   ✅ COMPLETADO
Semana 4-5:   Security, rate limiting             🔲 PENDIENTE
Semana 5-6:   Admin dashboard + metrics           🔲 PENDIENTE
Semana 6-7:   PyBLOCK client module (ai/)         🔲 EQUIPO PYBLOCK
Semana 7-8:   Testing, docs, beta launch          🔲 CONJUNTO

---

Branding

En PyBLOCK:     "AI powered by Astrolexis KCode"
En Astrolexis:  "Available on PyBLOCK - Bitcoin Terminal Dashboard"
Licencia:       PyBLOCK (GPL) usa Astrolexis API como servicio externo
                No hay conflicto de licencias (API boundary)

---

Notas para el equipo de desarrollo

1. No hace falta GPU — todo se proxea a Anthropic/OpenAI cloud
2. No hay modo gratuito — toda query AI pasa por Astrolexis y se cobra en sats
3. El valor está en el system prompt + contexto Bitcoin — eso es el IP de Astrolexis
4. Lightning payments son el diferenciador — sin cuentas, sin email, sin KYC. Puro Bitcoin
5. Empezar con Sonnet — más barato, suficiente para queries de nodo. Opus como opción premium
6. El proxy es stateless — fácil de escalar horizontalmente si crece
7. Privacy first — no se guarda contenido de queries, solo metadata de billing
8. Servidor propio — sin costos de hosting, margen neto desde la primera query
9. AlbyHub NWC — pagos Lightning automáticos, sin polling necesario (con fallback)
10. Ya está en producción — https://api.astrolexis.space/v1/health para verificar