dm-aioaiagent 0.6.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

dm_aioaiagent/__init__.py

@@ -1,3 +1,4 @@
 from .ai_agent import DMAIAgent
 from .async_ai_agent import DMAioAIAgent
-from .openai_image_message_content import OpenAIImageMessageContent
+from .input_image import InputImage
+from .output_image import OutputImage

dm_aioaiagent/ai_agent.py

@@ -1,22 +1,33 @@
+import copy
 import os
+import re
 import uuid
-from typing import Any
-from pydantic import SecretStr
+from typing import Any, Literal, Optional, Type
+from pydantic import BaseModel, Field, SecretStr
 from itertools import dropwhile
 from threading import Thread
 from langchain.chat_models import init_chat_model
-from langchain_core.tools import BaseTool
+from langchain_core.tools import BaseTool, StructuredTool
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
 from langchain_core.messages import SystemMessage, HumanMessage, AIMessage, ToolMessage
 from langgraph.graph import StateGraph
 from dm_logger import DMLogger
 
+from .output_image import OutputImage
 from .types import *
 
 
 class DMAIAgent:
     MAX_MEMORY_MESSAGES = 20  # Only INT greater than 0
+    ImageMemoryMode = Literal["drop", "keep_last", "keep_all"]
     _ALLOWED_ROLES = ("user", "ai")
+    _VALID_IMAGE_MEMORY_MODES = ("drop", "keep_last", "keep_all")
+    _INVALID_IMAGE_ERROR_MARKERS = (
+        "invalid_image_url",
+        "Could not process image",
+        "Unable to process input image",
+        "INVALID_ARGUMENT",
+    )
 
     def __init__(
         self,
@@ -35,6 +46,9 @@ class DMAIAgent:
         is_memory_enabled: bool = True,
         save_tools_responses_in_memory: bool = True,
         max_memory_messages: int = MAX_MEMORY_MESSAGES,
+        # multimodal
+        enable_image_generation: bool = False,
+        image_memory_mode: ImageMemoryMode = "keep_last",
         # other
         input_output_logging: bool = True,
         node_execution_logging: bool = True,
@@ -44,7 +58,8 @@ class DMAIAgent:
         llm_provider_api_key: str = "",
         llm_provider_base_url: str = ""
     ):
-        self._logger = DMLogger(agent_name)
+        self._agent_name = str(agent_name)
+        self._logger = DMLogger(self._agent_name)
 
         # general
         self._system_message = str(system_message)
@@ -66,6 +81,10 @@ class DMAIAgent:
         self._is_memory_enabled = bool(is_memory_enabled)
         self._save_tools_responses_in_memory = bool(save_tools_responses_in_memory)
         self._max_memory_messages = self._validate_max_memory_messages(max_memory_messages)
+        # multimodal
+        self._enable_image_generation = bool(enable_image_generation)
+        self._image_memory_mode = self._validate_image_memory_mode(image_memory_mode)
+        self._images: list[OutputImage] = []
         # other
         self._input_output_logging = bool(input_output_logging)
         self._node_execution_logging = bool(node_execution_logging)
@@ -84,9 +103,18 @@ class DMAIAgent:
 
         last_message = new_messages[-1]
         if isinstance(last_message, AIMessage):
-            return last_message.content
+            return self._extract_text(last_message)
         return last_message
 
+    @staticmethod
+    def _extract_text(message: AIMessage) -> str:
+        # AIMessage.content may be a plain string (legacy) or a list of standard
+        # v1 content blocks (multimodal). For non-string content collect every
+        # text block; if there are none, return empty string.
+        if isinstance(message.content, str):
+            return message.content
+        return "".join(b["text"] for b in message.content_blocks if b.get("type") == "text")
+
     def run_messages(
         self,
         messages: list[InputMessage],
@@ -98,8 +126,6 @@ class DMAIAgent:
     ) -> list[BaseMessage]:
         if ls_metadata is None:
             ls_metadata = {}
-        if isinstance(ls_run_id, uuid.UUID):
-            ls_run_id = ls_run_id
         if isinstance(ls_thread_id, uuid.UUID):
             ls_metadata["thread_id"] = ls_thread_id
 
@@ -118,8 +144,48 @@ class DMAIAgent:
     def memory_messages(self) -> list[BaseMessage]:
         return self._memory_messages
 
+    @property
+    def images(self) -> tuple[OutputImage, ...]:
+        return tuple(self._images)
+
     def clear_memory_messages(self) -> None:
         self._memory_messages.clear()
