---
title: Ask the Oracle
description: How the in-site AI assistant works — RAG over the docs, served by your own Ollama on neuronetz.ai.
---

The amber button in the corner of every page is the **Nibiru Oracle** — an AI assistant grounded in this very documentation. Ask it about routing, modules, the CLI, the Smarty layer, the meaning of `pageAction()`. It cites its sources.

## What's powering it

By default, the Oracle runs entirely on **your own infrastructure**:

| Layer | Backend | Default model |
|---|---|---|
| Chat (answer generation) | Ollama on `https://api.neuronetz.ai` | `qwen2.5-coder:14b` |
| Embeddings (RAG retrieval) | Ollama on `https://api.neuronetz.ai` | `nomic-embed-text` |

No paid API keys. No data leaves your network. The 5-GPU Ollama cluster you already run handles the load.

If you'd rather use a paid provider — Claude for chat, OpenAI for embeddings — set `LLM_PROVIDER=anthropic` and/or `EMBED_PROVIDER=openai` plus the matching API keys. The code paths are identical.

## How it works

```mermaid
flowchart LR
  A[User question] --> B[Embed via Ollama<br/>nomic-embed-text]
  B --> C[Cosine search<br/>against pre-computed<br/>doc-chunk index]
  C --> D[Top-K chunks]
  D --> E[Ollama chat<br/>qwen2.5-coder:14b<br/>system + retrieved context]
  E --> F[Answer + source list]
  F --> G[Render in chat UI]
```

1. **At build time**, the docs site walks every Markdown page, splits it into ~600-token chunks at H2/H3 boundaries, embeds each chunk with `nomic-embed-text`, and writes the result to `public/oracle-index.json`. No database needed.
2. **At request time**, the user's question is embedded the same way, the closest chunks are retrieved by cosine similarity, and they're stitched into a system prompt for the chat model.
3. **The chat model answers** in the user's language, citing source chunks by URL.

## Files

| File | Purpose |
|---|---|
| `scripts/lib/providers.mjs` | Shared chat + embedding adapter (Ollama / Anthropic / OpenAI). |
| `scripts/build-oracle-index.mjs` | Builds `public/oracle-index.json` at build time. |
| `public/oracle-index.json` | The committed/build-output embedding index. |
| `src/pages/api/oracle.ts` | The SSR endpoint the chat widget POSTs to. Also serves a GET for diagnostics. |
| `src/components/CosmicHeader.astro` | The floating launcher + chat UI. |

## One-time setup on neuronetz.ai

Pull the two models the Oracle uses:

```bash
curl https://api.neuronetz.ai/api/pull -d '{"name":"qwen2.5-coder:14b"}'
curl https://api.neuronetz.ai/api/pull -d '{"name":"nomic-embed-text"}'
```

`qwen2.5-coder:14b` is already installed (verified live). `nomic-embed-text` is the missing piece; without it the Oracle runs in chat-only (no-RAG) mode.

## Configuring it

The Oracle reads its config from environment variables. Sensible defaults are baked in.

```bash
# Default mode (Ollama on neuronetz.ai)
LLM_PROVIDER=ollama                                 # default
OLLAMA_BASE_URL=https://api.neuronetz.ai            # default
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b                 # default
OLLAMA_EMBED_MODEL=nomic-embed-text                 # default

# Optional fallbacks
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-haiku-4-5-20251001

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_EMBED_MODEL=text-embedding-3-small

# Behaviour
ORACLE_TOP_K=6
ORACLE_MAX_TOKENS=800
```

## Diagnostics endpoint

`GET /api/oracle` returns the current config (no secrets):

```bash
curl https://nibiru-framework.com/api/oracle
{
  "status": "ok",
  "llm":   { "provider": "ollama", "ollamaUrl": "https://api.neuronetz.ai",
             "model": "qwen2.5-coder:14b" },
  "embed": { "provider": "ollama", "ollamaUrl": "https://api.neuronetz.ai",
             "model": "nomic-embed-text" },
  "index": { "present": true, "chunks": 177,
             "provider": "ollama", "model": "nomic-embed-text" }
}
```

Handy for verifying a freshly-deployed container is using the backend you expected.

## Privacy

- Questions and conversation history are sent to your Ollama server. They are **not** stored by the docs site or by Anthropic/OpenAI in the default Ollama config.
- The OpenAI key (if used) is invoked only for embeddings.
- No analytics or cookies are set by the Oracle widget itself.

## Why a Nibiru-trained model?

The roadmap (see [AI Roadmap](/en/ai/roadmap/)) is to fine-tune a LoRA on the [Training Corpus](/en/ai/corpus/) export so the chat model itself is Nibiru-native. When that's ready, the Oracle's `OLLAMA_CHAT_MODEL` flips to the fine-tuned model and the system prompt simplifies. Same code, smarter answers.

## Try it

Open the Oracle (the amber planet, bottom-right) and try one of these:

- *"How do I create a new module?"*
- *"What does `pageAction` do?"*
- *"Show me how to handle a JSON endpoint."*
- *"Wie schreibe ich eine Migration?"* (German works.)
- *"認証フローを教えて"* (Japanese works.)
