Ejecútalo Localmente

El sitio de documentación — y el Oracle que vive en la esquina — es simplemente una aplicación de Astro. Puedes ejecutarlo de tres formas dependiendo de lo que tengas a mano.

Opción A — Servidor de desarrollo Astro, backend your Ollama instance (más rápido)

El Oracle llama a tu Ollama compartida en https://your-ollama-host.example. No se necesita un GPU local ni claves de API para gestionar.

cd /home/stephan/PhpstormProjects/Nibiru/docs

# .env (copy from .env.example, defaults already point at your Ollama instance)
cp .env.example .env

npm install      # one-time
npm run dev      # http://localhost:4321

Abre http://localhost:4321/. Haz clic en el lanzador amarillo de Oracle en la esquina inferior derecha y pregunta lo que quieras.

Extraiga el modelo de incrustación una vez en su host Ollama (en tiempo de construcción + en tiempo de ejecución):

curl https://your-ollama-host.example/api/pull -d '{"name":"nomic-embed-text"}'

Sin él, el Oracle sigue funcionando — solo que en modo de chat solamente (sin RAG) y responde basándose en el conocimiento paramétrico del modelo. Con él, las respuestas están respaldadas por esta documentación.

Construye el índice de embeddings

npm run build:oracle    # writes public/oracle-index.json

El servidor de desarrollo lo detectará en la próxima solicitud. O omite este paso por completo — el punto final de tiempo de ejecución maneja una índice ausente o vacío con gracia.

Inspecciona la configuración en tiempo de ejecución

El punto final /api/oracle del Oracle también responde a GET con su configuración actual (sin secretos):

curl http://localhost:4321/api/oracle
# {"status":"ok","llm":{"provider":"ollama","ollamaUrl":"https://your-ollama-host.example",
#  "model":"qwen2.5-coder:14b"},"embed":{...},"index":{...}}

Opción B — Docker Compose, localmente

Más cerca de la producción. Construye la misma imagen que desplegarías.

cd /home/stephan/PhpstormProjects/Nibiru/docs
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build

El docker-compose.local.yml override:

• Publica 4321:4321 para que la aplicación sea accesible en http://localhost:4321/.
• Elimina las variables de entorno VIRTUAL_HOST / LETSENCRYPT_HOST.
• No necesita una red nginx-proxy en tu máquina de desarrollo.

El primer build tarda 1-2 minutos. Las reconstrucciones posteriores son rápidas (Docker almacena en caché la capa de dependencias).

Opción C — Totalmente sin conexión, Ollama local

Para desarrollo sin conexión, demostraciones en avión o quemando tu propia GPU.

# 1) Run Ollama on your laptop
ollama serve &

# 2) Pull a chat model (any of these works)
ollama pull qwen2.5-coder:14b      # 8 GB, recommended
# ollama pull qwen2.5-coder:1.5b   # 1 GB, faster but less accurate
# ollama pull llama3.2:3b          # 2 GB, alternative

# 3) Pull an embedding model
ollama pull nomic-embed-text

# 4) Point the docs at it
cd /home/stephan/PhpstormProjects/Nibiru/docs
cat > .env <<EOF
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b
OLLAMA_EMBED_MODEL=nomic-embed-text
EOF

npm run build:oracle
npm run dev

Ahora http://localhost:4321/api/oracle llama a tu portátil Ollama. No se requiere internet.

Cambiar a Anthropic / OpenAI (si lo deseas)

El Oracle admite API pagadas como alternativa. En .env:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...

Útil si tu Ollama está caído o para comparar la calidad de las respuestas entre proveedores.

Hoja de referencia para pruebas de humo

curl http://localhost:4321/                                    # 301 → /en/
curl -I http://localhost:4321/en/                              # 200
curl http://localhost:4321/api/oracle                          # GET = config
curl -X POST -H 'Content-Type: application/json' \
     -d '{"messages":[{"role":"user","content":"How do I create a module?"}]}' \
     http://localhost:4321/api/oracle | jq .answer

Si la última llamada devuelve una respuesta real que menciona ./nibiru -m, tu pila está configurada correctamente.

Solución de problemas

Oracle devuelve “el Oracle no pudo responder”. El servidor de Ollama no es accesible o el modelo de chat no está extraído. Verifique:```bash curl https://your-ollama-host.example/api/tags | jq ‘.models[].name’

**Oracle responde sin citas.**
El índice de incrustación está vacío. Vuelve a ejecutar `npm run build:oracle` después de extraer `nomic-embed-text`.

**Ollama devuelve 404 modelo-no-encontrado.**
Extrae el modelo, por ejemplo:```bash
curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'

ECONNREFUSED 127.0.0.1:11434 en la opción C. El Ollama local no está ejecutándose. Inícielo con ollama serve & (o a través de su servicio del sistema).