# sureshpaulraj/financial-reasoning architecture

> Architecture diagram of the GitHub repository sureshpaulraj/financial-reasoning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sureshpaulraj/financial-reasoning
- Repository: https://github.com/sureshpaulraj/financial-reasoning

## Overview

##### Project type and purpose
- This is a Python-based data-processing CLI/tool (also runnable as a Jupyter notebook) that ingests financial PDF reports, extracts and formats their text, sends that content to Azure OpenAI’s o3 reasoning model for analysis, and then generates both a plain-text and HTML financial report. It can also email the generated reports.

##### File structure
- Top-level files:
- `.env` – stores Azure OpenAI credentials
- `requirements.txt` – Python dependencies
- `FinancialAnalysisFromPDF.ipynb` – orchestration notebook / main driver
- `pdfs/` – input folder for raw PDF files
- `formatted_financial_report.txt` & `financial_report.html` – output artifacts
- No separate `src/` or service folders; the notebook/script encapsulates all pipeline stages.
- Key libraries shown in dependencies: PyPDF2, PyMuPDF, python-dotenv, openai (Azure), requests, tiktoken, pydantic.

##### README for additional insights
- Pipeline stages are clearly described:
1. PDF text extraction (page-by-page)
2. Markdown formatting
3. Azure OpenAI API call (o3 reasoning model)
4. Formatting and report generation (text + HTML)
5. Optional email distribution

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Orchestrator
    Config[".env"]:::local
    Requirements["requirements.txt"]:::grey
    README["README.md"]:::grey
    Notebook["Orchestrator\n(FinancialAnalysisFromPDF.ipynb)"]:::grey

    %% Data Ingestion Layer
    subgraph "Data Ingestion"
        PDFs["pdfs/"]:::local
    end

    %% Processing Layer
    subgraph "Processing"
        PDFProc["PDF Processor"]:::green
        Formatter["Formatter"]:::green
        ReportGen["Report Generator"]:::green
    end

    %% External Integration Layer
    subgraph "External Integration"
        APIClient["API Client"]:::green
        EmailSender["Email Sender"]:::green
        Azure["Azure OpenAI"]:::orange
        EmailService["Email Service"]:::orange
    end

    %% Output & Distribution Layer
    subgraph "Output & Distribution"
        TxtOut["formatted_financial_report.txt"]:::local
        HTMLOut["financial_report.html"]:::local
    end

    %% Data Flow
    Notebook -->|orchestrates| Config
    Notebook -->|orchestrates| Requirements
    Notebook -->|orchestrates| README
    Notebook -->|orchestrates| PDFs
    PDFs -->|raw PDF files| PDFProc
    PDFProc -->|raw text| Formatter
    Formatter -->|Markdown payload| APIClient
    Config -->|credentials| APIClient
    APIClient -->|HTTP REST| Azure
    Azure -->|analysis response| APIClient
    APIClient -->|JSON/text| ReportGen
    ReportGen -->|plain text| TxtOut
    ReportGen -->|HTML| HTMLOut
    TxtOut -->|report files| EmailSender
    HTMLOut -->|report files| EmailSender
    Config -->|credentials| EmailSender
    EmailSender -->|SMTP/REST| EmailService

    %% Click Events
    click Config "https://github.com/sureshpaulraj/financial-reasoning/blob/main/.env"
    click PDFs "https://github.com/sureshpaulraj/financial-reasoning/tree/main/pdfs/"
    click Notebook "https://github.com/sureshpaulraj/financial-reasoning/blob/main/FinancialAnalysisFromPDF.ipynb"
    click Requirements "https://github.com/sureshpaulraj/financial-reasoning/blob/main/requirements.txt"
    click TxtOut "https://github.com/sureshpaulraj/financial-reasoning/blob/main/formatted_financial_report.txt"
    click HTMLOut "https://github.com/sureshpaulraj/financial-reasoning/blob/main/financial_report.html"
    click README "https://github.com/sureshpaulraj/financial-reasoning/blob/main/README.md"

    %% Styles
    classDef local fill:#E3F2FD,stroke:#42A5F5,stroke-width:2px;
    classDef green fill:#E8F5E9,stroke:#66BB6A,stroke-width:2px;
    classDef orange fill:#FFF3E0,stroke:#FFA726,stroke-width:2px;
    classDef grey fill:#EEEEEE,stroke:#BDBDBD,stroke-width:2px;
```
