Architecture

``

Each subsystem is import-isolated: none of the ten packages import from one another. They are designed to be composed manually by the consuming application (e.g. a DomainSpecificRAG can itself be passed as rag_system into a FederatedRAG source, since DomainSpecificRAG.query() and FederatedRAG._call_generate()'s duck-typing are compatible in shape).

Shared design pattern: the decorator/wrapper backend

Every module follows the same structural idea — it does not implement retrieval or generation itself. It receives an already-built rag_system (or vector_db + llm pair) in its constructor and layers new behavior around calls to that object's retrieve()/generate() (or query()) methods.

Common lifecycle across subsystems

Most subsystems expose a synchronous method (query, ask, or generate) and an async twin (aquery, aask, astream) that either delegates to the sync path in a thread or reimplements the same steps with await. The typical request lifecycle is:

Recurring implementation motifs

These patterns appear, nearly verbatim, across independent modules — useful to know because bugs or behaviors fixed in one place often exist in the others too:

• Heterogeneous document normalisation. Nearly every module has a _normalise_doc(s) / _retrieve_safe helper that accepts documents as dict, (text, score) tuple, (text, score, meta) tuple, or a raw object, and converts them to one dict shape. See agentic_rag.agentic_rag.AgenticRAG._normalise_docs, self_improving_rag.self_improving_rag._retrieve_safe, and streaming_rag.streaming_rag.StreamingRAG._normalise_doc.
• TTL caching. agentic_rag.cache.TTLCache and federated_rag.federat_cache.TTLCache are two independent, near-identical implementations of a SHA-256-or-tuple-keyed, time-boxed in-memory cache.
• Retry with exponential backoff. AgenticRAG._retrieve_with_retry, FederatedRAG._query_source, and self_improving_rag._call_llm each retry a flaky call a configurable number of times with a growing delay.
• Async context manager support. __aenter__/__aexit__ are defined on AgenticRAG, FederatedRAG, ConversationalRAG, DomainSpecificRAG, GraphRAG, MultiDocumentRAGSystem, MultiHopRAG, and SelfIRAG, allowing async with X(...) as x: usage, though none of the __aexit__ implementations shown perform explicit teardown work beyond returning.
• Bilingual (Arabic/English) prompt construction. Several modules (domain_rag, conversational_rag, multi_hop, streaming_rag) build prompts that instruct the LLM to answer in the same language as the question, with Arabic (ar) as the default language throughout.

Class relationship overview (representative subsystem: Agentic RAG)

Continue to the per-subsystem breakdowns in the API Reference.