Multi-Agent Intelligent Warehouse (MAIW)

An NVIDIA AI Blueprint for governed, agentic warehouse operations.

Powered by NVIDIA Nemotron, MCP, SOP-driven agents, and pluggable agent runtimes.

Observe → Reason → Recommend → Govern → Approve → Execute → Observe Outcome

!MAIW Runtime Pipeline

MAIW v2 is a closed-loop decision architecture in which sandboxed agents reason over a governed warehouse state, generate typed operational proposals, and pass those proposals through deterministic decision, approval, commit-validation, and execution layers before any warehouse system is changed. Execution outcomes are then measured, traced, and fed back into the warehouse state, creating an auditable learning loop while preserving a strict separation between AI reasoning and operational authority.

See docs/architecture/ARCHITECTURE.md for the full architecture document.

Warehouse World

MAIW ships with a deterministic synthetic warehouse environment used for development, demo, and evaluation. The canonical generation path is:

WarehouseWorldConfig
    ↓
WarehouseWorldGenerator  (deterministic, seed-based)
    ↓
Canonical Operational Graph
    ↓
WarehouseDataPack  (immutable, on-disk, verifiable)
    ↓
ScenarioOverlay  (disruption events)
    ↓
ScenarioWorld  (base + overlay, immutable view)
    ↓
DemoWarehouseWorld  (mutable runtime execution world)
    ↓
Simulation Providers
    ↓
WarehouseStateProvider → WarehouseState → Agents

Three-State Distinction

| Layer | Description | |-------|-------------| | BASE (DataPack) | Immutable, on-disk, checksummed artifact. Never mutated by a demo run. Identified by dataset_id + warehouse_id + seed. | | SCENARIO (ScenarioWorld) | Immutable view: DataPack base graph + deterministic event overlay. Validates entity references at construction. Does not modify the DataPack. | | LIVE (DemoWarehouseWorld) | Mutable runtime execution world. Derived from DataPack + ScenarioOverlay. Reset reconstructs from immutable sources — not from a snapshot. |

DataPack           = what the warehouse is
ScenarioWorld      = what happened to it
DemoWarehouseWorld = what MAIW is currently operating on

OperationalContextSnapshot

Each Copilot turn that reaches a model produces one OperationalContextSnapshot. It is captured before the model call — not reconstructed afterward. It is:

• Linked to the turn via turn_id, trace_id, and context_snapshot_id
• Linked to the DataPack via datapack_checksum (the same immutable semantic_checksum)
• Immutable after capture — LIVE mutations do not change historical snapshots
• Inspectable in the WORLD / CONTEXT tab or via GET /api/v1/world/context/by-turn/{turn_id}

See docs/architecture/WAREHOUSE_WORLD.md and docs/developer/WAREHOUSE_WORLD_MODEL.md.

Agents, SOPs, and Skills

What an Agent Is

An agent is a bounded operational role — not a general-purpose autonomous entity:

| Dimension | Description | |-----------|-------------| | AgentDefinition | Declares identity: agent_id, version, domain, objective, allowed capabilities, TerminationPolicy. MAIW-owned. | | SOPDefinition | A versioned, machine-readable Standard Operating Procedure: steps, allowed capabilities, allowed subagents, stop conditions, escalation rules, runtime profile. MAIW-owned. | | AgentTaskState | Tracks one execution of one SOP: task_id, current step, completed steps, context snapshot, delegation results, governance state, stop reason. |

Agents execute SOPs. SOPs do not own agents. An SOP defines the policy envelope; the agent runtime decides how to navigate within it.

Canonical Agents

| Agent | Domain | Package | |-------|--------|---------| | OperationsCoordinationAgent | Cross-domain coordination | packages/maiw-agents/maiw_agents/operations/ | | LaborAgent | Labor capacity and allocation | packages/maiw-agents/maiw_agents/labor/ | | WaveAgent | Wave prioritization and risk | packages/maiw-agents/maiw_agents/wave/ | | EquipmentAgent | Equipment status and assignment | packages/maiw-agents/maiw_agents/equipment/ | | SafetyAgent | Safety incident and compliance | packages/maiw-agents/maiw_agents/safety/ |

Agent vs. Skill

| | Agent | Skill | |-|-------|-------| | Has a goal? | Yes — SOP objective | No — executes one bounded capability | | Has state? | Yes — AgentTaskState | No — stateless | | Has a lifecycle? | Yes — SOP steps, stop conditions | No | | Can delegate? | Yes — to subagents (SOPs govern) | No | | Governance? | Yes — must emit RecommendedAction | Capability class constrains use |

Skill Capability Classes

| Class | Description | Direct Write? | |-------|-------------|---------------| | READ | Reads operational state via MCP | No | | ANALYTICAL | Computes metrics and assessments | No | | PROPOSAL | Builds typed ActionProposal | No | | WRITE | Invokes MCP write capability | Structurally blocked from agent runtime | | EMERGENCY_WRITE | Bypasses standard policy gating | Structurally blocked from agent runtime |

