<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Mohit Aggarwal on Medium]]></title>
        <description><![CDATA[Stories by Mohit Aggarwal on Medium]]></description>
        <link>https://medium.com/@mohitagr18?source=rss-3a62c8e9f67f------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*53jVlNMujbn1rAzlk0fwow.jpeg</url>
            <title>Stories by Mohit Aggarwal on Medium</title>
            <link>https://medium.com/@mohitagr18?source=rss-3a62c8e9f67f------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 09:42:03 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@mohitagr18/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Stop Prompting JSON: How to Build Zero-Retry LLM Pipelines]]></title>
            <link>https://aiadvances.org/stop-prompting-json-how-to-build-zero-retry-llm-pipelines-2c7036b1c08a?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/2c7036b1c08a</guid>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Thu, 24 Sep 2026 13:08:22 GMT</pubDate>
            <atom:updated>2026-09-24T13:08:22.333Z</atom:updated>
            <content:encoded><![CDATA[<h4><em>An architectural deep dive and empirical latency benchmark on replacing fragile prompts with Pydantic validation, token masking, and compiled prompts with Instructor, Outlines, and DSPy.</em></h4><p>💡 <strong>Companion Notebook:</strong> The complete, fully runnable Jupyter notebook with all imports, model setups, and live executions is available on <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">GitHub</a></p><blockquote>Non-Users — <a href="https://medium.com/@mohitagr18/2c7036b1c08a?source=friends_link&amp;sk=288e81633bd96b7290678137817411e5">click here</a></blockquote><h3>The Problem of Determinism in Production LLMs</h3><p>Taking Large Language Models (LLMs) from hacky prototypes into real production services runs straight into an architectural headache: LLMs predict tokens probabilistically, but backend services need deterministic, typed data. If an API endpoint expects clean JSON matching an exact database schema, receiving stray markdown fences, dropped fields, or half-baked syntax will crash downstream execution.</p><p>Engineering teams tackling non-deterministic outputs usually evolve through four distinct stages:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RU7m-ixSuPpn8sek_bn6EQ.png" /><figcaption><strong>Figure 1: The Evolution of Output Control.</strong> <em>Progression of structured LLM control paradigms — moving from brittle natural-language prompt engineering to application-level validation loops (Instructor), engine-level logit masking (Outlines), and declarative, metric-driven prompt compilation (DSPy). </em>(Source: Image generated using Google Gemini)</figcaption></figure><h3>Naïve vs. Strict Paradigms</h3><h4>Naïve JSON Prompt Engineering</h4><p>You prompt the model as plaintext to “return valid JSON”. Given generation is purely token probabilities conditioned on your text prompt, you often end up with chatterbox answer personas, code blocks wrapped in markdown code fences (`` ```json … ``` ``), hallucinated invalid keys, or partial Json responses dropping required attributes when context is heavy.</p><p><strong>Structured LLM Frameworks</strong> bake determinism into three very different layers of the inference stack:</p><h4>Application Level Validation ( <a href="https://python.useinstructor.com/">Instructor </a>)</h4><p>API’s that wrap provider SDKs to request JSON or function calls and then parse the response directly into typed run-time objects such as Pydantic models. If validation fails it intercepts the exception, injects the validation error trace directly into next prompt and allows the llm to fix its own error.</p><h4>Token Level Guided Masking ( <a href="https://dottxt-ai.github.io/outlines/latest/">Outlines </a>)</h4><p>Alters the tokens being decoded at literally the last microservice. By compiling your target schema or Lark grammar into a Finite State Automaton(FSA), we mask the logits of every syntactically invalid next token to negative infinity prior to sampling. It becomes mathematically impossible to generate invalid syntax.</p><h4>Programmatic System Optimization ( <a href="https://dspy.ai/current/getting-started/program-dont-prompt/">DSPy </a>)</h4><p>Swaps out brittle prompt strings with declarative signatures (input -&gt; output) and modular pipelines. Instead of manually finetuning adjectives for hours on end, you compile and optimize your instructions + few shot examples against code defined evaluation metrics.</p><h3>1. Deep Dive: Instructor</h3><p><a href="https://python.useinstructor.com/">Instructor </a>is a lightweight wrapper around standard provider SDKs (including OpenAI, Anthropic, Gemini, and Ollama). Instead of stringifying schemas into prompts and writing custom regex parsers, you patch the client with instructor.from_openai() or equivalent helpers. It maps a standard Pydantic BaseModel directly to the provider&#39;s structured output or tool-calling endpoint, taking care of serialization and object instantiation automatically.</p><h4>Core Patterns &amp; Walkthrough</h4><h4><strong>Pattern 1: </strong>Schema-Driven Extraction with Field-Level Prompts</h4><ol><li>The Production Problem</li></ol><p>In structured data extraction (e.g. processing product reviews), field names like pros or cons are ambiguous to an LLM without explicit context. Is pros a list of features, compliments, or technical specs? This ambiguity leads to inconsistent JSON structures across different inputs.</p><p>2. Why Naive Prompting Fails</p><p>Writing a 500-word system prompt explaining every schema key pollutes the context window, increases token costs, and breaks as field names or schemas change.</p><p>3. The Instructor Solution</p><p>Instructor leverages Pydantic schemas where Field(description=&quot;...&quot;) annotations double as field-level micro-prompts. Instructor serializes these descriptions into JSON Schema and passes them directly to provider API calls, keeping schema logic and extraction instructions unified in Python type hints.</p><p>4. Focused Code</p><pre>from pydantic import BaseModel, Field<br>import instructor<br>from openai import OpenAI<br><br>client = instructor.from_openai(OpenAI())<br><br># Schema field descriptions double as semantic micro-prompts for the model<br>class ProductReview(BaseModel):<br>    product_name: str = Field(description=&quot;Exact brand and model name&quot;)<br>    rating: int = Field(description=&quot;Rating from 1 to 5 stars&quot;)<br>    pros: list[str] = Field(description=&quot;Specific positive features mentioned <br>                            by reviewer&quot;)<br>    cons: list[str] = Field(description=&quot;Negative aspects or complaints&quot;)<br>    would_recommend: bool = Field(description=&quot;True if reviewer explicitly <br>                                  endorses product&quot;)<br><br>review = client.chat.completions.create(<br>    model=&quot;gpt-4o-mini&quot;,<br>    response_model=ProductReview,<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: f&quot;Extract review data: <br>                                          {review_text}&quot;}],<br>)</pre><p>5. Executed Console Output</p><pre>Product: Sony WH-1000XM5<br>Rating: 5/5<br>Pros: [&#39;superior noise cancellation&#39;, &#39;outstanding battery performance&#39;]<br>Cons: [&#39;somewhat expensive&#39;, &#39;carrying case is rather large&#39;]<br>Recommend: True</pre><h4>Pattern 2: @field_validator and Self-Correction Retry Loops</h4><p>1. The Production Problem</p><p>Backend systems require domain business rules (e.g., verifying email formats contain @, matching domain names to email strings, or date ordering) that raw syntax checking completely misses.</p><p>2. Why Naive Prompting Fails</p><p>Models ignore text instructions like “Email must contain @” up to 20% of the time under complex context, leading to silent runtime errors in downstream databases.</p><p>3. The Instructor Solution</p><p>Pydantic @field_validator decorators execute custom Python validation logic on the returned payload. When validation fails, Instructor catches the ValidationError and appends the exact error trace into a self-correction retry turn (max_retries=3), prompting the LLM to fix its mistake.</p><p>4. Focused Code</p><pre>from pydantic import BaseModel, field_validator<br><br>class EmailAddress(BaseModel):<br>    address: str<br>    domain: str<br><br>    @field_validator(&quot;address&quot;)<br>    @classmethod<br>    def must_be_valid_email(cls, v: str) -&gt; str:<br>        if &quot;@&quot; not in v:<br>            raise ValueError(f&quot;&#39;{v}&#39; is not a valid email — must contain &#39;@&#39;&quot;)<br>        return v.lower()<br><br>    @field_validator(&quot;domain&quot;)<br>    @classmethod<br>    def must_match_address(cls, v: str, values) -&gt; str:<br>        if &quot;address&quot; in values.data:<br>            expected = values.data[&quot;address&quot;].split(&quot;@&quot;)[-1]<br>            if v != expected:<br>                raise ValueError(f&quot;Domain &#39;{v}&#39; doesn&#39;t match email domain <br>                                &#39;{expected}&#39;&quot;)<br>        return v<br><br>email_object = client.chat.completions.create(<br>    model=&quot;gpt-4o-mini&quot;,<br>    response_model=EmailAddress,<br>    max_retries=3,  # Intercepts ValidationError and re-prompts model with error trace<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Parse: mohit@gmail.com <br>              (company email)&quot;}],<br>)</pre><p>5. Executed Console Output</p><pre>[Attempt 1] Submitting payload to gpt-4o-mini...<br>[ValidationError Intercepted]: &#39;mohit.gmail.com&#39; is not a valid email <br>                                — must contain &#39;@&#39;<br>[Attempt 2] Injecting error trace into context and re-prompting model...<br>[Success] Self-corrected object received on Attempt 2.<br><br>Validated Email Object: address=&#39;mohit@gmail.com&#39; domain=&#39;gmail.com&#39;</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View field validation retry mechanics in GitHub Notebook ↗</a></p><h4>Pattern 3: Real-Time Streaming</h4><p>1. The Production Problem</p><p>Waiting for full JSON objects from LLMs introduces 3–8 seconds of latency, creating a sluggish user experience in interactive web UIs.</p><p>2. Why Naive Prompting Fails</p><p>Standard json.loads() blocks execution until the entire string, including the final closing bracket }, is fully generated.</p><p>3. The Instructor Solution</p><p>create_partial() yields incomplete Pydantic instances (Partial[Model]) progressively as individual tokens arrive over the stream, enabling UI components to render fields in real time.</p><p>4. Focused Code</p><pre>from pydantic import BaseModel<br>class Order(BaseModel):<br>    customer: str<br>    items: list[str]<br>    total: float<br>    status: str<br># Stream partial updates as fields arrive over the wire<br>for partial_order in client.chat.completions.create_partial(<br>    model=&quot;gpt-4o-mini&quot;,<br>    response_model=Order,<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: f&quot;Extract order: {order_text}&quot;}],<br>):<br>    print(f&quot;Customer: {partial_order.customer or &#39;...&#39;} | <br>            Total: {partial_order.total or &#39;...&#39;}&quot;)</pre><p>5. Executed Console Output</p><pre>Customer: ... | Total: ...<br>Customer: John | Total: ...<br>Customer: John Doe | Total: ...<br>Customer: John Doe | Total: 4798.0</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View streaming partial updates in GitHub Notebook ↗</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*i8w_LxaDyJFyE0o8a8p8Dw.png" /><figcaption><strong>Figure 2: Instructor’s Dual Execution Modes.</strong> Left: The semantic validation retry loop, where intercepted Pydantic validation traces are reinjected into the prompt context at the cost of compounding latency. Right: Progressive UI streaming via create_partial(), delivering field-by-field updates to reduce perceived time-to-first-field by up to 1.6x. (Source: Image generated using Google Gemini)</figcaption></figure><h4>Pattern 4: Local Model Integration (Ollama / vLLM)</h4><p>1. The Production Problem</p><p>Cloud API costs scale linearly with volume, and transmitting sensitive PII to third-party endpoints violates privacy policies.</p><p>2. Why Naive Prompting Fails</p><p>Smaller open-weights models ($\le 8\text{B}$) struggle to adhere to raw JSON system prompts without structured API wrappers.</p><p>3. The Instructor Solution</p><p>Instructor patches OpenAI-compatible local servers (e.g. Ollama running qwen2.5:8b at http://localhost:11434/v1), delivering identical Pydantic extraction pipelines locally at zero cloud cost.</p><p>4. Focused Code</p><pre>from openai import OpenAI<br>import instructor<br>ollama_client = OpenAI(base_url=&quot;http://localhost:11434/v1&quot;, api_key=&quot;ollama&quot;)<br>client = instructor.from_openai(ollama_client)<br>result = client.chat.completions.create(<br>    model=&quot;qwen2.5:8b&quot;,<br>    response_model=SentimentResult,<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Classify: Product performance <br>              is exceptional!&quot;}],<br>)</pre><p>5. Executed Console Output</p><pre>SentimentResult(text=&#39;Product performance is exceptional!&#39;, <br>                sentiment=&#39;positive&#39;, confidence=0.98)</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View local model extraction pipeline in GitHub Notebook ↗</a></p><h4>Latency, Token Overhead, and Failure Modes</h4><p>While Instructor provides an intuitive developer interface, production deployment requires careful management of specific operational trade-offs:</p><ol><li><em>Latency Overhead:</em> Every validation failure triggers a full network round-trip. If max_retries=3 is exhausted, processing time scales linearly (Nₐₜₜₑₘₚₜₛ X Latencybₐₛₑ<em>), making tail latencies (</em>P₉₉) volatile.</li><li><em>Context Window &amp; Token Budget Inflation:</em> When retrying, Instructor appends the original system prompt, the invalid LLM response, and the ValidationError trace into the conversation history. For large schemas or long context extractions, prompt token consumption grows rapidly across attempts, increasing costs on cloud providers.</li><li><em>Unsatisfiable Constraints:</em> If a @field_validator enforces a condition that contradicts the source text or the model&#39;s factual knowledge, the LLM enters an infinite retry loop until max_retries is reached, raising an unhandled ValidationError to the caller.</li></ol><h3>3. Deep Dive: Outlines (Deterministic Constrained Generation)</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pFOxLg2WQQHlK7P3LM2Pdw.png" /><figcaption><strong>Figure 3: Outlines Execution Lifecycle.</strong> <em>Architectural separation between offline grammar compilation (</em><em>outlines-core in Rust) and online autoregressive token masking in inference engines like vLLM, guaranteeing 100% syntactically valid streams on the first forward pass. (Source: Image by Author)</em></figcaption></figure><p>While application-level frameworks like Instructor rely on prompt-based retries to self-correct validation errors, <a href="https://dottxt-ai.github.io/outlines/latest/">Outlines </a>operates directly at the token decoding level. Outlines converts target schemas (Pydantic models, JSON Schemas), Regular Expressions, and Lark <strong>Context-Free Grammars (CFGs) into Finite State Automata (FSAs)</strong> or pushdown automata.</p><p>At each step of the autoregressive token generation sequence, Outlines inspects the current state of the automaton and computes the subset of valid next tokens from the model’s vocabulary. It then modifies the model’s logit distribution by setting the logits (unnormalized log-probabilities) of all syntactically invalid tokens to negative infinity before softmax sampling:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6IMsyjBK46Wyaw6akJwhng.png" /><figcaption><strong>Figure 4: Conceptual Architecture of FSA-Guided Token Decoding.</strong> The compiled Finite State Automaton (FSA) operates directly on the raw vocabulary logits prior to softmax sampling, physically blocking transitions to syntactically invalid tokens to enforce deterministic schema compliance without retries. (Source: Image generated using Google Gemini)</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/700/1*rkLy_3mBRfUrHC3V7M9XiA.png" /></figure><p>Because invalid tokens are assigned a probability of zero, the language model is mathematically incapable of emitting missing fields, malformed syntax, or out-of-schema characters. This guarantees 100% syntactic adherence without requiring a single retry network call.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BcaauS7q3gsAFdTnXBga5w.png" /><figcaption><strong>Figure 5: Next-Token Logit Masking Mechanism.</strong> Tokens violating the current state of the FSM (e.g., markdown code fences or invalid syntax) have their logits set to infinity, reducing their sampling probability to zero and guaranteeing 100% syntactic validity on the first forward pass. (Source: Image generated using Google Gemini)</figcaption></figure><h3>Core Patterns &amp; Walkthrough</h3><h4>Pattern 1: Regex &amp; Choice Token Constraints</h4><p>1. The Production Problem</p><p>Customer support routing and database triggers require strictly formatted strings (e.g., international phone +1-XXX-XXX-XXXX) and closed database enums (&quot;billing&quot;, &quot;technical&quot;, &quot;shipping&quot;).</p><p>2. Why Naive Prompting Fails</p><p>LLMs frequently emit conversational chatter (“Sure! The phone is (800) 123–4567 and category is Billing &amp; Payments”), which crashes regex parsers and SQL INSERT queries because &quot;Billing &amp; Payments&quot; is not a valid enum key.</p><p>3. The Outlines Solution</p><p>Outlines compiles regular expressions and choice lists into an FSA. At every decoding step, tokens that do not match the state transitions are masked to infinity. The model physically cannot output conversational filler or invalid categories.</p><p>4. Focused Code</p><pre>import outlines, torch<br>from outlines.types import Regex, Choice<br>from transformers import AutoModelForCausalLM, AutoTokenizer<br>LOCAL_MODEL = &quot;Qwen/Qwen2.5-0.5B-Instruct&quot;<br>tokenizer = AutoTokenizer.from_pretrained(LOCAL_MODEL)<br>hf_model = AutoModelForCausalLM.from_pretrained(LOCAL_MODEL, <br>                                                torch_dtype=torch.float32)<br>local_model = outlines.from_transformers(hf_model, tokenizer)<br># Enforce exact phone format and closed category enum at logit level<br>phone = local_model(&quot;Contact us at +1 800-123-4567&quot;, <br>                    Regex(r&quot;\+\d{1,3}-\d{5}-\d{5}&quot;))<br>category = local_model(&quot;Classify ticket: &#39;My payment failed&#39;&quot;, <br>                      Choice([&quot;billing&quot;, &quot;technical&quot;, &quot;shipping&quot;]))</pre><p>5. Executed Console Output</p><pre>Phone Match: +1-80012-34567<br>Category Choice: shipping</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View Regex and Choice logit masking in GitHub Notebook ↗</a></p><h4>Pattern 2: Pydantic Schema-Guided Decoding Without Retries</h4><p>1. The Production Problem</p><p>Extracting complex nested data structures (like invoices with line items and numerical constraints) requires 100% syntactically valid JSON on the first pass without relying on slow retry loops.</p><p>2. Why Naive Prompting Fails</p><p>Under context pressure, models omit closing quotes, truncate JSON strings, or drop mandatory fields, causing json.loads() to raise JSONDecodeError.</p><p>3. The Outlines Solution</p><p>Outlines converts Pydantic JSON Schemas directly into a JSON FSA guide. Every bracket, field key, quote, and value type is governed by the state machine, guaranteeing zero syntax errors.</p><p>4. Focused Code</p><pre>from typing import Literal<br>from pydantic import BaseModel, Field<br>class LineItem(BaseModel):<br>    description: str<br>    quantity: int = Field(gt=0)<br>    price: float = Field(gt=0)<br>class Invoice(BaseModel):<br>    invoice_number: str<br>    customer_name: str<br>    items: list[LineItem]<br>    payment_status: Literal[&quot;paid&quot;, &quot;pending&quot;, &quot;overdue&quot;]<br># Generate JSON strictly governed by the Invoice FSA (max_new_tokens prevents truncation)<br>result_json = local_model(f&quot;Extract invoice: {invoice_text}&quot;, <br>                          Invoice, max_new_tokens=512)<br>invoice = Invoice.model_validate_json(result_json)</pre><p>5. Executed Console Output</p><pre>Parsed Invoice Object:<br>Invoice #: INV-2011-001 | Customer: ABC Corp. | Status: pending<br>Line Items: 1x Wireless Mouse @ $25.00</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View Pydantic schema-guided decoding in GitHub Notebook ↗</a></p><h4>Pattern 3: Context-Free Grammar (CFG) SQL Codegen</h4><p>Note — this pattern occurs in rare scenarios and requires local models as no cloud based model will allow modifying their generation logic</p><p>1. The Production Problem</p><p>Automated database agents must generate SQL queries that execute without syntax errors on strict database engines.</p><p>2. Why Naive Prompting Fails</p><p>Language models hallucinate invalid SQL syntax, mix up clause orders, or leave string quotes unclosed.</p><p>3. The Outlines Solution</p><p>Outlines uses Lark Context-Free Grammars (EBNF) compiled into pushdown automata to guide logit selection, making SQL syntax errors mathematically impossible.</p><p>4. Focused Code</p><pre>from outlines.types import CFG<br>simple_sql_grammar = r&quot;&quot;&quot;<br>    start: &quot;SELECT &quot; columns &quot; FROM &quot; table_name (&quot; WHERE &quot; condition)?<br>    columns: &quot;*&quot; | CNAME (&quot;,&quot; CNAME)*<br>    table_name: CNAME<br>    condition: CNAME op value<br>    op: &quot;=&quot; | &quot;&gt;&quot; | &quot;&lt;&quot; | &quot;!=&quot;<br>    value: /[0-9]+/ | /&#39;[^&#39;]*&#39;/<br>    CNAME: /[a-zA-Z_][a-zA-Z0-9_]*/<br>&quot;&quot;&quot;<br>sql_result = local_model(&quot;Generate SQL to find users older than 18:&quot;, <br>                        CFG(simple_sql_grammar))</pre><p>5. Executed Console Output</p><pre>SQL Output: SELECT * FROM users WHERE age &gt; 18</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View CFG SQL grammar generation in GitHub Notebook ↗</a></p><h4>FSM Compilation Latency vs. Deterministic Token Guarantees</h4><p>Deploying Outlines in production involves a distinct set of performance trade-offs compared to retry-based architectures:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7gwVR3jqCx_fYoGytCTPZw.png" /><figcaption><strong>Figure 6: Workload Amortization in Constrained Decoding.</strong> <em>By trading an upfront compilation latency at microservice initialization, Outlines removes runtime validation retries and stabilizes tail inference latency during live traffic. (Source: Image by Author)</em></figcaption></figure><ol><li><strong><em>Compilation Latency:</em></strong> Constructing a Finite State Automaton from complex Pydantic schemas or detailed Lark grammars incurs upfront compilation time when the guide object is instantiated. While high-performance Rust bindings (outlines-core) accelerate state graph construction, developers should pre-compile and cache FSM guides at microservice startup rather than compiling them per request.</li><li><strong><em>Inference Engine Support:</em></strong> Token-level logit masking requires direct access to vocabulary probabilities during decoding. This is supported natively on local model runners (transformers, vLLM). When integrating with production inference engines like vLLM, passing parameters such as guided_grammar or guided_json leverages Outlines under the hood to deliver high-throughput, deterministic outputs.</li></ol><h3>4. Deep Dive: DSPy (Programming Instead of Prompting)</h3><p>Traditional LLM pipelines rely heavily on hand-crafted prompt strings containing hardcoded system instructions, few-shot examples, and formatting tricks. When the underlying LLM model, target domain, or dataset distribution changes, these brittle strings break, forcing engineers into tedious manual re-prompting loops.</p><p><a href="https://dspy.ai/current/getting-started/program-dont-prompt/">DSPy </a>(Declarative Self-improving Python) replaces string-based prompt engineering with an abstraction layer inspired by PyTorch. In DSPy:</p><ol><li><strong>Signatures </strong>define <em>what</em> a task does declaratively (input -&gt; output) rather than <em>how</em> to prompt for it.</li><li><strong>Modules </strong>(dspy.Predict, dspy.ChainOfThought, dspy.ReAct) translate signatures into dynamic prompt transformations and manage control flow.</li><li><strong>Teleprompters / Optimizers</strong> (BootstrapFewShot, MIPROv2, GEPA) treat system prompts and few-shot demonstrations as compilable hyperparameters. They systematically evaluate and search candidate prompts against an objective, code-defined metric function.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*--nUPclXG4st3U3xMf2C2Q.png" /><figcaption><strong>Figure 7: DSPy Compilation Abstraction.</strong> <em>Modular program assembly: task contracts (</em><em>Signature) and execution flows (</em><em>Module) are decoupled from string prompts, enabling teleprompters (</em><em>MIPROv2, </em><em>GEPA) to optimize prompt instructions and few-shot examples programmatically against code-defined metrics. (Source: Image by Author)</em></figcaption></figure><h4>Core Patterns &amp; Walkthrough</h4><h4>Pattern 1: Declarative Signatures &amp; Chain-of-Thought</h4><p>1. The Production Problem</p><p>Hardcoded prompt strings containing instructions and formatting examples are fragile. Swapping the base LLM or updating the task breaks the prompt, requiring manual re-engineering.</p><p>2. Why Naive Prompting Fails</p><p>Manual prompt tuning does not scale across multiple models or changing enterprise domains.</p><p>3. The DSPy Solution</p><p>DSPy decouples task intent from prompt strings using dspy.Signature (question -&gt; answer). dspy.ChainOfThought automatically injects step-by-step reasoning fields before generating the answer.</p><p>4. Focused Code</p><pre>import dspy<br>lm = dspy.LM(&quot;openai/gpt-4o-mini&quot;)<br>dspy.configure(lm=lm)<br>class QuestionAnswering(dspy.Signature):<br>    &quot;&quot;&quot;Answer questions with short factual responses.&quot;&quot;&quot;<br>    question: str = dspy.InputField()<br>    answer: str = dspy.OutputField()<br>cot = dspy.ChainOfThought(QuestionAnswering)<br>res = cot(question=&quot;If a train travels 90 m/h for 2.5 hours, how far does <br>          it go?&quot;)</pre><p>5. Executed Console Output</p><pre>CoT Reasoning: To find the distance, multiply speed by time: <br>                                     90 m/h * 2.5 hours = 225 miles.<br>CoT Answer: 225 miles</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View DSPy Signatures and CoT in GitHub Notebook ↗</a></p><h4>Pattern 2: ReAct Tool Agent Loops</h4><p>1. The Production Problem</p><p>Complex multi-step queries (such as web research followed by math calculations) require orchestrating tool calls without getting stuck in infinite loops or hallucinating math.</p><p>2. Why Naive Prompting Fails</p><p>Hardcoding tool-invocation prompt templates leads to fragile parsing failures when tool signatures change.</p><p>3. The DSPy Solution</p><p>dspy.ReAct manages the Thought ➔ Action ➔ Observation loop declaratively, executing Python tool functions with iteration safeguards.</p><p>4. Focused Code</p><pre>def search_web(query: str) -&gt; str:<br>    return f&quot;Search results for &#39;{query}&#39;: US GDP 2025 = $30.7T, <br>      population = 330M&quot;<br><br>def calculator(expression: str) -&gt; str:<br>    return str(eval(expression))<br><br>agent = dspy.ReAct(&quot;question -&gt; answer&quot;, tools=[search_web, calculator], <br>  max_iters=5)<br><br>result = agent(question=&quot;What is the GDP per capita of US in 2025?&quot;)</pre><p>5. Executed Console Output</p><pre>[Thought 1]  : Search US GDP and population in 2025.<br>[Action 1]   : search_web(&#39;US GDP 2025&#39;)<br>[Observation]: US GDP 2025 = $30.7T, population = 330M<br>[Thought 2]  : Calculate 30.7e12 / 330e6 using calculator.<br>[Action 2]   : calculator(&#39;30.7e12 / 330e6&#39;)<br>[Observation]: 93030.30303030304<br>[Final Answer]: $93,030.30</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View ReAct agent execution in GitHub Notebook ↗</a></p><h4>Pattern 3: Automated Few-Shot Prompt Compilation (BootstrapFewShot &amp; MIPROv2)</h4><p>1. The Production Problem</p><p>Finding optimal system prompts and representative few-shot demonstrations by hand takes weeks of manual trial-and-error.</p><p>2. Why Naive Prompting Fails</p><p>Human engineers cannot efficiently explore the massive combinatorial space of system instructions and demonstration pairs.</p><p>3. The DSPy Solution</p><p>DSPy Optimizers (BootstrapFewShot, MIPROv2) treat prompts as code hyperparameters. They run Bayesian or genetic search against an objective Python metric function to synthesize optimal prompts automatically.</p><p>4. Focused Code</p><pre>from dspy.teleprompt import BootstrapFewShot<br>def answer_metric(example, pred, trace=None):<br>    expected = set(example.answer.lower().split())<br>    predicted = set(pred.answer.lower().split())<br>    return 1.0 if len(expected &amp; predicted) / len(expected) &gt;= 0.5 else 0.0<br>teleprompter = BootstrapFewShot(metric=answer_metric, max_bootstrapped_demos=2)<br>compiled_program = teleprompter.compile(SimpleQA(), trainset=trainset)</pre><p>5. Executed Console Output</p><pre>Compilation Complete! Bootstrapped 2 high-scoring demonstrations.<br>Compiled Program Output: DSPy is a framework for programming language models.</pre><p>👉 <a href="https://www.google.com/url?sa=E&amp;q=https%3A%2F%2Fgithub.com%2Fmohitagr18%2FLLMENGG%2Fblob%2Fmain%2FStructured_LLM_Engineering.ipynb">View DSPy teleprompter compilation in GitHub Notebook ↗</a></p><h4>How DSPy Replaces Manual Prompt Engineering with Programmatic Tuning</h4><p>DSPy fundamentally changes the developer workflow for building production LLM systems:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*etrPgYLcaC72294xVHylnQ.png" /><figcaption>Table 1: Manual Prompt Engineering vs. DSPy Programmatic Compilation.</figcaption></figure><p>By treating prompts as compilable artifacts, DSPy shifts AI engineering from fragile text wrangling to systematic, reproducible software compilation.</p><h3>5. Architectural Comparison &amp; Decision Guide</h3><p>To select the optimal framework for a production AI engineering stack, software architects must evaluate the structural trade-offs between application-level validation, token-level constrained decoding, and programmatic prompt compilation.</p><h4>Comparative Architectural Matrix</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LxzSqNL5CMblDI-rXEg5GA.png" /><figcaption><strong>Table 2: Comparative Architectural Matrix Across Paradigms.</strong> Side-by-side architectural evaluation of Instructor, Outlines, and DSPy across their primary enforcement layers, output certainty levels, token context overheads, and hosting requirements (closed cloud APIs vs. local/vLLM engines). (Source: Image generated using Google Gemini)</figcaption></figure><h4>Empirical Latency Benchmarks</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GH84AYOewWVZ2BPAlwaRvw.png" /><figcaption><strong>Figure 9: Production Telemetry Profiles Across Paradigms.</strong> Comparison of runtime request latency. (Source: Image generated using Google Gemini)</figcaption></figure><p>To quantify the runtime performance of each framework, we measured average response latencies across 5 trial runs in a standard Google Colab environment (T4 GPU instance):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/868/1*uN-6OtWCpC5QZDYgOA91MA.png" /><figcaption>Table 3: Empirical latency comparison across Instructor, Outlines, and DSPy measured in a Google Colab T4 GPU environment.</figcaption></figure><h4>Key Performance Takeaways:</h4><ul><li><strong>Cloud API Baseline </strong>(1.25s–1.67s): Instructor and DSPy offload heavy transformer computations to cloud providers, yielding fast 1-to-2 second latencies. DSPy incurs a slight overhead (~400ms) over direct extraction because ChainOfThought generates explicit intermediate reasoning tokens prior to the final answer.</li><li><strong>Upfront FSM Startup Cost</strong> (~168ms): Outlines incurs a minor initialization delay to build state automata from Regex or Pydantic schemas. In production microservices, this compilation occurs once at server startup and is cached across subsequent requests.</li><li><strong>Local Token Masking Trade-Off</strong> (~14.5s): Sequential token-level logit evaluation on unoptimized local PyTorch models increases generation time. In production environments, serving Outlines via dedicated C++ inference engines like vLLM (--guided-decoding-backend outlines) eliminates this overhead to deliver zero-retry deterministic outputs at native hardware speeds.</li></ul><h3>“When to Use What”: Production Decision Guide</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XQEfv-m0m69SEoR9ZDoxqw.png" /><figcaption><strong>Figure 10: Production Framework Decision Tree.</strong> <em>Systematic triage matrix for selecting between DSPy, Outlines, and Instructor based on reasoning complexity, syntax error tolerance, API hosting constraints (closed cloud API vs. self-hosted vLLM), and real-time streaming needs</em>. (Source: Image generated using Google Gemini)</figcaption></figure><h4>1. Use Instructor When:</h4><ul><li>Building unstructured document extraction, invoice parsing, or PII scrubbing microservices on cloud LLMs (OpenAI, Anthropic, Gemini).</li><li>Relying on complex semantic validation rules (e.g., verifying cross-field business logic, checking date ranges, or validating external database keys via Pydantic validators).</li><li>Requiring real-time streaming (Partial[Model]) to deliver fast visual time-to-first-field in frontend user interfaces.</li></ul><h4>2. Use Outlines When:</h4><ul><li>Generating SQL queries, programming code, or custom DSLs where any syntax error breaks downstream execution environments.</li><li>Serving open-weight models on self-hosted inference engines (vLLM) where token-level logit masking eliminates formatting preambles and retries.</li><li>Extracting structured tables and JSON directly from multimodal vision inputs (scanned handwritten documents, complex charts).</li></ul><h4>3. Use DSPy When:</h4><ul><li>Architecting multi-stage RAG pipelines, tool-using ReAct agents, or multi-hop retrieval systems where manual prompt engineering becomes unmaintainable.</li><li>Optimizing system instructions and few-shot examples programmatically against an objective code-defined metric (MIPROv2, GEPA).</li><li>Distilling complex pipeline behavior from expensive proprietary LLMs into small, fine-tuned local models (Llama 3.1 8B) for high-throughput, low-cost serving.</li></ul><h4>4. The Hybrid Production Architecture</h4><p>In modern enterprise AI systems, these frameworks are frequently combined:</p><ul><li><strong>DSPy</strong> compiles and optimizes the high-level orchestration, agent control flow, and retrieval reasoning steps.</li><li><strong>Instructor </strong>validates semantic business rules and handles progressive streaming at the service boundary.</li><li><strong>Outlines </strong>enforces strict token-level grammar logit masking on local vLLM endpoints for low-level SQL and DSL generation steps.</li></ul><h4>References</h4><ol><li>Instructor, Validation &amp; Structured Extraction (2024), Instructor Docs. (<a href="https://python.useinstructor.com/">https://python.useinstructor.com</a>)</li><li>Outlines, Structured Generation &amp; Token Masking (2024), Outlines Docs. (<a href="https://outlines-dev.github.io/outlines">https://outlines-dev.github.io/outlines</a>)</li><li>DSPy, Programming with Assertions &amp; Optimizers (2024), DSPy Docs. (<a href="https://dspy.ai/">https://dspy.ai</a>)</li><li>Pydantic, Schema Validation &amp; Field Validators (2024), Pydantic Docs. (<a href="https://docs.pydantic.dev/">https://docs.pydantic.dev</a>)</li><li>OpenAI, Structured Outputs Guide (2024), OpenAI Platform Docs. (<a href="https://platform.openai.com/docs/guides/structured-outputs">https://platform.openai.com/docs/guides/structured-outputs</a>)</li><li>vLLM, Guided Decoding Architecture (2024), vLLM Docs. (<a href="https://docs.vllm.ai/en/latest/serving/structured_outputs.html">https://docs.vllm.ai/en/latest/serving/structured_outputs.html</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2c7036b1c08a" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/stop-prompting-json-how-to-build-zero-retry-llm-pipelines-2c7036b1c08a">Stop Prompting JSON: How to Build Zero-Retry LLM Pipelines</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[You Shipped an AI Agent to Production Without Testing It. So Did I]]></title>
            <link>https://aiadvances.org/you-shipped-an-ai-agent-to-production-without-testing-it-so-did-i-aae9f02144ca?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/aae9f02144ca</guid>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[langchain]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 18 May 2026 22:22:44 GMT</pubDate>
            <atom:updated>2026-05-18T22:22:44.955Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How I used LangGraph, HITL tests, and evaluation gates to catch workflow failures before they hit production.</em></p><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/aae9f02144ca?source=friends_link&amp;sk=15acf67823bba092b533e8b03585dd4c"><em>friend link</em></a><em>.)</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*t1zyPUzkg0hSl1hjj6M2Fw.png" /><figcaption><strong>Figure 1: </strong>How I caught the approval path bug before production<strong> </strong>(Source: Image generated using Google Gemini)</figcaption></figure><h3>Testing the Workflow, Not Just the Nodes</h3><p>A flagged record reached finalization in production when it should have stopped for human review. The classifier caught the problem, and the finalization step behaved as written, but the workflow still routed the record forward. That is the bug this article is about.</p><p>In production, the record came from OCR-extracted paper timesheet data in a regulated healthcare workflow and should have been held for manual review. The classifier identified the issue, but the graph sent the record ahead anyway. That bug is what made me stop thinking about these systems as a few tested functions and start treating them as control paths that have to be verified end to end.</p><p>To make that failure easy to inspect, I use a simpler expense approval example in the rest of this article. In that version, a $3,500 hotel charge is correctly flagged for review, but the workflow still sends it straight to finalization instead of the approval step. The problem is not inside either node. It is in the route between them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*onxkqWnmMhCXBD6p" /><figcaption><strong>Figure 2:</strong> Incoming records are evaluated by classification rules, routing standard items to final processing and sending flagged transactions to a mandatory supervisor approval gate.</figcaption></figure><h3>Three Test Layers: Unit Checks, Dry Runs, and HITL Tests</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/843/0*BVrr96XEr2jw4Jml" /><figcaption><strong>Figure 3:</strong> This validation strategy has three layers. Unit tests check business rules against plain state dictionaries. Integration tests run the workflow in memory to verify routing and state handoff. Human-in-the-loop tests prove that the graph actually pauses and resumes at the approval boundary. (Source: Image by Author)</figcaption></figure><p>Testing individual node functions is necessary, but it is not enough. A graph can break in ways that make every node-level test pass. In this workflow, three failure modes matter most: the graph can route a flagged expense to the wrong step, state written in one node can fail to reach the next one, and a human-review pause can fail to stop or resume correctly.</p><p>That is why the test suite is layered. Unit tests catch rule errors inside a node. Integration tests catch routing and state handoff problems across the workflow. HITL tests catch failures in the pause-and-resume cycle that a single invoke call will never see.</p><h3><strong>Keeping Rules Separate from the Workflow</strong></h3><p>This test strategy only works if the business rules are not tangled up with the workflow runtime. If changing an approval threshold forces you to start queues, databases, or cloud services just to check one rule, the boundary is wrong.</p><p>In this repo, the dependency direction stays one way. The expense state schema lives in its own module. The node functions import that schema and apply the business rules. The graph layer imports both and defines the workflow. That keeps the policy logic easy to test without bringing up the orchestration layer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*z-qgODxAmDVUUjfd76ZImA.png" /><figcaption><strong>Figure 4:</strong> Architectural one-way dependency (Source: Image by Author)</figcaption></figure><p>That separation matters in day-to-day work. You can test approval rules locally with plain Python dictionaries. You do not need persistence, message infrastructure, or the full graph runtime just to confirm that a threshold or fail-safe still behaves correctly.</p><p>Once the business rules are separated from the workflow runtime, the test strategy becomes easier to organize. We use three layers because each one catches a different kind of failure before release.</p><ul><li>The first layer checks the rules inside individual nodes.</li><li>The second checks routing and state handoff across the workflow.</li><li>The third proves that a flagged transaction actually stops for human review and resumes correctly afterward.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*irJEcqwpRA1zwTmj" /><figcaption><strong>Figure 5</strong>: The test strategy has three layers. Unit tests check rule logic in isolation. Integration tests verify workflow routing in memory. HITL tests confirm that execution pauses and resumes at the approval boundary. (Source: Image by Author)</figcaption></figure><h3>Layer 1: Policy Rules in Unit Tests</h3><p>Unit tests check the rules that should never wobble. They answer simple questions: does a $500 expense get flagged, and does a missing approval decision fail closed?</p><p>Here, the tests call the node functions directly instead of running the full graph. That makes it easy to verify thresholds, vendor checks, and default rejection behavior without mixing in routing concerns.</p><pre># tests/test_unit.py<br>from src.nodes import classify_expense, finalize_expense, HIGH_AMOUNT_THRESHOLD<br><br>def test_amount_exactly_at_threshold_is_flagged():<br>    &quot;&quot;&quot;Verify regulatory boundaries trigger appropriate operational routing flags.&quot;&quot;&quot;<br>    state = _make_state(<br>        vendor=&quot;Marriott&quot;,<br>        category=&quot;lodging&quot;,<br>        amount=HIGH_AMOUNT_THRESHOLD,<br>    )<br>    result = classify_expense(state)<br>    assert result[&quot;risk_flag&quot;] == &quot;HIGH_AMOUNT&quot;<br>    assert result[&quot;requires_approval&quot;] is True<br>def test_fail_safe_missing_approval_decision_defaults_to_rejected():<br>    &quot;&quot;&quot;Ensure ambiguous review payloads default to a protective rejected status.&quot;&quot;&quot;<br>    state = _make_state(<br>        requires_approval=True,<br>        risk_flag=&quot;HIGH_AMOUNT&quot;,<br>        approval_decision=None,<br>    )<br>    result = finalize_expense(state)<br>    assert result[&quot;final_status&quot;] == &quot;rejected&quot;</pre><p>These tests are necessary, but they are not enough. A unit test can prove that classify_expense() sets requires_approval = True. It cannot prove that the workflow actually routes that record to the approval gate instead of skipping ahead.</p><h3>Layer 2: Dry Runs in Integration Tests</h3><p>Integration tests cover the part unit tests cannot see: the handoff between steps. They run the compiled graph and check that state moves through the workflow the way the design says it should.</p><p>In this layer, the graph uses in-memory storage. Each test run gets a unique thread ID so parallel runs do not collide. That lets you test the real path through the workflow without introducing cross-test state leakage.</p><pre># tests/test_integration.py<br>import uuid<br>import pytest<br>from src.graph import build_graph<br><br>@pytest.fixture<br>def graph():<br>    &quot;&quot;&quot;Provision an isolated runtime execution engine using in-memory storage.&quot;&quot;&quot;<br>    return build_graph()<br>def _unique_thread() -&gt; dict:<br>    &quot;&quot;&quot;Inject dynamic tracking identifiers to prevent concurrent state corruption.&quot;&quot;&quot;<br>    return {&quot;configurable&quot;: {&quot;thread_id&quot;: f&quot;integ-{uuid.uuid4().hex}&quot;}}<br>def test_small_meal_clears_in_single_invoke(graph):<br>    &quot;&quot;&quot;Confirm low-risk transactions successfully complete automated routing paths.&quot;&quot;&quot;<br>    config = _unique_thread()<br>    result = graph.invoke(_clean_expense(amount=35.00), config)<br>    assert result[&quot;final_status&quot;] == &quot;cleared&quot;<br>    assert result[&quot;requires_approval&quot;] is False</pre><p>This gives you confidence that a low-risk expense can move from classification to completion in one pass. It still does not prove the hardest part: that a flagged expense stops and waits for a human.</p><h3>Layer 3: HITL Verification</h3><p>The approval gate is the control that matters most in this workflow. If the graph does not stop there, the rest of the design does not matter.</p><p>That is why the HITL tests use a two-step pattern. First, the test sends in a flagged expense and checks that execution pauses. Then it resumes the same suspended run with a human decision and verifies the final state.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/915/0*QTMArh8VthdALQe6" /><figcaption><strong>Figure 6. Human-in-the-loop test flow for pause and resume.</strong> The workflow saves state, pauses at the approval step, resumes with a reviewer decision, and then writes the final result and audit trail. (Source: Image by Author)</figcaption></figure><p>The first check is simple and strict. A flagged transaction must return __interrupt__. If it does not, the workflow did not stop at the approval boundary.</p><pre># tests/test_hitl.py<br>def test_interrupt_is_present_in_step1_result(self, graph):<br>    &quot;&quot;&quot;Step 1: Confirm system execution suspends reliably at manual checkpoints.&quot;&quot;&quot;<br>    config = _unique_thread()<br>    result = graph.invoke(_flagged_expense(), config)<br><br>    assert &quot;__interrupt__&quot; in result, (<br>            &quot;Operational Failure: The engine failed to halt execution for a flagged record, &quot;<br>            &quot;allowing unauthorized data bypass.&quot;<br>        )</pre><p>The second check resumes the same run with a manager decision. Using the same thread ID matters because the graph has to reload the suspended state, apply the approval input, and continue from the correct point.</p><pre># tests/test_hitl.py<br>from langgraph.types import Command<br><br>def test_classification_fields_visible_after_resume(self, graph):<br>    &quot;&quot;&quot;Step 2: Confirm suspended state persistence and accurate downstream resumption.&quot;&quot;&quot;<br>    config = _unique_thread()<br>    expense_id = &quot;EXP-TWOPART&quot;<br>    # Step 1: Drive execution forward until reaching the mandatory regulatory stop<br>    graph.invoke(_flagged_expense(expense_id=expense_id, amount=900.00), config)<br>    # Step 2: Provide authorization instructions to resume from persistent storage<br>    final = graph.invoke(<br>        Command(resume={&quot;decision&quot;: &quot;approved&quot;, &quot;notes&quot;: &quot;CFO pre-approved.&quot;}),<br>        config,<br>    )<br>    # Validate end-to-end data integrity across the suspended execution boundary<br>    assert final[&quot;expense_id&quot;] == expense_id<br>    assert final[&quot;risk_flag&quot;] == &quot;HIGH_AMOUNT&quot;<br>    assert final[&quot;approval_decision&quot;] == &quot;approved&quot;<br>    assert final[&quot;final_status&quot;] == &quot;approved&quot;</pre><p>If this test passes, you know more than “the code works.” You know the graph paused at the right place, preserved the pre-review state, accepted the human decision, and finished the transaction on the expected path.</p><h3>Using Evaluation as a Release Gate</h3><p>Tracing tells you what happened in one run. It does not tell you whether the system made the right decision. A workflow can execute cleanly, emit logs, and still approve the wrong expense. That is why tracing is useful for debugging, but not enough for a release gate.</p><p>Evaluation answers a different question. Instead of inspecting one trace, you run the workflow against a fixed set of labeled cases and score the outputs against expected results. That gives you something tracing cannot: a repeatable check for policy drift across builds.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/870/1*kaMn6doPVqX9wT9FZJOhGA.png" /></figure><p>The evaluation set lives in eval/data/expense_eval_dataset.json. It includes ten labeled examples that cover the main classification paths, including the threshold boundary. One case checks that an expense at exactly $500.00 requires review. Another checks that $499.99 clears automatically. Those two cases matter because threshold regressions often show up first at the edge, not in the middle of the range.</p><p>The CI pipeline uploads that dataset once and runs evaluators against workflow outputs in LangSmith. Each evaluator checks one field instead of collapsing everything into a single vague pass or fail.</p><ul><li>One verifies the risk flag.</li><li>One checks whether the workflow required approval.</li><li>One checks the final status for auto-cleared cases.</li></ul><p>That split makes it easier to see what changed when a build regresses.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WrpLk4Ki5hHIQnECWRZMTA.png" /><figcaption><strong>Figure 7. LangSmith evaluator run details for the expense workflow.</strong> Each evaluator scores one output field separately, which makes it easier to see whether a regression affects risk classification, approval routing, or final status. (Source: Langsmith Screenshot)</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*lOLPmFr-WIkVykgn" /><figcaption><strong>Figure 8:</strong> The evaluation pipeline runs a versioned dataset through the workflow and scores the outputs before release. Technical detail: the evaluators check returned fields from the baseline runs and compute pass rates without simulating the later resume step. (Source: Image by Author)</figcaption></figure><p>This catches failures that tracing will never flag on its own. Suppose an engineer changes HIGH_AMOUNT_THRESHOLD from $500 to $750. The code still runs. The traces still look clean. Nothing crashes. But the behavior is now wrong for your policy. In that build, the $500 boundary case starts clearing automatically instead of requiring review. The evaluation score drops, and CI blocks the release.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kF0SW65pqOF9Wht2YzLRCQ.png" /><figcaption><strong>Figure 9. LangSmith experiment summary for the expense evaluation dataset.</strong> The dashboard aggregates evaluator scores, latency, run count, and error rate across the labeled cases, which makes the evaluation suite usable as a release gate rather than a debugging trace. (Source: Langsmith Screenshot)</figcaption></figure><p>That is the point of this layer. It does not replace unit tests or workflow tests. It gives you a build-level check that the business policy still matches the labeled cases you said the system must honor.</p><p>The deployment path should mirror the same state contract you test locally. In this project, the engine is served through the standard configuration in langgraph.json, while the test suite stays deterministic and fast because it does not depend on network calls or live LLM responses. That combination matters for audits and release reviews. You can show the rule tests, the workflow tests, and the dataset scores together instead of asking people to trust a clean trace.</p><h3>Takeaway for Leadership: What Makes an Agent Safe to Deploy</h3><p>Once an agent can approve, route, or finalize a transaction, the question is no longer whether the code runs without errors. The real question is whether the workflow stays inside the controls you intended.</p><p>That is why runtime health is not enough. Clean logs and successful traces can tell you that the system executed. They cannot tell you whether it made the right decision, paused at the right boundary, or drifted away from policy.</p><p>A safer deployment model starts with layers of verification. Unit tests check the rule logic. Integration tests check routing and state handoff across the workflow. Human-in-the-loop tests prove that flagged cases actually stop for review and resume correctly. Evaluation adds one more layer by scoring the workflow against labeled cases before release.</p><p>This is what leadership should ask for before an agent reaches production:</p><ol><li>What rules are tested in isolation?</li></ol><p>2. What workflow paths are tested end to end?</p><p>3. What proves the system pauses for human review when required?</p><p>4. What evaluation gate blocks release if policy behavior drifts?</p><p>That is the standard to use in finance, healthcare, and other high-liability workflows. Do not ask whether the team deployed an agent. Ask what controls, tests, and release gates stand between that agent and a bad write.</p><h4>Try it Yourself</h4><p>The workflow code is available on GitHub. Practitioners can clone the repository to inspect the flow and tune for their own datasets.</p><p>💻 <a href="https://github.com/mohitagr18/langgraph-agent-testing"><strong>Explore the Workflow on GitHub</strong></a></p><h3>References</h3><ol><li>LangChain, Graph API overview (2026), LangChain Docs. (https://docs.langchain.com/oss/python/langgraph/graph-api)</li><li>LangChain, Human-in-the-loop (2026), LangChain Docs. (https://docs.langchain.com/oss/python/langchain/human-in-the-loop)</li><li>LangChain, LangSmith Evaluation (2026), LangChain Docs. (https://docs.langchain.com/langsmith/evaluation)</li><li>Anthropic, Building Effective AI Agents (2024), Anthropic Research. (https://www.anthropic.com/research/building-effective-agents)</li><li>Fowler, M., The Practical Test Pyramid (2018), martinfowler.com. (https://martinfowler.com/articles/practical-test-pyramid.html)</li><li>PaddleOCR 3.0 Technical Report (2025), arXiv. (https://arxiv.org/abs/2507.05595)</li><li>National Institute of Standards and Technology, Artificial Intelligence Risk Management Framework (AI RMF 1.0) (2023), NIST. (https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-ai-rmf-10)</li><li>Administration for Community Living, Electronic Visit Verification: CMS Provides Guidance on “Good Faith Effort” Exemption (2019), ACL.gov. (http://acl.gov/news-and-events/announcements/electronic-visit-verification-cms-provides-guidance-good-faith-effort)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aae9f02144ca" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/you-shipped-an-ai-agent-to-production-without-testing-it-so-did-i-aae9f02144ca">You Shipped an AI Agent to Production Without Testing It. So Did I</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why Naive Chunking Breaks RAG, and What to Build Instead]]></title>
            <link>https://aiadvances.org/why-naive-chunking-breaks-rag-and-what-to-build-instead-f1cc12e60ecf?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/f1cc12e60ecf</guid>
            <category><![CDATA[multimodal]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[retrieval-augmented-gen]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 27 Apr 2026 17:57:31 GMT</pubDate>
            <atom:updated>2026-04-27T17:57:31.223Z</atom:updated>
            <content:encoded><![CDATA[<h4>How layout-aware parsing, visual captioning, and reranking improve retrieval on complex documents.</h4><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/f1cc12e60ecf?source=friends_link&amp;sk=cbe3c1fca5e196eb8d255b072dcbaac4"><em>friend link</em></a><em>.)</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rQJAPt6KhzvZljVOEqLGfQ.png" /><figcaption><strong>Figure 1: </strong>Naive chunking breaks the spatial relationships between tables, figures, formulas, and text; structure-aware processing preserves those links so retrieval can recover the right context.<strong> </strong>(Source: Image generated using Google Gemini)</figcaption></figure><h3>The problem with naive chunking</h3><p>Technical PDFs do not break RAG because they are long. They break because most chunking systems tear apart the structure that gives them meaning.</p><p>A table split across chunks stops being a table. A formula stripped from its layout turns into a jumble of symbols. A chart without its caption is no longer evidence — it is just an image without context.</p><p>That is what naive chunking does. Standard extractors slice documents by page length or character count, then read them as plain text from left to right and top to bottom, even when the document was never meant to be read that way.</p><p>The result is a retrieval system built on broken parts. Instead of returning a complete table row, a linked figure, or a coherent section, the vector database surfaces fragments: half a caption, the wrong column, a detached equation, a paragraph pulled out of sequence.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*wHeWR6BkArIRMn4F" /><figcaption><strong>Figure 2: </strong><em>Slicing a document by size rather than meaning splits tables and charts from their explanatory text. To prevent this, the parser must map the document’s spatial layout using coordinate bounding boxes before extracting the contents. </em>(Source: Image by Author)</figcaption></figure><p>The fix is not better chunk sizing. It is structure-aware parsing that preserves layout, coordinates, and multimodal relationships before anything is embedded or retrieved.</p><h3>Pipeline overview: four phases from PDF to answer</h3><p>To fix the broken layouts and detached content caused by naive chunking, the pipeline must preserve the spatial coordinates of tables, figures, and reading order from the start. It divides this workload into four sequential phases: Parse, Enrich, Ingest, and Retrieve. Each step relies on a local model to process the information and pass structured data or vector records to the next stage.</p><p>In the Parse phase, the pipeline maps the physical layout of the document before extracting any text. <em>PP-DocLayout-V3</em> identifies and assigns coordinate bounding boxes around tables, images, and paragraphs. Once these spatial regions are defined, an optical character recognition model named <em>GLM-OCR</em> extracts the text strictly from within those coordinates. This prevents the text of a sidebar from mixing with the main paragraph. The step outputs a structured JSON file containing the raw text alongside the exact bounding boxes for every element.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cFSgj3pevE1YVTsQaSi1OA.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*N2qI-iZKvVngq4Ulalb9ZQ.png" /><figcaption><strong>Figure 3: </strong>Layout detection maps the physical boundaries of different document elements before reading the text. The PP-DocLayout-V3 model assigns coordinate bounding boxes to tables, figures, and paragraphs to prevent them from being fragmented during extraction.<em> </em>(Source: Image by Author)</figcaption></figure><p>The Enrich phase translates non-text content into searchable descriptions. It extracts the bounded images, tables, and formulas from the structured JSON and passes them to <em>qwen2.5vl:7b</em>, a Vision-Language Model running locally via Ollama. This model writes a text caption for each visual element. The output is an enriched JSON file containing the original structural coordinates, the raw text, and the new captions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*60ejwVlnb3vE__4H" /><figcaption><strong>Figure 4:<em>The four-phase pipeline architecture</em></strong><em>. Arrows show the movement of JSON files and vector records between the local models operating at the layout extraction, image captioning, vector embedding, and retrieval nodes. </em>(Source: Image by Author)</figcaption></figure><p>During the Ingest phase, the enriched JSON files are prepared for storage. The <em>qwen3-embedding:4b</em> model converts the text and captions into vector embeddings, which are arrays of numbers used for similarity search. These numerical vectors, along with the original text chunks and bounding box coordinates, are stored as records in Qdrant, a local database optimized for vector retrieval.</p><p>The Retrieve phase executes when a user submits a query. It converts the question into a vector and searches the Qdrant database for the highest-similarity matches. For non-visual queries, a cross-encoder evaluates and reranks these initial results to filter out weak matches. The highest-scoring text, image, and table chunks are then passed forward as ranked context, preparing the final data for answer generation.</p><h3>Retrieval mechanics: modality boosting and cross-encoder reranking</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ZYRU786Xq0bNadda" /><figcaption><strong>Figure 5: The complete retrieval architecture.</strong> The system executes an initial vector search, applies a mathematical score boost for image chunks if visual keywords are present, and finally reranks the text and table candidates using a cross-encoder. (Source: Image by Author)</figcaption></figure><p>If a user submits a query like <em>“What does the architecture diagram show?”</em> or <em>“Describe the encoder and decoder blocks in the flowchart,”</em> a standard vector search looks for semantically similar text. However, this approach often fails when users specifically ask for diagrams, figures, or images. The vision model that captioned the images during the Enrich phase may have described the target image as “a system architecture with interconnected nodes.” This creates a semantic mismatch: the user asks for a visual format, but the caption only describes the content. To fix this gap, the pipeline uses modality boosting.</p><p>Modality boosting applies a targeted score boost during retrieval. When the pipeline detects visual keywords in the query, such as “diagram,” “figure,” or “flowchart,” it automatically applies a 35 percent score boost to all image chunks in the database. In the repository’s test results, this single adjustment elevated the correct image chunk from rank #7 to rank #1.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*RQbx1GOEXVuBqQxq" /><figcaption><strong>Figure 6: <em>Modality boosting</em></strong><em> applies a targeted score multiplier to image chunks when visual keywords appear in the search query. This adjustment compensates for the vocabulary mismatch between how users ask to view an image and how vision models describe it. </em>(Source: Image by Author)</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*hkYd04egkkinx_kw" /><figcaption><strong>Figure 7: </strong>Retrieval scores before and after the modality adjustment. Applying the 1.35 multiplier to the image chunk increases its score from 0.837 to 1.130, moving it from rank #7 to rank #1. (Source: Image by Author)</figcaption></figure><p>For text and table queries, the pipeline ensures precision through cross-encoder reranking. The initial dense vector search is fast but retrieves a broad list of the top 20 candidate chunks. The system then passes these candidates to the <em>ms-marco-MiniLM-L-12-v2</em> cross-encoder model. This model directly compares the user query against the text of each chunk to calculate a finer-grained relevance score. It reranks the candidates and keeps the top four chunks. In the repo’s test results, this reranking mechanism successfully evaluated queries about “model complexities” and “training costs,” consistently elevating the raw TABLE chunks to Rank #1 over standard text paragraphs.</p><p>The architecture intentionally bypasses this cross-encoder step for visual queries. Cross-encoder models are trained primarily to evaluate dense text paragraphs. In this pipeline’s evaluation, applying cross-encoders to short image captions for visual queries actually degraded ranking quality. For fetching visual content, the modality boost alone achieves higher retrieval accuracy.</p><h4>Evaluation outcomes</h4><p>Running the pipeline against the test queries demonstrates that the combination of structure-aware parsing, boosting, and reranking successfully surfaces the correct modality at the top of the context window.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qIzIImw8Fo_QNarqqg0BVg.png" /></figure><h3>Running the pipeline locally</h3><p>Hosted APIs are the default for many multimodal applications, but this pipeline runs entirely on local hardware. That matters for privacy as much as performance: sensitive documents, embeddings, and queries can remain inside infrastructure the team controls, rather than moving through third-party services. Local execution also makes the system easier to inspect. Developers can open the intermediate JSON artifacts from the Parse and Enrich phases and see exactly how the document was laid out, segmented, and captioned. The result is a pipeline that is easier to debug, easier to reproduce, and easier to trust.</p><p>Execution begins with a central entry point, run_all.py. The parsing and chunking logic is split across phase-specific modules, and this orchestrator calls each stage in sequence: src/phase1_parse.py through src/phase4_retrieve.py.</p><pre>for phase in phases:<br>        print(f&quot;\nPHASE {phase}&quot;)<br>        if phase == 1: run_phase1(pdf_path)<br>        elif phase == 2: run_phase2()<br>        elif phase == 3: run_phase3()<br>        elif phase == 4: run_test_queries()</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a_mR7gbAIE9m80Yp9CwrWA.png" /><figcaption><strong>Figure 8: </strong><em>The repository separates execution logic from configuration settings. A central entry point directs the data flow across isolated phase modules, allowing developers to debug or replace one stage without changing the rest of the pipeline. </em>(Source: Image by Author)</figcaption></figure><p>To support rapid experimentation, the architecture separates configuration from execution. The src/config.yaml file stores the shared settings. Centralizing these variables means that practitioners adapting the repository to their own data can swap an embedding model or point to a new local database directory by editing only one file.</p><pre>models:<br>  embedding: &quot;qwen3-embedding:4b&quot;<br>  llm: &quot;qwen2.5vl:7b&quot;<br>  vlm: &quot;qwen2.5vl:7b&quot;<br>  cross_encoder: &quot;cross-encoder/ms-marco-MiniLM-L-12-v2&quot;</pre><p>By isolating operations into separate files, the repository also makes it easier to modify specific pipeline behaviors without unintended side effects. For example, the retrieval logic resides cleanly in the retrieve phase module. When processing a query, this module evaluates the text for visual keywords and applies the modality boost mathematically.</p><pre>is_vis = bool(set(query.lower().split()) &amp; visual_kw)<br>    if is_vis:<br>        print(&#39;   Visual query - boosting image 35%&#39;)<br>        for hit in results.points:<br>            if hit.payload.get(&#39;modality&#39;) == &#39;image&#39;:<br>                hit.score *= 1.35</pre><p>Keeping this core logic exposed in plain Python makes the retrieval behavior easier to inspect and modify. Developers can tune the visual keyword list, adjust the 35 percent score boost weight, or experiment with new retrieval thresholds to better match the vocabulary and structure of their specific document sets.</p><h3>Conclusion</h3><p>Naive PDF extraction does more than lose formatting. It destroys the relationships that make tables, figures, formulas, and paragraphs meaningful in the first place. A structure-aware pipeline restores those relationships before retrieval begins, and when paired with visual captioning, modality boosting, and reranking, it produces more accurate context for answer generation. Running the stack locally adds another advantage: the system remains inspectable, reproducible, and better suited for sensitive documents.</p><h4>Try it Yourself</h4><p>The pipeline code is available on GitHub. Practitioners can clone the repository to inspect the execution flow or tune the modality boosting weights for their own datasets.</p><p>💻 <a href="https://github.com/mohitagr18/multimodal_rag_article"><strong>Explore the Pipeline on GitHub</strong></a></p><h3><strong>References</strong></h3><ol><li>Sun, X., et al., PP-DocLayout: A Unified Document Layout Detection Model to Accelerate Large Document Understanding (2025), arXiv. (https://arxiv.org/abs/2503.17213)</li><li>Zheng, X., et al., GLM-OCR Technical Report (2026), arXiv. (https://arxiv.org/abs/2603.10910)</li><li>Bai, S., et al., Qwen2.5-VL Technical Report (2025), arXiv. (https://arxiv.org/abs/2502.13923)</li><li>Qwen Team, Qwen3-Embedding: A Text Embedding and Ranking Model Series (2025), GitHub. (https://github.com/QwenLM/Qwen3-Embedding)</li><li>Qdrant Team, Qdrant: High-performance, massive-scale Vector Database (2024), Documentation. (https://qdrant.tech/)</li><li>Nogueira, R., and Cho, K., Passage Re-ranking with BERT (2019), arXiv. (https://arxiv.org/abs/1901.04085)</li><li>Karpukhin, V., et al., Dense Passage Retrieval for Open-Domain Question Answering (2020), arXiv. (https://arxiv.org/abs/2004.04906)</li><li>Lewis, P., et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (2020), arXiv. (https://arxiv.org/abs/2005.11401)</li><li>Ollama Team, Ollama: Run Large Language Models Locally (2024), Documentation. (https://ollama.com/)</li><li>PaddlePaddle Team, PP-DocLayoutV3: Layout Analysis for Non-Planar Document Images (2026), Hugging Face. (https://huggingface.co/PaddlePaddle/PP-DocLayoutV3)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f1cc12e60ecf" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/why-naive-chunking-breaks-rag-and-what-to-build-instead-f1cc12e60ecf">Why Naive Chunking Breaks RAG, and What to Build Instead</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Curing the Enterprise Hallucination Crisis]]></title>
            <link>https://aiadvances.org/curing-the-enterprise-hallucination-crisis-e47cd9f55f51?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/e47cd9f55f51</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[retrieval-augmented-gen]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Tue, 17 Mar 2026 14:14:23 GMT</pubDate>
            <atom:updated>2026-03-17T14:14:23.727Z</atom:updated>
            <content:encoded><![CDATA[<h4>Why Corrective RAG (CRAG) and Self-Reflective loops (SR-RAG) are the missing blueprint for curing enterprise AI hallucinations.</h4><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/e47cd9f55f51?source=friends_link&amp;sk=6964d257f9db7b1cc905fbed2f21691d"><em>friend link</em></a><em>.)</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bzDpjiOm2zBptL9qUzVvJw.png" /><figcaption><strong>Figure 1: The era of the blind AI is over.</strong> To build trustworthy enterprise systems, we have to transform the LLM from a passive writer into a relentless editor, catching its own hallucinations before they reach the user. (Source: Image generated using Google Gemini)</figcaption></figure><h3>The Enterprise Hallucination Crisis</h3><p>Drop a standard generative AI into a corporate data workflow, and its fragility is instantly exposed. Forget sci-fi scenarios; the real hallucination crisis is happening right now in the mundane labyrinth of enterprise compliance, intake, and scheduling.</p><p>Imagine a coordinator using an internal AI to check if a patient’s care plan complies with a new state guideline. If that system relies on “Basic RAG” (Retrieval-Augmented Generation) — which just hunts the database for documents with a similar “vibe” to the user’s query — that coordinator is flipping a dangerous coin.</p><p>When Basic RAG feeds incomplete or “vibey” data to an LLM, it fails in one of two ways:</p><ul><li><strong>The Confident Liar:</strong> The AI wants to be helpful, so it guesses to fill the gaps in its knowledge. In an enterprise, this isn’t a funny quirk — it’s a compliance breach waiting for an audit.</li><li><strong>The Truthful Bureaucrat:</strong> The AI is instructed not to lie, so when it doesn’t see an exact match, it flatly replies: <em>“The provided context does not mention this protocol.”</em> Safe, but your workflow is now completely dead.</li></ul><p>In a high-stakes environment, “I don’t know” is a massive bottleneck, and a confident guess is a disaster.</p><p>We don’t need AI that just reads text. We need AI that audits its own findings, realizes when it’s missing data, and relentlessly hunts for the truth. The good news? We can build this. In this master blueprint, we will cure <strong>AI Amnesia</strong>, stop <strong>Query Drift</strong>, and design a system that gracefully avoids <strong>Binary Failure</strong>. (And if you just want to skip the theory, the full, open-source code for this self-correcting pipeline is waiting for you on GitHub at the end of this article).</p><p>But to understand how to fix it, we first have to tear down how we currently build AI.</p><h3>The Architecture of a Relentless Researcher</h3><p>When building generative AI, it’s easy to fall for the “magic prompt” trap. We string together clever adjectives — “You are a strict, highly intelligent compliance officer” — and expect a single LLM to search a database, evaluate results, draft an answer, and double-check its own work.</p><p>It won’t. It will eventually collapse under the cognitive load, hallucinate, or forget what you asked it to do in the first place.</p><p>Building a production-ready agentic system requires abandoning the monolithic brain. You have to start treating your AI as a <strong>Hybrid Organism</strong> — a machine built of specialized, distinct organs that keep each other in check.</p><p>For this pipeline, those organs consist of a highly specific tech stack:</p><ul><li><strong>The Brain (Google Gemini):</strong> The core generative engine responsible for evaluating logic and synthesizing the final answer.</li><li><strong>The Memory (Qdrant &amp; Docling):</strong> Qdrant serves as the lightning-fast vector database for internal documents. Docling shreds those documents into clean formats so the AI doesn’t choke on complex PDFs.</li><li><strong>The Senses (Serper):</strong> A real-time web search integration that tethers the system to the outside world when internal documents fall short.</li></ul><p>But simply slapping these tools together in a linear script isn’t enough. The true intelligence of this architecture lies in the central nervous system that connects them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TSWQglcRtdn25bNBnkfVBg.png" /><figcaption><strong>Figure 2: <em>The Anatomy of an Agent. </em></strong>Forget linear scripts. This system uses recursive loops, gatekeepers, and critics to constantly evaluate its own work.(Source: Image by Author)</figcaption></figure><h3>The Gatekeeper: Defining Corrective RAG (CRAG)</h3><p>To understand why this pipeline succeeds where others fail, we need to look at the first half of our architecture: Corrective Retrieval-Augmented Generation (CRAG).</p><p>In a standard setup, the vector database acts like an overeager intern. The moment it finds <em>any</em> document that vaguely matches a search, it dumps it on the LLM’s desk and says, “Write an answer!” The LLM, eager to please, tries to synthesize a response even from completely irrelevant data. This is exactly how confident hallucinations are born.</p><p>CRAG changes this dynamic by putting a bouncer at the door.</p><p>Before the generative “Brain” is allowed to see any retrieved data, a lightweight evaluator grades the relevance of the local context against the user’s original query. If the data is bad, the bouncer doesn’t just pass it along with a warning — it actively corrects the search path.</p><p><strong>The 3-State Routing Logic</strong></p><p>Early CRAG models used a simple binary “Relevant/Irrelevant” system. But enterprise data is rarely binary. Often, a document has related keywords but lacks the specific technical depth needed. If you pass these “close enough” documents through, the AI hallucinates to fill the gaps.</p><p>To solve this, our evaluator uses a nuanced 3-State Routing system:</p><ul><li><strong>Correct:</strong> The local Qdrant database contains a definitive, high-quality match. The bouncer opens the door, and the documents go directly to the Generator. No web calls needed.</li><li><strong>Incorrect:</strong> The local documents are irrelevant (e.g., asking about a 2026 competitor, but the database ends at 2025). The bouncer trashes the local data to prevent hallucinations and triggers a pure Web Fallback (via Serper API) to find the answer externally.</li><li><strong>Ambiguous:</strong> <em>This is the game-changer.</em> The local documents are related but incomplete. Instead of forcing the AI to guess the missing pieces, the system triggers a Hybrid Search. It explicitly merges the partial local snippets with real-time web results to build a complete, fully grounded context window.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jln-f8NuasGT5Wed-xUgDA.png" /><figcaption><strong><em>Figure 3: The CRAG Decision Flow</em></strong><em>. </em>The generative model is never forced to guess. It only drafts an answer when the data passes the ‘Correct’ or ‘Ambiguous’ gate.<em> </em>(Source: Image by Author)</figcaption></figure><p>Only when this gatekeeper is satisfied with the evidence does the system finally draft an answer. But as you’ll see when you dig into the repo, even a perfectly factual answer can be entirely useless.</p><h3>The Critic: SR-RAG and the “Truthful Ignorance” Trap</h3><p>CRAG keeps the garbage out. But what happens when your pristine, verified data simply doesn’t contain the answer?</p><p>Suppose an engineer asks: <em>“Compare legacy Orion specs to the newly announced Starship V3.”</em> The AI checks the internal database. Orion is there; Starship V3 (announced yesterday) is not.</p><p>Eager to be honest, the AI replies: <em>“The provided context does not mention Starship V3.”</em></p><p>In a traditional evaluation, this scores a perfect 1.0 for “Grounding.” It didn’t lie. It didn’t make anything up. It just confidently gave up.</p><p>This is the <strong>Truthful Ignorance</strong> trap. In a production environment, an AI that politely says “I don’t know” and clocks out is a massive bottleneck.</p><p>To fix this, we introduce the second half of the architecture: Self-Reflective RAG (SR-RAG).</p><p>If the generative model is the Writer, SR-RAG is the ruthless Senior Editor (The Critic). Before the user ever sees a response, the Critic intercepts the draft and grades it on two strict axes:</p><ul><li><strong>Grounding (Precision):</strong> Is every single claim factually supported by our documents?</li><li><strong>Utility (Recall):</strong> Did it actually answer the user’s question, or did it just output a useless disclaimer?</li></ul><p><strong>The Recursive Loop</strong></p><p>By separating Grounding from Utility, we break the trap. When the AI submits its “I don’t know” draft, the Critic sees high Grounding but zero Utility. That low Utility score acts as an emergency brake. Instead of delivering a disclaimer, the Critic triggers a Recursive Loop:</p><ol><li><strong>Intercept &amp; Analyze:</strong> The Critic rejects the draft.</li><li><strong>Surgical Rewrite:</strong> It passes the failure to a Query Rewriter, crafting a highly targeted new search (e.g., <em>“Starship V3 payload specs”</em>).</li><li><strong>Web Fallback:</strong> It fires this new query back to the start of the pipeline, hitting the web to hunt down the missing facts.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wSzIBJzDxwDixFZCsFwK9A.png" /><figcaption><strong><em>Figure 4: The SR-RAG Refinement Loop</em></strong><em>. </em>If the Critic detects ‘Truthful Ignorance’ (high grounding, but zero utility), it pulls the emergency brake and forces the system to rewrite the query<em>. </em>(Source: Image by Author)</figcaption></figure><p><em>(Note: If you want to see exactly how to code this Critic intercept, the full routing logic is in the GitHub repo linked below).</em></p><p>But before we let the AI run wild with these recursive loops, we have to fix a dangerous side effect: AI Amnesia.</p><h3>The Anchor: Curing AI Amnesia with Query Decoupling</h3><p>Recursive loops are powerful, but they introduce a dangerous side effect: AI Amnesia.</p><p>When the Critic forces the system to rewrite a search query to find missing data, the AI becomes hyper-focused. This causes <strong>Query Drift</strong>.</p><p>Take our previous prompt: <em>“Compare legacy Orion specs to the newly announced Starship V3.”</em></p><p>The AI realizes it needs Starship data and rewrites the search to <em>“Starship V3 payload specs.”</em> If we pass this mutated query to the final Generator, the AI outputs a brilliant answer about Starship — but completely forgets Orion. It got so obsessed with finding the missing piece that it forgot the original prompt.</p><p>To fix this, our pipeline uses <strong>Query Decoupling</strong>. The moment a prompt enters the system, it is violently split into two isolated data streams:</p><ul><li><strong>The Search Query (The Scalpel):</strong> This string is allowed to mutate. The Rewriter alters it as many times as needed during recursive loops to hunt down specific, missing facts.</li><li><strong>The Original Intent (The Anchor):</strong> This string is locked in a vault. It is completely immune to the search loops.</li></ul><p>When the system finally gathers all the facts and drafts the response, it throws away the mutated search queries and passes <em>only</em> the Original Intent to the Generator. This guarantees that no matter how deep the AI goes to find a specific data point, it always climbs back out to answer your exact, multi-part question.</p><p><em>(Want to see the exact Python logic that handles this split? It is cleanly separated in the repo linked at the bottom).</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GYsTk3sYfxiQJnMbWejX7Q.png" /><figcaption><strong>Figure 5: The Complete Master Blueprint</strong>. With CRAG, SR-RAG, and Query Decoupling combined, the pipeline transforms from a simple retrieval script into a relentless, self-correcting cognitive loop. (Source: Image by Author)</figcaption></figure><h3>Production Realities: Knowing When to Compromise</h3><p>Architecture diagrams are clean. Production is messy. When you build a relentless, self-reflecting AI, you quickly discover that demanding absolute perfection creates a terrible user experience.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WHkH3oezE4GEGRNgJwxvSQ.png" /><figcaption><strong><em>Figure 6: </em>The X-Ray of an Agent</strong>. While architecture diagrams show the theory, an Opik trace reveals the messy production reality of recursive loops, query rewrites, and latency.<em> </em>(Source: Image by Author)</figcaption></figure><p>In early builds, this pipeline suffered from <strong>Binary Failure</strong>.</p><p>Imagine a user asking a two-part question: <em>“What is the maximum payload of legacy Orion, and who is the lead engineer for Starship V3?”</em></p><p>The AI easily finds the Orion payload (Part A). It scours the web but cannot find the name of the new Starship engineer (Part B). Because it failed to answer the <em>entire</em> prompt, the Critic scores the Utility low. The system loops, maxes out its retry limit, and returns a generic error: <em>“I’m sorry, I couldn’t find a grounded answer.”</em></p><p>It threw away perfectly valid data just because it didn’t have the complete picture. In the real world, “all-or-nothing” is a failing strategy.</p><p><strong>The Fix: Best-Effort Delivery</strong></p><p>To make the system usable, I had to teach the AI how to compromise. I implemented a Best-Effort Delivery mechanism:</p><ul><li><strong>The Loop Exhaustion Check:</strong> When the system hits its maximum search retries, it stops looking at the combined Utility score.</li><li><strong>The Grounding Override:</strong> It looks <em>only</em> at the Grounding score. Is the partial information it <em>did</em> find factually true?</li><li><strong>Partial Success:</strong> If the Grounding is high, it delivers the partial answer alongside a specific, generated disclaimer for the missing piece.</li></ul><p>Delivering the Orion specs with a polite note that Starship personnel records are unavailable is infinitely more valuable than a total system failure. <em>(If you want to see how to code this graceful degradation, check the orchestrator logic in the repo).</em></p><h3>Conclusion: From Chatbots to Agents</h3><p>The era of the generative chatbot is over.</p><p>When OpenAI first introduced modern LLMs, we were mesmerized by their ability to write poetry and hold a conversation. But as we integrate these models into the nervous system of enterprise data — whether in healthcare compliance, financial auditing, or legal review — that “creativity” becomes our greatest liability.</p><p>We don’t need an AI that can dream. We need an AI that can audit.</p><p>Building this Corrective and Self-Reflective (CRAG/SR-RAG) pipeline proved a fundamental truth about the next generation of software: Intelligence isn’t just about having the right answers; it is about having a methodology for handling failure.</p><p>To recap the blueprint:</p><ul><li><strong>The Gatekeeper (CRAG)</strong> stops the AI from forcing answers out of irrelevant data.</li><li><strong>The Critic (SR-RAG)</strong> breaks the “Truthful Ignorance” trap, forcing the AI to scour the web when internal documents fall short.</li><li><strong>Query Decoupling</strong> cures AI amnesia, ensuring it never loses sight of the original intent.</li><li><strong>Best-Effort Delivery</strong> teaches the machine to compromise, prioritizing partial, verified truth over binary failure.</li></ul><p>Generative AI is a brilliant, powerful engine. But an engine without a steering wheel, brakes, and a navigation system is just a bomb. This pipeline is the chassis. It transforms a fragile, hallucination-prone text generator into a relentless, self-correcting agent that actually deserves a seat at your enterprise table.</p><p><strong>Stop Trusting. Start Verifying.</strong></p><p>If you are tired of fighting the “Confident Liar” and the “Truthful Bureaucrat” in your own RAG systems, the code is open. You can pull down the full architecture right now — including the Qdrant vector store, Serper web fallback, and the complete recursive loop logic.</p><p>Fork the repo, break it, and build something that thinks before it speaks.</p><p>💻 <a href="https://github.com/mohitagr18/crag-srag-pipeline"><strong>Explore the CRAG/SR-RAG Pipeline on GitHub</strong></a></p><h4>References</h4><ol><li>Yan, S., et al., Corrective Retrieval Augmented Generation (2024), arXiv. (<a href="https://arxiv.org/abs/2401.15884">https://arxiv.org/abs/2401.15884</a>)</li><li>Asai, A., et al., Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection (2023), arXiv. (<a href="https://arxiv.org/abs/2310.11511">https://arxiv.org/abs/2310.11511</a>)</li><li>Lewis, P., et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (2020), arXiv. (<a href="https://arxiv.org/abs/2005.11401">https://arxiv.org/abs/2005.11401</a>)</li><li>Team, G., et al., Gemini 1.5: Unlocking multimodal understanding across millions of tokens of context (2024), arXiv. (<a href="https://arxiv.org/abs/2403.05530">https://arxiv.org/abs/2403.05530</a>)</li><li>Qdrant Team, Qdrant: High-performance, massive-scale Vector Database (2024), Documentation. (<a href="https://qdrant.tech/">https://qdrant.tech/</a>)</li><li>IBM Research, Docling: A Document Processing Library (2024), GitHub. (<a href="https://github.com/DS4SD/docling">https://github.com/DS4SD/docling</a>)</li><li>Serper.dev, Google Search API Wrapper (2024), Documentation. (<a href="https://serper.dev/">https://serper.dev/</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e47cd9f55f51" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/curing-the-enterprise-hallucination-crisis-e47cd9f55f51">Curing the Enterprise Hallucination Crisis</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Fact-Checking the Future: How BGE-M3 is Taming the RAG Hallucination Puzzle]]></title>
            <link>https://aiadvances.org/fact-checking-the-future-how-bge-m3-is-taming-the-rag-hallucination-puzzle-eb5d66db3617?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/eb5d66db3617</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 09 Feb 2026 14:59:24 GMT</pubDate>
            <atom:updated>2026-02-09T14:59:24.165Z</atom:updated>
            <content:encoded><![CDATA[<p><em>We haven’t “cured” AI hallucinations, but we’ve found a way to bridge the semantic gap with surgical precision.</em></p><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/eb5d66db3617?source=friends_link&amp;sk=46b2879d976c9c7382b7de460b174803"><em>friend link</em></a><em>.)</em></p><h3>The Search for the “Needle”</h3><p>Imagine asking a librarian for help with “carbon credit legislation.”</p><p>A traditional librarian might look for those exact three words and come up empty. A slightly more modern one might understand you’re interested in the broader “vibe” of climate policy but give you something too generic.</p><p>But a <strong>truly expert researcher</strong> knows that to find the truth, they need to understand your intent. They know that a technical document about “offsetting protocols” might be the exact needle you’re looking for, even if the phrase “carbon credit” never appears on the page.</p><p>In the world of Retrieval-Augmented Generation (RAG) — the technology that allows AI to look up facts before it speaks — we have been stuck with librarians who only read book titles. This is the “semantic gap.” It’s why AI often feels like it’s guessing; it grasps the general theme but fumbles the precise, technical details that are the difference between a breakthrough and a hallucination.</p><p>Enter <strong>BGE-M3</strong>, a breakthrough from the Beijing Academy of Artificial Intelligence (BAAI). It isn’t just another incremental update; it is a unified “Swiss Army Knife” designed to finally bridge the gap between human intent and technical exactness. It doesn’t just look for keywords — it understands the soul of the query.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*S4DIYJLisVQXzX8hojXhtQ.png" /><figcaption><strong>Figure 1: Moving from Keyword Matching to Cognitive Understanding </strong>— This graphic contrasts the old “Standard Library Search” with the new “Team of Specialized Researchers” approach. (Source: Image generated using Google Gemini)</figcaption></figure><h4>RAG 101: The Baseline</h4><p>To appreciate the “Triple-Threat” of BGE-M3, we first have to understand the <strong>Open-Book Exam</strong>.</p><p>At its core, RAG is a three-step choreography designed to keep AI grounded in reality:</p><ul><li><strong>Retrieval:</strong> The AI scans a massive database for relevant “chunks” of text.</li><li><strong>Augmentation:</strong> It pins those chunks to your question like a high-tech cheat sheet.</li><li><strong>Generation:</strong> It hands that cheat sheet to a Large Language Model to write a factual answer.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QZUmlqS12a02YYN1Do4ATA.png" /><figcaption><strong>Figure 2: The “Open-Book Exam” Architecture -</strong> How RAG consults a local knowledge base to ground AI responses in reality before the first word is generated. (Source: Image by Author)</figcaption></figure><p>In a standard “Vanilla” RAG system, this search is powered by <strong>Dense Retrieval</strong>. Your query is turned into a long string of numbers — a vector — representing its general meaning. If you ask how to fix a leaky faucet, the system looks for other vectors in the “plumbing” neighborhood of its mathematical map.</p><p>It is fast and intuitive, but it has a fatal flaw: <strong>it squashes information</strong>.</p><p>By forcing an entire paragraph into a single point on a map, the system often loses the specific serial numbers, rare technical terms, or unique product IDs that are the difference between a helpful answer and a hallucination. BGE-M3 changes the game by refusing to squash that data, doing the work of three separate systems in one unified pass.</p><h3>The Retrieval Trilemma</h3><p>In the quest for the perfect search system, engineers have traditionally been haunted by a “pick two” scenario. To build a system that is fast, jargon-accurate, and capable of deep context, you usually had to deploy three different types of technology simultaneously.</p><p>This is the <strong>Retrieval Trilemma</strong>. To understand the breakthrough, you have to meet the three players on the field:</p><ul><li><strong>The Speedster (Dense Retrieval):</strong> This is your “fast-thinking” generalist. It understands that “canine” and “dog” are essentially the same thing, scanning millions of documents in milliseconds. But because it compresses everything into a single mathematical point, it’s prone to “hallucinating” connections or missing a specific serial number.</li><li><strong>The Keyword Hunter (Sparse Retrieval):</strong> This is the classic index. It is the best tool for finding exact technical terms or unique product IDs. However, it is “lexically brittle” — if you search for “faucet repair” and the document says “tap maintenance,” it will find absolutely nothing.</li><li><strong>The Scholar (Multi-Vector Retrieval):</strong> This is the gold standard for accuracy. It looks at every single word in your query and compares it to every single word in a document. It is the most precise method we have, but it is computationally “heavy.” Using it to search a massive library is like trying to proofread every book on a shelf just to find one specific sentence. It is simply too slow for a first-pass search.</li></ul><p>Until BGE-M3, solving this meant managing three separate models on three different servers — a “Frankenstein” architecture that was as expensive to maintain as it was fragile.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/949/1*UALc6pMgFbZO9sK7jyGTNA.png" /><figcaption><strong>Figure 3: The Retrieval Trilemma</strong> — The traditional trade-off between semantic understanding (Dense), keyword precision (Sparse), and computational speed. (Source: Image by Author)</figcaption></figure><h3>The BGE-M3 “Triple-Threat”: One Model to Rule Them All</h3><p>BGE-M3’s primary breakthrough is its refusal to compromise. Instead of forcing you to choose between speed and precision, it performs all three retrieval tasks — the Generalist, the Hunter, and the Scholar — simultaneously, using a single <strong>Unified Encoder</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/999/1*ehrBnv_efLAOlWOjHd9iLg.png" /><figcaption><strong>Figure 4: The Swiss Army Knife of Search </strong>— How the BGE-M3 transformer processes a single input into Dense, Sparse, and Multi-Vector representations. (Source: Image by Author)</figcaption></figure><p>This is an engineering marvel. In the “Frankenstein” era, running three separate models would triple your memory requirements and slow your pipeline to a crawl. BGE-M3 manages this within a remarkably light footprint — roughly <strong>2GB of VRAM</strong>. It brings state-of-the-art, enterprise-grade search to a standard developer laptop.</p><p>Here is how the “Triple-Threat” works in a single forward pass:</p><ul><li><strong>The Dense Mode (The “Vibe Check”):</strong> It creates a 1024-dimensional map of your query. This is your high-speed recall, narrowing down millions of documents to a few hundred candidates in milliseconds by finding the general “neighborhood” of your answer.</li><li><strong>The Sparse Mode (The “Jargon Hunter”):</strong> When the search gets technical, a “vibe” isn’t enough. This mode uses learned term weights to find specific technical terms or rare vocabulary — like “hyper-threading” or a unique product ID — that a generalist might overlook.</li><li><strong>The Multi-Vector Mode (The “Scholar”):</strong> Adapted from the sophisticated ColBERT architecture, this mode doesn’t squash paragraphs. It keeps a mathematical signature for every single word, using the <strong>MaxSim (Maximum Similarity)</strong> operator to cross-reference your query with surgical precision.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/954/1*Tuo8-LkW32ugQnXMvYXxJA.png" /><figcaption><strong>Figure 5: The Triple-Threat Matrix</strong> — Sparse mode utilizes SPLADE-like term weights to ensure rare vocabulary acts as a “magnet” for technical queries. (Source: Image by Author)</figcaption></figure><p>By unifying these three modes, BGE-M3 ensures that the most relevant facts aren’t just found — they are promoted to the very top with undeniable accuracy.</p><h4>The Multi-Vector Mode: The “Scholar” (ColBERT)</h4><p>While the other modes find the “neighborhood” or hunt for specific “keywords,” the <strong>Multi-Vector Mode</strong> — the Scholar — is where the real magic happens.</p><p>Instead of squashing a paragraph into one single point on a map, BGE-M3 keeps a distinct mathematical signature for every single word. This is the <strong>ColBERT</strong> architecture in action, and it’s why the AI can understand nuances that other systems miss.</p><p>Think of it as a many-to-many investigation. For every individual word in your query, the model shines a spotlight across the entire document to find the single best match — the <strong>Maximum Similarity (MaxSim)</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rp6tP80jqv5sB6I8FRGbzQ.png" /><figcaption><strong>Figure 6: The MaxSim Operator</strong> — A token-level matching matrix that calculates the SIMs score by finding the best match for every word in the query. (Source: Image generated using Google Gemini)</figcaption></figure><p>The model then sums these individual “perfect matches” to produce a final <strong>SIMs Score</strong>.</p><p>Why does this matter? Because it prevents the meaning of a sentence from being lost in a single average. By comparing word-to-word relationships, the SIMs score ensures that the most relevant facts — those that truly answer the specific nuances of your question — are promoted to the very top. It turns the AI from a generalist into a specialist who has truly read the fine print.</p><h3>Global by Design: The Multilingual Breakthrough</h3><p>In the past, building a search system for a global enterprise was an operational nightmare. If you wanted your AI to work in English, Spanish, and Hindi, you were forced to maintain three separate models and three separate databases.</p><p>If a user asked a question in French but the answer was buried in an English technical manual, you had to insert a “translation layer” into the middle of your pipeline. This added latency, increased costs, and introduced the constant risk of “lost in translation” errors.</p><p>BGE-M3 eliminates this friction entirely. It was trained on a massive corpus covering over 100 languages, making it one of the most linguistically capable models in existence. But this isn’t just about “knowing” many languages; it’s about the concept of a <strong>Shared Embedding Space</strong>.</p><p>In BGE-M3’s mathematical “galaxy of meaning,” the English word “Dog,” the Spanish “Perro,” and the Hindi “कुत्ता” (Kutta) don’t just have similar meanings — <strong>they are mapped to the exact same coordinates.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/738/1*P24r6ub94qcCYERk7Ki7HQ.png" /><figcaption><strong>Figure 7: <em>The Shared Embedding Space</em></strong><em> — Because BGE-M3 understands concepts rather than just strings of text, different languages are “collapsed” into a single mathematical coordinate, enabling seamless cross-lingual search.</em> (Source: Image by Author)</figcaption></figure><p>This “Multi-Linguality” (the first ‘M’ in M3) allows for true cross-lingual retrieval. A developer can now build an application where a query in one language can retrieve the most relevant facts from a document written in another, with zero extra steps.</p><p>For a global organization, this is the difference between having twenty isolated “islands” of data and having one single, unified sea of knowledge.</p><h3>The Production Pipeline: From Wide Net to Fine Filter</h3><p>Building a world-class retrieval model is a feat of engineering, but for a developer, the real magic happens in the implementation. Knowing how a model works is one thing; knowing how to deploy it without melting your servers is another.</p><p>In production, BGE-M3 is best used as a two-stage choreography: the <strong>“Recall and Rerank”</strong> strategy. Think of this pipeline as a high-stakes filtering process, much like panning for gold. You don’t start by examining every grain of sand under a microscope; you start with a wide sieve to catch anything that looks like a nugget.</p><h4>Stage 1: The Wide Net (Hybrid Recall)</h4><p>When a user asks a question, the system scans millions of documents using Dense and Sparse modes simultaneously. Because these two modes generate different leaderboards, we need a way to fuse them. Engineers typically choose between two “voting” systems:</p><ul><li><strong>Reciprocal Rank Fusion (RRF):</strong> This is the “Consensus Maker.” it ignores raw scores and focuses solely on position. If a document appears at the top of both the “vibe check” and the “jargon hunter” lists, RRF gives it a massive boost. It’s simple, effective, and requires no manual tuning.</li><li><strong>Relative Score Fusion (RSF):</strong> This is the “Precision Scale.” It uses the actual mathematical scores from the model. While more precise, it requires careful normalization to ensure the technical jargon doesn’t accidentally drown out the general meaning.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XpXN93x5bFotlqXfiuJ2Kg.png" /><figcaption><strong>Figure 8: Merging the Streams</strong> — How RRF and RSF act as “judges” to create a single, unified leaderboard from multiple search methods. (Source: Image by Author)</figcaption></figure><blockquote><strong>Pro-Tip: Priming the Pump with HyDE — </strong>Sometimes, a user’s query is too brief for a good search. This is where <a href="https://arxiv.org/pdf/2212.10496"><strong>HyDE</strong></a><strong> (Hypothetical Document Embeddings)</strong> comes in. Before BGE-M3 even starts its search, we ask an LLM to write a “fake” ideal answer. We then use that fake answer as our search query. This gives the Dense mode a much richer “vibe” to track down in the vector space.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/968/1*42uypQNcSLBTW5NP6WXbng.png" /><figcaption><strong>Figure 9: The Imaginary Answer</strong> — HyDE uses an LLM to hallucinate a “perfect” response, then uses that hallucination as a magnet to find the grounded, real-world truth in your database.<strong> </strong>(Source: Image by Author)</figcaption></figure><h4>Stage 2: The Quality Check (Reranking)</h4><p>Now that we have narrowed the field from millions to just the top fifty candidates, we bring in the <strong>Scholar</strong>. We take those finalists and pass them through the Multi-Vector (ColBERT) mode.</p><p>Because we are only analyzing 50 documents instead of 50 million, the computational weight of the MaxSim operator becomes negligible. This stage re-orders the list with surgical precision, ensuring that the absolute best, most contextually accurate facts reach the top.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3UVWthjVidmMQxaoRZubNg.png" /><figcaption><strong>Figure 10: The Production Workflow</strong> — Moving from a high-speed “Wide Net” to a high-precision “Fine Filter” to ensure only the most relevant facts reach the AI. (Source: Image by Author)</figcaption></figure><p>By the time the information reaches the AI for the final answer, it isn’t a messy pile of keywords; it is a curated, verified “cheat sheet.” This drastic reduction in noise is what turns the AI from a creative storyteller into a reliable synthesizer of facts.</p><h3>The BGE-M3 Legacy: From Operational Chaos to Factual Truth</h3><p>In the “Frankenstein” era of RAG, building a production-grade system was a fragile, high-maintenance beast. To get professional results, you had to manage three separate servers running three different models: a dense embedder, a keyword indexer, and a cross-encoder reranker. This tripled the chance of a service outage and required a mountain of expensive GPU memory just to keep the lights on.</p><p><strong>BGE-M3 collapses this stack.</strong> By providing dense, sparse, and multi-vector capabilities in a single, unified footprint, it allows you to run state-of-the-art retrieval on a standard laptop.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*51Hw3dgOmuk4OkjTz8dJ8w.png" /><figcaption><strong>Figure 11: State-of-the-Art on a Budget.</strong> BGE-M3’s unified architecture replaces complex, multi-server stacks with a single, lightweight model that fits within ~2GB of VRAM, bringing high-precision search to standard laptops. (Source: Image generated using Google Gemini)</figcaption></figure><p>But this “Operational Sanity” is just the beginning. The ultimate goal of this precision isn’t just to save money — it’s to change the very nature of how we interact with intelligence.</p><p>When an AI is fed a messy, imprecise list of results, it is forced to “hallucinate” to fill the gaps. It becomes a <strong>Storyteller</strong>, spinning a narrative that <em>sounds</em> true because it doesn’t have the facts to <em>be</em> true. But when we provide a surgically precise “cheat sheet” via BGE-M3, the AI’s role changes fundamentally. It stops being a creator of fiction and starts being a <strong>Synthesizer of Facts</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EzRcmy3jEZn0BpwPJ4N3qQ.png" /><figcaption><strong>Figure 10: The Final Result</strong> — Drastic reduction in hallucinations as the LLM acts as a synthesizer of verified facts rather than a creator of fiction. (Source: Image generated using Google Gemini)</figcaption></figure><p>As we move toward an era of AI agents — systems that don’t just talk, but actually act on our behalf — this level of precision is no longer a luxury. It is a requirement. BGE-M3 represents the end of the “retrieval trade-off,” proving that we can finally have a search system that is as global as the internet, as fast as a click, and as precise as a scholar. We aren’t just fixing a search problem; we are building the foundation of a more trustworthy future.</p><h3>The BGE-M3 Cheat Sheet: A Production Blueprint</h3><p>We’ve covered the “why” and the “how” of this breakthrough. To wrap everything up, here is your high-level blueprint for building a production-grade, “Triple-Threat” RAG system. Use this as your roadmap to transform a vague user request into a verified, factual answer.</p><ol><li><strong>Query Analysis:</strong> Don’t search blindly. Use <strong>HyDE (Hypothetical Document Embeddings)</strong> to generate a “perfect” fake answer first. This gives your search a much richer target to track down in the mathematical vector space.</li><li><strong>Hybrid Retrieval:</strong> Execute parallel <strong>Dense (Vibe)</strong> and <strong>Sparse (Jargon)</strong> searches. This ensures you catch both the general intent and the rare technical terms that a single search method would miss.</li><li><strong>Hybrid Fusion:</strong> Merge the two leaderboards into a single unified list. Use <strong>RRF (Rank-based)</strong> for simple consensus or <strong>RSF (Score-based)</strong> if you need absolute control over the weighting.</li><li><strong>High-Precision Rerank:</strong> Apply the <strong>Multi-Vector (ColBERT)</strong> mode to calculate <strong>MaxSim scores</strong> for your top finalists. This re-orders your results with surgical precision, promoting the “needle” to the very top.</li><li><strong>LLM Generation:</strong> Deliver the final, curated “cheat sheet” to your LLM. With the noise removed, your AI finally stops being a storyteller and starts being a <strong>factual synthesizer</strong>.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nvEsPHq9Y71dBqwe0Ai44w.png" /><figcaption><strong>Figure 11: The Precision Pipeline Cheat Sheet.</strong> How BGE-M3 transforms a vague user request into a verified answer through a four-stage process of query expansion (HyDE), hybrid fusion (Dense + Sparse), token-level reranking (ColBERT/MaxSim), and finally, grounded synthesis. (Source: Image generated using Google Gemini)</figcaption></figure><h4>References</h4><ol><li>Chen, J., et al., <strong>BGE M3-Embedding: Multi-Lingual, Multi-Functionality, Multi-Granularity Text Embeddings Through Self-Knowledge Distillation</strong> (2025), arXiv. (<a href="https://arxiv.org/abs/2402.03216">https://arxiv.org/abs/2402.03216</a>)</li><li>Khattab, O., et al., <strong>ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT</strong> (2021), arXiv. (<a href="https://arxiv.org/abs/2004.12832">https://arxiv.org/abs/2004.12832</a>)</li><li>Gao, L., et al., <strong>Precise Zero-Shot Dense Retrieval without Relevance Labels</strong> (2022), arXiv. (<a href="https://arxiv.org/abs/2212.10496">https://arxiv.org/abs/2212.10496</a>)</li><li>Lewis, P., et al., <strong>Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks</strong> (2021), arXiv. (<a href="https://arxiv.org/abs/2005.11401">https://arxiv.org/abs/2005.11401</a>)</li><li>Formal, T., et al., <strong>SPLADE: Sparse Lexical and Expansion Model for First Stage Ranking</strong> (2022), arXiv. (<a href="https://arxiv.org/abs/2107.05720">https://arxiv.org/abs/2107.05720</a>)</li><li>Xiao, S., et al., <strong>C-Pack: Packaged Resources to Advance General Chinese Embedding</strong> (2024), arXiv. (<a href="https://arxiv.org/abs/2309.07597">https://arxiv.org/abs/2309.07597</a>)</li><li>Cormack, G. V., et al., <strong>Reciprocal Rank Fusion outshines Condorcet and Individual Rank Learning Methods</strong> (2009), SIGIR. (<a href="https://dl.acm.org/doi/10.1145/1571941.1572114">https://dl.acm.org/doi/10.1145/1571941.1572114</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=eb5d66db3617" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/fact-checking-the-future-how-bge-m3-is-taming-the-rag-hallucination-puzzle-eb5d66db3617">Fact-Checking the Future: How BGE-M3 is Taming the RAG Hallucination Puzzle</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Ghost in the Machine vs. The Bear in the Woods]]></title>
            <link>https://aiadvances.org/the-ghost-in-the-machine-vs-the-bear-in-the-woods-e1bd0012a8fb?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/e1bd0012a8fb</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[hiking]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Wed, 21 Jan 2026 18:43:35 GMT</pubDate>
            <atom:updated>2026-01-21T18:43:35.318Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Nature doesn’t have an “undo” button. From $107F heatwaves to “Confident Hallucinations,” here is how I applied the principles of </em><strong><em>Responsible AI</em></strong><em> to build a fail-safe Digital Ranger.</em></p><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/e1bd0012a8fb?source=friends_link&amp;sk=6d44054c6881b6dbe259a66975994e9b"><em>friend link</em></a><em>.)</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*J-Juw-7t4shSfQ-JaIDvxg.jpeg" /><figcaption><strong>Figure 1: </strong>Navigating the geothermal terrain of Bumpass Hell in Lassen Volcanic National Park with my friends. The rewards of the trail are immense, but in a landscape this indifferent, “luck” is never a strategy. (Source: Image by Author)</figcaption></figure><h3>Introduction: The Trailhead</h3><p>The air in the <a href="https://www.blm.gov/visit/stevens-trail-trailhead">American River Canyon</a> wasn’t just hot; it was a 107°F weight that made every breath feel like inhaling a furnace. I was in my 20s — that dangerous age where you believe you’re immortal simply because you’ve never been proven otherwise. My friends and I were sandwiched on a trail the width of a yoga mat: a sheer cliff on one side, a vertical drop on the other.</p><p>When we finally scrambled down to the river to collapse in the shade, we saw her: a mama bear picking her way across the water just 50 yards away. We thought it was a dog until the cubs appeared. The “fearless” version of me evaporated instantly. We survived, but I walked out of that canyon with a permanent scar of understanding: nature is indifferent to your intentions, and it is brutal to the unprepared.</p><p>Today, the stakes have shifted. I am no longer the foolish hiker; I am the designated protector for my family. But in the modern outdoors, I’ve discovered a danger more insidious than a bear: <strong>Bad Data</strong>.</p><p>My wife and I have stood in the biting cold of <a href="https://www.nps.gov/care/index.htm">Capitol Reef</a> in late December, watching my breath fog, only to find every “Open” restaurant on Yelp was shuttered for the season. We have felt the “range anxiety” of driving an EV to Bryce Canyon, praying the one supercharger outside the park was actually working. We have planned winter treks on the <a href="https://www.nps.gov/brca/planyourvisit/fairylandloop.htm">Fairyland Loop</a> based on official reports that said “open,” only to find — buried in a single AllTrails review from 24 hours prior — a photo of deep, impassable mud that would have stranded us.</p><p>Today, planning a safe trip means acting like a detective, toggling between five different apps while praying you didn’t miss a “Closed for Winter” note buried in a PDF. I didn’t want another app that just listed trails. I wanted a <strong>Digital Ranger</strong>. I wanted a system that didn’t just “chat,” but one that could reason through the life-and-death logistics of the physical world.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CJNFc4LyO-vmEyMLx2uQNQ.png" /><figcaption><strong>Figure 2: <em>The Digital Ranger at a glance:</em></strong><em> Moving beyond “generative” text to real-time safety orchestration. This isn’t just a chatbot; it’s a verified data shield for the physical world. </em>(Source: Image by Author)</figcaption></figure><h3>The Architecture of a Ranger</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-FEV4YpzMA0u7LjaCXF6Ag.png" /><figcaption><strong>Figure 3: The Blueprint</strong> - A structural view of the Digital Ranger, from raw data sources to the final user experience. (Source: Image by Author)</figcaption></figure><p>If you walk into a National Park Visitor Center and ask a human ranger, <em>“What’s the weather like on Angels Landing?”</em> they don’t just look at the sky and guess. They look at a specific terminal for the zonal forecast. If you add, <em>“…and can I take my kids?”</em> their entire internal calculus shifts. They are not just retrieving data; they are <strong>Orchestrating Context</strong>.</p><p>To build a digital version of this, a simple chatbot wasn’t enough. A generic Large Language Model (LLM) is a poet; it’s brilliant at describing a sunset but terrible at calculating the logistics of surviving one. For the wild, I needed a <strong>Planner</strong>. I needed a Reasoning Engine that could think: <em>“The user wants to hike The Narrows. It’s raining 20 miles away. That means a flash flood risk. I must check the NPS alert feed, cross-reference the weather API, and potentially override the user’s request.”</em></p><p>This required a shift in architecture. I had to stop treating the AI as a creative writer and start treating it as a <strong>Conductor</strong>.</p><p>I built a central <strong>Orchestrator</strong> that acts as the system’s brain. When you ask a question, the Orchestrator doesn’t answer immediately. Instead, it pauses, analyzes your intent, and dispatches a fleet of specialized “Scouts” to gather ground truth:</p><ul><li><strong>The Scout (NPS Client):</strong> Hits official databases to find trails that are not only beautiful but actually open.</li><li><strong>The Local (Places Client):</strong> Scans for the specific amenities — like that one critical EV supercharger at Bryce — and filters for “Open Now.”</li><li><strong>The Meteorologist (Weather Client):</strong> Calculates the <strong>Lapse Rate</strong> (a 3.5°F drop for every 1,000 feet of gain) to ensure you aren’t caught in a T-shirt when the summit is at freezing.</li><li><strong>The Ground Truth (Review Scraper):</strong> Scours the latest crowdsourced reports for the “mud” or trail damage that official sensors often miss.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OD5LjtIqYe6SnXVvib7UQQ.png" /><figcaption><strong>Figure 4: <em>The Conductor in Action — </em></strong><em>This sequence diagram illustrates how the Orchestrator pauses to gather real-time “Ground Truth” before ever generating a word of advice</em>. (Source: Image by Author)</figcaption></figure><p>The intelligence isn’t in the AI’s ability to speak; it’s in the architecture that binds its “creative” brain to the cold, hard reality of live data.</p><h3>The System Audit (Reality Check)</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sh7SgHsd-h1XzMM4quSd0w.png" /><figcaption><strong>Figure 5: The Goal </strong>- A system that orchestrates every layer of the outdoors — from live weather to previous chat history — into a single, context-aware response. (Source: Image by Author)</figcaption></figure><p>Architecture diagrams are clean; reality is messy. Once I connected my “Agentic Brain” to the live NPS and Google Maps APIs, I didn’t get a perfect digital ranger. I got a <strong>confident liar</strong>.</p><p>To ensure this system was safe for my family, I treated it like a mission-critical product. I ran a full System Audit, logging every failure point where the AI drifted, hallucinated, or crashed. These weren’t just coding errors; they were safety risks. My audit revealed three categories of failure that no simple “prompt engineering” could fix:</p><p>1. <strong>The “Zion Vanishing Act” </strong>— When I asked for trails in Zion, the AI confidently returned a list. But on the map, 65% of the park was missing. The NPS API nests location data inconsistently — sometimes in coordinates, sometimes in complex geometry objects. The LLM simply ignored what it didn’t understand, effectively deleting iconic landmarks like Angels Landing from the user’s world.</p><p>2. <strong>The “Safety False Positive” </strong>— I tested a critical query: “Is the Watchman Trail safe?” The AI saw a “Road Construction” alert nearby but decided the trail itself was fine, answering with a cheerful “Yes.” In reality, there was an active Ice/Snow Warning for that specific elevation. The AI prioritized being “helpful” over being “cautious,” a mistake that could lead a family straight into a hypothermic emergency.</p><p>3. <strong>The “Persona Drift” </strong>— Without strict management, the AI would lose its way. After a few turns of conversation, it would stop acting like a safety-first Ranger and start acting like a generic Wikipedia bot. It “forgot” the mission, dropping the safety constraints I had worked so hard to implement.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BoFbkybpBMkR9Bgceybujw.png" /><figcaption><strong>Figure 6: The Receipts</strong> - A snapshot of the System Audit Traceability Matrix. These weren’t just coding errors; they were safety risks — from mapping failures to hallucinated amenities. (View the full <a href="https://github.com/mohitagr18/outdoor_concierge/blob/main/Issues%20List.xlsx">Audit Matrix on GitHub</a>)</figcaption></figure><p>This audit proved a terrifying truth: in the wild, we cannot trust an LLM to “figure out” safety. If I wanted to protect my family, I had to stop asking the AI to be smart and start <strong>forcing</strong> it to be truthful.</p><h3>The Guardrails</h3><p>In most AI tutorials, the solution to “hallucinations” is a polite request. You are told to plead with the model: <em>“You are a helpful assistant, please don’t lie.”</em> In engineering, and especially in the wilderness, hope is not a strategy.</p><p>I realized that if I wanted to trust this system with my family’s safety, I had to stop treating the AI as a creator and start treating it as a <strong>Transformation Engine</strong>. Its job isn’t to invent facts; its job is to structure the messy, unpredictable reality of the world into a format I can strictly validate.</p><h4><strong>Enter Pydantic.</strong></h4><p>In the world of Python, Pydantic is used for data validation. But when combined with an LLM like Gemini, it becomes a law enforcement agency. By defining rigid “schemas” — strict digital templates — for every trail, weather report, and safety alert, I could force the AI to output data that fits the laws of the physical world. If the AI tries to guess or get “creative” with a trail’s safety status, the system doesn’t just display a warning — it fails loudly and prevents the user from ever seeing the bad data.</p><p>Here is the “Sheriff” in the code. Instead of asking for a general “list of trails,” I enforce a structure that the AI cannot ignore:</p><pre>from pydantic import BaseModel, Field<br>from typing import Literal, Optional<br><br>class TrailStats(BaseModel):<br>    name: str = Field(description=&quot;Official name of the trail&quot;)<br>    difficulty: Literal[&quot;Easy&quot;, &quot;Moderate&quot;, &quot;Strenuous&quot;] # Strict enum<br>    distance_miles: float<br>    status: Literal[&quot;Open&quot;, &quot;Closed&quot;, &quot;Caution&quot;]<br>    hazards: Optional[list[str]] = Field(description=&quot;Specific warnings like &#39;Flash Flood&#39;&quot;)<br><br>    # The magic: Validator logic<br>    @field_validator(&#39;status&#39;)<br>    def check_safety(cls, v, values):<br>        # If the trail is &quot;Open&quot; but we detect ice, force a Caution status<br>        if v == &quot;Open&quot; and &quot;Ice&quot; in values.data.get(&#39;hazards&#39;, []):<br>             return &quot;Caution&quot;<br>        return v</pre><p>This changes everything. This is <strong>Type Safety</strong> for the real world. If the AI tries to describe a trail’s difficulty as “Kind of hard,” the system throws an error because it <em>must</em> be one of the pre-defined categories: Easy, Moderate, or Strenuous.</p><p>The AI provides the raw intelligence, but the code is the <strong>Sheriff</strong>. It ensures that no matter how “creative” the model gets, the output adheres to the strict safety protocols of the physical world. This architecture fixed the “Zion Mapping Failure” overnight; by forcing the response into a strict schema, the system stopped guessing and started rejecting bad data entirely.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*m6CMtM1GZoNmWxhaklubJg.png" /><figcaption><strong>Figure 7: The Full Circle</strong> - From chaotic API data to structured AI reasoning. By wrapping Gemini’s creative power in the architectural constraints of Pydantic, the system moves from ‘guessing’ to ‘knowing’. (Source: Image by Author)</figcaption></figure><h3>The View from the Summit</h3><p>After weeks of wrestling with JSON schemas and “confident” hallucinations, the difference is night and day. In my old workflow, planning a family trip meant a frantic dance between five different browser tabs, three apps, and a constant, low-level anxiety that I had missed a critical “Closed” sign.</p><p>Now, I simply ask the Outdoor Adventure Concierge a single, human question:</p><blockquote>“What are some easy to moderate hikes at Zion and where can I eat after?”</blockquote><p>The system doesn’t just generate text; it <strong>synthesizes a reality</strong>. It doesn’t just guess that the trails are open; it hits the NPS API to verify. It doesn’t just suggest a random burger joint; it checks Google Maps to ensure the kitchen is actually open when you’ll be finishing your hike. It answers the logistical reality of the trip, not just the dream of it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GLwYOLLrGwu4gwZzpAz2Eg.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lqDxnWH9P32SbyQUQQ5dfw.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/885/1*OQIIxlrz50r0-do4RTOWgg.png" /><figcaption><strong>Figure 8: The payoff. </strong>Data Synthesis in Action: The agent retrieves live trail status, filters by difficulty, and pivots to the Google Maps API to find open restaurants nearby. (Source: Image by Author)</figcaption></figure><p>But the intelligence goes deeper than a chat box. The system remembers <strong>who</strong> I am planning for.</p><p>If I toggle “Dog Friendly,” the system instantly filters out 90% of the trails in Zion where pets are banned, saving me the heartbreak of being turned away at the trailhead. If I mention “kids” in the chat, the system doesn’t just recommend a trail; it prioritizes hikes with bathrooms nearby and automatically adds “extra snacks” to the packing list.</p><p>When I load the dashboard, it doesn’t just show me the weather at the Visitor Center; it calculates the <strong>Lapse Rate</strong>. It warns me that a comfortable 70°F at the trailhead might be a freezing 45°F at the summit. It is no longer just a database of maps; it is a Digital Ranger that understands the difference between “open” and “safe.”</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x58MYE9QO3avIYFiudIqsA.png" /><figcaption><strong>Figure 9: The Protector in the Code -</strong> The dashboard displays “Zonal Weather,” warning users that a comfortable 70°F at the start could mean hypothermic conditions at the summit. (Source: Image by Author)</figcaption></figure><h3>Conclusion</h3><p>Years ago, on that sweltering day along the American River, I wasn’t alone. I was with the same group of friends who have stood with me through the rattlesnake-lined trails of Sequoia. My wife has been by my side for countless miles, from witnessing the Milky Way at Glacier Point to watching meteor showers in Death Valley.</p><p>We were lucky that day in the canyon. The mama bear walked away, and we walked out. But as our group has grown — now including young nephews and nieces who look to us for protection — I’ve realized that luck is not a strategy.</p><p>As engineers, we are often seduced by the “magic” of AI — the way it can mimic human conversation or generate a complex packing list in seconds. But when we build for the real world, “magic” is a liability. We don’t need AI that can dream; we need AI that can follow instructions. We need systems that respect the physical reality of a cliff edge, a frozen summit, or a missing supercharger.</p><p>The Outdoor Adventure Concierge evolved into a case study on <strong>Responsible AI</strong>. By wrapping Gemini in the architectural constraints of Pydantic, I learned that the most powerful agents aren’t the ones that are the most “intelligent” — they are the ones that are the most reliable.</p><p>Today, when I plan a trip, I don’t open five tabs. I open one. I trust it not because it is “smart,” but because I know exactly how hard I forced it to tell the truth. For the first time in years, I can focus less on the logistics and more on the view.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HPRTNPLzntzK15HsaEz2_Q.jpeg" /><figcaption><strong>Figure 10: </strong>Overlooking the hoodoos of Bryce Canyon with my wife. By enforcing the principles of Responsible AI, I finally moved past the “range anxiety” and data detective work to focus on what truly matters: the view. (Source: Image by Author)</figcaption></figure><h3>Try It Yourself</h3><p>The wilderness is calling, but don’t go unprepared. You can explore the <strong>Outdoor Adventure Concierge</strong> live demo or dive into the full <strong>System Audit and Pydantic models</strong> on GitHub.</p><ul><li><strong>🚀 </strong><a href="https://outdoorconcierge-ma.streamlit.app/"><strong>Live Streamlit App</strong></a></li><li><strong>💻 </strong><a href="https://github.com/mohitagr18/outdoor_concierge"><strong>GitHub Repository</strong></a></li></ul><h4>References</h4><ol><li>Yao, S., et al., <strong>ReAct: Synergizing Reasoning and Acting in Language Models</strong> (2023), arXiv. (<a href="https://arxiv.org/abs/2210.03629">https://arxiv.org/abs/2210.03629</a>)</li><li>Team, G., et al., <strong>Gemini: A Family of Highly Capable Multimodal Models</strong> (2023), arXiv. (<a href="https://arxiv.org/abs/2312.11805">https://arxiv.org/abs/2312.11805</a>)</li><li>Colvin, S., et al., <strong>Pydantic: Data validation using Python type hints</strong> (2024), Documentation. (<a href="https://www.google.com/search?q=https://docs.pydantic.dev/">https://docs.pydantic.dev/</a>)</li><li>National Park Service, <strong>NPS Developer API Guide</strong> (2024), U.S. Department of the Interior. (<a href="https://www.nps.gov/subjects/developer/index.htm">https://www.nps.gov/subjects/developer/index.htm</a>)</li><li>AllTrails, <strong>National Park Trail Guides &amp; Maps</strong> (2024), Website. (<a href="https://www.alltrails.com/">https://www.alltrails.com/</a>)</li><li>WeatherAPI.com, <strong>Realtime &amp; Forecast Weather API</strong> (2024), Documentation. (<a href="https://www.weatherapi.com/">https://www.weatherapi.com/</a>)</li><li>Serper.dev, <strong>Google Maps Places API Wrapper</strong> (2024), Documentation. (<a href="https://serper.dev/">https://serper.dev/</a>)</li><li>Open-Elevation, <strong>Public Elevation API</strong> (2024), Documentation. (<a href="https://open-elevation.com/">https://open-elevation.com/</a>)</li><li>Firecrawl, <strong>Turn Websites into LLM-ready Markdown</strong> (2024), Documentation. (<a href="https://firecrawl.dev/">https://firecrawl.dev/</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e1bd0012a8fb" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/the-ghost-in-the-machine-vs-the-bear-in-the-woods-e1bd0012a8fb">The Ghost in the Machine vs. The Bear in the Woods</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My RAG Chatbot Approved a $5,000 Dinner: Building the Automaton (Part 2)]]></title>
            <link>https://aiadvances.org/my-rag-chatbot-approved-a-5-000-dinner-building-the-automaton-part-2-2fda360f6312?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/2fda360f6312</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[retrieval-augmented-gen]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 22 Dec 2025 16:34:59 GMT</pubDate>
            <atom:updated>2025-12-22T16:34:59.047Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How to move from “vibe checks” to automated real-time grading with Ragas and Qdrant.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ghsiKKVVumo6RP0_.png" /><figcaption><strong><em>Figure 1: The Chef and the Critic — </em></strong><em>Just like a restaurant, a RAG system needs two parts: a “Chef” that generates answers and a “Supervisor” that grades them before they reach the customer. </em>(Source: Image generated by Google Gemini)</figcaption></figure><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/2fda360f6312?source=friends_link&amp;sk=dae43b9890a56af53c365449e62bbb20"><em>friend link</em></a><em>.)</em></p><h3>Introduction: The Morning After the $5k Dinner</h3><p>In <a href="https://medium.com/@mohitagr18/my-rag-chatbot-approved-a-5-000-dinner-debugging-hallucinations-with-math-part-1-1b2cef8c3ccd">Part 1</a>, I shared the story of how my RAG chatbot — confident, articulate, and completely wrong — hallucinated a policy that approved a $5,000 expensed dinner.</p><p>We popped the hood and realized that “hallucination” is a lazy word. We broke the failure down into two distinct mathematical problems using the <strong>Shopper vs. Chef analogy</strong>:</p><ol><li><strong>The Shopper (Retrieval)</strong>: Did it buy the right ingredients? (Context Precision/Recall).</li><li><strong>The Chef (Generation)</strong>: Did it cook what was asked, or did it sneak in its own spices? (Faithfulness/Answer Relevancy).</li></ol><p>We proved — on paper — that you can calculate a “Trust Score” for every single interaction. But here is the hard truth about production engineering: <strong>Math on paper doesn’t scale</strong>.</p><p>You cannot manually inspect the “ingredients” for thousands of queries a day. You cannot sit there with a calculator checking if the Chef’s answer matches the retrieval vectors. If you rely on manual “vibe checks,” you are one bad retrieval away from another $5,000 mistake.</p><p>We need to automate the math. We need to build a <strong>Supervisor Engine</strong>.</p><p>In this article, we are going to build — from scratch — a production-ready evaluation pipeline using <strong>Streamlit</strong>, <strong>Qdrant</strong>, and <strong>Ragas</strong>. We will build a dashboard that doesn’t just answer questions but grades itself in real-time, effectively automating the “Trust, but Verify” doctrine.</p><p>No more guessing. Let’s write some code.</p><h3>The Architecture: “Trust, but Verify”</h3><p>To catch hallucinations before they happen, we need an architecture that supports two very different workflows:</p><ol><li><strong>The Live Audit (Single-Turn):</strong> A <strong>playground</strong> for single-query inspection. Ask a question (‘Can I expense a helicopter?’) and immediately see the Trust Score gauges.</li><li><strong>The Deep Evaluation (Batch):</strong> A regression testing suite that generates hundreds of questions and runs them all to produce a system-wide health report.</li></ol><p>We are building this as a <strong>Streamlit</strong> application because it gives us the UI components we need (gauges, dataframes, chat interfaces) without the overhead of a React frontend.</p><p><strong>The Tech Stack:</strong></p><ul><li><strong>Orchestration:</strong> LangChain</li><li><strong>Vector Database:</strong> Qdrant</li><li><strong>Evaluation Engine:</strong> Ragas</li><li><strong>LLM:</strong> GPT-4o (The “Chef” and the “Grader”)</li><li><strong>Frontend:</strong> Streamlit</li></ul><p>Here is the project structure we are working with. It is intentionally flat to keep the focus on the logic:</p><pre>rag-qa-ragas/<br>├── app.py                 # The Streamlit Frontend (UI)<br>├── backend.py             # The RAG Logic &amp; Ragas Integration (The Brain)<br>├── config.py              # Configuration (Keys, Model Names)<br>├── constitution_usa.pdf   # Our Ground Truth Document<br>└── golden_dataset.csv     # The Generated &quot;Exam&quot; Questions</pre><p>The core philosophy here is separation of concerns: app.py handles the &quot;Vibe Check&quot; (UI), while backend.py handles the &quot;Math&quot; (Logic).</p><p><strong>Configuration Strategy (</strong><strong>config.py):</strong><br> We keep our configuration strict. We use gpt-4o not just for answering, but for <em>grading</em>. Evaluation requires a smarter model than the one doing the task. If you use a weaker model to grade a stronger model, you get noise, not signal.</p><pre># config.py<br>class Config:<br>    PAGE_TITLE = &quot;RAG Chat &amp; Live Metrics&quot;<br>    LLM_MODEL = &quot;gpt-4o&quot;<br>    EMBEDDING_MODEL = &quot;text-embedding-3-small&quot;<br>    CHUNK_SIZE = 1000<br>    CHUNK_OVERLAP = 200</pre><p>With the foundation laid, let’s build the first mode: The Live Audit.</p><h3>Phase 1: The Live Audit (Real-Time Transparency)</h3><p>The first thing we need is a feedback loop. Usually, when you chat with a RAG bot, you get an answer and a black box. You have no idea if the bot found the right document or if it just made something up.</p><p>In our <strong>Live Audit</strong> mode, we change that. We calculate two critical metrics <em>during</em> the chat session:</p><ol><li><strong>Faithfulness:</strong> Did the answer come from the retrieved context?</li><li><strong>Answer Relevancy:</strong> Did the answer address the user’s question?</li></ol><p>We call this “The Supervisor Loop.”</p><h3>The Ingestion</h3><p>First, we need to ingest our “Ground Truth.” For this demo, we are using the <strong>US Constitution</strong>. We upload it, chunk it, and push the vectors to our <strong>Qdrant Cloud</strong> cluster. Using a cloud vector DB ensures our state persists and we aren’t rebuilding indices every time we restart the Streamlit server.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n2pdE2PQbOS3Yte-gTVrag.png" /><figcaption><strong>Figure 2</strong>: <strong><em>The ingestion pipeline</em></strong><em> handles PDF parsing and vector storage in Qdrant Cloud, preparing the system for retrieval. </em>(Source: Image by Author)</figcaption></figure><h3>The “Open Box” Chat</h3><p>Once ingested, we can chat. But unlike a standard chatbot, this UI splits the screen. On top, you have the chat. Below it, you have the <strong>Live Metrics Gauge</strong>.</p><p>In backend.py, we wrap every query in a <strong>Supervisor Loop</strong>. We don&#39;t just generate an answer; we immediately grade it before the user even reads it:</p><pre># backend.py<br><br>def query_and_evaluate(self, question: str):<br>    &quot;&quot;&quot;<br>    Perform a single-turn RAG operation (Retrieve -&gt; Generate) and immediately<br>    evaluate it using Ragas metrics (Faithfulness &amp; Answer Relevancy).<br>    &quot;&quot;&quot;<br>    # ... [Retrieval and Generation Code] ...<br><br>    # 3. Evaluation<br>    eval_llm = LangchainLLMWrapper(self.llm)<br>    eval_embeddings = LangchainEmbeddingsWrapper(self.embeddings)<br>    <br>    # Instantiate Metrics (Use Uppercase Class Names)<br>    faith_metric = Faithfulness(llm=eval_llm)<br>    relevancy_metric = ResponseRelevancy(llm=eval_llm, embeddings=eval_embeddings)<br>    <br>    sample = SingleTurnSample(<br>        user_input=question,<br>        response=answer,<br>        retrieved_contexts=retrieved_contexts<br>    )<br>    <br>    faith_score = faith_metric.single_turn_score(sample)<br>    rel_score = relevancy_metric.single_turn_score(sample)<br>    <br>    return {<br>        &quot;answer&quot;: answer,<br>        &quot;contexts&quot;: retrieved_contexts,<br>        &quot;metrics&quot;: {<br>            &quot;faithfulness&quot;: faith_score,<br>            &quot;answer_relevancy&quot;: rel_score<br>        }<br>    }</pre><h3>Seeing It in Action</h3><p>Let’s ask a “<strong>Golden Question</strong>”: <em>“How old do you have to be to be President?”</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/783/1*Iu_ZDXc2j-B6ukhzsdtUrQ.png" /><figcaption><strong>Figure 3</strong>: <strong><em>A “Perfect” Turn.</em></strong><em> The system retrieves Article II, Section 1 (Context), answers “35 years old,” and receives a Faithfulness score of 1.00. </em>(Source: Image by Author)</figcaption></figure><p>Now, let’s look at a failure case — or rather, a “<strong>Negative Test</strong>.” I asked: <em>“What is the airspeed velocity of an unladen swallow?”</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-OtFgTEOFSMNt8HTzfadUw.png" /><figcaption><strong>Figure 4</strong>: <strong><em>The “Hallucination Trap.”</em></strong><em> </em>Note the result: <strong>Answer Relevancy is 0.00</strong> (it didn’t answer the question), but <strong>Faithfulness is 1.00</strong>. Why? because the bot <em>admitted</em> it didn’t know. In RAG, admitting ignorance is faithful. Hallucinating an answer would be unfaithful.<em> </em>(Source: Image by Author)</figcaption></figure><p>This immediate feedback is invaluable for debugging prompts. But it’s manual. We can’t type 100 questions every time we change the code. We need automation.</p><h3>Phase 2: The “Exam” (Synthetic Data Generation)</h3><p>Manual testing is fine for a demo, but it doesn’t scale. If you change your chunk size from 1000 to 500, do you really want to manually re-type 50 questions to see if retrieval improved?</p><p>We need a regression test suite. But writing 50 questions and finding their ground truth answers in a PDF is tedious work.</p><p><strong>This is called Synthetic Data Generation</strong>. Instead of hiring humans to write test cases, we use the LLM to write its own exam. Ragas provides a TestsetGenerator that reads your document and generates diverse questions:</p><ul><li><strong>Simple:</strong> “What is the capital?”</li><li><strong>Reasoning:</strong> “Why does X imply Y?”</li><li><strong>Multi-Context:</strong> “Comparing Article I and Article II, who has more power?”</li></ul><p>We built a dedicated “Deep Evaluation” page in our app to handle this.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*i7oz7BIlIsmIHKi--FwicQ.png" /><figcaption><strong>Figure 5: <em>The “Deep Evaluation Engine” </em></strong><em>interface allowing us to generate a golden dataset automatically from the uploaded PDF. </em>(Source: Image by Author)</figcaption></figure><p>Here is the code in backend.py that powers this generation. It uses the TestsetGenerator to create a synthetic exam based on the actual document content.</p><pre># backend.py<br><br>def generate_test_data(self, file_path, num_questions=5):<br>    &quot;&quot;&quot;<br>    Generate synthetic &#39;Golden Data&#39; (Questions &amp; Ground Truths) from a PDF.<br>    Uses Ragas TestsetGenerator to create diverse questions.<br>    &quot;&quot;&quot;<br>    loader = PyPDFLoader(file_path)<br>    documents = loader.load()<br>    <br>    generator_llm = LangchainLLMWrapper(self.llm)<br>    generator_embeddings = LangchainEmbeddingsWrapper(self.embeddings)<br>    <br>    generator = TestsetGenerator(<br>        llm=generator_llm,<br>        embedding_model=generator_embeddings<br>    )<br>    <br>    dataset = generator.generate_with_langchain_docs(<br>        documents,<br>        testset_size=num_questions<br>    )<br>    <br>    return dataset.to_pandas()</pre><p>Clicking ‘Generate’ gives us our <strong>Golden Dataset</strong>: a CSV file with questions <em>and</em> their Ground Truth answers (extracted directly from the PDF). This file is the ‘Answer Key’ for our regression test..</p><p>Now that we have an exam, we need to take it.</p><h3>Phase 3: The Report Card (Deep Metrics)</h3><p>Now comes the payoff. We have our RAG pipeline, and we have our Golden Dataset (the exam).</p><p>We run the “Full Evaluation.” This isn’t just checking if the answer “feels” right. This is a rigorous, mathematical audit using <strong>6 Key Performance Indicators (KPIs)</strong>:</p><ol><li><strong>Faithfulness:</strong> (Chef) Is the answer derived <em>only</em> from context?</li><li><strong>Answer Relevancy:</strong> (Chef) Did it answer the user’s specific question?</li><li><strong>Context Precision:</strong> (Shopper) Did the best ingredient end up on top of the shopping bag, or buried at the bottom?</li><li><strong>Context Recall:</strong> (Shopper) Did we retrieve <em>all</em> the necessary information?</li><li><strong>Context Entity Recall:</strong> (Shopper) Did we buy <em>every</em> item on the list? (If the question asks about ‘apples and oranges’, did we retrieve both?)</li><li><strong>Noise Sensitivity:</strong> (Robustness) Did the bot get distracted by irrelevant info?</li></ol><p>We implement this in run_batch_evaluation. This function iterates through our Golden Set, runs the RAG pipeline for each question, and then uses Ragas to grade the results against the Ground Truth.</p><pre># backend.py<br><br>def run_batch_evaluation(self, test_df: pd.DataFrame):<br>    &quot;&quot;&quot;<br>    Run a full RAGAS evaluation (6 KPIs) on a provided test dataset.<br>    &quot;&quot;&quot;<br>    # ... [Data Normalization &amp; RAG Pipeline Execution Loop] ...<br>    <br>    # 3. Create Dataset for Ragas<br>    data = {<br>        &quot;user_input&quot;: questions,<br>        &quot;response&quot;: answers,<br>        &quot;retrieved_contexts&quot;: contexts,<br>        &quot;reference&quot;: ground_truths<br>    }<br>    dataset = Dataset.from_dict(data)<br>    <br>    # 4. Define Metrics (Classes Instantiated)<br>    metrics = [<br>        Faithfulness(llm=eval_llm),<br>        ResponseRelevancy(llm=eval_llm, embeddings=eval_embeddings),<br>        ContextPrecision(llm=eval_llm),<br>        ContextRecall(llm=eval_llm),<br>        ContextEntityRecall(llm=eval_llm),<br>        NoiseSensitivity(llm=eval_llm)<br>    ]<br>    <br>    # 5. Execute Evaluation<br>    results = evaluate(<br>        dataset=dataset,<br>        metrics=metrics<br>    )<br>    <br>    return results</pre><p>This evaluate() function is the engine of our Supervisor. It turns subjective text into objective numbers.</p><h3>The Result: A Production Report Card</h3><p>After the batch run completes, we get a detailed dashboard.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9pfY0mORcsfs8ys57dtjcg.png" /><figcaption><strong>Figure 6: <em>The Final Report Card.</em></strong><em> We achieved 1.00 in Faithfulness and Context Precision, but Context Recall (0.88) and Entity Recall (0.69) suggest we might need to tweak our chunking strategy or retrieval “k” value. </em>(Source: Image by Author)</figcaption></figure><p>This dashboard tells us exactly where to focus.</p><ul><li><strong>Low Context Recall?</strong> Increase k (retrieve more chunks).</li><li><strong>Low Faithfulness?</strong> Fix the prompt (tell the Chef to stick to the recipe).</li><li><strong>Low Relevancy?</strong> The model is dodging the question; maybe it’s too defensive.</li></ul><h3>The CCTV Camera (LangSmith Tracing)</h3><p>Metrics tell you <em>what</em> happened (Faithfulness: 0.5), but they don’t always tell you <em>why</em>. For that, we need observability.</p><p>By wrapping our pipeline with <strong>LangSmith</strong>, we can trace every single step of the evaluation process. We can see exactly how long the LLM spent “grading” the answer versus generating it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uQVtzJ4j1WHBrL5C88ZBew.png" /><figcaption><strong>Figure 7: <em>The LangSmith Waterfall.</em></strong><em> We can see the “ragas evaluation” span taking 114s, which confirms that grading is computationally expensive compared to the actual retrieval (2.7s). </em>(Source: Image by Author)</figcaption></figure><p>The Trace reveals the hidden cost of quality: <strong>Grading is slow</strong>.<br> Looking at the trace, you can see the ragas evaluation block consuming the vast majority of the time. This confirms why we split our app into &quot;Live Audit&quot; (Single Turn) and &quot;Deep Evaluation&quot; (Batch). You cannot run a full 6-KPI regression test on every user query in production unless you want your latency to spike by 2 minutes.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nMa5C9h_7vN6-xfZHcSKlA.png" /><figcaption><strong>Figure 8: <em>The Cost of Quality</em></strong><em>. We can track the token usage and cost for every evaluation run, giving us a clear ROI on our testing budget. </em>(Source: Image by Author)</figcaption></figure><p>Now we have the complete picture: The Code, The Metrics, and The Trace. The trace confirms that grading is <strong>50x more expensive</strong> than the actual retrieval. The retrieval took ~2 seconds. The grading took nearly 2 minutes. This is why we cannot run deep evaluation on every live query — it would kill the user experience. Deep evaluation belongs in the background (CI/CD), not the foreground.</p><h3>Conclusion: The Cost of Quality</h3><p>In Part 1, we learned the math. In Part 2, we built the machine.</p><p>We started with a chatbot that confidently lied about expensive dinners. We ended with a <strong>Supervisor Engine</strong> that:</p><ol><li><strong>Audits itself</strong> in real-time (Live Metrics).</li><li><strong>Writes its own exams</strong> (Synthetic Data Generation).</li><li><strong>Grades itself</strong> against a ground truth (Deep Evaluation).</li><li><strong>Watches itself</strong> via tracing (LangSmith).</li></ol><p>The difference between a “demo” and a “product” isn’t the LLM model — it’s the harness you build around it. By automating the “Shopper vs. Chef” evaluation, we moved from “vibes-based engineering” to “evidence-based engineering.”</p><p>Your RAG application is probably hallucinating right now. You just don’t know it yet. <strong>Stop guessing. Start grading.</strong></p><h3>Try It Yourself</h3><p>Don’t just take my word for it — try the “Supervisor” engine yourself. I have deployed a live demo where you can chat with any pdf file and watch the metrics update in real-time.</p><ul><li><strong>Live App:</strong> <a href="https://rag-app-ragas-ma.streamlit.app/">RAG Chat &amp; Metrics Demo</a></li><li><strong>Source Code:</strong> <a href="https://github.com/mohitagr18/rag-qa-ragas">GitHub Repository</a></li></ul><h4>References</h4><ol><li>Es, S., James, J., Espinosa-Anke, L., &amp; Schockaert, S., <em>RAGAS: Automated Evaluation of Retrieval Augmented Generation</em> (2024), arXiv. (<a href="https://arxiv.org/abs/2309.15217">https://arxiv.org/abs/2309.15217</a>)</li><li>Yu, H., et al., <em>Evaluation of Retrieval-Augmented Generation: A Survey</em> (2024), arXiv. (<a href="https://arxiv.org/pdf/2405.07437">https://arxiv.org/pdf/2405.07437</a>)</li><li>LangChain, <em>LangChain API Documentation</em> (2025), LangChain. (<a href="https://python.langchain.com/docs/get_started/introduction">https://python.langchain.com/docs/get_started/introduction</a>)</li><li>Ragas, <em>Ragas Documentation</em> (2025), Ragas. (<a href="https://docs.ragas.io/en/stable/">https://docs.ragas.io/en/stable/</a>)</li><li>Qdrant, <em>Qdrant Vector Database Documentation</em> (2025), Qdrant. (<a href="https://qdrant.tech/documentation/">https://qdrant.tech/documentation/</a>)</li><li>Streamlit, <em>Streamlit Docs</em> (2025), Streamlit. (<a href="https://docs.streamlit.io/">https://docs.streamlit.io/</a>)</li><li>LangSmith, <em>LangSmith Walkthrough</em> (2025), LangChain. (<a href="https://docs.smith.langchain.com/">https://docs.smith.langchain.com/</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2fda360f6312" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/my-rag-chatbot-approved-a-5-000-dinner-building-the-automaton-part-2-2fda360f6312">My RAG Chatbot Approved a $5,000 Dinner: Building the Automaton (Part 2)</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My RAG Chatbot Approved a $5,000 Dinner: Debugging Hallucinations with Math (Part 1)]]></title>
            <link>https://medium.com/@mohitagr18/my-rag-chatbot-approved-a-5-000-dinner-debugging-hallucinations-with-math-part-1-1b2cef8c3ccd?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/1b2cef8c3ccd</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[retrieval-augmented-gen]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 08 Dec 2025 15:23:35 GMT</pubDate>
            <atom:updated>2025-12-15T04:54:42.798Z</atom:updated>
            <content:encoded><![CDATA[<p>The Air Canada case set a global precedent: Companies are now liable for their AI’s hallucinations.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/863/1*9o0de2EN5ahkmLFZUrUXUQ.png" /><figcaption><strong>Figure 1: The Liability Shift.</strong> The BBC headline confirming that companies are now liable for their AI’s hallucinations. This case moved RAG evaluation from a technical “nice-to-have” to a legal necessity. (Source: BBC.com)</figcaption></figure><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/1b2cef8c3ccd?source=friends_link&amp;sk=04bbd7d541bb995ce6c0b5f9055ef6fb"><em>friend link</em></a><em>.)</em></p><p><strong>I love tools. Give me a chainsaw, a debugger, or a socket wrench, and I know exactly what it does. It works, or it doesn’t. Simple.</strong></p><p>But there is a new tool in corporate America that nobody seems to know how to use, but <em>everybody</em> wants to talk about. It’s called AI.</p><p>And the problem isn’t the robot. It’s the guy with the <strong>biggest ego in the room </strong>who signs the checks.</p><p>You know the type. He spends 15 minutes scrolling through “Tech Twitter”, learns three new buzzwords, and storms into a meeting demanding we deploy <em>“Agentic RAG”</em> to <em>“optimize synergy”. </em>He has no idea what those words mean. But he wants them deployed <em>yesterday</em>.</p><p>He screams <em>“Fail Fast!”</em> and <em>“Break Things!”</em> because he thinks he’s a visionary. Well, congratulations, genius. You finally broke something expensive.</p><p><strong>You broke the law.</strong></p><p>Just ask <strong>Air Canada.</strong></p><p>An <a href="https://www.bbc.com/travel/article/20240222-air-canada-chatbot-misinformation-what-travellers-should-know"><strong>Air Canada passenger</strong></a> asked their chatbot about bereavement fares. The bot — probably hallucinating because it was rushed out the door by some VP who wanted a bonus — invented a generous new refund policy on the spot.</p><p>When the passenger asked for the money, Air Canada said no. And their defense in court? This is my favorite part. They argued the chatbot was a “<strong>separate legal entity</strong>.”</p><p>That’s right. They tried to tell a judge that their software was a rogue freelancer. The judge, shockingly, didn’t buy it. They got laughed out of court.</p><p>But hey, at least they aren’t New York City.</p><p><strong>Enter the $43 Million Lawsuit Generator.</strong></p><p><a href="https://www.thecity.nyc/2024/03/29/ai-chat-false-information-small-business/"><strong>NYC’s “MyCity” Bot</strong></a> is a taxpayer-funded project that cost $43 million. And what did the city get for that money? A bot that advises landlords to break the law.</p><p>As you can see here, it confidently told landlords they could discriminate against voucher holders and — get this — steal their workers’ tips.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/799/1*AHmVqfRJa304VmI_XgUvbg.png" /><figcaption><strong>Figure 2: </strong><em>The MyCity Chatbot confidently encouraging illegal discrimination and wage theft. (Source: The Markup / The City)</em></figcaption></figure><p>That’s not a bug, folks. That’s a <strong>liability machine</strong>.</p><h3>Your “Vibes” Don’t Hold Up in Court</h3><p>See, these executives, they rely on the “<strong>Vibe Check</strong>.” They ask the bot, <em>“Are you polite?”</em> The bot says <em>“Yes.”</em> They say, <em>“Great! Ship it!”</em></p><p>That is reckless. A “Thumbs Down” button tells you a customer is angry. It doesn’t tell you <em>why</em>. You cannot debug a hallucination using a churn graph, and you certainly can’t explain “vibes” to a federal judge.</p><p>So, here is the deal. In this series, we are going to stop acting like <strong>amateurs</strong> who learn engineering from “hashtags”. We are going to start acting like <strong>engineers</strong>.</p><p>We are going to perform an autopsy on these failures.</p><p>We will debug a hypothetical “<strong>Corporate Travel Bot</strong>” that just made a massive mistake — approving a <strong>$5,000 dinner</strong> when the limit was $75. Apparently, the bot was feeling generous; the CFO was not.</p><p>This is <strong>Part 1 of 3</strong>. We will calculate the core metrics — <strong>Faithfulness, Answer Relevancy, Context Precision, Context Recall, Entity Recall, and Noise Sensitivity </strong>— manually. By doing the math by hand, we will develop the intuition needed to catch these errors before your “innovative” product accidentally breaks the law.</p><h3>The Mental Model: The Shopper and The Chef</h3><p>Before we can grade our homework, we need to understand who is taking the test. A RAG system isn’t one brain; it’s two distinct workers collaborating to answer a question.</p><p>To understand why the Travel Bot approved that expensive dinner, we will use the <strong>Shopper vs. Chef</strong> analogy.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O6orytRniHfiAVa1QDqUFw.png" /><figcaption><strong>Figure 3: The RAG Assembly Line.</strong> The Retriever acts as a Shopper gathering ingredients, while the Generator acts as a Chef cooking the meal. Failures can happen at either stage. (Source: Image by Author)</figcaption></figure><h4>1. The Retriever is The Shopper</h4><p>The Shopper’s job is to run to the grocery store (Vector Database) and bring back specific ingredients (Document Chunks) requested by the user. They don’t cook; they just fetch.</p><p><strong>How we evaluate the Shopper:</strong></p><ul><li><strong>Context Precision:</strong> Did they prioritize the right ingredients, or did they bury the good stuff under a pile of junk?</li><li><strong>Context Recall:</strong> Did they find <em>all</em> the ingredients, or did they leave the “Receipt Policy” behind?</li><li><strong>Entity Recall:</strong> Did they find specific brand names, dates, or IDs?</li></ul><h4>2. The Generator is The Chef</h4><p>The Chef (LLM) stays in the kitchen. Their job is to take <em>only</em> the ingredients provided by the Shopper and cook a meal (the Answer).</p><p><strong>How we evaluate the Chef:</strong></p><ul><li><strong>Faithfulness:</strong> Did they stick to the ingredients provided, or did they sneak in “secret spices” (hallucinations) from their training data?</li><li><strong>Answer Relevancy:</strong> Did they actually cook what the customer ordered?</li><li><strong>Noise Sensitivity:</strong> Did they get distracted by the “junk mail” the Shopper accidentally bought?</li></ul><h4>Why this matters</h4><p>You cannot fix a system if you don’t know who broke it.</p><ul><li>If the Shopper buys rotten eggs, the Chef fails no matter how good they are.</li><li>If the Shopper buys the perfect ingredients but the Chef ignores them, the Chef fails.</li></ul><p>We must measure them separately. Let’s start the autopsy.</p><h3>Metric 1: Faithfulness (The Chef’s Loyalty)</h3><p>We begin our audit with the Generator (The Chef).</p><p><strong>Faithfulness</strong> measures groundedness. It asks one simple question: <strong>Did the Chef stick to the ingredients provided?</strong></p><ul><li><strong>It Detects:</strong> Hallucinations (making up facts not in the docs).</li><li><strong>It Does NOT Detect:</strong> Worldly truth. (If your internal document says “The sky is green,” and the bot says “The sky is green,” it is faithful).</li></ul><h4>The Math</h4><p>The formula is simple:</p><ul><li><strong>Faithfulness</strong> = Number of claims supported by context​ / Total number of claims</li></ul><h4><strong>The Manual Calculation</strong></h4><p>To understand the math, we will recreate the internal logic of an evaluation library using Python. We are going to use a second LLM as a “Judge” to grade the first LLM.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/784/0*5SxmWPtJwkSt5JbD" /><figcaption><strong>Figure 4: The Fact-Checking Pipeline.</strong> To calculate Faithfulness, we break the answer into atomic claims and verify them one by one against the context. (Source: Image by Author)</figcaption></figure><p><strong>The Scenario:</strong></p><ul><li><strong>Context:</strong> “Employees may spend up to $75. Receipts required &gt;$25.”</li><li><strong>Bot Answer:</strong> “You are allowed $5000, and alcohol is pre-approved.”</li></ul><p><strong>Step 1: Extract Claims — </strong>First, we must break the bot’s answer into atomic, verifiable statements (claims).</p><pre># 1. Setup the data<br>bot_answer = &quot;You are allowed $5000 per person, and alcohol is pre-approved.&quot;<br>retrieved_context = &quot;Employees may spend up to $75 per person on client dinners. Receipts are required&quot;<br><br># 2. Define the extraction prompt <br>claim_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Given the following response, extract ALL factual claims as a numbered list.<br>Each claim should be a single, verifiable statement.<br><br>Response: {response}<br>&quot;&quot;&quot;)<br><br># 3. Run Extraction<br>claims_chain = claim_prompt | llm | StrOutputParser()<br><br>claims = claims_chain.invoke({&quot;response&quot;: bot_answer})<br>print(&quot;Claims:&quot;)<br>print(claims)</pre><blockquote>Output:<br><strong>- Claim A:</strong> “You are allowed $5000 per person.”<br><strong>- Claim B:</strong> “Alcohol is pre-approved.”</blockquote><p><strong>Step 2: Verify Against Context</strong> — Now, the Judge acts as a fact-checker. It compares each claim <em>only</em> against the retrieved context.</p><pre># Define the Verification Prompt<br>verification_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Given the following context and claim, determine if the claim is SUPPORTED by the context.<br>Answer &quot;SUPPORTED&quot; or &quot;NOT SUPPORTED&quot;.<br><br>Context: {context}<br>Claim: {claim}<br>&quot;&quot;&quot;)<br><br>verify_chain = verification_prompt | llm | StrOutputParser()<br><br># List of extracted claims (from Step 1)<br>claim_list = [<br>    &quot;You are allowed $5000 per person.&quot;,<br>    &quot;Alcohol is pre-approved.&quot;<br>]<br><br># Run Verification<br>results = []<br>for claim in claim_list:<br>    verdict = verify_chain.invoke({<br>        &quot;context&quot;: retrieved_context, <br>        &quot;claim&quot;: claim<br>    })<br><br>    if &quot;NOT SUPPORTED&quot; in verdict:<br>        score = 0<br>    elif &quot;SUPPORTED&quot; in verdict:<br>        score = 1<br>    else:<br>        score = 0 <br><br>    results.append(score)<br>    print(f&quot;Claim: &#39;{claim}&#39; -&gt; {verdict} (Score: {score})&quot;)</pre><blockquote><strong>- Check Claim A:</strong> The context says “$75.” The claim says “$5000.” → <strong>Not Supported.<br>- Check Claim B:</strong> The context mentions “Receipts” but is silent on alcohol. → <strong>Not Supported.</strong></blockquote><p><strong>Step 3: The Score</strong></p><pre># Manual faithfulness calculation<br><br>faithfulness_score = sum(results) / len(results)<br>print(f&quot;Faithfulness Score: {faithfulness_score}&quot;)</pre><blockquote>Faithfulness = 0/2 ​= <strong>0.0</strong></blockquote><h4>The Diagnosis</h4><p>A score of 0.0 means the Chef completely ignored the ingredients. This confirms the failure was a <strong>Generative Hallucination</strong>. The LLM likely relied on its internal training data (its “secret spices”) rather than the documents we gave it.</p><h4><strong>How to fix it:</strong></h4><ul><li>Lower the temperature (make it less creative).</li><li>Adjust the system prompt to explicitly state: “Answer strictly using the provided context.”</li></ul><h3>Metric 2: Answer Relevancy (The Chef’s Focus)</h3><p>We are still evaluating the Chef. Even if the Chef uses the right ingredients (Faithfulness), they might cook the wrong meal entirely.</p><p><strong>Answer Relevancy</strong> measures the relationship between the User’s Question and the Bot’s Answer.</p><ul><li><strong>It Detects:</strong> Evasiveness, pivoting, or answers that are factually true but useless.</li><li><strong>It Does NOT Detect:</strong> Hallucinations. (An answer can be completely relevant but total lies).</li></ul><p><strong>The Scenario:</strong></p><ul><li><strong>User Question:</strong> “What is the client dinner allowance?”</li><li><strong>Bot Answer:</strong> “Travel expenses must be submitted via Workday by Friday.”</li></ul><p><em>Note: The answer is factually correct (Faithful), but it ignores the user’s actual question about money. It’s useless.</em></p><h4>The Math: Reverse Engineering</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hDpRTYD47EmSTeCGXYWBzw.png" /><figcaption><strong>Figure 5: The Reverse Engineering Workflow.</strong> We generate hypothetical questions from the bot’s answer and compare their semantics to the original question. (Source: Image by Author)</figcaption></figure><p>How do we measure this? We use a clever trick called <strong>Reverse Engineering</strong>. Since it’s hard to compare a Question (apples) to an Answer (oranges), we ask an LLM to “reverse” the answer back into a question.</p><ol><li><strong>Reverse Engineer:</strong> We ask an LLM, “If this answer is the solution, what 3 specific questions would prompt this?”</li><li><strong>Vector Math:</strong> We compare the semantics of those <em>generated</em> questions against the <em>actual</em> user question.</li><li><strong>The Formula:</strong></li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VFvuDQE0I5lWydurIXJPXA.png" /><figcaption><strong>Figure 6: The Relevancy Equation.</strong> To get the final score, we calculate the average cosine similarity between the original user question and the N generated hypothetical questions. (Source: Image by Author)</figcaption></figure><p><strong>Step 1: Reverse Engineering</strong> — We feed the Bot’s “Workday” answer back into an LLM.</p><pre># 1. Setup data<br>original_question = &quot;What is the client dinner allowance?&quot;<br>bot_answer = &quot;Travel expenses must be submitted via Workday by Friday.&quot;<br><br># 2. Define the Reverse Engineering Prompt<br>reverse_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Given the following answer, generate 3 distinct questions that this answer would be a good response to.<br>Answer: {answer}<br>Generate 3 Questions (one per line):<br>1. <br>2. <br>3. <br>&quot;&quot;&quot;)<br><br># 3. Run Generation<br>gen_chain = reverse_prompt | llm | StrOutputParser()<br>generated_output = gen_chain.invoke({&quot;answer&quot;: bot_answer})<br><br>print(f&quot;Original: {original_question}&quot;)<br>print(f&quot;Generated: \n{generated_output}&quot;)</pre><blockquote><em>Output:<br>- “When is the deadline for submitting travel expenses?”</em> <br>- <em>“How should I submit my travel expenses?”<br>- “What platform do I need to use?”</em></blockquote><p><strong>Step 2: The Vector Math</strong> — Now we compare the <strong>Original Question</strong> (“Money”) against the <strong>Hypothetical Questions</strong> (“Deadlines/Platforms”). To a computer, these look semantically different.</p><p>We turn them into vectors (embeddings) and calculate the angle between them (Cosine Similarity).</p><pre>hypothetical_questions = [<br>    &quot;When is the deadline for submitting travel expenses?&quot;,<br>    &quot;How should I submit my travel expenses for reimbursement?&quot;,<br>    &quot;What platform do I need to use to report my travel expenses?&quot;<br>]<br><br># Function to calculate Cosine Similarity<br>def cosine_similarity(vec1, vec2):<br>    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))<br><br># 1. Get Embeddings for the Original Question<br>vec_original = embeddings.embed_query(original_question)<br><br># 2. Loop through Hypothetical Questions and calculate similarity<br>scores = []<br>for q in hypothetical_questions:<br>    vec_hypo = embeddings.embed_query(q)<br>    similarity = cosine_similarity(vec_original, vec_hypo)<br>    scores.append(similarity)<br><br># 3. Average the scores<br>relevancy_score = sum(scores) / len(scores)<br><br>print(f&quot;Individual Similarities: {scores}&quot;)<br>print(f&quot;Final Answer Relevancy Score: {relevancy_score:.4f}&quot;)</pre><blockquote>The Result:<br>- Similarity(“Dinner Allowance”, “When is the deadline… ?”): <strong>0.29<br>- </strong>Similarity(“Dinner Allowance”, “How should I submit… ?”): <strong>0.28<br>- </strong>Similarity(“Dinner Allowance”, “What platform do I need… ?”): <strong>0.23<br><em>Answer Relevancy Score:</em></strong><em> </em><strong><em>0.26 (Low)</em></strong></blockquote><h4>The Diagnosis</h4><p>The Chef cooked a compliant meal (the policy on Workday submission is real), but it wasn’t what the customer ordered. The low semantic similarity exposes the pivot.</p><h4><strong>How to fix it:</strong></h4><ul><li><strong>Tune the System Prompt:</strong> Prioritize “Direct Answers.”</li><li><strong>Post-Processing:</strong> Add a step where the LLM critiques its own answer: “Does this answer the specific question asked?” before sending it to the user.</li></ul><h3>Metric 3: Context Precision (The Shopper’s Organization)</h3><p>We are done auditing the Chef. Now we turn our attention to the Shopper (Retriever).</p><p>Even if the database contains the right answers, the Shopper might bury them under a pile of junk. <strong>Context Precision</strong> measures Ranking Quality. It asks: <strong>Did the Shopper put the most important ingredients at the top of the bag?</strong></p><p><strong>Why it matters:</strong> LLMs suffer from “Lost in the Middle” syndrome1. If the relevant document is buried at rank #10, the LLM will likely miss it.</p><ul><li><strong>It Detects:</strong> Bad ranking algorithms and diluted context.</li><li><strong>It Does NOT Detect:</strong> Missing information (that is Recall, which we cover next).</li></ul><h4>The Math: Precision@K</h4><p>We don’t just count <em>how many</em> relevant items we found; we measure <em>where</em> they appeared.</p><ul><li>Item at Rank 1 = High Score.</li><li>Item at Rank 10 = Low Score.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/626/1*eXvP-HsSs808lSUVmKn_zA.png" /><figcaption><strong>Figure 7: Precision at Each Rank (k).</strong> For every relevant item retrieved, we calculate the precision score (Relevant Items Found / Current Rank) to determine its weighted contribution to the final score. (Source: Image by Author)</figcaption></figure><p>The formula rewards systems that place relevant items at the top of the list (k=1, k=2).</p><h4>The Manual Calculation</h4><p>To visualize this, we need to evaluate the <strong>Order</strong> of retrieval.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8-OWXTBx76bzH9Am1sY64A.png" /><figcaption><strong>Figure 8: The Precision Workflow.</strong> We ask an LLM to judge relevance, turn those judgments into binary scores, and then calculate the weighted precision. (Source: Image by Author)</figcaption></figure><p><strong>The Scenario:</strong></p><ul><li><strong>User Question:</strong> “What is the dinner allowance?”</li><li><strong>Ground Truth:</strong> “Employees may spend up to $75.”</li></ul><p><strong>The Shopping Bag (Retrieved Chunks):<br>- </strong>“Employees may spend up to $75.” (<strong>Relevant</strong>) <br>- “All travel expenses must be reported in Workday.” (<strong>Relevant Context</strong>)<br>- “The breakfast allowance is $20 per day.” (<strong>Irrelevant Distractor</strong>)<br>- “The company HQ is located in New York.” (<strong>Irrelevant</strong>)</p><p><strong>Step 1: The Judge (Binary Verification) — </strong>We ask the LLM to judge each chunk individually against the Ground Truth.</p><pre># 1. Setup data<br>question = &quot;What is the dinner allowance?&quot;<br>ground_truth = &quot;Employees may spend up to $75 on client dinners.&quot;<br>retrieved_chunks = [<br>    &quot;Employees may spend up to $75 on client dinners.&quot;,<br>    &quot;All travel expenses must be reported in Workday.&quot;,<br>    &quot;The breakfast allowance is $20 per day.&quot;,<br>    &quot;The company HQ is located in New York.&quot;<br>]<br><br># 2. Define the Verification Prompt<br># We ask the LLM to act as a binary judge<br>relevance_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Given the Question and Ground Truth, determine if the following Context Chunk is RELEVANT.<br><br>Question: {question}<br>Ground Truth: {ground_truth}<br>Context Chunk: {chunk}<br><br>Is this chunk relevant for answering the question? Answer only &quot;RELEVANT&quot; or &quot;NOT RELEVANT&quot;.<br>&quot;&quot;&quot;)<br><br># 3. Run Verification Loop<br>relevance_chain = relevance_prompt | llm | StrOutputParser()<br><br>verdicts = []<br>print(&quot;🔍 Verifying Chunks...&quot;)<br><br>for chunk in retrieved_chunks:<br>    result = relevance_chain.invoke({<br>        &quot;question&quot;: question,<br>        &quot;ground_truth&quot;: ground_truth,<br>        &quot;chunk&quot;: chunk<br>    })<br>    <br>    # Convert text response to binary (1 or 0)<br>    is_relevant = 1 if &quot;RELEVANT&quot; in result.upper() else 0<br>    verdicts.append(is_relevant)<br>    <br>    print(f&quot;Chunk: &#39;{chunk[:30]}...&#39; -&gt; {result.strip()} ({is_relevant})&quot;)</pre><blockquote><strong>Output: </strong>Chunk 1 -&gt; <strong>RELEVANT (1), </strong>Chunk 2 -&gt; <strong>RELEVANT (1), </strong>Chunk 3 -&gt; <strong>NOT RELEVANT (0), </strong>Chunk 4 -&gt; <strong>NOT RELEVANT (0)</strong></blockquote><blockquote><strong>Verdict Vector:</strong> [1, 1, 0, 0]</blockquote><p><strong>Step 2: The Math (Calculating Average Precision)- </strong>Now we calculate the score based on the verdicts [1, 1, 0, 0].</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/475/1*aWXZBC0y57yaT_svkcWocA.png" /><figcaption><strong>Figure 9: Calculating Average Precision.</strong> We calculate the precision at every rank where a relevant item appears, then average them. (Source: Image by Author)</figcaption></figure><p><strong>Step 3: Final Calculation</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/690/1*OTqNtafSCxeQ65l7dOVncA.png" /><figcaption><strong>Figure 10: The Final Score Calculation.</strong> We sum the contributions from the previous step and divide by the total number of relevant items to get the final metric. (Source: Image by Author)</figcaption></figure><h4><strong>Why Order Matters (The “Bad Shopper” Example)</strong></h4><p>What if our Vector Database was poorly tuned and returned the exact same chunks, but in <strong>reverse order</strong>? <strong>Verdicts:</strong> [0, 0, 1, 1] (Irrelevant items first).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/448/1*ycXsQy_IsPSto7sf7KvoWA.png" /><figcaption><strong>Figure 11: Calculating Average Precision for a Bad Shopper.</strong> We calculate the precision at every rank where a relevant item appears, then average them. (Source: Image by Author)</figcaption></figure><p><strong>New Score:</strong></p><ul><li>Sum = 0.0 + 0.0 + 0.33 + 0.50 = 0.83</li><li>Context Precision = 0.83 / 2 = <strong>0.415</strong></li></ul><p><strong>The Diagnosis:</strong> Even though both Shoppers found the exact same information, the second Shopper buried the answer. A score of <strong>0.41</strong> alerts us that our <strong>Ranking</strong> algorithm is failing.</p><h4>How to fix it</h4><p>If Context Precision is low, your Shopper is finding the right aisle but grabbing the wrong items first.</p><ul><li><strong>The Fix:</strong> Implement a <strong>Re-Ranker</strong> (like Cohere or BGE-Reranker) to re-sort the top 10 results before sending them to the Chef.</li><li><strong>The Fix:</strong> Tune your <strong>Chunk Size</strong>. Smaller chunks are often more precise and rank better.</li></ul><h3>Metric 4: Context Recall (Auditing the Shopper)</h3><p>We determined that our Shopper can find relevant items and rank them well (Precision). But there is another problem: Did the Shopper find everything we needed? Or did they leave half the shopping list behind? This is Context Recall.</p><p>Context Recall measures Retrieval Completeness. It asks: Is the retrieved context missing any key information required to answer the question?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tAPLZbJYTJFvwMO5Cx9S3Q.png" /><figcaption><strong><em>Figure 12: Context Recall Evaluation Flow</em></strong><em>. A flow diagram showing the Ground Truth answer being split into claims, each claim checked against the retrieved context by an LLM “Judge,” and the final Context Recall score computed as found-claims divided by total claims. </em>(Source: Image by Author)</figcaption></figure><h4>Why it matters</h4><p>If the information isn’t in the context, the Chef (LLM) has to guess (hallucinate) or say “I don’t know.”</p><ul><li>It Detects: Missing information gaps in your database or poor retrieval search settings.</li><li>It Does NOT Detect: Ranking order or noise (it only cares if the info is present somewhere in the bag).</li></ul><h4>The Math: Retrieval Completeness</h4><p>To measure this, we need a Ground Truth (the perfect answer). We assume the Ground Truth contains every fact needed. We check if our retrieved context matches those facts.</p><p>The formula divides the number of found claims by the total claims in the Ground Truth.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/653/1*d7VJ6bZGCt4UNkWi3fZN2Q.png" /><figcaption><strong><em>Figure 13: Context Recall Formula</em></strong><em>. The metric is computed as the number of Ground Truth claims found in the retrieved context divided by the total number of Ground Truth claims. </em>(Source: Image by Author)</figcaption></figure><h4>The Manual Calculation</h4><p>We need to check if our system retrieved all the facts mentioned in the “perfect answer.”</p><p><strong>The Scenario:</strong></p><ul><li><strong>User Question</strong>: “What are the rules for client dinners?”</li><li><strong>Ground Truth</strong>: “Employees may spend up to $75. Receipts are required for expenses over $25.” (Note: The Ground Truth has 2 distinct facts).</li></ul><p><strong>The Shopping Bag (Retrieved Chunks)</strong>:</p><ol><li>“Employees may spend up to $75 on client dinners.”</li><li>“All expenses must be reported in Workday.”<br><em>(Note: The “Receipts &gt; $25” rule is missing from the retrieval).</em></li></ol><p><strong>Step 1: Extract Ground Truth Claims — </strong>First, we identify the specific facts we are looking for.</p><ul><li>Claim 1: “Employees may spend up to $75.”</li><li>Claim 2: “Receipts are required for expenses over $25.”</li></ul><p><strong>Step 2: Attribution Check (The Judge)</strong></p><p>We use the LLM to check if each Ground Truth claim exists inside the retrieved text. We use a specific prompt pattern to perform this “Attribution” check.</p><pre># Define Verification Prompt<br>attribution_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Can the following claim be attributed to (found in) the given context?<br>Context: {context}<br>Claim: {claim}<br><br>Answer &quot;YES&quot; if the claim is supported by the context, &quot;NO&quot; if it cannot be found.<br>&quot;&quot;&quot;)<br><br># Run Verification Loop<br>attribution_chain = attribution_prompt | llm | StrOutputParser()<br>attribution_results = []<br><br>print(&quot;🔍 Verifying Claims in Context...&quot;)<br><br># Join context into one block for easier checking<br>full_context_text = &quot;\n&quot;.join(retrieved_context)<br><br>for claim in gt_claims:<br>    result = attribution_chain.invoke({<br>        &quot;context&quot;: full_context_text,<br>        &quot;claim&quot;: claim<br>    })<br>    <br>    found = 1 if &quot;YES&quot; in result.upper() else 0<br>    attribution_results.append(found)<br>    <br>    status = &quot;✅ Found&quot; if found else &quot;❌ MISSING&quot;<br>    print(f&quot;Claim: &#39;{claim}&#39; -&gt; {result.strip()} ({status})&quot;)</pre><blockquote><strong>Output:<br></strong>- Claim 1 (“Spend up to $75”) -&gt; <strong>YES (✅ Found)<br></strong>- Claim 2 (“Receipts &gt; $25”) -&gt; <strong>NO (❌ MISSING)</strong></blockquote><p><strong>Step 3: Final Calculation — </strong>Now we calculate the score based on our findings.</p><pre># Total Ground Truth Claims: 2<br># Claims Successfully Found: 1<br><br>context_recall = 1 / 2<br><br>print(f&quot;Context Recall Score: {context_recall:.2f}&quot;)</pre><blockquote><strong>R<em>esult: 0.50 (Low Recall)</em></strong></blockquote><p><strong>The Diagnosis:</strong> Our system failed to retrieve the receipt rule. If the user asks “Do I need a receipt for a $30 dinner?”, the Chef will fail (or hallucinate) because the Shopper forgot to buy that ingredient.</p><h4>How to fix it</h4><p>Low Recall means your search isn’t casting a wide enough net.</p><ul><li>The Fix: Increase k. (the number of chunks retrieved). If you grab 4 chunks instead of 2, you might catch the missing receipt rule.</li><li>The Fix: Use Parent Document Retriever. Sometimes the “Receipt rule” is in a different paragraph than the “Price rule.” Retrieving larger parent documents helps capture surrounding context.</li></ul><h3>Metric 5: Context Entity Recall (Auditing the Shopper)</h3><p>We have verified that the Shopper can find relevant topics (Precision) and general facts (Recall). But can they find the specifics?</p><p>If your user asks about a specific person, date, or tool, and the Shopper brings back general policy info without those exact names, the Chef will fail. This is Context Entity Recall.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*roCgiFySqAN5Lvk9rV9J8w.png" /><figcaption><strong><em>Figure 14: Entity Recall Evaluation Flow</em></strong><em>. We use an LLM to extract named entities (people, places, dates) from the Ground Truth, creating a checklist. We then scan the retrieved context to see how many items from that checklist are present. </em>(Source: Image by Author)</figcaption></figure><h4>Why it matters</h4><p>Context Entity Recall measures the retrieval of specific Named Entities (People, Places, Dates, Organizations, Products). It asks: Did the retrieved context contain all the specific proper nouns mentioned in the Ground Truth?</p><ul><li>It Detects: Loss of critical details. (e.g., The Ground Truth says “submit to Concur,” but your context only says “submit to the portal”).</li><li>It Does NOT Detect: General semantic meaning (that is Context Recall).</li></ul><h4>The Math: Entity Presence</h4><p>We use an LLM to perform Named Entity Recognition (NER) on the Ground Truth to create a checklist of required terms. Then we scan the Retrieved Context to see if they are present.</p><p><strong>The Formula:<br></strong>We calculate the score by dividing the number of specific entities found in the retrieved context by the total number of entities present in the Ground Truth.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/630/1*vwPQnxux-u54VP8AgyemjQ.png" /><figcaption><strong><em>Figure 15: Entity Recall Formula</em></strong><em>. The metric is computed as the number of specific entities found in the retrieved context divided by the total number of entities present in the Ground Truth. </em>Source: (Image by Author)</figcaption></figure><h4>The Manual Calculation</h4><p>Let’s refine our Travel Policy scenario. The user is asking for a specific contact person for approval.</p><p><strong>The Scenario:</strong></p><ul><li><strong>User Question</strong>: “Who approves dinner expenses over $75?</li><li><strong>Ground Truth</strong>: “Expenses over $75 must be approved by Sarah Jenkins, the VP of Finance.” (Note: This answer relies on 3 specific entities).</li></ul><p><strong>The Shopping Bag (Retrieved Chunks):</strong></p><ol><li>“Dinner expenses over $75 require approval from the VP of Finance.”</li><li>“Sarah Jenkins handles all international travel requests.”</li></ol><p><strong>Step 1: Extract Entities (The Judge) — </strong>First, we define our data and use the LLM to identify the “Must Have” entities from the Ground Truth.</p><pre># 1. Setup data<br>ground_truth = &quot;Expenses over $75 must be approved by Sarah Jenkins, the VP of Finance.&quot;<br>retrieved_chunks = [<br>    &quot;Dinner expenses over $75 require approval from the VP of Finance.&quot;,<br>    &quot;Sarah Jenkins handles all international travel requests.&quot;<br>]<br><br># Compute the full text for comparison<br>retrieved_text = &quot;\n&quot;.join(retrieved_chunks)<br><br># 2. Define Entity Extraction Prompt<br>entity_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Extract all Named Entities (Person, Organization, Date, Location, Monetary Values, Roles) from the text.<br>Return a Python list of strings.<br><br>Text: {text}<br>Entities:<br>&quot;&quot;&quot;)<br><br># 3. Extract Entities from Ground Truth<br>extraction_chain = entity_prompt | llm | StrOutputParser()<br><br># This asks the LLM to find the entities in the Ground Truth<br>gt_entities = extraction_chain.invoke({&quot;text&quot;: ground_truth})<br><br># Simulated result from the LLM:<br>print(f&quot;Ground Truth Entities: {gt_entities}&quot;)<br>print(f&quot;Retrieved Text Length: {len(retrieved_text)} chars&quot;)</pre><blockquote><strong>Output:<br>- Ground Truth Entities:</strong> [&#39;$75&#39;, &#39;Sarah Jenkins&#39;, &#39;VP of Finance&#39;]</blockquote><p><strong>Step 2: Comparison Check</strong> — Now we check if these specific strings appear in our retrieved_text.</p><pre># We compare the GT entities against the computed Retrieved Text<br>gt_entities = [&quot;$75&quot;, &quot;Sarah Jenkins&quot;, &quot;VP of Finance&quot;]<br>entities_found = []<br>context_lower = retrieved_text.lower()<br><br>print(&quot;🔍 Checking Entities...&quot;)<br>for entity in gt_entities:<br>    if entity.lower() in context_lower:<br>        entities_found.append(entity)<br>        print(f&quot;   ✅ Found: &#39;{entity}&#39;&quot;)<br>    else:<br>        print(f&quot;   ❌ MISSING: &#39;{entity}&#39;&quot;)<br><br>print(f&quot;Entities Found List: {entities_found}&quot;)</pre><blockquote><strong>Output:<br></strong>- ✅ Found: ‘$75’<br>- ✅ Found: ‘VP of Finance’<br>- ✅ Found: ‘Sarah Jenkins’</blockquote><p><strong>Step 3: The Math</strong></p><pre># Total GT Entities: 3<br># Found in Context: 3<br><br>entity_recall = 3 / 3<br><br>print(f&quot;Entity Recall Score: {entity_recall:.2f}&quot;)</pre><blockquote><strong>Result: 1.0 (Perfect Entity Recall)</strong></blockquote><p><strong>The Diagnosis:</strong> The Shopper found all the names! However, notice that “Sarah Jenkins” was found in a chunk about international travel, not dinner approval.</p><p>If the Chef still fails to answer correctly, it is because the contexts are disjointed. This highlights why you need both Context Recall (Semantic facts) and Entity Recall (Specific names) to get the full picture.</p><h4>How to fix it</h4><p>If Entity Recall is low (e.g., missing “Sarah Jenkins” entirely):</p><ul><li>Use Hybrid Search. Vector search struggles with exact names (confusing “Sarah Jenkins” with “Sarah Jones”). Keyword search (BM25) excels at fetching specific names.</li><li>Small-to-Big Retrieval. Retrieve small chunks (sentences containing names) but feed the Chef the larger surrounding window to ensure the connection is clear.</li></ul><h3>Metric 6: Noise Sensitivity (Auditing the System)</h3><p>Finally, we must test the Chef’s focus. Even if the Shopper brings back the right ingredients (Context Recall), they might accidentally toss some “junk mail” or irrelevant receipts into the bag (Noise).</p><p>Does the Chef ignore the junk, or do they get confused and accidentally cook it into the meal? This is <strong>Noise Sensitivity</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3xLX6nEnseNJI2to7fsz7w.png" /><figcaption><strong><em>Figure 16: Noise Sensitivity Evaluation Flow</em></strong><em>. We verify the Bot’s response claims against the Ground Truth. Any claim in the response that cannot be supported by the Ground Truth is considered “Noise” or hallucination induced by the context. (Source: Image by Author)</em></figcaption></figure><h4>Why it matters</h4><p>Noise Sensitivity measures Robustness. It asks: How often does the system make mistakes because it was distracted by irrelevant documents?</p><ul><li>It Detects: The LLM being easily distracted or confused by contradictory/old information found in the search results.</li><li>It Does NOT Detect: Missing info (Recall) or Ranking issues (Precision).</li></ul><p>Important: Unlike other metrics where 1.0 is good, here 0.0 is perfect. We want zero sensitivity to noise.</p><h4>The Math: Robustness</h4><p>We compare the Bot’s Answer against the Ground Truth. If the Bot includes information that came from the retrieved chunks but contradicts or adds to the Ground Truth, it implies the Bot was “tricked” by the noise.</p><p>The formula divides the number of incorrect (unsupported) claims by the total number of claims in the bot’s answer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/676/1*dMgXNbeICur8GSe93G55lA.png" /><figcaption><strong>F<em>igure 17: Noise Sensitivity Formula</em></strong><em>. Calculated as the number of claims in the response that are NOT supported by the Ground Truth, divided by the total number of claims in the response. (Source: Image by Author)</em></figcaption></figure><h4>The Manual Calculation</h4><p>Let’s see if our Travel Bot gets distracted by outdated policy documents that the Shopper accidentally retrieved.</p><p><strong>Scenario:</strong></p><ul><li><strong>User Question:</strong> “What is the standard room rate?”</li><li><strong>Ground Truth:</strong> “The standard room rate is <strong>$250</strong>.”</li></ul><p><strong>The Shopping Bag (Retrieved Chunks):</strong></p><ol><li>“Effective 2024: The standard room rate is $250.” <em>(Relevant)</em></li><li>“ARCHIVED 2019 POLICY: The room rate limit is $150.” <em>(Noise/Distractor)</em></li></ol><p><strong>Bot Answer:</strong> “The standard room rate is <strong>$250</strong>, but it was previously <strong>$150</strong>.”</p><p><strong>Step 1: Extract Claims from Bot Answer</strong> — We break the answer down into atomic facts.</p><pre># 1. Setup data<br>bot_response = &quot;The standard room rate is $250, but it was previously $150.&quot;<br>ground_truth = &quot;The standard room rate is $250.&quot;<br><br># 2. Define Extraction Prompt<br>claim_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Extract claims from the text. Return a list of strings.<br>Text: {text}<br>Claims:<br>&quot;&quot;&quot;)<br><br># 3. Run Extraction<br>claim_chain = claim_prompt | llm | StrOutputParser()<br><br># Simulated Output from LLM<br>claims = claim_chain.invoke({&quot;text&quot;: bot_response}) <br><br>print(f&quot;Extracted Claims:  \n{claims}&quot;)</pre><blockquote>Output:<br>- Claim 1: “The standard room rate is $250”<br>- Claim 2: “It was previously $150”</blockquote><p><strong>Step 2: Verification against Ground Truth</strong></p><p>We verify each claim against the <strong>Ground Truth</strong> (NOT the retrieved context). This is key. We want to know if the Bot is saying things <em>outside</em> the perfect answer.</p><pre>claims = [<br>    &quot;The standard room rate is $250&quot;,<br>    &quot;It was previously $150&quot;<br>]<br><br># Define Verification Prompt<br>verification_prompt = ChatPromptTemplate.from_template(&quot;&quot;&quot;<br>Is the following claim supported by the Ground Truth?<br>Ground Truth: {ground_truth}<br>Claim: {claim}<br><br>Answer &quot;SUPPORTED&quot; or &quot;NOT SUPPORTED&quot;.<br>&quot;&quot;&quot;)<br><br>verification_chain = verification_prompt | llm | StrOutputParser()<br><br>incorrect_claims = 0<br>total_claims = len(claims)<br><br>print(&quot;🔍 Verifying Claims against Ground Truth...&quot;)<br><br>for claim in claims:<br>    result = verification_chain.invoke({<br>        &quot;ground_truth&quot;: ground_truth,<br>        &quot;claim&quot;: claim<br>    })<br>    <br>    if &quot;NOT SUPPORTED&quot; in result:<br>        incorrect_claims += 1<br>        print(f&quot;   Claim: &#39;{claim}&#39; -&gt; ❌ NOT in GT (Noise Detected)&quot;)<br>    else:<br>        print(f&quot;   Claim: &#39;{claim}&#39; -&gt; ✅ Supported&quot;)</pre><blockquote><strong>Output:<br></strong>- Claim 1 (“Rate is $250”) -&gt; <strong>✅ Supported<br></strong>- Claim 2 (“Previously $150”) -&gt; <strong>❌ NOT in GT</strong> <br><em>(The Ground Truth never mentioned history. The Chef got distracted by the 2019 document).</em></blockquote><p><strong>Step 3: Final Calculation</strong></p><pre># Incorrect Claims (Noise): 1<br># Total Claims: 2<br><br>noise_sensitivity = 1 / 2<br><br>print(f&quot;Noise Sensitivity Score: {noise_sensitivity:.2f}&quot;)</pre><blockquote><strong>Result: 0.50 (High Sensitivity)</strong></blockquote><p><strong>The Diagnosis:</strong> The score is <strong>0.50</strong> (remember, we want 0.0). This tells us our LLM is “chatty” and includes irrelevant details found in the search results. In a compliance setting, stating the old rate might confuse the user.</p><h4>How to fix it</h4><p>If Noise Sensitivity is high:</p><ul><li><strong>Prompt Engineering</strong>. Explicitly instruct the Chef: “Do not include information from the context unless it directly answers the question.”</li><li><strong>Filter Retrieval</strong>. Use metadata filtering (e.g., status=&quot;active&quot;) to stop the Shopper from buying &quot;Archived&quot; documents in the first place.</li></ul><h3>Summary: The RAG Evaluation Master Sheet</h3><p>We started this journey with a chatbot that approved a $5,000 dinner because it retrieved an old 2019 policy document. Instead of relying on “vibe checks” or staring at churn graphs, we popped the hood and did the math.</p><p>By manually calculating these metrics, we’ve replaced intuition with engineering. We now know that a Faithfulness failure is a Chef problem (Hallucination), while a Context Precision failure is a Shopper problem (Ranking).</p><p>Here is your cheat sheet. This combines the calculation logic with the debugging actions you need to take when the numbers drop.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dtFs6ZgYuLQLAGSYyRS8Gg.png" /><figcaption><strong><em>Figure 18: The RAG Evaluation Master Sheet</em></strong><em>. A summary table mapping each metric (Faithfulness, Relevancy, Precision, Recall, Entity Recall, Noise Sensitivity) to the specific component it tests (Shopper vs. Chef) and the recommended fix. (Source: Image by Author)</em></figcaption></figure><h3>What’s Next? From Manual to Automatic</h3><p>Calculating these metrics by hand for one question took us about 15 minutes of coding. Doing this for a production dataset of 500+ questions would take a lifetime.</p><p>In <strong>Part 2</strong>, we will automate this entire workflow. We will:</p><ol><li>Replace our manual Python scripts with the <a href="https://docs.ragas.io/en/latest/"><strong>Ragas</strong></a><strong> Library</strong>.</li><li>Build a synthetic <strong>Test Set</strong> automatically (so you don’t have to write Ground Truths by hand).</li><li>Run a full evaluation suite in minutes to catch regressions before they hit production.</li></ol><p>Stop guessing. Start measuring. See you in Part 2.</p><h4>Try It Yourself!</h4><p>You can run every manual calculation script from this article and explore the logic step-by-step using the complete Jupyter Notebook on GitHub. I’d love to see you fork it and test it against your own RAG systems.</p><p>💻 <a href="https://github.com/mohitagr18/rag-evaluation">GitHub Repository</a></p><h4>References</h4><ol><li>Yu, H., et al., <em>Evaluation of Retrieval-Augmented Generation: A Survey</em> (2024), arXiv. (<a href="https://arxiv.org/pdf/2405.07437">https://arxiv.org/pdf/2405.07437</a>)</li><li>LangChain, <em>LangChain API Documentation</em> (2025), LangChain. (<a href="https://python.langchain.com/docs/get_started/introduction">https://python.langchain.com/docs/get_started/introduction</a>)</li><li>Es, S., <em>Ragas: Automated Evaluation of Retrieval Augmented Generation</em> (2024), Ragas Documentation. (<a href="https://docs.ragas.io/en/stable/">https://docs.ragas.io/en/stable/</a>)</li><li>Liu, N. F., et al., <em>Lost in the Middle: How Language Models Use Long Contexts</em> (2023), arXiv. (<a href="https://arxiv.org/abs/2307.03172">https://arxiv.org/abs/2307.03172</a>)</li><li>BBC News, <em>Air Canada must honor refund policy invented by airline’s chatbot</em> (2024), BBC. (<a href="https://www.bbc.com/news/technology-68334805">https://www.bbc.com/news/technology-68334805</a>)</li><li>The City, <em>Foreman, A. (2024). NYC&#39;s AI Chatbot Tells Businesses to Break the Law.</em> The City. (<a href="https://www.thecity.nyc/2024/03/29/ai-chat-false-information-small-business/">https://www.thecity.nyc/2024/03/29/ai-chat-false-information-small-business/</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1b2cef8c3ccd" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Reality of “Agentic” AI: Why My Weekend Project Became a Nightmare]]></title>
            <link>https://aiadvances.org/the-reality-of-agentic-ai-why-my-weekend-project-became-a-nightmare-3899df1ea1dd?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/3899df1ea1dd</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[gaming]]></category>
            <category><![CDATA[systems-thinking]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 24 Nov 2025 16:54:45 GMT</pubDate>
            <atom:updated>2025-11-24T18:08:48.386Z</atom:updated>
            <content:encoded><![CDATA[<p>I thought Generative AI would be a magic wand. Instead, it was a stubborn component that needed a nervous system.</p><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/3899df1ea1dd?source=friends_link&amp;sk=6a983c26884ffa7ae59b4bd2ca19b3d4"><em>friend link</em></a><em>.)</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JZNqBSQ59b-Hw3S2MCSIsA.png" /><figcaption><strong>Figure 1: The Loop Era.</strong> My gaming roots in <em>Contra</em> and <em>Counter-Strike</em>. While the action was legendary, the audio was a static, relentless loop that never cared if I was winning or sneaking. (Image generated by Google Gemini)</figcaption></figure><p>My gaming career peaked with <em>Contra</em> and <em>Counter-Strike</em>. Growing up, we didn’t have the budget for the latest consoles or high-end rigs, but I didn’t need them to be fascinated by the commando action of those early shooters. I haven’t picked up a controller seriously in years, but one specific detail stuck with me: the loops.</p><p>No matter how intense the firefight got, the background track remained a static, relentless loop. It never cared if I was winning, losing, or sneaking.</p><p>In the modern industry, solving this requires massive audio engines and composers who understand “vertical layering” — the art of stacking instrument stems so they can fade in and out dynamically. I wanted to build that. I wanted to create a “Live Soundtrack Crossfader” that finally broke that static loop. If a player entered a stealth section, I wanted the engine to “hear” the context and fade out the drums while swelling the ambient pads.</p><p>There was just one problem: I have zero musical talent, and I have never written a line of game code.</p><p>But I did have a theory: Could Generative AI act as my domain expert?. I figured I could wire Google Gemini (the Brain) to a React/Howler.js frontend (the Hands) using Python (the Nervous System) in a single weekend.</p><p>I was wrong.</p><p>Because I was new to this domain, I walked straight into a minefield of browser caches, hallucinating SDKs, and “ghost” interfaces. I realized I wasn’t just building a music player; I was stress-testing the reality of building complex, agentic AI applications from scratch.</p><p>Here is the story of how I built the adaptive audio engine I imagined as a kid, and the six specific technical nightmares I had to survive to make it sing.</p><h3><strong>The Vision: Designing a Hybrid Orchestra</strong></h3><p>Since I couldn’t code the musical rules myself, I needed an architecture where the AI could act as the conductor. I realized early on that a simple script wouldn’t cut it. I needed a system that could “think” in Python (where the powerful AI libraries live) but “perform” in the browser (where audio playback is smoothest).</p><p>This presented a technical dilemma. If I tried to do everything in Python using Streamlit, the audio would be clunky — reloading the entire page just to fade out a drum track. If I moved everything to JavaScript, I’d lose easy access to the heavy-lifting Python AI libraries.</p><p>So, I designed a hybrid organism:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/861/1*4B35c77EYOdvwbARJzMiqg.png" /><figcaption><strong>Figure 2: The “Hybrid Organism” Architecture.</strong> The Streamlit &amp; Python backend (Nervous System) acts as the mandatory bridge between the AI’s logic (The Brain) and the browser’s audio engine (The Hands), preventing the AI from hallucinating files that don’t exist. (Image by Author)</figcaption></figure><ul><li><strong>The Brain (Google Gemini 2.5 Flash):</strong> This is the musical intelligence. It analyzes the game state (e.g., “Health is low, Player is sneaking”) and decides which instrument stems should be active and how loud they should be.</li><li><strong>The Nervous System (Python &amp; Streamlit):</strong> This handles the logic. It validates the AI’s decisions against a local inventory to ensure we don’t try to play songs that don’t exist.</li><li><strong>The Hands (React + Howler.js):</strong> This is the execution layer. It runs in the user’s browser, receiving instructions from Python to smoothly crossfade audio stems in real-time without page reloads.</li><li><strong>The Lungs (Google Cloud Storage):</strong> To keep the app fast, the actual audio files (.wav stems) are streamed directly from the cloud, bypassing the app server entirely.</li></ul><p>To ensure the “Brain” didn’t just chat with us, I defined a strict protocol in the “Nervous System.” This Pydantic model acts as a contract, forcing the AI to return a precise recipe for the audio engine rather than conversational text:</p><pre># schemas.py<br>class MusicalIntent(BaseModel):<br>    &quot;&quot;&quot;<br>    Describes the musical configuration for a given theme:<br>    - Theme label, active stems, gains, fades, timestamp.<br>    &quot;&quot;&quot;<br>    theme: Literal[&#39;explore&#39;, &#39;combat&#39;, &#39;stealth&#39;, &#39;bosscombat&#39;]<br>    active_stems: List[str]<br>    target_gains: Dict[str, float]<br>    fade_durations: Dict[str, float]<br>    timestamp: datetime</pre><p>It looked perfect on paper. I had a clear flow: The Brain sends an intent to the Nervous System, which passes a signal to the Hands. But as soon as I tried to build it, the body started rejecting the organs.</p><h3><strong>The Hallucinating DJ</strong></h3><p>With the architecture in place, I fired up the backend for the first test. I set the game state to “Combat” and asked Gemini to generate a tracklist. The response was confident and musically sound. It suggested a high-tempo drum track, a gritty bassline, and a specific synthesizer lead called neon_blades.wav.</p><p>It sounded perfect. There was just one problem: neon_blades.wav didn’t exist.</p><p>I realized immediately that I had fallen into the classic LLM trap: I was treating Gemini like a database, but it was acting like an improviser. It saw the word “Combat” and hallucinated a cool-sounding filename that fit the vibe, completely ignoring the actual files on my hard drive. If I fed this instruction to the frontend, the audio engine would crash, trying to load a ghost file.</p><p>To fix this, I had to build a hard guardrail in the Python layer. I couldn’t trust the AI to know what music I owned, so I wrote a function to perform a physical inventory check before every request.</p><p>First, Python scans the local directory to establish the “Ground Truth”:</p><pre># llm_advisor.py<br>def generate_mix_intent_from_folder(theme: str, base_dir: str = &quot;audio_clips&quot;) -&gt; MixIntent:<br>    # ... checks for directory existence ...<br>    stem_intents = []<br>    for fname in os.listdir(theme_dir):<br>        if fname.lower().endswith(&quot;.wav&quot;):<br>            stem_name = os.path.splitext(fname)[0]<br>            # ... build StemIntent object ...<br>            stem_intents.append(StemIntent(...))<br>    return MixIntent(theme=theme, stem_intents=stem_intents)</pre><p>Once I had this list, I couldn’t just hope the AI would respect it. I had to force it. I updated the prompt construction logic to inject this list of valid filenames directly into the prompt, along with a stern warning.</p><p>Here is the exact constraint that stopped the hallucinations:</p><pre># llm_advisor.py<br>    def _build_prompt(self, session_log, current_state, next_theme, valid_stems, user_query):<br>        valid_stems_str = &quot;, &quot;.join([f&quot;&#39;{s}&#39;&quot; for s in valid_stems])<br><br>        prompt = (<br>            f&quot;Current theme: {current_state[0][&#39;filename&#39;].split(&#39;/&#39;)[0] if current_state else &#39;[unknown]&#39;}\n&quot;<br>            f&quot;Next theme: {next_theme}\n&quot;<br>            f&quot;**CRITICAL CONSTRAINT**: The ONLY audio files available for &#39;{next_theme}&#39; are: [{valid_stems_str}].\n&quot;<br>            f&quot;You MUST NOT invent new filenames. You MUST use a subset of the provided valid stems.\n&quot;<br>            # ... rest of prompt ...<br>        )<br>        return prompt</pre><p>This was a lesson in “Agentic” development: You don’t ask the AI to create reality; you give it a sandbox and dare it to step outside.</p><h3><strong>The “Ghost” Interface</strong></h3><p>With the AI tamed, I had a brain. Now I needed hands.</p><p>I needed a way for the Python backend to reach into the user’s browser and tweak audio faders in real-time. Streamlit, my Python UI library, allows for “Custom Components” — essentially embedding a React app inside the Python interface.</p><p>The bridge code looks deceptively simple. You tell Python where the JavaScript lives, and it handles the rest:</p><pre># stem_mixer.py<br>_parent_dir = os.path.dirname(os.path.abspath(__file__))<br>component = components.declare_component(<br>    &quot;stem_mixer&quot;,<br>    path=os.path.join(_parent_dir, &quot;frontend&quot;, &quot;build&quot;)<br>)<br><br>def mix_and_transition(current_stems, next_stems):<br>    &quot;&quot;&quot;<br>    Show the frontend stem mixer/transition UI.<br>    Passes two lists of stems (current, next) to the React frontend.<br>    &quot;&quot;&quot;<br>    return component(<br>        current_stems=json.dumps(current_stems),<br>        next_stems=json.dumps(next_stems)<br>    )</pre><p>I fired up the server, expecting to see my audio controls. Instead, I saw… nothing. It was a “Ghost” interface. The Python logs insisted the data was sent. The React logs were silent. The browser just showed a blank white box where my audio engine should be.</p><p>I spent two days chasing this ghost. The culprit turned out to be a fundamental mismatch in language. I was using Vite to build my React code. By default, Vite builds “Single Page Applications” (websites). But Streamlit doesn’t want a website; it wants a “Library” (a specific UMD bundle it can inject).</p><p>My Python backend was trying to read a book, and my frontend was handing it a movie. I surgically altered the vite.config.ts file to force a UMD output. But the ghost wasn&#39;t done. Even after I fixed the build, the browser refused to update.</p><p>I literally added a giant header tag reading &lt;h1&gt;TEST STRING 123456&lt;/h1&gt; just to prove I was editing the right file. It still didn’t show up.</p><p>It turned out to be the oldest enemy in web development: The Browser Cache. The browser was so convinced it knew what the audio engine looked like (empty) that it refused to look at the new version.</p><p>I had to use the nuclear option — deleting the build folder entirely — to finally exorcise the ghost.</p><h3><strong>The Stubborn Composer</strong></h3><p>With the frontend finally rendering, I loaded the app for a full test. I set the current game state to <strong>Combat</strong> (high intensity) and the next state to <strong>Explore</strong> (low intensity). I hit the “Transition” button, expecting the AI to drop the aggressive drums and fade in a gentle melody.</p><p>Instead, it gave me <em>more</em> drums.</p><p>The AI saw that the current state was “Combat” and decided that the most logical next step was… to keep fighting. It was prioritizing consistency over change. It was like a DJ who refuses to play a slow song because the dance floor is currently full.</p><p>I realized that my prompt was too passive. I had been giving the AI a status report: “Here is the current state, here is the session history.” The AI looked at that history and thought, “Okay, we are in a battle, let’s keep the vibe going.”</p><p>I had to stop treating the AI like a collaborator and start treating it like a subordinate. I rewrote the prompt logic to be aggressive. I explicitly injected the next_theme and framed the request as a direct command to transition, rather than an open-ended question:</p><pre># llm_advisor.py<br>def _build_prompt(self, session_log, current_state, next_theme, valid_stems, user_query):<br>    # ... setup schema description ...<br>    prompt = (<br>        f&quot;Current theme: {current_state...}\n&quot;<br>        f&quot;Next theme: {next_theme}\n&quot;<br>        # ... constraints ...<br>        f&quot;Transition the music mix from the current theme to &#39;{next_theme}&#39;.\n&quot;<br>        &quot;What is the next musical intent?&quot;<br>    )<br>    return prompt</pre><p>I essentially had to shout at the digital conductor: <em>“I don’t care what the band is playing right now. Start playing Jazz.”</em> Once I forced that context shift, the transitions clicked. The drums faded out, the synth pads swelled in, and the system finally worked.</p><h3>The Systems Engineering Reality</h3><p>While the “Ghost” interface and the “Stubborn” composer were the headline acts, the full integration required surviving a gauntlet of invisible errors. I wasn’t just prompting an AI; I was fighting the entropy of a complex system.</p><p>Beyond the architecture battles, I hit three specific “invisible walls” that nearly killed the project:</p><ul><li><strong>The Hallucinating SDK:</strong> The AI kept writing code for the bleeding-edge Google GenAI library (google.genai), but my environment was running the older, stable version (google.generativeai). This caused constant &quot;Attribute Errors&quot; where the AI was technically right, but practically useless. I had to force it to revert to legacy syntax to match my actual environment.</li><li><strong>The “Buried” Data:</strong> Even when the AI generated the right music cues, it would wrap the data in Markdown formatting (like ```json), which broke my strict data parsers. I couldn&#39;t just ask the AI to be &quot;neater&quot;—I had to write a robust Regex &quot;reader&quot; to hunt through the text response and extract the JSON payload, ignoring the conversational filler.</li><li><strong>The “Silent” History:</strong> I built a “Replay” feature to review past music choices, but it crashed immediately. The issue? Data serialization. The Python backend was saving complex objects (like “low health” flags) as simple text strings. I had to write a sanitation layer to ensure the data history remained machine-readable, not just human-readable.</li></ul><p>These weren’t AI problems; they were systems engineering problems.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JDzzblcHWNhbK5B60zYCTw.png" /><figcaption><strong>Figure 3: The complete post-mortem</strong>. While I detailed the biggest blockers above, the full integration required fixing six distinct categories of failure. (Image by Author)</figcaption></figure><h3><strong>The Final Mix</strong></h3><p>After weeks of fighting, the ghost interface finally materialized.</p><p>I fired up the final build (demo2_st.py). Gone were the raw JSON text boxes and error logs. In their place was a clean, dashboard-style control deck. On the left, a dropdown to select the <strong>Current Theme</strong> (Combat). On the right, the <strong>Next Theme</strong> (Explore).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cRW2ygisngolqs9g4kdIFQ.png" /><figcaption><strong>Figure 4: The Agent in Action.</strong> Unlike a standard shuffle, the AI generates a precise JSON “recipe” for the audio engine. Note the <strong>Mixing Details</strong> panel (bottom left), where the AI dynamically assigns gain levels (0.6) and fade durations (4.0s) for specific stems like Pad and Strings. (Image by Author)</figcaption></figure><p>I set the intensity to default, and hit “Transition.”</p><p>This time, the backend didn’t crash. The AI didn’t hallucinate a song I didn’t own. Instead, the “Mixing Details” panel lit up with a structured plan. It didn’t just say “Play Explore Track”; it gave me a recipe:</p><blockquote><strong><em>Pad:</em></strong><em> Fade in over 4.0s (Gain 0.6).</em></blockquote><blockquote><strong><em>Strings:</em></strong><em> Fade in over 4.0s (Gain 0.4).</em></blockquote><blockquote><strong><em>Reasoning:</em></strong><em> “</em>To transition to ‘explore’ from ‘combat’, we need to create a sense of spaciousness and wonder.<em>”</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6PL8VGcOX4LelMKh_rjJeQ.png" /><figcaption><strong>Figure 5: The “Why” Behind the Mix.</strong> One of the biggest advantages of Agentic AI is explainability. Here, the model explicitly justifies its creative choices (top), explaining that it chose “Pads” to create “spaciousness.” The <strong>Transition History</strong> (bottom) proves the “Silent History” bug was resolved, successfully logging complex state data without crashing. (Image by Author)</figcaption></figure><p>And then, the audio played. The aggressive combat drums didn’t just cut out; they melted away, replaced by a swelling tide of cinematic strings and ambient pads. It wasn’t a playlist shuffle. It was a mix.</p><p>I had built exactly what I set out to create: a system where I didn’t need to be a composer to direct the music. I just had to tell the AI the vibe, and it handled the faders.</p><h3><strong>Conclusion: The Reality of “Weekend” AI Projects</strong></h3><p>When I started this project, I thought the hard part would be teaching a computer to understand music. I assumed the AI would be the bottleneck.</p><p>I was wrong. The AI was the easy part.</p><p>Google Gemini understood my requests instantly. It knew which stems to fade and how to build tension. The real battle wasn’t prompt engineering; it was systems engineering. It was fighting build tools to output the right library format. It was scrubbing browser caches that refused to let go of old code. It was forcing a stateless LLM to respect the physical reality of my hard drive.</p><p>We often talk about “Agentic AI” as if it’s a magic spell. We imagine we can just sprinkle an LLM onto a problem and watch it solve itself.</p><p>But the reality of building this engine proved that AI is just a component — a powerful, brilliant, sometimes stubborn component — that still needs a nervous system to function. It needs guardrails, error handling, and robust architecture.</p><p>I still have zero musical talent. I can’t read sheet music, and I can’t play the piano. But I can now sit at my dashboard, select “Stealth Mode,” and watch as my code conducts a symphony.</p><p>I didn’t become a musician. I built one.</p><h3>Try It Yourself!</h3><p>You can explore the final, working application and dive into the complete source code on GitHub. I’d love to see what you build with it.</p><ul><li><strong>🚀 </strong><a href="https://ma-gamesound-generator.streamlit.app/"><strong>Live Streamlit App</strong></a></li><li><strong>💻 </strong><a href="https://github.com/mohitagr18/game_sound_generator"><strong>GitHub Repository</strong></a></li></ul><h4>References</h4><ol><li>Google, Gemini API Documentation (2025), Google AI for Developers. (<a href="https://ai.google.dev/gemini-api/docs">https://ai.google.dev/gemini-api/docs</a>)</li><li>Streamlit, Streamlit API Reference (2025), Streamlit Inc. (<a href="https://docs.streamlit.io/">https://docs.streamlit.io/</a>)</li><li>J. Simpson, Howler.js: Audio Library for the Modern Web (2024), Goldfire Studios. (<a href="https://howlerjs.com/">https://howlerjs.com/</a>)</li><li>S. Colvin, Pydantic: Data Validation using Python Type Hints (2024), Pydantic. (<a href="https://www.google.com/search?q=https://docs.pydantic.dev/">https://docs.pydantic.dev/</a>)</li><li>Meta Open Source, React: The Library for Web and Native User Interfaces (2025), React.dev. (<a href="https://react.dev/">https://react.dev/</a>)</li><li>E. You, Vite: Next Generation Frontend Tooling (2024), ViteJS. (<a href="https://vitejs.dev/guide/">https://vitejs.dev/guide/</a>)</li><li>Google Cloud, Cloud Storage Introduction (2025), Google Cloud Documentation. (<a href="https://cloud.google.com/storage/docs/introduction">https://cloud.google.com/storage/docs/introduction</a>)</li><li>L. Weng, LLM Powered Autonomous Agents (2023), Lil’Log. (<a href="https://lilianweng.github.io/posts/2023-06-23-agent/">https://lilianweng.github.io/posts/2023-06-23-agent/</a>)</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3899df1ea1dd" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/the-reality-of-agentic-ai-why-my-weekend-project-became-a-nightmare-3899df1ea1dd">The Reality of “Agentic” AI: Why My Weekend Project Became a Nightmare</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My AI Failed My Garden. So I Built a Better One]]></title>
            <link>https://aiadvances.org/my-ai-failed-my-garden-so-i-built-a-better-one-145327b08f93?source=rss-3a62c8e9f67f------2</link>
            <guid isPermaLink="false">https://medium.com/p/145327b08f93</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[gardening]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <dc:creator><![CDATA[Mohit Aggarwal]]></dc:creator>
            <pubDate>Mon, 03 Nov 2025 13:22:14 GMT</pubDate>
            <atom:updated>2025-11-03T13:22:14.532Z</atom:updated>
            <content:encoded><![CDATA[<p>How a single caterpillar sparked a quest to build a ‘Plant Doctor’ that gives advice that’s actually useful.</p><p><em>(Note for Medium members: If you’d like to read this story for free, please use this</em> <a href="https://medium.com/@mohitagr18/145327b08f93?source=friends_link&amp;sk=70b92c3930a99326e822a7848cad9184"><em>friend link</em></a><em>.)</em></p><p>It all started with a caterpillar. 🐛</p><p>My wife and I are avid home gardeners. Every season, our small backyard transforms into a hopeful plot of fruits and vegetables, and every season, we face a new antagonist. One year, it was moles leaving a trail of subterranean destruction. The next, it was squirrels who saw our ripening pomegranates as their personal buffet.</p><p>This year’s villain was smaller but no less formidable: a tiny, voracious caterpillar, contentedly munching away on our small lemon tree.</p><p>While I can’t exactly build an anti-rodent force field, I figured a software solution for pests was within my grasp. I snapped a photo and fed it to Google Gemini. The response was fast and accurate: a Swallowtail Caterpillar. It even suggested a treatment, but the recommendation felt hollow.</p><p>It was a classic AI failure: a technically correct answer that was practically useless. It didn’t know about the dry spell in my zip code, my garden’s sandy soil, or what specific organic products I could get from Amazon by the weekend.</p><p>That gap is what separates a novelty gadget from a genuine tool. I didn’t need a simple pest <em>identifier</em>; I needed a true <em>plant doctor</em>. I needed an AI that could see the photo, understand my local context, and give me a plan that actually worked.</p><p>The AI I wanted didn’t exist. So, I decided to build one. This is the story of how I turned that single caterpillar photo into a full-blown, intelligent AI agent.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/863/1*tcZOAT6xQn7-u0YL5-47YA.png" /><figcaption>Figure 1: The very first “patient” — a small caterpillar found munching on a lemon leaf, which inspired the creation of the AI Plant Doctor. (Image by author)</figcaption></figure><h3>The Vision: Building a True Agricultural Assistant</h3><p>My experiment with the caterpillar proved one thing: a simple photo-to-text diagnosis wasn’t enough. To be truly useful, the app had to move from identification to <em>recommendation</em>. I didn’t just need an encyclopedia; I needed a consultant.</p><p>The goal was to build an intelligent agent that could reason about a problem by gathering data from multiple, specialized sources. Instead of a single, rigid script, I designed a system that could autonomously decide <em>which tool to use</em> to build a complete answer.</p><p>I gave my Plant Doctor a “toolkit” with four specialized members:</p><ol><li><strong>The Eyes:</strong> Google’s Gemini 2.5 Flash. It needed to <em>see</em> the problem. It analyzes the uploaded photo to identify the pest, the host plant, and the severity of the infestation.</li><li><strong>The Local Expert:</strong> Government APIs. For hyper-local context, the agent calls the National Weather Service for real-time forecasts and the USDA for detailed soil composition in the user’s zip code.</li><li><strong>The Pharmacist:</strong> A Product Search Tool. To make the advice instantly actionable, the agent searches for specific, organic products available on Amazon, providing direct purchase links.</li><li><strong>The Universal Adapter:</strong> A special protocol that makes this toolkit “shareable.” This means other AI clients (like Anthropic’s Claude or future models) can plug into my application and use its specialized gardening tools, making it a modular part of a bigger AI ecosystem.</li></ol><p>With this team assembled, the agent could finally act like a real-world expert, gathering all the necessary intel <em>before</em> delivering a comprehensive treatment plan.</p><h3>The Gauntlet: Hurdles I Overcame to Get It Working</h3><p>Every builder knows that a polished final product is often built on a mountain of failed attempts, cryptic error messages, and moments of sheer frustration. This project was no exception. Getting the Plant Doctor from a simple idea to a deployed, functioning application meant running through a gauntlet of technical challenges.</p><p>Here are the biggest battles I fought to get it working.</p><p>First, the AI itself was uncooperative. In early tests, it would give me a perfect list of Amazon products… but completely forget to write the <em>actual treatment advice</em>. It was like a doctor handing you a prescription for a mystery illness. The breakthrough came when I realized I was asking it to do too much at once. I had to stop treating it like an oracle and start treating it like a junior assistant: I split the task into two steps. First, “Act as an expert and write the advice.” Then, and only then, “Read that advice and find matching products.” That separation was the key.</p><p>Then came the classic nightmare: “But… it works on my machine!” When I tried to move the app from my Apple laptop to a cloud server, nothing worked. The code was built for a different <em>type</em> of computer, and it crashed instantly. The solution was to build the app inside a “Docker container” specifically telling it to be “Linux-compatible” — an essential, frustrating step to making it work anywhere.</p><p>Finally, I hit a user-experience wall. After a user uploaded a photo and got an assessment, the app would make them go to a <em>new screen</em> to enter their location, forcing them to lose sight of the original problem. It felt clunky and confusing. I had to refactor the whole workflow so the image, the assessment, and the local data all stayed visible on one single screen. It was a simple change for the user, but a significant headache to re-engineer.</p><p>These hurdles were the project’s real proving ground. Each one forced a smarter design choice and, ultimately, shaped the final application into something that truly works.</p><h3>How the Plant Doctor Thinks</h3><p>Building an intelligent agent required solving a few core challenges. The final design works less like a single brain and more like a team of specialists who know how to collaborate. Here’s how the key components work together.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L-hyzjo6VffTTwivq_RdqQ.png" /><figcaption>Figure 2: The complete architecture of the Plant Doctor, showing how the Gemini orchestrator coordinates a specialized toolkit and a two-step reasoning process to generate a final, personalized recommendation. (Image by author)</figcaption></figure><h4>The Two-Step Prompt: The Secret to Reliable AI</h4><p>My first prompts were a disaster. I asked the AI to do everything at once: “Identify this, write a treatment plan, and find me products.” The AI would often hallucinate or skip steps, like a doctor handing you a prescription without a diagnosis.</p><p>The breakthrough was to stop treating the AI like a magical oracle and start treating it like a junior assistant who needs sequential instructions. I broke the task into a two-step chain:</p><ol><li><strong>First, generate expert advice.</strong> The AI is prompted to act as an agricultural expert and write a detailed treatment plan, and it’s <em>explicitly forbidden</em> from mentioning any products.</li><li><strong>Then, find the products.</strong> The system takes the AI’s newly written advice and uses it as context for a <em>second</em> prompt, which tasks the AI with finding matching organic products using its search tool.</li></ol><p>This “separation of concerns” was the key to making the app’s output consistent and reliable every single time.</p><pre># A simplified look at the logic from qa_engine_agentic.py<br><br># Step 1: Generate the expert advice<br>advice_prompt = f&quot;&quot;&quot;<br>Based on the provided context, act as an agricultural expert.<br>Write a detailed, 2-3 paragraph treatment plan.<br>Do NOT include any product recommendations in this step.<br>Context: {context}<br>&quot;&quot;&quot;<br>treatment_advice = model.generate_content(advice_prompt)<br><br># Step 2: Use the advice to find products<br>product_prompt = f&quot;&quot;&quot;<br>Based on the following treatment plan, find 2-3 relevant<br>organic products on Amazon using the search tool.<br>Treatment Plan: {treatment_advice}<br>&quot;&quot;&quot;<br>product_links = model.generate_content(product_prompt)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1O4_k0iO53E-TdoEHfKU-g.png" /><figcaption>Figure 3: An example of the AI Plant Doctor’s comprehensive detection results, including pest identification, severity, personalized treatment recommendations, and product links. (Image by Author)</figcaption></figure><h4>The Specialist Toolkit: Giving the AI Senses</h4><p>An AI is only as good as its data. To move beyond generic advice, I gave the Plant Doctor “senses” by connecting it to a toolkit of specialized APIs. When a user enters their zip code, the agent automatically calls:</p><ul><li><strong>The National Weather Service</strong> for real-time local forecasts.</li><li><strong>The USDA Soil Data Access API</strong> for detailed local soil composition.</li></ul><p>These tools allow the AI to function like a real-world consultant. It can now tailor its advice to a user’s <em>actual</em> environment — for example, by warning them not to apply a treatment just before a big rainstorm.</p><pre># A simplified look at how the location_service.py uses these tools<br><br>def get_full_context(zip_code):<br>    &quot;&quot;&quot;<br>    Fetches weather and soil data for a given zip code.<br>    &quot;&quot;&quot;<br>    # Get coordinates for the zip code<br>    coordinates = get_coords_from_zip(zip_code)<br><br>    # Call the NWS API<br>    weather_data = nws_api_call(coordinates)<br><br>    # Call the USDA Soil API<br>    soil_data = usda_api_call(coordinates)<br><br>    return f&quot;Weather: {weather_data}, Soil: {soil_data}&quot;</pre><h4>The Universal Adapter: Building for a Collaborative Future</h4><p>To make the Plant Doctor more than just a standalone app, I wrapped its special functions (like get_weather or get_soil_data) in a standard Model Context Protocol (MCP) format. This design means my app is no longer a silo. Its expert gardening tools can be instantly plugged into and used by <em>any other</em> compatible AI, whether it&#39;s from Google, Anthropic, or an open-source project. This transforms the app from a single-purpose tool into a modular, reusable service, ready for a future where AIs collaborate.</p><pre># A conceptual look at registering a tool with the MCP server<br>from mcp import MCPServer, Tool<br><br>class GetWeatherTool(Tool):<br>    def call(self, zip_code: str) -&gt; str:<br>        # Logic to call the NWS API<br>        return get_weather_from_nws(zip_code)<br><br># The server exposes the tool using a standard interface<br>mcp_server = MCPServer()<br>mcp_server.register_tool(<br>    name=&quot;get_weather&quot;,<br>    description=&quot;Fetches weather for a US zip code.&quot;,<br>    tool=GetWeatherTool()<br>)<br>mcp_server.start()</pre><h4>Deployment: From a Local Script to a Global App</h4><p>A great app isn’t finished until it’s in the hands of users. I used <strong>Google Cloud Run</strong>, a “serverless” platform that automatically handles scaling, so the app is always fast, even if user traffic suddenly spikes.</p><p>To make updates seamless, I built an automated pipeline using <strong>GitHub Actions</strong>. Now, when I push a new change to the main code branch, a workflow automatically builds, tests, and deploys the new version to the live app with zero downtime. This pipeline turns a complex, manual process into a single, reliable step, letting me focus on improving the app instead of wrestling with deployments.</p><pre># A simplified look at the deployment job in .github/workflows/deploy.yml<br><br>- name: Build and Push Docker Image<br>  uses: docker/build-push-action@v2<br>  with:<br>    context: .<br>    push: true<br>    tags: gcr.io/your-project/plant-doctor:latest<br>    platforms: linux/amd64<br><br>- name: Deploy to Google Cloud Run<br>  uses: google-github-actions/deploy-cloudrun@v0<br>  with:<br>    service: plant-doctor-app<br>    image: gcr.io/your-project/plant-doctor:latest</pre><h3>Conclusion: From a Single Caterpillar to a Smarter Garden</h3><p>This project started with a single pest on a lemon tree but grew into something far more ambitious: an AI system that delivers truly contextual, useful advice. It’s a testament to the power of moving beyond generic answers and building tools that can reason about a problem like a real-world partner.</p><p>More than just a piece of software, the Plant Doctor represents a vision for a more practical future for AI — one where intelligent agents help us solve tangible, everyday problems in smarter, more effective ways.</p><p>After all, if we can build an AI smart enough to save a garden, what else can we build?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*DJml6MU45R8Mi5qwQ8qiZw.gif" /><figcaption>Figure 4: The AI Plant Doctor in action. Watch as it transforms a simple photo and zip code into a complete, personalized treatment plan — with product links — in seconds. (Image by author)</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XQ_Ot2z4e1Gn8p3ALd4xhw.png" /><figcaption>Figure 5: The interactive follow-up loop, showing how users can ask for deeper analysis on soil, weather, or ask new questions after the initial report. (Image by author)</figcaption></figure><h3>Try It Yourself!</h3><p>You can explore the final, working application and dive into the complete source code on GitHub. I’d love to see what you build with it.</p><ul><li><strong>🚀 </strong><a href="https://agri-assistant-218722702133.us-central1.run.app/"><strong>Live Streamlit App</strong></a></li><li><strong>💻 </strong><a href="https://github.com/mohitagr18/plant_pest_detector"><strong>GitHub Repository</strong></a></li></ul><h4>References</h4><ol><li>Q. Wu, G. Bansal, J. Zhang, et al., AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation (2023), arXiv. (<a href="https://arxiv.org/abs/2308.08155">https://arxiv.org/abs/2308.08155</a>)</li><li>Google, Gemini API Documentation (2025), Google AI for Developers. (<a href="https://ai.google.dev/gemini-api/docs">https://ai.google.dev/gemini-api/docs</a>)</li><li>National Weather Service, API Web Service Documentation (2025), NWS. (<a href="https://www.weather.gov/documentation/services-web-api">https://www.weather.gov/documentation/services-web-api</a>)</li><li>Mohit Aggarwal, Beyond the Prompt: An Architect’s Guide to Production-Ready AI Agents (2025), Medium. (<a href="https://medium.com/@mohitagr18/beyond-the-prompt-an-architects-guide-to-production-ready-ai-agents-4df49c1c8553">https://medium.com/@mohitagr18/beyond-the-prompt-an-architects-guide-to-production-ready-ai-agents-4df49c1c8553</a>)</li><li>Google Cloud, Generative AI on Vertex AI: Live API Reference (2025), Google Cloud Docs. (<a href="https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-live">https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/multimodal-live</a>)</li><li>USDA NRCS, Soil Data Access API — Tabular POST endpoint (n.d.), SDA. (<a href="https://sdmdataaccess.nrcs.usda.gov/Tabular/post.rest">https://sdmdataaccess.nrcs.usda.gov/Tabular/post.rest</a>)</li><li>FastMCP, Framework Overview and Quickstart (2023–2025), FastMCP Site. (<a href="https://gofastmcp.com/">https://gofastmcp.com</a>)</li><li>Streamlit Community, Build a Research Agent with LangGraph and Streamlit (2025), Community Tutorial. (<a href="https://discuss.streamlit.io/t/build-a-research-agent-with-deepseek-langgraph-and-streamlit/97580">https://discuss.streamlit.io/t/build-a-research-agent-with-deepseek-langgraph-and-streamlit/97580</a>)</li><li>jlowin/fastmcp, Fast, Pythonic MCP Servers and Clients (2025), GitHub Repository. (<a href="https://github.com/jlowin/fastmcp">https://github.com/jlowin/fastmcp</a>)</li><li>Mohit Aggarwal, A Step-by-Step Guide to Building an Agentic RAG Agent with LangGraph (2025), Medium. (<a href="https://medium.com/@mohitagr18/the-ai-that-thinks-before-it-searches-a-deep-dive-into-agentic-rag-82e5db9a0826">https://medium.com/@mohitagr18/the-ai-that-thinks-before-it-searches-a-deep-dive-into-agentic-rag-82e5db9a0826</a><a href="https://medium.com/@mohitagr18)%5B4">)</a></li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=145327b08f93" width="1" height="1" alt=""><hr><p><a href="https://aiadvances.org/my-ai-failed-my-garden-so-i-built-a-better-one-145327b08f93">My AI Failed My Garden. So I Built a Better One</a> was originally published in <a href="https://aiadvances.org/">AI Advances</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>