+        self._images.clear()
+
+    def as_tool(
+        self,
+        *,
+        description: str,
+        name: Optional[str] = None,
+        args_schema: Optional[Type[BaseModel]] = None,
+    ) -> BaseTool:
+        # Wraps this agent as a StructuredTool callable from another agent
+        # (multi-agent composition). Default tool name is derived from
+        # `agent_name` by lowercasing and replacing every non-[a-z0-9] run
+        # with a single underscore (matches the regex `[a-z0-9_]+`). Default
+        # args_schema is a single `query: str` field. `description` is required
+        # — without it the parent model has no signal for when to call.
+        if not description:
+            raise ValueError("`description` is required for as_tool().")
+        tool_name = name if name else self._sanitize_tool_name(self._agent_name)
+        schema = args_schema if args_schema is not None else self._default_tool_args_schema()
+        return StructuredTool.from_function(
+            name=tool_name,
+            description=description,
+            args_schema=schema,
+            func=lambda query, **kw: self.run(query),
+        )
+
+    @staticmethod
+    def _sanitize_tool_name(raw: str) -> str:
+        sanitized = re.sub(r"[^a-z0-9]+", "_", raw.lower()).strip("_")
+        return sanitized or "agent"
+
+    @staticmethod
+    def _default_tool_args_schema() -> Type[BaseModel]:
+        class _AgentToolInput(BaseModel):
+            query: str = Field(..., description="User query for the wrapped agent.")
+        return _AgentToolInput
 
     def _prepare_messages_node(self, state: State) -> State:
         messages = state["messages"] or [{"role": "user", "content": ""}]
@@ -129,16 +195,17 @@ class DMAIAgent:
                 role = item.get("role")
                 content = item.get("content")
                 if not role or role not in self._ALLOWED_ROLES or not content:
+                    self._logger.debug("Skipped malformed input dict", role=role, content_type=type(content).__name__)
                     continue
-                if role == "ai":
-                    MessageClass = AIMessage
-                else:
-                    MessageClass = HumanMessage
-                state["messages"].append(MessageClass(content))
+                # content may be a plain str (legacy) or a list of v1 standard
+                # content blocks (multimodal: text + image/audio/video/file).
+                # Both shapes are accepted by HumanMessage/AIMessage as-is.
+                MessageClass = AIMessage if role == "ai" else HumanMessage
+                state["messages"].append(MessageClass(content=content))
             elif isinstance(item, BaseMessage):
                 state["messages"].append(item)
 
-        if self._input_output_logging:
+        if self._input_output_logging and state["messages"]:
             self._logger.debug(f'Query:\n{state["messages"][-1].content}')
         if self._is_memory_enabled:
             state["messages"] = self._memory_messages + state["messages"]
@@ -152,7 +219,8 @@ class DMAIAgent:
         except Exception as e:
             self._logger.error(e)
             if second_attempt:
-                if "invalid_image_url" in str(e):
+                err_str = str(e)
+                if any(m in err_str for m in self._INVALID_IMAGE_ERROR_MARKERS):
                     response = self._response_if_invalid_image
                 else:
                     response = self._response_if_request_fail
@@ -221,8 +289,19 @@ class DMAIAgent:
                 answer = answer.content
             self._logger.debug(f'Answer:\n{answer}')
 
+        last = state["messages"][-1] if state["messages"] else None
+        new_imgs = OutputImage.extract_from(last) if isinstance(last, AIMessage) else []
+        if self._image_memory_mode == "drop":
+            self._images = list(new_imgs)
+        elif self._image_memory_mode == "keep_last":
+            if new_imgs:
+                self._images = list(new_imgs)
+        else:  # keep_all
+            self._images.extend(new_imgs)
+
         if self._is_memory_enabled:
             messages_to_memory = state["messages"][-self._max_memory_messages:]
+            messages_to_memory = self._apply_image_memory_mode(messages_to_memory)
             if self._save_tools_responses_in_memory:
                 # drop ToolsMessages from start of list
                 self._memory_messages = list(dropwhile(lambda x: isinstance(x, ToolMessage), messages_to_memory))
@@ -234,6 +313,43 @@ class DMAIAgent:
                     self._memory_messages.append(mes)
         return state
 
