# ragbuilder - Doramagic AI Context Pack > Positioning: a pre-install experience and judgment asset. It helps the host AI get off to a good start, but it does not mean the project has already been installed, run, or validated. ## Sufficiency Principle - **Sufficiency over compression**: The AI Context Pack should be sufficient for the host AI to understand the project's value, capability boundaries, entrypoints, risks, and evidence sources before starting work; it may be layered, but it does not aim for the shortest possible summary. - **Compression policy**: Compress only noise and duplication, never context that affects judgment or the quality of the work. ## How the Host AI Should Use This You are reading the AI Context Pack that Doramagic compiled for ragbuilder. Treat it as pre-work context: help the user understand who it fits, what it can do, how to start, what must be verified after install, and where the risks are. Do not claim that you have already installed, run, or executed the target project. ## Claim Consumption Rules - **Fact source**: Repo Evidence + Claim/Evidence Graph; the Human Wiki only supplies salience, terminology, and narrative structure. - **Minimum status for a fact**: `supported` - `supported`: May be used as a project fact, but the answer must cite the claim_id and evidence path. - `weak`: Usable only as a low-confidence lead; the user must be asked to keep verifying. - `inferred`: Usable only for risk notes or open questions; must not be packaged as a project fact. - `unverified`: Must not be used as fact; state clearly that evidence is insufficient. - `contradicted`: Must show the conflicting sources and must not force a single version on the user's behalf. ## Who It Fits Best - **Users who want to understand an open-source project's value and boundaries before installing**: Current evidence comes mainly from project documentation. Evidence: `README.md` Claim: `clm_0002` supported 0.86 ## What It Can Do - **Command-Line Startup or Install Flow** (Verify after install): The project documentation contains runnable commands; real use requires running them in a local or host environment. Evidence: `install.sh` Claim: `clm_0001` supported 0.86 ## How to Start - `curl -fsSL https://raw.githubusercontent.com/KruxAI/ragbuilder/main/Brewfile -o Brewfile` Evidence: `install.sh` Claim: `clm_0003` supported 0.86 ## Continue-or-Stop Decision Card - **Current recommendation**: Needs admin / security approval - **Why**: Continuing may involve secrets, accounts, external services, or sensitive context; get admin or security approval first. ### 30-Second Read - **What to do now**: Needs admin / security approval - **Minimum safe next step**: Run Prompt Preview first; if credentials or an enterprise environment are involved, get approval before trialing - **Do not trust yet**: Real output quality cannot be trusted before install. - **Continuing will touch**: Command execution, Local environment or project files, Environment variables / API keys ### What You Can Trust Now - **Target-audience signal: Users who want to understand an open-source project's value and boundaries before installing** (supported): Backed by a supported claim or project evidence, but that still is not the same as real install results. Evidence: `README.md` Claim: `clm_0002` supported 0.86 - **Capability exists: Command-Line Startup or Install Flow** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `install.sh` Claim: `clm_0001` supported 0.86 - **There are Quick Start / install-command signals** (supported): You can trust that the docs mention a startup or install entrypoint; do not run it directly in your primary environment because of that. Evidence: `install.sh` Claim: `clm_0003` supported 0.86 ### What You Cannot Trust Yet - **Real output quality cannot be trusted before install.** (unverified): Prompt Preview can only show how it guides you; it cannot prove result quality in the real project. - **Host AI version compatibility cannot be trusted before install.** (unverified): Host loading rules and version differences across Claude, Cursor, Codex, Gemini, and others must be verified in a real environment. - **That it will not pollute your existing host AI's behavior cannot be trusted directly.** (inferred): Skill, plugin, and AGENTS/CLAUDE/GEMINI instructions may change the host AI's default behavior. - **Safe rollback cannot be assumed by default.** (unverified): Unless the project clearly provides uninstall and recovery instructions, verify in an isolated environment first. - **After a real install, is it compatible with the user's current host AI version?** (unverified): Compatibility can only be verified in the actual host environment. - **Does the project's output quality meet the user's specific task?** (unverified): The pre-install preview can only show flow and boundaries; it cannot replace real evaluation. - **Do the install commands require network access, permissions, or global writes?** (unverified): This affects install risk in both enterprise and personal environments. Evidence: `install.sh` ### What Continuing Will Touch - **Command execution**: Package managers, network downloads, the local plugin directory, project config, or the user's home directory. Why: Running the very first command can already change your environment; decide whether it is worth running first. Evidence: `install.sh` - **Local environment or project files**: Install results, plugin caches, project config, or local dependency directories. Why: The write scope and rollback path cannot be proven before install and need isolated verification. Evidence: `install.sh` - **Environment variables / API keys**: Project entry docs explicitly showing API key, token, secret, or account credential configuration. Why: If a real install needs credentials, use test credentials first and go through a permission/compliance review. Evidence: `README.md`, `src/ragbuilder/langchain_module/embedding_model/embedding.py`, `src/ragbuilder/langchain_module/llms/llmConfig.py`, `src/ragbuilder/langchain_module/retriever/retriever.py` - **Host AI context**: The AI Context Pack, Prompt Preview, Skill routing, risk rules, and project facts. Why: Importing context affects the host AI's later judgment, so avoid packaging unverified items as facts. ### Minimum Safe Next Steps - **Run Prompt Preview first**: Use a pre-install interactive trial to judge whether the way of working fits; it needs no authorization or environment change. (applies when: Applies to any project, especially when output quality is unknown.) - **Trial-install only in an isolated directory or a test account**: Avoid letting install commands pollute your primary host AI, real projects, or home directory. (applies when: When there are signals of command execution, plugin config, or local writes.) - **Do not use real production credentials**: Once an environment variable / API key enters the host or toolchain, it can create account and compliance risk. (applies when: When environment signals like API, TOKEN, KEY, or SECRET appear.) - **After install, verify just one minimal task**: Verify loading, compatibility, output quality, and rollback first, then decide whether to use it deeply. (applies when: When moving from a trial into a real workflow.) ### Exit Plan - **Preserve the pre-install state**: Record the original host config and project state so you can later judge whether it is recoverable. - **Record the install commands and written paths**: Without clear uninstall instructions, you at least need to know which directories or configs to clean up manually. - **Be ready to revoke test API keys or tokens**: If test credentials leak or are misused, you can cut losses quickly. - **If there is no rollback path, do not enter your primary environment**: No rollback is a blocker before continuing; do not proceed on trust or luck. ## What Can Only Be Previewed - Explain who the project fits and what it can do - Demonstrate a typical conversation flow based on project docs - Help the user decide whether it is worth installing or researching further ## What Must Be Verified After Install - Actually installing the Skill, plugin, or CLI - Running scripts, modifying local files, or accessing external services - Verifying real output quality, performance, and compatibility ## Boundary & Risk Decision Card - **Mistaking the pre-install preview for a real run**: The user may overestimate how much configuration, permission, and compatibility verification the project has already done. Mitigation: Clearly separate prompt_preview_can_do from runtime_required. Claim: `clm_0004` inferred 0.45 - **Command execution will modify the local environment**: Install commands may write to the user's home directory, the host plugin directory, or project configuration. Mitigation: Run in an isolated environment or a test account first. Evidence: `install.sh` Claim: `clm_0005` supported 0.86 - **To confirm**: After a real install, is it compatible with the user's current host AI version?. Why: Compatibility can only be verified in the actual host environment. - **To confirm**: Does the project's output quality meet the user's specific task?. Why: The pre-install preview can only show flow and boundaries; it cannot replace real evaluation. - **To confirm**: Do the install commands require network access, permissions, or global writes?. Why: This affects install risk in both enterprise and personal environments. ## Pre-Work Working Context ### Loading Order - First read how_to_use.host_ai_instruction to establish the boundaries of this pre-install judgment asset. - Read claim_graph_summary to confirm facts come from the Claim/Evidence Graph, not the Human Wiki narrative. - Then read intended_users, capabilities, and quick_start_candidates to judge whether the user is a match. - When you need to carry out a concrete task, check role_skill_index first, then evidence_index. - For real install, file modification, network access, performance, or compatibility questions, turn to risk_card and boundaries.runtime_required. ### Task Routes - **Command-Line Startup or Install Flow**: State that this is an after-install capability first, then give a pre-install checklist. Boundary: Must be verified after a real install or run. Evidence: `install.sh` Claim: `clm_0001` supported 0.86 ### Context Scale - Total files: 377 - Important-file coverage: 40/377 - Evidence index entries: 57 - Role / Skill entries: 1 ### Handling Insufficient Evidence - **missing_evidence**: State that evidence is insufficient and ask the user for the target file, a README section, or after-install verification records; do not fill in facts. - **out_of_scope_request**: State that the task is beyond the current AI Context Pack's evidence scope and suggest the user check the Human Manual or verify after a real install. - **runtime_request**: Provide a pre-install checklist and command sources, but do not run commands for the user or claim they have been run. - **source_conflict**: Show the conflicting sources side by side, mark them as unverified, and do not force a single version. ## Prompt Recipes ### Fit assessment - Goal: Judge whether this project fits the user's current task. - Expected output: A fit conclusion, key reasons, evidence citations, what can be previewed before install, what must be verified after install, and a next-step recommendation. ```text Based on the AI Context Pack for ragbuilder, ask me 3 necessary questions first, then judge whether it fits my task. The answer must cover: who it fits, what it can do, what it cannot do, whether it is worth installing, and where the evidence comes from. Every project fact must cite evidence_refs, source_paths, or a claim_id. ``` ### Pre-install experience - Goal: Let the user feel the core workflow before installing, while avoiding packaging the preview as real capability or a marketing promise. - Expected output: An experience script with boundary labels, an after-install verification checklist, and a cautious recommendation; with no real-run promises or strong marketing language. ```text Treat ragbuilder as a pre-install experience asset, not an already-installed tool or a real runtime environment. Output exactly four parts: 1. Ask me 3 necessary questions first. 2. Give an "experience script": use the three labels [Previewable before install], [Must verify after install], and [Insufficient evidence] to show how it might guide the workflow. 3. Give an after-install verification checklist: list which capabilities can only be confirmed after a real install, real host loading, and a real project run. 4. Give a cautious recommendation: only "worth researching/trialing further", "add information before deciding", or "not recommended to continue"; do not endorse the project. Hard boundaries: - Do not claim you have installed, run, executed tests, modified files, or produced real results. - Do not write promise-like phrasing such as "auto-adapts", "guarantees passing", "perfect fit", or "strongly recommend installing". - If you describe how it works after install, you must use a conditional such as "if installed successfully and the host loads the Skill correctly, it might...". - The experience script may only be written as "example lines / hypothetical flow": use "might ask / might suggest / might show", not "has written, has generated, has passed, is running, is generating". - Prompt Preview does not hand out install commands; if the user is ready to trial, only prompt them to read Quick Start and the Risk Card first and to verify in an isolated environment. - Every project fact must come from a supported claim, evidence_refs, or source_paths; inferred/unverified items can only be risks or open questions. ``` ### Role / Skill selection - Goal: Pick the best-matching asset from the project's roles or Skills. - Expected output: A list of candidate roles or Skills, each with an applicable scenario, evidence paths, risk boundary, and whether after-install verification is needed. ```text Read role_skill_index and recommend 3-5 of the most relevant roles or Skills for my target task. For each recommendation, state the applicable scenario, likely output, risk boundary, and evidence_refs. ``` ### Risk pre-check - Goal: Identify environment, permission, rule-conflict, and quality risks before installing or adopting. - Expected output: A checklist of environment, permission, dependency, license, host-conflict, quality risk, and unknown items. ```text Based on risk_card, boundaries, and quick_start_candidates, give me a pre-install risk pre-check list. Do not run commands for me; only explain what I should check, why, and what impact a failure would have. ``` ### Host AI kickoff instruction - Goal: Turn the project context into a host AI instruction for the start of a conversation. - Expected output: A pre-work instruction with clear boundaries and clear evidence citations, suitable to copy to a host AI. ```text Based on the AI Context Pack for ragbuilder, generate a pre-work instruction I can paste to my host AI. This instruction must obey not_runtime=true and must not claim the project has been installed, run, or produced real results. ``` ## Role / Skill Index - Indexed 1 role / Skill / project-doc entries. - **Readme** (project_doc): ! RagBuilder logo ./assets/ragbuilder dark.png gh-dark-mode-only ! RagBuilder logo ./assets/ragbuilder light.png gh-light-mode-only Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `README.md` ## Evidence Index - Indexed 57 evidence entries. - **Readme** (documentation): ! RagBuilder logo ./assets/ragbuilder dark.png gh-dark-mode-only ! RagBuilder logo ./assets/ragbuilder light.png gh-light-mode-only Evidence: `README.md` - **License** (source_file): Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ Evidence: `LICENSE` - **Init** (source_file): module dir = os.path.dirname file ⋮---- module name = filename :-3 Evidence: `byor/__init__.py` - **Docker Compose** (source_file): version: "3.8" services: neo4j: build: ./neo4j ports: - "7474:7474" - "7687:7687" environment: NEO4J AUTH: "neo4j/ragbuilder" NEO4J apoc export file enabled: "true" NEO4J apoc import file enabled: "true" NEO4J apoc import file use neo4j config: "true" NEO4J dbms security procedures unrestricted: "apoc. " volumes: - ./data:/data networks: - custom-network ragbuilder: image: ashwinzyx/ragbuilder:latest ports: - "55003:8005" volumes: - .:/ragbuilder env file: - .env depends on: - neo4j command: "ragbuilder" networks: - custom-network networks: custom-network: driver: bridge Evidence: `docker-compose.yml` - **Install** (source_file): echo Installing RagBuilder setlocal EnableDelayedExpansion Evidence: `install.bat` - **Install** (source_file): set -e echo "Downloading Brewfile..." curl -fsSL https://raw.githubusercontent.com/KruxAI/ragbuilder/main/Brewfile -o Brewfile echo "Installing Homebrew packages..." brew bundle install --file=Brewfile echo "Installing ragbuilder..." python3 -m pip install ragbuilder echo "Setup completed successfully." Evidence: `install.sh` - **Optional dependencies** (source_file): project name = "ragbuilder" dynamic = "version" description = "RagBuilder SDK - Create optimal Production-ready RAG pipelines" authors = {name = "Ashwin Aravind", email = "ashwin@krux.ai"}, {name = "Aravind Parameswaran", email = "aravind@krux.ai"}, requires-python = " =3.7" readme = "README.md" license = {text = "Apache-2.0"} Evidence: `pyproject.toml` - **Init** (source_file): version = "unknown version" ⋮---- all = 'RAGBuilder', ' version ' Evidence: `src/ragbuilder/__init__.py` - **Init** (source_file): all = Evidence: `src/ragbuilder/config/__init__.py` - **Base** (source_file): class LLMConfig BaseModel ⋮---- model config = {"protected namespaces": , "arbitrary types allowed": True} ⋮---- type: Optional LLMType = None model kwargs: Optional Dict str, Any = Field default=None, description="Model-specific parameters like model name/type" initialized llm: Optional Union BaseChatModel, BaseLLM = PrivateAttr default=None ⋮---- @property def llm self - Optional Union BaseChatModel, BaseLLM ⋮---- llm class = LLM MAP self.type ⋮---- @classmethod def from llm cls, llm: Union BaseChatModel, BaseLLM - 'LLMConfig' ⋮---- class EmbeddingConfig BaseModel ⋮---- type: Optional EmbeddingType = None model kwargs: Optional Dict str, Any = None custom class: Optional str = None initia… Evidence: `src/ragbuilder/config/base.py` - **Component type definitions** (source_file): @dataclass class PkgSpec ⋮---- install name: str import name: str = "" ⋮---- def post init self ⋮---- def validate self - str ⋮---- Component type definitions class GraphType str, Enum ⋮---- NEO4J = "neo4j" ⋮---- class LLMType str, Enum ⋮---- OPENAI = "openai" AZURE OPENAI = "azure openai" HUGGINGFACE = "huggingface" OLLAMA = "ollama" COHERE = "cohere" VERTEXAI = "vertexai" BEDROCK = "bedrock" JINA = "jina" CUSTOM = "custom" ⋮---- class ParserType str, Enum ⋮---- TEXT = "text" UNSTRUCTURED = "unstructured" PYMUPDF = "pymupdf" PYPDF = "pypdf" DOCX = "docx" AZURE BLOB = "azure blob" S3 = "s3" DIRECTORY = "directory" WEB = "web" ⋮---- class ChunkingStrategy str, Enum ⋮---- CHARACTER = "Charact… Evidence: `src/ragbuilder/config/components.py` - **Data Ingest** (source_file): class LoaderConfig BaseModel ⋮---- type: ParserType loader kwargs: Optional Dict str, Any = None custom class: Optional str = None ⋮---- class ChunkingStrategyConfig BaseModel ⋮---- type: ChunkingStrategy chunker kwargs: Optional Dict str, Any = None custom class: Union str, Any = None ⋮---- class ChunkSizeConfig BaseModel ⋮---- min: int = Field default=500, description="Minimum chunk size" max: int = Field default=3000, description="Maximum chunk size" stepsize: int = Field default=500, description="Step size for chunk size" ⋮---- class ChunkSizeStatic BaseModel ⋮---- val: int = Field default=500, description="chunk size" ⋮---- class VectorDBConfig BaseModel ⋮---- type: VectorDatabase vect… Evidence: `src/ragbuilder/config/data_ingest.py` - **Retriever** (source_file): class BaseRetrieverConfig BaseModel ⋮---- type: RetrieverType retriever kwargs: Optional Dict str, Any = Field default factory=dict, description="Retriever-specific parameters" custom class: Optional str = None retriever k: List int = Field default= 100 , description="Number of documents to retrieve" weight: float = Field ⋮---- class RerankerConfig BaseModel ⋮---- type: RerankerType reranker kwargs: Optional Dict str, Any = Field default factory=dict, description="Re-ranker-specific parameters" ⋮---- class RetrievalOptionsConfig BaseModel ⋮---- retrievers: List BaseRetrieverConfig = Field default=None, description="List of retrievers to try" rerankers: Optional List RerankerConfig = Field d… Evidence: `src/ragbuilder/config/retriever.py` - **Init** (source_file): all = 'DBLoggerCallback', 'ConfigStore', 'DocumentStore', 'setup rich logging', 'console' Evidence: `src/ragbuilder/core/__init__.py` - **Custom Components** (source_file): class ContextualChunker TextSplitter ⋮---- def split text self, text: str - List str ⋮---- temp doc = Document page content=text processed docs = self.split documents temp doc ⋮---- def split documents self, documents: List Document - List Document ⋮---- splitter = RecursiveCharacterTextSplitter chunk size=self.chunk size, chunk overlap=self.chunk overlap splits = splitter.split documents documents ⋮---- document array = ⋮---- chunk length = len split.page content ⋮---- context length = int chunk length 0.1 ⋮---- chunk group = splits max 0, i - 5 :min len splits , i + 6 chunk content = self.format docs split ⋮---- chunk group content = self.format docs chunk group ⋮---- prompt = f''' ⋮----… Evidence: `src/ragbuilder/custom_components.py` - **Evaluation** (source_file): class Evaluator ABC ⋮---- @abstractmethod def evaluate self, pipeline: DataIngestPipeline - Tuple float, List Dict str, Any ⋮---- class SimilarityEvaluator Evaluator ⋮---- def init self, evaluation config: EvaluationConfig ⋮---- kwargs = evaluation config.evaluator kwargs or {} ⋮---- weight sum = sum self.position weights ⋮---- def calculate weighted score self, relevance scores: List float - float ⋮---- padded scores = relevance scores + 0.0 self.top k - len relevance scores ⋮---- def evaluate self, pipeline: DataIngestPipeline - Tuple float, List Dict str, Any ⋮---- total score = 0.0 question details = eval timestamp = int time.time 1000 ⋮---- start time = datetime.now ⋮---- results = pip… Evidence: `src/ragbuilder/data_ingest/evaluation.py` - **Add any additional callbacks** (source_file): class DataIngestOptimizer ⋮---- db callback = DBLoggerCallback ⋮---- Add any additional callbacks ⋮---- def build trial config self, trial - Tuple DataIngestConfig, List Document ⋮---- """Build config from trial parameters""" Get loader configuration ⋮---- document loader = self.options config.document loaders 0 ⋮---- document loader = self.document loader map trial.suggest categorical ⋮---- chunking strategy = self.options config.chunking strategies 0 if len self.options config.chunking strategies == 1 ⋮---- chunk size = trial.suggest int "chunk size", self.options config.chunk size.min, self.options config.chunk size.max, step=self.options config.chunk size.stepsize ⋮---- chunk overlap =… Evidence: `src/ragbuilder/data_ingest/optimization.py` - **Add kwargs hashes using make hashable** (source_file): class DataIngestPipeline ⋮---- def init self, config: DataIngestConfig, documents: List Document = None, verbose: bool = False ⋮---- def make hashable self, obj: Any - Any ⋮---- def get loader key self - str ⋮---- loader kwargs = self.config.document loader.loader kwargs or {} ⋮---- def get config key self - str ⋮---- """Generate a unique key for the complete configuration""" ⋮---- embedding type = self.config.embedding model.type ⋮---- embedding type = self.config.embedding model. initialized embedding. class . name ⋮---- embedding type = "unknown" ⋮---- components = ⋮---- Add kwargs hashes using make hashable ⋮---- def get or load documents self - List Document ⋮---- input source = self.c… Evidence: `src/ragbuilder/data_ingest/pipeline.py` - **Init** (source_file): all = Evidence: `src/ragbuilder/generation/__init__.py` - **Configure RAGAS run settings** (source_file): class GenerationEvaluator ⋮---- def init self, eval config: EvaluationConfig ⋮---- llm config = self.eval config.llm if self.eval config.llm else ConfigStore .get default llm ⋮---- embedding config = self.eval config.embeddings if self.eval config.embeddings else ConfigStore .get default embeddings ⋮---- Configure RAGAS run settings ⋮---- def load test dataset self - pd.DataFrame ⋮---- df = pd.read csv self.test dataset path required columns = 'user input', 'reference' ⋮---- missing = col for col in required columns if col not in df.columns ⋮---- Remove rows with missing reference answers df = df.dropna subset= 'reference' ⋮---- def evaluate generation self, pipeline: Any, config key: str -… Evidence: `src/ragbuilder/generation/evaluation.py` - **Add any additional callbacks** (source_file): CONFIG STORE = ConfigStore ⋮---- class GenerationOptimizer ⋮---- retriever pipeline = CONFIG STORE.get best retriever pipeline ⋮---- db callback = DBLoggerCallback ⋮---- Add any additional callbacks ⋮---- def generate generation config self, trial: Trial - GenerationConfig ⋮---- """ Generate a generation configuration from trial parameters. Args: trial: Optuna trial object Returns: GenerationConfig for this trial """ Select LLM llm index = trial.suggest categorical "llm index", list self.llm map.keys llm config = self.llm map llm index ⋮---- prompt index = trial.suggest categorical "prompt index", list self.prompt map.keys ⋮---- params = { ⋮---- def objective self, trial: Trial - float ⋮---… Evidence: `src/ragbuilder/generation/optimization.py` - **def invoke self, query: str, chat history: Optional List = None - Dict str, Any :** (source_file): class GenerationPipeline ⋮---- def create pipeline self - Any ⋮---- def format docs docs ⋮---- llm = self.config.llm.llm prompt template = self.config.prompt template ⋮---- prompt = ChatPromptTemplate.from messages ⋮---- rag chain = ⋮---- def invoke self, query: str, chat history: Optional List = None - Dict str, Any : """ Generate an answer for the given query. ⋮---- Args: query: User question to answer chat history: Optional chat history for contextual generation ⋮---- Returns: Dictionary with generated answer and context ⋮---- try: if self.verbose: self.logger.debug f"Generating answer for query: {query}" ⋮---- Prepare input input data = {"question": query} ⋮---- def batch generate self,… Evidence: `src/ragbuilder/generation/pipeline.py` - **Sample Retriever** (source_file): def sample retriever url ⋮---- def format docs docs ⋮---- llm = AzureChatOpenAI model="gpt-4o-mini" ⋮---- loader = WebBaseLoader url docs = loader.load ⋮---- embedding = AzureOpenAIEmbeddings model="text-embedding-3-large" ⋮---- splitter = RecursiveCharacterTextSplitter chunk size=500, chunk overlap=200 splits = splitter.split documents docs ⋮---- c=FAISS.from documents documents=splits, embedding=embedding ⋮---- retriever = c.as retriever search type="similarity", search kwargs={"k": 5} ensemble retriever = EnsembleRetriever retrievers= retriever Evidence: `src/ragbuilder/generation/sample_retriever.py` - **Init** (source_file): def check graph dependencies Evidence: `src/ragbuilder/graph_utils/__init__.py` - **Graph Retriever** (source_file): class Neo4jGraphRetriever BaseRetriever ⋮---- graph: Any = Field None, description="Neo4j graph instance" embeddings: Any = Field None, description="Embedding model to embed queries" top k: int = Field default=3, description="Number of documents to retrieve" max hops: int = Field default=2, description="Maximum number of hops in graph traversal" max related docs per doc: int = Field default=3, description="Maximum related documents per primary document" graph weight: float = Field default=0.3, description="Weight for graph-based scores" index name: str = Field default="document embeddings", description="Name of the vector index" ⋮---- @property def query template self - str ⋮---- query embe… Evidence: `src/ragbuilder/graph_utils/graph_retriever.py` - **Init** (source_file): version = "unknown version" ⋮---- all = "run ragbuilder"," version " Evidence: `src/ragbuilder/langchain_module/__init__.py` - **Init** (source_file): version = "unknown version" ⋮---- all = "run ragbuilder"," version " Evidence: `src/ragbuilder/langchain_module/retriever/__init__.py` - **print compressor config** (source_file): logger = logging.getLogger "ragbuilder" ⋮---- rerankers to check = ⋮---- def getRetriever kwargs ⋮---- retriever type = kwargs.get 'retriever type' search kwargs=kwargs.get 'search kwargs',None ⋮---- document compressor pipeline=kwargs 'retriever kwargs' .get 'document compressor pipeline', ⋮---- search kwargs=100 ⋮---- document compressor pipeline=kwargs 'retriever kwargs' .get 'document compressor pipeline',None ⋮---- code string = f"""retriever=c.as retriever search type='{kwargs 'search type' }', search kwargs={{'k': 100}} """ ⋮---- code string = f"""retriever=c.as retriever search type='{kwargs 'search type' }', search kwargs={{'k': {kwargs 'search kwargs' }}} """ ⋮---- import string =… Evidence: `src/ragbuilder/langchain_module/retriever/retriever.py` - **Init** (source_file): version = "unknown version" ⋮---- all = "run ragbuilder"," version " Evidence: `src/ragbuilder/langchain_module/vectordb/__init__.py` - **If no modules were found, print a message or handle as needed** (source_file): module dir = os.path.dirname file ⋮---- modules found = False ⋮---- module name = filename :-3 ⋮---- modules found = True Mark that at least one module was found ⋮---- If no modules were found, print a message or handle as needed Evidence: `src/ragbuilder/rag_templates/sota/__init__.py` - **Contextul Retriever** (source_file): code="""from langchain openai import ChatOpenAI Evidence: `src/ragbuilder/rag_templates/sota/contextul_retriever.py` - **Graph Rag** (source_file): code="""from langchain core.runnables import RunnablePassthrough Evidence: `src/ragbuilder/rag_templates/sota/graph_rag.py` - **Graph Rag Hybrid** (source_file): code="""from langchain core.runnables import RunnablePassthrough Evidence: `src/ragbuilder/rag_templates/sota/graph_rag_hybrid.py` - **Hybrid Rag** (source_file): code="""from langchain community.llms import Ollama Evidence: `src/ragbuilder/rag_templates/sota/hybrid_rag.py` - **Hyde** (source_file): code="""from langchain community.llms import Ollama Evidence: `src/ragbuilder/rag_templates/sota/hyde.py` - **Query Rewrite** (source_file): code="""from langchain community.llms import Ollama Evidence: `src/ragbuilder/rag_templates/sota/query_rewrite.py` - **Simple Rag** (source_file): code="""from langchain community.llms import Ollama Evidence: `src/ragbuilder/rag_templates/sota/simple_rag.py` - **Check if column exists** (source_file): logger = logging.getLogger "ragbuilder" LOG FILENAME = logger.handlers 0 .baseFilename LOG DIRNAME = Path LOG FILENAME .parent BASE DIR = Path file .resolve .parent ⋮---- url = "http://localhost:8005" ⋮---- app = FastAPI DATABASE = 'eval.db' BAYES OPT = 1 CURRENT RUN ID = 0 ⋮---- templates = Jinja2Templates directory=Path BASE DIR, 'templates' ⋮---- def basename path ⋮---- def get db ⋮---- db = sqlite3.connect DATABASE, check same thread=False ⋮---- def get hashmap db: sqlite3.Connection = Depends get db ⋮---- cur = db.execute 'SELECT hash, test data path FROM synthetic data hashmap' rows = cur.fetchall ⋮---- def insert hashmap hash: str, path: str, db: sqlite3.Connection ⋮---- insert query… Evidence: `src/ragbuilder/ragbuilder.py` - **Convert to EvaluationDataset format** (source_file): class Evaluator ABC ⋮---- @abstractmethod def evaluate self, pipeline: RetrieverPipeline - Tuple float, List Dict str, Any ⋮---- class RetrieverF1ScoreEvaluator Evaluator ⋮---- def init self, eval config: EvaluationConfig ⋮---- llm config = self.eval config.llm if self.eval config.llm else ConfigStore .get default llm ⋮---- embedding config = self.eval config.embeddings if self.eval config.embeddings else ConfigStore .get default embeddings ⋮---- default config = { ⋮---- config = eval config.evaluator kwargs.get "run config", {} ⋮---- eval data = eval timestamp = int time.time 1000 ⋮---- start time = datetime.now ⋮---- retrieved docs = pipeline.retrieve row "user input" ⋮---- latency = date… Evidence: `src/ragbuilder/retriever/evaluation.py` - **Add any additional callbacks** (source_file): STORE = DocumentStore CONFIG STORE = ConfigStore ⋮---- class RetrieverOptimization ⋮---- db callback = DBLoggerCallback ⋮---- Add any additional callbacks ⋮---- def load test queries self - List Dict str, Any ⋮---- """Load test queries from the specified dataset.""" Implementation depends on test dataset format ⋮---- def generate retrieval config self, trial: Trial - RetrievalConfig ⋮---- """Generate a retrieval configuration from trial parameters.""" retrievers = ⋮---- If only one retriever option, use it directly ⋮---- retriever config = self.retriever map 0 If only one k value, use it directly k = retriever config.retriever k 0 if len retriever config.retriever k == 1 ⋮---- n retrievers… Evidence: `src/ragbuilder/retriever/optimization.py` - **status.update " status Creating ensemble retriever... /status "** (source_file): class RetrieverPipeline ⋮---- def validate config self, config: RetrievalConfig - None ⋮---- def create base retrievers self - List BaseRetriever ⋮---- retrievers = weights = ⋮---- retriever = self.vectorstore.as retriever ⋮---- retriever = MultiQueryRetriever.from llm ⋮---- child splitter = self.best data ingest pipeline.chunker parent splitter = None ⋮---- splitter = RecursiveCharacterTextSplitter ⋮---- splitter = CHUNKER MAP self.best data ingest config "chunking strategy" "type" parent splitter = splitter ⋮---- store = InMemoryStore ⋮---- retriever = ParentDocumentRetriever ⋮---- chunks = self.best data ingest pipeline.ingest status=None ⋮---- retriever = BM25Retriever.from documents ⋮-… Evidence: `src/ragbuilder/retriever/pipeline.py` - **Init** (source_file): version = "0.1.0" all = 'app' Evidence: `src/ragbuilder_ui/__init__.py` - **.dockerignore** (source_file): .dockerignore .log .env .csv .log .pyc .db .DS Store .dockerignore .git .gitignore venv/ Evidence: `.dockerignore` - **Description: Environment variables for the project. Rename to .env file for use** (source_file): Description: Environment variables for the project. Rename to .env file for use OPENAI API KEY=XXXXXXXXX MISTRAL API KEY=XXXXXXXXX MIXPANEL TOKEN=XXXXXXXXX HUGGINGFACEHUB API TOKEN=XXXXXXXXX COHERE API KEY=XXXXXXXXX JINA API KEY=XXXXXXXXX ENABLE ANALYTICS=True SINGLESTOREDB URL=userid:password@host:port/dbname PINECONE API KEY=XXXXXXXXX GROQ API KEY=XXXXXXXXX AZURE OPENAI API KEY=XXXXXXXXX AZURE OPENAI ENDPOINT=https://XXXXXXXXX.openai.azure.com/ OPENAI API VERSION=2024-02-01 GOOGLE API KEY=AIzaSyDN2-XXXXXXXXX GOOGLE CLOUD PROJECT=projectid GOOGLE APPLICATION CREDENTIALS=credentials.json must be placed in the folder where docker is run PGVECTOR CONNECTION STRING=postgresql+psycopg://langcha… Evidence: `.env-Sample` - **Use an official Python runtime as a parent image** (source_file): Use an official Python runtime as a parent image FROM python:3.12.3-slim Evidence: `Dockerfile` - **Arxiv.783857** (source_file): ,question,contexts,ground truth,evolution type,metadata,episode done 0,What kind of practical exercises or resources can be offered to help manage symptoms and improve mental wellbeing?," '\nYour\n\napproach\n\nAs the patient shares their struggles, you will provide insightful guidance and evidence-based strategies tailored to their unique needs. You may also offer practical exercises or resources to help them manage their symptoms and improve their mental wellbeing. When necessary, you will gently redirect the conversation back to the patient\'s primary concerns related to anxiety, mental health, or family issues. This ensures that each session is productive and focused on addressing the m… Evidence: `SampleSyntheticDataFiles/arxiv.783857.sample` - **Lilianweng** (source_file): ,question,contexts,ground truth,evolution type,metadata,episode done 0,What is the process followed by GPT-Engineer to create a repository of code given a task specified in natural language?," ' practice file naming convention.\nMake sure that files contain all imports, types etc. Make sure that code in different files are compatible with each other.\nEnsure to implement all code, if you are unsure, write a plausible implementation.\nInclude module dependency or package manager dependency definition file.\nBefore you finish, double check that all parts of the architecture is present in the files.\nUseful to know:\nYou almost always put different classes in different files.\nFor Python, you… Evidence: `SampleSyntheticDataFiles/lilianweng.sample` - **Rag** (source_file): ,question,contexts,ground truth,evolution type,metadata,episode done 0,What is the purpose of calculating cosine similarity between two word vectors?," '.6Vector embeddings exampledef word to vector word : Define some basic rules for our vector components vector = 0 5 Initialize a vector of 5 dimensions Rule 1: Length of the word normalized to a max of 10 characters for simplicity vector 0 = len word / 10 Rule 2: Number of vowels in the word normalized to the length of the word vowels = \'aeiou\' vector 1 = sum 1 for char in word if char in vowels / len word Rule 3: Whether the word starts with a vowel 1 or not 0 vector 2 = 1 if word 0 in vowels else 0 Rule 4: Whether the word ends with a v… Evidence: `SampleSyntheticDataFiles/rag.sample` - **Myrag** (source_file): def rag pipeline ⋮---- def format docs docs ⋮---- llm = Ollama model='llama3.1:latest',base url='http://localhost:11434' ⋮---- loader = WebBaseLoader 'https://ashwinaravind.github.io/' docs = loader.load ⋮---- embedding = OllamaEmbeddings model='mxbai-embed-large:latest',base url='http://localhost:11434' ⋮---- splitter = RecursiveCharacterTextSplitter chunk size=1600, chunk overlap=200 splits=splitter.split documents docs c=Chroma.from documents documents=splits, embedding=embedding, collection name='testindex-ragbuilder', retrievers= retriever=c.as retriever search type='similarity', search kwargs={'k': 5} ⋮---- retriever=MergerRetriever retrievers=retrievers prompt = hub.pull "rlm/rag-pro… Evidence: `byor/myrag.py` - **Dockerfile** (source_file): ENV NEO4JLABS PLUGINS ' "apoc" ' ENV NEO4J dbms security procedures unrestricted apoc. Evidence: `neo4j/Dockerfile` - **Pytest** (source_file): pytest addopts = --strict-markers markers = core: marks tests as slow deselect with '-m "not slow"' serial timeout = 50 log cli=true log level=DEBUG log format = % asctime s % levelname s % message s log date format = %Y-%m-%d %H:%M:%S log file = logs/pytest-logs.txt minversion = 7.2 required plugins = pytest-xdist =3.2.0 pytest-env =0.8.0 Evidence: `pytest.ini` - **Rag Prompts** (source_file): {"locale":"en","featureFlags": "alive longer retries","bypass copilot indexing quota","copilot new references ui","copilot beta features opt in","copilot chat retry on error","copilot chat persist submitted input","copilot conversational ux history refs","copilot editor upsells","copilot free limited user","copilot implicit context","copilot no floating button","copilot smell icebreaker ux","experimentation azure variant endpoint","failbot handle non errors","geojson azure maps","ghost pilot confidence truncation 25","ghost pilot confidence truncation 40","hovercard accessibility","issues advanced search","issues react close as duplicate","issues react new timeline","issues react avatar ref… Evidence: `rag_prompts.yml` - **Ragbuilder Sdk Demo** (source_file): { "cells": { "cell type": "markdown", "metadata": {}, "source": " RAGBuilder Optimization Demo" }, { "cell type": "code", "execution count": null, "metadata": {}, "outputs": , "source": "!uv venv" }, { "cell type": "code", "execution count": null, "metadata": {}, "outputs": , "source": "!source .venv/bin/activate" }, { "cell type": "code", "execution count": null, "metadata": {}, "outputs": , "source": " First clone the RAGBuilder repo\n", "!uv pip install ragbuilder" }, { "cell type": "markdown", "metadata": {}, "source": " Quickstart - Basic Configuration" }, { "cell type": "code", "execution count": 1, "metadata": {}, "outputs": , "source": "from ragbuilder import RAGBuilder" }, { "cell… Evidence: `ragbuilder_sdk_demo.ipynb` - **sample data.txt** (source_file): sample data.txt This is a sample document for testing the RAGBuilder data ingestion pipeline. It contains multiple sentences to demonstrate chunking. We'll use this to test our parser, chunker, embedder, and indexer components. The goal is to ensure that our pipeline works end-to-end with a simple configuration. Evidence: `sample_data.txt` - **Sample Questions** (source_file): What is the purpose of this document? What does this document show? What all components will we test? Evidence: `sample_questions.txt` - **Start Server** (source_file): def main ⋮---- parser = argparse.ArgumentParser description='Start the RAG server.' ⋮---- args = parser.parse args ⋮---- builder = RAGBuilder.from source with defaults Evidence: `start_server.py` - **Test Pipeline Options** (source_file): input source: "sample data.txt" test dataset: "sample questions.txt" document loaders: - type: "unstructured" loader kwargs: {} chunking strategies: - "RecursiveCharacterTextSplitter" - "CharacterTextSplitter" - "custom" chunk size: min: 100 max: 500 stepsize: 100 chunk overlap: 50, 100 embedding models: - type: "openai" model: "text-embedding-3-small" - type: "huggingface" model: "sentence-transformers/all-MiniLM-L6-v2" vector databases: - type: "chroma" collection name: "test collection" persist directory: "chroma sample2" collection metadata: "hnsw:space": "cosine" - type: "faiss" normalize L2: true top k: 3 sampling rate: null optimization: n trials: 10 timeout: 600 storage: "sqlite:///… Evidence: `test_pipeline_options.yaml` ## Rules the Host AI Must Follow - **Treat this asset as pre-work context, not a runtime environment.**: The AI Context Pack contains only an evidence-backed understanding of the project, not the project's executable state. Evidence: `README.md`, `LICENSE`, `byor/__init__.py` - **When answering the user, distinguish what can be previewed from what can only be verified after install.**: The consumer value of the pre-install experience comes from reducing bad installs and misjudgments, not from pretending to be a real run. Evidence: `README.md`, `LICENSE`, `byor/__init__.py` ## Questions the User Should Answer First - Which host AI or local environment do you plan to use it in? - Do you just want to experience the workflow first, or are you ready to actually install? - What matters most to you: install cost, output quality, or conflicts with your existing rules? ## Acceptance Checks - Every capability claim can be traced back to a file path in evidence_refs. - AI_CONTEXT_PACK.md does not package previews as a real run. - The user can understand who it fits, what it can do, how to start, and the risk boundaries within 3 minutes. --- ## Doramagic Context Augmentation The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints. ## Human Manual Outline Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph. Host AI hard rules: - Do not treat page titles, section order, summaries, or importance values as factual project evidence. - When explaining the Human Manual outline, state that it is only a reading route or salience signal. - Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph. - **Overview and Installation**: importance `high` - source_paths: README.md, install.sh, install.bat, docker-compose.yml, Dockerfile - **Core SDK API and Configuration Schema**: importance `high` - source_paths: src/ragbuilder/ragbuilder.py, src/ragbuilder/__init__.py, src/ragbuilder/config/base.py, src/ragbuilder/config/components.py, src/ragbuilder/config/data_ingest.py - **RAG Templates and Component Modules**: importance `high` - source_paths: src/ragbuilder/rag_templates/sota/graph_rag.py, src/ragbuilder/rag_templates/sota/graph_rag_hybrid.py, src/ragbuilder/rag_templates/sota/hybrid_rag.py, src/ragbuilder/rag_templates/sota/hyde.py, src/ragbuilder/rag_templates/sota/query_rewrite.py - **Optimization, Evaluation, Deployment, and Troubleshooting**: importance `high` - source_paths: src/ragbuilder/data_ingest/optimization.py, src/ragbuilder/data_ingest/evaluation.py, src/ragbuilder/data_ingest/pipeline.py, src/ragbuilder/retriever/optimization.py, src/ragbuilder/retriever/evaluation.py ## Repo Inspection Evidence - repo_clone_verified: true - repo_inspection_verified: true - repo_commit: `5b084512d65042d9207ba19331176963fe005dd8` - inspected_files: `Dockerfile`, `README.md`, `docker-compose.yml`, `pyproject.toml`, `src/__init__.py`, `src/ragbuilder/__init__.py`, `src/ragbuilder/analytics.py`, `src/ragbuilder/config/__init__.py`, `src/ragbuilder/config/base.py`, `src/ragbuilder/config/components.py`, `src/ragbuilder/config/data_ingest.py`, `src/ragbuilder/config/generation.py`, `src/ragbuilder/config/retriever.py`, `src/ragbuilder/core/__init__.py`, `src/ragbuilder/core/builder.py`, `src/ragbuilder/core/callbacks.py`, `src/ragbuilder/core/config_store.py`, `src/ragbuilder/core/document_store.py`, `src/ragbuilder/core/exceptions.py`, `src/ragbuilder/core/logging_utils.py` Host AI hard rules: - Without repo_clone_verified=true, do not claim that the source code has been read. - Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts. - Without quick_start_verified=true, do not claim that the Quick Start path has run successfully. ## Doramagic Pitfall Constraints These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes. ### Constraint 1: Capability evidence risk requires verification - Trigger: README/documentation is current enough for a first validation pass. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/KruxAI/ragbuilder - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.