Enterprise Voice AI Support — Architecture Simulator

This prototype demonstrates a deterministic support orchestration pipeline with inspectable node-by-node state.

Run locally

npm install
npm run dev

Open http://localhost:3000.

Agentic architecture (additional path)

A second orchestration path now exists in parallel to the current hybrid pipeline:

• Hybrid (existing): intent understanding + deterministic policy/routing.
• Agentic (new): OpenAI Agent SDK decides tool usage directly (no intent-classification gate).

Use:

• /tester and switch Approach between Hybrid and Agentic.
• /knowledge-base to upload and preview markdown knowledge files used for troubleshooting.

Optional env var:

OPENAI_AGENT_MODEL=gpt-4.1-mini

Hybrid Understanding Layer configuration

The understanding node supports live structured interpretation with graceful fallback to the deterministic mock provider.

Environment variables

Copy .env.example to .env.local (or create .env.local) and fill in values:

cp .env.example .env.local

# Optional: enables live understanding
OPENAI_API_KEY=sk-...

# Optional override; defaults to gpt-5-mini
OPENAI_UNDERSTANDING_MODEL=gpt-5-mini

# Optional override; defaults to https://api.openai.com/v1
OPENAI_BASE_URL=https://api.openai.com/v1

# Optional: pre-tool provider, defaults to mock
# Set to openai only if your provider supports this endpoint
OPENAI_PRETOOL_PROVIDER=mock

Mock mode (no API key)

If OPENAI_API_KEY is missing or invalid, the app automatically runs in mock mode.

• UI remains functional.
• Understanding node details show provider=mock and fallback reason.
• Deterministic routing and policy behavior are still enforced.

Live mode

With a valid API key, the understanding adapter sends a structured request to GPT-5 mini and validates/sanitizes the result before it reaches routing.

If model output is malformed, the adapter falls back safely to mock/unclear behavior.

Safety note

Structured model output never directly executes tools. The existing deterministic routing/policy layer remains the action gate.

Pre-tool LLM role (current behavior)

The pre-tool LLM is implemented as an advisory understanding step, not the sole workflow controller:

• It runs only when intentUnderstandingMode === "llm_assisted".
• It infers intent and extracts entities into a constrained schema (service_status | announcements | none) and can suggest a workflow.
• It effectively does intent matching against the allowed demo intents by sanitizing to that whitelist; anything else is normalized to none/unclear.
• Its output is mapped into understandingProviderResult, then passed into the deterministic policy engine.
• The policy engine does a second routing-table match (ROUTING_CONFIG) and may still override low-confidence/unclear cases with deterministic fallback signals before deciding the route.
• The deterministic policy still makes the final route decision (workflow, clarify, handoff, or no_workflow) and controls tool execution.

So today, intent matching exists, but in two guarded stages (LLM schema match + deterministic policy/table match), with workflow driving remaining policy-gated by design.

Tool Execution subsystem

Tool execution is implemented as a typed subsystem under tools/:

• toolTypes.ts: typed tool contracts (request/response per tool)
• toolConfigs.ts: per-tool mode/endpoint/timeout/fallback config
• registry.ts: tool registry that dispatches each tool by name
• mockTools.ts: deterministic demo-friendly local behavior
• apiTools.ts: fetch-based API adapter with timeout/error handling
• toolRunner.ts: orchestration entrypoint that selects tools, validates payloads, executes, and returns inspectable execution records

Supported tools:

• diagnose_connectivity()
• check_outage_status(postcode)
• reschedule_technician(date)
• create_support_ticket(summary)

Switching mock vs API mode is done in demo controls and requires no orchestration rewrite.

Multi-turn state + slot filling

The tester/orchestrator now keeps explicit conversation state across turns:

• running turn history (session.conversation.history)
• durable slot memory (session.conversation.slots)
• pending workflow continuation (session.conversation.pendingWorkflow)

If a routed workflow is missing required parameters (for example postcode for outage checks), the deterministic policy stays inspectable and moves into clarify with a concrete slot prompt. The next turn can fill the missing slot and automatically continue the pending workflow without rewriting the existing architecture.

OSS Support Portal API-backed tools

API mode can now call real portal-backed endpoints through app routes:

• POST /api/tools/outage-check → OSS /v1/outages/check
• POST /api/tools/diagnose-connectivity → OSS /v1/connectivity/diagnose
• GET /api/tools/service-status → OSS /v1/status

Set these optional env vars to enable live calls:

OSS_SUPPORT_PORTAL_BASE_URL=https://api.oss-support-portal.example.com
OSS_SUPPORT_PORTAL_API_KEY=...

Additional API-backed tools now include:

• fetch_service_status(active?)
• fetch_notifications(active?, from?, to?)
• check_outage_status(serviceNameOrRegion?) (aggregates service-status + notifications)

OSS Support Portal configuration

OSS_PORTAL_BASE_URL=https://status.oss-portal.example.com
OSS_PORTAL_API_KEY=...

check_outage_status in API mode queries:

• GET /api/service-status?active=true|false
• GET /api/notifications?active=true|false&from=YYYY-MM-DD&to=YYYY-MM-DD

The tool normalizes both feeds into one inspectable outage result payload for response generation.

MVP polish additions (UX + inspectability)

This pass improves demo-readiness without changing simulator core behavior:

• Clearer controls copy and run-button wording in full-run vs step mode.
• Keyboard shortcuts for presenter speed:
  • Ctrl/Cmd + Enter: run simulation
  • N: next step (only in step mode)
• Lightweight progress indicator in header (currentStep/totalSteps).
• Copyable inspection JSON from the Execution panel (session + logs snapshot).
• Readable structured diagnostics (pretty-printed payloads in node details).

Demo flow checklist

Use this sequence for reliable stakeholder walkthroughs:

1. Start with default sample utterance and Run full simulation.
2. Open Execution Log & Latency Timeline and copy inspection JSON.
3. Click each node to inspect inputs/outputs and fallback behavior.
4. Enable Step-through mode and use N to show deterministic progression.
5. Toggle fallback and workflow flags to show policy-controlled route changes.
6. Switch tool mode between mock/API stub to demonstrate adapter boundaries.
7. Replay synthesized audio from Session Summary.

Verification commands

npm run lint
npm run build

If both pass, the MVP is ready for demo packaging and handoff.

Demo documentation

• README.md: architecture and setup overview
• DEMO_GUIDE.md: presenter walkthrough and edge-case scripts
• MVP_CHECKLIST.md: final pre-demo verification checklist