Number Intelligence Service — AI Integration

Version: 1.0 Status: Draft Owner: Messaging Core Last Updated: 2026-04-21 Companion: SECURITY_MODEL · APPLICATION_LOGIC · SERVICE_RISK_REGISTER

1. Posture: AI is advisory only

number-intelligence-service is a telecom-deterministic service. MSISDN attribution, MNP lookup, EIR status, and reconciliation are all rule-driven and numeric — they do not benefit from LLM reasoning and they must remain reproducible for regulator defensibility. AI is therefore used only in two narrowly-scoped advisory roles: (A) MNP reconciliation conflict-resolution heuristics, and (B) MNP-churn anomaly detection feeding fraud-intel-service. Neither use case is on the hot path; neither sends raw MSISDN, IMEI, MO body, or any PII to any cloud LLM.

1.1 Non-use guarantees (explicit)

• No cloud LLM, ever, for PII-bearing content. The service does not call Anthropic, OpenAI, Google, or any other cloud LLM with subscriber MSISDN, IMEI, HLR VLR addresses, or MNP file contents. This is enforced at the egress NetworkPolicy (see DEPLOYMENT_TOPOLOGY §5) which whitelists only Postgres, Redis, NATS, Vault, per-MNO SFTP endpoints, per-MNO HLR endpoints (REST adapters where configured), MinIO/S3, and the on-cluster compliance-ai LLM service.
• No real-time AI in the hot path. ResolveMsisdn, LookupPorting, LookupEir are pure SQL + Redis with ≤ 15 ms P95 budgets; AI on the hot path would violate the SLA and the determinism the regulator expects.
• No AI authoring of audit rows, MNP records, EIR records, or HLR probe results. These are deterministic state changes; AI does not draft or summarise them.
• No PII leaves Afghanistan. Per ADR-0004 §3 and the platform data-residency invariant. Even the on-cluster compliance-ai runs in Afghan regions; model weights are pulled into a private registry in Afghan regions, never at runtime from offshore.

2. AI use case A — MNP reconciliation conflict-resolution heuristic (offline, advisory)

2.1 Purpose

When two MNOs claim the same ported MSISDN within a ±2 day window (see APPLICATION_LOGIC §3 MNP Conflict Resolution Heuristics), the deterministic weighted-score heuristic produces a score in [0, 1]. Scores below 0.7 are flagged for manual review. AI is used only to rank the backlog of manual-review items and to generate a short natural-language summary for the admin UI. The admin still makes every resolution decision.

2.2 Topology

• Runs as a scheduled Kubernetes CronJob numint-conflict-triage weekly (Sunday 05:00 Asia/Kabul) and on demand via admin API.
• Reads numint.reconciliation_conflicts WHERE resolution IS NULL for the last 90 days.
• Uses the same on-cluster compliance-ai deployment as compliance-engine (vLLM serving Llama-3.1-8B-Instruct-AWQ; see compliance-engine AI_INTEGRATION §3). No new infrastructure is provisioned.

2.3 Input redaction

Before any token leaves number-intelligence-service for the LLM:

Pattern	Replacement
Raw MSISDN	[MSISDN_N] where N is an index into the current batch (so the model can reference "[MSISDN_1]" across fields)
Tenant identifier	[TENANT_N]
Source-file filename (may contain MNO internal codes)	[FEED_N]
Any 15-digit sequence (likely IMEI or IMSI)	[DIGITS]

The redactor is a strict allow-by-default-deny pipeline in services/number-intelligence-service/src/ai/redactor.ts. An ESLint rule (no-msisdn-in-llm-prompt) forbids calling the LLM client with raw MSISDN strings. A contract test (tests/ai/redactor.spec.ts) verifies that no test input reaches the model un-redacted.

2.4 Prompt (single-turn, JSON-constrained)

System:
You are a telecom Mobile Number Portability conflict triage assistant. You receive
a list of MNP conflicts where two Afghan MNOs claim the same ported MSISDN within
a ±2 day window. For each conflict, the current platform produces a deterministic
weighted score; your job is to (a) rank conflicts by operational urgency, and
(b) provide a one-sentence human-readable summary for each. You MUST NOT propose
a resolution — only rank and summarise.

Output JSON only: { rankings: [ { conflictId, urgencyRank: 1..N, oneLineSummary } ] }.

User:
<REDACTED BATCH of up to 50 conflicts, each with: conflictId, candidateA(mno,portDate,feed),
 candidateB(mno,portDate,feed), deterministicScore>

vLLM grammar-constrained decoding enforces the JSON shape. A response that does not parse is dropped and the conflict triage falls back to pure deterministic-score ordering. The metric numint_ai_conflict_triage_parse_error_total tracks parse failures.

