Skip to main content

AI_INTEGRATION — inventory-service

Sibling: DOMAIN_MODEL · APPLICATION_LOGIC · EVENT_SCHEMAS · SECURITY_MODEL

Strategic anchors: 02 §11 AI Architecture · 08 AI Architecture

inventory-service does not call any AI model directly. The allocation path is concurrency-critical and must remain deterministic — no LLM, no inference, no model-driven decision is allowed in the path that takes an advisory lock and writes the ledger. Inventory's contribution to the platform's AI capabilities is the event stream: ai-orchestrator-service consumes our events to feed forecasting and pattern-detection models that other services use.

1. AI capabilities not used here​

The following are explicitly not on the inventory critical path:

CapabilityWhy not
LLM-based allocation suggestionsAllocation must be sub-200 ms and provably correct under concurrency; an LLM in this path is a latency and correctness hazard
Model-driven overbooking decisionsOverbooking policy is an operator-set rule with auditable cap; AI may suggest a cap (offline, in pricing-service's revenue model) but never set it directly
AI-driven room pick from the type poolThe RoomPicker is a deterministic strategy with documented modes (sequential, least_used, housekeeping_ready_first); deterministic failure modes are easier to debug
Free-text NL search over availabilityLives in bff-tenant-booking-service / search-aggregation-service, not here

If a future enhancement (e.g., demand-aware auto-block, AI room picker) is proposed, it must go through ADR review and ship as a parallel non-blocking path with measurable rollback to the deterministic baseline.

2. AI capabilities that consume inventory events (downstream)​

ai-orchestrator-service subscribes to our analytical event stream and feeds the following models:

ModelTrained onConsumed by
Occupancy forecast2 y of inventory.allocation.confirmed.v1 + …released.v1 + …block.created.v1, joined with pricing-service rate history and external signals (holidays, regional events)pricing-service (dynamic rate suggestions for ops review), revenue-management-service (Phase 2), backoffice dashboards
OOO churn detectorinventory.block.created.v1 density per property × roomhousekeeping-service (preventive maintenance scheduling), reservation-service (proactive reaccommodation alerts)
Walk-in propensityinventory.allocation.confirmed.v1 with mode='walk_in' per property × time-of-daysearch-aggregation-service (cache warm-up scheduling) and bff-backoffice-service (staff scheduling hints)
Group-hold patterninventory.allocation.confirmed.v1 with mode='group_member' joined to groupHoldIdpricing-service group rate suggestions, sales hints
Stop-sell anomalyinventory.block.created.v1 + manual stop_sell flipsnotification-service (alerts to gm/owner if pattern is suspicious)

All consumption happens via Pub/Sub subscriptions on the analytical retention topics; no direct DB read of inventory by AI.

3. Event payload constraints for AI consumption​

Because AI models train on these events, the schemas in EVENT_SCHEMAS are designed to:

  • Carry room-type granularity (not just property-level) so models can learn type-mix.
  • Carry the booking source (mode, assignmentSource, causationEventId) so models can attribute demand to channel.
  • Never carry guest PII (no names, emails, phones, ids beyond opaque ULIDs). Inventory has no PII to begin with; this is a structural property, not a redaction step.
  • Sample availability.queried.v1 at 1% (configurable) to keep the analytical topic affordable while preserving forecasting fidelity.

A schema-CI guard in the platform schema registry blocks any inventory event subject from acquiring a guest-identifying field.

4. Provenance for any AI-derived flag persisted​

In the rare cases where an AI verdict from an upstream service does land back in our DB — e.g., a stop_sell toggle flipped by pricing-service based on a forecasted-demand-collapse signal — the row carries an AIProvenance envelope on a sidecar audit table:

interface AIProvenance {
  modelRef: string;             // 'vertex-ai/occupancy-fc@2026-04-01'
  promptHash?: string;
  inputDigest: string;
  outputDigest: string;
  confidence: number;
  routedBy: 'cloud' | 'edge';
  policyVersion: string;
  decidedAt: string;
  reviewer?: { actorType: 'gm' | 'owner'; actorId: string; reviewedAt: string };
}

Stored in inventory.ai_decisions_audit (append-only). The flip itself remains an operator action by attribution — staff confirm the model suggestion before it lands. We never auto-flip on AI verdict alone.

5. HITL boundaries​

Any AI-suggested change to inventory state is a suggestion, surfaced in the backoffice UI:

  • Suggested stop-sell for a date range based on demand collapse → operator must confirm.
  • Suggested overbooking cap raise for a known event peak → gm/owner must confirm.
  • Suggested OOO consolidation (combine multiple short blocks into one maintenance window) → operator must confirm.

The platform-canonical rule applies: the AI never advances state irreversibly; it never overrides policy; it never decides money.

6. Cost & failure model​

  • We pay zero AI cost on the allocation path.
  • The analytical event topics' BigQuery storage and AI-orchestrator's egress are charged to the AI cost center, not inventory.
  • If ai-orchestrator-service is down: no inventory functionality is impaired. Forecasts in dashboards stale gracefully. Operators see "Forecast unavailable" badges. The only AI-touched inventory surface (suggested stop-sell) simply does not show suggestions.
  • If a model emits a degenerate verdict (e.g., suggesting cap=999999) the operator-confirmation gate prevents the platform from acting on it; the model's output is logged but inert.

7. Cross-references​