Module 1: Genai In Production Vs A Notebook

1. Guide introduction: the eighth piece of the ecosystem

Description

If you made it this far, Andes Cargo already has a real production system, not a prototype. An S3 bucket (andes-cargo-shipment-docs) that receives shipment manifests. A Lambda function, process-shipment-manifest, that parses them. A DynamoDB table, Shipments, with partition key shipmentId, that persists them. An event bus, andes-cargo-events, where ShipmentProcessed gets published every time a shipment is processed successfully. A Step Functions workflow, ShipmentManifestWorkflow, that chains validation, processing, and notification with real retries. A REST API, andes-cargo-api, that exposes GET /shipments/{shipmentId}. All of it declared in Terraform inside andes-cargo-infra/, running through a GitHub Actions pipeline with a security gate (policy-check/iac-scan/verify-artifact) and a cost gate (cost-estimate/cost-check/cost-tags) that no bad change can cross without being stopped.

This guide doesn't rebuild any of that. It adds to Andes Cargo its first generative AI workload — and, with it, a question that none of the seven previous guides had to answer: what changes when a piece of your production system is no longer deterministic? process-shipment-manifest always produces the same output for the same input. A language model doesn't. That single difference — determinism versus non-determinism — is the thread that runs through the eight lessons of this module, and the eight modules that follow in this guide.

Connection to the module

This is the opening module of an eight-module guide, and this is its first lesson. Its job, before touching Bedrock, guardrails, or cost per token, is to build the bridge: exactly what you inherit (this lesson), why "it works in a notebook" isn't the same as "it works in production" (lesson 2), what the real Andes Cargo problem is that justifies this guide (lesson 3), where this guide ends and AI Engineering begins (lesson 4), what genuinely exists today in the inherited infrastructure (lesson 5), which models Bedrock offers in 2026 and why the cheap path remains the default (lesson 6), what happens when you actually try to touch Bedrock from this $0 lab (lesson 7), and the document that closes the module: the ADR that fixes, in writing, the architecture decision that carries the whole guide (lesson 8).

The full map: the 8 modules of this guide

   GENAI IN PRODUCTION ON AWS — THE 8 MODULES

   M1  GenAI in production vs. a notebook     ← you are here: the bridge, the boundary, the ADR
   M2  The Bedrock cost model                 on-demand/Provisioned/Batch, the custom calculator
   M3  IaC for an AI endpoint                 bedrock.tf, real validate/plan, the most EXECUTED module
   M4  Bedrock guardrails and defense in depth   6 policies + custom scrubber
   M5  Securing the AI workload               the inherited security gate, extended
   M6  FinOps for tokens                      the inherited cost gate, extended
   M7  Observability, latency, and evals      AI SLI/SLO, the smoke test harness
   M8  Capstone: Andes Cargo's GenAI extractor   the full system, the honesty ledger

#	Module	What it builds	EXECUTED weight
1	GenAI in production vs. a notebook	The bridge, the boundary with AI Engineering, the ADR	Low — vocabulary and decision module
2	The Bedrock cost model	The custom cost-per-token calculator	Medium — inherited Infracost + new calculator
3	IaC for an AI endpoint	`bedrock.tf`, `modules/bedrock-guardrail/`, the IAM role	High — real `validate`/`plan`, no LocalStack
4	Bedrock guardrails and defense in depth	The managed guardrail in HCL + the custom scrubber	High — real HCL + custom Python with `pytest`
5	Securing the AI workload	`conftest`/Trivy/`cosign` extended, not rebuilt	High — same $0 tools, new Terraform
6	FinOps for tokens	The cost gate extended with a token budget	High — same mechanics, new policy
7	Observability, latency, and evals	Real CloudWatch + the smoke test harness	Medium — real logging, representative model output
8	Capstone: the GenAI extractor	The full system, with the honesty ledger	Mixed, declared line by line

Notice the progression: first you install the vocabulary and the decision (M1) — the LLM is an escalation path, not the default —, then you understand how much it really costs (M2) before declaring a single resource, then you declare the infrastructure (M3), put guardrails on it (M4), secure it (M5), and give it a budget (M6) by reusing the gates that already exist, you observe it (M7), and you close with the capstone (M8) that walks the full system end to end, with the exact honesty of what really ran and what stayed representative.

This module's map: the 8 lessons

