How gkatenin/wiki-rag works
Purpose and execution
This repository is a minimal Go command-line RAG pipeline for retrieving Wikipedia content and producing an LLM-generated answer. The executable entry point is main.go; users provide -query and optional -lang flags. The system is designed around on-demand retrieval rather than a persistent corpus or web service.
CLI orchestration
main.go owns the top-level control flow: validate input, fetch a relevant Wikipedia article, chunk/index its text, retrieve context for the query, then pass that context to an LLM reader. It is the integration boundary between command-line input and the retrieval/generation stages.
• main.go
Wikipedia acquisition boundary
Wikipedia access is isolated in wiki.go. This layer uses Go HTTP facilities to search/fetch article material for a selected language, keeping remote Wikipedia interaction separate from retrieval and inference logic. It is the primary external network dependency.
• wiki.go
• main.go
Document preparation
Article content is divided into overlapping character-based chunks before indexing. Overlap preserves neighboring context across chunk boundaries, which is important because retrieved chunks become the prompt evidence supplied to generation. Shared text/chunk handling is likely centralized in utility code.
• utils.go
• wiki.go
Retrieval and ranking
bm25.go implements lexical relevance scoring for the fetched article chunks. This is the core retrieval stage: the query is compared against chunk content, and the strongest passages are selected as grounded context. The repository’s RAG scope is therefore per-request and per-article, rather than a durable multi-document index.
• bm25.go
• main.go
Embedding and model runtime
The project depends on github.com/kelindar/search for semantic search/embedding capabilities and uses GGUF-compatible BERT-style models through llama.cpp bindings backed by purego, avoiding cgo. Model loading and inference-facing integration are represented by the LLM reader layer, with dependency versions pinned in Go modules.
• llm-reader.go
• go.mod
• go.sum
Context-to-answer generation
llm-reader.go forms the generation boundary: it receives selected context plus the original query and invokes the local model runtime to produce the final answer printed by the CLI. Retrieval output should be treated as untrusted remote text; generation behavior, prompt construction, and model availability are operationally dependent on local GGUF model assets/runtime support.
• llm-reader.go
• main.go
Key flow and operational boundaries
Control flow is: CLI flags → Wikipedia HTTP retrieval → article chunking → BM25/semantic ranking → top-context assembly → local LLM answer output. External services are Wikipedia over HTTP; inference is local through llama.cpp/GGUF rather than a hosted model API. The Go binary is portable in principle, but execution materially requires a compatible local embedding/generation model and the native runtime access expected by the search dependency.
Main entry points: main.go RAG command · wiki.go Wikipedia client · llm-reader.go LLM reader · bm25.go BM25 ranker
Components 12
CLI orchestration
- User query · Query and optional language flags.
- RAG command · Coordinates fetch, retrieval, and answer output.
main.go - Answer output
On-demand retrieval
- Wikipedia client · Searches and fetches article material for the selected language.
wiki.go - Article chunker · Creates overlapping character-based chunks.
utils.go - BM25 ranker · Scores article chunks against the query.
bm25.go - Top context · Selected passages from the fetched article.
Local inference
- LLM reader · Builds a prompt from query and retrieved context, then generates an answer.
llm-reader.go - GGUF model assets · Compatible embedding and generation models are required at runtime.
- llama.cpp runtime · GGUF-compatible model access through purego bindings.
- Search dependency · Provides embedding and semantic-search capabilities.
go.mod
Other components
- Wikipedia
Connections 14
- User query → RAG command: -query, -lang
- RAG command → Wikipedia client: fetch article
- Wikipedia client → Wikipedia: HTTP search/fetch
- Wikipedia → Wikipedia client: article text
- Wikipedia client → Article chunker: article content
- Article chunker → BM25 ranker: overlapping chunks
- RAG command → BM25 ranker: query
- BM25 ranker → Top context: ranked passages
- RAG command → LLM reader: query and context
- Top context → LLM reader: grounding evidence
- LLM reader → llama.cpp runtime: inference request
- GGUF model assets → llama.cpp runtime: loads GGUF models
- Search dependency → llama.cpp runtime: purego-backed access
- LLM reader → Answer output: generated answer