Foundations of Agentic AI for Retail: Companion Code (Third Edition)

The runnable companion to Foundations of Agentic AI for Retail, Third Edition. Agent architectures, decision frameworks, coordination protocols, guardrails, evaluation and end-to-end demos, as the book prints them, with a regression test for each.

Foundations of Agentic AI for Retail: Designing, Building, and Operating Retail AI Agents, from First Principles to Production, Third Edition (October 2026), by Fatih Nayebi. A pricing agent marks down a winter coat in one region, exactly as its rules allow, and by morning the brand owns the outcome. The book asks when a retailer should hand a decision to software, and what evidence and controls make the handover worthwhile, from first principles to production. In paperback and hardcover, in full color. The Kindle edition will follow. Buy on Amazon: US | CA | UK | DE | FR | IT | ES | JP Earlier editions: second (2026) | first (2025)

Start Here

git clone https://github.com/gradient-divergence/agentic-retail-foundations.git
cd agentic-retail-foundations
uv sync --frozen                                    # Python 3.13, the locked environment

uv run --frozen python -m demos.intro_inventory_book_demo   # Chapter 1's reorder agent
uv run --frozen python -m demos.capstone_scaffold_demo      # the capstone's approval-and-receipt record
uv run --frozen python -m demos.capstone_gate_review_demo   # Chapter 14's simulated gate review

The tag third-edition is the code exactly as printed. For the full test suite, install every extra (uv sync --frozen --all-extras) and run MPLBACKEND=Agg uv run --frozen python -m pytest: 1,029 tests.

The Book, Chapter by Chapter

Where each chapter's printed listings live. Every runnable listing in the book comes from this repository.

What's New in the Third Edition

• Repaired code. The demos, agents and utilities were repaired for this edition, and the book's printed listings are drawn from this code.
• Regression tests. Each repair came with a test; the suite grew from 36 test files to 113, and all 1,029 tests pass.
• Demos that say what they need. A demo that needs an API key or a running service now names it and stops, instead of failing midway.
• Current stack. Python 3.13 and the latest compatible releases of every dependency, locked in uv.lock.
• Tags. third-edition (and v3.1.0) marks the code as printed in the published third edition; v3.0.0 is the 7 October pre-release state, and v2.0.0 is the second edition's.

• Retail Agent Operating Model (RAOM) as the narrative spine across chapters and code.
• Capstone workflow that accumulates across chapters (inventory risk → supplier outreach → price protection → customer messaging → audit trail).
• Three-plane architecture: capability, control, and integration planes for system design.
• Contract-first schemas with runnable companion code and drift controls.
• Evaluation pyramid + red-team packs for safety, regression control, and release readiness.
• Agent learning ladder: prompt/tool tuning → SFT/PEFT → DPO/GRPO → RLHF/RLAIF → RFT.
• Interoperability & standards: MCP, agent-to-agent messaging, and emerging commerce protocols (ACP, AP2).
• Context engineering as a first-class design discipline (memory, retention boundaries, policies).
• Expanded coverage: offline RL, constrained RL, conformal prediction, GNNs, Mamba/SSM.
• Teaching assets: case packets, notation guide, glossary, and companion resources.

Table of Contents

• Start Here
• The Book, Chapter by Chapter
• What's New in the Third Edition
• Companion Code Highlights
• Directory Structure
• Setup Instructions
• Usage
• Development Best Practices
• Contribution Guidelines
• Documentation

Companion Code Highlights

• Retail Agent Operating Model (RAOM): Minimal RAOM implementation and examples (agents/raom_minimal.py).
• Capstone Workflow: End-to-end orchestration scaffolding with schemas, policies, tools, and tracing (capstone/).
• Agent Architectures: BDI, OODA, Q-learning, Bayesian, causal, and LLM-based agents (agents/).
• Coordination Protocols: Contract Net, auctions, and inventory sharing (agents/protocols/).
• Interoperability & Standards: MCP tooling contracts and commerce protocols (ACP/AP2) via demos and manifests (demos/).
• Evaluation & Red Teaming: Scenario packs and scoring rubrics (evals/, redteam/).
• Retail Data Models: Pydantic models for core retail concepts (models/).
• Utilities & Observability: Monitoring, event bus, planning, CRDTs, and NLP helpers (utils/).
• Notebooks & Demos: Marimo notebooks and runnable demos aligned to the book (notebooks/, demos/).
• Testing & Tooling: Pytest suite, Ruff, MyPy, and Makefile automation (tests/, Makefile).

Directory Structure

agentic-retail-foundations/
├── agents/               # Core agent logic, protocols, and specific agent types
│   ├── coordinators/     # Coordinator agent implementations
│   ├── cross_functional/ # Agents spanning multiple business functions
│   ├── protocols/        # Coordination protocols (CNP, Auction, Inventory Sharing)
│   └── ...
├── assets/               # Diagrams and static assets (book cover, figures)
├── capstone/             # End-to-end capstone workflow scaffolding
├── config/               # Configuration helpers
├── connectors/           # Interfaces to external systems (mocked connectors)
├── demos/                # Standalone demo scripts and protocol examples
├── docs/                 # MkDocs documentation source files
├── environments/         # Simulation environments (e.g., MDP for RL)
├── evals/                # Evaluation scenarios and scoring rubrics
├── models/               # Pydantic data models for retail concepts
├── notebooks/            # Marimo notebooks for exploration and visualization
├── redteam/              # Red-team scenarios for safety testing
├── tests/                # Unit and integration tests (pytest)
├── utils/                # Utilities (monitoring, planning, NLP, event bus, etc.)
├── .env.example          # Example environment variables template
├── .gitignore
├── .pre-commit-config.yaml
├── LICENSE
├── Makefile
├── mkdocs.yml
├── pyproject.toml
└── README.md

