Setup — antes de PyCon Colombia 2026

Objetivo: antes del taller, tenés academy check verde y Cognee reachable. El día del evento no perdemos 20 min en instalar.

1. Requisitos base

• Python 3.12+ bash python3 --version # 3.12.x o superior
• uv — gestor de paquetes rápido. bash curl -LsSf https://astral.sh/uv/install.sh | sh # o brew install uv
• Docker Desktop (o Docker Engine + docker compose) — solo si usás la opción local de Cognee.
• git, make (viene por defecto en macOS/Linux).

2. Clone + install

git clone https://github.com/centinela-io/ctl-academy.git
cd ctl-academy
uv sync

Esto crea .venv/ con todas las dependencias fijadas.

3. OpenRouter API key

1. Registrate en https://openrouter.ai.
2. Cargá crédito (USD 5 alcanza sobrado; usamos claude-haiku-4.5 ~USD 0.20 por sesión completa).
3. Generá una key en https://openrouter.ai/keys.
4. Configurala: bash cp .env.example .env # editá .env y reemplazá OPENROUTER_API_KEY=sk-or-v1-REPLACE-ME

4. Cognee — elegí una ruta

Cognee necesita un grafo (Neo4j). Dos rutas soportadas — elegí una:

Ruta A — Neo4j local en Docker (recomendado)

academy cognee up          # levanta neo4j:5.24-community en localhost:7687
academy cognee status      # debe imprimir "✅ Neo4j alive"

Browser Neo4j: http://localhost:7474 (user neo4j, pass loopcraft).

Los valores por defecto de .env.example ya apuntan a este Neo4j local.

Ruta B — Neo4j remoto pre-cargado

Si el instructor te compartió credenciales de una instancia hospedada (Centinela pre-carga una para participantes sin Docker):

1. Abrí .env.
2. Comentá las 3 líneas de la "Opción A".
3. Descomentá las 3 líneas de la "Opción B" y pegá las credenciales: bash NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io NEO4J_USER=neo4j NEO4J_PASSWORD=…tu-pass…
4. Verificá: bash academy cognee status

No hace falta correr academy cognee up en esta ruta.

5. Verificar la rig

./scripts/setup.sh   # bootstrap + smoke test
academy check        # gates verdes en repo vacío
academy status       # 0/10 checkpoints esperado en repo fresco

Esperado: check verde. status muestra la tabla con todos los signals en ○.

6. (Opcional) Coding agent instalado

Vas a poder usar los starter prompts con cualquiera:

• Claude Code (recomendado)
• Cursor
• Codex CLI
• OpenCode

O escribí el código a mano leyendo las referencias colapsables en cada lección.

7. Chequeos previos al día del taller

• [ ] uv --version funciona
• [ ] uv sync termina sin errores
• [ ] .env tiene una OPENROUTER_API_KEY real (no placeholder)
• [ ] academy check sale verde
• [ ] academy cognee status responde OK (ruta A o B)
• [ ] academy site serve abre http://127.0.0.1:8000
• [ ] Existe .cognee_system/databases/ (lo crea ./scripts/setup.sh)

Bugs de integración con Cognee — ya resueltos en la rig

Estos 5 puntos ya están mitigados en el rig por defecto. Los documentamos para que, si tocás config y algo se rompe, sepas por qué esos ajustes existen.

1. sqlite unable to open database file

Causa: Cognee 1.4 crea SQLite dentro de .cognee_system/databases/. Si el dir no existe cuando se intenta la primera escritura, explota.

Fix aplicado: scripts/setup.sh corre mkdir -p .cognee_system/databases .data en cada bootstrap. Si querés recrearlo:

mkdir -p .cognee_system/databases .data

2. LLMAPIKeyNotSetError aunque COGNEE_LLM_API_KEY esté seteada

Causa: cognee 1.4 lee variables de entorno sin el prefijo COGNEE_ (usa LLM_API_KEY, LLM_MODEL, etc.). Nuestro .env.example usa COGNEE_LLM_* para claridad — pero el runtime lee las otras.

Fix aplicado: en .skills/query_cognee/tool.py (Lesson 05) mapeamos las variables antes de importar cognee:

import os

for prefixed in ("LLM_API_KEY", "LLM_MODEL", "LLM_PROVIDER", "LLM_ENDPOINT",
                 "EMBEDDING_API_KEY", "EMBEDDING_MODEL", "EMBEDDING_PROVIDER",
                 "EMBEDDING_ENDPOINT", "EMBEDDING_DIMENSIONS"):
    val = os.environ.get(f"COGNEE_{prefixed}") or os.environ.get(prefixed)
    if val:
        os.environ[prefixed] = val

Rationale: no tocamos .env (queda declarativo con COGNEE_*); el mapeo se hace en el punto donde importa.

3. 404 Not Found desde OpenRouter cuando cognee genera

Causa: cognee 1.4+ usa litellm internamente. litellm requiere que el modelo tenga formato <provider>/<model>. Como nuestro endpoint es OpenAI-compatible (OpenRouter), el modelo va prefijado con openai/:

❌ anthropic/claude-haiku-4.5      → 404 (litellm no sabe qué provider usar)
✅ openai/anthropic/claude-haiku-4.5 → OK

Fix aplicado: .env.example ya viene con COGNEE_LLM_MODEL=openai/anthropic/claude-haiku-4.5. Verificalo si te da 404.

4. Neo4j Community rechaza CREATE DATABASE

Causa: Cognee 1.4+ intenta crear su propia database. Esa operación requiere Neo4j Enterprise (multi-database) — Community solo tiene la db neo4j default.

Fix aplicado: docker-compose.yml setea:

NEO4J_dbms_databases_default__database: "neo4j"
NEO4J_ENABLE_BACKEND_ACCESS_CONTROL: "false"

Con eso Cognee usa la db default y no intenta crear una nueva.

5. fastembed no instalado → embeddings vía OpenRouter

Causa: la config original usaba EMBEDDING_PROVIDER=fastembed (embeddings offline via sentence-transformers). Requiere el package fastembed que no está en pyproject.toml para mantener la rig chica.

Fix aplicado: .env.example usa EMBEDDING_PROVIDER=openai + text-embedding-3-small (1536 dims) vía OpenRouter.

Gotcha adicional: cognee re-carga .env con override=True al importarse. Si seteás variables de embedding desde Python antes de import cognee, se pisan. Por eso Lesson 05 mapea env vars antes del import pero también reafirma después:

# ANTES de import cognee (setea si no estaba)
_map_env_vars()

import cognee  # ⚠️ acá cognee re-carga .env

# DESPUÉS de import cognee (fuerza override final)
_map_env_vars()

Troubleshooting

uv sync falla en deepagents → confirmá Python 3.12+.

Neo4j Docker no arranca (puerto ocupado) → lsof -i :7687 y matá el proceso, o cambiá el mapeo en docker-compose.yml.

academy cognee status rojo con TCP OK pero no autentica → Neo4j tarda ~20s en aceptar auth después del startup. Esperá y reintentá.

mypy --strict se queja de un import → los stubs de deepagents/cognee/statemachine/pyperclip están en [tool.mypy.overrides] con ignore_missing_imports = true. No toques ese bloque.

Cognee falla en macOS ARM al importar pyarrow → uv add pyarrow --upgrade para forzar wheel ARM64.

No tenés Docker → usá la Ruta B (remoto) o pedile al instructor las credenciales pre-cargadas.

No sé qué modelo de OpenRouter usar → anthropic/claude-haiku-4.5 es el default. Ver alternativas en .env.example.