hungtran24/dotb_ai-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dotb_ai-platform/CONTEXT.md

4.5 KiB
Raw Blame History

Context

Canonical language for the AI Platform Lead Scoring provider. The implementation described here is planned, not verified as working. The provider specification docs/specs/ai-platform-lead-scoring.md is a draft/review_ready, pending approval.

Systems and ownership

  • AI Platform: provider service for bounded AI profiles, rule execution, scoring-run lifecycle, result retrieval, and terminal notification.
  • DotB-Omni / Omni: customer-facing authority for configured rules and weights, HITL policy and actions, caller-side authorization, lead identity/snapshot construction, and CRM writeback. Omni reads details from the provider after a signed notification.
  • DotB EMS: CRM system of record for leads.
  • AIHub: default external AI gateway expected to validate/use per-request V-Key and own model access, quota, and provider behavior. An internal, versioned Lead Scoring AI profile may instead select a separate OpenAI-compatible adapter with a server-side key. AIHub's protocol and integration have not yet been independently verified; never infer endpoints, headers, or payloads.

Domain terms

  • Tenant: customer/account boundary used to scope credentials, idempotency keys, and run access. A run lookup must remain inside its authenticated tenant.
  • Tenant key: service credential used to authenticate a tenant/caller at the provider boundary, subject to final agreed provisioning contract. It is distinct from the raw V-Key used for AIHub access. Do not treat the terms as interchangeable.
  • V-Key: sensitive AIHub credential material. Target rule: keep raw value in memory only for the active execution attempt; never persist, log, trace, or send it to the browser. Source and exact forwarding protocol are unresolved.
  • Canonical snapshot: bounded input assembled by Omni from the lead and permitted evidence. It is an input snapshot, not an AI Platform-owned CRM record.
  • Scoring configuration: customer-authored rule/weight and HITL configuration owned by Omni. The provider may consume an immutable version with the request for reproducibility; it does not become the customer configuration authority.
  • AI profile: light, medium, or heavy in an Omni request denotes the bounded orchestration mode. Separately, the internal versioned Lead Scoring configuration selects the provider, model, prompt and timeout; each run freezes its version. Provider choice is not an Omni request field. Concrete models and AIHub behavior still require verification.
  • Scoring run: one provider execution for one tenant, request UUID, subject, snapshot, configuration version, and AI profile. The server-generated run UUID identifies the persisted run.
  • Request UUID / idempotency identity: client-provided UUID included in the request body, scoped to a tenant. Same UUID and same canonical body replays the existing run; same UUID and different body conflicts. A new scoring attempt uses a new UUID. Exact fingerprint normalization remains contract work.
  • Result GET: tenant-authenticated read of the authoritative run result. Omni calls it after receiving a signed terminal notification.
  • HITL (human-in-the-loop): human review workflow and customer actions owned by Omni. The provider does not authorize end users or own the review interface.
  • Terminal notification: provider-to-Omni signed HMAC webhook indicating a run outcome. It is a notification, not the result source of truth; Omni GETs the run. HMAC envelope, replay window, and retry protocol are unresolved.
  • Recovery: after interruption of the single-process runtime, terminalize work that cannot continue because its volatile task/V-Key was lost. Recovery is not resumption and does not imply automatic re-execution.
  • Retention: proposed deletion/redaction of sensitive run material after 90 days. Backup deletion, audit retention, and tenant offboarding behavior need explicit approval.

Disambiguation

  • Rules and weights are customer policy owned by Omni; rule execution is provider behavior owned by AI Platform.
  • Customer action means Omni-authorized configuration/review/initiation behavior; an API caller's identity does not establish end-user permission.
  • Webhook delivery state is separate from scoring-run state. A notification failure does not by itself rewrite a completed scoring result.
  • Idempotency prevents duplicate admission for a body UUID; it does not guarantee exactly-once AIHub invocation or webhook delivery.
  • Draft/review_ready means prepared for stakeholder review only. It does not mean approved, released, or implemented.