Setup Instructions

1. Prerequisites:

   • Git
   • Python 3.13 (the current dependency stack excludes 3.14)
   • uv (recommended for fast environment/package management)

2. Clone the repository:

   git clone https://github.com/gradient-divergence/agentic-retail-foundations.git
   cd agentic-retail-foundations
   

3. Install uv (if not already installed):
   Follow the official instructions: https://github.com/astral-sh/uv

4. Create Virtual Environment & Install Dependencies:

   uv sync --frozen
   # Complete test environment:
   uv sync --frozen --all-extras
   

5. Activate the Virtual Environment:

   source .venv/bin/activate
   

   Run commands with uv run --frozen to use the locked environment without activation.

6. Set up Environment Variables:

   • Copy the example environment file:

     cp .env.example .env
     

   • Edit .env and add your necessary API keys or configuration secrets (e.g., OPENAI_API_KEY).
   • Important: .env is listed in .gitignore and should never be committed.

7. Optional: OpenAI Agents SDK demos

   • The SDK dependencies are included in the frozen installation above.
   • SDK-specific demos (for example, demos/*_agents_sdk_demo.py) import the SDK via
     demos/openai_agents_sdk_import.py to avoid collisions with this repo's local
     agents/ package.

8. Optional: Protocol SDKs and reference implementations

   • Install protocol SDK dependencies:

     uv sync --frozen --extra agent_protocols
     

   • ACP is treated as a spec-only protocol reference (no SDK dependency).
   • Other optional stacks have named extras: streaming (Redis/Kafka), spark,
     gnn, monitoring (Prometheus), cloud (Postgres/Supabase), auth, and explainability (SHAP).
     Install one with uv sync --frozen --extra <name>; use uv sync --frozen --all-extras for the complete test environment.

9. Install Pre-commit Hooks (Recommended):

   make precommit
   # or: pre-commit install
   

Usage

Common development tasks are streamlined using the Makefile. Ensure your virtual environment is active (source .venv/bin/activate or make shell) when running Python scripts or tools like marimo directly.

• Run Marimo Notebooks:

  marimo edit notebooks/<notebook_name>.py
  # e.g., marimo edit notebooks/multi-agent-systems-in-retail.py
  

  Use marimo run ... for a read-only view.

• Run Demo Scripts:
  Run from the companion repository root:

  python -m demos.<demo_name>
  # e.g., python -m demos.task_allocation_cnp_demo
  

  Chapter 8's complete approval_request in demos/book_pricing_contracts.json
  proposes ending SKU-123's discount from Friday 16 October 2026 at 00:00 UTC
  until Monday 19 October at 00:00 UTC (exclusive), covering the promotion's
  remaining Friday-to-Sunday window. Its unit-margin check is gross margin:
  (price - unit_cost_usd) / price, about 45.45% at the proposed $22 price
  against $12 merchandise cost, above the 40% floor. Contribution per unit
  also deducts $4 in other variable selling costs: $20 - $12 - $4 = $4
  currently, or $22 - $12 - $4 = $6 if approved. These per-unit contributions
  exclude the transfer's $20 transport/handling cost and the donor's $8
  expected contribution loss, deducted separately in the decision record.

• Run Linters / Formatters / Type Checks:

  make lint          # Run Ruff linter
  make format        # Run Ruff formatter
  make format-check  # Check formatting without making changes (for CI)
  make type-check    # Run MyPy static type checker
  

• Run Tests:

  make test          # Run offline pytest tests with the existing .venv
  make test PYTHON=/path/to/python  # Use an existing interpreter; installs nothing
  make check         # Run Ruff on packages/tests, then offline tests
  make coverage      # Run tests and generate coverage report
  make ci            # Run format-check, type-check, tests, coverage, docs build
  

• Build / Serve Documentation:

  make docs-build    # Build MkDocs site (outputs to site/)
  make docs-serve    # Serve docs locally with live reload (http://127.0.0.1:8000)
  

• Manage Environment:

  make shell         # Start a new shell with venv activated
  make clean         # Remove cache files (__pycache__), build artifacts
  make clean-venv    # Remove the .venv directory entirely
  make venv          # Recreate the virtual environment (if deleted)
  make install       # Sync dependencies into the existing venv
  

• List All Commands:

  make help
  

Development Best Practices

• Modularity: Keep agent logic, data models, utilities, and connectors in their respective directories.
• Configuration: Use environment variables (.env file loaded via python-dotenv) for secrets and environment-specific settings.
• Typing: Use Python type hints extensively. Run make type-check (mypy) regularly.
• Linting & Formatting: Adhere to styles enforced by ruff. Run make format and make lint frequently.
• Testing: Write unit tests (pytest) for individual functions/classes and integration tests for components working together.
  make test and make check use installed tools and never create an environment or install packages.
  Full-suite tests require the locked extras (uv sync --all-extras); provider calls use fake clients.
  Coroutine tests with synchronous fixtures can run offline using asyncio.run when pytest-asyncio is absent.
  Coverage is opt-in (make coverage, requires pytest-cov); normal tests use the installed runtime dependencies.
• Documentation: Maintain docs in docs/ and keep this README in sync with the book and code.

Contribution Guidelines

Please refer to CONTRIBUTING.md for details on how to contribute to this project.

Documentation

Build and browse the MkDocs documentation locally:

make docs-serve    # http://127.0.0.1:8000

Repository: https://github.com/gradient-divergence/agentic-retail-foundations