# magnivorg/prompt-layer-library architecture

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

- Interactive diagram: https://gitdiagram.com/magnivorg/prompt-layer-library
- Repository: https://github.com/magnivorg/prompt-layer-library

## Overview

##### Project type and purpose
- This is a Python client-library and middleware for PromptLayer’s REST API. It sits between your Python code and OpenAI’s SDK, intercepts and records every OpenAI call, and then forwards the original request to OpenAI while sending metadata to PromptLayer’s backend for tracking and analytics.
- The README confirms it is not a full-stack app but a wrapper/SDK that:
- Exposes the same OpenAI interface
- Logs every request, response, timings, tags
- Calls two external services: OpenAI API and PromptLayer’s own REST endpoints

##### File structure
- Top-level files:
- pyproject.toml, Makefile, .devcontainer, GitHub workflows → build/test/deploy
- promptlayer/ → core package
- tests/ → fixtures, unit/integration tests
- Within promptlayer/:
- promptlayer.py & promptlayer_base.py → core client class definitions
- promptlayer_mixins.py → methods to extend the client dynamically
- span_exporter.py → tracing instrumentation
- streaming/ → streaming API support (blueprint_builder, handlers, processor)
- track/ → logic for preparing and sending tracking payloads
- types/ → data models (PromptTemplate, RequestLog, etc.)
- templates.py, utils.py → helper functions
- Presence of config files (.pre-commit, GitHub actions) indicates CI/CD integration but not part of runtime architecture.

##### Key architecture insights from the README
- The client:
- Instantiates PromptLayer(api_key) → overrides openai client
- When user calls openai.Completion.create(..., pl_tags=[…]), the wrapper:
– Records start time, end time, request/response details
– Immediately forwards the operation to the real OpenAI API locally
– Posts a JSON log to https://api.promptlayer.com/track-request
- No local database or server. All persistence lives on PromptLayer’s cloud service.

##### Main components & their relationships
a. User Application
- Your Python code that imports promptlayer.PromptLayer and calls openai.*
b. PromptLayer Python SDK
- Core client (promptlayer.PromptLayer)
- Mixins (metrics, grouping, streaming support)
- Track module (builds track-request payload; calls HTTP client)
- Templates/types for serializing data
c. OpenAI Python SDK
- Underneath the wrapper; actual API calls go here
d. External Services
- OpenAI REST API endpoints (text completion, chat, embeddings, streaming)
- PromptLayer REST API (track-request, templates, tags)
e. CI/CD & Tests (not runtime but part of development workflow)

##### Architectural patterns & design principles
- Decorator/Proxy Pattern: PromptLayer wraps the OpenAI client, intercepts calls, and delegates execution
- Single Responsibility: Separate modules for streaming, tracking, templating, utils
- Pluggable Mixins: Extend core client with additional capabilities (groups, streaming, span export)
- External Integration: Stateless library; state lives in external APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User application
    UserApp["User Application"]:::inprocess

    %% SDK container
    subgraph "PromptLayer Python SDK"
        direction TB
        CoreClient["Core Client"]:::inprocess
        BaseClient["Base Client Definition"]:::inprocess
        Mixins["Dynamic Extensions (Mixins)"]:::inprocess
        GroupsMixin["Metrics & Grouping Mixin"]:::inprocess
        SpanExporter["Tracing/Span Exporter"]:::inprocess
        subgraph "Streaming Support"
            direction TB
            BlueprintBuilder["Blueprint Builder"]:::inprocess
            ResponseHandlers["Response Handlers"]:::inprocess
            StreamProcessor["Stream Processor"]:::inprocess
        end
        TrackModule["Tracking Module"]:::inprocess
        subgraph "Data Models / Types"
            direction TB
            PromptTemplate["PromptTemplate"]:::inprocess
            RequestLog["RequestLog"]:::inprocess
        end
        Templates["Templates & Serialization Helpers"]:::inprocess
        Utils["Utility Functions"]:::inprocess
    end

    %% Third-party library
    OpenAISDK["OpenAI Python SDK"]:::thirdparty

    %% External services
    OpenAIAPI(("OpenAI REST API")):::external
    PromptLayerAPI(("PromptLayer REST API")):::external

    %% Flows
    UserApp -->|"import & call openai.*"| CoreClient
    CoreClient -->|"delegates to"| BaseClient
    BaseClient -->|"applies mixins"| Mixins
    Mixins -->|"includes grouping"| GroupsMixin
    Mixins -->|"includes tracing"| SpanExporter
    Mixins -->|"includes streaming"| BlueprintBuilder
    BlueprintBuilder --> ResponseHandlers
    ResponseHandlers --> StreamProcessor
    CoreClient -->|"forward request"| OpenAISDK
    OpenAISDK -->|"HTTP request"| OpenAIAPI
    CoreClient -->|"send tracking payload"| TrackModule
    TrackModule -->|"POST JSON"| PromptLayerAPI

    %% Styling
    classDef inprocess fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef thirdparty fill:#F0F0F0,stroke:#666,color:#333
    classDef external fill:#DFF2BF,stroke:#4F8A10,color:#333

    %% Click Events
    click CoreClient "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/promptlayer.py"
    click BaseClient "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/promptlayer_base.py"
    click Mixins "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/promptlayer_mixins.py"
    click GroupsMixin "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/groups/groups.py"
    click SpanExporter "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/span_exporter.py"
    click BlueprintBuilder "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/streaming/blueprint_builder.py"
    click ResponseHandlers "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/streaming/response_handlers.py"
    click StreamProcessor "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/streaming/stream_processor.py"
    click TrackModule "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/track/track.py"
    click PromptTemplate "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/types/prompt_template.py"
    click RequestLog "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/types/request_log.py"
    click Templates "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/templates.py"
    click Utils "https://github.com/magnivorg/prompt-layer-library/blob/master/promptlayer/utils.py"
```
