Chapter 0.9 — Narrative thread case study: Hermes Logística¶
🎯 Chapter objective¶
Introduce a recurring narrative case study that will appear across several parts of the book as short vignettes. The case gives concrete weight to decisions — when a technique is discussed in the abstract, it is easy to agree; when it appears in a context with real constraints (multi-tenant, language, regulation, tight budget), the trade-offs become visible.
⚠️ Not a runnable example. Nothing here is real code; no "Hermes Logística" company needs to exist for the book to work. The case is didactic and deliberately plausible. When the practical examples in
labs/are implemented, they will be linked to parts of this case by conceptual affinity — not by a promise of faithful reproduction. Today, Hermes appears exclusively as narrative.
🏢 Scenario¶
Hermes Logística is a fictional B2B company that operates a freight and warehouse platform for mid-sized retailers and manufacturers. The operations team receives hundreds of tickets per day: tracking, order discrepancies, refunds, cancellations, integration with the customer's ERP, escalation to legal, etc. There are several tenants (end customers), three operational languages, and regulatory requirements by region.
Hermes's AI team starts small and grows in waves that will appear throughout the book:
| Wave | What comes in | Why |
|---|---|---|
| Wave 1 — Classic triage | Traditional ML intent classifier + routing | Cut volume with something cheap and auditable |
| Wave 2 — Knowledge via RAG | Per-tenant RAG for FAQ, contracts and SLA | Reduce made-up answers, keep freshness |
| Wave 3 — Actions via agent | Agent with tools (CRM, billing, WMS) and HITL | Automate repetitive steps with human approval |
| Wave 4 — Harden | Policy-as-code, tenant isolation, threat modeling, audit | Pass audit, withstand a real incident |
| Wave 5 — Operate | Observability, continuous evals, per-tenant FinOps | Sustain in production, not just go-live |
| Wave 6 — Lifecycle | Versioning, canary, tool deprecation, breaking changes | Change without causing an incident |
Hermes is deliberately "ordinary": it is not big tech, it does not have an infinite budget, it does not run on its own dedicated GPU cluster. It is the kind of environment most teams will operate in.
🧭 Main constraints of the case¶
- Latency. Chat responses: p95 ≤ 8 s. Initial classification: p95 ≤ 200 ms. CRM operations via agent can reach tens of seconds when human approval is involved.
- Cost. The average cost per automated ticket must stay below the average cost of a human agent for the equivalent task, with a margin defined in an ADR.
- Privacy. End-customer PII (tax IDs, email, address, order history) must not cross tenants nor leave the regional perimeter without a contract.
- Auditing. Every action executed by an agent needs a trail: who proposed it (model), who authorized it (policy + human when applicable), with which tool version, against which resource.
- Operation. The operations team is small; runbooks, alerts and rollback must be simple enough to be used at 3 a.m.
🧪 How this case is used in the book¶
Hermes reappears at moments such as:
- Part 1 (traditional ML). Intent classifier, drift when Hermes enters a new vertical, per-tenant fairness.
- Part 2 (LLMs). Per-tenant RAG; when the team tries to solve "knowledge" with fine-tuning and why it goes back to RAG; embeddings and Matryoshka to control retrieval cost.
- Part 3 (Agentic AI). Agent that creates/updates tickets; tool registry; using MCP to integrate with a large customer's ERP; why multi-agent is avoided.
- Part 4 (Security). Threat modeling with adapted STRIDE; indirect prompt injection from end-customer messages; vector poisoning during manual ingestion; tenant isolation in the retriever.
- Part 5 (Observability). How an incident ("agent opened a ticket in the wrong tenant") was diagnosed from semantic spans; eval regression before promoting a prompt.
- Part 6 (Costs). Why the bill doubled in a week; use of gateway, cache and model routing; per-tenant budget.
- Part 7 (Lifecycle). Deprecation of
tool crm.update_contact@1.xwith a window, dual-read in the RAG index, breaking change communicated to internal consumers.
🚧 What the case is not¶
- Not a real case study. Any resemblance to a specific company is coincidental. The numbers used are plausible orders of magnitude, not measurements.
- Not an implementation. There is no associated code at this stage of the book. When examples in
labs/are delivered, they will be linked to parts of this case by affinity. - Not a single recipe. Hermes shows one reasonable path; other paths would be equally defensible. The case exists to make trade-offs concrete.
📌 How to follow the case¶
Passages about Hermes appear throughout the book as explicitly marked blocks:
🏢 Hermes Logística — wave X. (short narrative of a decision or mistake, tied to the current chapter).
These blocks are optional for reference reading. In linear mode, they work as grounding for what was just discussed.