#	Lesson	What you practice
1	Introduction (this one)	The full map, what's inherited from the previous seven guides, what exists by the time M8 closes
2	A notebook and a production system are not the same problem	Why "it works in the Bedrock playground" says nothing about cost, security, or reliability
3	Andes Cargo's AI workload	The real problem: free-text manifests that `process-shipment-manifest` can't read
4	The boundary with AI Engineering, said out loud	What this guide builds versus what AI Engineering builds — with no ambiguity, from lesson 4 on
5	Hands-on: inventory of what already exists	Executed (representative): `awslocal events list-rules`, `lambda list-functions`, `iam list-roles`
6	Bedrock, 2026 landscape	Amazon Nova, Claude, Llama, Mistral — verified against 2026 sources, with URLs
7	Hands-on: the honest attempt against Bedrock on LocalStack	Executed (the attempt) + representative (the conclusion): `awslocal bedrock list-foundation-models`
8	Project: Andes Cargo's AI workload map	Executed (the document): a short ADR, the decision that governs the rest of the guide

Analogy: arriving at the eighth restaurant of a chain that already works

Imagine you're hired as manager of the eighth location of a restaurant chain that already has seven locations running well: the kitchen is standardized, the supplier is negotiated, the reservation system works, there's an audited food safety protocol, and there's a monthly budget nobody skips without approval. Your job isn't to reinvent any of those seven things — it's to open the eighth location by adding one new dish to the menu, one that requires an ingredient none of the previous locations needed: something that cooks differently every time, from a supplier that charges per serving, not per hour the kitchen stays on. That new dish is Andes Cargo's generative AI workload. The rest of the restaurant — the kitchen, the supplier, the reservations, the protocol, the budget — is exactly what the seven previous guides already built, and this guide inherits without re-cooking.

What you inherit, without it being re-explained

This guide assumes, without repeating it, seven complete pieces of the ecosystem:

From aws-core-services-guide (transitive, via terraform-and-iac-guide): what single-account IAM is, and the four services that carry the case — S3, DynamoDB, Lambda, IAM — with process-shipment-manifest, the Shipments table, and the LambdaManifestProcessorRole/AppServerRole roles as the literal starting point.
From terraform-and-iac-guide: the full andes-cargo-infra/ project, the modules/s3-bucket//modules/iam-role/ modules, the init/plan/apply/destroy cycle. This guide adds bedrock.tf and modules/bedrock-guardrail/ to that same project, following the same naming convention.
From aws-serverless-and-containers-guide: the andes-cargo-events bus, the andes-cargo-api REST API, ShipmentManifestWorkflow in Step Functions, advanced Lambda (layers, environment variables, aliases). This guide's extractor is one more Lambda function, triggered by an event on that same bus.
From cicd-and-gitops-on-aws-guide: act as the local execution engine, ci.yml/apply.yml, the plan-on-PR/apply-on-merge pattern.
From cloud-security-and-guardrails-guide: the complete security gate (policy-check/iac-scan/verify-artifact), the policy/ directory, THREAT-MODEL.md/RISK-MAP.md. This guide adds new policies to that same directory, never replacing the ones already there.
From finops-and-cost-guardrails-guide: the complete cost gate (cost-estimate/cost-check/cost-tags), the cost-policy/ directory, Infracost already installed and its authentication limit already documented — this design inherits that finding, it doesn't re-investigate it.
From sre-and-incident-response-guide (transitive): the SLI/SLO/error budget vocabulary, already applied once to a Lambda and an API. This guide reapplies it to AI metrics, it doesn't reintroduce it from scratch.

And an eighth piece, AI Engineering, the full ecosystem — not an AWS guide, the entire ecosystem that precedes this one in the graph (BACKEND → AI ENGINEERING → AWS CLOUD). The learner arrives already knowing how to build AI systems: prompting, function calling, RAG, agents. This guide takes that as given, and doesn't repeat it — lesson 4 fixes that boundary with precision.

If any of these seven pieces doesn't feel solid, the signal is to go back to the corresponding guide before continuing. No lesson from here on re-explains what a Terraform resource is, an EventBridge event, or a pipeline job — only how a generative AI workload gets added to them.

What's genuinely new in this guide

