npm package: @marcos_feitoza/personal-finance-backend-ai-insights
Description: Financial intelligence service in the Personal Finance ecosystem.
Latest version: 1.1.2

# 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:

```bash
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 `CronJob`s (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.