+    def _apply_image_memory_mode(self, messages: list) -> list:
+        # Returns a list of messages with image blocks stripped according to
+        # self._image_memory_mode. ToolMessages are never touched. Original
+        # message objects are deep-copied before mutation, so callers holding
+        # references (notably state["new_messages"]) see untouched content.
+        if self._image_memory_mode == "keep_all":
+            return list(messages)
+
+        last_user_image_idx = -1
+        last_ai_image_idx = -1
+        for i, m in enumerate(messages):
+            if isinstance(m, ToolMessage) or not isinstance(m.content, list):
+                continue
+            if not any(isinstance(b, dict) and b.get("type") == "image" for b in m.content):
+                continue
+            if isinstance(m, HumanMessage):
+                last_user_image_idx = i
+            elif isinstance(m, AIMessage):
+                last_ai_image_idx = i
+
+        result = []
+        for i, m in enumerate(messages):
+            if isinstance(m, ToolMessage) or not isinstance(m.content, list):
+                result.append(m)
+                continue
+            if self._image_memory_mode == "keep_last" and i in (last_user_image_idx, last_ai_image_idx):
+                result.append(m)
+                continue
+            if not any(isinstance(b, dict) and b.get("type") == "image" for b in m.content):
+                result.append(m)
+                continue
+            placeholder = {"type": "text", "text": "[generated image]" if isinstance(m, AIMessage) else "[image]"}
+            m_copy = copy.deepcopy(m)
+            m_copy.content = [placeholder if (isinstance(b, dict) and b.get("type") == "image") else b for b in m_copy.content]
+            result.append(m_copy)
+        return result
+
     def _messages_router(self, state: State) -> str:
         if self._output_schema:
             return "exit"
@@ -242,7 +358,7 @@ class DMAIAgent:
         return "exit"
 
     def _init_agent(self) -> None:
-        base_kwargs = {"model": self._model}
+        base_kwargs = {"model": self._model, "output_version": "v1"}
         if self._temperature is not None:
             if not isinstance(self._temperature, (int, float)):
                 raise ValueError("Temperature must be a float value.")
@@ -252,9 +368,35 @@ class DMAIAgent:
         if self._llm_provider_base_url:
             base_kwargs["base_url"] = self._llm_provider_base_url
 
+        # Pre-init: OpenAI image generation needs the Responses API.
+        # Detect the requested provider from the model string (init_chat_model
+        # itself does the same) so we can flip use_responses_api before init.
+        if self._enable_image_generation and self._wants_openai_provider(self._model):
+            base_kwargs["use_responses_api"] = True
+
+        # Pre-init: Gemini image-output models also need the IMAGE modality —
+        # but only if the user opted into image generation via the master flag.
+        is_gemini_image = self._is_gemini_image_model(self._model)
+        if self._enable_image_generation and is_gemini_image:
+            base_kwargs["response_modalities"] = ["IMAGE", "TEXT"]
+
         llm = init_chat_model(**base_kwargs)
 
-        provider = self._detect_provider(self._model)
+        provider = self._get_provider(llm)
+
+        # Cross-provider warnings for image-generation flag mismatches.
+        if self._enable_image_generation and self._output_schema:
+            self._logger.warning(
+                "output_schema disables tools — enable_image_generation will be ignored."
+            )
+        if self._enable_image_generation and provider == "anthropic":
+            self._logger.warning("Claude does not support image generation; the flag is ignored.")
+        if not self._enable_image_generation and is_gemini_image:
+            self._logger.warning(
+                f"Model {self._model!r} is image-capable but enable_image_generation=False "
+                f"— set the flag to True to let it draw."
+            )
+
         if provider == "anthropic":
             bind_tool_kwargs = {"tool_choice": {"type": "auto"}}
             if isinstance(self._parallel_tool_calls, bool):
@@ -268,7 +410,13 @@ class DMAIAgent:
 
         if self._is_tools_exists:
             self._tool_map = {t.name: t for t in self._tools}
-            llm = llm.bind_tools(self._tools, **bind_tool_kwargs)
+
+        tools_to_bind: list = list(self._tools)
+        if self._enable_image_generation and provider == "openai" and not self._output_schema:
+            tools_to_bind.append({"type": "image_generation"})
+
+        if tools_to_bind:
+            llm = llm.bind_tools(tools_to_bind, **bind_tool_kwargs)
 
         if self._output_schema:
             llm = llm.with_structured_output(self._output_schema)
@@ -278,14 +426,38 @@ class DMAIAgent:
         self._agent = prompt | llm
 
     @staticmethod
