# abhiramk6/research-paper-analyze architecture

> Architecture diagram of the GitHub repository abhiramk6/research-paper-analyze, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhiramk6/research-paper-analyze
- Repository: https://github.com/abhiramk6/research-paper-analyze

## Overview

1. **Overall architecture**
   This is a LangGraph-orchestrated document-evaluation pipeline for research papers. The system takes either an arXiv URL or a local PDF, turns the paper into structured text, extracts checkable claims, retrieves external evidence, runs several grounded evaluators, and writes a Markdown report.

2. **Entry points**
   `app.py` is the interactive Streamlit front end for submitting a paper and downloading results. `pipeline.py` is the core orchestration layer and defines the active evaluation flow: input → ingest → extract_claims → retrieve_evidence → evaluate_consistency → evaluate_grammar → evaluate_novelty → evaluate_fabrication → build_report.

3. **Ingestion and parsing boundary**
   `ingestion/downloader.py` handles paper acquisition from arXiv or local file paths. `parser/pdf_parser.py` converts PDFs into a lightweight textual structure suitable for downstream processing. This boundary isolates raw document handling from the LLM-driven analysis stages.

4. **Context management and chunking**
   `chunker/token_chunker.py` creates rolling token windows with overlap to stay under the model’s context limit. This is important because the system is designed around bounded, traceable LLM calls rather than passing the whole paper at once.

5. **Claim extraction subsystem**
   `claims/claim_extractor.py` converts paper text into a reduced taxonomy of operational claims: contribution, result, comparison, factual, and method. This is the main semantic pivot in the pipeline: downstream evaluation operates on claims, not on the whole paper indiscriminately.

6. **Evidence retrieval subsystem**
   `retrieval/retriever.py` coordinates external lookup using `retrieval/query_builder.py` and `retrieval/evidence_ranker.py`, with settings in `config/retrieval.yaml`. The README indicates a scholarly-first strategy with fallback to broader web search, so external evidence is treated as supporting context for checkable claims rather than as a generic search result dump.

7. **Verification layer**
   `verification/verifier_agent.py` compares extracted claims against both paper-local context and retrieved evidence. This is the grounding boundary: it determines whether a claim is supported, contradicted, or remains uncertain before the later scoring agents synthesize higher-level judgments.

8. **Evaluation agents**
   The `agents/` directory contains specialized LLM-driven evaluators:
   - `consistency_agent.py` for overall internal consistency
   - `grammar_agent.py` for writing quality
   - `novelty_agent.py` for literature-backed novelty synthesis
   - `credibility_agent.py` for fabrication-risk synthesis
   - `assessment_synthesis_agent.py` for combining assessment signals
   `agents/llm_client.py` centralizes model access, likely to Gemini per the README and `.env.example`.

9. **Scoring and model layer**
   `scoring/credibility_model.py` and `models/schema.py` define the structured outputs and scoring artifacts used across the pipeline. This layer provides the data contract between extraction, retrieval, verification, and report generation.

10. **Caching and runtime resilience**
   `utils/cache_manager.py` suggests memoization or artifact reuse across runs, which matters because retrieval and LLM calls are expensive. The README also notes conservative fallback behavior when Gemini output or retrieval is unavailable, so the architecture is designed to degrade rather than fail noisily.

11. **Reporting and outputs**
   `reporter/report_writer.py` writes the final Markdown report to `reports/<paper_id>/report.md`. This is the system’s durable output boundary: all upstream analysis is funneled into a human-readable audit artifact that includes scores like consistency, grammar, novelty, and fabrication risk.

12. **Operational shape**
   The repo is a single-process application with two user-facing surfaces: Streamlit for interaction and file-based Markdown reports for persistence. External dependencies that materially shape the architecture are the LLM provider, PDF inputs, and scholarly/web retrieval sources; everything else is internal orchestration and transformation.

