pip install universal-rag                 # núcleo (embeddings deterministas)
pip install "universal-rag[local]"        # + embeddings neuronales locales
pip install "universal-rag[media]"        # + audio/video/youtube (faster-whisper, yt-dlp)
pip install "universal-rag[s3]"           # + S3/MinIO (boto3)
pip install "universal-rag[tables]"       # + tablas en PDF (pdfplumber)
pip install "universal-rag[local,media,s3,tables]"  # todo

# Ingesta (el conector se resuelve automáticamente por esquema/extensión/dominio)
universal-rag ingest ./docs/manual.pdf
universal-rag ingest "https://es.wikipedia.org/wiki/Energía_solar"
universal-rag ingest "./informes/*.md"            # globs = ingesta masiva
universal-rag ingest ./podcast.mp3                # → transcripción local + minutos
universal-rag ingest ./clase.mp4                  # → pista de audio → ASR + minutos
universal-rag ingest "https://youtu.be/abc123"    # → YouTube → ASR + minutos
universal-rag ingest "drive://<fileId>"           # → Google Drive (público/compartido)

# Fase 5: S3/MinIO y Notion
universal-rag ingest "s3://mi-bucket/informes/"   # → prefijo: ingesta todos los soportados
universal-rag ingest "s3://mi-bucket/informe.pdf" # → objeto concreto (MinIO: endpoint_url=…)
universal-rag ingest "notion://<page-id>"          # → página de Notion (requiere RAG_NOTION_TOKEN)
universal-rag ingest "notion://database/<db-id>"   # → cada fila = un documento
universal-rag ingest "notion://search/manual faq"  # → primer resultado de la búsqueda

# Fase 7: Confluence y SharePoint (empresariales)
universal-rag ingest "confluence://space/DEV"      # → todas las páginas del espacio
universal-rag ingest "confluence://page/12345"     # → una página concreta
universal-rag ingest "confluence://cql/text ~ \"seguridad\""  # → búsqueda CQL
universal-rag ingest "https://acme.atlassian.net/wiki/spaces/DEV"  # → URL directa
universal-rag ingest "sharepoint://contoso.sharepoint.com/sites/Marketing"
universal-rag ingest "https://contoso.sharepoint.com/sites/Marketing" -o folder=/General/2024

# Consulta con citas (en media, con minuto exacto)
universal-rag query "¿cada cuánto se limpian los paneles?"

# Fase 7: memoria conversacional multi-turno
universal-rag query "¿qué es RAG?" --conversation demo
universal-rag query "¿y cómo se compara con LangChain?" --conversation demo  # recuerda el turno anterior
universal-rag conversations                          # lista conversaciones vivas
universal-rag conversations --show demo              # historial de una conversación
universal-rag conversations --clear all              # borra todas

# Fase 8: agente multi-hop (plan + pasos trazables)
universal-rag ask "¿Qué mantenimiento necesita un panel solar y cuánto dura el inversor?"
universal-rag ask "…" --max-steps 3 --planning heuristic --quiet

# Chat interactivo multi-turno (memoria activada por defecto)
universal-rag chat
universal-rag chat --conversation demo               # reanuda la conversación 'demo'

# Fase 7: sincronización programada
universal-rag sync add "https://ejemplo.com/docs" --interval 600
universal-rag sync list                              # estado de las fuentes
universal-rag sync run <job-id>                      # ejecución inmediata
universal-rag sync remove <job-id>

# Colecciones (Fase 4): bases de conocimiento aisladas
universal-rag ingest ./contratos/2025.pdf --collection legal
universal-rag query "¿cláusula de penalización?" --collection legal
universal-rag collections                        # lista colecciones activas

# Chat interactivo en la terminal
universal-rag chat

# Evaluación de calidad con un golden set (precision/recall/MRR)
universal-rag eval examples/golden.jsonl --k 5
universal-rag eval examples/golden.jsonl --json      # reporte completo en JSON

# Administración
universal-rag documents     # lista lo ingestado
universal-rag stats         # documentos, fragmentos, conectores, modo de búsqueda

universal-rag serve --port 8100
# → http://localhost:8100/      workbench web (Fase 6: chat streaming + gestión)
# → http://localhost:8100/chat  mini chat clásico
# → http://localhost:8100/docs  Swagger UI

curl -X POST localhost:8100/ingest -H 'Content-Type: application/json' \
     -d '{"source": "https://ejemplo.com/articulo"}'

curl -X POST localhost:8100/ingest -H 'Content-Type: application/json' \
     -d '{"source": "./entrevista.mp3", "options": {"language": "es", "asr_model": "small"}}'

curl -X POST localhost:8100/query -H 'Content-Type: application/json' \
     -d '{"question": "¿qué dijo sobre costos?", "k": 4}'

# Fase 4 — colecciones y jobs asíncronos
curl -X POST localhost:8100/ingest/text -H 'Content-Type: application/json' \
     -d '{"text": "…", "title": "Nota", "collection": "legal"}'

curl -X POST localhost:8100/ingest/async -H 'Content-Type: application/json' \
     -d '{"source": "./podcast-largo.mp3"}'          # → {"job_id": …}
curl localhost:8100/jobs/<job_id>                     # → estado del job

# Fase 4 — con autenticación (si RAG_API_KEY está definida)
curl localhost:8100/stats -H 'X-API-Key: <tu-key>'

# Fase 6 — streaming SSE (eventos: meta → token* → done)
curl -N -X POST localhost:8100/query/stream -H 'Content-Type: application/json' \
     -d '{"question": "¿qué dijo sobre costos?"}'

