# Finance App Agent API

API independente para operar a API principal do Finance App usando um modelo local do Ollama e um sistema de tools semelhante a Function Calling.

## Arquitetura

- `src/config`: variaveis de ambiente e logger.
- `src/controllers`: entrada HTTP.
- `src/routes`: rotas Express.
- `src/services/ai`: comunicacao com Ollama e orquestracao do agente.
- `src/services/api`: cliente HTTP unico para a API principal.
- `src/tools`: registry e definicoes das tools.
- `src/prompts`: prompts de planejamento e resposta final.
- `src/middlewares`: autenticacao, 404 e erros.
- `src/docs`: documento OpenAPI.

## Instalar

```bash
npm install
```

## Configurar

Copie `.env.example` para `.env` e ajuste:

```env
PORT=3080
OLLAMA_URL=http://localhost:11434/api/chat
OLLAMA_MODEL=llama3.2:1b
OLLAMA_TIMEOUT_MS=180000
FINANCE_API_URL=http://localhost
LOG_LEVEL=info
```

`FINANCE_API_URL` deve apontar para o backend PHP do Finance App. As credenciais do usuario nao ficam no `.env`: cada requisicao ao agente deve enviar Basic Auth com email e senha do usuario do Finance App. O agente valida essas credenciais em `/login` antes de executar qualquer tool.

## Iniciar

Desenvolvimento:

```bash
npm run dev
```

Producao:

```bash
npm run build
npm start
```

A aplicacao roda por padrao em `http://localhost:3080`.

## Autenticacao

Todas as rotas exigem Basic Auth de um usuario valido do Finance App:

```http
Authorization: Basic base64(email:senha)
```

Depois de autenticar, todas as operacoes usam exclusivamente o usuario autenticado. O agente ignora qualquer `id_usuario` ou `usuario` enviado no prompt ou no `context`.

## Endpoints

- `GET /health`: status da Agent API.
- `POST /api/agent/chat`: conversa com o agente.
- `GET /api/tools`: lista tools cadastradas.
- `GET /docs`: Swagger UI.
- `GET /openapi.json`: documento OpenAPI.

## Exemplo de requisicao

```http
POST /api/agent/chat
Authorization: Basic base64(usuario@email.com:senha)
Content-Type: application/json
```

```json
{
  "message": "Liste as despesas pendentes de julho de 2026"
}
```

## Exemplo de resposta

```json
{
  "answer": "Encontrei as despesas pendentes do periodo...",
  "toolCalls": [
    {
      "name": "listBills",
      "arguments": {
        "filter": {
          "tipo": "D",
          "status": "PE",
          "vencimento": {
            "BETWEEN": ["2026-07-01", "2026-07-31"]
          }
        }
      }
    }
  ],
  "toolResults": []
}
```

## Como alterar o modelo do Ollama

Altere `OLLAMA_MODEL` no `.env`, por exemplo:

```env
OLLAMA_MODEL=llama3.2:3b
```

Se o modelo local demorar para carregar ou responder prompts maiores, aumente `OLLAMA_TIMEOUT_MS`.

Toda comunicacao com o provedor fica centralizada em `src/services/ai/OllamaClient.ts`. Para trocar de provedor no futuro, crie outro client com o mesmo contrato usado por `AgentService`.

## Como adicionar novas tools

1. Adicione a definicao em `src/tools/financeTools.ts`.
2. Defina `name`, `description`, schema Zod em `parameters`, `parametersDescription` e `execute`.
3. Use `FinanceApiClient` para chamar a API principal.
4. Rode `npm run build`.

Exemplo:

```ts
{
  name: 'myTool',
  description: 'Executa uma operacao do Finance App.',
  parameters: z.object({ status: z.enum(['PE', 'PA']).optional() }),
  parametersDescription: { status: 'Filtro opcional.' },
  execute: (input, context) =>
    financeApi.post('/private/recurso/listar', {
      filter: {
        ...input,
        id_usuario: context.user.id
      }
    }, { basicAuth: context.basicAuth })
}
```

## Como conectar novas APIs

Crie um novo client em `src/services/api`, injete a dependencia na tool e mantenha validacao de parametros com Zod. Nao coloque regra de negocio no agente; regra deve permanecer no sistema responsavel pela API.

## Fluxo completo

1. A rota `/api/agent/chat` recebe a mensagem.
2. O `AgentService` monta o prompt com as tools disponiveis.
3. O `OllamaClient` envia a conversa ao Ollama.
4. O modelo retorna JSON com `toolCalls` ou uma resposta final.
5. O `ToolRegistry` valida argumentos com Zod e executa as tools.
6. Os resultados voltam para o modelo.
7. O modelo gera a resposta final baseada apenas nos resultados.

## Escopo e seguranca

O agente e restrito ao sistema financeiro. Quando a solicitacao estiver fora do dominio financeiro da aplicacao, ele retorna a mensagem padrao de recusa definida em `src/prompts/systemPrompt.ts`.

O agente nao navega na internet, nao consulta servicos externos fora do Ollama e da API principal, nao inventa informacoes e nao executa acoes fora das tools cadastradas.

O agente tambem nao aceita identidade de usuario por prompt. O usuario e definido apenas pela autenticacao Basic Auth da requisicao. Para listagens, criacoes, resumos, saldos e analises, o agente injeta o usuario autenticado. Para atualizar, pagar ou excluir registros por ID, a tool primeiro confirma na API financeira que o registro pertence ao usuario autenticado.

## Logs

Logs incluem:

- prompt enviado ao modelo;
- tool escolhida;
- chamadas para a API principal;
- tempo de execucao;
- erros;
- resposta final.

Use `LOG_LEVEL=debug|info|warn|error` para ajustar verbosidade.

## Manutencao futura

- Prefira novas tools pequenas e explicitas.
- Mantenha schemas Zod proximos dos contratos reais do backend.
- Evite duplicar regras de negocio do PHP.
- Atualize `docs/backend-ia.md` ou a tool correspondente sempre que novos endpoints forem publicados.
- Rode `npm run build` antes de publicar.