-    def _detect_provider(model: str) -> str:
+    def _get_provider(llm) -> str:
+        # Derive provider tag from the chat-model class name: strip "Chat" prefix
+        # and lowercase. Vertex AI is aliased to Google Generative AI — they are
+        # the same provider for our branching purposes.
+        name = type(llm).__name__
+        if name.startswith("Chat"):
+            name = name[4:]
+        provider = name.lower()
+        if provider == "vertexai":
+            provider = "googlegenerativeai"
+        return provider
+
+    @staticmethod
+    def _wants_openai_provider(model: str) -> bool:
+        # Used pre-init for kwargs that must be set on the constructor
+        # (use_responses_api). OpenAI prefixes are stable; other providers go
+        # through post-init _get_provider().
         if ":" in model:
-            return model.split(":", 1)[0].replace("-", "_").lower()
-        if model.startswith(("gpt-", "o1", "o3")):
-            return "openai"
-        if model.startswith("claude"):
-            return "anthropic"
-        return ""
+            return model.split(":", 1)[0].lower() == "openai"
+        m = model.lower()
+        return m.startswith(("gpt-", "o1", "o3", "o4", "chatgpt"))
+
+    @staticmethod
+    def _is_gemini_image_model(model: str) -> bool:
+        # Model names like "gemini-2.5-flash-image" or
+        # "gemini-2.0-flash-preview-image-generation" — must opt into the
+        # IMAGE modality at init time, otherwise the model still answers in
+        # text only.
+        m = model.lower()
+        if ":" in m:
+            m = m.split(":", 1)[1]
+        return m.startswith("gemini") and "image" in m
 
     def _init_graph(self) -> None:
         workflow = StateGraph(State)
@@ -317,6 +489,14 @@ class DMAIAgent:
             return max_messages_in_memory
         return cls.MAX_MEMORY_MESSAGES
 
+    @classmethod
+    def _validate_image_memory_mode(cls, mode: str) -> str:
+        if mode in cls._VALID_IMAGE_MEMORY_MODES:
+            return mode
+        raise ValueError(
+            f"image_memory_mode must be one of {cls._VALID_IMAGE_MEMORY_MODES}, got {mode!r}."
+        )
+
     @staticmethod
     def _validate_output_schema(schema: OutputSchemaType) -> OutputSchemaType:
         if schema is None:

dm_aioaiagent/async_ai_agent.py

@@ -1,7 +1,9 @@
 import uuid
 import asyncio
-from typing import Any
+from typing import Any, Optional, Type
+from pydantic import BaseModel
 from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.tools import BaseTool, StructuredTool
 
 from .ai_agent import DMAIAgent
 from .types import *
@@ -27,7 +29,7 @@ class DMAioAIAgent(DMAIAgent):
 
         last_message = new_messages[-1]
         if isinstance(last_message, AIMessage):
-            return last_message.content
+            return self._extract_text(last_message)
         return last_message
 
     async def run_messages(
@@ -41,8 +43,6 @@ class DMAioAIAgent(DMAIAgent):
     ) -> list[BaseMessage]:
         if ls_metadata is None:
             ls_metadata = {}
-        if isinstance(ls_run_id, uuid.UUID):
-            ls_run_id = ls_run_id
         if isinstance(ls_thread_id, uuid.UUID):
             ls_metadata["thread_id"] = ls_thread_id
 
@@ -65,7 +65,8 @@ class DMAioAIAgent(DMAIAgent):
         except Exception as e:
             self._logger.error(e)
             if second_attempt:
-                if "invalid_image_url" in str(e):
+                err_str = str(e)
+                if any(m in err_str for m in self._INVALID_IMAGE_ERROR_MARKERS):
                     response = self._response_if_invalid_image
                 else:
                     response = self._response_if_request_fail
@@ -123,3 +124,29 @@ class DMAioAIAgent(DMAIAgent):
 
         await asyncio.gather(*tasks)
         return state
+
+    def as_tool(
+        self,
+        *,
+        description: str,
+        name: Optional[str] = None,
+        args_schema: Optional[Type[BaseModel]] = None,
+    ) -> BaseTool:
+        if not description:
+            raise ValueError("`description` is required for as_tool().")
+        tool_name = name if name else self._sanitize_tool_name(self._agent_name)
+        schema = args_schema if args_schema is not None else self._default_tool_args_schema()
+
+        async def _arun(query: str, **kw):
+            return await self.run(query)
+
+        def _run_sync(query: str, **kw):
+            return asyncio.run(self.run(query))
+
+        return StructuredTool.from_function(
+            name=tool_name,
+            description=description,
+            args_schema=schema,
+            func=_run_sync,
+            coroutine=_arun,
+        )

