docs

Imported from h3man1h/GovAssist (docs/AGENTS.md). Install upstream with npx skills add h3man1h/GovAssist --skill docs. Copyright stays with the author.

GovAssist — Multi-Agent Architecture & Specification

This document details the responsibilities, inputs, processing logic, outputs, tools, LLM interactions, communication protocols, and failure handling mechanisms for all 8 agents implemented in GovAssist.

1. Agent Architecture Summary

                                  ┌────────────────────────┐
                                  │   Orchestrator Agent   │
                                  │ (State Machine & Gate) │
                                  └───────────┬────────────┘
                                              │ Typed AgentMessage[T]
        ┌──────────────┬──────────────┬───────┴──────┬──────────────┬──────────────┐
        ▼              ▼              ▼              ▼              ▼              ▼
┌──────────────┐┌──────────────┐┌──────────────┐┌──────────────┐┌──────────────┐┌──────────────┐
│Profile Agent ││Discovery Agt ││Eligibility Ag││Document Agent││Application Ag││Verificat. Ag │
│(LLM + Regex) ││(Catalog Tool)││(Determ. Rule)││ (OCR Engine) ││(Portal Client││(Audit Engine)│
└──────────────┘└──────────────┘└──────────────┘└──────────────┘└──────────────┘└──────────────┘
                                                                                       │ Passes Audit
                                                                                       ▼
                                                                                [Human Approval Gate]
                                                                                       │ AUTH-TOKEN
                                                                                       ▼
                                                                                ┌──────────────┐
                                                                                │Execution Agt │
                                                                                │(Portal Client│
                                                                                └──────────────┘

2. Agent Specifications

2.1 Orchestrator Agent (OrchestratorAgent)

• Module: backend/app/agents/orchestrator.py
• Purpose: Acts as the central workflow manager. It maintains session state, enforces valid workflow transitions, sequences agent execution, generates cryptographic human confirmation tokens, and coordinates agent-to-agent communication via typed AgentMessage envelopes.
• Workflow State Sequence:

  INTAKE ➔ DISCOVERY ➔ ELIGIBILITY ➔ DOCUMENTS ➔ DRAFTING ➔ AUDIT_PENDING ➔ HUMAN_CONFIRMATION ➔ EXECUTION ➔ COMPLETE

• Input: Citizen HTTP requests, session IDs, scheme IDs, files, confirmation tokens.
• Processing:
  1. Inspects current SessionModel.current_stage.
  2. Validates whether the requested action is permitted under VALID_TRANSITIONS.
  3. Constructs strongly typed AgentMessage[T] envelopes and dispatches them to specialized agents.
  4. Persists state updates to SQLite and records millisecond telemetry.
  5. If VerificationAgent passes audit, transitions state to HUMAN_CONFIRMATION and generates AUTH-TOKEN-XXXXXXXXXXXX.
  6. Rejects any attempt to execute final submission unless state is HUMAN_CONFIRMATION and the token is valid.
• Output: Structured workflow dictionaries returned to API gateway.
• Tools: Internal state machine transition validator (VALID_TRANSITIONS).
• LLM Usage: None. The Orchestrator is entirely deterministic to ensure predictable workflow enforcement.
• Failure Handling: Raises InvalidWorkflowTransitionError (HTTP 400), UnauthorizedSubmissionError (HTTP 403), or updates stage to FAILED.

2.2 Profile Agent (ProfileAgent)

• Module: backend/app/agents/profile_agent.py
• Purpose: Ingests unstructured conversational text from citizens, extracts demographic, educational, and financial attributes into a structured CitizenProfile, and identifies missing parameters.
• Input: AgentMessage[ProfileExtractionRequest] containing user_text and optional existing CitizenProfile.
• Processing:
  1. Executes regex heuristic extraction for state names, degrees (B.Tech, Degree, ITI), and income figures (e.g. "1.8 Lakhs", "180000").
  2. If an active LLM provider (Ollama) is available, invokes llm_provider.generate_structured(prompt, schema_cls=CitizenProfile) with system prompt instructions.
  3. Validates and merges LLM-extracted fields with heuristic values.
  4. Assigns safe demo placeholders (DEMO-ID-0000, DEMO-BANK-0000) to guarantee no real sensitive numbers are collected.
  5. Computes completeness score and identifies missing parameters.
• Output: AgentMessage[ProfileExtractionResponse] containing merged CitizenProfile, completeness_score, missing_fields, and optional follow_up_question.
• Tools: Deterministic regex heuristic extractor, CitizenProfile Pydantic validator.
• LLM Usage: Invokes local Ollama (gemma4:e2b) for contextual entity understanding with fallback to deterministic heuristics when Ollama is unreachable.
• Failure Handling: Gracefully falls back to heuristic regex extraction if LLM inference times out or fails.

2.3 Scheme Discovery Agent (SchemeDiscoveryAgent)

• Module: backend/app/agents/discovery_agent.py
• Purpose: Discovers matching welfare and scholarship programs from the local scheme catalog based on the citizen's profile.
• Input: AgentMessage[SchemeDiscoveryQuery] containing CitizenProfile.
• Processing:
  1. Invokes SchemeCatalogTool.search(db, profile).
  2. Queries SchemeModel records filtered by state (citizen's state + ALL_INDIA).
  3. Evaluates income ceiling compatibility against scheme specifications.
  4. Assigns match scores (0.0 to 1.0) and generates concise human-readable match rationales (e.g. "Direct match for Andhra Pradesh residents; Income ₹180,000 qualifies under ₹250,000 ceiling").
• Output: AgentMessage[SchemeDiscoveryResponse] containing a ranked list of DiscoveredSchemeMatch items.
• Tools: SchemeCatalogTool.search(), database catalog queries.
• LLM Usage: None during standard search; deterministic catalog queries ensure that only genuine seeded schemes are returned.
• Failure Handling: If no schemes match, returns an empty matches list with advice to adjust income or domicile parameters.

2.4 Eligibility Agent (EligibilityAgent)

• Module: backend/app/agents/eligibility_agent.py
• Purpose: Verifies whether the citizen satisfies official scheme criteria. Crucially, eligibility is evaluated deterministically by the EligibilityEngine rather than delegating decisions to the LLM.
• Input: AgentMessage[EligibilityCheckRequest] containing CitizenProfile and scheme_id.
• Processing:
  1. Loads official scheme rule specification from SchemeModel.eligibility_rules.
  2. Executes EligibilityEngine.evaluate(profile, scheme).
  3. Itemizes criteria evaluations:
     • Income ceiling check (annual_family_income <= max_family_income)
     • Domicile state check (state in eligible_states)
     • Educational level & course check (course in eligible_courses)
     • Merit score threshold check (if applicable)
  4. Determines overall_eligible (True if and only if all mandatory criteria pass).
  5. Determines list of required supporting documents from scheme registry.
• Output: AgentMessage[EligibilityReport] containing itemized CriterionVerdict objects, overall_eligible boolean, and required_documents.
• Tools: EligibilityEngine.evaluate(), SchemeCatalogTool.get_by_id().
• LLM Usage: Zero LLM usage. The engine is the sole source of truth to guarantee 100% deterministic, audit-compliant outcomes.
• Failure Handling: Raises ValueError if scheme ID is invalid; records audit log with ERROR status.

2.5 Document Agent (DocumentAgent)

• Module: backend/app/agents/document_agent.py
• Purpose: Validates uploaded supporting certificates for file readability, extracts key figures (such as annual family income), and cross-checks figures against the citizen's profile.
• Strict Non-Authenticity Standard: The agent never claims that a document is legally or officially authentic. Allowed statuses are strictly:
  • VERIFIED_INFORMATION (document is legible, required fields extracted, and matches profile)
  • NEEDS_REVIEW (discrepancy detected or fields require manual check)
  • MISSING (required certificate omitted)
  • UNREADABLE (corrupted, unparseable, or blank file)
• Input: AgentMessage[DocumentAnalysisRequest] containing document_id, document_type, and file_path.
• Processing:
  1. Ingests file from local storage (backend/app/uploads/).
  2. Dispatches OCREngine.analyze_document(document_id, document_type, file_path, profile).
  3. Reads text content, verifies header tokens (e.g. "INCOME CERTIFICATE", "GOVERNMENT OF ANDHRA PRADESH", "TAHSILDAR").
  4. Extracts numeric values (e.g. 180000.0), certificate numbers, and applicant names.
  5. Cross-checks extracted income against profile.annual_family_income.
  6. Sets verification status to VERIFIED_INFORMATION if values match, or records discrepancies in mismatches_against_profile.
• Output: AgentMessage[DocumentValidationReport] containing verification status, readability score, and extracted fields dictionary.
• Tools: OCREngine.analyze_document().
• LLM Usage: None. Regex and text token classification provide predictable parsing without hallucinations.
• Failure Handling: Returns UNREADABLE status if file cannot be read or parsed.

2.6 Application Agent (ApplicationAgent)

• Module: backend/app/agents/application_agent.py
• Purpose: Automatically drafts the citizen's application on the standalone demonstration government portal (http://127.0.0.1:8001) by mapping verified profile attributes and certificates to portal fields.
• Input: AgentMessage[PortalDraftRequest] containing CitizenProfile, scheme_id, and list of verified documents.
• Processing:
  1. Calls PortalAutomationClient.create_session(scheme_id) on the mock portal.
  2. Populates Step 1 (Applicant Data): full name, DOB, gender, state, demo ID.
  3. Populates Step 2 (Academic Data): institution name, course, current year, roll number.
  4. Populates Step 3 (Financial Data): annual family income, category, demo bank token.
  5. Populates Step 4 (Documents Attachment): uploads verified certificate files to the portal session.
  6. Verifies draft readiness for pre-submission audit.
• Output: AgentMessage[PortalDraftResult] containing portal_session_id (PORTAL-XXXXXXXX), current_step, and draft data dictionary.
• Tools: PortalAutomationClient (asynchronous HTTP client).
• LLM Usage: None. Field mapping is deterministic to eliminate form-filling hallucinations.
• Failure Handling: Catches HTTP communication errors with the portal and raises detailed diagnostic exceptions.

2.7 Verification Agent (VerificationAgent)

• Module: backend/app/agents/verification_agent.py
• Purpose: Executes an independent, automated pre-submission compliance audit on the drafted portal application prior to presenting it to the citizen.
• Input: AgentMessage[AuditVerificationRequest] containing portal_session_id, CitizenProfile, and document validation reports.
• Processing:
  1. Queries the mock portal state via PortalAutomationClient.get_session_state(portal_session_id).
  2. Cross-checks portal applicant name against citizen profile name.
  3. Cross-checks portal domicile state against scheme requirements.
  4. Cross-checks portal course against eligibility criteria.
  5. Cross-checks portal annual family income against both profile income and document OCR extraction.
  6. If any discrepancy exists (e.g. portal income ₹180,000 conflicts with certificate income ₹350,000), flags a blocking issue and sets is_ready_for_human_review = False.
  7. If all fields match, computes compliance score (1.0) and sets is_ready_for_human_review = True.
• Output: AgentMessage[VerificationAuditReport] containing is_ready_for_human_review, field_audits array, blocking_issues list, and compliance_score.
• Tools: PortalAutomationClient.get_session_state().
• LLM Usage: None. Pure deterministic comparison of drafted portal fields against verified sources.
• Failure Handling: Automatically populates blocking_issues and prevents the workflow from unlocking human confirmation.

2.8 Execution Agent (ExecutionAgent)

• Module: backend/app/agents/execution_agent.py
• Purpose: Executes the final, irreversible application submission on the mock government portal strictly upon receiving explicit user authorization.
• Backend Authorization Gate: Under zero circumstances will the ExecutionAgent execute submission without:
  1. Session workflow stage being strictly HUMAN_CONFIRMATION.
  2. A valid, non-empty confirmation_token matching SchemeApplicationModel.human_confirmation_token.
• Input: AgentMessage[ExecutionSubmissionRequest] containing portal_session_id and confirmation_token.
• Processing:
  1. Validates token presence and format.
  2. Calls PortalAutomationClient.submit_application(portal_session_id, declaration=True).
  3. Receives official registration reference number from the portal (DEMO-AP-2026-XXXXXX).
  4. Captures receipt payload, submission timestamp, and marks status as SUBMITTED.
• Output: AgentMessage[ExecutionSubmissionResult] containing reference_number, status: "SUBMITTED", and receipt_payload.
• Tools: PortalAutomationClient.submit_application().
• LLM Usage: None.
• Failure Handling: Raises UnauthorizedSubmissionError (HTTP 403) if token is missing or forged.

3. Typed Agent Communication Protocol (AgentMessage[T])

All 8 agents communicate strictly using strongly-typed envelopes defined in backend/app/schemas/agent_protocol.py:

class AgentMessage(BaseModel, Generic[T]):
    message_id: str = Field(default_factory=lambda: f"MSG-{uuid.uuid4().hex[:8].upper()}")
    session_id: str
    sender_agent: str
    recipient_agent: str
    message_type: str
    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
    payload: T

Benefits of This Architecture:

1. Type Safety: The payload T is validated at runtime using Pydantic V2 models.
2. Auditability: Every message envelope carries a unique message_id, session_id, and UTC timestamp.
3. Observability: Input and output envelopes are logged directly to AgentAuditLogModel with millisecond execution latencies.
4. Modularity: Individual agents can be tested, mocked, or upgraded in isolation without breaking the orchestration state machine.