Live Demo | Documentation | Report Bug | Request Feature
Sistema RAG (Retrieval-Augmented Generation) listo para producción que transforma el conocimiento organizacional en un asistente conversacional inteligente. Diseñado para empresas que exigen seguridad, escalabilidad y rendimiento en tiempo real.
Cortex es una plataforma completa de asistente de conocimiento que combina búsqueda vectorial semántica, algoritmos de recuperación híbrida y respuestas LLM en streaming para entregar respuestas precisas y contextuales desde tu corpus documental.
A diferencia de implementaciones RAG básicas, Cortex está diseñado desde cero para entornos empresariales de producción con:
- Arquitectura multi-tenant con aislamiento de datos por cliente
- Detección y enmascaramiento de PII para cumplimiento regulatorio
- Streaming en tiempo real via Server-Sent Events
- Control de acceso basado en roles con permisos granulares
- Stack completo de observabilidad (métricas, logs, trazas)
Pruébalo ahora: Visita la demo en vivo para ver Cortex en acción con un corpus bancario pre-cargado.
| Requisito | Versión | Propósito |
|---|---|---|
| Docker | 20.10+ | Runtime de contenedores |
| Docker Compose | 2.0+ | Orquestación multi-contenedor |
| HuggingFace Token | Gratis | Inferencia LLM (obtener aquí) |
# Clone & enter
git clone https://github.com/DeepRatAI/cortex-knowledge-assistant.git
cd cortex-knowledge-assistant
# Configure
cp .env.example .env
echo "HUGGINGFACE_API_TOKEN=your_token_here" >> .env
# Launch
docker compose up -d./start.sh # Start all services
./stop.sh # Stop all services
docker compose logs -f # View logs
docker compose ps # Check status
|
|
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
│ CORTEX ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────────┐ ┌─────────────────────┐ │
│ │ React UI │─────▶│ FastAPI Core │─────▶│ Qdrant Vector DB │ │
│ │ (Vite/TS) │ │ (Python 3.12) │ │ (12,000+ docs) │ │
│ └─────────────┘ └────────┬─────────┘ └─────────────────────┘ │
│ │ │ │
│ │ ┌────────┴────────┐ │
│ │ │ │ │
│ │ ┌────▼────┐ ┌─────▼────┐ ┌─────────────────┐ │
│ │ │ Redis │ │ LLM │ │ PostgreSQL │ │
│ │ │ Cache │ │(Llama 3) │ │ (Users/Auth) │ │
│ │ └─────────┘ └──────────┘ └─────────────────┘ │
│ │ │
│ ┌─────▼─────────────────────────────────────────────────────────────┐ │
│ │ Cloudflare Tunnel (HTTPS) │ │
│ │ cortex.deeprat.tech ←→ api.cortex.deeprat.tech │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| Capa | Tecnologías | Por Qué Esta Elección |
|---|---|---|
| Frontend | React 18, TypeScript, Vite, TailwindCSS | Type-safe, builds rápidos, DX moderno |
| Backend | FastAPI, Python 3.12, Pydantic v2 | Async-nativo, auto OpenAPI docs, validación |
| Vector DB | Qdrant | Alto rendimiento, filtrado, snapshots |
| Cache | Redis | Gestión de sesiones, rate limiting |
| Database | PostgreSQL | Usuarios, roles, audit logs |
| LLM | HuggingFace Inference (Llama 3.1 8B) | Tier gratuito, sin GPU requerida |
| Embeddings | sentence-transformers (multilingüe) | Soporte Español/Inglés |
| Infraestructura | Docker Compose, Cloudflare Tunnel | HTTPS zero-config, edge caching |
cortex-knowledge-assistant/
├── src/cortex_ka/ # Core Python package
│ ├── api/ # FastAPI routes & middleware
│ ├── application/ # RAG service, DLP, chunking, prompts
│ ├── auth/ # JWT, RBAC, session management
│ ├── domain/ # Models, ports (hexagonal architecture)
│ ├── infrastructure/ # Adapters: Qdrant, HuggingFace, Redis
│ ├── transactions/ # Service instances, audit logging
│ ├── system/ # Setup, status, admin operations
│ ├── scripts/ # Ingestion, evaluation, maintenance
│ └── demos/ # Demo mode functionality
├── ui/ # React 18 + TypeScript + Vite frontend
├── tests/ # Pytest suite (35+ test files)
├── docker/ # Dockerfile variants & compose files
├── docs/ # Complete documentation suite
├── scripts/ # Utility scripts & demos
└── k8s/ # Kubernetes manifests (production-ready)
docker compose up -d| Servicio | Puerto | Propósito |
|---|---|---|
cortex_api |
8088 | Backend FastAPI |
cortex_ui |
3000 | Frontend React |
cortex_qdrant |
6333 | Base de datos vectorial |
cortex_redis |
6379 | Capa de cache |
cortex_postgres |
5432 | Datos relacionales |
# Ya configurado para este proyecto
docker run -d --name cloudflared-cortex \
--network host \
--restart unless-stopped \
cloudflare/cloudflared:latest \
tunnel run --token YOUR_TUNNEL_TOKEN# .env (required)
HUGGINGFACE_API_TOKEN=hf_xxxxxxxxxxxxx
# .env (optional)
CKA_JWT_SECRET=your-secret-key-change-in-production
CKA_LOG_LEVEL=INFO
CKA_PII_MASK_ENABLED=true
CKA_QDRANT_HOST=cortex_qdrant
CKA_REDIS_HOST=cortex_redis
CKA_POSTGRES_HOST=cortex_postgres# Crear entorno
python -m venv .venv
source .venv/bin/activate
# Instalar dependencias
pip install -r requirements.txt -r requirements-dev.txt
# Ejecutar tests
make test # Todos los tests
make test-fast # Saltar slow/e2e
make coverage # Con reporte de coverage
# Calidad de código
make lint # Ruff + mypy
make format # Black + isortDocs interactivos disponibles en runtime:
- Swagger UI: http://localhost:8088/docs
- ReDoc: http://localhost:8088/redoc
- OpenAPI JSON: http://localhost:8088/openapi.json
| Versión | Estado | Enfoque |
|---|---|---|
| Beta | Actual | Core RAG, multi-tenancy, PII detection, streaming, RBAC, Kubernetes ready |
| v1.0.0 | Próximo | Customer Experience, Employee Productivity, Admin Operations, UX Polish |
La v1.0.0 prioriza estabilidad operativa y experiencia de usuario sobre expansión funcional. Cada dominio (Customer, Employee, Admin) tendrá su superficie funcional completa.
Ver ROADMAP.md para el detalle completo incluyendo Design Intent, Status por feature y criterios de priorización.
Las contribuciones son bienvenidas. Ver CONTRIBUTING.md para las guías.
# Fork → Clone → Branch → Commit → Push → PR
git checkout -b feature/your-amazing-feature
git commit -m "feat: add amazing feature"
git push origin feature/your-amazing-featureEste proyecto tiene licencia dual:
| Caso de Uso | Licencia | Detalles |
|---|---|---|
| Open Source | AGPL-3.0 | Gratis para proyectos open source |
| Comercial | Licencia Comercial | Contactar para uso propietario |
Ver LICENSE para detalles completos.
Documentación completa disponible en docs/:
| Documento | Descripción |
|---|---|
| Índice | Punto de entrada y navegación |
| Inicio Rápido | Instalación y primera consulta |
| Arquitectura | Diseño hexagonal, componentes, flujo de datos |
| API Reference | 50+ endpoints documentados con ejemplos |
| Configuración | 40+ variables de entorno |
| Seguridad | JWT, RBAC, multi-tenancy, DLP, PII |
| Despliegue | Docker Compose, producción, Kubernetes |
| Desarrollo | Testing, contribución, arquitectura interna |
| Roadmap | Features planificadas para v1.0.0 |
| ADRs | Architecture Decision Records |
Construido con estos excelentes proyectos open source:
- FastAPI – High-performance async web framework
- Qdrant – Vector similarity search engine
- HuggingFace – LLM inference infrastructure
- sentence-transformers – State-of-the-art embeddings
- React – UI component library
