Getting Started

This guide covers:

Admin workflow: create and maintain knowledge bases, validate via chat, and monitor the system.
Developer/operator setup: environment variables, URLs/base paths, and common troubleshooting.

1) Where to Go in the UI

Admin UI

Knowledge bases: /admin/knowledge-bases
Sessions: /admin/sessions
Tracing: /admin/tracing
Dashboard: /admin/dashboard

AI Chat UI

Chat home: /ai-chat
KB-scoped chat: /ai-chat/{kb_id}

Documentation

Docs home: /docs

2) Typical Admin Workflow (End-to-End)

Step A — Create a Knowledge Base

Go to Knowledge Bases and create a new KB using one of the supported modes:

URL ingestion (common): provide a source URL, optional name/description, optional ingestion preset.
File upload (if enabled): upload a file and create a KB from it.

What to expect:

The KB is created immediately, but content ingestion happens in the background.
The KB status changes over time (queued → scraping → indexing → ready).

Step B — Wait Until the KB Is Ready

KBs move through statuses such as:

queued: waiting to start
scraping: fetching/extracting content
indexing: chunking/embedding content
ready: retrieval + chat are available
failed: a processing error occurred

Operational rule:

Treat ready as the only safe state for serious chat testing.

Step C — Review Documents

Open the KB detail page to:

confirm documents were ingested
preview content (sanity-check extraction)
delete or re-add problematic documents

Step D — Configure the KB

Typical configuration fields include:

display name + description
language (affects UI direction and sometimes processing defaults)
theme color + icon
source visibility in chat (show/hide citations)

Step E — Test in AI Chat

Test from:

the KB list “Chat” action, or
/ai-chat/{kb_id} directly

During testing:

ask simple “can it find the content?” questions first
verify sources/citations are correct (if enabled)
only then move to harder queries

Step F — Review Sessions and Traces

Use:

Sessions to review stored conversations (questions, answers, feedback, sources).
Tracing for deeper debugging (retrieval details, timing, scores, pipeline steps).

3) Developer / Operator Setup

Environment variables

The UI and scripts commonly rely on:

APP_NAME
API_BASE_URL
WEB_HOST

Important distinction:

API_BASE_URL is for API fetch calls.
Templates should use /admin/... and /static/... for navigation and assets.

Rule of thumb:

In templates, use /static/... for scripts/styles/images.
In templates, use /admin/... for admin links.
In JavaScript, use window.API_BASE_URL when building API endpoints.

If you suspect the rule is violated:

Open browser DevTools → Network.
Click a sidebar item.
If you see navigation to a different origin/port and lots of asset downloads, the page is being built with the wrong base.

There is client-side admin navigation support in frontend/static/js/admin-navigation.js.

It is opt-in via the <html> attribute data-admin-ajax-nav="true".
When enabled, sidebar clicks can be intercepted to load only <main> content via fetch().

Tradeoffs:

Faster perceived navigation after first load.
Requires careful page reinitialization (some pages rely on DOMContentLoaded).

If you enable it, test every admin page thoroughly.

4) Common Gotchas

“Ready” but answers look wrong

Typical causes:

content extraction was poor (document preview shows junk or missing sections)
KB language is mismatched (RTL vs LTR UI confusion)
sources are hidden (appears “ungrounded” when citations would clarify)

Recommended checks:

open KB detail → preview a couple of documents
run 2–3 “obvious” queries and verify retrieval
check traces for retrieved chunks

“Chat” works but is slow