dm_aioaiagent/input_image.py

@@ -0,0 +1,73 @@
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Optional, Union
+
+from langchain_core.messages import HumanMessage
+
+
+class InputImage:
+    """Cross-provider image input helper.
+
+    Builds a ``HumanMessage`` whose ``.content`` is a list of LangChain v1
+    standard content blocks — one optional ``{"type":"text"}`` followed by
+    one ``{"type":"image"}``. The same message is accepted by OpenAI,
+    Anthropic, and Gemini chat models when used through ``init_chat_model``.
+    """
+
+    @classmethod
+    def from_file(
+        cls,
+        path: Union[str, Path],
+        *,
+        text: Optional[str] = None,
+        mime_type: Optional[str] = None,
+    ) -> HumanMessage:
+        path = Path(path)
+        data = path.read_bytes()
+        if mime_type is None:
+            mime_type, _ = mimetypes.guess_type(str(path))
+            if mime_type is None:
+                raise ValueError(
+                    f"Could not infer mime type for {path!s}. Pass mime_type explicitly."
+                )
+        return cls.from_bytes(data, mime_type=mime_type, text=text)
+
+    @classmethod
+    def from_url(cls, url: str, *, text: Optional[str] = None) -> HumanMessage:
+        block = {"type": "image", "url": str(url)}
+        return cls._build_message(block, text)
+
+    @classmethod
+    def from_base64(
+        cls,
+        data: str,
+        *,
+        mime_type: str,
+        text: Optional[str] = None,
+    ) -> HumanMessage:
+        if not mime_type:
+            raise ValueError("mime_type is required for from_base64().")
+        block = {"type": "image", "base64": str(data), "mime_type": str(mime_type)}
+        return cls._build_message(block, text)
+
+    @classmethod
+    def from_bytes(
+        cls,
+        data: bytes,
+        *,
+        mime_type: str,
+        text: Optional[str] = None,
+    ) -> HumanMessage:
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError("from_bytes() expects bytes-like object.")
+        b64 = base64.b64encode(bytes(data)).decode("ascii")
+        return cls.from_base64(b64, mime_type=mime_type, text=text)
+
+    @staticmethod
+    def _build_message(image_block: dict, text: Optional[str]) -> HumanMessage:
+        content: list[dict] = []
+        if text:
+            content.append({"type": "text", "text": str(text)})
+        content.append(image_block)
+        return HumanMessage(content=content)

dm_aioaiagent/output_image.py

@@ -0,0 +1,60 @@
+import base64
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Union
+
+from langchain_core.messages import BaseMessage
+
+
+@dataclass
+class OutputImage:
+    """Provider-agnostic representation of an AI-generated image."""
+
+    bytes: bytes
+    mime_type: str
+
+    def save(self, path: Union[str, Path]) -> Path:
+        path = Path(path)
+        path.write_bytes(self.bytes)
+        return path
+
+    def to_base64(self) -> str:
+        return base64.b64encode(self.bytes).decode("ascii")
+
+    def __repr__(self) -> str:
+        return f"OutputImage(mime_type={self.mime_type!r}, size={len(self.bytes)} bytes)"
+
+    @classmethod
+    def extract_from(cls, message: BaseMessage) -> List["OutputImage"]:
+        """Extract every image block from ``message.content_blocks``.
+
+        Inline base64 blocks decode directly. URL blocks are fetched via
+        ``urllib`` and the response's ``Content-Type`` is preferred over the
+        block's declared ``mime_type``. Blocks that fail to decode or download
+        are silently skipped — partial extraction beats raising on one bad block.
+        """
+        result: List["OutputImage"] = []
+        for block in message.content_blocks:
+            if not isinstance(block, dict) or block.get("type") != "image":
+                continue
+            mime_type = block.get("mime_type") or "image/png"
+            data: Optional[bytes] = None
+            if block.get("base64"):
+                try:
+                    data = base64.b64decode(block["base64"])
+                except Exception:
+                    continue
+            elif block.get("url"):
+                try:
+                    with urllib.request.urlopen(block["url"]) as resp:
+                        data = resp.read()
+                        ct = resp.headers.get("Content-Type")
+                        if ct:
+                            mime_type = ct.split(";", 1)[0].strip()
+                except Exception:
+                    continue
+            if data is None:
+                continue
+            result.append(cls(bytes=data, mime_type=mime_type))
+        return result

