FAQ

Does core include a vector database or embedding model?

No. RAGSystem orchestrates a caller-supplied vector_db, llm, chunker, and context_manager. See Dependencies for the exact interface each must implement.

Why did generate() return "❌ There was an error: ..." instead of raising?

By design. RAGSystem.generate()/agenerate() never raise — all internal exceptions are caught and converted into a returned error string, so a single bad query never crashes a request-handling loop. See the generate() algorithm for the exact catch/return logic. If you need exceptions, call retrieve() directly instead — it does raise RAGRetrievalError.

Why do add_documents() and aadd_documents() accept different argument shapes?

This is a real inconsistency in the analyzed source: the synchronous RAGSystem.add_documents(docs: List[LoadedDocument]) expects a list of LoadedDocument objects, while RAGSystem.aadd_documents(docs: Dict[str, str]) expects a plain {doc_id: text} dict. See the warning in the async API reference — this is documented as-observed, not as an intended design.

Why did my document's doc_id collide with another document's?

LoadedDocument.__post_init__ auto-generates an ID from an MD5 hash of the content plus a second-resolution timestamp. Two documents with identical content created in the same second get the same auto-generated ID. Always pass an explicit doc_id if uniqueness matters. See LoadedDocument.

Why is my entire retrieval cache empty right after I added one new document?

RAGSystem.add_documents() clears the retrieval cache in full on every successful ingestion call, regardless of whether the new content is related to any cached query. See Cookbook: avoiding cache-clearing storms.

How do I make reranking use my LLM instead of just heuristics?

config = RAGConfig(enable_reranking=True, rerank_mode="llm")  # or "hybrid"
rag = RAGSystem(vector_db=..., llm=your_llm, chunker=..., context_manager=..., config=config)

If llm were None, Reranker would silently downgrade to heuristic mode — see the constructor warning.

Does query expansion work without an LLM?

Yes — QueryExpander falls back to a curated Arabic/English synonym table (synonm_table.py) when no LLM is supplied or when the LLM call fails. See QueryExpander.expand.

Can I use DocumentVersionManager with a standalone core package?

Only partially. add_or_update() performs a deferred import of LoadedDocument using the absolute path zerda.rag.core.rag_system, which requires core to be installed as part of the zerda.rag namespace. See the availability note.

Is core thread-safe?

Partially. RetrievalCache is fully thread-safe (RLock-protected). stats dict mutation on BaseRAGSystem/RAGSystem has no locking. See the thread-safety notes on the BaseRAGSystem and RAGSystem pages.

What languages does the library support?

Arabic and English are explicitly handled throughout — language detection (with several slightly different thresholds/algorithms depending on the module — see Troubleshooting), bilingual prompt templates, few-shot examples, and the synonym table. No other languages have dedicated handling in the analyzed source; non-Arabic, non-English text is generally treated as English by the various "any Arabic character?" / "Arabic character ratio" checks.

Where can I find the exact list of RAGAS-style metrics computed by RAGEvaluator?

See evaluation API reference — faithfulness, answer relevancy, context precision, context recall, and answer correctness.