Module 8: Capstone The Andes Cargo Genai Extractor
3. End-to-end walkthrough: the deterministic, cheap path, executed
Description
This lesson walks through, end to end, the left half of lesson 2's diagram — the deterministic path — with a single goal: to prove, with really-run code, that a well-formed manifest never triggers ManifestParseFailed. This isn't a theoretical claim repeated for the third time; it's parse_manifest(), exactly the same code from process-shipment-manifest M1.3 already presented, run here against a new batch of well-formed manifests, with the same escalation criterion escalation_rate.py (M7.4) already encoded. The result, literal: zero out of ten manifests escalate. extract-shipment-manifest-fields never gets invoked. Bedrock never gets touched.
Connection to the module
This lesson is the first half of the walkthrough lesson 2 promised: the deterministic path, fully executed, with no representative exception whatsoever — unlike lesson 4, which does hit a real limit halfway through. It's also the living proof of ADR-001's (M1.8) central thesis: the LLM is an escalation path, not the default.
Analogy: the ATM that never needed to call a human
Going back to lesson 2's analogy: an ATM that processes a hundred cash withdrawals in a row, all with a valid card and sufficient balance, never triggers the bell that calls the bank staff — not even once, because none of those hundred cases needed human help. This lesson is exactly that run of a hundred withdrawals: a batch of manifests, all with the shape Andes Cargo always expected, processed by the ATM (parse_manifest()), with the human counter (extract-shipment-manifest-fields) receiving not a single call.
Step 1 — The batch: ten well-formed manifests, never randomly generated
Reuses, with no change, parse_manifest() (M1.3) and SHIPMENT_FIELDS_SCHEMA/would_escalate() (M4.6, M7.4). This lesson's batch cycles among the three already-known shipments (4471, 4472, 4473) and adds a fourth (4477), new in this lesson, to confirm the result doesn't depend on always reusing the same three texts:
#!/usr/bin/env python3
"""deterministic_path_walkthrough.py -- Module 8, lesson 3 of
genai-on-aws-production-guide. Runs parse_manifest() (Module 1, lesson 3)
and would_escalate() (Module 7, lesson 4) against a batch of TEN
well-formed manifests only -- never a mixed batch like escalation_rate.py's
50 events. The claim this script proves: a well-formed manifest never
escalates, period.
Never uses random or datetime.now(). Same batch, same order, every run.
"""
from __future__ import annotations
# --- parse_manifest(): Module 1, lesson 3, unmodified ----------------------
def parse_manifest(text: str) -> dict:
fields = {}
for line in text.strip().splitlines():
if "=" in line:
key, _, value = line.partition("=")
fields[key.strip()] = value.strip()
return fields
# --- SHIPMENT_FIELDS_SCHEMA / would_escalate(): Module 4/7, unmodified -----
SHIPMENT_FIELDS_SCHEMA = (
"shipmentId",
"originCountry",
"destinationCountry",
"carrier",
"weightKg",
)
def would_escalate(parsed: dict) -> bool:
return bool(set(SHIPMENT_FIELDS_SCHEMA) - set(parsed.keys()))
# --- Four known shipments, cycled ten times ---------------------------
SHIPMENTS = {
"4471": {"originCountry": "Peru", "destinationCountry": "Chile", "carrier": "AndesExpress", "weightKg": "120"},
"4472": {"originCountry": "Colombia", "destinationCountry": "Ecuador", "carrier": "AndesExpress", "weightKg": "85"},
"4473": {"originCountry": "Chile", "destinationCountry": "Peru", "carrier": "RutaSur", "weightKg": "200"},
"4477": {"originCountry": "Bolivia", "destinationCountry": "Peru", "carrier": "RutaSur", "weightKg": "60"},
}
CYCLE = ["4471", "4472", "4473", "4477"]
TOTAL_MANIFESTS = 10
def well_formed_manifest(shipment_id: str) -> str:
fields = {"shipmentId": shipment_id, **SHIPMENTS[shipment_id]}
return "\n".join(f"{k}={v}" for k, v in fields.items()) + "\n"
def main() -> int:
escalated = 0
for i in range(TOTAL_MANIFESTS):
shipment_id = CYCLE[i % len(CYCLE)]
text = well_formed_manifest(shipment_id)
parsed = parse_manifest(text)
escalates = would_escalate(parsed)
status = "ESCALATES" if escalates else "write_shipment_record()"
print(f"[{i + 1:02d}] shipmentId={shipment_id:<6s} fields={len(parsed)}/5 -> {status}")
if escalates:
escalated += 1
total = TOTAL_MANIFESTS
print()
print(f"Total well-formed manifests {total}")
print(f"Escalated (ManifestParseFailed) {escalated}")
print(f"Escalation rate {round((escalated / total) * 100, 1)}%")
return 0
if __name__ == "__main__":
raise SystemExit(main())Notice SHIPMENTS["4477"]: a fourth shipment, never used in any previous lesson in this guide — proof this lesson's result doesn't depend on reusing, over and over, the same three texts 4471/4472/4473 have made familiar since M1.3.
Step 2 — Running the complete walkthrough, for real
python3 deterministic_path_walkthrough.pyWhat to expect (literal — really run, this same guide's environment; parse_manifest() and would_escalate() with no change from M1.3/M7.4):
[01] shipmentId=4471 fields=5/5 -> write_shipment_record()
[02] shipmentId=4472 fields=5/5 -> write_shipment_record()
[03] shipmentId=4473 fields=5/5 -> write_shipment_record()
[04] shipmentId=4477 fields=5/5 -> write_shipment_record()
[05] shipmentId=4471 fields=5/5 -> write_shipment_record()
[06] shipmentId=4472 fields=5/5 -> write_shipment_record()
[07] shipmentId=4473 fields=5/5 -> write_shipment_record()
[08] shipmentId=4477 fields=5/5 -> write_shipment_record()
[09] shipmentId=4471 fields=5/5 -> write_shipment_record()
[10] shipmentId=4472 fields=5/5 -> write_shipment_record()
Total well-formed manifests 10
Escalated (ManifestParseFailed) 0
Escalation rate 0.0%
Ten out of ten, zero escalations. Every line shows fields=5/5 — SHIPMENT_FIELDS_SCHEMA's five fields present, with no exception — and the final column confirms, for each one, that the next step would be write_shipment_record(), inherited unchanged from aws-core-services-guide, Module 7: never ManifestParseFailed, never extract-shipment-manifest-fields, never Bedrock.
Step 3 — Contrasting with M7.4's mixed batch, side by side
This comparison exists so this lesson's 0.0% doesn't read as a coincidence but as the direct consequence of a deliberately different batch:
M7.4 -- MIXED BATCH (50 events) M8.3 -- THIS BATCH (10 events)
44 well-formed + 6 that escalate 10 well-formed, 0 that escalate
(on purpose, to have something (on purpose, to prove the
the SLI can measure) other half of ADR-001's thesis)
Result: 12.0% escalation Result: 0.0% escalation
Both batches are HAND-BUILT, deterministic, never "random" nor a
sample of real traffic -- the same honesty M7.4, Step 5 already
declared for its own number.Neither of these two numbers contradicts the other: M7.4 measured what proportion of a batch designed to include failures escalates; this lesson measured what proportion of a batch designed to have none escalates. The two results, together, confirm the same mechanism from two angles: would_escalate() returns False for every well-formed manifest, with no exception, and True only when at least one field is missing — never randomly, never based on batch volume.
Step 4 — Confirming the result with pytest, one new case
"""test_deterministic_path_walkthrough.py -- Module 8, lesson 3. Confirms,
as an executable assertion, the exact claim this lesson makes in prose:
an all-well-formed batch never escalates. No random, no datetime.now()."""
from deterministic_path_walkthrough import CYCLE, TOTAL_MANIFESTS, well_formed_manifest, parse_manifest, would_escalate
def test_all_ten_manifests_have_five_fields():
for i in range(TOTAL_MANIFESTS):
shipment_id = CYCLE[i % len(CYCLE)]
parsed = parse_manifest(well_formed_manifest(shipment_id))
assert len(parsed) == 5
def test_zero_of_ten_escalate():
escalated = sum(
would_escalate(parse_manifest(well_formed_manifest(CYCLE[i % len(CYCLE)])))
for i in range(TOTAL_MANIFESTS)
)
assert escalated == 0
def test_new_shipment_4477_is_well_formed():
parsed = parse_manifest(well_formed_manifest("4477"))
assert would_escalate(parsed) is False
assert parsed["originCountry"] == "Bolivia"pytest test_deterministic_path_walkthrough.py -v -p no:randomlyWhat to expect (literal — really run):
============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0
collected 3 items
test_deterministic_path_walkthrough.py::test_all_ten_manifests_have_five_fields PASSED [ 33%]
test_deterministic_path_walkthrough.py::test_zero_of_ten_escalate PASSED [ 66%]
test_deterministic_path_walkthrough.py::test_new_shipment_4477_is_well_formed PASSED [100%]
============================== 3 passed in 0.01s ===============================
Step 5 — The one thing this walkthrough doesn't execute, and why it isn't a new limit
write_shipment_record() — the step that, in the real system, would write each of these ten records to Shipments — doesn't run against a real DynamoDB table in this lesson, for the exact same reason M3.4 already documented for BedrockManifestExtractorRole: this specific writing environment has no LOCALSTACK_AUTH_TOKEN exported, so no LocalStack service starts here — not even DynamoDB, which is included in the free Hobby plan. This isn't a new limit in this lesson; it's the same environment limit, already declared, now applied to the deterministic path's last step. On your own machine, with a real Hobby token exported, this lesson's ten write_shipment_record() calls would really execute, writing ten real items to an emulated Shipments table — with parse_manifest() and would_escalate(), this lesson's real core, not changing a single line.
Common mistakes
Concluding this lesson's 0.0% "proves" Andes Cargo will never need the escalation path (generalizing from a deliberately built batch to all real traffic). What happens: someone, seeing zero escalations in this batch, concludes extract-shipment-manifest-fields is unnecessary. How to spot it: if your takeaway from this lesson is "so AI is never needed for this." How to fix it: this batch was deliberately built with ten well-formed manifests — the same honesty M7.4, Step 5 already applied to its own mixed batch's 12.0%. M1.3 already documented, with a real email, that free-text manifests parse_manifest() can't read do exist; this lesson doesn't deny that, it proves the complementary half: when the manifest DOES have the correct shape, the system never escalates unnecessarily.
Thinking this lesson's 4477 is the same kind of "new case" as M7.6's 4475/4476 (confusing two batches with different purposes). What happens: someone looks for 4477 in evals/fixtures/sample_manifests.json (M7.6) and doesn't find it, and wonders whether this lesson made a continuity mistake. How to spot it: if your expectation is that every new shipment in this guide shows up in M7.6's fixtures file. How to fix it: 4477 is a new shipment, exclusive to this lesson, chosen only to demonstrate the 0.0% result doesn't depend on reusing the same three texts as always — it was never part of the smoke test harness's fixtures batch, which has its own, different purpose (testing validate_shipment_fields(), not would_escalate()).
Assuming write_shipment_record() not running in this lesson invalidates the rest of the walkthrough (treating a representative step as if it contaminated the real ones). What happens: someone, reading Step 5, concludes "so this lesson isn't 100% executed either." How to spot it: if your summary of this lesson includes the word "representative" applied to parse_manifest() or would_escalate(). How to fix it: this lesson's central claim — a well-formed manifest never triggers ManifestParseFailed — depends exclusively on parse_manifest() and would_escalate(), both 100% real, run and verified with pytest. That the final DynamoDB write step depends on a LocalStack token this specific environment doesn't have is a detail of the writing environment, not a crack in the central claim this lesson proves.
Exercises
Exercise 1 — Modify, yourself, SHIPMENTS["4477"] so it's missing the weightKg field, and add it to the cycle. Before running the script, predict what would happen to the batch's escalation rate.
See solution
The escalation rate would stop being 0.0% — with 4477 missing weightKg, that specific manifest (which appears two or three times in a ten-item cycle, depending on position) would make would_escalate() return True every time it appears. With TOTAL_MANIFESTS = 10 and a four-element cycle, 4477 would appear at positions 4 and 8 (twice), so the new rate would be 2/10 = 20.0%. This exercise confirms, with your own change, that this lesson's 0.0% isn't a fixed value in the code — it depends, entirely, on every manifest in the batch genuinely being well-formed, exactly as this lesson's Step 3 already explained in contrast with M7.4.
Exercise 2 — Explain, in your own words, why this lesson chose a batch of TEN manifests, instead of, say, a hundred or a thousand. Does the batch's size change the validity of the conclusion this lesson demonstrates?
See solution
It doesn't change the conclusion's validity — would_escalate() is a pure, deterministic function: given a parsed with all five fields present, it always returns False, no matter how many times it's called or in what order. A batch of ten is enough to demonstrate the mechanism with legible clarity; a batch of a thousand would produce exactly the same 0.0%, just with a thousand output lines instead of ten, adding no additional evidence about the mechanism's own correctness. Choosing ten is a pedagogical-readability decision, not a limitation of what the code can prove — the same distinction M7.4, Exercise 3 already made between "determinism of the calculation" and "sample size."
Exercise 3 — Predict what would happen if, in Step 4, someone added a fifth test that reuses well_formed_manifest("4471") and compares it, field by field, against SHIPMENTS["4471"] from Module 7, lesson 4 (observability/escalation_rate.py). Should they match exactly?
See solution
Yes, they should match exactly — both dictionaries (SHIPMENTS["4471"] in this lesson and in escalation_rate.py) describe the same Andes Cargo shipment 4471 (Peru → Chile, AndesExpress, 120kg), the same one M1.3 originally introduced. A test that compared both and found a difference would correctly flag a real inconsistency between two parts of this guide that should be telling the same story about the same shipment — exactly the kind of continuity check a careful engineer would run before presenting either script as part of one coherent system.
Summary and next step
This lesson proved, with code executed in its entirety — parse_manifest() and would_escalate(), with no change from M1.3/M7.4 —, lesson 2's diagram's left half: ten well-formed manifests, 0.0% escalation, also verified with three pytest cases. You contrasted this result with M7.4's mixed batch's 12.0%, confirming both numbers are consistent with the same mechanism, not contradictory. The only step this walkthrough doesn't execute against a real service — write_shipment_record() on DynamoDB — stays representative for the same, already-known environment reason M3.4 established for BedrockManifestExtractorRole.
Before moving on you should be able to: run deterministic_path_walkthrough.py with your own fifth shipment and predict the result; explain why 0.0% here and 12.0% in M7.4 don't contradict each other; and name the exact reason — of environment, not of service — why the final write to Shipments stays outside this lesson's executed scope.
Lesson 4 walks through the diagram's other half: the escalation path, where ManifestParseFailed really does fire, and where the walkthrough becomes, quite deliberately, mixed — real up to the exact point of invoking Bedrock, representative from there.
Resources
- This same course, Module 1, lesson 3 (
03-andes-cargos-ai-workload-when-the-deterministic-parser-is-not-enough.md) — the origin ofparse_manifest(), run here with no change. - This same course, Module 7, lesson 4 (
04-hands-on-the-escalation-rate-metric.md) — the origin ofwould_escalate()and the mixed batch this lesson's Step 3 contrasts. - This same course, Module 3, lesson 4 (
04-hands-on-bedrockmanifestextractorrole-least-privilege.md) — the source for the "environment limit, not a service limit" distinction this lesson's Step 5 reapplies. - AWS Docs — DynamoDB
PutItem— official reference for the operationwrite_shipment_record()would execute, inherited fromaws-core-services-guide.