resources

https://cookbook.openai.com/examples/partners/eval_driven_system_design/receipt_inspection

and also evaluation-driven system design / system delivery

Eval-Driven Development (EDD) is the architectural answer to the non-deterministic nature of AI.

In traditional software, we use TDD (Test-Driven Development): assert result == expected.

In AI Engineering, we use EDD: assert similarity(result, expected) > 0.8.

As a Principal Architect, you must establish EDD early. Without it, your team is “vibing” – tweaking prompts based on gut feeling rather than engineering rigor. This leads to regression loops where fixing one prompt breaks five others.

Here is the architectural blueprint for an EDD pipeline.

I. The Core Concept: The “Pyramid of Evals”#

Just like the “Test Pyramid” (Unit > Integration > E2E), AI has its own hierarchy of verification. You should implement them in this order to balance cost and speed.

II. The Metrics: What are we actually measuring?#

For most RAG and Agentic systems, you need to measure three distinct dimensions. We often use the RAG Triad (popularized by frameworks like Ragas):

1. Context Precision (The Retrieval Metric):
   • Question: Did our search engine find the right documents?
   • Failure Mode: The LLM gave a bad answer because it was fed garbage data (“Garbage In, Garbage Out”).
2. Faithfulness (The Hallucination Metric):
   • Question: Is the answer derived solely from the retrieved context?
   • Failure Mode: The LLM ignored the documents and made up facts based on its training data.
3. Answer Relevance (The User Metric):
   • Question: Did the answer actually address the user’s prompt?
   • Failure Mode: The answer is true, but it’s a non-sequitur (e.g., User: “Price?” AI: “The product is blue.”).

III. The Mechanism: “LLM-as-a-Judge”#

This is the engine of modern EDD. You cannot manually review 1,000 logs every time you update a prompt. Instead, you automate it.

How it works:

You deploy a highly capable model (e.g., GPT-4o or Claude 3.5 Sonnet) to act as the “Judge.” It evaluates the traces generated by your production model (e.g., Llama-3-8B).

The Architectural Pattern:

1. Dataset: A set of 50 “Golden Questions” + “Ideal Answers” (Ground Truth).
2. Run: Pipeline processes the 50 questions.
3. Eval: The “Judge” model compares the Pipeline Output vs. Ideal Answer.
4. Score: Returns a structured JSON: { "score": 0.85, "reasoning": "Missed the nuance about the date." }.

IV. Implementing the EDD Pipeline (CI/CD for AI)#

As an Architect, you should integrate this into your DevOps lifecycle.

1. The Tooling#

Don’t build this from scratch. Use established open-source tools:

• Promptfoo: Excellent for developer-centric, local CLI testing. Great for diffing prompt changes.
• DeepEval / Ragas: Python libraries specifically for calculating the RAG metrics mentioned above.
• LangSmith / Arize: Cloud platforms for managing datasets and running these evals on historical traces.

2. The Workflow#

Scenario: A developer wants to change the System Prompt to be “more concise.”

• Step 1 (Local): Developer runs promptfoo eval on their laptop against a subset of 10 test cases.
  • Result: Pass.
• Step 2 (PR): Developer opens a Pull Request.
• Step 3 (CI): GitHub Actions triggers the full regression suite (100 test cases).
  • Check: avg_faithfulness dropped from 0.92 $\rightarrow$ 0.85.
  • Action: Build Failed.
• Step 4 (Review): Developer inspects the failures, realizes “concise” made the model skip important safety warnings, and fixes the prompt.

V. Summary Checklist for the Principal Architect#

To “investigate” this part of the stack, I would ask the team these three questions:

1. “Do we have a Golden Dataset?” (If no, start curating 20 high-quality examples today).
2. “Are we logging inputs and outputs?” (You need raw data to build future datasets).
3. “Do we have a regression test?” (Can I change the prompt right now without fear of breaking the app?).