hammad-python 0.0.23__py3-none-any.whl → 0.0.25__py3-none-any.whl

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,36 @@ if TYPE_CHECKING:
         run_agent_iter,
         async_run_agent,
         async_run_agent_iter,
+        agent_decorator,
+    )
+    from .graphs import (
+        GraphBuilder,
+        GraphContext,
+        GraphEnd,
+        GraphEvent,
+        GraphHistoryEntry,
+        GraphNode,
+        GraphState,
+        GraphResponse,
+        GraphStream,
+        GraphResponseChunk,
+        BaseGraph,
+        BasePlugin,
+        PluginDecorator,
+        PydanticGraphContext,
+        AudioPlugin,
+        ServePlugin,
+        MemoryPlugin,
+        HistoryPlugin,
+        SettingsPlugin,
+        ActionNode,
+        ActionInfo,
+        ActionSettings,
+        action,
+        plugin,
+        select,
+        SelectionStrategy,
+        ActionDecorator,
     )
     from .models.embeddings import (
         Embedding,
@@ -42,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
@@ -73,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",
@@ -87,6 +130,35 @@ __all__ = [
     "run_agent_iter",
     "async_run_agent",
     "async_run_agent_iter",
+    "agent_decorator",
+    # hammad.genai.graphs
+    "GraphBuilder",
+    "GraphContext",
+    "GraphEnd",
+    "GraphEvent",
+    "GraphHistoryEntry",
+    "GraphNode",
+    "GraphState",
+    "GraphResponse",
+    "GraphStream",
+    "GraphResponseChunk",
+    "BaseGraph",
+    "BasePlugin",
+    "PluginDecorator",
+    "PydanticGraphContext",
+    "AudioPlugin",
+    "ServePlugin",
+    "MemoryPlugin",
+    "HistoryPlugin",
+    "SettingsPlugin",
+    "ActionNode",
+    "ActionInfo",
+    "ActionSettings",
+    "action",
+    "plugin",
+    "select",
+    "SelectionStrategy",
+    "ActionDecorator",
     # hammad.genai.models.embeddings
     "Embedding",
     "EmbeddingModel",
@@ -108,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",

hammad/genai/a2a/__init__.py

@@ -0,0 +1,32 @@
+"""hammad.genai.a2a"""
+
+from typing import TYPE_CHECKING
+from ..._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from fasta2a import (
+        FastA2A
+    )
+    from .workers import (
+        as_a2a_app,
+        GraphWorker,
+        AgentWorker,
+    )
+
+
+__all__ = (
+    # fasta2a
+    "FastA2A",
+    # hammad.genai.a2a.workers
+    "as_a2a_app",
+    "GraphWorker",
+    "AgentWorker",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)