2.5 HITL (human-in-the-loop)

1. LLM output is written to a non-persisted workshop table (not part of numint schema) with TTL 30 days.
2. The admin UI at /v1/admin/numint/mnp/conflicts displays conflicts sorted by urgencyRank when AI output exists, falling back to deterministic score otherwise.
3. Admin review is the authoritative step; conflict resolutions persist through POST /v1/admin/numint/mnp/conflicts/{conflictId}/resolve (see API_CONTRACTS §2.2).
4. The admin UI shows the AI summary and deterministic score side-by-side so the admin can cross-check reasoning.

No conflict is resolved without explicit admin action. AI's role is triage ordering + summary generation.

3. AI use case B — MNP-churn anomaly detection (offline, fraud-signal feed)

3.1 Purpose

Detect abnormal MNP-churn patterns across MSISDN ranges — e.g., a cluster of ported-out MSISDNs from MNO A to MNO B on the same day within a tight prefix range, suggesting either a legitimate enterprise bulk-port (benign) or SIM-swap laundering (malign). The output feeds fraud-intel-service as a signal, not an action.

3.2 Topology

• Runs as a daily Kubernetes CronJob numint-churn-detector at 05:00 Asia/Kabul, after MNP reconciliation completes.
• Reads aggregated counts from numint.portability_history partitioned by (recipient_mno_id, e164 prefix /5, port_date).
• Uses a local classical ML model (scikit-learn IsolationForest, not an LLM) trained weekly on 90 days of historical churn patterns. No LLM is involved in this use case — classical ML is deterministic and cheap to audit.

3.3 Input redaction

Inputs are already aggregated counts; no individual MSISDN ever leaves the service.

Input field	Example
recipientMno	mtn-afghanistan
prefixBucket	+9370 (first 5 digits; ≥ 1 000 MSISDN granularity)
portDate	2026-04-20
count	237
rolling30dMean	8.4
rolling30dStddev	3.1

3.4 Output

Anomalies are published as numint.mnp.churn_anomaly.v1 to fraud-intel-service:

{
  "schemaVersion": "1",
  "recipientMno": "mtn-afghanistan",
  "prefixBucket": "+9370",
  "portDate": "2026-04-20",
  "observedCount": 237,
  "expectedCount": 8.4,
  "zScore": 73.8,
  "severity": "HIGH"
}

No individual MSISDN is ever cited. fraud-intel-service may then independently cross-reference with its own MSISDN-level signals.

3.5 Model governance

• Training data: last 90 days of portability_history aggregated as above.
• Weekly retrain cron; model artifact versioned in MinIO with SHA-256 and signed by the ML engineer.
• A/B shadow: new models run in shadow for 7 days before cutover.
• Regulator defensibility: a full training manifest (inputs, hyperparameters, evaluation metrics) is retained with the model artifact.

4. Out-of-scope AI uses

Explicitly considered and rejected for NI v1:

• LLM-based MSISDN disambiguation (e.g., to guess MNO from ambiguous prefix). The prefix table is deterministic and authoritative; LLM guessing would introduce non-reproducibility.
• LLM-based HLR response interpretation. 3GPP MAP responses are strongly typed; there is nothing for an LLM to interpret.
• LLM-based tenant-facing chatbot for Lookup API. Tenants consume a typed REST API; a chatbot layer belongs to a separate developer-experience-service, not NI.
• Automated MNP conflict resolution. Under no circumstances does AI commit a ReconciliationConflict resolution; this is a regulatory decision path.

5. Monitoring of AI components

Metric	Purpose
numint_ai_conflict_triage_runs_total{outcome}	Weekly triage cron runs
numint_ai_conflict_triage_parse_error_total	LLM response parse failures → fall back to deterministic score
numint_ai_conflict_triage_duration_seconds	Per-run duration
numint_mnp_churn_anomalies_emitted_total{severity}	Anomalies forwarded to fraud-intel
numint_mnp_churn_model_version{version} gauge	Current IsolationForest model version (for rollback clarity)

Alerts:

• NumIntAIConflictTriageDown — cron did not run this week (HIGH).
• NumIntMnpChurnModelStale — current model older than 14 days (MEDIUM).

6. Security reviewer notes

• No secret or credential ever leaves the service to the LLM. The redactor removes even tenant IDs.
• The egress NetworkPolicy blocks all non-Afghan endpoints; a deploy-time residency test verifies.
• On a security incident affecting the on-cluster LLM (e.g., a prompt-injection vector discovered in compliance-engine), both use cases can be disabled via feature flag NUMINT_AI_DISABLED=true; the service continues to operate with deterministic-only conflict triage and no churn-anomaly emission, with no functional degradation of the hot path.