WRITE and EMERGENCY_WRITE are structurally blocked from the agent runtime. They can only be invoked by ActionExecutor after a full governance pass.

SOP Engine V2

A SOP is not a system prompt. It is a versioned, reviewable artifact that the engine executes one step at a time, and the engine — not the model, not the runtime — decides what happens next.

The rule the whole design exists to enforce:

A step advances because its declared completion criterion was proven — not because a runtime or a model said it was done.

Explicit executable SOPs. Procedures live in agents/sops/**.yaml as typed, versioned steps. No expression language, no eval, no dynamic import. A SOP names a registered predicate; it cannot supply one.

Step-by-step runtime control. The runtime is handed exactly one step and returns one claim about it. It is never asked which step comes next, never told how many iterations remain, and never offered a choice of successor.

Validator-owned completion authority. A runtime reporting status=COMPLETED is a claim. The engine runs the step's declared validator — SCHEMA, STATE_PREDICATE, CAPABILITY_RESULT, or LEGACY_SUCCESS — and the validator's verdict is what advances the procedure.

Bounded loops and retries. A loop is bounded twice over, by iteration count and optionally by wall clock, and both bounds are held by the engine. A model returning COMPLETED does not exit the loop; a model returning FAILED does not extend it. Loops are structurally forbidden on governed-write steps, because re-entering a write can duplicate a physical side effect.

Runtime neutrality. The engine knows nothing about waves, equipment, inventory or labour — asserted by a test that inspects its import graph. The same machinery serves any domain that supplies a step executor and registered predicates.

External governance. Governance never runs inside the SOP Engine. A write-related step pauses at WAITING_FOR_GOVERNANCE and the caller resumes it only after governance has completed.

Authoritative outcome verification. A write-related step is not complete because governance returned APPROVED or because a call returned 2xx. It completes when a re-read of authoritative state proves the change landed. An indeterminate outcome escalates as EXECUTION_INDETERMINATE — it is never resolved by repeating the write.

Persistence and recovery. Supplying a ProcedureStateStore makes a procedure recoverable. The engine checkpoints every lifecycle transition, so a restart restores exactly which SOP version was running, which step and attempt were active, what evidence had been proven, and whether a write may already have occurred. The SOP version is pinned: a procedure never auto-upgrades, because half its steps completing under v1.0 and the rest under v1.1 is a procedure that never existed. Terminal states are immutable, so a restart cannot re-open a finished procedure.

Evidence enforcement. Steps declare evidence_requirements, and the critical ones are enforced as completion preconditions — checked before the completion validator, so a step that cannot show its work reports EVIDENCE_MISSING rather than a misleading validation failure. Only a structured EvidenceRef with a matching type, source and fields counts. Model prose cannot satisfy an evidence requirement: a confident sentence is not an observation.

Runtime capability boundary (deny-by-default). Each task is issued an immutable RuntimeCapabilityPolicy built only from the AgentDefinition, the SOP and the capability registry — never from model output, a prompt, or anything a sandbox declares about itself. A capability absent from the allow-list is denied, including one that did not exist when the policy was issued. WRITE and EMERGENCY_WRITE are denied unconditionally and cannot be argued back in. Enforcement sits at the invocation seam in both runtimes, via one shared function, so there is no second implementation to drift.

Proof SOPs

| SOP | Property it proves | |-----|--------------------| | wave_risk_resolution.v2 | Multi-domain coordination ending in a governed recommendation, with post-execution state verification | | equipment_failure_recovery.v1 | Execution succeeding is not recovery succeeding — the write landing, the intended transition, and actual recovery are three separate proofs | | picking_inventory_exception.v1 | A bounded reassessment loop, plus facility-strategy variation: one procedure behaves differently in zone- and discrete-picking facilities without a separate code path |

Authority model

Context → SOP Engine / AgentRuntime → RecommendedAction
→ Governance → Approval → ActionExecutor → MCP → Operational Systems

Everything left of Governance is advisory. The SOP Engine imports no ActionExecutor, no DecisionEngine, no MCP write client and no warehouse credentials — enforced by AST inspection in CI, not by convention. Adding persistence did not move any authority into the engine: a restored procedure that was waiting on governance is still waiting on governance.

Sandbox status: procedure state is recoverable, evidence requirements are enforced, and runtime capabilities are explicitly deny-by-default. See Sandboxed Agent Runtime below.

See docs/architecture/SOP_ENGINE_V2_DESIGN.md.

Runtime Architecture

MAIW provides two runtimes behind the AgentRuntime protocol:

MAIWDeterministicRuntime (strict mode)

• Executes SOP steps in exact declared order
• No LLM nondeterminism — same inputs always produce the same output
• Used for CI/CD pipelines, safety-sensitive procedural checks, and degraded-mode fallback
• No external dependencies beyond MAIW packages

DeepAgentsRuntime (adaptive mode)

• Adaptive reasoning within the SOP policy envelope
• Uses ReAct-style tool/subagent scheduling via deepagents>=0.7.15,<0.8 (optional extra: pip install -e 'packages/maiw-agents[deep-agents]')
• MAIW supplies: system prompt, tools (READ/ANALYTICAL only), subagent specs, SOP envelope
• Deep Agents provides: the runtime loop, tool selection, intermediate context management
• All model calls route through MAIWModelGatewayChat — never directly to a provider
• Does NOT own governance, SOPs, task state, or execution authority

runtime_profile: strict    # → MAIWDeterministicRuntime
runtime_profile: adaptive  # → DeepAgentsRuntime

The dual-runtime architecture is intentional design. It provides a clean separation between deterministic compliance and adaptive reasoning. MAIWDeterministicRuntime is the reference and strict-mode fallback; DeepAgentsRuntime is the primary adaptive runtime for complex resolution SOPs.

See docs/architecture/AGENT_RUNTIME.md.

Sandboxed Agent Runtime

OpenShell enforces the security boundary; NemoClaw packages and operates it; MAIW continues to define what the agent is allowed to do and remains the sole authority over warehouse actions.

Either runtime can be wrapped in a sandbox boundary. This is containment, not migration — nothing in packages/ changed, and no MAIW semantics moved onto NemoClaw.

┌─ OpenShell sandbox ──────────────────────┐
│  SOP Engine + AgentRuntime               │
│  READ / ANALYTICAL / PROPOSAL only       │
│  network: deny-by-default                │
│  credentials: none                       │
└──────────────┬───────────────────────────┘
               ↓
       RecommendedAction
══════════ MAIW AUTHORITY BOUNDARY ══════════
               ↓
    Governance → ActionExecutor → MCP WRITE

runtime = SandboxedAgentRuntime(
    inner=MAIWDeterministicRuntime(...),   # unchanged, and unaware
    config=SandboxConfig.from_env(),
    provisioner=OpenShellSandboxProvisioner(),
)

RuntimeCapabilityPolicy is rendered into a sandbox policy that is deterministic (same policy → byte-identical YAML), monotonic (rendered ⊆ MAIW policy, checked on every render) and credential-free. WRITE and EMERGENCY_WRITE have no route in — not via the class list, a capability id, a network endpoint, or an injected credential.

Three sandbox modes, and the middle one is the point:

| Mode | Behaviour when the sandbox is unavailable | |---|---| | disabled | normal operation, no sandbox expected | | required | fail the task. No fallback — not as a retry, not behind a flag | | preferred | warn and continue; the MAIW capability policy still applies |

A sandbox authorises nothing. Every capability check that runs unsandboxed still runs sandboxed, through the same authorize_step. The sandbox is a second wall behind the first. If integrations/nemoclaw/ were deleted, capability enforcement, governance and procedure persistence would be unchanged.

Qualification status. NemoClaw v0.0.124 and OpenShell v0.0.116 are installed on epg-tme-smc-h100-02 and the package-level security boundary (capability policy, sandbox isolation, approved Nemotron 3/3.5 policy in PolicyFilter, MAIWHTTPModelGatewayClient) was qualified for v2.0.0 — see docs/audits/MAIW_NEMOCLAW_SECURITY_QUALIFICATION.md and artifacts/nemoclaw/. The independent post-release audit of v2.0.0 (PR #142) then found that the shipped application composition did not match those claims (inference endpoint not mounted on maiw_api.app:app, an ungoverned legacy chat write path, durable stores not wired, readiness that failed open, a document path outside ModelGateway). v2.0.1 (released) remediated those gaps on the canonical app — see docs/audits/MAIW_V2.0.1_REMEDIATION_AUDIT.md. v2.1.0 is the current release — see What ships and RELEASE_NOTES_v2.1.0.md.

See docs/architecture/NEMOCLAW_OPENSHELL_INTEGRATION.md.

What ships (v2.1.0)

The only release composition root is apps/api/maiw_api/app.py (uvicorn maiw_api.app:app, port 8001). src/api/app.py is a legacy development server and is never part of a deployment or qualification.

| Surface | Behaviour in the shipped app | |---|---| | POST /api/v1/inference | Mounted on the API port. Internal token required (fail-closed 401/503); forbidden routing fields and unknown fields → 422; every call goes through the canonical ModelGateway → PolicyFilter (Nemotron 3 / 3.5 only). | | Operational writes | Only governed routes mutate: agent proposal → DecisionEngine → ActionExecutor (/equipment/{assign,release,maintenance}, /copilot/turn, /demo/{analyze,approve,reject,reconcile}). | | Legacy /api/v1/chat, /api/v1/reasoning | Not mounted. Use POST /api/v1/copilot/turn. | | Other legacy routers (inventory, WMS, IoT, ERP, scanning, attendance, migrations, forecasting, training) and operations/safety | Read-only (GET) in the shipped app. | | Procedure state | JsonFileProcedureStateStore + JsonFileGovernanceInbox under MAIW_PERSISTENCE_ROOT (default /var/lib/maiw), built once by the composition root; GET /api/v1/procedures is a read-only view. MAIW_PERSISTENCE_MODE=memory is an explicit development/test opt-in. | | GET /api/v1/ready | 503 NOT_READY with failed_components when persistence, ModelGateway, the governed write path, MCP domains or (outside demo mode) the database are unavailable. | | Document pipeline | Every model call goes through ModelGateway with an explicit modality. Vision steps need an approved multimodal Nemotron model; with none enabled, documents fail with a typed MODEL_UNAVAILABLE — never mock data, never a synthetic APPROVE. |

ModelGateway

All model calls — from both runtimes — pass through a single ModelGateway chain:

AgentRuntime
    ↓
ModelGateway
    ↓
PolicyFilter  (hard eligibility gate: risk × reasoning × deployment)
    ↓
ModelRouter   (deterministic rule-based model selection)
    ↓
Deployment Resolver  (NVIDIA_HOSTED / LOCAL_NIM / OPENAI_COMPATIBLE / ENTERPRISE)
    ↓
NVIDIA NIM / Hosted / Local

Agents express what level of reasoning a decision requires (via ReasoningLevel). ModelGateway selects the physical model. Agents never reference model IDs directly.

Nemotron model roles: lightning (fast; default for LOW and MEDIUM reasoning), ultra (default for HIGH reasoning and CRITICAL risk), super and nano (hosted endpoints retired; self-hosted NIM only, disabled by default).

MAIW v2 Supported Models

MAIW v2 permits only Nemotron 3 and Nemotron 3.5 for production and qualification. This is a hard policy enforced by PolicyFilter at routing time, not a configuration default.

| Role | Model ID | Generation | Status | |------|----------|------------|--------| | lightning | nvidia/nemotron-3.5-lightning-30b-a3b | nemotron-3.5 | Approved, enabled — LOW and MEDIUM reasoning | | ultra | nvidia/nemotron-3-ultra-550b-a55b | nemotron-3 | Approved, enabled — HIGH reasoning and CRITICAL risk | | super | nvidia/nemotron-3-super-120b-a12b | nemotron-3 | Approved, disabled (hosted endpoint retired 2026-10-19; self-hosted NIM only) | | nano | nvidia/nemotron-3-nano-30b-a3b | nemotron-3 | Approved, disabled (hosted endpoint retired 2026-09-01; self-hosted NIM only) | | nano-omni | — | nemotron-3 | No approved deployment; vision requests fail closed |

MAIW v2 supports Nemotron 3 and Nemotron 3.5 model families. Any model whose generation is not in {"nemotron-3", "nemotron-3.5"} is rejected by PolicyFilter before any provider call. See packages/maiw-models/maiw_models/routing.py (PolicyFilter.APPROVED_MODEL_GENERATIONS).

See docs/architecture/MODEL_GATEWAY.md.

Governance and Authority Boundary

Agent (either runtime)
    → RecommendedAction
    → WAITING_FOR_GOVERNANCE
──────── MAIW AUTHORITY BOUNDARY ────────
ActionProposal  (typed, immutable)
    ↓
DecisionEngine  (synchronous, no I/O, deterministic)
    → APPROVED / REJECTED / REQUIRES_HUMAN_APPROVAL / REQUIRES_FRESH_STATE
    ↓
Human Approval  (where required — explicit, expirable, single-use)
    ↓
ActionExecutor  (6-guard pattern before any MCP write)
    ↓
MCP Interoperability Layer
    ↓
Warehouse Systems

RecommendedAction lives ABOVE the authority boundary — it is agent output, semantic intent, not a write command.

ActionProposal lives BELOW the authority boundary — it is a governed operational artifact with explicit target, risk, and trace identity.

The invariant is non-negotiable:

The LLM never touches a write path directly.

AI recommends and proposes. The DecisionEngine governs. Human authority approves where required. ActionExecutor executes.

DecisionEngine is synchronous, performs no I/O, and cannot be overridden by a model-generated argument. ActionExecutor checks six guards in order: (1) decision outcome is APPROVED, (2) decision binds to the exact proposal ID, (3) action name is in the static allowlist, (4) the decision is not stale, (5) domain-specific additional guards (e.g. state-drift check), (6) request deadline not expired immediately before write.

See docs/architecture/GOVERNANCE.md and docs/architecture/DECISION_ENGINE.md.

MCP Interoperability Layer

MAIW uses the official MCP Python SDK (mcp 2.0.0, protocol 2026-07-28).

Skill
    ↓
MAIWMCPClient.invoke("warehouse.inventory.get", payload)
    ↓
CapabilityRegistry.resolve()  →  server URL
    ↓
mcp.client.Client(server_url)     ← official MCP v2 Client
    ↓
client.call_tool("warehouse.inventory.get", payload)
    ↓
[MCP 2026-07-28 over Streamable HTTP]
    ↓
MCPServer (mcp.server.MCPServer)
    ↓
Warehouse Backend

MCP is the interoperability layer, not the authority layer. MCP capabilities are not exposed to the LLM's tool registry. The LLM produces a RecommendedAction; ActionExecutor translates a governed ActionProposal into an MCP call.

MAIWMCPClient wraps mcp.client.Client. Servers use mcp.server.MCPServer. Transport: Streamable HTTP (stateless, no session affinity required). Test transport: in-memory via CapabilityRegistry.

See docs/architecture/MCP.md.

Reliability and Closed-Loop Outcome Observation

MAIW treats distributed-systems uncertainty as a first-class concern.

When a write may have succeeded but its acknowledgement is lost, MAIW does not blindly retry:

UNKNOWN → suppress automatic retry → reread authoritative state → reconcile
    ↓
CONFIRMED_EXECUTED | CONFIRMED_NOT_EXECUTED | INDETERMINATE

The reliability infrastructure includes:

| Concern | Mechanism | |---------|-----------| | Ambiguous writes | AmbiguousWriteError → UNKNOWN outcome — never auto-retried | | Execution identity | execution_id generated before write, propagated through MCP | | Idempotency | ExecutionRegistry — same idempotency key cannot produce multiple mutations | | Reconciliation | ReconciliationService with capability-specific postcondition strategies | | Request deadlines | Hierarchy at API boundary — analyze / execution / reconciliation / startup budgets | | Circuit breakers | DomainCircuitRegistry — per-domain isolation; NIM circuit independent of MCP circuits | | Fault injection | Deterministic fault framework (F01–F16 profiles) — test/demo only, never in production |

Every operational interaction is traceable through:

Evidence → Agent Interpretation → Skills → RecommendedAction → ActionProposal
    → Decision → Approval → Execution → Outcome

MAIW implements Closed-Loop Outcome Observation. The system observes whether the intended operational outcome occurred: Did backlog fall? Did wave risk improve? Did throughput recover? Outcome observation closes the operational loop — it does not imply autonomous learning or self-modification.

MAIW Copilot

MAIW Copilot is the conversational interaction layer over the governed lifecycle. Operators ask natural-language questions, receive evidence-grounded analysis with ranked recommendations, and initiate governed warehouse actions — all through a single endpoint (POST /api/v1/copilot/turn).

Four Intents, One Endpoint

| Intent | What it does | |--------|-------------| | ASK | Graph-grounded answer about current warehouse state. Returns evidence facts and Operational Graph neighborhood context. No proposal, no execution. | | ANALYZE | Deterministic severity assessment + ranked RecommendedAction list. Severity is computed before the LLM call; recommendations route through the standard governance pipeline when acted upon. | | ACT | Converts the selected recommendation into a governed ActionProposal, evaluates it through DecisionEngine, and either executes (if approved autonomously) or queues for human approval. | | OBSERVE_OUTCOME | Post-execution outcome observation. Compares pre- and post-execution state to determine whether the intended operational objective was achieved. |

Copilot never bypasses DecisionEngine, human approval, or ActionExecutor. The trust boundary is enforced architecturally: CopilotService cannot import ActionExecutor, ApprovalStore, or DecisionEngine — only GovernedActionOrchestrator crosses that boundary, and only after a full policy evaluation.

Model Gateway Evaluation Lab

The Model Gateway Evaluation Lab (at /models/lab) is a read-only developer tool for inspecting pre-computed model evaluation artifacts. It provides:

• Multi-model comparison across fixed evaluation benchmarks
• Deterministic graders (not LLM judges)
• Router assessment with routing provenance (requested_role, selected_role, fallback_from)
• Evidence for model selection decisions (insufficient evidence → retain current router)

See docs/developer/MODEL_GATEWAY_EVALUATION.md.

Architecture Ownership

| Layer | Owns | |-------|------| | MAIW | Warehouse semantics, SOPs, task state, permissions, governance, execution, outcome | | Deep Agents | Adaptive runtime loop, tool/subagent scheduling, working context | | ModelGateway | Model access, eligibility, routing, deployment | | MCP | Standardized interoperability | | WMS / WES / etc. | Operational systems of record |

What MAIW Is NOT

| What people might expect | What MAIW actually is | |--------------------------|----------------------| | A WMS replacement | An intelligence and governance layer above warehouse systems | | A WES replacement | An agent orchestration framework that integrates with execution systems | | A generic chatbot | A governed operational intelligence architecture with SOP-driven agents | | A generic agent framework | A warehouse-specific framework with typed contracts, SOPs, and execution governance | | Direct LLM-to-tool execution | Governed: LLM → RecommendedAction → DecisionEngine → ActionExecutor → MCP | | An MCP orchestration layer | MCP is the interoperability layer; MAIW is the governance and semantic layer above it | | A replacement for enterprise warehouse systems | A complement that adds reasoning, governance, and outcome observation to existing systems | | A service hardened for untrusted networks | A blueprint for a single trusted host (remote UI access via SSH tunnel): the MCP domain servers have no caller authentication, so every port binds 127.0.0.1 by default. See Supported Deployment Boundary |

Quickstart

Prerequisites

• Python 3.11+
• Node.js 20+
• NVIDIA API key (nvapi-...) from build.nvidia.com
• Git

Steps

# 1. Clone
git clone https://github.com/NVIDIA-AI-Blueprints/Multi-Agent-Intelligent-Warehouse.git
cd Multi-Agent-Intelligent-Warehouse
2. Install dependencies, then all MAIW packages (editable), in a fresh venv
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install -e packages/maiw-contracts -e packages/maiw-mcp -e packages/maiw-state \
    -e packages/maiw-models -e packages/maiw-skills -e packages/maiw-decision \
    -e packages/maiw-execution -e packages/maiw-agents -e packages/maiw-world \
    -e apps/api
3. Configure the model endpoint: a .env with only the provider key.
   Do not copy .env.example for Demo Mode: it configures the reference
   deployment (MAIW_DEPLOYMENT_PROFILE=reference, MAIW_SANDBOX_MODE=required),
   which overrides MAIW_DEMO_MODE and keeps /api/v1/ready at 503 without a
   database and an OpenShell sandbox.
echo 'NVIDIA_API_KEY=nvapi-...' > .env && chmod 600 .env
For a self-hosted NIM: also add MAIW_NIM_BASE_URL (and MAIW_NIM_API_KEY if
  needed); it must serve the approved model ID of each enabled role (see .env.example)
4. Warehouse World (DataPack): the canonical pack is committed at
   data/worlds/dc47-demo-v1, so this step is optional. To regenerate it:
   python -m maiw_world generate --overwrite
5. Start backend (development: in-memory procedure state, explicitly)
MAIW_DEMO_MODE=true MAIW_PERSISTENCE_MODE=memory uvicorn maiw_api.app:app --reload --port 8001
   Ready when GET /api/v1/ready on port 8001 returns "status": "READY", "profile": "demo"
6. Start frontend (in a second terminal; proxies /api to localhost:8001)
cd src/ui/web && npm install && npm start
Runs at http://localhost:3001 (bound to 127.0.0.1; see DEPLOYMENT.md for remote access)
7. Open WORLD tab → inspect DataPack, Operational Graph, LIVE state
8. Activate Wave 17 scenario → observe SCENARIO layer
9. Ask Copilot: "What is the current wave risk?" (ASK intent)
10. Ask Copilot: "What should I do about the labor shortage?" (ANALYZE intent)
11. Inspect OperationalContextSnapshot in WORLD → CONTEXT tab
12. Run SOP-driven agent: OperationsCoordinationAgent → wave_risk_resolution SOP
13. Review RecommendedAction — semantic intent above the authority boundary
14. Execute governed action: Copilot ACT or POST /api/v1/demo/approve
15. Observe LIVE outcome in WORLD → LIVE tab
16. Ask Copilot: "Did it work?" (OBSERVE_OUTCOME intent)
17. Open Model Gateway Lab at http://localhost:3001/models/lab

Demo Mode (MAIW_DEMO_MODE=true) does not require PostgreSQL, Redis, Milvus, or Kafka. Only NVIDIA_API_KEY is needed. For a durable local run set MAIW_PERSISTENCE_ROOT to a writable directory instead of MAIW_PERSISTENCE_MODE=memory; the reference deployment (scripts/start_reference_deployment.sh) is always file-backed.

Developer Notebook / Brev

The canonical developer journey is available as a Jupyter notebook:

notebooks/MAIW_v2_Getting_Started.ipynb

This notebook walks through the full 17-step journey — from environment validation through Warehouse World generation, scenario activation, Copilot interaction, SOP-driven agent execution, governance, outcome observation, and the Model Gateway Evaluation Lab.

Environment Configuration

Required

| Variable | Required for | Description | |----------|-------------|-------------| | NVIDIA_API_KEY | All modes | NVIDIA API key (nvapi-...), from build.nvidia.com | | POSTGRES_PASSWORD | Full-stack only | PostgreSQL password — not required for Demo Mode | | JWT_SECRET_KEY | Full-stack only | JWT signing secret (min 32 chars) — not required for Demo Mode |

Demo Mode (MAIW_DEMO_MODE=true) does not require PostgreSQL, Redis, Milvus, or Kafka.

Model Configuration

| Variable | Default | Description | |----------|---------|-------------| | LLM_NIM_URL | https://integrate.api.nvidia.com/v1 | NIM inference endpoint | | LLM_MODEL | nvidia/nemotron-3.5-lightning-30b-a3b | Default model ID for callers that bypass ModelGateway | | NEMOTRON_LIGHTNING_ENABLED | true | Lightning role (LOW and MEDIUM reasoning) | | NEMOTRON_ULTRA_ENABLED | true | Ultra role (HIGH reasoning, CRITICAL risk) | | NEMOTRON_SUPER_ENABLED | false | Super role; enable only for a self-hosted Super NIM (hosted endpoint retired) | | NEMOTRON_NANO_ENABLED | false | Nano role; enable only for a self-hosted Nano NIM (hosted endpoint retired) | | NEMOTRON__MODEL | approved ID per role | May only name that role's approved model ID; anything else fails closed |

Infrastructure (Full-stack only)

| Variable | Default | Description | |----------|---------|-------------| | PGHOST / PGPORT | localhost / 5435 | PostgreSQL for the API's SQL data path and /api/v1/ready | | DB_HOST / DB_PORT | localhost / 5435 | PostgreSQL for legacy services and migrations | | REDIS_HOST | localhost | Redis host | | MILVUS_HOST | localhost | Milvus vector DB host |

Architecture Invariants

These invariants are enforced by the test suite and must not be broken:

| Invariant | Enforcement | |-----------|------------| | LLM cannot call MCP write tools directly | No MCP write tool in any agent tool registry | | Proposals are built locally, never via MCP | ActionProposal factories have no MCP client | | DecisionEngine is synchronous, no I/O | evaluate() has no await, no client dependencies | | Only ActionExecutor.execute() reaches MCP writes | Single call-site per domain executor | | Action names are statically allowlisted | _ALLOWED_ACTIONS is a frozenset literal | | No canonical package imports from src.* | AST scanner in test_package_imports.py | | UNKNOWN outcome is never auto-retried | ExecutionRegistry.mark_unknown() blocks subsequent attempts | | Post-mutation timeout produces UNKNOWN, not FAILED | AmbiguousWriteError → distinct outcome path in BaseActionExecutor | | Same idempotency key cannot produce multiple mutations | ExecutionRegistry capability:key compound dedup | | execution_id generated before write, propagated through MCP | BaseActionExecutor.execute() generates UUID pre-write | | One circuit breaker per domain | DomainCircuitRegistry: equipment/labor/wave/inventory circuits are independent | | NIM circuit breaker independent of MCP domain circuits | ModelGateway has its own nim_circuit | | Fault injection lives only in test/demo infrastructure | Production packages contain zero fault_id checks or FaultProfile references |

Testing

MAIW uses a three-tier test structure. CORE CI requires no running services:

DATABASE_URL=postgresql://warehouse:ci_placeholder@localhost:5435/warehouse \
python -m pytest tests/unit/ tests/contract/ tests/mcp/ tests/api/ packages/maiw-agents/tests/ \
  --timeout=120 \
  --ignore=tests/unit/test_all_agents.py \
  --ignore=tests/unit/test_basic.py \
  --ignore=tests/unit/test_nvidia_llm.py \
  --ignore=tests/unit/test_caching_demo.py \
  --ignore=tests/unit/test_response_quality_demo.py \
  --ignore=tests/unit/test_mcp_integrated_planner_graph.py \
  --ignore=tests/unit/test_chunking_demo.py \
  --ignore=tests/unit/test_db_connection.py \
  --ignore=tests/unit/test_enhanced_retrieval.py \
  --ignore=tests/unit/test_evidence_scoring_demo.py \
  --ignore=tests/unit/test_mcp_system.py \
  --ignore=tests/unit/test_guardrails.py \
  --ignore=tests/unit/test_guardrails_sdk.py \
  --ignore=tests/unit/test_mcp_planner_integration.py \
  --ignore=tests/unit/test_nvidia_integration.py \
  --ignore=tests/unit/test_document_action_tools.py \
  --ignore=tests/unit/test_document_pipeline.py \
  --ignore=tests/unit/test_embedding.py \
  --ignore=tests/unit/test_reasoning_evaluation.py \
  --ignore=tests/unit/test_prompt_injection_protection.py \
  --ignore=tests/unit/test_prompt_injection_simple.py

MAIW v2.1.0 test baseline: 3258 Python tests (CORE CI suite, same command as .github/workflows/ci-cd.yml) + 991 UI tests (42 suites)

| Test tier | Command | Requires | |-----------|---------|---------| | CORE CI | Command above | Python packages only | | Integration | pytest tests/integration/ | Running MAIW server + PostgreSQL | | External service | Set NVIDIA_API_KEY, remove --ignore flags | NVIDIA API key + NIM endpoint |

See docs/architecture/TEST_STRATEGY.md for per-file exclusion rationale.

Counterfactual Evaluation (SIMULATED)

Two warehouse worlds (same scenario, same seed) were advanced through the same disruption timeline. The control world received no MAIW intervention; the MAIW world executed governed actions through the standard pipeline.

These results are SIMULATED in MAIW's deterministic synthetic warehouse environment. They are not measurements from a production warehouse.

| Metric | Control | MAIW | |--------|---------|------| | Time to recovery | not reached | 300s (5 sim-min) | | Backlog AUC reduction | — | −92% | | Wave-risk exposure reduction | — | −86.7% | | MAIW governance cycles | 0 | 6 |

Reproduce with:

MAIW_DEMO_MODE=true MAIW_PERSISTENCE_MODE=memory uvicorn maiw_api.app:app --port 8001
python scripts/counterfactual_eval.py   # generates artifacts/demo/labor_wave_control_vs_maiw.*
python scripts/trace_capture.py          # generates artifacts/demo/labor_constraint_wave_risk_trace.*

A frozen pre-NemoClaw performance baseline is preserved under artifacts/baselines/ for future regression comparison.

Repository Structure

.
├─ packages/               # Canonical Python packages
│  ├─ maiw-contracts/      # Domain value objects (equipment, labor, wave, inventory contracts)
│  ├─ maiw-mcp/            # MCP client, capability registry, circuit breakers
│  ├─ maiw-state/          # WarehouseState, domain state models
│  ├─ maiw-decision/       # ActionProposal, DecisionEngine — APPROVED/REJECTED/REQUIRES_HUMAN_APPROVAL/REQUIRES_FRESH_STATE
│  ├─ maiw-models/         # ModelGateway, NIM provider, PolicyFilter, ModelRouter
│  ├─ maiw-skills/         # Inventory, Equipment, Labor, Wave skills
│  ├─ maiw-execution/      # BaseActionExecutor (6-guard pattern), domain executors
│  ├─ maiw-agents/         # Equipment, Labor, Wave, Operations, Safety agents
│  └─ maiw-world/          # Warehouse World — DataPack, ScenarioOverlay, Explorer
├─ apps/api/               # FastAPI application (bootstrap.py, MAIWRuntime)
├─ integrations/           # External integrations (imports packages/, never the reverse)
│  └─ nemoclaw/            # NemoClaw/OpenShell sandbox boundary — policy renderer, contracts
├─ mcp_servers/            # Standalone MCP v2 servers (Inventory, Equipment, Labor, Wave)
├─ src/ui/web/             # React web dashboard
├─ notebooks/              # Developer notebook (MAIW_v2_Getting_Started.ipynb)
├─ artifacts/              # Evaluation artifacts (reliability, model lab, counterfactual)
├─ data/                   # Generated world DataPacks (data/worlds/<dataset_id>/)
├─ deploy/                 # Docker Compose files, container configs, OpenShell sandbox policy
├─ scripts/                # Utility scripts (counterfactual eval, model scripts, data gen)
├─ tests/                  # Test suite (unit, contract, mcp, integration, reliability)
└─ docs/                   # Documentation
   ├─ architecture/        # Architecture docs and diagrams
   ├─ developer/           # Developer reference docs
   └─ GLOSSARY.md          # Canonical terminology glossary

Developer Documentation

| Document | Description | |----------|------------| | docs/architecture/ARCHITECTURE.md | Full architecture document | | docs/architecture/AGENT_RUNTIME.md | Agent runtime (deterministic vs. adaptive) | | docs/architecture/GOVERNANCE.md | Authority boundary, DecisionEngine, approval lifecycle | | docs/architecture/MODEL_GATEWAY.md | ModelGateway chain, Nemotron roles, routing policy | | docs/architecture/MCP.md | MCP SDK, protocol version, deployment | | docs/architecture/WAREHOUSE_WORLD.md | Warehouse World layers, OperationalContextSnapshot | | docs/architecture/DECISION_ENGINE.md | Constraint rules, outcome model | | docs/architecture/CAPABILITY_MATRIX.md | All 13 capabilities, read/write classification | | docs/architecture/DEPENDENCY_BOUNDARIES.md | Package boundary rules | | docs/architecture/RUNTIME_EXECUTION_FLOW.md | Full pipeline sequence diagrams | | docs/architecture/NEMOCLAW_OPENSHELL_INTEGRATION.md | Sandbox containment boundary, policy mapping, threat model | | docs/architecture/TEST_STRATEGY.md | CORE CI command, exclusion rationale | | docs/developer/WAREHOUSE_WORLD_MODEL.md | Warehouse World developer reference | | docs/developer/MODEL_DEPLOYMENT.md | Model deployment modes — hosted, local NIM | | docs/developer/MODEL_GATEWAY_EVALUATION.md | Model Gateway Lab artifacts and evaluation methodology | | docs/GLOSSARY.md | Canonical terminology glossary |

Contributing

1. Fork the repository and create a feature branch.
2. All changes must keep CORE CI green: current baseline 3258 Python tests + 991 UI tests (42 suites).
3. New canonical code goes in packages/, never in src.* for business logic.
4. No src.* imports in any packages/ code — enforced by the test suite.
5. Commit messages must follow Conventional Commits.

License

Apache License 2.0. See LICENSE for full text.

Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.