# poldrack/ai-peer-review architecture

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

- Interactive diagram: https://gitdiagram.com/poldrack/ai-peer-review
- Repository: https://github.com/poldrack/ai-peer-review

## Overview

##### Project type and purpose
- This is an open-source command-line tool (Python package) called “AI Peer Review.” Its job is to take a PDF of an academic paper, send it to multiple LLMs, collect individual reviews, synthesize a meta-review, and emit results in markdown, CSV, and JSON. It’s not a full-stack web app but a CLI-centric orchestration tool that integrates with external LLM APIs.

##### File structure
Top-level files:
- pyproject.toml – build/config for packaging
- README.md/.env.example – user documentation and sample environment variables
- src/ai_peer_review/cli.py – entrypoint for commands (config, review)
- src/ai_peer_review/utils/… – modules for configuration, PDF parsing
- src/ai_peer_review/llm_clients/… – one client per supported LLM, all subclassing a base_client
- src/ai_peer_review/review.py – core logic: orchestrate reviews, generate meta-review, write outputs
- tests/… – unit tests covering CLI, utils, clients, review logic

##### README for additional insights
- Workflow:
a) Load API keys (from CLI config or .env)
b) Parse PDF → text
c) For each configured LLM client: send prompt + paper → receive review
d) Aggregate reviews → meta-review via prompt
e) Produce files in output directory

##### Main components and their interactions
a. CLI Layer (cli.py)
- Parses user commands/flags
- Kicks off “review” command or “config” command
b. Configuration Manager (utils/config.py)
- Reads/writes ~/.ai-peer-review/config.json or environment variables
c. PDF Processor (utils/pdf.py)
- Extracts text from a PDF file path
d. Core Orchestrator (review.py)
- Instantiates all requested LLM clients
- Feeds them the review prompt + paper text
- Collects individual reviews
- Sends collected reviews to meta-review prompt
- Emits final artifacts via file I/O
e. LLM Clients (llm_clients/*.py)
- Each client implements a “generate_review” method calling a specific external API
- Share common interface defined in base_client.py
f. Output Writer (inside review.py)
- Writes review_{model}.md, meta_review.md, concerns_table.csv, results.json to disk
g. External Services
- OpenAI, Anthropic, Google AI, Together API – invoked by LLM clients

##### Architectural patterns / design principles
- Plugin-style client architecture: each LLM client is interchangeable, all inheriting from a base class
- Single-responsibility: CLI, config management, PDF parsing, orchestration, API clients, and I/O are decoupled
- Dependency injection: orchestrator loops over configured clients rather than hard-coding them

## Diagram (Mermaid)

```mermaid
graph TB
    %% Components and Layers
    subgraph "CLI Layer"
        CLI["CLI Layer\n(cli.py)"]:::cli
    end

    subgraph "Configuration Manager"
        Config["Configuration Manager\n(utils/config.py)"]:::config
    end

    subgraph "PDF Processor"
        PDF["PDF Processor\n(utils/pdf.py)"]:::pdf
    end

    subgraph "Core Orchestrator"
        Orchestrator["Review Orchestrator\n(review.py)"]:::orchestrator
        Output["Output Writer\n(review.py)"]:::output
    end

    subgraph "LLM Clients"
        Base["BaseClient Interface\n(base_client.py)"]:::llm
        Anthropic["AnthropicClient"]:::llm
        Deepseek["DeepseekClient"]:::llm
        Google["GoogleClient"]:::llm
        LLaMA["LLaMAClient"]:::llm
        OpenAI["OpenAIClient"]:::llm
    end

    LocalConfig["Local Config\n(~/.ai-peer-review/config.json\n.env vars)"]:::storage
    FS["File System\n(Output Files)"]:::storage

    subgraph "External LLM Services"
        CloudOpenAI("OpenAI API"):::cloud
        CloudAnthropic("Anthropic API"):::cloud
        CloudGoogle("Google AI API"):::cloud
        CloudTogether("Together API"):::cloud
    end

    subgraph "Support Files"
        PyProject["pyproject.toml"]:::doc
        Version["version.py"]:::doc
        EnvExample[".env.example"]:::doc
        README["README.md"]:::doc
    end

    %% Data Flows
    User(("User")) -->|"runs CLI"| CLI
    CLI -->|"load config"| Config
    Config --> LocalConfig
    CLI -->|"invoke review"| Orchestrator
    Orchestrator -->|"parse PDF"| PDF
    PDF -->|"returns text"| Orchestrator

    Orchestrator -->|"uses BaseClient"| Base
    Base --> Anthropic
    Base --> Deepseek
    Base --> Google
    Base --> LLaMA
    Base --> OpenAI

    Anthropic -->|"call API"| CloudAnthropic
    Deepseek -->|"call API"| CloudTogether
    Google -->|"call API"| CloudGoogle
    LLaMA -->|"call API"| CloudTogether
    OpenAI -->|"call API"| CloudOpenAI

    CloudAnthropic -->|"review_text"| Anthropic
    CloudTogether -->|"review_text"| Deepseek
    CloudGoogle -->|"review_text"| Google
    CloudTogether -->|"review_text"| LLaMA
    CloudOpenAI -->|"review_text"| OpenAI

    Anthropic -->|"send review"| Orchestrator
    Deepseek -->|"send review"| Orchestrator
    Google -->|"send review"| Orchestrator
    LLaMA -->|"send review"| Orchestrator
    OpenAI -->|"send review"| Orchestrator

    Orchestrator -->|"generate meta-review"| Base
    Base --> CloudOpenAI
    CloudOpenAI -->|"meta_review"| Orchestrator

    Orchestrator -->|"write outputs"| Output
    Output --> FS

    %% Click Events
    click CLI "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/cli.py"
    click Config "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/utils/config.py"
    click PDF "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/utils/pdf.py"
    click Orchestrator "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/review.py"
    click Output "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/review.py"
    click Base "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/llm_clients/base_client.py"
    click Anthropic "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/llm_clients/anthropic_client.py"
    click Deepseek "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/llm_clients/deepseek_client.py"
    click Google "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/llm_clients/google_client.py"
    click LLaMA "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/llm_clients/llama_client.py"
    click OpenAI "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/llm_clients/openai_client.py"
    click PyProject "https://github.com/poldrack/ai-peer-review/blob/main/pyproject.toml"
    click Version "https://github.com/poldrack/ai-peer-review/blob/main/src/ai_peer_review/version.py"
    click EnvExample "https://github.com/poldrack/ai-peer-review/blob/main/.env.example"
    click README "https://github.com/poldrack/ai-peer-review/blob/main/README.md"

    %% Styles
    classDef cli fill:#D6E9FE,stroke:#4C6EF5;
    classDef config fill:#E2F0CB,stroke:#82C91E;
    classDef pdf fill:#FFF2CC,stroke:#FAB005;
    classDef orchestrator fill:#FDE9D9,stroke:#F76707;
    classDef output fill:#F8D7DA,stroke:#D6336C;
    classDef llm fill:#E4D5F7,stroke:#7048E8;
    classDef storage fill:#D9EDF7,stroke:#339AF0;
    classDef cloud fill:#D0E0E3,stroke:#495057,stroke-dasharray: 5 5;
    classDef doc fill:#F0E6D2,stroke:#B197FC;
```
