# pranabesh14/esg_report_analyser architecture

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

- Interactive diagram: https://gitdiagram.com/pranabesh14/esg_report_analyser
- Repository: https://github.com/pranabesh14/esg_report_analyser

## Overview

This is a CLI/Python API multimodal PDF knowledge base. Users ingest year-tagged PDFs, then query for cited answers: parsing and chart extraction create units, entity resolution and relationship extraction connect cross-page content, and hybrid retrieval expands vector/BM25 matches through those links before evidence aggregation and answer generation. The README documents capability stages whose orchestration details are not fully shown in excerpts; those links are included only where the README or sampled caller supports them. Sampled storage is SQLite/Postgres relational data plus FAISS and BM25.

Main entry points: [`pipeline.py`](https://github.com/pranabesh14/esg_report_analyser/blob/main/pipeline.py) (Pipeline orchestrator), [`core/llm_provider.py`](https://github.com/pranabesh14/esg_report_analyser/blob/main/core/llm_provider.py) (LLM provider factory), [`retrieval/hybrid_retriever.py`](https://github.com/pranabesh14/esg_report_analyser/blob/main/retrieval/hybrid_retriever.py) (Hybrid graph retrieval), [`ingestion/vision_extractor.py`](https://github.com/pranabesh14/esg_report_analyser/blob/main/ingestion/vision_extractor.py) (Chart extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_pdf["PDF layout parser<br/>[pdf_parser.py]"]
  node_vision["Chart extraction"]
end

subgraph group_knowledge["Entity knowledge"]
  node_entity_extract["Mention extraction<br/>[extraction.py]"]
  node_resolution["Canonical resolution<br/>[resolution.py]"]
  node_relations["Relationship extraction<br/>[extraction.py]"]
  node_summary["Context summarization"]
end

subgraph group_stores["Persistence"]
  node_rel_store[("Relational store")]
  node_vector_store[("Dual vector index<br/>[vector_store.py]")]
  node_bm25_store[("BM25 index<br/>[bm25_store.py]")]
end

subgraph group_query["Retrieval and answers"]
  node_retriever["Hybrid graph retrieval"]
  node_aggregator["Evidence aggregation"]
  node_generator["Cited answer generation"]
end

subgraph group_platform["Shared services"]
  node_pipeline["Pipeline orchestrator<br/>[pipeline.py]"]
  node_schemas["Shared data schemas<br/>[schemas.py]"]
  node_settings["Runtime configuration<br/>[settings.py]"]
  node_llm["LLM provider factory<br/>[llm_provider.py]"]
end

node_user(("CLI/API user"))
node_cli["CLI<br/>[cli.py]"]
node_llm_services["Anthropic / Azure OpenAI"]

node_user -->|"runs commands"| node_cli
node_user -->|"calls API"| node_pipeline
node_cli -->|"invokes"| node_pipeline
node_pipeline -->|"parses PDFs"| node_pdf
node_pipeline -->|"processes images"| node_vision
node_pdf -->|"yields images"| node_vision
node_pipeline -->|"extracts mentions"| node_entity_extract
node_pipeline -->|"resolves mentions"| node_resolution
node_pipeline -->|"extracts links"| node_relations
node_pipeline -->|"summarizes units"| node_summary
node_resolution -->|"embeds, disambiguates"| node_llm
node_vision -->|"extracts chart data"| node_llm
node_relations -->|"infers relations"| node_llm
node_summary -->|"creates context"| node_llm
node_pipeline -->|"loads and saves"| node_rel_store
node_pipeline -->|"indexes embeddings"| node_vector_store
node_pipeline -->|"indexes text"| node_bm25_store
node_pipeline -->|"embeds units"| node_llm
node_retriever -->|"embeds query"| node_llm
node_retriever -->|"searches vectors"| node_vector_store
node_retriever -->|"searches terms"| node_bm25_store
node_retriever -->|"loads seeds, expands graph"| node_rel_store
node_pipeline -.->|"retrieves evidence"| node_retriever
node_pipeline -.->|"aggregates evidence"| node_aggregator
node_pipeline -.->|"generates answer"| node_generator
node_aggregator -->|"provides evidence"| node_generator
node_generator -->|"writes answer"| node_llm
node_llm -->|"dispatches provider calls"| node_llm_services
node_settings -->|"configures runtime"| node_pipeline
node_schemas -->|"models pipeline data"| node_pipeline

click node_cli "https://github.com/pranabesh14/esg_report_analyser/blob/main/cli.py"
click node_pipeline "https://github.com/pranabesh14/esg_report_analyser/blob/main/pipeline.py"
click node_pdf "https://github.com/pranabesh14/esg_report_analyser/blob/main/ingestion/pdf_parser.py"
click node_vision "https://github.com/pranabesh14/esg_report_analyser/blob/main/ingestion/vision_extractor.py"
click node_entity_extract "https://github.com/pranabesh14/esg_report_analyser/blob/main/entities/extraction.py"
click node_resolution "https://github.com/pranabesh14/esg_report_analyser/blob/main/entities/resolution.py"
click node_relations "https://github.com/pranabesh14/esg_report_analyser/blob/main/relationships/extraction.py"
click node_summary "https://github.com/pranabesh14/esg_report_analyser/blob/main/entities/contextual_summarizer.py"
click node_rel_store "https://github.com/pranabesh14/esg_report_analyser/blob/main/storage/relational_store.py"
click node_vector_store "https://github.com/pranabesh14/esg_report_analyser/blob/main/storage/vector_store.py"
click node_bm25_store "https://github.com/pranabesh14/esg_report_analyser/blob/main/storage/bm25_store.py"
click node_retriever "https://github.com/pranabesh14/esg_report_analyser/blob/main/retrieval/hybrid_retriever.py"
click node_aggregator "https://github.com/pranabesh14/esg_report_analyser/blob/main/retrieval/evidence_aggregator.py"
click node_generator "https://github.com/pranabesh14/esg_report_analyser/blob/main/generation/answer_generator.py"
click node_schemas "https://github.com/pranabesh14/esg_report_analyser/blob/main/core/schemas.py"
click node_settings "https://github.com/pranabesh14/esg_report_analyser/blob/main/config/settings.py"
click node_llm "https://github.com/pranabesh14/esg_report_analyser/blob/main/core/llm_provider.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pdf,node_vision,node_user toneBlue
class node_entity_extract,node_resolution,node_relations,node_summary toneAmber
class node_rel_store,node_vector_store,node_bm25_store toneMint
class node_retriever,node_aggregator,node_generator toneRose
class node_pipeline,node_schemas,node_settings,node_llm,node_llm_services toneIndigo
class node_cli toneTeal
```

## Components

### Document ingestion

- [PDF layout parser](https://github.com/pranabesh14/esg_report_analyser/blob/main/ingestion/pdf_parser.py): `ingestion/pdf_parser.py`
- [Chart extraction](https://github.com/pranabesh14/esg_report_analyser/blob/main/ingestion/vision_extractor.py): `ingestion/vision_extractor.py`

### Entity knowledge

- [Mention extraction](https://github.com/pranabesh14/esg_report_analyser/blob/main/entities/extraction.py): `entities/extraction.py`
- [Canonical resolution](https://github.com/pranabesh14/esg_report_analyser/blob/main/entities/resolution.py): `entities/resolution.py`
- [Relationship extraction](https://github.com/pranabesh14/esg_report_analyser/blob/main/relationships/extraction.py): `relationships/extraction.py`
- [Context summarization](https://github.com/pranabesh14/esg_report_analyser/blob/main/entities/contextual_summarizer.py): `entities/contextual_summarizer.py`

### Persistence

- [Relational store](https://github.com/pranabesh14/esg_report_analyser/blob/main/storage/relational_store.py): `storage/relational_store.py`
- [Dual vector index](https://github.com/pranabesh14/esg_report_analyser/blob/main/storage/vector_store.py): `storage/vector_store.py`
- [BM25 index](https://github.com/pranabesh14/esg_report_analyser/blob/main/storage/bm25_store.py): `storage/bm25_store.py`

### Retrieval and answers

- [Hybrid graph retrieval](https://github.com/pranabesh14/esg_report_analyser/blob/main/retrieval/hybrid_retriever.py): `retrieval/hybrid_retriever.py`
- [Evidence aggregation](https://github.com/pranabesh14/esg_report_analyser/blob/main/retrieval/evidence_aggregator.py): `retrieval/evidence_aggregator.py`
- [Cited answer generation](https://github.com/pranabesh14/esg_report_analyser/blob/main/generation/answer_generator.py): `generation/answer_generator.py`

### Shared services

- [Pipeline orchestrator](https://github.com/pranabesh14/esg_report_analyser/blob/main/pipeline.py): `pipeline.py`
- [Shared data schemas](https://github.com/pranabesh14/esg_report_analyser/blob/main/core/schemas.py): `core/schemas.py`
- [Runtime configuration](https://github.com/pranabesh14/esg_report_analyser/blob/main/config/settings.py): `config/settings.py`
- [LLM provider factory](https://github.com/pranabesh14/esg_report_analyser/blob/main/core/llm_provider.py): `core/llm_provider.py`

### Other components

- **CLI/API user**
- [CLI](https://github.com/pranabesh14/esg_report_analyser/blob/main/cli.py): `cli.py`
- **Anthropic / Azure OpenAI**

## Connections

- CLI/API user → CLI: runs commands (evidence: `README.md`)
- CLI/API user → Pipeline orchestrator: calls API (evidence: `README.md`)
- CLI → Pipeline orchestrator: invokes (evidence: `README.md`)
- Pipeline orchestrator → PDF layout parser: parses PDFs (evidence: `pipeline.py`)
- Pipeline orchestrator → Chart extraction: processes images (evidence: `pipeline.py`)
- PDF layout parser → Chart extraction: yields images (evidence: `ingestion/vision_extractor.py`)
- Pipeline orchestrator → Mention extraction: extracts mentions (evidence: `README.md`)
- Pipeline orchestrator → Canonical resolution: resolves mentions (evidence: `pipeline.py`)
- Pipeline orchestrator → Relationship extraction: extracts links (evidence: `pipeline.py`)
- Pipeline orchestrator → Context summarization: summarizes units (evidence: `pipeline.py`)
- Canonical resolution → LLM provider factory: embeds, disambiguates (evidence: `entities/resolution.py`)
- Chart extraction → LLM provider factory: extracts chart data (evidence: `ingestion/vision_extractor.py`)
- Relationship extraction → LLM provider factory: infers relations (evidence: `relationships/extraction.py`)
- Context summarization → LLM provider factory: creates context (evidence: `entities/contextual_summarizer.py`)
- Pipeline orchestrator → Relational store: loads and saves (evidence: `pipeline.py`)
- Pipeline orchestrator → Dual vector index: indexes embeddings (evidence: `pipeline.py`)
- Pipeline orchestrator → BM25 index: indexes text (evidence: `pipeline.py`)
- Pipeline orchestrator → LLM provider factory: embeds units (evidence: `pipeline.py`)
- Hybrid graph retrieval → LLM provider factory: embeds query (evidence: `retrieval/hybrid_retriever.py`)
- Hybrid graph retrieval → Dual vector index: searches vectors (evidence: `retrieval/hybrid_retriever.py`)
- Hybrid graph retrieval → BM25 index: searches terms (evidence: `retrieval/hybrid_retriever.py`)
- Hybrid graph retrieval → Relational store: loads seeds, expands graph (evidence: `retrieval/hybrid_retriever.py`)
- Pipeline orchestrator → Hybrid graph retrieval: retrieves evidence (evidence: `README.md`)
- Pipeline orchestrator → Evidence aggregation: aggregates evidence (evidence: `README.md`)
- Pipeline orchestrator → Cited answer generation: generates answer (evidence: `README.md`)
- Evidence aggregation → Cited answer generation: provides evidence (evidence: `generation/answer_generator.py`)
- Cited answer generation → LLM provider factory: writes answer (evidence: `generation/answer_generator.py`)
- LLM provider factory → Anthropic / Azure OpenAI: dispatches provider calls (evidence: `core/llm_provider.py`)
- Runtime configuration → Pipeline orchestrator: configures runtime (evidence: `pipeline.py`)
- Shared data schemas → Pipeline orchestrator: models pipeline data (evidence: `README.md`)
