agentic-retail-foundations

# 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. <table> <tr> <td width="60%"> <a href="https://www.amazon.com/dp/1069422649"><strong>Foundations of Agentic AI for Retail: Designing, Building, and Operating Retail AI Agents, from First Principles to Production</strong></a>, Third Edition (October 2026), by Fatih Nayebi. <br><br> <em>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.</em> <br><br> In paperback and hardcover, in full color. The Kindle edition will follow.<br> <strong>Buy on Amazon:</strong> <a href="https://www.amazon.com/dp/1069422649">US</a> | <a href="https://www.amazon.ca/dp/1069422649">CA</a> | <a href="https://www.amazon.co.uk/dp/1069422649">UK</a> | <a href="https://www.amazon.de/dp/1069422649">DE</a> | <a href="https://www.amazon.fr/dp/1069422649">FR</a> | <a href="https://www.amazon.it/dp/1069422649">IT</a> | <a href="https://www.amazon.es/dp/1069422649">ES</a> | <a href="https://www.amazon.co.jp/dp/1069422649">JP</a> <br><br> _{Earlier editions: <a href="https://www.amazon.com/dp/1069422622">second (2026)</a> | <a href="https://www.amazon.com/dp/1069422606">first (2025)</a>} </td> <td width="40%" align="center" valign="center"> <a href="https://www.amazon.com/dp/1069422649"> <img src="assets/book-cover-3rd-edition.jpg" alt="Book cover: Foundations of Agentic AI for Retail, Third Edition" width="300"/> </a> </td> </tr> </table> ## Start Here ```sh 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. | Ch. | Chapter | Main files | |---|---|---| | 1 | Introduction: The Age of Agency | `demos/intro_inventory_book_demo.py` | | 2 | Agent Architectures and Operating Models | `agents/raom_minimal.py`, `agents/bdi.py`, `agents/ooda.py`, `demos/bdi_inventory_demo_short.py` | | 3 | Decision Frameworks I: Probabilistic Reasoning and Optimization | `demos/bayesian_reco_book_demo.py`, `demos/bayes_uplift_demo.py` | | 4 | Decision Frameworks II: Sequential Decision-Making | `demos/mdp_dynamic_pricing_book_demo.py`, `demos/capstone_mdp_simulator_demo.py` | | 5 | Decision Frameworks III: Learning and Planning | `demos/agent_optimization_ladder_demo.py`, `demos/store_fulfillment_book_demo.py` | | 6 | Core Technologies Enabling Agentic Retail | `demos/structured_output_schema_demo.py`, `demos/tool_calling_rag_demo.py`, `demos/shelf_monitoring_book_demo.py` | | 7 | Physical Perception and Sensor Intelligence | `agents/sensor.py`, `demos/knowledge_graph_book_demo.py`, `demos/promotion_causal_book_demo.py` | | 8 | Multi-Agent Coordination and Interoperability | `demos/agent_communication_demo.py`, `demos/task_allocation_cnp_demo.py`, `demos/procurement_auction_demo_short.py`, `demos/inventory_sharing_demo_short.py` | | 9 | End-to-End Agent Integration | `demos/order_orchestration_demo.py`, `demos/inventory_event_api_demo.py`, `demos/api_gateway_book_demo.py`, `demos/inventory_crdt_demo.py` | | 10 | Building Production Agents | `demos/agent_session_state_demo.py`, `demos/inventory_agent_unit_test_demo.py`, `demos/monitoring_dashboard_api_demo.py` | | 11 | Operating Agents (AgentOps) | `demos/agent_eval_hook_demo.py`, `demos/agentops_latency_middleware.py`, `demos/preference_pair_builder_demo.py` | | 12 | Governance and Responsible Autonomy | `demos/hitl_approval_api_demo.py`, `demos/pricing_explainability_shap_demo.py` | | 13 | Playbooks and Case Studies | `demos/inventory_agents_sdk_demo.py`, `demos/dynamic_pricing_agents_sdk_demo.py`, `demos/virtual_shopping_responses_demo.py` | | 14 | Strategy, Maturity, and Futures | `demos/capstone_gate_review_demo.py` | ## 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. <details> <summary><strong>What the second edition added</strong></summary> - **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. </details> ## Table of Contents - [Start Here](#start-here) - [The Book, Chapter by Chapter](#the-book-chapter-by-chapter) - [What's New in the Third Edition](#whats-new-in-the-third-edition) - [Companion Code Highlights](#companion-code-highlights) - [Directory Structure](#directory-structure) - [Setup Instructions](#setup-instructions) - [Usage](#usage) - [Development Best Practices](#development-best-practices) - [Contribution Guidelines](#contribution-guidelines) - [Documentation](#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:** ```sh 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:** ```sh uv sync --frozen # Complete test environment: uv sync --frozen --all-extras ``` 5. **Activate the Virtual Environment:** ```sh 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: ```sh 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: ```sh 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):** ```sh 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:** ```sh 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: ```sh 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:** ```sh 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:** ```sh 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:** ```sh 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:** ```sh 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:** ```sh 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`](CONTRIBUTING.md) for details on how to contribute to this project. ## Documentation Build and browse the MkDocs documentation locally: ```sh make docs-serve # http://127.0.0.1:8000 ``` Repository: https://github.com/gradient-divergence/agentic-retail-foundations