TrustGraph Skill

Guía completa para operar TrustGraph – tu “segundo cerebro” digital para el workspace.

¿Qué es TrustGraph?

Sistema de memoria basado en grafos de conocimiento que:

• Conecta documentación mediante relaciones semánticas
• Permite consultas inteligentes usando GraphRAG (no solo búsqueda por palabras clave)
• Almacena datos en Cassandra (grafo) y Qdrant (vectores)
• Expone API REST y UI web en localhost:8888

Requisitos Previos

• Docker y Docker Compose instalados
• Python 3.x con httpx (pip install httpx)
• API key de LLM (OpenAI, Anthropic, Z.AI, Kimi, MiniMax, o Ollama local)

Flujos de Trabajo

1. Setup Inicial (Primera vez)

Opción A – Wizard Interactivo (Recomendado):

# Setup completo con menús navegables
./setup.sh makeenv
# ↑↓ para navegar, ENTER para seleccionar

# O usando make:
make makeenv

Opción B – Setup Manual:

# 1. Configurar variables de entorno manualmente
cp .env.example .env
nano .env  # Editar con tus API keys

# 2. Crear directorios de datos
make setup

2. Iniciar TrustGraph

# Iniciar todos los servicios
make up

# Verificar estado
make status
make health

# Ver logs en tiempo real
make logs

Servicios disponibles después de iniciar:

• Workbench UI: http://localhost:8888
• API Gateway: http://localhost:8080
• Grafana: http://localhost:3000 (admin/admin)

3. Cargar Documentación

# Cargar documentación del workspace
make load

# O con opciones avanzadas:
python scripts/load_docs.py --dry-run              # Simular sin enviar
python scripts/load_docs.py --category trustgraph  # Filtrar por categoría
python scripts/load_docs.py /ruta/a/docs          # Directorio específico

Nota: La primera carga puede tardar varios minutos dependiendo del volumen.

4. Consultar Memoria (GraphRAG)

# Modo interactivo (recomendado)
make query

# Búsqueda directa
make search QUERY="¿Qué es TrustGraph?"

# Comandos avanzados:
python scripts/query_graphrag.py "tu pregunta aquí"
python scripts/query_graphrag.py --search "término"
python scripts/query_graphrag.py --graph --depth 3
python scripts/query_graphrag.py --cores

5. Detener y Limpiar

# Detener servicios (conserva datos)
make down

# Limpieza completa (⚠️ elimina todos los datos)
make clean

# Resetear y recargar
make reset

Comandos Makefile Rápidos

Configuración (.env)

Variables esenciales:

# Proveedor de LLM: openai, anthropic, zai, kimi, minimax, ollama
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key

# O usar Z.AI (智谱AI/GLM)
LLM_PROVIDER=zai
ZAI_API_KEY=your-zai-key
ZAI_MODEL=glm-5

# O usar Kimi (Moonshot AI)
LLM_PROVIDER=kimi
KIMI_API_KEY=sk-kimi-your-key
KIMI_MODEL=kimi-k2

# O usar MiniMax
LLM_PROVIDER=minimax
MINIMAX_API_KEY=your-minimax-key
MINIMAX_MODEL=MiniMax-M2.5

# Ollama local
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434

# Configuración del proyecto
CONTEXT_CORE_ID=documentation
COLLECTION_NAME=docs

Cambio Rápido de Proveedor

Wizard Interactivo (recomendado para configuración inicial):

# Configuración completa con menús navegables
make makeenv
# ↑↓ para navegar entre proveedores, ENTER para seleccionar

Cambio rápido de proveedor:

# Ver estado actual y menú interactivo
make provider

# Cambiar directamente a cualquier proveedor
make provider USE=zai       # Z.AI (GLM-5)
make provider USE=kimi      # Kimi (K2)
make provider USE=minimax   # MiniMax (M2.5)
make provider USE=openai    # OpenAI (GPT-4o)
make provider USE=ollama    # Modelos locales

# Reiniciar para aplicar cambios
docker compose restart

API REST

Endpoints principales:

# Health check
curl http://localhost:8080/api/v1/health

# GraphRAG query
curl -X POST http://localhost:8080/api/v1/graphrag/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "¿Qué es TrustGraph?",
    "context_core": "documentation",
    "include_sources": true
  }'

# Vector search
curl -X POST http://localhost:8080/api/v1/search/vector \
  -H "Content-Type: application/json" \
  -d '{
    "query": "arquitectura del sistema",
    "collection": "docs",
    "limit": 5
  }'

Troubleshooting

TrustGraph no responde

# Verificar servicios
docker compose ps

# Ver logs
docker compose logs -f workbench
docker compose logs -f graphrag

# Reiniciar
docker compose restart

Error de API Key

# Verificar variable
echo $OPENAI_API_KEY

# Recargar .env
source .env

# Reiniciar servicios
docker compose restart

Puerto ocupado

# Encontrar proceso
lsof -i :8888

# Matar o cambiar puerto en docker-compose.yaml

Problemas de ingesta

# Verificar que Pulsar esté listo
docker compose logs pulsar

# Reintentar carga
python scripts/load_docs.py --retries 3

Recursos del Sistema

Arquitectura Resumida

Usuario → Workbench/UI → API Gateway → GraphRAG/Knowledge Builder
                                            ↓
                    Cassandra (Grafo) ← Pulsar → Qdrant (Vectores)

Pipeline de Datos

1. Ingesta: Documentos → Knowledge Builder
2. Procesamiento: Extracción de entidades y relaciones
3. Almacenamiento: Triples → Cassandra, Embeddings → Qdrant
4. Consulta: Query → Vector Search → Graph Traversal → Respuesta