35 lines
4.5 KiB
Markdown
35 lines
4.5 KiB
Markdown
# 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.
|