2268b6a77a
Add app credentials, account-scoped idempotency and per-app terminal notifications. Consolidate the unreleased migration baseline, preserve rule descriptions as AI context, and regenerate provider contracts with regression coverage.
35 lines
5.2 KiB
Markdown
35 lines
5.2 KiB
Markdown
# Context
|
|
|
|
Canonical language for the AI Platform Lead Scoring provider. The approved rebuild and app-auth baseline `omni-ai-platform-app-auth` revision 2 are implemented and covered by local provider tests. The provider specification `docs/specs/ai-platform-lead-scoring.md` remains `review_ready` for cross-service acceptance. Local checks do not establish Omni/EMS integration or production readiness; see `docs/contracts/app-auth-provider-handoff.md` for evidence and remaining checks.
|
|
|
|
## 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
|
|
|
|
- **App / installation:** one Omni deployment/environment with a stable `app_id`; one backend API key shared by its accounts. Provider checks active state and the simple Lead Scoring permission, and stores only a verifier. Rotation keeps run ownership. Admin Web uses an independent session; issuance/rotation is operator CLI only.
|
|
- **Account:** Omni workspace identified by `account_id` in the request. Omni owns user/account/EMS authorization; AI Platform does not register accounts. `(app_id, account_id)` distinguishes workspaces across installations.
|
|
- **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 app/account context, 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 `(app_id, account_id, request_id)`. Same UUID and same canonical body replays the existing run; same UUID and different body conflicts. A new scoring attempt uses a new UUID. Fingerprint normalization uses the HTTP-validated body serialized as sorted-key compact UTF-8 JSON; generated OpenAPI and fixtures define the input contract.
|
|
- **Result GET:** app-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 carrying app/account/request/run identity and terminal status. Server-side `AI_PLATFORM_APP_WEBHOOKS` chooses each app's destination and secret. The notification is not the result source of truth; Omni GETs the run. Signature/replay and consumer writeback still require cross-service acceptance.
|
|
- **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 app 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.
|