Skip to main content

OpenSearch GenAI SDK

OTel-native tracing and scoring for LLM applications. Instrument your AI workflows with standard OpenTelemetry spans and submit evaluation scores, all routed to OpenSearch through a single OTLP pipeline.

Features

  • One-line setup: register() configures the full OTel pipeline (TracerProvider, exporter, auto-instrumentation)
  • observe(): one decorator and context manager that creates OTel spans with GenAI semantic convention attributes
  • enrich(): add model, token usage and other GenAI attributes to the active span from anywhere in your code
  • mark_agent_root(): mark the agent's span as the trace's agent root in OpenSearch Agent Traces
  • Auto-instrumentation: discovers and activates installed instrumentor packages (OpenAI, Anthropic, Bedrock, LangChain and more)
  • Scoring: score() emits each evaluation result as an OTel gen_ai.evaluation.result log event, parented to the evaluated span, at span, trace, session or tool-call level
  • Benchmarks: evaluate() runs your agent against a dataset with scorers; Benchmark uploads results from any eval framework (RAGAS, DeepEval, pytest). Each case is its own agent trace plus one gen_ai.evaluation.result log event per score
  • AWS SigV4: built-in SigV4 signing for AWS-hosted OpenSearch and Data Prepper endpoints
  • Zero lock-in: remove a decorator and your code still works; everything is standard OTel

Requirements

  • Python: 3.10, 3.11, 3.12 or 3.13
  • OpenTelemetry SDK: >=1.38.0, <2 (Logs API with event_name, used for evaluation events)

Installation

pip install opensearch-genai-observability-sdk-py

Upgrading from 0.2.x? endpoint= is now the OTLP base URL and the default moved to http://localhost:4318: see Upgrading to 0.3.0.

The core package includes the OTel SDK and exporters. Auto-instrumentation of LLM libraries is opt-in: install the extras for the providers you use, for example pip install "opensearch-genai-observability-sdk-py[openai,anthropic]".

Extra Installs
openai, anthropic, bedrock, google, langchain, llamaindex The instrumentor for that provider or framework
otel-instrumentors All instrumentors, including Cohere, Mistral, CrewAI, MCP and vector stores
opensearch opensearch-py, for OpenSearchTraceRetriever
all Everything, for development and integration testing

The full list is in Auto-instrumentation.

Quick start

Tracing

from opensearch_genai_observability_sdk_py import Op, enrich, observe, register

register(service_name="research-app")  # OTLP to http://localhost:4318


@observe(name="research_agent", op=Op.INVOKE_AGENT)
def research(query: str) -> str:
    with observe("web_search", op=Op.EXECUTE_TOOL):
        results = [f"Result for: {query}"]
    enrich(model="gpt-4.1", provider="openai", input_tokens=150, output_tokens=50)
    return f"Summary of: {results}"


research("What is OpenSearch?")

This produces the span invoke_agent research_agent with a child execute_tool web_search. A longer example and the span tree are in Architecture.

Evaluations

This continues the tracing example: it scores research, and the evaluation events need the LoggerProvider that register() installs.

from opensearch_genai_observability_sdk_py import evaluate, scorer


@scorer(name="accuracy", threshold=1)
def accuracy(input, output, expected):
    return 1.0 if expected in output else 0.0


result = evaluate(
    name="research-agent",
    task=research,
    data=[{"input": "What is OpenSearch?", "expected": "OpenSearch"}],
    scores=[accuracy],
)

Each case is its own agent trace, and each score is one gen_ai.evaluation.result event. To score live traffic, call score(): see score() and Getting started with agent evaluations.

Documentation

Document What it covers
docs/api-reference.md Every public API: register(), observe(), Op, enrich(), mark_agent_root(), score(), evaluate(), Benchmark, OpenSearchTraceRetriever
docs/configuration.md Environment variables, endpoints, protocols, AWS SigV4, ingestion pipeline settings, auto-instrumented libraries
docs/architecture.md How spans and evaluation events flow from the SDK into OpenSearch
docs/agent-evaluations.md Evaluation concepts and reference: data model, what gets stored, index template, ingestion, verify, troubleshooting
docs/getting-started-evaluations.md Guided walkthrough from an instrumented agent to online and offline results in OpenSearch Dashboards
examples/ Runnable examples, one SDK feature each

The docs index is docs/README.md.

TypeScript SDK

Looking for the TypeScript version? See opensearch-genai-observability-sdk-ts.

Contributing

See CONTRIBUTING.md for the development setup, tests and the pull request process.

Security

See SECURITY.md to report a vulnerability.

License

This project is licensed under the Apache License 2.0.

Copyright OpenSearch Contributors. See NOTICE for details.

Metadata

Release files for opensearch-genai-observability-sdk-py 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opensearch-genai-observability-sdk-py 0.3.0
File Size Uploaded Provenance Actions
opensearch_genai_observability_sdk_py-0.3.0.tar.gz 113.4 kB With provenance Details for opensearch_genai_observability_sdk_py-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opensearch-genai-observability-sdk-py 0.3.0
File Interpreter ABI Platform Actions
opensearch_genai_observability_sdk_py-0.3.0-py3-none-any.whl Python 3 none any Details for opensearch_genai_observability_sdk_py-0.3.0-py3-none-any.whl

Total release size: 179.5 kB

Release files / opensearch_genai_observability_sdk_py-0.3.0.tar.gz

Download URL opensearch_genai_observability_sdk_py-0.3.0.tar.gz
Size 113.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4811207c495aaf90005d6c9a5296f9720f47250544193b1b2b40f23fb077306d
BLAKE2b-256 checksum
How to use checksums
7e10a7870def062631e9a823351cf27a9b30328561b06bb247b0d579a42f2c37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / opensearch_genai_observability_sdk_py-0.3.0-py3-none-any.whl

Download URL opensearch_genai_observability_sdk_py-0.3.0-py3-none-any.whl
Size 66.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
517a445e7f795a563edc3bd25827170a25e0222b2bb3712704701207cd742494
BLAKE2b-256 checksum
How to use checksums
1b37cebf3bfeaba5163b5b4702f4e10e252c527df7cb7f31a4b582da8678583c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for opensearch-genai-observability-sdk-py 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for opensearch_genai_observability_sdk_py-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page