{"id":31832116,"url":"https://github.com/codestrate/financial-document-analyser-agent","last_synced_at":"2025-10-11T22:29:46.985Z","repository":{"id":315464481,"uuid":"1059432745","full_name":"CodeStrate/financial-document-analyser-agent","owner":"CodeStrate","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-18T17:53:12.000Z","size":8656,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-18T20:21:37.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodeStrate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-18T12:43:51.000Z","updated_at":"2025-09-18T17:53:16.000Z","dependencies_parsed_at":"2025-09-18T20:37:08.387Z","dependency_job_id":null,"html_url":"https://github.com/CodeStrate/financial-document-analyser-agent","commit_stats":null,"previous_names":["codestrate/financial-document-analyser-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/CodeStrate/financial-document-analyser-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeStrate%2Ffinancial-document-analyser-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeStrate%2Ffinancial-document-analyser-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeStrate%2Ffinancial-document-analyser-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeStrate%2Ffinancial-document-analyser-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeStrate","download_url":"https://codeload.github.com/CodeStrate/financial-document-analyser-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeStrate%2Ffinancial-document-analyser-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279009071,"owners_count":26084549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T22:29:42.921Z","updated_at":"2025-10-11T22:29:46.978Z","avatar_url":"https://github.com/CodeStrate.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Financial Document Analyzer Agent - Base App Debugged\n\n[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n\nThis project is an AI-powered system that analyzes financial documents (such as quarterly earnings reports) to provide a comprehensive summary, investment advice, and a risk assessment. It uses **CrewAI** to orchestrate a team of specialized AI agents and a **FastAPI** server for interaction.\n\nThis repository is the improved and stable version of the base assignment codebase, with bugs fixed and prompts refined without bonus features.\n\n---\n\n## Table of Contents\n\n1. [Key Features](#key-features)\n2. [Bugs Squashed](#bugs-squashed)\n3. [Technology Stack](#technology-stack)\n4. [Setup and Installation](#setup-and-installation)\n5. [Usage](#usage)\n6. [API Reference](#api-reference)\n\n---\n\n## Key Features\n\n* **AI Agent Orchestration**: CrewAI manages specialized agents for document analysis, investment advice, and risk assessment.\n* **Robust PDF Parsing**: Custom CrewAI tool for extracting text from PDF documents.\n* **RESTful API**: FastAPI-based interface for document submission and result retrieval.\n\n---\n\n## Bugs Squashed\n\nDuring development, several issues were identified and fixed:\n\n* **Dependency Conflicts**: `requirements.txt` had too many versioning issues especially with `opentelemetry`, `google` packages and `onnxruntime`\n    - Fix: Made sure to use appropriate package versions w.r.t. `crewai==1.30.0`.\n* **Broken Custom Tools**: Fixed PDF parsing tool by properly inheriting from `crewai.tools.BaseTool` for proper format, implementing `_run` method for tool execution and integrating `PyPDFium2Loader` from `langchain-community`. As well as fixed `SerperDevTool` import (was `serper_dev_tool`)\n* **LLM Initialization**: Corrected agent LLM initialization (llm=llm) with `LLM` class from `crewai` (so we can easily switch AI providers as well as models) and environment variable configuration. Also tools were passed incorrectly to the agents, that was fixed. (was `tools=` not `tool=`)\n* **Crew Running Problems**: `run_crew` in `main` was not passing all agents and tasks in the workflow also it didn't get file_path in `kickoff()`. Fixed by adding them.\n\n### Inefficient Prompting Fixes and Removal of Redundant Code\n* **Problem 1** : The Agents' role, backstory and goals were sarcastic jokes or satire at worst. It lead to hallucination at best and undesirable output at worst.\n  - Fix : The role, goals and backstory were properly defined to position each agent as a serious professional. So now each Agent carries a persona or a character it plays that leads to quality output.\n\n* **Problem 2** : The tasks were also poorly written, like hyperbolic jokes with no clear directive, the task assignment also needed fixing, as it was wrong. Also no context sharing between agents so no agent had knowledge towards its task from the previous.\n  - Fix : Defined structured tasks with a clear output format in mind while passing the output from one task to the next. eg. `financial_analysis_task` forms the context for `investment_analysis_task` and the both tasks formed the context for the `risk_assessment_task` for the best response.\n \n* **Redundant Code Removed** : `Verifier` Agent and its subsequent task was removed from the codebase as it wasn't influencing the Agent's response and it's objective was already fulfilled by the `financial_analyst` Agent and task. It wasn't logically to add this overhead which might have caused confusion for the LLM. Also tools for `investment_analysis` and `risk_assessment` were also removed since they weren't doing anything extra that the Agents could not on their own reasoning and supplied WebSearch tools.\n\n---\n\n## Technology Stack\n\n* **AI Framework**: [CrewAI](https://www.crewai.com/)\n* **LLM**: OpenAI GPT-4o (or any compatible model)\n* **Web Framework**: [FastAPI](https://fastapi.tiangolo.com/)\n* **PDF Parsing**: [PyPDFium2](https://pypdfium2.readthedocs.io/en/stable/)\n\n---\n\n## Setup and Installation\n\n### Prerequisites\n\n* Python 3.13+\n* Git\n* OpenAI API Key\n\n---\n\n### Steps\n\n1. Clone the repository:\n\n   ```powershell\n   git clone https://github.com/CodeStrate/financial-document-analyser-agent.git\n   cd financial-document-analyser-agent\n   ```\n\n2. Create and activate a virtual environment:\n\n   ```powershell\n   python -m venv venv\n   .\\venv\\Scripts\\activate\n   ```\n\n   or in Linux\n   ```bash\n   python3.13 -m venv venv\n   source venv/bin/activate\n   ```\n\n3. Install dependencies:\n\n   ```powershell\n   pip install -r requirements.txt\n   ```\n\n4. Configure environment variables:\n   ```env\n   OPENAI_API_KEY=\"sk-...\"\n   SERPER_API_KEY=\"a20...\"\n   ```\n\n5. Run the FastAPI server:\n\n   ```powershell\n   python main.py\n   ```\n\n---\n\n## Usage\n\nSubmit a document and check results through the API.\n\n### 1. Submit a document for analysis\n\n```bash\nhttp POST http://localhost:8000/analyze file@data/quarterly_report.pdf query=\"Provide a detailed analysis, recommendation, and risk assessment.\"\n```\n\n---\n\n## API Reference\n\n### `POST /analyze`\n\nUploads a financial document and starts analysis.\n\n**Request Body**:\n\n* `file` (file) – required, PDF file\n* `query` (string) – optional\n\n**Response**:\n\n```json\n{\n      \"status\": \"success\",\n      \"query\": \"User query\",\n      \"analysis\": \"Agent response\",\n      \"file_processed\": \"file_name\"\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodestrate%2Ffinancial-document-analyser-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodestrate%2Ffinancial-document-analyser-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodestrate%2Ffinancial-document-analyser-agent/lists"}