# samuelint/langchain-openai-api-bridge architecture

> Architecture diagram of the GitHub repository samuelint/langchain-openai-api-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samuelint/langchain-openai-api-bridge
- Repository: https://github.com/samuelint/langchain-openai-api-bridge

## Overview

##### Project Overview & Purpose
- This project is a FastAPI extension designed to expose Langchain (and Langgraph) agents as an OpenAI-compatible API. It supports two major API types: the Assistant API and the Chat Completions API.
- The project is tailored to integrate multiple LLM vendors (such as OpenAI, Anthropic, Groq, LLamaCPP) and serves requests from external OpenAI-compatible clients.

##### Main Components/Modules
a. API Gateway (FastAPI Integration):
- The FastAPI application is the entry point where API endpoints are registered. The “fastapi” directory and bindings in modules like langchain_openai_api_bridge/fastapi/langchain_openai_api_bridge_fastapi.py are the core parts.
- Two API routes exist – one tied to the Assistant API (with functionalities such as threads, messages, run stream, tool event streams) and one for Chat Completion.

b. Assistant and Chat Completion Modules:
- The “assistant” directory encapsulates functionalities that support the OpenAI Assistant API. It includes multiple adapters, message services, thread services, DTOs for agent creation, and repository integrations.
- The “chat_completion” directory handles the components necessary for exposing the Chat Completions API. This includes adapter modules (factories, object factories, stream adapters) that process chat response content.

c. Chat Model Adapters:
- The “chat_model_adapter” directory contains vendor-specific adapters (e.g. for Anthropic and LLamaCPP). These adapters provide compatibility layers so that the agents can mimic OpenAI chat models regardless of the underlying vendor.

d. Core Modules:
- The “core” directory holds components that manage agent creation, agent factories (base, function-based, and role adaptors), and support utilities (like dependency injection container and async iterator utilities). This area provides the backbone for orchestrating the bridge between Langchain agents and OpenAI API calls.

e. Repositories and Data Persistence:
- Inside both the assistant sub-modules and in separate repository directories, there are in-memory implementations for managing messages, threads, and run histories. These repositories offer a stateless or ephemeral data handling for API interactions.

f. Testing and Examples:
- The tests directory provides functional and unit tests showing practical integration scenarios, with sample agent factories and server implementations (e.g., for Anthropic, OpenAI, Groq, and LLamaCPP). This demonstrates real-world usage and integration points for both API types.

##### Relationships and Interactions
- The FastAPI entry point binds the bridge (e.g., LangchainOpenaiApiBridgeFastAPI) to the API endpoints. This component internally calls agent factories (user provided or default) to create Langchain agents.
- Depending on the endpoint (Assistant or Chat Completion), the request flows through adapter layers (e.g., from langchain inputs to OpenAI message formats) and then is handled by the respective services (like assistant_run_service or chat_completion services).
- Repositories (in-memory for this project) maintain conversation histories, thread details, and run metadata that can be used for further processing or later retrieval.
- Vendor-specific adapters (found in chat_model_adapter/ and within assistant/adapter) are responsible for translating requests to the target vendor’s format, ensuring compatibility and proper handling of streaming or multimodal responses.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Organized directories (assistant, chat_completion, core, fastapi) denote clear functional boundaries.
- Adapter/Facade Pattern: Many “adapter” modules convert inputs, messages, and events between Langchain/Langgraph internal representations and OpenAI API-compatible structures.
- Extensibility: By supporting multiple agent factories and vendor-specific adapters, users can plug in custom logic for different LLM vendors.
- Dependency Injection: The usage of providers (e.g., agent_factory_provider in the FastAPI bridge and in-memory repository providers) supports loose coupling and testability.

