Foundations of Agentic AI for Retail (Second Edition Companion Code)

A modular, extensible Python framework and companion codebase for the second edition of Foundations of Agentic AI for Retail. It includes agent architectures, coordination protocols, production guardrails, evaluation packs, and end-to-end demos that map to the book's operating model and capstone workflow.

Featured Book: Foundations of Agentic AI for Retail — Second Edition

Foundations of Agentic AI for Retail: Operating Models, Decision Frameworks, and Retail-Grade Architectures (Second Edition) by Dr. Fatih Nayebi. Retail is the most demanding proving ground for agentic AI: thin margins, live inventory, real customers, and constant change. This edition focuses on production-ready operating models, evaluation, and governance. Purchase on Amazon: US | CA | JP | UK | DE | FR | IN | IT | ES

What's New in the Second Edition

• 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 SOTA coverage: offline RL, constrained RL, conformal prediction, GNNs, Mamba/SSM.
• Teaching assets: case packets, notation guide, glossary, and companion resources.

Table of Contents

• What's New in the Second Edition
• Companion Code Highlights
• Directory Structure
• Setup Instructions
• Usage
• Development Best Practices
• Contribution Guidelines
• Documentation Website
• GitHub Repository

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.10+
   • 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:

   make install
   # or: make venv

5. Activate the Virtual Environment:

   source .venv/bin/activate

   Alternatively, use make shell to start a sub-shell with the environment activated.

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

   • Install the SDK dependencies:

     pip install --upgrade openai openai-agents python-dotenv

   • 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 pip install -e ".[agent_protocols]"

   • ACP is treated as a spec-only protocol reference (no SDK dependency).

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:

  python demos/<demo_name>.py
  # e.g., python demos/task_allocation_cnp_demo.py

• 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 pytest test suite
  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.
• 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 Website

The MkDocs site is published at: https://gradient-divergence.github.io/agentic-retail-foundations

You can also build and serve the documentation locally using make docs-serve.

GitHub Repository

• Main repository: https://github.com/gradient-divergence/agentic-retail-foundations