Klaus Proxy Global

# 🤖 klaude-proxy > Proxy semántico entre Claude Code y `api.anthropic.com`/Ollama con caché vectorial en Qdrant, Knowledge RAG de proyecto, Sources RAG (web/markdown/PDF), analytics de costes y dashboard de observabilidad en tiempo real. ## ¿Qué es? Un proxy HTTP que se interpone entre tu instancia de Claude Code y la API de Anthropic (o Ollama local). Tres capas de enriquecimiento semántico: 1. **Caché semántica** — dual threshold: score ≥ 0.98 → respuesta directa sin LLM (`X-Cache: HIT`); 0.87–0.97 → inyecta la respuesta previa como RAG context (`X-Cache: CACHE-RAG`) 2. **Knowledge RAG** — indexa los ficheros del proyecto (`klaude_knowledge`, búsqueda híbrida BM25+dense). Cada petición recibe contexto relevante del código base automáticamente (`X-Cache: KNOWLEDGE-RAG`) 3. **Sources RAG** — indexa documentación externa: webs via Crawl4AI, ficheros Markdown y PDFs (`klaude_sources`). Enriquece las respuestas con fuentes de conocimiento externas (`X-Cache: SOURCES-RAG`) Registra el coste real de cada llamada y el ahorro acumulado en SQLite, visible en el dashboard web. ```text Claude Code ──▶ klaude-proxy :8080 ──▶ Qdrant (klaude_cache / klaude_knowledge / klaude_sources) │ │ │ miss │ analytics.db ▼ ▼ api.anthropic.com / Ollama /data/analytics.db ``` ## ⚡ Inicio rápido ```bash cp .env.example .env # Añadir ANTHROPIC_API_KEY (solo esta) ./scripts/setup.sh # Levanta Qdrant + proxy en Podman # Configurar Claude Code export ANTHROPIC_BASE_URL=http://localhost:8080 ``` ## 🏗️ Stack | Componente | Tecnología | | --- | --- | | Proxy | FastAPI + Python 3.12 | | Vector DB | Qdrant v1.18.2 — 3 colecciones: `klaude_cache`, `klaude_knowledge`, `klaude_sources` | | Embeddings | Fastembed `nomic-embed-text-v1.5` (local, sin API key) | | Web crawling | Crawl4AI (headless browser, soporte JS) | | Analytics | SQLite stdlib (persistente en volumen Podman) | | Orquestación | Podman Compose | ## 📊 Dashboard El dashboard muestra en tiempo real el estado del sistema, costes y logs: ```bash open http://localhost:8080/dashboard # ó en servidor remoto: open http://192.168.1.50:8080/dashboard ``` | Sección | Descripción | | --- | --- | | 📋 Live Logs | Logs del proxy en tiempo real vía SSE | | 📄 Request Content | Texto plano de cada petición enviada a Anthropic | | 🔢 Session Counters | Cache hits, misses y vectores indexados en Qdrant | | 💰 Costes | USD gastados en Anthropic y USD ahorrados por caché | | 📞 Llamadas Proveedor | Peticiones salientes a Anthropic y respuestas entrantes | ## 📡 API de observabilidad ```bash # Estadísticas de caché curl http://localhost:8080/cache/stats # Costes y contadores de sesión curl http://localhost:8080/analytics/stats # Últimas 50 peticiones (histórico entre reinicios) curl http://localhost:8080/analytics/requests?n=50 # Totales históricos acumulados curl http://localhost:8080/analytics/history ``` ## 📚 Documentación | Doc | Contenido | | --- | --- | | [docs/architecture.md](docs/architecture.md) | Diagrama de flujo completo y decisiones de diseño | | [docs/proxy.md](docs/proxy.md) | API endpoints, X-Cache headers y variables de entorno | | [docs/cache.md](docs/cache.md) | Caché semántica, dual-threshold y trigger `kache` | | [docs/cache_flush_manual.md](docs/cache_flush_manual.md) | Cómo y cuándo hacer flush manual del caché | | [docs/knowledge_base.md](docs/knowledge_base.md) | Knowledge RAG — indexación de ficheros del proyecto | | [docs/sources.md](docs/sources.md) | Sources RAG — ingestión web/markdown/PDF | | [docs/analytics.md](docs/analytics.md) | Analytics de costes, SQLite y endpoints `/analytics/*` | | [docs/dashboard.md](docs/dashboard.md) | Dashboard web — paneles, datos y layout | | [docs/providers.md](docs/providers.md) | Providers — routing Anthropic vs Ollama | | [docs/setup.md](docs/setup.md) | Instalación y configuración multicliente | | [docs/test_suite_generation.md](docs/test_suite_generation.md) | Generación y ejecución de la batería de tests | ## 🔒 Seguridad - Solo se necesita `ANTHROPIC_API_KEY` en `.env` (excluido de git) - Sin API keys de terceros para embeddings — modelo 100% local - El proxy valida TLS hacia Anthropic (nunca `--insecure`) - `CLAUDE.md` excluido de git (contexto local de K*) - SQLite de analytics almacenado en volumen Podman aislado (no exportado)