finance-agent

Este projeto é um Agente inteligente de análise financeira cujo princípio central é permitir que um modelo de linguagem de grande porte (DeepSeek), por meio de chamadas de ferramentas (Function Calling), decida autonomamente as etapas da análise e produza ao final um relatório estruturado de análise financeira com fundamentação. Arquiteturalmente, o loop principal está em app/agent/loop.py: o prompt de sistema e o conjunto de ferramentas são enviados juntos à interface chat(tools) do DeepSeek; após o modelo retornar tool_calls, o dispatch executa a ferramenta correspondente, e o resultado é reinserido como mensagem tool, iterando até se chegar à resposta. O conjunto de ferramentas inclui quatro tipos de capacidades: - query_db(sql): executa consultas SQL somente leitura no banco financeiro SQLite, permitindo apenas SELECT / WITH / PRAGMA e proibindo escritas. - calc_financial_model(model, ...): calcula indicadores financeiros como margem bruta, margem líquida, índice de liquidez corrente, índice de liquidez seca, índice de endividamento, ROE, ROA, índices de rotatividade, WACC, DCF, IRR, perda esperada de crédito, entre outros; implementação puramente em Python, com fórmulas padronizadas e testáveis por unidade. - rag_search(q): recuperação leve baseada em TF-IDF, cobrindo normas contábeis, auditoria, avaliação e conhecimentos de machine learning/NLP; o corpus fica em app/knowledge/corpus.json e não depende de banco de dados vetorial. - run_python(code): executa scripts de cálculo financeiro como subprocesso, com timeout e truncamento de saída. A camada de serviço usa FastAPI e oferece interfaces como GET / (interface web), POST /api/agent/analyze, GET /api/rag/search, GET /tools, GET /health. O web/index.html fornece uma interface no navegador; após inserir a pergunta, é possível exibir o relatório de análise e o processo de chamadas tool_trace. O projeto também inclui Dockerfile, fluxo de trabalho CI do GitHub Actions e testes pytest. O fluxo de início rápido é: instalar as dependências de requirements-dev.txt, copiar .env.example para .env e preencher a DeepSeek API Key, executar o script para gerar o banco financeiro de exemplo e iniciar o serviço com uvicorn. O README apresenta exemplos curl para verificação de saúde, lista de ferramentas, busca RAG e requisição de análise financeira. Em termos de normas de engenharia, destaca-se a obrigatoriedade de consultas somente leitura ao banco de dados, isolamento de execução de código em subprocesso com timeout, registro estruturado em tool_trace do nome, parâmetros, resultado e tempo de cada chamada de ferramenta, além de implantação em contêiner e testes automatizados em CI. O projeto posiciona-se como um projeto prático nas direções de informatização financeira e AI Agent, voltado à apresentação em candidaturas de emprego.