finance-agent

This project is an intelligent financial analysis Agent. The core idea is to let the large language model (DeepSeek) autonomously decide the analysis steps through tool calling (Function Calling), ultimately outputting a structured financial analysis report with supporting evidence. Architecturally, the main loop is located in app/agent/loop.py: the system prompt and tool set are sent together to DeepSeek's chat(tools) interface. After the model returns tool_calls, dispatch executes the corresponding tools, and the results are fed back as tool messages, continuing the iteration until an answer is reached. The tool set includes four types of capabilities: - query_db(sql): Executes read-only SQL queries against the SQLite financial database, allowing only SELECT / WITH / PRAGMA, with writes prohibited. - calc_financial_model(model, ...): Calculates financial indicators such as gross margin, net margin, current ratio, quick ratio, debt-to-asset ratio, ROE, ROA, turnover ratios, WACC, DCF, IRR, and expected credit loss. It is a pure Python implementation with standard formulas that can be unit tested. - rag_search(q): A lightweight TF-IDF-based retrieval covering accounting standards, auditing, valuation, and machine learning/NLP knowledge. The corpus is stored in app/knowledge/corpus.json and does not depend on a vector database. - run_python(code): Runs financial calculation scripts in a subprocess with timeout and output truncation. The service layer uses FastAPI, providing endpoints such as GET / (web interface), POST /api/agent/analyze, GET /api/rag/search, GET /tools, and GET /health. web/index.html provides a browser interface where users can enter questions and view the analysis report and the tool_trace call process. The project also includes a Dockerfile, a GitHub Actions CI workflow, and pytest tests. The quick start process is: install dependencies from requirements-dev.txt, copy .env.example to .env and fill in the DeepSeek API Key, run the script to generate a sample financial database, and then start the service with uvicorn. The README provides curl examples for health checks, tool listing, RAG retrieval, and financial analysis requests. In terms of engineering standards, the project emphasizes mandatory read-only database queries, subprocess isolation and timeout for code execution, structured tool_trace logging that records the name, parameters, results, and duration of each tool call, as well as containerized deployment and CI automated testing. The project is positioned as a practical project in the direction of financial informatization and AI Agent for job-seeking demonstration.