AI intent assessment¶

The intent compiler converts an English, Filipino, or Taglish message into a validated situation assessment. It distinguishes a journey-worthy government request from conversation or ambiguity.

Processing modes¶

Authorized eGovAI configured¶

When EGOV_AI_BASE_URL, EGOV_AI_ACCESS_CODE, and generation are configured, the compiler can use the authorized eGovAI adapter for requests that are uncertain, complex, or explicitly require AI assessment. Clear, high-confidence rules may resolve without a provider call.

Provider unavailable locally¶

Named deterministic heuristics handle supported high-confidence requests and provide a safe fallback when provider credits are unavailable. The heuristic path produces the same Pydantic assessment shape. If neither path can establish a supported request confidently, eAkto asks for clarification instead of inventing a journey.

Assessment shape¶

The current response separates:

explicit_context — facts stated by the citizen;
inferred_context — possible affected services and blockers;
uncertain_claims — statements expressed with uncertainty;
claims_requiring_verification — claims that need an authoritative source;
workflow_candidates — bounded workflow suggestions;
assistant_reply — normal conversation when no journey should be proposed; and
backend-selected workflow and routing diagnostics.

Journey proposal decision¶

A review card appears only when the compiler determines that:

the message concerns a government goal or record;
enough specific context exists;
a compatible workflow is registered; and
the backend confidence and compatibility checks pass.

Messages such as “hello,” “how are you,” or “what should I do?” receive a concise normal reply. The conversation composer remains available so the citizen can clarify.

Direct requests such as changing an address or correcting National ID information do not require an artificial marriage or life-event classification.

Authority rules¶

The prompt and backend enforce these principles:

Uncertain wording remains uncertain.
AI is not an acceptable verification source.
A provider response cannot mark an agency record complete without authoritative evidence.
AI cannot create new workflow codes.
The backend, not the model, selects the final workflow.
Provider output is parsed once, with at most one bounded schema-repair generation.

Controlled capabilities¶

eGovAI is accessed through capability codes:

Capability	Purpose	Key guard
`EGOVAI_CREDITS_READ`	Confirm available sandbox credits	Brief in-memory cache
`EGOVAI_ASSISTANT_GENERATE`	Assess citizen situation	Permission-gated
`EGOVAI_TRANSLATE`	Translate current guidance	Current journey action required
`EGOVAI_SPEECH_GENERATE`	Produce written speech-style guidance	Optional and non-blocking
`EGOVAI_DOCUMENT_EXTRACT`	Normalize allowed document fields	Consent + idempotency + confirmation

Callers cannot supply a raw provider URL, HTTP method, access code, bearer token, or arbitrary header.

Testing AI behavior¶

Ordinary tests use fakes and never spend provider credits:

cd backend
.venv/Scripts/python.exe -m pytest -q \
  tests/test_intents.py \
  tests/test_marriage_precision.py \
  tests/test_situation_assessment.py

The opt-in sandbox tests are described in Testing.