# arize-ai/openinference architecture

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

- Interactive diagram: https://gitdiagram.com/arize-ai/openinference
- Repository: https://github.com/arize-ai/openinference

## Overview

##### Project Type and Purpose
- This is an open-source instrumentation framework (OpenInference) that provides:
- A formal **specification** (in Markdown under `/spec`) for tracing AI/LLM applications
- A **core library** with shared utilities and semantic conventions
- **Language-specific instrumentation packages** (Python, JavaScript, Java) that implement the spec atop OpenTelemetry
- **Example applications** in each language demonstrating how to use the instrumentations
- CI/CD pipelines to test, build, and publish each package to its registry

##### High-Level Architecture Components
A. **Specification Layer**
- `/spec` directory: Markdown docs defining the OpenInference trace model and semantic conventions
- Serves as the source of truth for all downstream libraries

B. **Core Libraries**
- `js/packages/openinference-core` and `python/openinference-instrumentation` and `java/openinference-instrumentation`
- Provide shared code for managing spans, context attributes, tracer configuration, masking rules, etc.
- Depend on the Spec

C. **Semantic Conventions**
- `js/packages/openinference-semantic-conventions`, `python/openinference-semantic-conventions`, `java/openinference-semantic-conventions`
- Attribute names, resource attributes, span kinds, etc., per the spec
- Imported by core and instrumentation modules

D. **Instrumentation Plugins**
- Python: many sub-packages under `python/instrumentation/openinference-instrumentation-*`
- JavaScript: `js/packages/openinference-instrumentation-*` (OpenAI, LangChain, BeeAI, MCP, Vercel, Mastra)
- Java: `java/instrumentation/openinference-instrumentation-*` (LangChain4j, SpringAI)
- Each plugin: wraps a target SDK or framework to emit OpenInference spans

E. **Examples and Demo Apps**
- For each language, the `examples/` folders under `python/`, `js/examples/`, `java/examples/`
- Complete end-to-end usage: app code <–instrumentation→ OTEL SDK <–spans→ collector

F. **CI/CD and Publishing**
- `.github/workflows/`: separate pipelines for Python (tox, pyproject), JS (pnpm, ts), Java (Gradle), release tooling
- Scripts: version-update, release-please, dependency updates (Dependabot)
- Targets: PyPI, npm registries, Maven Central, Docker (examples)

G. **External Dependencies and Services**
- **OpenTelemetry**–compatible collectors
- **Arize-Phoenix** or any OTEL backend for span ingestion
- Language SDK runtimes (FastAPI, Next.js, Express, Spring AI, LangChain, DSPy, LlamaIndex, etc.)

##### Relationships and Data Flows
- **Spec** → informs → **Semantic Conventions** → imported by → **Core Libraries**
- **Core Libraries** + **Semantic Conventions** → used by → **Instrumentation Plugins**
- **Instrumentation Plugins** → wrap → **Target SDKs** → generate → **Spans**
- **Examples** → include → **Instrumentation Plugins** + **Target SDK code** → send spans → **OTEL Collector**
- **CI/CD Workflows** → build/test → publish → **Package Registries**

##### Architectural Patterns
- **Layered Architecture**: Spec → Core → Plugins → Examples
- **Plugin Pattern**: Each SDK/framework gets its own wrapper module
- **Polyglot Distribution**: Same spec implemented across Python, JS, Java ecosystems
- **GitOps for CI/CD**: Declarative workflows driving tests and releases

