hammad-python 0.0.24__py3-none-any.whl → 0.0.26__py3-none-any.whl

hammad/data/types/file.py

@@ -9,7 +9,13 @@ from urllib.parse import urlparse
 from ..models.model import Model
 from ..models.fields import field
 
-__all__ = ("File", "FileSource")
+__all__ = (
+    "File",
+    "FileSource",
+    "read_file_from_path",
+    "read_file_from_url",
+    "read_file_from_bytes",
+)
 
 
 _FILE_SIGNATURES = {
@@ -356,3 +362,70 @@ class File(Model, kw_only=True, dict=True):
                 path=Path(name) if name else None,
             ),
         )
+
+
+def read_file_from_path(
+    path: str | Path,
+    *,
+    encoding: str | None = None,
+) -> File:
+    """Read a file from a filesystem path.
+
+    Args:
+        path: The path to the file to read.
+        encoding: Optional text encoding to use when reading the file.
+                 If not provided, will attempt to detect automatically.
+
+    Returns:
+        A File instance containing the file data.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        PermissionError: If the file cannot be read due to permissions.
+        IsADirectoryError: If the path points to a directory.
+    """
+    return File.from_path(path, encoding=encoding)
+
+
+def read_file_from_url(
+    url: str,
+    *,
+    encoding: str | None = None,
+    timeout: float = 30.0,
+) -> File:
+    """Read a file from a URL.
+
+    Args:
+        url: The URL to fetch the file from.
+        encoding: Optional text encoding to use when reading the response.
+                 If not provided, will attempt to detect automatically.
+        timeout: Request timeout in seconds. Defaults to 30.0.
+
+    Returns:
+        A File instance containing the downloaded data.
+
+    Raises:
+        httpx.RequestError: If the request fails.
+        httpx.HTTPStatusError: If the response has an error status code.
+    """
+    return File.from_url(url, encoding=encoding, timeout=timeout)
+
+
+def read_file_from_bytes(
+    data: bytes,
+    *,
+    type: str | None = None,
+    name: str | None = None,
+) -> File:
+    """Create a file from raw bytes data.
+
+    Args:
+        data: The bytes data to create the file from.
+        type: Optional MIME type of the data. If not provided,
+              will attempt to detect from content signatures.
+        name: Optional name for the file data.
+
+    Returns:
+        A File instance containing the bytes data.
+    """
+    return File.from_bytes(data, type=type, name=name)

hammad/data/types/multimodal/__init__.py

@@ -7,13 +7,25 @@ from typing import TYPE_CHECKING
 from ...._internal import create_getattr_importer
 
 if TYPE_CHECKING:
-    from .image import Image
-    from .audio import Audio
+    from .image import (
+        Image,
+        read_image_from_path,
+        read_image_from_url,
+    )
+    from .audio import (
+        Audio,
+        read_audio_from_path,
+        read_audio_from_url,
+    )
 
 
 __all__ = (
     "Image",
     "Audio",
+    "read_audio_from_path",
+    "read_audio_from_url",
+    "read_image_from_path",
+    "read_image_from_url",
 )
 
 

hammad/data/types/multimodal/audio.py

@@ -1,12 +1,19 @@
 """hammad.data.types.multimodal.audio"""
 
 import httpx
+import mimetypes
+from pathlib import Path
 from typing import Self
 
-from ...types.file import File, FileSource
+from ...types.file import File, FileSource, _FILE_SIGNATURES
 from ...models.fields import field
 
-__all__ = ("Audio",)
+
+__all__ = (
+    "Audio",
+    "read_audio_from_path",
+    "read_audio_from_url",
+)
 
 
 class Audio(File):
@@ -94,3 +101,100 @@ class Audio(File):
                 size=size,
             ),
         )
