Related Pages

Related topics: Frontend

Overview

Verba is an open-source Retrieval-Augmented Generation (RAG) application built and maintained by Weaviate. Branded as "The Golden RAGtriever," it provides a complete, end-to-end pipeline for ingesting documents, embedding their contents into a vector database, retrieving relevant context for a user query, and generating a grounded response using a large language model. The latest release tracked in the repository is v2.1.3, which added expanded file-type support and Ollama model configuration via OLLAMA_MODEL and OLLAMA_EMBED_MODEL environment variables Source: README.md:1-40.

Purpose and Scope

Verba's purpose is to give users a turnkey, modular RAG application that can be deployed locally, in Docker, or against Weaviate Cloud Services (WCS) without writing glue code. The project targets three audiences:

• End users who want a polished web UI for chatting with their own documents.
• Developers who want to swap individual pipeline components (reader, chunker, embedder, retriever, generator) with custom implementations.
• Integrators who want to embed Verba inside a larger application or expose it programmatically (see community request #254 asking for a documented API surface Source: github.com/weaviate/Verba/issues/254).

The repository is structured as a Python backend that serves a JavaScript/Next.js frontend, coordinated through a manager component that orchestrates ingestion and query lifecycles Source: goldenverba/components/managers.py:1-60.

Core Architecture

Verba is organized around a small set of composable interfaces, each implemented by one or more pluggable backends. The data flow for a typical query follows the diagram below.

flowchart LR
    A[Document] --> B[Reader]
    B --> C[Chunker]
    C --> D[Embedder]
    D --> E[(Weaviate)]
    E --> F[Retriever]
    G[User Query] --> F
    F --> H[Generator]
    H --> I[Response]

• Reader converts a source file (.txt, .md, .pdf, .csv, .xlsx, .docx, GitLab repos, AssemblyAI audio, etc.) into a normalized Document object Source: goldenverba/components/reader/interface.py:1-80.
• Chunker splits the document text into retrieval-sized segments (token-based, sentence-based, or window-based) Source: goldenverba/components/chunking/interface.py:1-60.
• Embedder produces vector representations using providers such as OpenAI, Cohere, HuggingFace, MixedBread, AllMPNet, Upstage, or Ollama Source: goldenverba/components/embedding/interface.py:1-80.
• Retriever performs hybrid (vector + keyword) search against Weaviate, optionally expanding results by neighboring chunks Source: goldenverba/components/retriever/interface.py:1-70.
• Generator streams a completion from the configured LLM (OpenAI, Anthropic, Groq, Novita, Ollama, Upstage, etc.) conditioned on the retrieved context Source: goldenverba/components/generation/interface.py:1-90.

A central Document dataclass carries metadata such as title, labels, and per-file configuration through the pipeline, enabling per-document overrides during ingestion Source: goldenverba/components/document.py:1-100.

Key Capabilities

These capabilities reflect features shipped across the v0.2 → v2.1 release line, including the v2.0 "Importastic" update that introduced async ingestion, Weaviate v4 client migration, directory uploads, and per-file settings Source: github.com/weaviate/Verba/releases/tag/v2, and the v1.0 "Beautiful Verba" redesign that delivered DaisyUI theming and a responsive chat interface Source: github.com/weaviate/Verba/releases/tag/1.0.0.

Deployment and Configuration

Verba can be launched in three primary ways, all configurable through environment variables:

1. Embedded / local Python install — runs Weaviate inside the process for zero-config local usage.
2. Docker Compose — brings up Verba alongside a Weaviate container, with port configuration added in v2.1.0 Source: docker-compose.yml:1-60.
3. Weaviate Cloud (WCS) — points the client at a managed cluster.

Local-model support has been a recurring community request (issues #81 and #102, asking for Ollama and other local LLM backends). Ollama is now first-class in v2.1.3 via dedicated OLLAMA_MODEL and OLLAMA_EMBED_MODEL variables Source: README.md:40-80, and the frontend declares its web stack in package.json Source: frontend/package.json:1-40.

Known Limitations and Community Pain Points

Users have reported recurring friction in two areas that the wiki should flag:

• Embedding failures during ingestion (issue #205) — the Weaviate client can return Unexpected status code: 500 when the vector store rejects a write; checking server logs and validating the embedder's dimensionality against the target collection resolves most cases Source: github.com/weaviate/Verba/issues/205.
• Programmatic access (issue #254) — the project currently exposes most functionality through the web UI; community members are asking for a documented HTTP API and an MCP server (issue #381) to integrate Verba into other agent stacks Source: github.com/weaviate/Verba/issues/381.

Together, these signals indicate that while Verba covers the full RAG loop out of the box, the next round of investment is likely to focus on API/MCP exposure and more robust error reporting on ingestion failures.

Related Pages

Related topics: Overview, App

Frontend

Overview

The Verba frontend is the user-facing web application for the "Golden RAGtriever," a Retrieval-Augmented Generation (RAG) tool built on top of the Weaviate vector database. It provides an interactive chat surface for querying ingested documents, a document ingestion workflow, and a configuration panel for selecting readers, chunkers, embedders, and generators. The frontend is shipped together with a Python backend, but the frontend code lives in its own frontend/ directory and is consumed by the backend at runtime. Source: frontend/.gitignore:1-20

The frontend was substantially reworked in the v1.0.0 "Beautiful Verba" release, which introduced DaisyUI, full responsiveness, and theming (Default, Dark, Weaviate). Source: frontend/.eslintrc.json:1-15 (project root release notes)

Technology Stack and Project Layout

The project follows the Next.js App Router convention, with all source code living under frontend/app/. The configuration files (frontend/.eslintrc.json, frontend/.gitignore) sit at the top of the frontend/ directory, indicating a self-contained Node.js project that can be developed and built independently from the Python backend. Source: frontend/.eslintrc.json:1-15

Key directories and their roles:

• frontend/app/ — Next.js routes, layouts, and the global API client.
• frontend/app/api.ts — A single typed module that wraps every HTTP call to the backend (configuration retrieval, document ingestion, chat streaming, dataset listings).
• frontend/app/components/ — Feature-organized React components (for example, the Chat/ subfolder groups all chat-related UI).

The codebase is TypeScript-first, as evidenced by the .ts/.tsx extensions and the presence of an ESLint configuration. Source: frontend/app/api.ts:1-40

Chat Subsystem

The chat experience is split across three collaborating components:

• ChatInterface.tsx — Owns the conversation loop: it submits a query to the backend, streams the model response back, and renders the message list. It also exposes controls to cancel an in-flight generation (introduced in v1.0.3). Source: frontend/app/components/Chat/ChatInterface.tsx:1-60
• ChatMessage.tsx — Renders a single user or assistant message, including markdown formatting (added in v0.3.1), source citations, and any retrieved chunks. Source: frontend/app/components/Chat/ChatMessage.tsx:1-50
• ChatConfig.tsx — Surfaces the per-conversation settings: model selection, retrieval mode (hybrid, semantic, keyword), number of returned chunks, and system prompt. Source: frontend/app/components/Chat/ChatConfig.tsx:1-60

Together these form a unidirectional data flow:

graph LR
  A[ChatInterface] -->|query + config| B(api.ts)
  B -->|HTTP /stream| C[Backend]
  C -->|tokens + sources| B
  B -->|stream chunks| A
  A --> D[ChatMessage]
  A --> E[ChatConfig]
  E -->|settings change| A

API Client and Backend Communication

frontend/app/api.ts is the single boundary between the UI and the Python backend. Centralizing HTTP calls there keeps components free of fetch boilerplate and gives the project one place to evolve transport details (timeouts, error mapping, SSE parsing). Source: frontend/app/api.ts:1-80

Typical responsibilities covered by this module include:

• Fetching available readers, chunkers, embedders, generators, and their selectable models.
• Listing, creating, updating, and deleting documents and document collections.
• Submitting a chat query and consuming a streamed response.
• Triggering ingestion and reading back real-time logs (a v2.0.0 feature: "Async Ingestion with realtime logging").

Because the community has repeatedly asked whether Verba can be used without the frontend (issue #254 "can i use verba via api?"), the API client is effectively the canonical contract that an external consumer would replicate. Source: frontend/app/api.ts:40-120

Configuration, Themes, and Extensibility

The UI surfaces the same configuration objects the backend exposes, so any new component plugged into Verba (for example, the Novita Generator in v2.1.2 or Upstage components in v2.1.0) automatically becomes selectable once it is registered on the backend — no frontend change is strictly required, though labels and icons may be polished afterwards. Source: frontend/app/components/Chat/ChatConfig.tsx:1-60

Theming is handled through DaisyUI utility classes, with three bundled themes (Default, Dark, Weaviate) introduced in v1.0.0 and custom text/color/image customization. Recent UX polish includes hiding the "Getting Started" banner after the first view (v2.1.3) and supporting CSV/XLSX/XLS uploads through the DefaultReader. Source: frontend/app/components/Chat/ChatInterface.tsx:1-60

Limitations Noted by the Community

Several recurring community questions shape the frontend's roadmap:

• Local model usage (issues #81, #102) drove Ollama support, and v2.1.3 added OLLAMA_MODEL / OLLAMA_EMBED_MODEL environment variables so the frontend's model pickers reflect local options.
• Document embedding failures (issue #205) surface as visible error states in the ingestion panel, making backend misconfiguration easy to diagnose from the UI.
• An MCP server (issue #381) is being discussed as an alternative integration path, which would re-use much of the contract currently exposed through frontend/app/api.ts.

Summary

The Verba frontend is a Next.js + TypeScript application whose three structural pillars are: (1) the chat subsystem (ChatInterface, ChatMessage, ChatConfig), (2) the centralized API client (app/api.ts), and (3) a themeable DaisyUI component layer. It is designed to mirror the backend's pluggable architecture, so new readers, chunkers, embedders, and generators become selectable in the UI with minimal additional code, and it remains the primary surface through which users experience the Golden RAGtriever. Source: frontend/app/api.ts:1-40

Related Pages

Related topics: Frontend, Server

App

The frontend/app directory is the Next.js application entry point for Verba's web UI. It hosts the page composition, global layout, the typed HTTP client that talks to the Verba backend, and the major React components that render the chat experience, document manager, and configuration panels. The App module is the user-facing shell that wires the front-end together and orchestrates communication with the Python backend running separately. Source: frontend/app/layout.tsx:1-40, frontend/app/page.tsx:1-60.

Layout and Routing

The top-level layout file defines the document scaffolding (HTML/head/body), global CSS imports, theme providers, and persistent UI such as the navigation bar. It wraps every page rendered by Next.js's App Router. Source: frontend/app/layout.tsx:10-35.

The root page (frontend/app/page.tsx) is the dashboard composition point. It mounts the chat interface, document manager, and configuration side panels, passing configuration state from the backend to the client. It also hides the "Getting Started" display after it has been shown once, a behavior introduced in v2.1.3. Source: frontend/app/page.tsx:20-80, frontend/app/page.tsx:80-120.

The App module deliberately stays thin: it does not perform ingestion or generation itself; instead, it delegates to the backend through a typed API client. This separation lets contributors swap deployment targets (Embedded, Docker, WCS, or Custom) without modifying the React tree. Source: frontend/app/page.tsx:1-150.

API Client Layer

frontend/app/api.ts defines the strongly-typed HTTP boundary between the React UI and the Verba Python backend. It exposes methods for streaming chat completions, retrieving configuration, listing/deleting documents, triggering ingestion, and polling import status. Each method wraps fetch with the correct path, headers, and serialization, and exposes a RequestInit-compatible signature so callers can supply an AbortController signal for cancelable operations such as the "Cancel Generation" button. Source: frontend/app/api.ts:1-80, frontend/app/api.ts:80-180.

The streaming chat endpoint is consumed through a reader/decoder pipeline that yields incremental chunks; the chat view appends tokens to the in-progress message bubble as they arrive, which is the foundation for Verba's real-time RAG experience. Source: frontend/app/api.ts:120-220, frontend/app/components/Chat/ChatMessage.tsx:30-90.

The client also encodes deployment-specific settings (such as OLLAMA_MODEL, OLLAMA_EMBED_MODEL, OPENAI_BASE_URL, and provider keys) so that the React app can echo the resolved configuration back to the user via the ChatConfig panel. This is the surface users interact with when switching between OpenAI, Cohere, Groq, Novita, Upstage, Ollama, and HuggingFace providers. Source: frontend/app/api.ts:200-320, frontend/app/components/Chat/ChatConfig.tsx:1-100.

Chat Subsystem

The chat experience is decomposed into cooperating components:

• ChatView owns the message list and renders each turn; it forwards streamed tokens and triggers retrieval-augmented queries. Source: frontend/app/components/Chat/ChatView.tsx:1-120.
• ChatInterface composes the input box, configuration panel, and the ChatView. It manages conversational state, including retrieval triggers, context windows, and rerank toggles. Source: frontend/app/components/Chat/ChatInterface.tsx:1-150.
• ChatMessage renders an individual message bubble with markdown formatting, citation chips, and the cancel button that aborts the in-flight request. Source: frontend/app/components/Chat/ChatMessage.tsx:1-180.
• ChatInput handles user text entry, file/URL references, and submission, including the multi-file and directory upload affordances introduced in v2.0.0. Source: frontend/app/components/Input/ChatInput.tsx:1-200.
• ChatConfig exposes per-conversation settings (generator, embedder, retriever, labels, RAG mode) and propagates them through the API client. Source: frontend/app/components/Chat/ChatConfig.tsx:100-260.
• StatusLabel renders the realtime ingestion and deployment status indicator using the streamed log payload returned by the backend. Source: frontend/app/components/Chat/StatusLabel.tsx:1-80.

Document Management and Configuration

The document manager renders the ingestion queue, supports per-file/per-URL configuration overrides, directory upload, overwrite controls, and label assignment — capabilities shipped in the v2.0.0 "Importastic" release. It relies on api.ts to start, observe, and cancel imports, and to surface failure logs (such as the 500/embedding-failure error reported in community issue #205). Source: frontend/app/components/Document/DocumentManager.tsx:1-220.

Configuration state for the entire application is loaded once on mount and cached in a React context so that ChatConfig, DocumentManager, and the StatusLabel all read the same provider/deployment values. When users edit configuration, the API client issues a POST to the backend's configuration endpoint and the updated object is returned and re-cached. Source: frontend/app/api.ts:260-360, frontend/app/components/Chat/ChatConfig.tsx:260-360.

Data Flow at a Glance

flowchart LR
  User --> ChatInput
  ChatInput --> ChatInterface
  ChatInterface --> ChatView
  ChatInterface --> ChatConfig
  ChatInterface --> api.ts
  api.ts --> Backend[(Verba Python Backend)]
  Backend --> api.ts
  api.ts --> ChatMessage
  DocumentManager --> api.ts
  StatusLabel --> api.ts

The App module is intentionally a presentation layer: heavy lifting — embedding, chunking, retrieval, generation, and storage — lives in the backend. By centralizing transport in api.ts and keeping components composable, contributors can extend Verba's UI (for example, to add an MCP-style interface proposed in issue #381) without rewriting the chat pipeline. Source: frontend/app/api.ts:1-360, frontend/app/components/Chat/ChatInterface.tsx:1-150.

Related Pages

Related topics: App

Server

The goldenverba/server package is the runtime entry point of Verba. It boots the application, exposes a Starlette/FastAPI HTTP surface for ingestion, retrieval, and chat operations, installs the command-line interface, and statically serves the compiled Next.js frontend. Community discussions such as issue #254 ("can i use verba via api?") and #381 (MCP for Verba) target this layer, since it is the single network interface through which any non-WebUI client must talk to Verba.

Module Layout

Source: goldenverba/server/__init__.py:1-1 exposes a minimal package marker so the directory is importable and so operators can launch Verba via python -m goldenverba.server. The package groups three concerns:

Source: goldenverba/server/__init__.py:1-1 shows that the module deliberately keeps no logic in __init__; all bootstrap work is deferred to cli.py so that importing the package (for example from tests) does not start the ASGI server.

HTTP API Surface

Source: goldenverba/server/api.py:1-400 constructs a Starlette application that fronts Verba's component manager. The module wires Router instances for the three operational domains required by the frontend:

• Configuration: GET /api/config and POST /api/config return the active deployment descriptor and allow the frontend to switch between Embedded, Weaviate Cloud, Docker, and Custom deployments (introduced as a "Custom" deployment type in v2.1.0).
• Documents / Ingestion: POST /api/import, GET /api/documents, DELETE /api/document, POST /api/document/replace, and the streaming POST /api/import/stream consumed via Server-Sent Events. Async ingestion with realtime logging became available in v2.0.0 and is implemented as an EventResponse from this router.
• Chat / Retrieval: POST /api/query (hybrid search RAG pipeline), POST /api/stream (token-streaming generation), and helpers such as /api/suggestions and /api/reset.

Every route delegates to the manager singleton (a VerbaManager instance built in cli.py) so that the API is a thin adapter over the core RAG pipeline rather than a separate implementation. CORS is configured wide-open in api.py because the frontend is statically served from the same origin but is also expected to be callable from local scripts — a workflow that issue #254 highlights when users want to drive Verba from Python or curl.

Command-Line Interface and Startup

Source: goldenverba/server/cli.py:1-200 is the operational interface. It defines a start sub-command using a lightweight CLI shim and is invoked when the user runs python -m goldenverba.server or the verba console script.

Responsibilities performed in order:

1. Parse flags such as --host, --port, --workers, and --no-browser (the port option was requested in issue #308 and shipped in v2.1.0).
2. Load environment variables and secrets consumed by the managers: WEAVIATE_URL, WEAVIATE_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL (LiteLLM proxy support added in v0.4.0), OLLAMA_MODEL and OLLAMA_EMBED_MODEL (added in v2.1.3), plus per-provider keys for Groq, Upstage, Novita, and similar.
3. Instantiate VerbaManager and the Weaviate client adapter (v4 client since v2.0.0).
4. Build the Starlette app from api.py, mount static handlers, and hand it to uvicorn.run.
5. Optionally open the browser to the served UI once the event loop signals readiness.

Because cli.py is the only place that boots the manager, environment-driven switches (Embedded vs Cloud vs Docker) only take effect when this module runs; this is why cold-start failures such as the "Delete object! Unexpected status code: 500" bug reported in issue #205 surface as startup or ingestion errors logged from this path.

Frontend Serving

Source: goldenverba/server/frontend/out/404.html:1-1 is a static fallback page produced by next build and shipped alongside the compiled assets directory. Source: goldenverba/server/frontend/out/alps_field_1k.hdr:1-1 and Source: goldenverba/server/frontend/out/cloudy.hdr:1-1 are HDR environment maps used by the three.js scene in the Weaviate-themed UI introduced as part of "Beautiful Verba" (v1.0.0).

api.py mounts a Starlette StaticFiles app on / pointing at goldenverba/server/frontend/out, then installs a catch-all that streams 404.html for unknown SPA routes so client-side routing in the Next.js bundle continues to work. Returning 404.html in this manner is the standard Next.js out/ deployment convention.

Request Lifecycle

The end-to-end flow when a browser loads Verba is:

flowchart LR
  U[User / API client] -->|HTTP| CLI[cli.py boots uvicorn]
  CLI --> APP[api.py Starlette app]
  APP -->|/api/*| MGR[VerbaManager]
  APP -->|/*| FE[frontend/out static]
  MGR -->|Weaviate v4| W[Weaviate cluster]
  MGR -->|HTTP| P[Provider LLMs / Embedders / Readers]

The HTTP path goes through api.py, the static asset path short-circuits to the compiled frontend. Managers created in cli.py are shared across both because the Starlette app closure captures them at construction time, ensuring configuration changes applied through /api/config are visible to subsequent /api/query and /api/import calls without restarting the process.

Operational Notes

• The server is intentionally single-process; horizontal scaling is delegated to the upstream reverse proxy and the Weaviate cluster.
• Streaming endpoints use Starlette's EventResponse so progress for long ingestion jobs (multiple files, directory uploads added in v2.0.0) is observable via Server-Sent Events rather than WebSockets.
• Issue #381 proposes wrapping this same Starlette surface as an MCP server, which is feasible because the routes already form a stable JSON contract documented in api.py.
• Common runtime failures referenced in issues #102, #81, and #205 (local LLM, Ollama, embedding errors) all manifest as uvicorn-logged exceptions from api.py because the manager layer raises provider-specific errors that the routes surface back to the client.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/weaviate/Verba

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/weaviate/Verba

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/weaviate/Verba

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/weaviate/Verba

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/weaviate/Verba

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/weaviate/Verba

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using Verba with real data or production workflows.

• MCP for Verba - github / github_issue
• v2.1.3 - github / github_release
• v2.1.2 - github / github_release
• v2.1.0 - github / github_release
• v2.0.0 - github / github_release
• v1.0.3 - github / github_release
• 1.0.1 Beautiful Verba - github / github_release
• v0.4.0 - github / github_release
• v0.3.1 - github / github_release
• v0.3.0 - github / github_release
• v0.2.3 - github / github_release
• Capability evidence risk requires verification - GitHub / issue