##### Essential Elements
- Component names exactly as they appear in the file tree (e.g., `openinference-core`, `openinference-instrumentation-openai`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Specification Layer
    spec["spec"]:::specLayer
    click spec "https://github.com/arize-ai/openinference/tree/main/spec"

    %% Semantic Conventions Layer
    subgraph "Semantic Conventions"
        direction TB
        jsSem["openinference-semantic-conventions (JS)"]:::semantic
        pySem["openinference-semantic-conventions (Python)"]:::semantic
        javaSem["openinference-semantic-conventions (Java)"]:::semantic
        click jsSem "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-semantic-conventions"
        click pySem "https://github.com/arize-ai/openinference/tree/main/python/openinference-semantic-conventions"
        click javaSem "https://github.com/arize-ai/openinference/tree/main/java/openinference-semantic-conventions"
    end

    %% Core Libraries Layer
    subgraph "Core Libraries"
        direction TB
        jsCore["openinference-core (JS)"]:::core
        pyCore["openinference-instrumentation (Python)"]:::core
        javaCore["openinference-instrumentation (Java)"]:::core
        click jsCore "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-core"
        click pyCore "https://github.com/arize-ai/openinference/tree/main/python/openinference-instrumentation"
        click javaCore "https://github.com/arize-ai/openinference/tree/main/java/openinference-instrumentation"
    end

    %% Instrumentation Plugins Layer
    subgraph "Instrumentation Plugins"
        direction TB
        subgraph "JavaScript Plugins"
            direction TB
            jsOpenAI["openinference-instrumentation-openai"]:::plugin
            jsLangChain["openinference-instrumentation-langchain"]:::plugin
            jsBeeAI["openinference-instrumentation-beeai"]:::plugin
            jsMCP["openinference-instrumentation-mcp"]:::plugin
            jsVercel["openinference-vercel"]:::plugin
            jsBedrockAgent["openinference-instrumentation-bedrock-agent-runtime"]:::plugin
            jsBedrock["openinference-instrumentation-bedrock"]:::plugin
            click jsOpenAI "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-openai"
            click jsLangChain "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-langchain"
            click jsBeeAI "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-beeai"
            click jsMCP "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-mcp"
            click jsVercel "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-vercel"
            click jsBedrockAgent "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-bedrock-agent-runtime"
            click jsBedrock "https://github.com/arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-bedrock"
        end
        subgraph "Python Plugins"
            direction TB
            pyAgno["openinference-instrumentation-agno"]:::plugin
            pyAnthropic["openinference-instrumentation-anthropic"]:::plugin
            pyBedrock["openinference-instrumentation-bedrock"]:::plugin
            click pyAgno "https://github.com/arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-agno"
            click pyAnthropic "https://github.com/arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-anthropic"
            click pyBedrock "https://github.com/arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-bedrock"
        end
        subgraph "Java Plugins"
            direction TB
            javaLangChain4j["openinference-instrumentation-langchain4j"]:::plugin
            javaSpringAI["openinference-instrumentation-springAI"]:::plugin
            click javaLangChain4j "https://github.com/arize-ai/openinference/tree/main/java/instrumentation/openinference-instrumentation-langchain4j"
            click javaSpringAI "https://github.com/arize-ai/openinference/tree/main/java/instrumentation/openinference-instrumentation-springAI"
        end
    end

    %% Examples Layer
    subgraph "Example Applications"
        direction TB
        jsExamples["js/examples"]:::examples
        pyExamples["python/examples"]:::examples
        javaExamples["java/examples"]:::examples
        click jsExamples "https://github.com/arize-ai/openinference/tree/main/js/examples"
        click pyExamples "https://github.com/arize-ai/openinference/tree/main/python/examples"
        click javaExamples "https://github.com/arize-ai/openinference/tree/main/java/examples"
    end

    %% External Services
    collector["OTEL Collector"]:::external
    arize["Arize-Phoenix"]:::external

    %% CI/CD Pipelines
    cicd[".github/workflows"]:::cicd
    click cicd "https://github.com/arize-ai/openinference/tree/main/.github/workflows"
    releaseTool["release-please-config.json"]:::cicd
    click releaseTool "https://github.com/arize-ai/openinference/blob/main/release-please-config.json"

    %% Relationships
    spec -->|"informs"| jsSem
    spec -->|"informs"| pySem
    spec -->|"informs"| javaSem

    jsSem -->|"imported by"| jsCore
    pySem -->|"imported by"| pyCore
    javaSem -->|"imported by"| javaCore

    jsCore -->|"used by"| jsOpenAI
    jsCore -->|"used by"| jsLangChain
    jsCore -->|"used by"| jsBeeAI
    jsCore -->|"used by"| jsMCP
    jsCore -->|"used by"| jsVercel
    jsCore -->|"used by"| jsBedrockAgent
    jsCore -->|"used by"| jsBedrock

    pyCore -->|"used by"| pyAgno
    pyCore -->|"used by"| pyAnthropic
    pyCore -->|"used by"| pyBedrock

    javaCore -->|"used by"| javaLangChain4j
    javaCore -->|"used by"| javaSpringAI

    jsOpenAI -->|"used in"| jsExamples
    jsLangChain -->|"used in"| jsExamples
    jsBeeAI -->|"used in"| jsExamples
    jsMCP -->|"used in"| jsExamples
    jsVercel -->|"used in"| jsExamples
    jsBedrockAgent -->|"used in"| jsExamples
    jsBedrock -->|"used in"| jsExamples

    pyAgno -->|"used in"| pyExamples
    pyAnthropic -->|"used in"| pyExamples
    pyBedrock -->|"used in"| pyExamples

    javaLangChain4j -->|"used in"| javaExamples
    javaSpringAI -->|"used in"| javaExamples

    jsExamples -->|"- - emits spans - - "| collector
    pyExamples -->|"- - emits spans - - "| collector
    javaExamples -->|"- - emits spans - - "| collector

    collector -->|"forwards"| arize

    cicd -->|"build/test/publish"| jsCore
    cicd -->|"build/test/publish"| pyCore
    cicd -->|"build/test/publish"| javaCore
    cicd -->|"build/test/publish"| jsOpenAI
    cicd -->|"build/test/publish"| pyAgno
    cicd -->|"build/test/publish"| javaLangChain4j

    cicd -->|"release config"| releaseTool

    classDef specLayer fill:#D0E6A5,stroke:#3D550C,color:#3D550C
    classDef semantic fill:#A5C4D0,stroke:#1B3A4B,color:#1B3A4B
    classDef core fill:#A5D0E2,stroke:#0A3A4B,color:#0A3A4B
    classDef plugin fill:#F5C280,stroke:#7A4A01,color:#7A4A01
    classDef examples fill:#D8D8D8,stroke:#4A4A4A,color:#4A4A4A
    classDef external fill:#E2C0F9,stroke:#5A0D5A,color:#5A0D5A
    classDef cicd fill:#C0C0C0,stroke:#404040,color:#404040
```