dm_aioaiagent/types.py

@@ -9,27 +9,13 @@ AfterToolCallCallback = Callable[[str, dict, str], None]
 AsyncBeforeToolCallCallback = Callable[[str, dict], Coroutine[Any, Any, None]]
 AsyncAfterToolCallCallback = Callable[[str, dict, str], Coroutine[Any, Any, None]]
 
-class ImageMessageTextItem(TypedDict):
-    type: Literal['text']
-    text: str
-
-
-class ImageMessageImageItem(TypedDict):
-    type: Literal['image_url']
-    image_url: dict
-
-
-class ImageMessage(TypedDict):
-    role: Literal["user"]
-    content: list[Union[ImageMessageTextItem, ImageMessageImageItem]]
-
 
 class TextMessage(TypedDict):
     role: Literal["user", "ai"]
     content: str
 
 
-InputMessage = Union[TextMessage, ImageMessage, BaseMessage]
+InputMessage = Union[TextMessage, BaseMessage]
 
 
 class State(TypedDict):

{dm_aioaiagent-0.6.1.dist-info → dm_aioaiagent-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dm-aioaiagent
-Version: 0.6.1
+Version: 0.7.0
 Summary: This is my custom aioaiagent client
 Home-page: https://pypi.org/project/dm-aioaiagent
 Author: dimka4621
@@ -42,6 +42,8 @@ Requires-Dist: langchain-groq<2.0.0,>=1.0.0; extra == "all"
 Requires-Dist: langchain-mistralai<2.0.0,>=1.0.0; extra == "all"
 Requires-Dist: langchain-deepseek<2.0.0,>=1.0.0; extra == "all"
 Requires-Dist: langchain-ollama<2.0.0,>=1.0.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: Pillow<12.0.0,>=10.0.0; extra == "test"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -234,32 +236,152 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-### Image vision
+### Working with images — input
+
+Use the `InputImage` helper to attach an image to a user message in a way that works **across providers** (OpenAI, Anthropic, Gemini). Each factory returns a ready-to-send `HumanMessage` whose `.content` is a list of LangChain v1 standard content blocks.
 
