EigenVertex guide: WikiLLM, Retrieval, and Graph-LLM

Get Started

Recommended first workflow

Start with one clean workspace and a small but representative corpus. The first decision is not “which clever question should I ask?” It is “should this workspace behave like a persistent wiki or like a retrieval engine?” Once that is clear, the rest of the system becomes much easier to operate and explain.

1. Choose the workspace mode first: WikiLLM for durable memory, Retrieval for broad document recall.
2. Create one clean workspace for one topic, client, project, or research corpus.
3. Import a small but representative set of documents before scaling the corpus.
4. Process documents so EigenVertex extracts text, OCR, transcription, and semantic metadata.
5. If the workspace is Retrieval, chunk and index the corpus for lexical, vector, and graph search.
6. If the workspace is WikiLLM, let the backend compile source, topic, entity, and concept pages.
7. Use Chat only after the workspace has become readable: wiki pages for WikiLLM, indexed evidence for Retrieval.
8. Run wiki lint and maintain in WikiLLM, or inspect evidence quality in Retrieval, before large-scale usage.

Workspace Modes

Choose the mode before you ingest

A workspace now has a primary mode. This is not a cosmetic setting. It decides how ingestion, query, maintenance, and the console itself should behave.

Product Architecture

The three strategies

EigenVertex should not be described as a single “RAG stack”. It exposes three distinct strategies with different jobs.

Ingestion

Supported source types and ingestion flow

EigenVertex is designed for heterogeneous corpora. The same product can ingest written documents, media, expert notes, and generated artifacts while preserving provenance.

Search & Chat

Chat options only make sense inside the right mode

The console should not present the same controls everywhere. WikiLLM and Retrieval do not have the same knobs.

Retrieval strategies

Speed profile

Fast

API usage, product flows, and quick checks. Keeps the path short and grounded. In WikiLLM it means concise wiki synthesis. In Retrieval it means a shorter evidence path with lower orchestration cost.

Balanced

Default human chat and most serious corpus questions. The normal “work carefully” profile. It preserves grounding while allowing a fuller synthesis path and better coverage.

Thorough

Ambiguous, comparative, or high-value research questions. Expands coverage and depth. Use it when latency matters less than reading breadth, comparison quality, and reasoning depth.

Answer behavior

Grounded (`strict` in API)

Audits, compliance, factual checks, and corpus-only answers. The model should stay inside the retrieved or compiled evidence. If the workspace cannot support an answer, it should say so.

RAG (`research` in API)

Serious Q&A, exploration, and synthesis. The answer can derive a fuller synthesis from the evidence, including assumptions, limitations, and follow-up questions, while staying grounded.

Builder (`build` in API)

Code, algorithms, protocols, implementation planning, and constructive outputs. The model may propose concrete artifacts guided by the workspace, clearly separating what is supported from what is derived.

Native API

Use EigenVertex as an application backend

The native API is the richest integration surface. Use it when you need workspaces, documents, connectors, ingestion status, SSE progress, conversations, wiki maintenance, or retrieval controls.

Create a workspace with an explicit mode

export EVTX_BASE_URL="https://api.eigenvertex.com"
export EVTX_API_KEY="evtx_..."

curl -X POST "$EVTX_BASE_URL/v1/workspaces" \
  -H "Authorization: Bearer $EVTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Piano Research",
    "slug": "piano-research",
    "visibility": "private",
    "workspace_mode": "wiki_llm"
  }'

WikiLLM chat turn

curl -X POST "$EVTX_BASE_URL/v1/conversations/CONVERSATION_ID/chat-turn" \
  -H "Authorization: Bearer $EVTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize EigenVertex in five points.",
    "include_sources": true,
    "save_messages": true,
    "query_profile": "fast",
    "answer_mode": "research"
  }'

Retrieval chat turn

curl -X POST "$EVTX_BASE_URL/v1/conversations/CONVERSATION_ID/chat-turn" \
  -H "Authorization: Bearer $EVTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Quels algorithmes sont robustes pour détecter la f0 du piano ?",
    "top_k": 8,
    "include_sources": true,
    "save_messages": true,
    "query_profile": "balanced",
    "answer_mode": "research",
    "retrieval_strategy": "vector",
    "retrieval_layers": ["vector"]
  }'

Wiki lint and maintain

curl -X POST "$EVTX_BASE_URL/v1/wiki/workspaces/WORKSPACE_ID/lint" \
  -H "Authorization: Bearer $EVTX_API_KEY" \
  -H "Content-Type: application/json"

