Update README.md

README.md

@@ -1,484 +1,16 @@
-# DECI — Decentralized Cognitive Identity
-
-> **PoH Engine · Sprint 1 MVP · Vertex Coders LLC**
-
-![Version](https://img.shields.io/badge/version-0.1.0--sprint1-red)
-![Status](https://img.shields.io/badge/status-MVP%20%2F%20Research-yellow)
-![Stack](https://img.shields.io/badge/stack-FastAPI%20%2B%20Qdrant%20%2B%20Python-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
-
----
-
-## ¿Qué es DECI?
-
-DECI es un motor experimental de **autenticación cognitiva continua**. En vez de preguntar *"¿qué sabes?"* (contraseña) o *"¿qué tienes?"* (token), DECI pregunta *"¿cómo piensas mientras escribes?"*
-
-Analiza señales de comportamiento en tiempo real — latencia entre teclas, patrones de corrección, micro-pausas — y genera un **Trust Score (0.0 → 1.0)** que indica si quien está escribiendo es un humano real o un bot automatizado.
-
-```
-Score >= 0.65  →  HUMAN      ✓
-Score  0.40-0.65  →  SUSPECT  ⚠
-Score <  0.40  →  BOT        ✗
-```
-
-> **Nota importante:** Este es un MVP de investigación (Sprint 1). Los números de precisión no están validados con datos reales todavía. Ver sección [Estado actual del proyecto](#estado-actual-del-proyecto).
-
----
-
-## Screenshots
-
-| Dashboard | Session Analyzer |
-|-----------|-----------------|
-| ![Dashboard](docs/screenshots/dashboard.png) | ![Analyzer](docs/screenshots/analyzer.png) |
-
-| Red Team Lab | Signal Analysis |
-|-------------|-----------------|
-| ![Attacks](docs/screenshots/attacks.png) | ![Signals](docs/screenshots/signals.png) |
-
----
-
-## Arquitectura
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    DECI Architecture                    │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  Browser/Client                                         │
-│  ┌──────────────────────┐                               │
-│  │  deci-dashboard.html │  ← Dashboard HTML (single     │
-│  │  (Keystroke capture) │    file, sin dependencias)    │
-│  └──────────┬───────────┘                               │
-│             │ POST /session/analyze                     │
-│             │ POST /attack/simulate/ghosting            │
-│             ▼                                           │
-│  ┌──────────────────────┐                               │
-│  │  FastAPI (Python)    │  ← PoH Engine, port 8000     │
-│  │  app/main.py         │                               │
-│  │  app/core/engine.py  │  ← Scoring logic              │
-│  └──────────┬───────────┘                               │
-│             │                                           │
-│             ▼                                           │
-│  ┌──────────────────────┐                               │
-│  │  Qdrant              │  ← Cognitive DNA Vault        │
-│  │  (Vector DB)         │    port 6333                  │
-│  └──────────────────────┘                               │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
-
 ---
-
-## Estructura del proyecto
-
-```
-deci-prototype/
-├── docker-compose.yml          # Levanta FastAPI + Qdrant
-├── Dockerfile                  # Container de la API
-├── .env                        # Variables de entorno
-├── requirements.txt            # Dependencias Python
-│
-├── app/
-│   ├── main.py                 # Punto de entrada FastAPI
-│   ├── core/
-│   │   ├── engine.py           # PoH Engine — corazón del sistema
-│   │   ├── config.py           # Configuración global
-│   │   └── security.py        # JWT + Shadow Mode
-│   ├── api/
-│   │   ├── endpoints/
-│   │   │   ├── session.py      # POST /session/analyze
-│   │   │   └── attack.py       # POST /attack/simulate/ghosting
-│   │   └── schemas/
-│   │       └── telemetry.py    # Modelos Pydantic — el Contrato
-│   ├── database/
-│   │   └── qdrant_vault.py     # Cognitive DNA Vault
-│   └── tests/
-│       └── deepseek_lab/       # Red Team attack suite
-│           ├── mimicry_attack_v2.py
-│           ├── ghosting_attack.py
-│           ├── forced_errors.py
-│           ├── entropy_scanner.py
-│           ├── benchmark.py
-│           └── results/
-│
-├── scripts/
-│   └── setup_db.py             # Inicializa colección Qdrant
-│
-└── deci-dashboard.html         # Dashboard completo (single file)
-```
-
+title: Deci Core Api
+emoji: 🛡️
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
 ---
 
-## Instalación y arranque rápido
-
-### Requisitos previos
-
-- [Docker Desktop](https://www.docker.com/products/docker-desktop/) instalado y corriendo
-- Python 3.11+ (solo para el red team lab)
-- Un browser moderno (Chrome, Firefox, Edge)
-
-### Paso 1 — Clonar el repo
-
-```bash
-git clone https://github.com/tu-usuario/deci-prototype.git
-cd deci-prototype
-```
-
-### Paso 2 — Configurar variables de entorno
-
-```bash
-cp .env.example .env
-# El .env por defecto funciona para desarrollo local
-# Cambia SECRET_KEY en producción
-```
-
-### Paso 3 — Levantar el backend
-
-```bash
-docker-compose up
-```
-
-Deberías ver algo así:
-
-```
-deci_vault  | Qdrant HTTP listening on 6333
-deci_core   | INFO: Uvicorn running on http://0.0.0.0:8000
-deci_core   | [DECI] Cognitive Vault ready — collection: cognitive_dna
-```
-
-### Paso 4 — Abrir el dashboard
-
-Tienes dos opciones:
-
-**Opción A — Directo en el browser (más simple):**
-```bash
-# Windows
-start deci-dashboard.html
-
-# Mac
-open deci-dashboard.html
+# DECI — Decentralized Cognitive Identity Core (PoH Engine)
 
-# Linux
-xdg-open deci-dashboard.html
-```
+**Invisible Behavioral Biometrics & Proof of Humanity Engine for Zero-Trust Authentication.**
 
-**Opción B — Con servidor local (recomendado, evita CORS):**
-```bash
-# Si tienes Python
-python -m http.server 5500
-# Abrir: http://localhost:5500/deci-dashboard.html
-
-# Si tienes Node
-npx serve .
-# Abrir: http://localhost:3000/deci-dashboard.html
-```
-
-### Paso 5 — Verificar que todo funciona
-
-El topbar del dashboard debe mostrar `● OPERATIONAL` en verde.
-
-Si muestra `● API OFFLINE`, verifica que `docker-compose up` esté corriendo.
-
----
-
-## Guía de uso del Dashboard
-
-### Tab 1 — Dashboard
-
-Vista general en tiempo real. Muestra:
-
-- **Métricas** — conteo de sesiones Human / Suspect / Bot / Calibrating
-- **Score distribution** — histograma de scores de las últimas sesiones
-- **Attack detections** — chart de ataques detectados vs bypassed (datos del Sprint 1)
-- **Live session feed** — feed en tiempo real de sesiones entrantes
-
-Las sesiones del feed en modo demo son simuladas. Cuando conectas el Session Analyzer, las sesiones reales aparecen aquí.
-
-### Tab 2 — Session Analyzer
-
-**El corazón del sistema.** Aquí puedes probar DECI con tu propia escritura.
-
-**Cómo usarlo:**
-
-1. Click en **Start** — el textarea se activa
-2. **Escribe cualquier cosa** — un párrafo, texto libre, lo que sea. Mínimo 10 keystrokes, ideal 80+
-3. Click en **Analyze** — el payload se envía al engine
-4. El resultado aparece a la derecha con:
-   - **Verdict** (HUMAN / SUSPECT / BOT)
-   - **Score** (0.0 → 1.0)
-   - **Confidence** — qué tan seguro está el engine
-   - **Signal breakdown** — por qué tomó esa decisión
-
-**Importante:** Con menos de 50 keystrokes el IKL Entropy es inestable. Para resultados confiables escribe al menos 2-3 oraciones completas.
-
-**¿Qué mide mientras escribes?**
-
-| Señal | Peso | Lo que detecta |
-|-------|------|----------------|
-| IKL Entropy | 30% | Variabilidad en el tiempo entre teclas. Los humanos tienen distribución lognormal. Los bots tienen distribución normal o constante. |
-| Corrections | 25% | Patrones de backspace. Los humanos cometen errores en ráfagas orgánicas. Los bots no cometen errores o los distribuyen uniformemente. |
-| Pauses | 15% | Micro-pausas (>800ms). Los humanos pausan antes de palabras difíciles. Los bots generan de forma lineal. |
-| Speed | 15% | Velocidad en CPM. Rango humano: 150-600 CPM. |
-| Fatigue | 15% | ¿Se simplifica el vocabulario con el tiempo? Los humanos se cansan. Los bots no. |
-
-### Tab 3 — Red Team Lab
-
-**El laboratorio de DeepSeek.** Simula ataques contra el engine para probar su robustez.
-
-#### Ghosting Attack
-
-Simula un bot que intenta imitar latencia humana. Cuatro niveles de sofisticación:
-
-| Nivel | Técnica | Score esperado | ¿Pasa? |
-|-------|---------|----------------|--------|
-| L1 — Constant | Delay fijo de 100ms | ~0.08 | ❌ BOT |
-| L2 — Gaussian | Noise gaussiano | ~0.22 | ❌ BOT |
-| L3 — Bimodal | Clusters rápido+lento | ~0.44 | ❌ SUSPECT |
-| L4 — Lognormal | Distribución biológica + bursts + fatiga | ~0.60 | ⚠ SUSPECT |
-
-**Cómo correrlo:**
-1. Seleccionar el nivel en el dropdown
-2. Opcionalmente cambiar el texto objetivo
-3. Click **Run Attack** — el payload se envía al endpoint real de Gemini
-4. El resultado aparece en el Attack Log
-
-**Full Suite** corre los 4 niveles en secuencia automáticamente.
-
-#### Forced Errors
-
-Testea si el engine detecta la ausencia de correcciones orgánicas:
-
-- **Variant A** — Cero correcciones (clásico tell de LLM) → detectado
-- **Variant C** — Fake burst (ataque sofisticado) → SUSPECT
-- **Variant E** — Bursts posicionados óptimamente → SUSPECT
-
-#### Replay Attack
-
-Visualiza el scatter de cosine similarity. El threshold de detección es 0.92 — sesiones con similarity mayor son flaggeadas como replay.
-
-### Tab 4 — Signal Analysis
-
-Análisis técnico de las señales:
-
-- **Signal weights** — donut chart con el peso de cada señal en el score final
-- **Human vs Bot radar** — comparación de perfil cognitivo humano real vs bot L4
-- **DeepSeek V1 vs V2** — evolución del ataque a través de versiones
-- **Signal definitions** — definición técnica de cada señal
-
----
-
-## Red Team Lab — Correr los ataques desde Python
-
-Además del dashboard, puedes correr los ataques directamente desde Python:
-
-```bash
-# Instalar dependencias
-pip install -r requirements.txt
-
-# Asegúrate de que docker-compose up está corriendo
-# Luego:
-
-# Ataque simple
-python app/tests/deepseek_lab/mimicry_attack_v2.py --version v2 --target gemini
-
-# Con texto largo (más confiable)
-python app/tests/deepseek_lab/mimicry_attack_v2.py \
-  --version v2 \
-  --target gemini \
-  --text "Intento de acceso no autorizado al nucleo VIC de Vertex Coders usando patron cognitivo avanzado de nivel cuatro"
-
-# Benchmark completo V1 vs V2
-python app/tests/deepseek_lab/mimicry_attack_v2.py --benchmark --runs 10
-
-# Suite completa de DeepSeek
-python app/tests/deepseek_lab/benchmark_v2.py --verbose --iterations 20
-```
-
-Los resultados se guardan en `app/tests/deepseek_lab/results/`.
-
----
-
-## API Endpoints
-
-Con el backend corriendo, la documentación interactiva está en:
-**http://localhost:8000/docs**
-
-### Endpoints principales
-
-#### `POST /session/analyze`
-
-Analiza una sesión de telemetría y devuelve un PoH verdict.
-
-
-
-```json
-// Request
-### POST /session/analyze
-Analiza la telemetría conductual. **Importante:** Requiere mínimo 15 eventos para un veredicto confiable.
-
-// Request (Esquema TelemetryPayload)
-{
-  "session_id": "SESS-001",
-  "events": [
-    { "key": "v", "timestamp": 1000.0 },
-    { "key": "e", "timestamp": 1150.0 }
-  ],
-  "metadata": {
-    "total_chars": 20,
-    "total_corrections": 0
-  }
-}
-
-// Response
-{
-  "verdict": "HUMAN",
-  "score": 0.8561,
-  "confidence": 0.90,
-  "signal_scores": {
-    "entropy": 0.85,
-    "cv": 0.15,
-    "corrections": 0.05
-  }
-}
-
-
-```
-
-#### `POST /attack/simulate/ghosting`
-
-Endpoint del red team. Simula un ataque de ghosting y devuelve el verdict del engine.
-
-```json
-// Request
-{
-  "session_id": "atk-001",
-  "events": [
-    { "key": "A", "timestamp": 1700000000100 },
-    { "key": "c", "timestamp": 1700000000200 }
-  ]
-}
-
-// Response
-{
-  "session_id": "atk-001",
-  "entropy_score": 0.43,
-  "score": 0.51,
-  "verdict": "SUSPECT",
-  "signal_breakdown": { ... }
-}
-```
-
-#### `GET /health`
-
-```json
-{ "api": "ok", "vault": "ok", "shadow_mode": true }
-```
-
-#### `DELETE /session/{user_id}/dna`
-
-Elimina todo el Cognitive DNA de un usuario. Cumplimiento GDPR Art. 17.
-
----
-
-## Variables de entorno (.env)
-
-```bash
-# API
-APP_ENV=development          # development | production
-SECRET_KEY=change_me_please  # JWT secret — cambia esto en producción
-
-# Qdrant
-QDRANT_HOST=qdrant           # nombre del servicio en docker-compose
-QDRANT_PORT=6333
-QDRANT_COLLECTION=cognitive_dna
-
-# PoH Engine thresholds
-POH_HUMAN_THRESHOLD=0.65     # score >= este valor → HUMAN
-POH_SUSPECT_THRESHOLD=0.40   # score entre 0.40-0.65 → SUSPECT
-POH_ENTROPY_MIN=1.8          # entropía mínima para clasificar como humano
-POH_CALIBRATION_SESSIONS=3   # sesiones requeridas antes de activar validación completa
-
-# Shadow Mode — en true, el engine observa pero NO bloquea
-SHADOW_MODE=true
-```
-
----
-
-## Estado actual del proyecto
-
-### ✅ Completado (Sprint 1)
-
-- PoH Engine funcional con 5 señales cognitivas
-- Cognitive DNA Vault (Qdrant) con GDPR erasure
-- API FastAPI completa con documentación automática
-- Red Team framework (DeepSeek attack suite)
-- Dashboard HTML completo con 4 módulos
-- Shadow Mode para calibración sin bloqueo
-- Cold start detection (período de calibración)
-- Docker Compose con Qdrant + FastAPI
-
-### ⚠️ Limitaciones conocidas (Sprint 1)
-
-- **No validado con datos reales** — los thresholds (0.65, 0.40) fueron elegidos por lógica, no por datos estadísticos de usuarios reales
-- **IKL Entropy inestable con < 50 keystrokes** — textos cortos dan entropy cercana a 0
-- **Sin ZK-Proofs** — la capa de privacidad avanzada está planificada para Sprint 2
-- **Sin P2P Mesh** — los nodos validadores están planificados para Sprint 2
-- **Sin WebSocket** — el dashboard usa polling/simulación, no conexión en vivo
-
-### 🔜 Sprint 2 (planificado)
-
-- ZK-Proof layer para privacidad absoluta
-- LibP2P validation mesh
-- Adaptive PoH challenges (se adaptan cuando un ataque los rompe)
-- WebSocket para feed en tiempo real
-- Validación con dataset de 50+ usuarios reales
-
----
-
-## Equipo
-
-| Rol | Responsabilidad |
-|-----|-----------------|
-| **Denis Sanchez Leyva** (CEO, Vertex Coders) | Producto, arquitectura general, FastAPI, dashboard |
-| **Claude** (Anthropic) | PoH Engine design, privacy layer, API architecture |
-| **Gemini** (Google) | Infrastructure, Qdrant integration, node mesh design |
-| **DeepSeek** | Offensive security, attack suite, cognitive mimicry testing |
-
----
-
-## Contribuir
-
-Este proyecto está en fase de investigación activa. Si quieres contribuir:
-
-1. Fork el repo
-2. Crea un branch: `git checkout -b feature/nombre-del-feature`
-3. Commit tus cambios: `git commit -m 'feat: descripción'`
-4. Push: `git push origin feature/nombre-del-feature`
-5. Abre un Pull Request
-
-**Áreas donde más se necesita ayuda:**
-- Recolección de datos reales para validar thresholds
-- Mejoras al PoH Engine (nuevas señales cognitivas)
-- Ataques nuevos para el red team lab
-- Tests unitarios
-
----
-
-## Licencia
-
-MIT License — ver [LICENSE](LICENSE) para detalles.
-
----
-
-## Disclaimer
-
-DECI es un proyecto de investigación en desarrollo activo. **No usar en producción** sin validación previa con datos reales de tu caso de uso específico. Los números de precisión en el artículo de lanzamiento son estimados teóricos, no métricas validadas.
-
----
-
-**Vertex Coders LLC — Miami, Florida**
-*Ofensivo por diseño. Defensivo por naturaleza.* 🛡️🔥
-
----
+DECI is a high-performance, privacy-first backend API designed to detect advanced AI bots, cognitive mimicry attacks, and credential stuffing in real time.
 
-*Hecho con ☕ y muchas noches de trinchera.*
+Developed by **Vertex Coders LLC**. *Offensive by design. Defensive by nature.* 🛡️🔥