Skip to content

Quick Start

This guide walks you through the core workflow: start the app, create a notebook, upload a document, and get your first AI-powered answer with citations.

Step 0: Start the App

If you haven't already started the services:

cd beyond-retrieval-pythonv
cp .env.example .env          # defaults to fully self-hosted (local Supabase)
python start_services.py --profile cpu --build

See Installation for details on profiles and configuration.

Step 1: Open the Dashboard

Navigate to your Beyond Retrieval instance:

If authentication is bypassed (default in dev), you land directly on the Dashboard.

Step 2: Create a Notebook

  1. Click Create Notebook on the Dashboard.
  2. Fill in:
  3. Title — e.g., "Product Docs"
  4. Embedding Model — select text-embedding-3-small (recommended)
  5. Click Create.

Embedding Model is Permanent

The embedding model is locked after notebook creation. All documents in the notebook must share the same vector space. Choose carefully.

Step 3: Upload Documents

  1. Open your new notebook and navigate to the Documents page.
  2. Drag and drop files onto the upload area, or click to browse.
  3. Supported formats: PDF, DOCX, TXT, MD, CSV, XLSX.
  4. After uploading, click Ingest to start the processing pipeline.

The pipeline runs in the background:

Upload → Parse (Docling/Mistral OCR) → Chunk → Embed → Store in pgvector

Watch the status column — it progresses from Pending → Processing → Success.

Step 4: Ask a Question

  1. Navigate to the Chat page.
  2. Click + New Chat to create a conversation.
  3. Type your question, e.g.: "What is the cancellation policy?"
  4. Press Enter.

The RAG pipeline searches your documents, retrieves relevant chunks, and generates a cited answer:

According to the documents [1], the cancellation policy requires...

Click on citation numbers to see the source text.

Step 5: Explore

Now that you have a working notebook, explore the other features:

Feature What to Try
Search Playground Compare Fusion vs Semantic search on the same query
AI Enhancer Enrich document chunks with AI-generated context
Intelligence Settings Switch between OpenRouter, OpenAI, or Ollama
System Monitor Check the health score of your knowledge base

Using the API

You can also interact with Beyond Retrieval programmatically. Here's a complete example using Python:

import httpx

BASE = "http://localhost:8000/api"

# 1. Create a notebook
nb = httpx.post(f"{BASE}/notebooks/", json={
    "title": "My API Notebook",
    "embedding_model": "openai/text-embedding-3-small"
}).json()["data"]

notebook_id = nb["notebook_id"]
print(f"Created notebook: {notebook_id}")

# 2. Upload a file
with open("document.pdf", "rb") as f:
    upload = httpx.post(
        f"{BASE}/notebooks/{notebook_id}/documents/upload",
        files={"files": ("document.pdf", f, "application/pdf")}
    ).json()["data"]

file_info = upload[0]
print(f"Uploaded: {file_info['file_name']}")

# 3. Start ingestion
httpx.post(f"{BASE}/notebooks/{notebook_id}/documents/ingest", json={
    "files": [file_info],
    "settings": {
        "parser": "Docling Parser",
        "chunking_strategy": "Recursive Chunking",
        "chunk_size": 1000,
        "chunk_overlap": 200
    },
    "notebook_name": "My API Notebook"
})

# 4. Wait for ingestion, then create a conversation
import time
time.sleep(10)  # Wait for background processing

conv = httpx.post(f"{BASE}/notebooks/{notebook_id}/conversations", json={
    "title": "First Chat"
}).json()["data"]

# 5. Ask a question
response = httpx.post(
    f"{BASE}/notebooks/{notebook_id}/conversations/{conv['conversation_id']}/messages",
    json={"content": "What are the main topics in this document?"}
).json()["data"]

print(response["assistant_message"]["content"])

See the API Reference for the complete endpoint catalog.

Next Steps