Skip to content

AI_MODELS.md

Latest commit

 

History

History
124 lines (95 loc) · 6.03 KB

AI_MODELS.md

File metadata and controls

124 lines (95 loc) · 6.03 KB
Raw

AI model integration and activation

Sahaay exposes AI as an optional, backend-controlled application-assessment feature. The live adapter uses the OpenAI Responses API and structured output; deterministic intelligence remains available in the demonstration UI when the adapter is disabled.

AI output is advisory. It cannot approve, decline, price, or automatically advance a loan. An authorised reviewer must validate source data, deterministic policy rules, generated conditions, and the final decision.

What is implemented

Component Behaviour
GET /api/v1/ai/status Reports enabled/configured/available state, provider, and model; never returns a secret
POST /api/v1/ai/application-assessments Sends an allowlisted, minimized application snapshot to the configured adapter
OpenAI adapter Calls /v1/responses, requests strict JSON-schema output, validates the response, and returns safe provider errors
Application drawer Shows live-AI availability and uses the live assessment when the reviewer selects Run live AI
Disabled mode Preserves deterministic demonstration intelligence and makes no provider request

Get and store an API key

  1. Create a project and API key in the OpenAI platform for the appropriate non-production or production environment.
  2. Store the key in an approved secret manager. Do not paste it into source, .env.example, frontend configuration, tickets, or logs.
  3. Inject the secret as OPENAI_API_KEY into the FastAPI runtime.
  4. Restrict secret access to the API workload and configure spend/rate limits and operational alerts in the provider account.

For local sandbox development only, copy the environment template and put a sandbox key in the ignored .env file:

cp .env.example .env
AI_ENABLED=true
AI_PROVIDER=openai
AI_MODEL=gpt-5.6-luna
OPENAI_API_KEY=your-sandbox-key
OPENAI_BASE_URL=https://api.openai.com/v1
AI_REQUEST_TIMEOUT_SECONDS=30
AI_MAX_OUTPUT_TOKENS=1400
AI_STORE_PROVIDER_RESPONSES=false
VITE_API_BASE_URL=http://localhost:8000

Restart the API after changing environment variables. Never prefix the key with VITE_; Vite exposes such values to browser bundles.

Verify activation

Start the backend and frontend, then check the safe status endpoint:

curl http://localhost:8000/api/v1/ai/status

An activated adapter returns:

{
  "enabled": true,
  "configured": true,
  "available": true,
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "secret_exposed": false
}

Open an application, select Intelligence, and choose Run live AI. The UI will show the provider/model badge and replace the local demonstration assessment only after a schema-valid provider response is received.

API contract

Only allowlisted fields are accepted. Direct identifiers such as borrower name, PAN, Aadhaar, phone number, email, address, and account number are not part of the contract.

curl -X POST http://localhost:8000/api/v1/ai/application-assessments \
  -H 'Content-Type: application/json' \
  -d '{
    "application_id": "HL-2026-0842",
    "loan_product": "Home Loan",
    "amount_inr": 4600000,
    "stage": "Underwriting",
    "current_risk_band": "Medium",
    "bureau_score": 690,
    "monthly_income_inr": 145000,
    "monthly_obligations_inr": 60900,
    "document_confidence": 84,
    "flags": ["bank_statement_requires_review"],
    "consent_reference": "consent-LOS-0842-v1",
    "purpose": "underwriting_assistance"
  }'

The consent reference is validated by the LOS but deliberately excluded from the provider payload. In production it must refer to a persisted, current consent record; the demonstration UI uses a synthetic reference.

Security and governance controls

  • Keep AI_ENABLED=false until security, legal, compliance, data-residency, model-risk, and vendor approvals are complete.
  • Keep AI_STORE_PROVIDER_RESPONSES=false unless retention has been explicitly approved.
  • Enforce outbound network policy so the API can reach only approved provider endpoints.
  • Keep bounded request timeouts and output-token limits, and add per-user rate and spend controls.
  • Record application ID, consent ID, purpose, provider/model, provider request ID, input fingerprint, timestamps, reviewer action, and overrides in an immutable audit trail.
  • Do not log prompts, raw model responses, API keys, or borrower PII.
  • Add server-side authentication, authorisation, rate limiting, idempotency, budget controls, retries, circuit breaking, and audit persistence before production.
  • Run bias, accuracy, stability, prompt-injection, data-leakage, and representative-case evaluations before every model or prompt change.
  • Pin a tested model snapshot for controlled production releases when the provider supports snapshots; promote model changes through the normal SDLC.

Switching models or providers

AI_MODEL is environment-driven so a tested model can be promoted without changing the UI. A model change is still an SDLC change: run contract tests, offline evaluation, model-risk review, UAT, approval, deployment, and post-release monitoring.

The service uses an internal adapter protocol. To add another provider:

  1. Implement AIApplicationAssessmentAdapter under backend/app/integrations/ai/.
  2. Map the provider response into AIAssessmentContent.
  3. Add adapter contract and safe-error tests.
  4. Register the provider in AIAssessmentService.
  5. Add provider-specific secret references and onboarding documentation.
  6. Complete the same governance and release gates as the OpenAI adapter.

Do not use a client-supplied base URL or key. Provider selection and credentials remain deployment configuration controlled by the server.

Official OpenAI references