hungtran24/dotb_ai-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dotb_ai-platform/CONTEXT.md
hungtran24 6577bb74be refactor: simplify scoring service, AI profile revisions and test suite 
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.
2026-10-09 08:23:21 +07:00

2.6 KiB
Raw Blame History

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.