# run-llama/llama_parse architecture

> Architecture diagram of the GitHub repository run-llama/llama_parse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/run-llama/llama_parse
- Repository: https://github.com/run-llama/llama_parse

## Overview

- LlamaParse – a GenAI-native document parser,
- LlamaReport – an agentic report generator (beta/invite-only), and
- LlamaExtract – an agentic data extractor (beta/invite-only).

a. Client/SDK Layer: Represent the three primary service clients (LlamaParse, LlamaReport, LlamaExtract) as main components providing interfaces for developers to integrate with LlamaCloud.
c. Utility/Helper Modules: In the llama_cloud_services package, include modules for constants, extraction utilities, parsing base classes, CLI interfaces (under both llama_cloud_services/parse/cli and llama_parse/llama_parse/cli). This helps to clarify separation between core functionality and command-line tools.
d. Examples & Test Suites: Represent “examples” and “tests” directories as supporting components that verify and demonstrate the functionality of the SDKs.

##### Relationships and Interactions
b. Separation between the client interface layer (i.e., service classes for Parse, Report, and Extract) and the underlying implementation details (helper functions, CLI utilities, and internal constants).
c. Configuration pathway where the API key and base URL (including EU-specific configuration) are passed into each service, ensuring that requests are applied to the correct remote endpoints.

##### Architectural Patterns and Design Principles
a. Modularity: Emphasize how the project separates each service (Parse, Report, Extract) into its own module or sub-package to allow loosely coupled development.
c. Separation of Concerns: Clearly segregate the SDK's responsibilities (e.g., API client methods) from the utility functions and configuration management with separate modules.

##### Technologies and Frameworks
a. Python (implied by the pip installation and pyproject.toml files)
b. GitHub Actions (for CI/CD pipelines)
c. Notebook-based examples (Jupyter notebooks within examples/ directory)
d. External documentation and hosting (links to official docs and the LlamaCloud website)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        dev["Developer Code"]:::external
    end

    %% Client/SDK Layer
    subgraph "Client/SDK Layer"
        LParse["LlamaParse"]:::client
        LReport["LlamaReport"]:::client
        LExtract["LlamaExtract"]:::client
    end

    %% API & Remote Service Layer
    subgraph "API & Remote Service Layer"
        API["LlamaCloud API Endpoint (Configurable:Standard/EU)"]:::service
    end

    %% Utility/Helper Modules
    subgraph "Utility/Helper Modules"
        Constants["Common Constants"]:::utility
        ParseBase["Parsing Base"]:::utility
        ParseUtils["Parsing Utils"]:::utility
        CLI_Primary["CLI Utilities (Primary)"]:::utility
        CLI_Alternate["CLI Utilities (Alternate)"]:::utility
    end

    %% Supporting Components
    subgraph "Supporting Components"
        Examples["Examples"]:::external
        Tests["Test Suites"]:::external
    end

    %% CI/CD Infrastructure
    subgraph "CI/CD Infrastructure"
        Workflows["GitHub Workflows"]:::utility
    end

    %% Connections from Developer to Client/SDK Layer
    dev -->|"calls"| LParse
    dev -->|"calls"| LReport
    dev -->|"calls"| LExtract

    %% Internal dependencies within the SDK
    LParse -->|"uses"| Constants
    LParse -->|"uses"| ParseBase
    LParse -->|"uses"| ParseUtils
    LParse -->|"invokes"| CLI_Primary
    LParse -->|"alternative"| CLI_Alternate

    LReport -->|"integrates_with"| Constants
    LExtract -->|"leverages"| ParseUtils

    %% SDK making API calls to Cloud Service
    LParse -->|"HTTP_request"| API
    LReport -->|"HTTP_request"| API
    LExtract -->|"HTTP_request"| API

    %% Examples and Tests verifying SDK functionality
    Examples -->|"demonstrates_usage"| LParse
    Examples -->|"demonstrates_usage"| LReport
    Examples -->|"demonstrates_usage"| LExtract

    Tests -->|"validates"| LParse
    Tests -->|"validates"| LReport
    Tests -->|"validates"| LExtract

    %% CI/CD integration monitoring and automating processes
    Workflows -->|"automates_build_and_test"| dev
    Workflows -->|"monitors"| LParse
    Workflows -->|"monitors"| LReport
    Workflows -->|"monitors"| LExtract

    %% Click Events
    click LParse "https://github.com/run-llama/llama_parse/tree/main/llama_cloud_services/parse"
    click CLI_Primary "https://github.com/run-llama/llama_parse/blob/main/llama_cloud_services/parse/cli/main.py"
    click CLI_Alternate "https://github.com/run-llama/llama_parse/blob/main/llama_parse/llama_parse/cli/main.py"
    click LReport "https://github.com/run-llama/llama_parse/tree/main/llama_cloud_services/report"
    click LExtract "https://github.com/run-llama/llama_parse/tree/main/llama_cloud_services/extract"
    click Constants "https://github.com/run-llama/llama_parse/blob/main/llama_cloud_services/constants.py"
    click ParseBase "https://github.com/run-llama/llama_parse/blob/main/llama_cloud_services/parse/base.py"
    click ParseUtils "https://github.com/run-llama/llama_parse/blob/main/llama_cloud_services/parse/utils.py"
    click Examples "https://github.com/run-llama/llama_parse/tree/main/examples/"
    click Tests "https://github.com/run-llama/llama_parse/tree/main/tests/"
    click Workflows "https://github.com/run-llama/llama_parse/tree/main/.github/workflows"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef service fill:#ccf,stroke:#333,stroke-width:2px;
    classDef utility fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fc9,stroke:#333,stroke-width:2px;

    class dev external;
    class LParse,LReport,LExtract client;
    class API service;
    class Constants,ParseBase,ParseUtils,CLI_Primary,CLI_Alternate,Workflows utility;
    class Examples,Tests external;
```
