Warehouse Assistant — FieldOps Module

Material Stock, Deliveries &
Receiving — AI-Driven.

A multi-agent AI assistant embedded inside FieldOps that answers field crew questions about material stock, delivery status, receiving confirmations, damage reports, and spec lookups — connected to real IFC takeoff data published from PRIME's Takeoff-Cost module.

7
Warehouse intents — stock, delivery, receiving, damage, invoice, specs, escalation
IFC
Required quantities sourced from real takeoff data — no synthetic SKU table
RAG
Spec sheets, SDS, submittals, and vendor catalogs — searchable by AI
100%
Safety keywords escalate immediately — bypass confidence routing

Overview

Billie for Construction — Translated

The Warehouse Assistant adapts IKEA's Billie multi-agent architecture — intent classification, confidence routing, RAG, and human handoff — for a commercial construction warehouse embedded in FieldOps alongside Procure and Contracts Q&A.

Where Billie routes retail queries (order tracking, product availability, billing problems), the Warehouse Assistant routes construction queries: material stock checks against IFC takeoff quantities, delivery status from PO records, receiving confirmations, damage reports with photo capture, invoice discrepancy flags, and specification lookups via pgvector RAG.

Frontend
Embedded FieldOps module — scoped CSS, dark sub-container, same hub/launch pattern as Procure and Contracts Q&A
AI Layer
Claude (claude-sonnet-4-6) for intent classification and RAG-grounded answers — reuses the existing voice-engines/shared/claudeApi.ts helper
State
Zustand slice (useAssistantStore) subscribing to activeUpload cross-module store for live IFC takeoff data
Backend
Supabase (same project as prime-suite-v3) — takeoff line items, receiving ledger, installation log, pgvector knowledge base. Currently mock-backed; service layer designed for drop-in swap.
Scope
Multi-project, multi-trade commercial suite — keyed on job_id to match FieldOps's existing 16-table schema convention

Intent Classification

Seven Intents — One Router

Every message from a field crew member is first classified by Claude into one of seven warehouse intents. The intent determines which specialist agent handles the response and what data source it queries.

material_stock_check Queries takeoff_line_items (required qty) minus installation_log (consumed) minus receiving_ledger in-transit. Returns the real on-hand gap — not a flat inventory count.
delivery_status Queries PO records from the Procure module (status: issued|received) and shipment tracking data for ETA and dock appointment.
receiving_confirm Writes a receiving confirmation entry to receiving_ledger. Field crew confirms quantity, condition, and PO match — with photo capture from FieldOps's existing capture pipeline.
damage_report Initiates a damaged/short shipment report linked to the relevant PO line item. Routes to the safety override path if safety keywords are detected. Photo evidence attached via FieldOps capture hooks.
invoice_discrepancy Flags a 3-way match failure: PO value vs. receiving confirmation vs. vendor invoice. Logs the discrepancy to the project record and optionally routes to procurement for resolution.
spec_lookup RAG query against kb_chunks (pgvector, cosine similarity) over uploaded spec sheets, SDS documents, submittals, and vendor catalogs. Returns cited passages with source reference.
human_agent Terminal intent — issued when confidence is below 60% or a safety override fires. Packages conversation context into a handoff summary card for a human supervisor to pick up.

Confidence Routing

Three Bands. One Safety Override.

After intent classification, the confidence score routes the query to one of three paths. A separate safety override gate runs before the confidence check — if triggered, it bypasses all confidence bands and escalates immediately.

Input
Field Query
Raw message from warehouse crew or PM
→
Step 1
Intent + Confidence
Claude classifies intent and returns a 0–1 confidence score
→
> 90%
Auto-resolve
Agent executes, returns answer
60–90%
Clarify
ClarificationPrompt shown to user
< 60%
Human handoff
HandoffSummaryCard generated
> 90% — High
Auto-resolve
Agent executes the intent immediately. Answer returned with source data citation. No user confirmation required.
60–90% — Mid
Clarify
ClarificationPrompt component renders in the chat — asks a single targeted question to resolve ambiguity before proceeding. Once answered, re-routes through confidence check.
< 60% — Low
Human handoff
HandoffSummaryCard packages the full conversation context — intent guess, confidence, message history, and data queried so far — for a human supervisor to pick up without re-asking questions already answered.
⚠ Safety Override — Highest Priority Gate
Safety keywords bypass confidence routing at 100%