No module in this guide rewrites a business resource already declared. The bucket is still andes-cargo-shipment-docs, the table is still Shipments with partition key shipmentId, the process-shipment-manifest function is still the first line of defense. What's new, always in the AI layer, never in the business layer:

  andes-cargo-infra/
  ├── THREAT-MODEL.md / RISK-MAP.md      (inherited — this module doesn't edit them)
  ├── policy/                             (inherited — M5 adds bedrock-least-privilege.rego)
  ├── cost-policy/                        (inherited — M6 adds bedrock-budget.rego)
  ├── bedrock.tf                          ← NEW (M3)
  ├── modules/
  │   ├── s3-bucket/  ├── iam-role/  ├── oidc-provider/   (inherited, unchanged)
  │   └── bedrock-guardrail/              ← NEW (M3)
  ├── functions/
  │   ├── process-shipment-manifest/      (inherited — M1.3 picks it back up, without rewriting it)
  │   └── extract-shipment-manifest-fields/   ← NEW (M3-M4)
  ├── guardrails/
  │   ├── pre_invoke_checks.py            ← NEW (M4) — PII scrubber
  │   └── post_invoke_checks.py           ← NEW (M4) — schema validator
  ├── scripts/
  │   └── bedrock_cost_estimate.py        ← NEW (M2) — cost-per-token calculator
  ├── evals/                              ← NEW (M7) — smoke test
  ├── GENAI-COST-PROFILE.md               ← NEW (M2) — companion to COST-PROFILE.md
  └── ADR-001-llm-as-escalation-path.md   ← NEW (M1.8, this lesson previews it)

The event that triggers this entire new layer doesn't exist yet either: ManifestParseFailed, published by process-shipment-manifest when a manifest arrives as free text and the key=value parser can't read it. Lesson 3 of this module introduces it with the full detail of the problem it solves.

This guide's honesty commitment, summarized up front

This is the only guide in the ecosystem where no lesson invokes a real model. Amazon Bedrock charges per token, requires an AWS account with an active payment method, and LocalStack's free plan (Hobby) doesn't include it — only the paid Ultimate plan does. None of that is a weakness of this guide: it's the exact nature of the service it teaches you to operate, and it's stated plainly from this first lesson, not hidden at the end.

What does run for real, with real $0 tools, carries most of the eight modules: terraform validate/plan on real Bedrock resources (M3 — confirmed by direct execution, without needing LocalStack or an AWS account, because a new resource never needs to read from state); a local, custom, deterministic guardrail (M4); conftest/Trivy/cosign/Infracost, reused from the sibling guides (M5/M6); the cost-per-token calculator, 100% deterministic Python code (M2); real CloudWatch logging and metrics (M7). What stays representative, always with the exact technical reason cited at the moment it appears: any real Bedrock invocation, a managed guardrail's real block, Infracost's dollar figure, and a model response's real latency/quality. This lesson only previews it — each module states it again, at the exact point where it applies.

Common mistakes

Assuming this guide is going to "teach you to use Bedrock" in the sense of writing prompts (expectation mistake). What happens: someone arrives expecting to learn prompt engineering, RAG, or agents on Bedrock, as a natural continuation of an AI Engineering course. How to spot it: if your question at the end of lesson 4 is still "but how do I write a better prompt?". How to fix it: this guide operates AI infrastructure — cost, security, guardrails, observability —, it doesn't build the AI application itself. Lesson 4 fixes this boundary with a direct quote from the ecosystem's own design, and it repeats every time a lesson brushes up against the temptation to teach prompting instead of infrastructure.

Skipping one of the seven previous guides because "this one already explains what's needed" (flow mistake). What happens: someone without aws-serverless-and-containers-guide arrives at lesson 5 of this module and doesn't recognize andes-cargo-events, ShipmentManifestWorkflow, or EventBridgeAutomationRole. How to spot it: if a name like process-shipment-manifest or a file like bedrock.tf (which extends, not replaces, andes-cargo-infra/) feels unfamiliar in context. How to fix it: go back to the corresponding guide from the list above. This guide assumes all seven in full, no exceptions, from this first lesson on.

Concluding, from reading "no lesson invokes a real model," that this guide doesn't build anything real (reading mistake). What happens: someone reads this section's honesty commitment and decides the whole guide is theoretical. How to spot it: if your mental summary is "this guide is pure slideware." How to fix it: M3 — infrastructure as code for an AI endpoint — is, proportionally, the module with the most executed weight in this entire guide: terraform validate/plan on a full aws_bedrock_guardrail runs for real, without LocalStack, without an AWS account, without a token, because declaring and planning a new resource never requires connectivity to the real API. The only thing that doesn't run is inference — the model actually responding — which is, precisely, the one piece this guide exists to teach you to operate around, not to build.

Exercises

Exercise 1 — Name the seven inherited guides, without looking at the table. From memory, write down the seven guide names this guide assumes complete, and which concrete piece of andes-cargo-infra/ each one contributes.

See solution

aws-core-services-guide (transitive) — process-shipment-manifest, the Shipments table, the base roles. terraform-and-iac-guide — the full andes-cargo-infra/ project, the s3-bucket/iam-role modules. aws-serverless-and-containers-guide — the andes-cargo-events bus, the andes-cargo-api API, ShipmentManifestWorkflow. cicd-and-gitops-on-aws-guide — act, ci.yml/apply.yml. cloud-security-and-guardrails-guide — the security gate (policy-check/iac-scan/verify-artifact). finops-and-cost-guardrails-guide — the cost gate (cost-estimate/cost-check/cost-tags). sre-and-incident-response-guide (transitive) — the SLI/SLO/error budget vocabulary. If you remembered at least five without looking, you have a clear grasp of the foundation this whole guide builds on.

Exercise 2 — Explain, in one sentence, the single technical difference that justifies an entire guide. A colleague asks why an eight-module guide is needed just to "add an AI model" to a system that already works. Answer them with this lesson's central idea.

See solution

A complete answer sounds, roughly, like this: "Because process-shipment-manifest is deterministic — the same input always produces the same output —, and everything the previous seven guides taught about predictable cost, verifiable security, and a literal 'What to expect' assumes that. A language model isn't deterministic: the same input can produce a different output, it costs per token instead of per hour running, and it needs a defense layer that a 'normal' AWS resource never needed. That single difference — determinism versus non-determinism — is what justifies eight new modules, not an extra chapter in an existing guide."

Exercise 3 — Locate where each new piece lives in andes-cargo-infra/. Without looking at this lesson's diagram, name at least four of the seven new artifacts this guide adds to the project, and which module each one appears in.

See solution

bedrock.tf and modules/bedrock-guardrail/ (M3); guardrails/pre_invoke_checks.py and guardrails/post_invoke_checks.py (M4); scripts/bedrock_cost_estimate.py (M2); policy/bedrock-least-privilege.rego (M5); cost-policy/bedrock-budget.rego (M6); evals/ (M7); GENAI-COST-PROFILE.md (M2) and ADR-001-llm-as-escalation-path.md (M1, this very introductory lesson's project). If you named four without looking, you have a clear grasp of this guide's module-by-module progression.

Summary and next step

In this lesson you saw the full map of this guide's 8 modules, confirmed what's inherited without repeating from the previous seven guides in the ecosystem — infrastructure, pipeline, security gate, cost gate, SRE vocabulary — and what's genuinely new: seven artifacts in the AI layer, none in the business layer. You also saw, up front, this guide's honesty commitment: it's the only one in the ecosystem where no lesson invokes a real model, with the exact technical reason (Bedrock charges per token and isn't in LocalStack's free plan), and where real code does run: Terraform, Python, the inherited gates.

Before moving on you should be able to: name the eight modules in order and what each one builds; explain why this guide doesn't repeat the previous seven; and say, without hesitating, the difference between "invoking a model" (never happens here) and "declaring and planning a model's infrastructure" (happens, for real, starting in M3).

Lesson 2 installs the module's central thesis: why "it works in the Bedrock playground" says absolutely nothing about whether that same call is safe, cheap, or reliable in production — the deliberate echo of a lesson you already saw, in other words, in the two previous guides in this same ecosystem.

Resources

terraform-and-iac-guide, aws-serverless-and-containers-guide, cicd-and-gitops-on-aws-guide, cloud-security-and-guardrails-guide, finops-and-cost-guardrails-guide, sre-and-incident-response-guide (NIEVA) — the six guides whose completed work this guide inherits without repeating.
src/paths/aws-cloud-ecosystem/STRATEGY.md — this guide's position in the ecosystem graph, after AI Engineering: "The learner arrives already knowing how to build AI systems. It doesn't repeat fundamentals: it teaches how to operate them".
AWS — Amazon Bedrock — the service's official page, which this entire guide learns to operate, the starting point of lesson 6.
LocalStack Docs — Bedrock — the exact source of why this guide can't invoke a model: "Included in Plans: Ultimate", no Hobby.
src/paths/aws-cloud-ecosystem/VALIDACION.md — the market audit that fixes this guide's weight and position as a closing differentiator, not an entry point.

Next →2. A notebook and a production system are not the same problem