dspy.Image

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

@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

def format(self) -> list[dict[str, Any]] | str:
    try:
        image_url = encode_image(self.url)
    except Exception as e:
        raise ValueError(f"Failed to format image for DSPy: {e}")
    return [{"type": "image_url", "image_url": {"url": image_url}}]

@classmethod
def from_PIL(cls, pil_image):  # noqa: N802
    return cls(url=encode_image(pil_image))

@classmethod
def from_file(cls, file_path: str):
    return cls(url=encode_image(file_path))

@classmethod
def from_url(cls, url: str, download: bool = False):
    return cls(url=encode_image(url, download))

@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

@pydantic.model_validator(mode="before")
@classmethod
def validate_input(cls, values):
    # Allow the model to accept either a URL string or a dictionary with a single 'url' key
    if isinstance(values, str):
        # if a string, assume it's the URL directly and wrap it in a dict
        return {"url": values}
    elif isinstance(values, dict) and set(values.keys()) == {"url"}:
        # if it's a dict, ensure it has only the 'url' key
        return values
    elif isinstance(values, cls):
        return values.model_dump()
    else:
        raise TypeError("Expected a string URL or a dictionary with a key 'url'.")