[codex] Portal API: tenant isolation, p95 gates, and multilingual demo (10/10)

[ChunkyTortoise]

Summary

This PR completes the Portal API interview hardening and advanced demo enhancement in two commits:

1. portal_api: add idempotency keys and auth mode hardening
2. portal-api: ship tenant isolation, p95 gates, and multilingual demo

Together, they move the demo from a basic deterministic flow to an interview-ready 10/10 flow with production-oriented safety and operability signals.

Problem

The prior interview slice proved basic API correctness, but it did not fully demonstrate:

1. Strong multi-tenant safety guarantees
2. Deterministic performance gates with explicit pass/fail criteria
3. Multilingual readiness on a typed API contract
4. Replay safety and env-gated auth controls on all key mutating routes

In practical terms, that made it hard to show senior-level readiness under real constraints.

Root cause

The Portal API lacked a canonical tenant context model and tenant-scoped in-memory partitions, performance checks were informational rather than release-gating, and language readiness had no endpoint contract. In addition, mutating route hardening needed explicit idempotency/auth behavior with stable contract-level guarantees.

User impact

For interview/demo stakeholders, this change improves confidence that the API:

1. Prevents cross-tenant data leakage deterministically
2. Enforces p95 latency expectations as script-level gates
3. Supports a multilingual roadmap with typed, test-backed behavior
4. Preserves reliable mutating behavior with idempotent replay and clear auth semantics

Implementation details

1) Tenant isolation and context rules

• Added canonical tenant context resolution in portal_api/dependencies.py:
  • X-Tenant-ID header (preferred)
  • payload fallback where applicable (location_id on swipe)
  • default tenant_default
• Partitioned in-memory state by tenant in:
  • modules/inventory_manager.py
  • modules/ghl_sync.py
  • modules/appointment_manager.py
• Applied tenant scoping to read/write endpoints:
  • GET /portal/deck
  • POST /portal/swipe
  • GET /system/state
  • GET /system/state/details
  • POST /vapi/tools/book-tour

2) Performance threshold gates

• Extended scripts/portal_api_latency_sanity.py to probe:
  • /health
  • /portal/deck?contact_id=lead_001
  • /portal/swipe
• Added p95 thresholds and failure exit behavior:
  • health p95 <= 50ms
  • deck p95 <= 200ms
  • swipe p95 <= 100ms
• Script now prints per-endpoint table + pass/fail lines and returns non-zero on breach.

3) Multilingual detection endpoint

• Added typed models in portal_api/models.py:
  • LanguageDetectRequest
  • LanguageDetectResponse
• Added new route POST /language/detect via portal_api/routers/language.py and router wiring in portal_api/app.py.
• Implemented deterministic baseline detection:
  • Hebrew by Unicode range
  • Spanish by accents + stopword heuristics
  • English by stopword heuristics
  • fallback unknown for ambiguous inputs

4) Hardening baseline integration

• Preserved and extended idempotency/auth/request-id/openapi hardening from the prior commit:
  • idempotency replay and conflict handling on mutating routes
  • env-gated auth mode behavior
  • stable error envelope contracts
  • request-id propagation

5) Demo + evidence upgrades

• Upgraded scripts/portal_api_interview_demo.sh from 7/7 to 10/10:
  • 8/10 tenant isolation proof
  • 9/10 performance validation
  • 10/10 multilingual detection
• Updated docs/evidence:
  • README.md
  • plans/PORTAL_API_INTERVIEW_EVIDENCE_FEB10_2026.md
  • plans/PORTAL_API_INTERVIEW_COMPLETION_SPEC_FEB10_2026.md
  • plans/PORTAL_API_INTERVIEW_WALKTHROUGH_5MIN_FEB10_2026.md

Validation

Commands run from repo root:

bash -n scripts/portal_api_validate.sh scripts/portal_api_interview_demo.sh
ruff check main.py portal_api modules scripts/portal_api_client_example.py scripts/portal_api_latency_sanity.py
python3 -m py_compile main.py portal_api/app.py portal_api/dependencies.py portal_api/models.py portal_api/routers/root.py portal_api/routers/vapi.py portal_api/routers/portal.py portal_api/routers/ghl.py portal_api/routers/admin.py portal_api/routers/language.py modules/inventory_manager.py modules/ghl_sync.py modules/appointment_manager.py modules/voice_trigger.py scripts/portal_api_client_example.py scripts/portal_api_latency_sanity.py
pytest -q -o addopts='' --confcutdir=portal_api/tests portal_api/tests
bash scripts/portal_api_interview_demo.sh

Observed results:

1. ruff: pass
2. py_compile: pass
3. pytest: 51 passed
4. demo script: pass with [PASS] interview demo flow completed (10/10)

Notable output proofs

1. [PASS] tenant_a and tenant_b are fully isolated
2. [PASS] p95 thresholds met
3. [PASS] multilingual readiness verified (en/es/he)
4. [PASS] interview demo flow completed (10/10)

Risks and mitigations

1. Risk: tenant scoping could break legacy no-header flows
   • Mitigation: explicit tenant_default fallback + compatibility tests
2. Risk: noisy local machines can skew latency
   • Mitigation: configurable run counts/timeouts while keeping deterministic threshold logic
3. Risk: rule-based language detection can misclassify edge text
   • Mitigation: explicit scoped detector with unknown fallback and typed confidence/strategy fields

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.