AI Insights Service - Personal Finance Backend

Financial intelligence service in the Personal Finance ecosystem.

Purpose

This service transforms user financial data into actionable AI outputs:

• deterministic insights and alerts
• explainable recommendations (why, impact, suggested action)
• simulation and monthly planning endpoints
• chat advisory baseline
• notifications generation and delivery data
• observability metrics for AI usage and quality

It never executes financial actions and does not connect directly to bank accounts.

How It Fits In The Ecosystem

1. Frontend calls backend-core (/api/ai/*).
2. backend-core validates auth and forwards Authorization + X-Correlation-ID.
3. backend-core calls this service internally.
4. ai-insights reads user financial data from Postgres and returns results.

Responsibilities:

• frontend: experience and interactions
• backend-core: gateway/orchestration/auth boundary
• ai-insights: AI/business analysis logic
• backend-shared: models/database/auth dependencies

Current API Surface

• GET /api/ai/health
• GET /api/ai/insights
• POST /api/ai/chat
• POST /api/ai/feedback
• POST /api/ai/simulate
• POST /api/ai/plan/monthly
• GET /api/ai/observability/summary
• GET /api/ai/usage/summary

Notifications (backend-backed):

• POST /api/ai/notifications/generate
• GET /api/ai/notifications
• GET /api/ai/notifications/unread-count
• GET /api/ai/notifications/schedule
• POST /api/ai/notifications/{notification_id}/read
• POST /api/ai/notifications/read-all
• POST /api/ai/notifications/scheduler/generate (internal, token-protected)
• POST /api/ai/notifications/scheduler/deliver (internal, token-protected)

Notifications Strategy

This service supports two generation modes (env controlled):

• test_interval: generate window-based notifications every N minutes (default 30) for test flows.
• daily_6am: production-ready mode for daily generation at configured hour (default 06:00 UTC).

Current env defaults are prepared for test iteration and easy switch to daily.

Dedupe Policy (in-app)

In-app notifications use daily dedupe to avoid feed spam:

• dedupe key format: insight_<period_end>_<code>
• same user + same day + same alert code => no duplicate in-app item
• repeated scheduler runs in the same day update delivery pipeline but do not create duplicate in-app messages

This keeps the in-app feed concise while allowing richer channel delivery later (email/push).

Segurança e autenticação

• Requisições devem carregar Authorization: Bearer <token>
• O token é validado no ecossistema compartilhado (personal-finance-backend-shared)
• Propagação de X-Correlation-ID para rastreio fim-a-fim

Observabilidade

• Logging estruturado JSON
• Correlação por request (X-Correlation-ID)
• Eventos importantes com contexto (user_id, endpoint, período)

Nota de produto/arquitetura:

• métricas operacionais de observability são consumidas de forma centralizada no Admin Console (via backend-core).
• usuários finais continuam com funcionalidades AI de produto (insights/chat/notificações/plan), sem tela operacional dedicada.

Dependências

• FastAPI + Uvicorn
• PostgreSQL (via personal-finance-backend-shared)
• personal_finance_shared (models, db, auth/dependencies, logging)

Data Structures Created At Runtime

• ai_feedback: thumbs up/down feedback (chat/insight/notification context)
• ai_observability_events: endpoint latency, errors, feature usage events
• ai_notifications: persisted user notifications + read state + relevance score
• ai_notification_deliveries: delivery pipeline state (pending, delivered, failed) per channel
• ai_usage_events: AI metering events (request-level usage, latency, status, feature)
• ai_usage_credits: AI overage credit balance per user
• ai_usage_credit_ledger: append-only ledger for AI credit adjustments/consumption

Explainability

Insights include explainability fields per alert:

• why
• impact_estimate
• suggested_action

This supports transparent recommendations in UI and future LLM tool orchestration.

Guardrails

• no direct banking integrations
• no payment/trade execution
• informational guidance only

Security and Traceability

• Bearer token auth via shared dependencies
• structured JSON logs
• correlation via X-Correlation-ID
• endpoint-level observability

Environment Variables

Database/Auth:

• DB_HOST
• DB_NAME
• DB_USER
• DB_PASSWORD
• JWT_SECRET_KEY
• CORS_ALLOWED_ORIGINS

Notifications behavior:

• AI_NOTIFICATIONS_MODE (test_interval or daily_6am)
• AI_NOTIFICATIONS_TEST_INTERVAL_MINUTES (default 30)
• AI_NOTIFICATIONS_DAILY_HOUR_UTC (default 6)
• AI_NOTIFICATIONS_SCHEDULER_TOKEN (required for internal scheduler endpoints)

AI metering/quota behavior:

• AI_QUOTA_ENFORCEMENT_ENABLED (false by default)
• AI_MONTHLY_REQUEST_LIMIT (fallback global, default 500)
• AI_MONTHLY_REQUEST_LIMIT_FREE (default 60)
• AI_MONTHLY_REQUEST_LIMIT_PLUS (default 300)
• AI_MONTHLY_REQUEST_LIMIT_PRO (default 1200)

Planos de Produto (Free / Plus / Pro) e AI Metering

Proposta de segmentação alinhada ao objetivo do app:

• free (ou bronze)
  • contas (cash/cc), categorias, transações
  • AI básica: insights e chat com limite reduzido
  • sem tela de investimentos
• plus (ou prata)
  • tudo do free
  • acesso a investimentos
  • AI moderada (insights + chat + análises padrão)
• pro (ou gold)
  • tudo do plus
  • modo "CFO pessoal"
  • AI avançada com previsões, planejamento e relatórios customizados

Add-ons (sob demanda):

• pacote extra de créditos AI
• relatório AI customizado avulso
• recursos "pro" avulsos (upgrade temporário)

Limites sugeridos de AI por plano (fase inicial)

Para controlar custo sem degradar UX:

• free: ~60 requests AI/mês
• plus: ~300 requests AI/mês
• pro: ~1200 requests AI/mês

Endpoints considerados para metering/quota:

• GET /api/ai/insights
• POST /api/ai/chat
• POST /api/ai/simulate
• POST /api/ai/plan/monthly
• POST /api/ai/notifications/generate

Status de implementação no serviço

Implementado agora:

• metering por request em ai_usage_events
• summary mensal via GET /api/ai/usage/summary
• quota enforcement por usuário/plano (free/plus/pro):
  • AI_QUOTA_ENFORCEMENT_ENABLED
  • AI_MONTHLY_REQUEST_LIMIT_FREE
  • AI_MONTHLY_REQUEST_LIMIT_PLUS
  • AI_MONTHLY_REQUEST_LIMIT_PRO
  • AI_MONTHLY_REQUEST_LIMIT (fallback)
• base de overage pronta no ecossistema:
  • saldo de créditos por usuário
  • ledger de créditos
  • endpoints admin no backend-core para ajuste/consulta

Resposta do GET /api/ai/usage/summary agora inclui:

• quota.plan
• quota.monthly_request_limit (limite efetivo do usuário)
• quota.plan_limits (tabela de limites por plano)
• quota.metered_requests
• quota.remaining_requests

Próximo passo para monetização completa:

• manter limite por plano e evoluir para entitlements granulares no backend-core
• expor add-ons de crédito AI sobre o limite base do plano
• habilitar overage via add-on (créditos extras)

Exemplo de estratégia de ativação (rollout seguro)

1. Ativar quota enforcement com limite global conservador (ex.: 500) para validar comportamento.
2. Introduzir entitlements por plano no backend-core.
3. Migrar para limite por plano mantendo logs e dashboard de uso.
4. Ativar add-ons somente após estabilizar custo real por coorte.

Local Run

From monorepo root:

pip install -r personal-finance-backend-ai-insights/requirements.txt
uvicorn personal-finance-backend-ai-insights.app.main:app --reload --app-dir .

Deploy

• Build/push image with dockerbuild.sh or monorepo podman-build.sh.
• Helm chart: helm/
• Argo CD application: argocd-application.yaml

Cluster target URL (default):

http://personal-finance-backend-ai-insights.app.svc.cluster.local:8000

Scheduler (independente de sessão de usuário)

O chart Helm inclui dois CronJobs (habilitados por padrão em prod-values.yaml):

• notifications-generate: chama POST /api/ai/notifications/scheduler/generate
• notifications-deliver: chama POST /api/ai/notifications/scheduler/deliver

Com isso:

1. A geração de notificações roda sem usuário logado.
2. Geração e entrega ficam separadas.
3. Estado de entrega fica persistido em ai_notification_deliveries.

Configuração no Helm (scheduler.*):

• scheduler.enabled
• scheduler.generateSchedule
• scheduler.deliverSchedule
• scheduler.tokenSecretName
• scheduler.tokenSecretKey

Integração com backend-core

No backend-core, o proxy /api/ai/* chama este serviço via:

• AI_INSIGHTS_SERVICE_URL (env var)

Default esperado no cluster:

http://personal-finance-backend-ai-insights.app.svc.cluster.local:8000

Recommended Next Steps

1. Add unit tests for scoring/dedupe/window generation rules.
2. Add timezone-aware user delivery windows.
3. Add email/push channels on top of current in_app delivery pipeline (without changing in-app daily dedupe).
4. Add LLM orchestration layer using these deterministic endpoints as tools.