Appendix B — The Two Capstones: Use Cases at a Glance
Read this when you need to explain the book’s two capstone systems to someone who won’t read the code: a product owner, an architect reviewing the design, or a team choosing which pattern to copy.
You get: the business problem, actors, use cases, a conceptual domain model and an end-to-end journey for each capstone, plus the shared pattern that lets one decision client serve both.
| Capstone 1: Incident & FinTech Triage Engine (Part I, Ch 1–8) | Capstone 2: SmartPlant Decision Intelligence (Part II, Ch 9–13) | |
|---|---|---|
| Domain | Payments support & fraud operations | Industrial IoT predictive maintenance |
| Trigger | A customer report or fraud-monitor alert (JSON) | Motor telemetry crossing a meaningful band, or a heartbeat |
| Decision model | Jev, hosted by TypeSafe | Kev, self-hosted open source |
| Typed questions | is_fraud_suspected (Noul) · urgency_rating 1–5 (Score) · dispatch_target (Choice) | intervention_urgency (Choice) · operational_action (Choice) · standard_workflow (Noul) · operational_severity 1–5 (Score) |
| What can go wrong | Money lost to an account takeover; wrong refund | Equipment damage, unplanned downtime, missed delivery |
| Hard boundary in code | Refunds > ₹50k need approval; manipulation never auto-routes | PLC trips stay authoritative; load transfer / shutdown need an authorised human |
| Decision cadence | Per report, seconds matter | Per meaningful change, latency budget ~1 s on the edge |
| Fallback when the model is down | Keyword rules → SecOps or manual escalation, never refunds | Threshold rules → INSPECT + specialist review, never TRANSFER_LOAD |
| Proof of action | Re-read the ticket / case / refund record | Re-read the CMMS work order; hash-chained audit |
| Learning loop | Labeled replay set, threshold sweeps | Expert-labelled outcomes → Kev fine-tuning |
B.1 One pattern, two domains
Both capstones are the same six-step loop. Only the inputs, questions and actions change, and that’s why triage.jev_client.DecisionClient and triage.resilience.CircuitBreaker serve both without modification.
The invariants every use case below inherits:
- Code computes, the model decides, people authorise, fresh state proves.
- The model only sees evidence (never instructions hidden in data) and only eligible options.
- Every consequential action has a deterministic floor or gate the model can’t go below.
- Silence is never consent and an outage never drops a case. There’s always a fallback route.
- Every decision is reconstructable from its trace or audit chain.
B.2 Capstone 1: Incident & FinTech Triage Engine
Problem
A payments company receives thousands of support messages and fraud-monitor alerts a day. A few are account takeovers where money is leaving now. Most are how-to questions, duplicate charges or slow screens. Manual triage takes minutes to hours, and keyword rules either flood SecOps or miss real fraud. LLM triage adds 2–8 s per message and an uncalibrated “confidence”.
Goal: every report is triaged in about 100 ms. Account takeovers reach SecOps at P1 within seconds, refunds move only through policy, and humans see only the uncertain or irreversible cases.
Actors
| Actor | Role in the system |
|---|---|
| Customer | Sends the report (untrusted text) |
| Fraud monitor | Upstream rules/ML that raise alerts with signals |
| Tier-1 agent | Handles how-to and service issues |
| SecOps analyst | Investigates suspected fraud and account takeover |
| Refund approver | Approves refunds above the policy limit |
| Escalation team | Handles legal, regulatory, bereavement, manipulation and low-confidence cases |
| Jev | Answers the typed triage questions |
Use cases
Purple is the core path that always runs: triage, then verify and trace. Teal is the money path: open a refund, then approve it above ₹50k. Coral covers the risk and safety branches: fraud override, escalation, and safe degradation.
| ID | Use case | Main rule | Built in |
|---|---|---|---|
| UC-F1 | Triage an incoming report | One Jev call: fraud, urgency, target + speculative questions | Ch2–3 |
| UC-F2 | Route suspected fraud to SecOps | is_fraud_suspected ≥ 0.85 overrides the model’s own routing; 0.50–0.85 → SecOps with confirmation | Ch4 |
| UC-F3 | Open a refund request | Requires a posted transaction (eligibility) and ≥ 0.90 confidence | Ch3–4, Ch6 |
| UC-F4 | Approve refund above limit | Amount band above_50k → requires_human_approval, computed in code | Ch4 |
| UC-F5 | Escalate manipulation / low confidence | contains_instructions_to_system ≥ 0.5 or below per-target gate → manual escalation | Ch4–5 |
| UC-F6 | Degrade safely when Jev is unavailable | Circuit breaker + keyword fallback; fallback can never move money | Ch5 |
| UC-F7 | Verify outcome & write decision trace | Re-read ticket/case/refund; second failure → escalate | Ch4, Ch6, Ch8 |
Conceptual model
Journey: an account takeover, end to end
Success measures
| Measure | Target direction |
|---|---|
| Time from report to SecOps P1 for confirmed takeovers | Seconds, not queue minutes |
| Adversarial rows auto-routed to money | 0 (release gate, Ch5) |
| Share of reports auto-routed in the high band | Up, without precision dropping below target |
| Escalation share | Stable; spikes trigger a review (Ch8 runbook) |
| Decision-layer cost | ≈ $57 per 3M reports on Jev (Ch8 estimate) |
B.3 Capstone 2: SmartPlant Decision Intelligence
Problem
A production line runs motors, pumps and bearings. Threshold alarms say something is wrong but not what to do. Operators must weigh machine condition, data quality, maintenance history, spare parts, backup capacity and a high-priority order, often at 3 a.m. Telemetry can’t leave the plant network, and protective functions must never depend on software that might be down.
Goal: minimise unplanned downtime while protecting people, equipment, product quality and delivery commitments. The system turns every meaningful change in an asset’s condition into a bounded, explained recommendation that a human can trust and audit.
Actors
| Actor | Role in the system |
|---|---|
| Sensors / OPC UA–MQTT gateway | Deliver readings every ~10 s |
| PLC / SIS | Owns interlocks and protective trips (authoritative, outside SmartPlant) |
| Operator | Sees recommendations; performs inspections |
| Shift supervisor | Approves load transfer and shutdown requests (authorised role) |
| Maintenance technician | Executes work orders, records findings |
| Reliability engineer | Labels outcomes, owns limits, thresholds and the fine-tuning loop |
| Kev | Answers the typed operational questions on the edge box |
Use cases
Purple marks the core decision path (S1 → S2 → S3). Coral marks the safeguard branches (S4, S5, S6). Teal marks the learning loop (S7 → S8).
- S1 → S5 fires when the limit is reached.
- S2 → S4 fires on TRANSFER_LOAD or REQUEST_SHUTDOWN.
- S2 → S6 fires on invalid data or when the breaker is open.
| ID | Use case | Main rule | Built in |
|---|---|---|---|
| UC-S1 | Build a trusted edge snapshot | Bands, trends, staleness, stuck/noisy/missing sensors computed in code | Ch9 |
| UC-S2 | Recommend an operational response | One Kev call; code safety floor; production priority can’t lower it | Ch10 |
| UC-S3 | Create / escalate a work order | One work order per asset/action/episode; worse condition escalates it | Ch11 |
| UC-S4 | Approve load transfer or shutdown request | Named operator with an authorised role; silence = denial → INSPECT | Ch11 |
| UC-S5 | Mirror a protective trip | Latched mirror of the PLC; no model call; controlled-shutdown request documented | Ch9, Ch11 |
| UC-S6 | Fall back on bad data or Kev outage | Invalid data never reaches Kev; breaker + threshold rules; never TRANSFER_LOAD | Ch10–11 |
| UC-S7 | Record outcome & expert labels | Technician finding + engineer labels appended to the hash-chained audit | Ch11, Ch13 |
| UC-S8 | Benchmark & fine-tune Kev | 10-scenario replay (rules vs LLM vs Kev); audit → kev.train | Ch12–13 |
Conceptual model
Journey: a bearing degrades during a high-priority order
Success measures
| Measure | Target direction |
|---|---|
| Critical-case miss rate (under-escalation) | 0 (release gate, Ch12) |
| Unnecessary interventions on healthy assets | Down vs threshold alarms |
| Time from first abnormal zone to inspection work order | Minutes, not shifts |
| Fallback success when Kev is down | 100 % of cases still get a safe action |
| Audit completeness | 100 % of decisions reconstructable |
| Automation at a 5 % error budget after fine-tuning | Up, per checkpoint (Ch13) |
B.4 Choosing your own third use case
The capstones are templates. A new domain fits this pattern when you can answer yes to all of these:
- The decision repeats often enough that latency and cost compound
- The answer space can be bounded: options, yes/no, or a describable rubric
- Exact facts (amounts, dates, counts, limits) can be computed in code first
- There’s a safe default for when the model is unsure or unavailable
- Consequential actions can be gated by code and, where needed, a human
- The outcome can be verified in a system of record
- You can collect labelled examples, including ambiguous and adversarial ones
Pick Jev when hosted latency and calibration matter most and data may leave your network. Pick Kev when data must stay on-site, you need offline operation, or you want to fine-tune on your own decisions. Either way, the client, breaker, trace and evaluation discipline are the same.