Metadata-Version: 2.5
Name: opentelemetry-instrumentation-genai-dspy
Version: 1.2b0
Summary: OpenTelemetry Official DSPy instrumentation
Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-dspy
Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python-genai
Author-email: OpenTelemetry Authors <cncf-opentelemetry-contributors@lists.cncf.io>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api~=1.43
Requires-Dist: opentelemetry-instrumentation<1,>=0.64b0
Requires-Dist: opentelemetry-semantic-conventions<1,>=0.64b0
Requires-Dist: opentelemetry-util-genai<2,>=1.2b0
Requires-Dist: wrapt<3.0.0,>=1.17.0
Provides-Extra: instruments
Requires-Dist: dspy<4,>=3.3.0; extra == 'instruments'
Description-Content-Type: text/x-rst

OpenTelemetry DSPy Instrumentation
==================================

|pypi|

.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-genai-dspy.svg
   :target: https://pypi.org/project/opentelemetry-instrumentation-genai-dspy/

This package provides OpenTelemetry instrumentation for the
`DSPy framework <https://pypi.org/project/dspy/>`_, emitting Generative AI
semantic conventions for DSPy Tool executions, ReAct agent loops
(supporting both ``dspy.ReAct`` and ``dspy.ReActV2``), and ``dspy.Retrieve``
retrieval operations.

Installation
------------

::

    pip install opentelemetry-instrumentation-genai-dspy

Usage
-----

.. code:: python

    from opentelemetry.instrumentation.genai.dspy import (
        DSPyInstrumentor,
    )

    DSPyInstrumentor().instrument()

Message content capture is disabled by default. Set
``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to one of
``NO_CONTENT``, ``SPAN_ONLY``, ``EVENT_ONLY``, or ``SPAN_AND_EVENT`` to record
prompts, completions, and module inputs/outputs.

Uploading prompts and completions
---------------------------------

Instead of recording message content inline, prompts and completions can be
uploaded to external storage via a completion hook. To enable the built-in
upload hook, set:

- ``OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload``
- ``OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH`` to an ``fsspec``-compatible
  URI/path (e.g. ``/path/to/prompts`` or ``gs://my_bucket``), and install the
  ``upload`` extra (``pip install opentelemetry-util-genai[upload]``).

A custom ``CompletionHook`` can also be passed programmatically, taking
precedence over the environment variable::

    DSPyInstrumentor().instrument(completion_hook=my_hook)

References
----------

* `OpenTelemetry Project <https://opentelemetry.io/>`_
* `OpenTelemetry GenAI semantic conventions <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`_
* `DSPy <https://github.com/stanfordnlp/dspy>`_