##### Technologies & Frameworks
- Python language with FastAPI framework as the web server.
- Langchain and Langgraph providing agent/LLM orchestration.
- In-memory repository implementations used for prototyping; extensibility is available for production-grade stores.
- Testing is managed using pytest.
- The project also involves Docker/Poetry for dependency management and CI/CD pipelines as seen in GitHub workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client("External Client"):::client

    %% FastAPI Layer
    FastAPI("FastAPI Application"):::api
    Bridge("Bridge Component (LangchainOpenaiApiBridgeFastAPI)"):::api

    %% API Endpoints
    AssistantAPI("Assistant API Endpoint"):::api
    ChatCompletionAPI("Chat Completion API Endpoint"):::api

    %% Assistant Module and its subcomponents
    subgraph "Assistant Module"
        A_Adapters("Adapters"):::adapter
        A_MessageService("Message & Thread Services"):::adapter
        A_DTO("API DTOs"):::adapter
    end

    %% Chat Completion Module and its subcomponents
    subgraph "Chat Completion Module"
        CC_Adapters("Adapters & Factories"):::adapter
        CC_Stream("Stream Handlers"):::adapter
    end

    %% Chat Model Adapters
    ChatModelAdapters("Chat Model Adapters (Anthropic, LLamaCPP, etc.)"):::adapter

    %% Core Modules & Agent Factories
    Core("Core Module & Agent Factories"):::core

    %% In-Memory Repositories
    Repos("In-Memory Repositories\n(Messages, Threads, Runs)"):::repo

    %% Testing & Examples
    Testing("Testing & Example Implementations"):::test

    %% Connections: Client initiates request
    Client -->|"sends request"| FastAPI

    %% FastAPI binds to Bridge Component
    FastAPI -->|"routes to"| Bridge

    %% Bridge exposes two API endpoints
    Bridge -->|"binds"| AssistantAPI
    Bridge -->|"binds"| ChatCompletionAPI

    %% API endpoints interact with service modules
    AssistantAPI -->|"calls"| A_Adapters
    AssistantAPI -->|"calls"| A_MessageService
    AssistantAPI -->|"calls"| A_DTO

    ChatCompletionAPI -->|"calls"| CC_Adapters
    ChatCompletionAPI -->|"calls"| CC_Stream

    %% Both modules interact with Chat Model Adapters
    A_Adapters -->|"utilizes"| ChatModelAdapters
    CC_Adapters -->|"utilizes"| ChatModelAdapters

    %% Bridge uses Core Agent Factories for agent creation
    Bridge -->|"creates agents via"| Core

    %% Assistant Module utilizes Repositories for state
    A_MessageService -->|"stores data in"| Repos
    A_DTO -->|"stores data in"| Repos

    %% Testing interacts with various layers
    Testing -->|"tests"| Bridge
    Testing -->|"tests"| Core
    Testing -->|"tests"| A_Adapters
    Testing -->|"tests"| CC_Adapters

    %% Click Events
    click Bridge "https://github.com/samuelint/langchain-openai-api-bridge/blob/main/langchain_openai_api_bridge/fastapi/langchain_openai_api_bridge_fastapi.py"
    click AssistantAPI "https://github.com/samuelint/langchain-openai-api-bridge/blob/main/langchain_openai_api_bridge/fastapi/assistant_api_router.py"
    click ChatCompletionAPI "https://github.com/samuelint/langchain-openai-api-bridge/blob/main/langchain_openai_api_bridge/fastapi/chat_completion_router.py"
    click A_Adapters "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/assistant"
    click A_MessageService "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/assistant"
    click A_DTO "https://github.com/samuelint/langchain-openai-api-bridge/blob/main/langchain_openai_api_bridge/assistant/create_thread_api_dto.py"
    click CC_Adapters "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/chat_completion"
    click CC_Stream "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/chat_completion"
    click ChatModelAdapters "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/chat_model_adapter"
    click Core "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/core"
    click Repos "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/langchain_openai_api_bridge/assistant/repository"
    click Testing "https://github.com/samuelint/langchain-openai-api-bridge/tree/main/tests"

    %% Styling: Define classes with colors
    classDef client fill:#ccccff,stroke:#000,stroke-width:1px;
    classDef api fill:#66ffff,stroke:#000,stroke-width:1px;
    classDef adapter fill:#ff9900,stroke:#000,stroke-width:1px;
    classDef core fill:#66cc66,stroke:#000,stroke-width:1px;
    classDef repo fill:#9966cc,stroke:#000,stroke-width:1px;
    classDef test fill:#ff6666,stroke:#000,stroke-width:1px;
```
