ContentParser

@classmethod
def register(cls, content_type: str, content_class: type[BaseContent]) -> None:
    """Register a new content type.

    Example:
        # Add support for new "reflection" type
        class ReflectionContent(BaseContent):
            type: Literal["reflection"] = "reflection"
            reflection: str
            confidence: float

        ContentParser.register("reflection", ReflectionContent)
    """
    cls._registry[content_type] = content_class

@classmethod
def parse(cls, data: dict[str, Any]) -> BaseContent:
    """Parse content block data to appropriate type.

    Returns:
        - Specific type (TextContent, ReasoningContent, etc.) if known
        - GenericContent if unknown type or parsing fails
        - Always succeeds - never raises for unknown types!
    """
    content_type = data.get("type", "unknown")

    # Try known type
    if content_type in cls._registry:
        content_class = cls._registry[content_type]
        try:
            return content_class(**data)
        except Exception as e:
            # Parsing failed - fall back to generic
            # This ensures we never lose data due to validation errors
            warnings.warn(
                f"Failed to parse {content_type} as {content_class.__name__}: {e}. Using GenericContent instead.",
                UserWarning,
                stacklevel=2,
            )
            return GenericContent(**data)

    # Unknown type - use generic (KEY FOR FORWARD COMPATIBILITY!)
    # Ensure 'type' field is present for GenericContent validation
    data_with_type = {"type": content_type, **data}
    return GenericContent(**data_with_type)