Before any confidence check runs, safetyOverride.ts scans the raw query for keywords including injury, unsafe, exposed wiring, structural, collapse. If any match, the query escalates immediately to a human agent — the EscalationBanner renders as a non-dismissible red banner in the chat UI. Confidence score is irrelevant: a "material_stock_check" flagged with a safety keyword escalates the same as a "damage_report". This is the key deviation from Billie's architecture, where escalation is sentiment-driven only.

  • Safety override fires before any confidence check — no routing band can catch it first
  • EscalationBanner is non-dismissible — requires explicit supervisor acknowledgment
  • Damage reports near safety keywords auto-escalate regardless of how the intent was classified
  • Override keywords are configurable per project in the assistant settings

Material Stock Check

Real Quantities — Not a Flat SKU Table

The critical deviation from Billie's product availability intent: stock check doesn't query an isolated inventory table keyed by SKU. In a construction warehouse, quantities are defined by the IFC takeoff — what's required to build the model. The warehouse assistant resolves against that published takeoff data, joined against what's arrived and what's been installed.

required = takeoff_line_items -- from IFC Takeoff-Cost, published via "Publish to Warehouse"
in_transit = receiving_ledger -- confirmed PO deliveries not yet consumed
installed = installation_log -- field crew confirms material consumed on-site

on_hand_gap = required − installed − in_transit

-- positive gap = material still needed
-- zero or negative = covered by deliveries + installed

The Publish to Warehouse action on the IFC Takeoff-Cost module is the upstream dependency — it writes finalized line items to takeoff_line_items in Supabase when a takeoff is committed. Until that action exists, material stock check runs against mock data behind the same service-layer seam used by Procure and Contracts Q&A.

Knowledge Base

Spec Sheets, SDS & Submittals — AI-Searchable

The spec_lookup intent routes to a RAG pipeline over pgvector on Supabase — the same database already running FieldOps and Procure. No additional vector database vendor. Cosine similarity retrieval with project-scoped RLS so crews only see documents relevant to their job.

Document types supported

  • Specification sections (CSI MasterFormat divisions)
  • Safety Data Sheets (SDS) for all site materials
  • Submittal packages — shop drawings, product data, samples
  • Vendor catalogs and cut sheets
  • Installation manuals and technical bulletins

Retrieval design

  • Voyage AI embeddings (1024-dim) — Anthropic's recommended embedding partner
  • Cosine similarity via Supabase match_documents RPC
  • Row-Level Security scoped by project_id — no cross-job document leakage
  • Every answer cites the source document title and chunk reference

Database Schema

Five New Tables — Same Supabase Project

All new tables key on job_id to match FieldOps's existing 16-table schema convention. No project_id — job is already the project-equivalent in the existing schema.

takeoff_line_items — published from IFC Takeoff-Cost module
iduuid PKprimary key
job_iduuid FKreferences job(id) — multi-project scoping
ifc_element_guidtexttraceability to source IFC element in BIM model
material_codetextmaterial identifier / CSI code
descriptiontexthuman-readable material description
unittexte.g. m², m³, LF, EA
quantitynumericrequired quantity from takeoff
tradetexttrade category (structural, mechanical, finishes…)
sourcetext'takeoff' | 'quickEstimate'
committed_attimestamptzwhen takeoff was published to warehouse
receiving_ledger — deliveries confirmed by field crew
iduuid PK
job_iduuid FKreferences job(id)
po_iduuid FKreferences purchase_orders — extends existing Procure PO
material_codetextmatches takeoff_line_items.material_code
qty_receivednumericconfirmed quantity received at dock
conditiontext'good' | 'damaged' | 'short'
photo_urlstext[]from FieldOps photo capture pipeline
received_attimestamptz
received_byuuid FKfield crew member who confirmed
installation_log — material consumed on-site
iduuid PK
job_iduuid FK
takeoff_line_item_iduuid FKlinks consumption back to the IFC element
qty_installednumericquantity installed this entry
location_notetextfloor / grid reference where installed
logged_attimestamptz
logged_byuuid FK
kb_documents — uploaded spec sheets, SDS, submittals, catalogs
iduuid PK
job_iduuid FKRLS scoped — crews see only their project docs
doc_typetext'spec' | 'sds' | 'submittal' | 'catalog'
titletextdocument display name
source_reftextspec section number, submittal ref, or catalog part
uploaded_attimestamptz
kb_chunks — pgvector embeddings for RAG retrieval
iduuid PK
document_iduuid FKreferences kb_documents(id)
chunk_texttextraw passage text used for retrieval and citation
embeddingvector(1024)Voyage AI embeddings — 1024 dimensions
metadatajsonbpage number, section heading, trade tag