+
+    @classmethod
+    def from_path(
+        cls,
+        path: str | Path,
+    ) -> Self:
+        """Create an audio file from a file path.
+
+        Args:
+            path: The path to the audio file.
+
+        Returns:
+            A new Audio instance.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            ValueError: If the file is not a valid audio file.
+        """
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            raise FileNotFoundError(f"Audio file not found: {path}")
+
+        if not path_obj.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+
+        # Read file data
+        data = path_obj.read_bytes()
+
+        # Determine MIME type
+        type = None
+
+        # Check file signature first
+        for signature, mime_type in _FILE_SIGNATURES.items():
+            if data.startswith(signature) and mime_type.startswith("audio/"):
+                type = mime_type
+                break
+
+        # Fall back to mimetypes module
+        if not type:
+            type, _ = mimetypes.guess_type(str(path))
+
+        # Validate it's an audio file
+        if type and not type.startswith("audio/"):
+            raise ValueError(f"File is not an audio file: {type}")
+
+        return cls(
+            data=data,
+            type=type,
+            source=FileSource(
+                is_file=True,
+                path=path_obj,
+                size=len(data),
+            ),
+        )
+
+
+def read_audio_from_url(
+    url: str,
+    *,
+    lazy: bool = True,
+    timeout: float = 30.0,
+) -> Audio:
+    """Download and create an audio file from a URL.
+
+    Args:
+        url: The URL to download from.
+        lazy: If True, defer loading content until needed.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        A new Audio instance.
+
+    Raises:
+        httpx.RequestError: If the request fails.
+        httpx.HTTPStatusError: If the response has an error status code.
+        ValueError: If the URL does not point to an audio file.
+    """
+    return Audio.from_url(url, lazy=lazy, timeout=timeout)
+
+
+def read_audio_from_path(
+    path: str | Path,
+) -> Audio:
+    """Create an audio file from a file path.
+
+    Args:
+        path: The path to the audio file.
+
+    Returns:
+        A new Audio instance.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file is not a valid audio file.
+    """
+    return Audio.from_path(path)

hammad/data/types/multimodal/image.py

@@ -1,12 +1,19 @@
 """hammad.data.types.multimodal.image"""
 
 import httpx
+import mimetypes
+from pathlib import Path
 from typing import Self
 
-from ...types.file import File, FileSource
+from ...types.file import File, FileSource, _FILE_SIGNATURES
 from ...models.fields import field
 
-__all__ = ("Image",)
+
+__all__ = (
+    "Image",
+    "read_image_from_path",
+    "read_image_from_url",
+)
 
 
 class Image(File):
@@ -78,3 +85,98 @@ class Image(File):
                 size=size,
             ),
         )
+
+    @classmethod
+    def from_path(
+        cls,
+        path: str | Path,
+    ) -> Self:
+        """Create an image from a file path.
+
+        Args:
+            path: The path to the image file.
+
+        Returns:
+            A new Image instance.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            ValueError: If the file is not a valid image.
+        """
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            raise FileNotFoundError(f"Image file not found: {path}")
+
+        if not path_obj.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+
+        # Read the file data
+        data = path_obj.read_bytes()
+
+        # Detect MIME type
+        type = None
+        for sig, mime in _FILE_SIGNATURES.items():
+            if data.startswith(sig):
+                type = mime
+                break
+
+        # Fallback to mimetypes module
+        if not type:
+            type, _ = mimetypes.guess_type(str(path))
+
+        # Validate it's an image
+        if type and not type.startswith("image/"):
+            raise ValueError(f"File is not an image: {type}")
+
+        return cls(
+            data=data,
+            type=type,
+            source=FileSource(
+                is_file=True,
+                path=path_obj,
+                size=len(data),
+            ),
+        )
+
+
+def read_image_from_url(
+    url: str,
+    *,
+    lazy: bool = True,
+    timeout: float = 30.0,
+) -> Image:
+    """Download and create an image from a URL.
+
+    Args:
+        url: The URL to download from.
+        lazy: If True, defer loading content until needed.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        A new Image instance.
+
+    Raises:
+        httpx.RequestError: If the request fails.
+        httpx.HTTPStatusError: If the response has an error status code.
+        ValueError: If the URL does not point to an image.
+    """
+    return Image.from_url(url, lazy=lazy, timeout=timeout)
+
+
+def read_image_from_path(
+    path: str | Path,
+) -> Image:
+    """Create an image from a file path.
+
+    Args:
+        path: The path to the image file.
+
+    Returns:
+        A new Image instance.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file is not a valid image.
+    """
+    return Image.from_path(path)

hammad/data/types/text.py

@@ -1054,6 +1054,242 @@ class Text(BaseText, Generic[T]):
         return self.render(OutputFormat.ANY)
 
 