 ```python
-from dm_aioaiagent import DMAIAgent, OpenAIImageMessageContent
+from dm_aioaiagent import DMAIAgent, InputImage
 
+agent = DMAIAgent(agent_name="image_vision", model="gpt-4o-mini")
 
-def main():
-    # create an agent
-    ai_agent = DMAIAgent(agent_name="image_vision", model="gpt-4o")
+# from a local file (mime type inferred from extension)
+msg_file = InputImage.from_file("photo.png", text="What is in the picture?")
 
-    # create an image message content
-    # NOTE: text argument is optional
-    img_content = OpenAIImageMessageContent(image_url="https://your.domain/image",
-                                            text="Hello, what is shown in the photo?")
+# from a remote URL
+msg_url = InputImage.from_url("https://your.domain/image.png", text="Describe it.")
 
-    # define the conversation messages
-    messages = [
-        {"role": "user", "content": "Hello!"},
-        {"role": "user", "content": img_content},
-    ]
+# from raw bytes / base64 (mime_type required)
+with open("photo.png", "rb") as f:
+    msg_bytes = InputImage.from_bytes(f.read(), mime_type="image/png", text="Describe.")
+msg_b64 = InputImage.from_base64("aGVsbG8=", mime_type="image/png")
 
-    # call an agent
-    new_messages = ai_agent.run_messages(messages)
-    answer = new_messages[-1].content
+answer = agent.run_messages([msg_file])
+print(answer[-1].content_blocks)  # list of standard blocks
+```
 
+**Multiple images per turn.** Each factory builds **one** image message. To attach several images to a single user turn, pass several messages:
 
-if __name__ == "__main__":
-    main()
+```python
+messages = [
+    InputImage.from_file("front.png", text="Compare these two views:"),
+    InputImage.from_file("back.png"),
+]
+agent.run_messages(messages)
 ```
+
+> **`from_url` caveats.** Some providers (notably Anthropic and Gemini) may have stricter rules about remote URLs (allowed hosts, public reachability, redirects). When in doubt — read the file yourself and use `from_file` / `from_bytes`.
+
+### Image generation and edit
+
+The agent can also produce images. The mechanism differs by provider, so two flavours of model are supported:
+
+`enable_image_generation` is the **single master switch** for image output across providers — image generation is off by default, and you opt in with one flag. The flag's effect is provider-specific (different APIs underneath), but the semantics are uniform: turn it on → the agent can draw, leave it off → it can't.
+
+#### OpenAI — `enable_image_generation=True`
+
+Pass the flag to a normal chat-capable OpenAI model (`gpt-5`, `gpt-5-mini`, etc.). Under the hood the agent enables the **Responses API** and binds OpenAI's built-in `image_generation` tool — the model decides on its own when to call it. Plain text turns stay text.
+
+```python
+from dm_aioaiagent import DMAIAgent, OutputImage
+
+agent = DMAIAgent(model="gpt-5-mini", enable_image_generation=True)
+
+agent.run("Draw a small red square on a white background.")
+
+# Generated images surface on agent.images
+for i, img in enumerate(agent.images):
+    img.save(f"out_{i}.png")
+```
+
+The same flag can be combined with regular tools — they coexist. `enable_image_generation=True` is **safe** even when the user only asks for text: the model uses `tool_choice="auto"`.
+
+> Older OpenAI models (`gpt-4o`, `gpt-4.1`, etc.) require **organization verification** at platform.openai.com before they will accept the `image_generation` tool. The `gpt-5` family works on a fresh API key without verification.
+
+#### Gemini — image-output models + the same flag
+
+For Gemini you pick a model whose name contains `image` — e.g. `gemini-2.5-flash-image` (Nano Banana) — **and** turn the flag on. The agent then injects `response_modalities=["IMAGE", "TEXT"]` so the model is allowed to draw.
+
+```python
+agent = DMAIAgent(
+    model="google_genai:gemini-2.5-flash-image",
+    enable_image_generation=True,
+)
+
+agent.run("Generate a small red square.")
+agent.images[0].save("out.png")
+```
+
+If you pick a Gemini image model but forget the flag, the agent logs a warning (`"... is image-capable but enable_image_generation=False — set the flag to True to let it draw."`) and stays in text-only mode.
+
+> **Heads up.** A Gemini image-output model is **not** a general chat model — it tends to draw on every turn, including plain greetings. For mixed workloads use a **two-agent pattern**: a chat agent with the image agent attached as a tool. See [`agent.as_tool()`](#agentas_tool) below.
+
+#### Anthropic — vision only
+
+Claude **cannot generate** images. If you pass `enable_image_generation=True` to a Claude model, the flag is silently ignored and a warning is logged. Image input (vision) works as usual.
+
+### Working with generated images — `OutputImage`
+
+Generated images live in `agent.images` as `OutputImage` instances:
+
+```python
+img = agent.images[0]
+img.bytes        # raw image bytes
+img.mime_type    # e.g. "image/png"
+img.save("out.png")
+img.to_base64()
+```
+
+You can also extract images directly from any `AIMessage`:
+
+```python
+from dm_aioaiagent import OutputImage
+images = OutputImage.extract_from(response_message)  # list[OutputImage]
+```
+
+### Image memory modes
+
+Images in `agent.memory_messages` (the conversation history sent to the LLM on each turn) and in `agent.images` (the property exposing AI-generated images) follow the `image_memory_mode` constructor argument:
+
+| Mode | Memory (history) | `agent.images` |
+|---|---|---|
+| `keep_last` *(default)* | last user-image kept; last AI-image kept; older → `[image]` / `[generated image]` placeholder | last AI-image kept; replaced when a new one arrives |
+| `drop` | every image (user + AI) becomes a placeholder right after the turn | only the AI-image of the **current** turn (then wiped on the next call) |
+| `keep_all` | nothing is stripped — full multimodal history | every AI-image accumulates |
+
+```python
+agent = DMAIAgent(model="gpt-4o-mini", image_memory_mode="keep_last")
+agent.run_messages([InputImage.from_file("photo.png", text="Describe.")])
+agent.run("What colour was dominant?")  # answers based on the image
+```
+
+`agent.clear_memory_messages()` clears both `memory_messages` and `images`.
+
+> Only **AI-generated** images populate `agent.images`. Images you upload via `InputImage` go into history per the rules above but are not exposed on the `images` property.
+
+### `agent.as_tool()`
+
+Wrap any agent as a `StructuredTool` so a *parent* agent can call it like any other tool — the basis for multi-agent composition. Default name is derived from `agent_name` (lowercased, non-alphanumerics replaced with `_`); `description` is required.
+
+```python
+from dm_aioaiagent import DMAIAgent
+
+# specialised image agent
+image_agent = DMAIAgent(
+    agent_name="image_drawer",
+    model="google_genai:gemini-2.5-flash-image",
+    enable_image_generation=True,
+)
+
+# chat agent that delegates drawing to the image agent
+chat_agent = DMAIAgent(
+    model="google_genai:gemini-2.5-flash",
+    tools=[image_agent.as_tool(description="Generates an image from a text prompt.")],
+)
+
+chat_agent.run("Hi! Please draw a small red square.")
+# the chat agent picks the tool, the image agent draws, image lands in image_agent.images
+image_agent.images[0].save("out.png")
+```
+
+The async client (`DMAioAIAgent.as_tool`) returns a tool with both `func` and `coroutine` set, so it can be invoked from sync or async parent agents.

dm_aioaiagent-0.7.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dm_aioaiagent/__init__.py,sha256=HSrPWMzO3tl0Yvmrl__1ZO80hZ0ClHoUzTJbCNcclnE,147
+dm_aioaiagent/ai_agent.py,sha256=TQLlTAM9AZInTnmqDqVeiwYBofYHMon1BEJ0OC54Tv0,22551
+dm_aioaiagent/async_ai_agent.py,sha256=kKXTXu32O-nM98_zVynJB52rOU7TxQcgyuO3FvFqNKM,5808
+dm_aioaiagent/input_image.py,sha256=Rb2VXgxwmZhUrMbSL3giOF2upOtD2SI7fpFYNNx7iWE,2399
+dm_aioaiagent/output_image.py,sha256=V-MRYqUjC30udxPEAHU95bYWapuV7CaPq0DbcMeXzuo,2165
+dm_aioaiagent/types.py,sha256=AvcxvT3YgDoq-9xfuELceGeVcltyONEBpgUMk3CEHVw,720
+dm_aioaiagent-0.7.0.dist-info/METADATA,sha256=n48XBgmbsbZRTVNZU54v0MdTEa3cw1kkBCY84Ql3MhU,15583
+dm_aioaiagent-0.7.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dm_aioaiagent-0.7.0.dist-info/top_level.txt,sha256=CbasLH0KI7zA77XwT6JDCnmRascxKNGvUVV9MgYjHAU,14
+dm_aioaiagent-0.7.0.dist-info/RECORD,,

dm_aioaiagent/openai_image_message_content.py

@@ -1,15 +0,0 @@
-class OpenAIImageMessageContent(list):
-    def __init__(self, image_url: str, text: str = None):
-        content = []
-        if isinstance(text, str):
-            content.append({
-                "type": "text",
-                "text": text
-            })
-        content.append({
-            "type": "image_url",
-            "image_url": {
-                "url": image_url
-            }
-        })
-        super().__init__(content)

dm_aioaiagent-0.6.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-dm_aioaiagent/__init__.py,sha256=VuBGUpDb9woPGO989Otb54ngJSuDzKJOjxy7s3V3V5M,141
-dm_aioaiagent/ai_agent.py,sha256=gZpyfFinYEQ6JgfMqfRvXtTtbkt_goJmtIb0L_fWYDU,13960
-dm_aioaiagent/async_ai_agent.py,sha256=zNw_4lkzQMmDdwhhrgWQ5ZuzqsOvj5KDrARLTY_dgYo,4866
-dm_aioaiagent/openai_image_message_content.py,sha256=EP_i0ERCz7c4KOM8UXp2-AI91ntGC7PGQBc5MMNspcs,434
-dm_aioaiagent/types.py,sha256=XKnKLRPiFGmoMq3vjoV6fxWZ8BiHilM4jvkQU1dO_2c,1036
-dm_aioaiagent-0.6.1.dist-info/METADATA,sha256=evY48_wSPnaVSCwG3RcschJBuh7rcPo4wjMHtTFl74w,9308
-dm_aioaiagent-0.6.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-dm_aioaiagent-0.6.1.dist-info/top_level.txt,sha256=CbasLH0KI7zA77XwT6JDCnmRascxKNGvUVV9MgYjHAU,14
-dm_aioaiagent-0.6.1.dist-info/RECORD,,