FieldOps Integration

Scaffold — Same Pattern as Procure & Contracts Q&A

The Warehouse Assistant follows the same hub-page + dark sub-container pattern established by Procure and Contracts Q&A. Scoped CSS prefix (wa-*) prevents class collisions. Nav entry added to nav.ts. Route added to App.tsx.

warehouse-assistant/
├── src/features/warehouseAssistant/
│ ├── components/
│ │ ├── ChatWidget.tsx orchestrates intent → confidence → agent → response
│ │ ├── ClarificationPrompt.tsx rendered in chat for 60–90% confidence queries
│ │ ├── EscalationBanner.tsx red, non-dismissible — fires on safety override
│ │ └── HandoffSummaryCard.tsx packages context for human supervisor pickup
│ ├── agents/
│ │ ├── intentRouter.ts classify → {intent, confidence} via Claude
│ │ ├── confidenceRouter.ts >90 auto / 60–90 clarify / <60 human handoff
│ │ └── safetyOverride.ts keyword gate — bypasses confidence entirely
│ ├── api/ mock-backed, Supabase seam clearly marked
│ │ ├── materialStock.ts reads activeUpload takeoff store → on-hand gap
│ │ ├── deliveryStatus.ts Procure PO / shipment records
│ │ ├── receivingLedger.ts writes confirmation entries, reuses photo capture
│ │ └── knowledgeBase.ts pgvector cosine similarity via match_documents RPC
│ ├── store/
│ │ └── assistantStore.ts Zustand slice, subscribes to activeUpload cross-module store
│ └── types/index.ts WarehouseIntent union, message types, store shape
├── WarehousePage.tsx hub page — follows ProcurePage / ContractsPage pattern
├── WarehouseShell.tsx tab nav: Assistant | Stock | Receiving | Documents
└── warehouse.css wa-* scoped, self-contained — no procura.css dependency

Build Sequence

What's Built vs. What's Next

✅
Done — FieldOps module scaffold
Hub page, chat widget, intent router, confidence router, safety override, all four API functions (mock-backed), Zustand store, scoped CSS, nav entry, and App.tsx route. TypechecksI and builds clean.
✅
Done — Supabase schema
warehouse_schema.sql — five tables ready to run against the shared Supabase project: takeoff_line_items, receiving_ledger, installation_log, kb_documents, kb_chunks with pgvector.
⏳
Next — Publish to Warehouse action
New action on the IFC Takeoff-Cost module in prime-suite-v3. Writes committed line items to takeoff_line_items in Supabase. This is the upstream bottleneck — material stock check has nothing real to query until this exists.
⏳
Next — Supabase client wiring
Each API function has the real Supabase query commented inline at the exact point of the mock. Wiring the backend is a find-and-replace, not a redesign — by design.
⏳
Next — pgvector RAG pipeline
Enable pgvector extension on Supabase, create match_documents RPC, configure Voyage AI embedding generation on document upload. knowledgeBase.ts already has the retrieval call written.
⏳
Next — Auth & RLS policies
Row-Level Security on all five new tables — scoped by job_id to the authenticated user's assigned jobs. No cross-project data leakage.

Module Status

Frontend scaffold complete — backend pending Supabase provisioning

The Warehouse Assistant runs today against mock data. Real stock checks activate once the Publish to Warehouse action is built in the Takeoff-Cost module.

Back to PRIME Suite ← Procure Module