dspy.Audio

dspy.Audio

Bases: Type

Functions

description() -> str classmethod

Description of the custom type

Source code in dspy/adapters/types/base_type.py

@classmethod
def description(cls) -> str:
    """Description of the custom type"""
    return ""

extract_custom_type_from_annotation(annotation) classmethod

Extract all custom types from the annotation.

This is used to extract all custom types from the annotation of a field, while the annotation can have arbitrary level of nesting. For example, we detect Tool is in list[dict[str, Tool]].

Source code in dspy/adapters/types/base_type.py

@classmethod
def extract_custom_type_from_annotation(cls, annotation):
    """Extract all custom types from the annotation.

    This is used to extract all custom types from the annotation of a field, while the annotation can
    have arbitrary level of nesting. For example, we detect `Tool` is in `list[dict[str, Tool]]`.
    """
    # Direct match. Nested type like `list[dict[str, Event]]` passes `isinstance(annotation, type)` in python 3.10
    # while fails in python 3.11. To accommodate users using python 3.10, we need to capture the error and ignore it.
    try:
        if isinstance(annotation, type) and issubclass(annotation, cls):
            return [annotation]
    except TypeError:
        pass

    origin = get_origin(annotation)
    if origin is None:
        return []

    result = []
    # Recurse into all type args
    for arg in get_args(annotation):
        result.extend(cls.extract_custom_type_from_annotation(arg))

    return result

format() -> list[dict[str, Any]]

Source code in dspy/adapters/types/audio.py

def format(self) -> list[dict[str, Any]]:
    try:
        data = self.data
    except Exception as e:
        raise ValueError(f"Failed to format audio for DSPy: {e}")
    return [{
        "type": "input_audio",
        "input_audio": {
            "data": data,
            "format": self.audio_format
        }
    }]

from_array(array: Any, sampling_rate: int, format: str = 'wav') -> Audio classmethod

Process numpy-like array and encode it as base64. Uses sampling rate and audio format for encoding.

Source code in dspy/adapters/types/audio.py

@classmethod
def from_array(
    cls, array: Any, sampling_rate: int, format: str = "wav"
) -> "Audio":
    """
    Process numpy-like array and encode it as base64. Uses sampling rate and audio format for encoding.
    """
    if not SF_AVAILABLE:
        raise ImportError("soundfile is required to process audio arrays.")

    byte_buffer = io.BytesIO()
    sf.write(
        byte_buffer,
        array,
        sampling_rate,
        format=format.upper(),
        subtype="PCM_16",
    )
    encoded_data = base64.b64encode(byte_buffer.getvalue()).decode("utf-8")
    return cls(data=encoded_data, audio_format=format)

from_file(file_path: str) -> Audio classmethod

Read local audio file and encode it as base64.

Source code in dspy/adapters/types/audio.py

@classmethod
def from_file(cls, file_path: str) -> "Audio":
    """
    Read local audio file and encode it as base64.
    """
    if not os.path.isfile(file_path):
        raise ValueError(f"File not found: {file_path}")

    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("audio/"):
        raise ValueError(f"Unsupported MIME type for audio: {mime_type}")

    with open(file_path, "rb") as file:
        file_data = file.read()

    audio_format = mime_type.split("/")[1]
    encoded_data = base64.b64encode(file_data).decode("utf-8")
    return cls(data=encoded_data, audio_format=audio_format)

from_url(url: str) -> Audio classmethod

Download an audio file from URL and encode it as base64.

Source code in dspy/adapters/types/audio.py

@classmethod
def from_url(cls, url: str) -> "Audio":
    """
    Download an audio file from URL and encode it as base64.
    """
    response = requests.get(url)
    response.raise_for_status()
    mime_type = response.headers.get("Content-Type", "audio/wav")
    if not mime_type.startswith("audio/"):
        raise ValueError(f"Unsupported MIME type for audio: {mime_type}")
    audio_format = mime_type.split("/")[1]
    encoded_data = base64.b64encode(response.content).decode("utf-8")
    return cls(data=encoded_data, audio_format=audio_format)

serialize_model()

Source code in dspy/adapters/types/base_type.py

@pydantic.model_serializer()
def serialize_model(self):
    formatted = self.format()
    if isinstance(formatted, list):
        return f"{CUSTOM_TYPE_START_IDENTIFIER}{formatted}{CUSTOM_TYPE_END_IDENTIFIER}"
    return formatted

validate_input(values: Any) -> Any classmethod

Validate input for Audio, expecting 'data' and 'audio_format' keys in dictionary.

Source code in dspy/adapters/types/audio.py

@pydantic.model_validator(mode="before")
@classmethod
def validate_input(cls, values: Any) -> Any:
    """
    Validate input for Audio, expecting 'data' and 'audio_format' keys in dictionary.
    """
    if isinstance(values, cls):
        return {"data": values.data, "audio_format": values.audio_format}
    return encode_audio(values)

:::