# Fase 7 — memoria conversacional multi-turno (mismo conversation_id = contexto compartido)
curl -X POST localhost:8100/query -H 'Content-Type: application/json' \
     -d '{"question": "¿qué es RAG?", "conversation_id": "sesion-web-1"}'
curl -X POST localhost:8100/query -H 'Content-Type: application/json' \
     -d '{"question": "¿y sus desventajas?", "conversation_id": "sesion-web-1"}'
curl localhost:8100/conversations                     # conversaciones vivas
curl localhost:8100/conversations/sesion-web-1        # historial (user/assistant)
curl -X DELETE localhost:8100/conversations/sesion-web-1

# Fase 7 — sincronización programada
curl -X POST localhost:8100/sync -H 'Content-Type: application/json' \
     -d '{"source": "https://ejemplo.com/docs", "interval": 600}'
curl localhost:8100/sync                              # jobs + último estado
curl -X POST localhost:8100/sync/<job_id>/run         # ejecución inmediata
curl -X DELETE localhost:8100/sync/<job_id>

# Fase 8 — agente multi-hop (plan → búsquedas → síntesis con pasos trazables)
curl -X POST localhost:8100/query/agent -H 'Content-Type: application/json' \
     -d '{"question": "¿Qué mantenimiento necesita un panel solar y cuánto dura el inversor?"}'

# Fase 8 — streaming del agente (SSE: plan → step* → synthesize → token* → done)
curl -N -X POST localhost:8100/query/agent/stream -H 'Content-Type: application/json' \
     -d '{"question": "…", "max_steps": 3, "planning": "heuristic"}'

universal-rag mcp                             # stdio
universal-rag mcp --transport streamable-http --port 8200

docker compose up -d --build
curl http://localhost:8100/health

from universal_rag import CollectionManager, RAGPipeline

rag = RAGPipeline()
rag.ingest("./docs/contrato.pdf")
rag.ingest("./entrevista.mp3", language="es", asr_model="small")

answer = rag.query("¿cuál es la cláusula de penalización?")
print(answer.answer)
for citation in answer.citations:
    minute = f" {citation.timestamp}" if citation.timestamp else ""
    print(f"  [{citation.source}{minute}] {citation.title} → {citation.quote[:80]}")
#  [audio 03:12–04:05] Entrevista → ...sobre la cláusula de penalización...

# Fase 6: streaming token a token + caché semántica
for event in rag.stream_query("¿cuál es la cláusula de penalización?"):
    if event["type"] == "token":
        print(event["value"], end="", flush=True)
    elif event["type"] == "done":
        print("\ncitas:", len(event["answer"]["citations"]))
rag.query("¿cuál es la cláusula de penalización?").cached   # → True (⚡ caché)

# Fase 4: colecciones aisladas que comparten embedder/generator
manager = CollectionManager()
manager.get("legal").ingest("./docs/contrato.pdf")
manager.get("faq").ingest_text("¿Horario? De 9 a 17.", title="FAQ")
manager.get("faq").query("¿cuál es el horario?")
print(manager.list_collections())   # resumen por colección

# Fase 7: memoria conversacional multi-turno
rag.query("¿qué es RAG?", conversation_id="demo")
answer = rag.query("¿y cómo se compara con LangChain?", conversation_id="demo")  # recuerda el turno previo
print(rag.memory.conversations())   # [{"id": "demo", "turns": 2, …}]
print(rag.memory.history("demo"))   # mensajes user/assistant para inspección

# Fase 7: sincronización programada
from universal_rag.core.sync import SyncScheduler

scheduler = SyncScheduler(rag, tick=5.0, state_path="data/sync_state.json")
scheduler.register("https://ejemplo.com/docs", interval=600)
scheduler.start()                    # hilo de fondo; con la API: RAG_SYNC_ENABLED=1

export RAG_LLM_BASE_URL=http://localhost:11434/v1
export RAG_LLM_MODEL=llama3.1

fuente ──▶ ConnectorRegistry (auto-descubrimiento + prioridad) ──▶ Document
              │ text/file/url (F1)      │ audio/video/youtube/drive (F2: ASR local)
              │                         │ s3/notion (F5)      │ segments (start, end, text)
              │                         │ confluence/sharepoint (F7: APIs oficiales)
              │                         └ tablas DOCX/HTML/PDF → Markdown (F5)
                                        ▼
                                        Chunker ──▶ Chunks ──▶ Embedder ──▶ VectorStore (Chroma)
                                        (texto: párrafos)    (media: por minuto [mm:ss])
                                                                     │
        pregunta ──▶ Caché semántica (F6, coseno ≥ threshold) ──▶ hit: tokens desde caché
          │ miss           (F7: se omite si la consulta es conversacional)
          ▼
        Retriever ◀────────────────────────────────────┘
          │  │ vectorial (coseno)
          │  └ híbrido: + BM25 (F3) ── fusión RRF/weighted
          │ RetrievedChunks ──▶ Reranker (F3: cross-encoder · F5: LLM, opcionales)
                        ▼
                   Generator (OpenAI-compat / echo) ──▶ Answer + Citations [1][2]… [00:00–01:05]
                        │  ▲ historial user/assistant por conversation_id (F7, LRU)
                        │  query():      Answer completo
                        └  stream_query(): meta → token* → done  (SSE, F6)

        SyncScheduler (F7): re-ingesta periódica de fuentes registradas → pipeline.ingest()
                             (hilo de fondo con RAG_SYNC_ENABLED=1; estado JSON opcional)

git clone https://github.com/rtostudioco/universal-rag && cd universal-rag
pip install -e ".[dev]"
pytest                # 306 tests (sin red, sin modelos pesados)
ruff check .