Integrating HybridRAG into agent code generator

[natarajan-chidambaram]

A PR was created in WME to include HybridRAG in the frontend. This is for the backend generator to include HybridRAG if the user selects it. Also, added comments in the agent template to inform the user about use_ui and file uploading when generating from RAG.

[ArmenSl]

Reviewed this alongside its frontend halves (WME #177 and #179). The load-bearing parts are correct — I checked the risky ones against the actual besser-agentic-framework 4.5.1 wheel rather than assuming, and the generated code will run:

• from baf.nlp.rag.rag import RAG, HybridRAG — correct path, HybridRAG(RAG) is there.
• The constructor is compatible. HybridRAG.__init__(self, *args, bm25_docs=None, bm25_weight=0.6, **kwargs) captures bm25_weight keyword-only and forwards the rest to RAG.__init__, which takes agent, vector_store, splitter, llm_name, llm_prompt, k, num_previous_messages. All eight kwargs the template emits land correctly.
• Omitting bm25_docs is fine, which was my main worry: HybridRAG overrides load_pdfs to call super().load_pdfs() then _sync_bm25(), which rebuilds the ensemble from the vector store. So the construct-then-load_pdfs order the template emits does activate BM25.
• rank_bm25 is only in BAF's optional extras, but the generated readme.txt already tells users pip install besser-agentic-framework[all], which includes it — and the BM25 import is guarded with a warning rather than a hard failure. Non-issue.

Four things worth addressing.

The reverse converter isn't here. agent_model_builder.py now writes use_hybrid_rag= and bm25_weight= into the generated B-UML, but buml_to_json/agent_diagram_converter.py isn't in this PR — its new_rag(...) parser only pulls out name, llm_name and llm_prompt. So export a HybridRAG agent to B-UML, re-import it in the editor, and the setting is silently gone. In fairness this extends an existing gap rather than creating one — k and num_previous_messages are already lost the same way — but this PR is the moment the field becomes user-visible, so it's the natural time to close it.

No tests. tests/utilities/web_modeling_editor/backend/services/converters/test_agent_converter_roundtrip.py already has the pattern in test_agent_roundtrip_preserves_ollama_llm_and_embedding, which round-trips a RAG and asserts its vector-store parameters survive. An equivalent test asserting use_hybrid_rag / bm25_weight survive would have caught the point above, which is a good argument for adding it.

bm25_weight is unbounded. BAF documents it as 0–1 and computes the vector weight as 1 − bm25_weight, so a value above 1 produces a negative vector weight and below 0 a negative BM25 weight. Nothing in the metamodel, the converter, or the template bounds it. RAG has no validation on any field, so I'm not calling this a convention break — but the consequence is concrete enough to be worth a clamp somewhere, most cheaply in agent_diagram_processor.py right where the value is already being coerced with float().

One of the new comments is slightly off. # Place your documents (PDF, TXT, etc.) in the './{{ rag_slug }}' folder before running. — load_pdfs() filters on file.endswith('.pdf'), so a .txt dropped in that folder is silently ignored. Since the whole point of the comment is to save users a confusing debugging session, it'd be worth saying PDFs only. The use_ui comment is accurate, and both are a genuinely nice addition.

On docs: docs/source/buml_language/model_types/agent.rst describes RAG in prose without enumerating parameters, so leaving bm25_weight undocumented is consistent with how that page works. But HybridRAG is a distinct capability rather than a parameter, and as it stands there's no way for a reader to discover it exists — a sentence in that section would be enough.

Two things I looked at and deliberately am not flagging: the new metamodel attributes are plain public fields with no property/setter, but every existing RAG field is the same, and the getattr(rag, 'use_hybrid_rag', False) in the code builder matches the llm_prompt line directly above it. Both follow local convention.

Merge order: this needs to land before WME #177, which needs to land before WME #179 — #179's template switches HybridRAG on by default, and #177's deserialize() whitelists fields explicitly, so out of order the setting is silently dropped rather than erroring.