Main entry points: [`pipeline.py`](https://github.com/abhiramk6/research-paper-analyze/blob/main/pipeline.py) (Pipeline), [`retrieval/retriever.py`](https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/retriever.py) (Retriever), [`agents/llm_client.py`](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/llm_client.py) (LLM client), [`agents/credibility_agent.py`](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/credibility_agent.py) (Credibility)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User surface"]
  node_app_py["App<br/>streamlit ui<br/>[app.py]"]
end

subgraph group_pipeline["Core flow"]
  node_pipeline_py["Pipeline<br/>orchestrator<br/>[pipeline.py]"]
  node_claim_extractor["Claims<br/>claim extraction<br/>[claim_extractor.py]"]
  node_retriever["Retriever<br/>evidence retrieval<br/>[retriever.py]"]
  node_verifier_agent["Verifier<br/>grounding check<br/>[verifier_agent.py]"]
end

subgraph group_agents["LLM evaluators"]
  node_consistency_agent["Consistency<br/>assessment agent"]
  node_grammar_agent["Grammar<br/>assessment agent<br/>[grammar_agent.py]"]
  node_novelty_agent["Novelty<br/>assessment agent<br/>[novelty_agent.py]"]
  node_credibility_agent["Credibility<br/>assessment agent"]
  node_synthesis_agent["Synthesis<br/>assessment combiner"]
  node_llm_client["LLM client<br/>model access<br/>[llm_client.py]"]
end

subgraph group_support["Support layer"]
  node_downloader["Downloader<br/>ingest<br/>[downloader.py]"]
  node_pdf_parser["PDF parser<br/>[pdf_parser.py]"]
  node_token_chunker["Chunker<br/>context windows<br/>[token_chunker.py]"]
  node_query_builder["Query builder<br/>search queries<br/>[query_builder.py]"]
  node_evidence_ranker["Ranker<br/>evidence ranking<br/>[evidence_ranker.py]"]
  node_credibility_model["Credibility model<br/>scoring model"]
  node_schema["Schema<br/>structured outputs<br/>[schema.py]"]
  node_cache_manager[("Cache<br/>[cache_manager.py]")]
  node_retrieval_yaml["Retrieval config<br/>settings<br/>[retrieval.yaml]"]
end

subgraph group_storage["Artifacts"]
  node_report_md["Report<br/>markdown artifact<br/>[report.md]"]
end

node_app_py -->|"submits paper"| node_pipeline_py
node_pipeline_py -->|"ingest"| node_downloader
node_downloader -->|"raw pdf"| node_pdf_parser
node_pdf_parser -->|"paper text"| node_token_chunker
node_token_chunker -->|"chunks"| node_claim_extractor
node_claim_extractor -->|"claim objects"| node_schema
node_pipeline_py -->|"retrieve evidence"| node_retriever
node_retriever -->|"build queries"| node_query_builder
node_retriever -->|"rank evidence"| node_evidence_ranker
node_retriever -->|"uses config"| node_retrieval_yaml
node_retriever -->|"reuse artifacts"| node_cache_manager
node_pipeline_py -->|"verify claims"| node_verifier_agent
node_verifier_agent -->|"verification output"| node_schema
node_pipeline_py -->|"evaluate consistency"| node_consistency_agent
node_pipeline_py -->|"evaluate grammar"| node_grammar_agent
node_pipeline_py -->|"evaluate novelty"| node_novelty_agent
node_pipeline_py -->|"evaluate fabrication"| node_credibility_agent
node_consistency_agent -->|"model call"| node_llm_client
node_grammar_agent -->|"model call"| node_llm_client
node_novelty_agent -->|"model call"| node_llm_client
node_credibility_agent -->|"scores risk"| node_credibility_model
node_credibility_agent -->|"model call"| node_llm_client
node_pipeline_py -->|"combine signals"| node_synthesis_agent
node_synthesis_agent -->|"final summary"| node_schema
node_pipeline_py -->|"write report"| node_report_md
node_pipeline_py -->|"store run state"| node_cache_manager
node_app_py -->|"download output"| node_report_md

click node_app_py "https://github.com/abhiramk6/research-paper-analyze/blob/main/app.py"
click node_report_md "https://github.com/abhiramk6/research-paper-analyze/blob/main/reports/test-case/report.md"
click node_pipeline_py "https://github.com/abhiramk6/research-paper-analyze/blob/main/pipeline.py"
click node_downloader "https://github.com/abhiramk6/research-paper-analyze/blob/main/ingestion/downloader.py"
click node_pdf_parser "https://github.com/abhiramk6/research-paper-analyze/blob/main/parser/pdf_parser.py"
click node_token_chunker "https://github.com/abhiramk6/research-paper-analyze/blob/main/chunker/token_chunker.py"
click node_claim_extractor "https://github.com/abhiramk6/research-paper-analyze/blob/main/claims/claim_extractor.py"
click node_retriever "https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/retriever.py"
click node_query_builder "https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/query_builder.py"
click node_evidence_ranker "https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/evidence_ranker.py"
click node_verifier_agent "https://github.com/abhiramk6/research-paper-analyze/blob/main/verification/verifier_agent.py"
click node_consistency_agent "https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/consistency_agent.py"
click node_grammar_agent "https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/grammar_agent.py"
click node_novelty_agent "https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/novelty_agent.py"
click node_credibility_agent "https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/credibility_agent.py"
click node_synthesis_agent "https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/assessment_synthesis_agent.py"
click node_llm_client "https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/llm_client.py"
click node_credibility_model "https://github.com/abhiramk6/research-paper-analyze/blob/main/scoring/credibility_model.py"
click node_schema "https://github.com/abhiramk6/research-paper-analyze/blob/main/models/schema.py"
click node_cache_manager "https://github.com/abhiramk6/research-paper-analyze/blob/main/utils/cache_manager.py"
click node_retrieval_yaml "https://github.com/abhiramk6/research-paper-analyze/blob/main/config/retrieval.yaml"

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_app_py toneBlue
class node_pipeline_py,node_claim_extractor,node_retriever,node_verifier_agent toneAmber
class node_consistency_agent,node_grammar_agent,node_novelty_agent,node_credibility_agent,node_synthesis_agent,node_llm_client toneMint
class node_downloader,node_pdf_parser,node_token_chunker,node_query_builder,node_evidence_ranker,node_credibility_model,node_schema,node_cache_manager,node_retrieval_yaml toneRose
class node_report_md toneIndigo
```

## Components

### User surface

Interactive entry point and persisted report output.

- [App](https://github.com/abhiramk6/research-paper-analyze/blob/main/app.py): streamlit ui · Interactive front end for submitting papers and downloading results. · `app.py`

### Core flow

Orchestration and major analysis stages for a paper run.

- [Pipeline](https://github.com/abhiramk6/research-paper-analyze/blob/main/pipeline.py): orchestrator · Core LangGraph-style orchestration from input through report generation. · `pipeline.py`
- [Claims](https://github.com/abhiramk6/research-paper-analyze/blob/main/claims/claim_extractor.py): claim extraction · Reduces paper text into checkable claim types such as contribution, result, comparison, factual, and method. · `claims/claim_extractor.py`
- [Retriever](https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/retriever.py): evidence retrieval · Coordinates external evidence lookup for claims. · `retrieval/retriever.py`
- [Verifier](https://github.com/abhiramk6/research-paper-analyze/blob/main/verification/verifier_agent.py): grounding check · Compares claims against paper context and retrieved evidence to determine support status. · `verification/verifier_agent.py`

### LLM evaluators

Specialized model-backed evaluators and shared client.

- [Consistency](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/consistency_agent.py): assessment agent · Evaluates overall internal consistency of the paper and extracted findings. · `agents/consistency_agent.py`
- [Grammar](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/grammar_agent.py): assessment agent · Assesses writing quality and language clarity. · `agents/grammar_agent.py`
- [Novelty](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/novelty_agent.py): assessment agent · Synthesizes literature-backed novelty judgments. · `agents/novelty_agent.py`
- [Credibility](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/credibility_agent.py): assessment agent · Synthesizes fabrication-risk and credibility signals. · `agents/credibility_agent.py`
- [Synthesis](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/assessment_synthesis_agent.py): assessment combiner · Combines assessment signals into a final structured judgment. · `agents/assessment_synthesis_agent.py`
- [LLM client](https://github.com/abhiramk6/research-paper-analyze/blob/main/agents/llm_client.py): model access · Centralized access layer for model calls used by agents and pipeline stages. · `agents/llm_client.py`

### Support layer

Parsing, chunking, retrieval, caching, and schema contracts.

- [Downloader](https://github.com/abhiramk6/research-paper-analyze/blob/main/ingestion/downloader.py): ingest · Acquires paper content from arXiv URLs or local file paths. · `ingestion/downloader.py`
- [PDF parser](https://github.com/abhiramk6/research-paper-analyze/blob/main/parser/pdf_parser.py): parse · Converts PDFs into lightweight structured text for downstream analysis. · `parser/pdf_parser.py`
- [Chunker](https://github.com/abhiramk6/research-paper-analyze/blob/main/chunker/token_chunker.py): context windows · Creates overlapping token windows to keep model calls within context limits. · `chunker/token_chunker.py`
- [Query builder](https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/query_builder.py): search queries · Forms scholarly-first and fallback search queries for evidence lookup. · `retrieval/query_builder.py`
- [Ranker](https://github.com/abhiramk6/research-paper-analyze/blob/main/retrieval/evidence_ranker.py): evidence ranking · Orders retrieved sources by relevance and usefulness for verification. · `retrieval/evidence_ranker.py`
- [Credibility model](https://github.com/abhiramk6/research-paper-analyze/blob/main/scoring/credibility_model.py): scoring model · Defines credibility and fabrication-risk scoring logic or structure. · `scoring/credibility_model.py`
- [Schema](https://github.com/abhiramk6/research-paper-analyze/blob/main/models/schema.py): structured outputs · Shared data contracts for extracted claims, evidence, and assessment artifacts. · `models/schema.py`
- [Cache](https://github.com/abhiramk6/research-paper-analyze/blob/main/utils/cache_manager.py): runtime cache · Memoizes or reuses artifacts across runs to reduce repeated retrieval and LLM cost. · `utils/cache_manager.py`
- [Retrieval config](https://github.com/abhiramk6/research-paper-analyze/blob/main/config/retrieval.yaml): settings · Retrieval configuration for evidence lookup behavior. · `config/retrieval.yaml`

### Artifacts

Run outputs and generated reports.

- [Report](https://github.com/abhiramk6/research-paper-analyze/blob/main/reports/test-case/report.md): markdown artifact · Example persisted evaluation report for a paper run. · `reports/test-case/report.md`

## Connections

- App → Pipeline: submits paper · The UI hands user input to the orchestration layer.
- Pipeline → Downloader: ingest · Pipeline acquires paper source from URL or local file.
- Downloader → PDF parser: raw pdf · Downloaded paper is parsed into structured text.
- PDF parser → Chunker: paper text · Parsed text is windowed for bounded processing.
- Chunker → Claims: chunks · Chunked text feeds claim extraction.
- Claims → Schema: claim objects · Extracted claims are produced in shared structured form.
- Pipeline → Retriever: retrieve evidence · Pipeline requests external evidence for claims.
- Retriever → Query builder: build queries · Retrieval constructs search queries from claims and context.
- Retriever → Ranker: rank evidence · Candidate sources are scored and ordered.
- Retriever → Retrieval config: uses config · Retrieval behavior is driven by configuration settings.
- Retriever → Cache: reuse artifacts · Retrieval may reuse cached results across runs.
- Pipeline → Verifier: verify claims · Claims and retrieved evidence are checked for support or contradiction.
- Verifier → Schema: verification output · Verification produces structured grounding results.
- Pipeline → Consistency: evaluate consistency · Pipeline invokes the consistency evaluator.
- Pipeline → Grammar: evaluate grammar · Pipeline invokes the writing-quality evaluator.
- Pipeline → Novelty: evaluate novelty · Pipeline invokes the novelty synthesizer.
- Pipeline → Credibility: evaluate fabrication · Pipeline invokes the credibility and fabrication-risk evaluator.
- Consistency → LLM client: model call · Consistency assessment is generated through shared model access.
- Grammar → LLM client: model call · Grammar assessment is generated through shared model access.
- Novelty → LLM client: model call · Novelty synthesis is generated through shared model access.
- Credibility → Credibility model: scores risk · Fabrication-risk logic is grounded in the scoring model.
- Credibility → LLM client: model call · Credibility synthesis may use shared model access.
- Pipeline → Synthesis: combine signals · Pipeline merges evaluator outputs into a final assessment.
- Synthesis → Schema: final summary · Combined assessment is emitted in shared structured form.
- Pipeline → Report: write report · Final structured findings are rendered to a Markdown report.
- Pipeline → Cache: store run state · Pipeline may persist intermediate artifacts for reuse.
- App → Report: download output · The UI exposes the generated report to the user.
