ZerdaZerda

Architecture

On this page

It then attempts two additional, best-effort import blocks wrapped in try/except ImportError: pass:

Python · 9 lines
try:
    from zerda.rag.core.evaluation import RAGEvaluator, EvalSample, EvalResult, EvalReport, MetricScore
except ImportError:
    pass

try:
    from zerda.rag.core.document_versioning import DocumentVersionManager, DocVersion, ContentDiff
except ImportError:
    pass

[!NOTE] Why this matters If evaluation.py or document_versioning (or one of their imports) fails to import for any reason, core as a whole will still import successfully — but RAGEvaluator/DocumentVersionManager and friends will silently be unavailable from the top-level core namespace. Note that RAGConfig is imported from base_rag_system, which itself imports it from rag_config — both import paths resolve to the same class.

Module dependency graph

This graph reflects only the intra-package from .module import ... statements found in the source.

evaluation and document_versioning are notably standalone — neither imports anything else from core at module load time. document_versioning.py only reaches into rag_system via a deferred, function-local import inside DocumentVersionManager.add_or_update():

Python
from zerda.rag.core.rag_system import LoadedDocument

This import uses the installed package path (zerda.rag.core), not a relative import — meaning DocumentVersionManager.add_or_update() will only work correctly when core is installed as part of the zerda.rag package tree, not when used as a bare top-level core.

Class relationships

RAGConfig and RerankerConfig are not linked by inheritance or composition in the source — RAGSystem.__init__ manually copies rerank_* fields from RAGConfig into a fresh RerankerConfig instance when constructing the Reranker (see RAGSystem internals).

End-to-end request flow (generate / ask)

If retrieve() finds no chunks, generate() short-circuits and returns a "No relevant information found." message without calling the LLM (see RAGSystem.generate).

Ingestion flow (add_documents)

Extension points

Based on the abstract methods and duck-typed interfaces in the source, core exposes these extension points:

Extension pointHowWhere
Custom RAG pipelineSubclass BaseRAGSystem and implement add_documents, retrieve, generatebase_rag_system.py
Custom vector databaseProvide any object with .add(chunks) / .search(query, top_k, score_threshold) (optionally .remove_by_doc_id, .save, .load, .size, .aadd, .asearch)RAGSystem dependencies
Custom LLMProvide any object with .generate(prompt, **kwargs) -> str (optionally .generate_async, .astream)RAGSystem dependencies
Custom chunkerProvide any object with .chunk_text(text, doc_id) or .chunk(text, doc_id)RAGSystem dependencies
Custom context builderProvide any object with .build(query, chunks) -> strRAGSystem dependencies
Custom promptPass a PromptTemplate-like object (.format(context=..., question=...)), a callable (context, query) -> str, or a raw format string to RAGSystem(prompt=...) / set_prompt()RAGSystem._resolve_prompt
Custom reranking weightsConfigure RerankerConfig / the rerank_* fields on RAGConfigRAGConfig, Reranker

What is not in this codebase

To avoid inventing functionality, note explicitly what the analyzed source does not contain:

  • No REST or WebSocket API layer.
  • No CLI commands.
  • No database ORM models.
  • No plugin/entry-point discovery system.
  • No built-in vector database, embedding model, or LLM client implementation — these are caller-supplied dependencies.
  • No background worker/scheduler.

Related pages