+def convert_to_simple_text(
+    obj: Any,
+    *,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    type: str = "simple",
+    heading_level: int = 2,
+    show_in_toc: bool = True,
+    collapsible: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+    sections: Optional[List["BaseText"]] = None,
+    format_config: Optional[Dict["OutputFormat", Dict[str, Any]]] = None,
+    **kwargs,
+) -> "SimpleText":
+    """Convert any object to a SimpleText instance (fully parameterized)."""
+    content = convert_to_text(obj)
+    return SimpleText(
+        content=content,
+        title=title,
+        description=description,
+        type=type,
+        heading_level=heading_level,
+        show_in_toc=show_in_toc,
+        collapsible=collapsible,
+        metadata=metadata or {},
+        sections=sections or [],
+        format_config=format_config or {},
+        **kwargs,
+    )
+
+
+def convert_to_output_text(
+    obj: Any,
+    *,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    type: str = "output",
+    heading_level: int = 2,
+    show_in_toc: bool = True,
+    collapsible: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+    sections: Optional[List["BaseText"]] = None,
+    format_config: Optional[Dict["OutputFormat", Dict[str, Any]]] = None,
+    output_schema: Optional[Any] = None,
+    examples: Optional[List[Any]] = None,
+    validation_rules: Optional[List[str]] = None,
+    error_cases: Optional[List[Dict[str, Any]]] = None,
+    **kwargs,
+) -> "OutputText":
+    """Convert any object to an OutputText instance (fully parameterized)."""
+    content = convert_to_text(obj)
+    return OutputText(
+        content=content,
+        title=title,
+        description=description,
+        type=type,
+        heading_level=heading_level,
+        show_in_toc=show_in_toc,
+        collapsible=collapsible,
+        metadata=metadata or {},
+        sections=sections or [],
+        format_config=format_config or {},
+        output_schema=output_schema,
+        examples=examples or [],
+        validation_rules=validation_rules or [],
+        error_cases=error_cases or [],
+        **kwargs,
+    )
+
+
+def convert_to_output_instructions(
+    obj: Any,
+    *,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    type: str = "output",
+    heading_level: int = 2,
+    show_in_toc: bool = True,
+    collapsible: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+    sections: Optional[List["BaseText"]] = None,
+    format_config: Optional[Dict["OutputFormat", Dict[str, Any]]] = None,
+    output_schema: Optional[Any] = None,
+    examples: Optional[List[Any]] = None,
+    validation_rules: Optional[List[str]] = None,
+    error_cases: Optional[List[Dict[str, Any]]] = None,
+    as_message: bool = False,
+    role: str = "user",
+    as_message_content: bool = False,
+    **kwargs,
+) -> Union[str, Dict[str, Any]]:
+    """
+    Convert any object to output instructions, returning either:
+      - a string (default)
+      - a chat message dict (if as_message=True)
+      - a chat message content param dict (if as_message_content=True)
+
+    Only one of as_message or as_message_content can be True.
+    """
+    if as_message and as_message_content:
+        raise ValueError("Only one of as_message or as_message_content can be True.")
+
+    content = convert_to_text(obj)
+    output_text = OutputText(
+        content=content,
+        title=title,
+        description=description,
+        type=type,
+        heading_level=heading_level,
+        show_in_toc=show_in_toc,
+        collapsible=collapsible,
+        metadata=metadata or {},
+        sections=sections or [],
+        format_config=format_config or {},
+        output_schema=output_schema,
+        examples=examples or [],
+        validation_rules=validation_rules or [],
+        error_cases=error_cases or [],
+        **kwargs,
+    )
+    text_str = str(output_text)
+
+    if as_message:
+        # Return a chat message dict
+        return {"role": role, "content": text_str}
+    elif as_message_content:
+        # Return a chat message content param dict
+        return {"type": "text", "text": text_str}
+    else:
+        # Return as plain string
+        return text_str
+
+
+def convert_to_code_section(
+    obj: Any,
+    *,
+    language: str = "python",
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    type: str = "code",
+    heading_level: int = 2,
+    show_in_toc: bool = True,
+    collapsible: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+    sections: Optional[List["BaseText"]] = None,
+    format_config: Optional[Dict["OutputFormat", Dict[str, Any]]] = None,
+    line_numbers: bool = False,
+    **kwargs,
+) -> "CodeSection":
+    """Convert any object to a CodeSection instance (fully parameterized)."""
+    content = convert_to_text(obj)
+    return CodeSection(
+        content=content,
+        language=language,
+        title=title,
+        description=description,
+        type=type,
+        heading_level=heading_level,
+        show_in_toc=show_in_toc,
+        collapsible=collapsible,
+        metadata=metadata or {},
+        sections=sections or [],
+        format_config=format_config or {},
+        line_numbers=line_numbers,
+        **kwargs,
+    )
+
+
+def convert_to_schema_section(
+    obj: Any,
+    *,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    type: str = "schema",
+    heading_level: int = 2,
+    show_in_toc: bool = True,
+    collapsible: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+    sections: Optional[List["BaseText"]] = None,
+    format_config: Optional[Dict["OutputFormat", Dict[str, Any]]] = None,
+    schema_object: Optional[Any] = None,
+    show_examples: bool = True,
+    table_format: bool = True,
+    **kwargs,
+) -> "SchemaSection":
+    """Convert any object to a SchemaSection instance (fully parameterized)."""
+    content = convert_to_text(obj)
+    return SchemaSection(
+        content=content,
+        title=title,
+        description=description,
+        type=type,
+        heading_level=heading_level,
+        show_in_toc=show_in_toc,
+        collapsible=collapsible,
+        metadata=metadata or {},
+        sections=sections or [],
+        format_config=format_config or {},
+        schema_object=schema_object or obj,
+        show_examples=show_examples,
+        table_format=table_format,
+        **kwargs,
+    )
+
+
+def convert_to_base_text(
+    obj: Any,
+    *,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    type: str = "base",
+    heading_level: int = 2,
+    show_in_toc: bool = True,
+    collapsible: bool = False,
+    metadata: Optional[Dict[str, Any]] = None,
+    sections: Optional[List["BaseText"]] = None,
+    format_config: Optional[Dict["OutputFormat", Dict[str, Any]]] = None,
+    **kwargs,
+) -> "BaseText":
+    """Convert any object to a BaseText instance (fully parameterized)."""
+    content = convert_to_text(obj)
+    return BaseText(
+        content=content,
+        title=title,
+        description=description,
+        type=type,
+        heading_level=heading_level,
+        show_in_toc=show_in_toc,
+        collapsible=collapsible,
+        metadata=metadata or {},
+        sections=sections or [],
+        format_config=format_config or {},
+        **kwargs,
+    )
+
+
 __all__ = (
     "OutputFormat",
     "HeadingStyle",
@@ -1063,4 +1299,10 @@ __all__ = (
     "SimpleText",
     "OutputText",
     "Text",
+    "convert_to_simple_text",
+    "convert_to_output_text",
+    "convert_to_output_instructions",
+    "convert_to_code_section",
+    "convert_to_schema_section",
+    "convert_to_base_text",
 )

hammad/genai/__init__.py

@@ -4,10 +4,17 @@ from typing import TYPE_CHECKING
 from .._internal import create_getattr_importer
 
 
+if TYPE_CHECKING:
+    from .a2a import (
+        as_a2a_app,
+        GraphWorker,
+        AgentWorker,
+    )
 if TYPE_CHECKING:
     from .agents import (
         Agent,
         AgentEvent,
+        AgentSettings,
         AgentResponse,
         AgentStream,
         AgentContext,
@@ -20,6 +27,7 @@ if TYPE_CHECKING:
         run_agent_iter,
         async_run_agent,
         async_run_agent_iter,
+        agent_decorator,
     )
     from .graphs import (
         GraphBuilder,
@@ -46,6 +54,9 @@ if TYPE_CHECKING:
         ActionSettings,
         action,
         plugin,
+        select,
+        SelectionStrategy,
+        ActionDecorator,
     )
     from .models.embeddings import (
         Embedding,
@@ -68,6 +79,7 @@ if TYPE_CHECKING:
         LanguageModelStream,
         run_language_model,
         async_run_language_model,
+        language_model_decorator,
         create_language_model,
     )
     from .models.reranking import run_reranking_model, async_run_reranking_model
@@ -99,9 +111,14 @@ if TYPE_CHECKING:
 
 
 __all__ = [
+    # hammad.genai.a2a
+    "as_a2a_app",
+    "GraphWorker",
+    "AgentWorker",
     # hammad.genai.agents.agent
     "Agent",
     "AgentEvent",
+    "AgentSettings",
     "AgentResponse",
     "AgentStream",
     "AgentContext",
@@ -113,6 +130,7 @@ __all__ = [
     "run_agent_iter",
     "async_run_agent",
     "async_run_agent_iter",
+    "agent_decorator",
     # hammad.genai.graphs
     "GraphBuilder",
     "GraphContext",
@@ -138,6 +156,9 @@ __all__ = [
     "ActionSettings",
     "action",
     "plugin",
+    "select",
+    "SelectionStrategy",
+    "ActionDecorator",
     # hammad.genai.models.embeddings
     "Embedding",
     "EmbeddingModel",
@@ -159,6 +180,7 @@ __all__ = [
     "run_language_model",
     "async_run_language_model",
     "create_language_model",
+    "language_model_decorator",
     # hammad.genai.models.reranking
     "run_reranking_model",
     "async_run_reranking_model",