6577bb74be
Phase 2 and 3 of the platform rework. - Neutral request/response contract: external_id, metadata, X-AI-Key, run_id in the response; client-specific fields removed. - AI profile is a revision table: saving creates an inactive revision, activation is separate, try-run does not store a run. One chat-completions gateway serves AIHub and OpenAI-compatible profiles. - Add between and in rule operators. - Contracts moved to contracts/lead-scoring/ with a score-response fixture. - Admin Web updated for revisions, runs and the neutral fixture. - Consolidate tests; remove rewrite_architect.md and the stale handoff doc; rewrite spec, CONTEXT and ARCHITECTURE for the current design. Not verified: live AIHub/OpenAI behavior, Omni/EMS integration.
29 lines
2.6 KiB
Markdown
29 lines
2.6 KiB
Markdown
# Context
|
|
|
|
Canonical language for the AI Platform Lead Scoring service. Behavior is specified in `docs/specs/ai-platform-lead-scoring.md`; exact wire shapes are in `contracts/lead-scoring/`. Local checks do not establish client (Omni/EMS) integration, live AI behavior or production readiness.
|
|
|
|
## Systems and ownership
|
|
|
|
- **AI Platform:** a shared, stateless-in-business-terms scoring service. It executes rules, calls an AI model, returns the result and stores the run for replay and the Admin Web.
|
|
- **Client (currently DotB-Omni):** owns rules, weights, score thresholds, human review, user authorization, lead snapshot construction and CRM writeback. The service has no client-specific code; client data travels in `metadata`.
|
|
- **DotB EMS:** CRM system of record for leads.
|
|
- **AIHub:** external AI gateway that receives the client's AI key from the `X-AI-Key` header. An AI profile may instead select an OpenAI-compatible endpoint with a server-side key. AIHub's real protocol and behavior are not independently verified.
|
|
|
|
## Domain terms
|
|
|
|
- **App / installation:** one client deployment with a stable `app_id` and one backend API key. The service stores only a verifier. Rotation keeps run ownership. Admin Web uses an independent session; issuance and rotation are operator CLI only.
|
|
- **Snapshot:** bounded input assembled by the client from a lead and its conversations.
|
|
- **Scoring configuration:** rules, `rule_weight` and `ai_weight`, supplied per request by the client.
|
|
- **Rule score / AI score / final score:** the deterministic rule result, the model's score, and `clamp(round(rule*rule_weight + ai*ai_weight), 0, 100)`.
|
|
- **AI profile:** a service-owned, revisioned configuration (provider, URL, model, timeout, reasoning effort, rubric instructions, prompt switches). Saving creates an inactive revision; activating is a separate step. Each run records the revision used.
|
|
- **AI key:** the client's credential for AIHub, sent per request in `X-AI-Key` and held in memory only.
|
|
- **Idempotency key:** a client UUID, unique per `(app_id, idempotency_key)`. Same key and body replays the stored result; same key and different body is rejected.
|
|
- **Result mode:** `rules_only`, `hybrid` or `rules_only_fallback`; the fallback carries an `error_code`.
|
|
- **Metadata:** an opaque client JSON object (max 10KB) stored and returned unchanged.
|
|
|
|
## Disambiguation
|
|
|
|
- **Rules and weights** are client policy; **rule execution** is service behavior.
|
|
- **Idempotency** prevents duplicate runs for a key; it does not guarantee exactly-once AI invocation.
|
|
- **Draft/review_ready** means prepared for review only, not approved or implemented.
|