curl -X POST "$EVTX_BASE_URL/v1/wiki/workspaces/WORKSPACE_ID/maintain" \
  -H "Authorization: Bearer $EVTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apply_safe_fixes": true
  }'

Python client example

import os
import requests

base_url = os.environ["EVTX_BASE_URL"]
api_key = os.environ["EVTX_API_KEY"]

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

payload = {
    "question": "Compare YIN, SWIPE and parametric methods for piano f0 detection.",
    "top_k": 10,
    "include_sources": True,
    "query_profile": "balanced",
    "answer_mode": "research",
    "retrieval_strategy": "vector",
    "retrieval_layers": ["vector"],
}

response = requests.post(
    f"{base_url}/v1/conversations/{os.environ['EVTX_CONVERSATION_ID']}/chat-turn",
    headers=headers,
    json=payload,
    timeout=120,
)
response.raise_for_status()

data = response.json()
print(data["assistant_message"]["content"])
print(data["query_result"]["diagnostics"])

TypeScript client example

type QueryProfile = "fast" | "balanced" | "thorough";
type AnswerMode = "strict" | "research" | "build";
type RetrievalStrategy = "vector" | "graph";

export async function askEigenVertex(params: {
  baseUrl: string;
  apiKey: string;
  conversationId: string;
  question: string;
  profile?: QueryProfile;
  mode?: AnswerMode;
  retrieval?: RetrievalStrategy;
}) {
  const response = await fetch(
    `${params.baseUrl}/v1/conversations/${params.conversationId}/chat-turn`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${params.apiKey}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        question: params.question,
        top_k: 8,
        include_sources: true,
        save_messages: true,
        query_profile: params.profile ?? "fast",
        answer_mode: params.mode ?? "research",
        retrieval_strategy: params.retrieval ?? "vector",
        retrieval_layers: [params.retrieval ?? "vector"]
      })
    }
  );

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}

OpenAI-compatible API

Consume EigenVertex like a model when that is easier

The OpenAI-compatible facade is useful when an existing application already uses OpenAI SDKs. The request still reaches EigenVertex, but the client can speak the familiar /v1/chat/completions or /v1/responses language.

from openai import OpenAI

client = OpenAI(
    api_key="evtx_...",
    base_url="https://api.eigenvertex.com/v1",
)

response = client.chat.completions.create(
    model="eigenvertex-grounded",
    messages=[
        {"role": "system", "content": "Answer in French with citations when available."},
        {"role": "user", "content": "What does the corpus say about tuning stability?"}
    ],
    extra_body={
        "eigenvertex": {
            "workspace_id": "WORKSPACE_ID",
            "include_sources": True,
            "answer_mode": "research",
            "query_profile": "balanced"
        }
    }
)

print(response.choices[0].message.content)
print(response.model_extra.get("eigenvertex"))

Operations

What to monitor and maintain

EigenVertex exposes operational surfaces because large or valuable corpora are never “fire and forget”. The exact maintenance shape depends on the workspace mode.

Ingestion SSE

Watch active documents, current steps, progress percent, and recent workspace updates.

WikiLLM operations

Run lint to diagnose the wiki and maintain to apply safe repairs. This is where AGENTS.md, index.md, log.md, provenance, cross-links, and contradiction notes are kept healthy.

Retrieval evidence quality

Inspect chunking, index readiness, and citation quality. Retrieval workspaces depend on the evidence layer staying readable and trustworthy.

Deletion and cleanup

Workspace and document deletion must clean database rows, object storage, wiki pages, and retrieval artifacts according to the workspace mode.

Authors and provenance

When available, authors and provenance should be preserved and displayed. This matters especially for scientific corpora where the value of a claim depends on who made it and where.

Deployment Models

Cloud EigenVertex now, on-prem path next

The production posture is to keep the backend stateless and keep Postgres, Qdrant, and S3-compatible storage as separate services. This keeps cloud and self-hosted deployment cleaner and makes the split between WikiLLM and Retrieval easier to operate.

APP_ENV=production
APP_REQUIRE_API_KEY=true
APP_CORS_ALLOW_ORIGINS=https://labs.eigenvertex.com

DATABASE_URL=postgresql+psycopg://eigenvertex:***@postgres:5432/eigenvertex
QDRANT_URL=http://qdrant:6333
S3_ENDPOINT_URL=http://minio:9000
S3_BUCKET=eigenvertex-documents

OPENAI_API_KEY=...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
LLAMA_API_KEY=...