# zipstack/llm-whisperer-python-client architecture

> Architecture diagram of the GitHub repository zipstack/llm-whisperer-python-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zipstack/llm-whisperer-python-client
- Repository: https://github.com/zipstack/llm-whisperer-python-client

## Overview

##### Main Components
a. Client Library Modules:
- LLMWhispererClient (legacy) and LLMWhispererClientV2: These reside in the src/unstract/llmwhisperer folder and serve as the entry points for users.
- Utility Functions: Located in utils.py, these support common operations required by both client versions.
b. Integration with APIs/External Services:
- Although the code does not include explicit API calls in the file tree, the README clearly indicates the library is built for interacting with LLMWhisperer APIs. Represent an “External LLMWhisperer API” component.
c. Testing & Quality Assurance:
- The tests folder (with both integration and unit tests) verifies client functionality using sample document files (PDFs and expected text outputs) stored under tests/test_data.
- CI/CD and Deployment Infrastructure: .github/workflows and configuration files (e.g., tox.ini, .pre-commit-config.yaml) indicate automated testing and code quality tools.
d. Packaging and Configuration:
- Build and deployment tools such as pdm.lock and pyproject.toml.

##### Representing Relationships and Data Flow
- That the “Legacy Client” and “Client V2” both rely on common utility functions.
- In the testing section, demonstrate how integration tests confirm that documents (input files like PDFs) are processed into various text representations – indicating data flow from sample inputs to expected outputs.
- CI/CD workflows that trigger tests and verifications on commit.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinguish between the client API interface (which handles document processing) and the underlying utility functions.
- Versioning: Highlight the dual implementation accommodating backward compatibility with the legacy client and the recommended “V2” for new development.
- Modularity: The code base is organized into logical modules and directories (src, tests, .github) that allow independent development and testing.
- Extensibility: The project configuration and comprehensive testing folder suggest that the library is designed for both robustness and ease of extension.

##### Final Recommendations
- That components are clearly isolated, making it immediately apparent which parts interact with each other.
- Legends or notes that highlight the separation of legacy versus current client functionality to make the architecture explicit to developers and stakeholders.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Application Node
    A["User/Application"]:::external

    %% Client Library Subgraph
    subgraph "Client Library"
        CL1["LLMWhispererClient (Legacy)"]:::client
        CL2["LLMWhispererClientV2"]:::client
        U["Utilities"]:::utility
    end

    %% External API
    API["LLMWhisperer API"]:::external

    %% Quality & Deployment Subgraph
    subgraph "Quality & Deployment"
        CICD["CI/CD Pipeline"]:::cicd
        TS["Test Suite"]:::tests
    end

    %% Build & Packaging Subgraph
    subgraph "Build & Packaging"
        PYP["pyproject.toml"]:::build
        PDM["pdm.lock"]:::build
        TOX["tox.ini"]:::build
        PRE[".pre-commit-config.yaml"]:::build
    end

    %% Connections from User to Client Library
    A -->|"calls"| CL1
    A -->|"calls"| CL2

    %% Client Library interactions with Utilities and External API
    CL1 -->|"uses"| U
    CL2 -->|"uses"| U
    CL1 -->|"calls"| API
    CL2 -->|"calls"| API

    %% CI/CD Pipeline triggering Test Suite
    CICD -->|"triggers"| TS

    %% Build & Packaging configuration supports CI/CD and Client Library packaging
    PYP -->|"configures"| CICD
    PDM -->|"configures"| CICD
    TOX -->|"configures"| CICD
    PRE -->|"configures"| CICD
    PYP ---|"builds"| CL1
    PYP ---|"builds"| CL2

    %% Test Suite validates Client Library functionality
    TS -->|"validates"| CL1
    TS -->|"validates"| CL2

    %% Click Events
    click CL1 "https://github.com/zipstack/llm-whisperer-python-client/blob/main/src/unstract/llmwhisperer/client.py"
    click CL2 "https://github.com/zipstack/llm-whisperer-python-client/blob/main/src/unstract/llmwhisperer/client_v2.py"
    click U "https://github.com/zipstack/llm-whisperer-python-client/blob/main/src/unstract/llmwhisperer/utils.py"
    click TS "https://github.com/zipstack/llm-whisperer-python-client/tree/main/tests"
    click CICD "https://github.com/zipstack/llm-whisperer-python-client/tree/main/.github/workflows"
    click PYP "https://github.com/zipstack/llm-whisperer-python-client/blob/main/pyproject.toml"
    click PDM "https://github.com/zipstack/llm-whisperer-python-client/blob/main/pdm.lock"
    click TOX "https://github.com/zipstack/llm-whisperer-python-client/blob/main/tox.ini"
    click PRE "https://github.com/zipstack/llm-whisperer-python-client/blob/main/.pre-commit-config.yaml"

    %% Styles
    classDef client fill:#aeeaff,stroke:#006699,stroke-width:2px;
    classDef utility fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef external fill:#ffe4b5,stroke:#cc6600,stroke-width:2px;
    classDef tests fill:#ffd1dc,stroke:#ff69b4,stroke-width:2px;
    classDef cicd fill:#ffdead,stroke:#cd853f,stroke-width:2px;
    classDef build fill:#d8bfd8,stroke:#9932cc,stroke-width:2px;
```
