How bigdatawirtz/semanticsearch works
This repo is a single-process Python web app that provides:
• Document ingestion: upload JSON documents via a Gradio UI
• Vector indexing + retrieval: store embeddings in ChromaDB (in-memory)
• Semantic search: query → retrieve most relevant document(s)
• Optional RAG QA: send the question + retrieved JSON to a local Ollama server (http://localhost:11434) to generate an answer
Key architectural implication called out by the README: everything is in RAM and disappears when the app stops (no persistent DB volume unless you add one).
File structure to architectural components
From the tree:
• semanticsearch.py
The entire app: Gradio UI + upload handling + validation + embedding + ChromaDB indexing + retrieval + (optional) Ollama call.
• samples/*.json
• requirements.txt
• Dockerfile
Deployment mode: app can run locally or inside a container, exposing 7860.
Gradio Web Server / UI Layer
• Tabs: upload + search (per README)
• Accepts files and queries, displays results
Upload & JSON Validation
• Ensures JSON is valid (explicit feature)
• Parses JSON into a canonical text/string representation used for embeddings + display
Embedding / Vectorization Component
• Takes JSON (or extracted text) and produces embeddings
ChromaDB (In-Memory Vector Store)
• Stores document embeddings + metadata
• Supports similarity search
• Important annotation: ephemeral / RAM-only
Retrieval / Ranking
• Executes semantic query against ChromaDB
• Returns top-k document(s) (README implies “most relevant document” for RAG)
RAG Prompt Builder (Context Assembler)
• Builds a context payload: question + retrieved JSON doc
• This is a distinct logical step even if it’s just a few lines in code
Ollama Client
• HTTP call to Ollama server (http://localhost:11434)
• Default model per README: llama3.3 (include as a label/annotation)
External service boundary
• Ollama Server (Local LLM Runtime)
• Exposes HTTP API on 11434
• Generates answer conditioned on provided context
Deployment boundary (optional but recommended)
• Docker Container running the Python app, exposing 7860
• In Docker mode, Ollama may be:
• Outside the container on the host (common), requiring host networking or host.docker.internal-style access
UI / app
• Browser → Gradio App: HTTP :7860
(Upload JSON, submit search query, ask QA)
Ollama Server → Ollama Client → Gradio UI: answer text
• Single-process, modular internal components: UI + indexing + retrieval + LLM call all in one Python runtime.
• Ephemeral state: ChromaDB in-memory store; no persistence.
• RAG pattern: retrieve → augment prompt → generate.
• Local-first / offline-ish: relies on local Ollama, not a hosted LLM (important boundary condition).
Explicit annotations:
• “Vector DB = RAM-only; reset on restart”
• “Ollama dependency: must be running at localhost:11434”
• “App exposed at localhost:7860”
Show:
• User browser
• Docker container OR local Python process (two variants or a note)
• Ollama server
• Ports 7860 and 11434
This answers: “What runs where and how does it connect?”
• Gradio UI
• Validation/Parser
• Embedding
• ChromaDB
• Retrieval
• Prompt Builder
• Ollama client
This answers: “What are the main responsibilities and boundaries inside semanticsearch.py?”
Two sequences are enough:
• Upload → index
• Ask question → retrieve → (optional) Ollama generation
This answers: “In what order do calls happen and what data moves?”
Diagramming conventions (make it “principal-engineer grade”)
Elements explicitly:
Clear labels
• component name
• key tech (e.g., “Gradio”, “ChromaDB”)
• statefulness (“in-memory”)
• Ports/protocol where relevant: HTTP :7860, HTTP :11434
Don’t overthink granularity—split aggressively
Even if semanticsearch.py is one file, represent each responsibility as a separate component. This matches the project’s real conceptual architecture and makes future refactors obvious (e.g., extracting retrieval, storage, LLM client into modules).