tena 0.1.0__py3-none-any.whl

tena/__init__.py

@@ -0,0 +1,3 @@
+from tena.image import GeneratedImage, ImageModel, draw, suffix_for_mime_type
+
+__all__ = ["GeneratedImage", "ImageModel", "draw", "suffix_for_mime_type"]

tena/image.py

@@ -0,0 +1,990 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+from contextlib import ExitStack
+import hashlib
+import json
+import logging
+import mimetypes
+import os
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+import urllib.parse
+import urllib.request
+
+from dotenv import load_dotenv
+from google import genai
+from google.genai import types
+from google.genai.types import HttpOptions
+import httpx
+from openai import AsyncOpenAI
+
+ClientKind = Literal[
+    "openai",
+    "openrouter",
+    "gemini-interactions",
+    "gemini-generate-content",
+]
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class GeneratedImage:
+    data: bytes
+    mime_type: str
+
+
+@dataclass(frozen=True)
+class ImageModel:
+    model_displayname: str
+    model_realname: str
+    client: ClientKind
+    api_key_env: str
+    base_url: str | None = None
+    default_mime_type: str = "image/png"
+
+
+@dataclass(frozen=True)
+class _ResolvedInputImage:
+    path: Path
+    mime_type: str
+
+
+IMAGE_MODELS: Mapping[str, ImageModel] = {
+    "openrouter/gpt-image-2": ImageModel(
+        model_displayname="GPT Image 2 (OpenRouter)",
+        model_realname="openai/gpt-image-2",
+        client="openrouter",
+        api_key_env="OPENROUTER_API_KEY",
+        base_url="https://openrouter.ai/api/v1",
+    ),
+    "zenmux/gpt-image-2": ImageModel(
+        model_displayname="GPT Image 2 (Zenmux)",
+        model_realname="openai/gpt-image-2",
+        client="openai",
+        api_key_env="ZENMUX_API_KEY",
+        base_url="https://zenmux.ai/api/v1",
+    ),
+    "302ai/gpt-image-2": ImageModel(
+        model_displayname="GPT Image 2 (302AI)",
+        model_realname="gpt-image-2",
+        client="openai",
+        api_key_env="AI302_API_KEY",
+        base_url="https://api.302.ai/v1",
+    ),
+    "zenmux/gemini-3.1-flash-image": ImageModel(
+        model_displayname="Gemini-3.1-Flash-Image (Zenmux)",
+        model_realname="google/gemini-3.1-flash-image",
+        client="gemini-generate-content",
+        api_key_env="ZENMUX_API_KEY",
+        base_url="https://zenmux.ai/api/vertex-ai",
+    ),
+    "google/gemini-3.1-flash-image": ImageModel(
+        model_displayname="Gemini-3.1-Flash-Image (Google)",
+        model_realname="gemini-3.1-flash-image",
+        client="gemini-interactions",
+        api_key_env="GEMINI_API_KEY",
+    ),
+}
+
+IMAGE_SUFFIXES: Mapping[str, str] = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+}
+
+URL_INPUT_IMAGE_CACHE_DIR = Path("/tmp/tena/input_images")
+URL_DOWNLOAD_TIMEOUT_SECONDS = 30
+OPENROUTER_REQUEST_TIMEOUT_SECONDS = 300
+
+
+def suffix_for_mime_type(mime_type: str) -> str:
+    return IMAGE_SUFFIXES.get(mime_type, ".bin")
+
+
+async def draw(
+    *,
+    model_path: str,
+    prompt: str,
+    size: str = "auto",
+    number: int = 1,
+    input_images: Sequence[str] | None = None,
+    web_search: bool | Mapping[str, Any] = False,
+) -> list[GeneratedImage]:
+    """Generate images with a registered text-to-image model.
+
+    The `size` parameter is intentionally model/client specific:
+    - OpenAI-compatible clients receive it as the API `size` value directly.
+    - OpenRouter receives it as the API `size` value directly.
+    - Gemini clients parse it into their image response config, supporting
+      values like `16:9`, `2K`, and `16:9@2K`.
+    """
+    if number < 1:
+        logger.debug("Rejecting image request with invalid number=%s", number)
+        raise ValueError("number must be greater than or equal to 1")
+    if web_search is not False:
+        logger.debug("Rejecting image request because web_search is not implemented")
+        raise NotImplementedError("web_search is not implemented yet")
+
+    start_time = time.perf_counter()
+    model = _get_image_model(model_path)
+    logger.info(
+        "Starting image generation: model_path=%s model=%s client=%s size=%s "
+        "number=%s input_images=%s prompt_length=%s",
+        model_path,
+        model.model_realname,
+        model.client,
+        size,
+        number,
+        len(input_images or ()),
+        len(prompt),
+    )
+    api_key = _get_api_key(model)
+    resolved_input_images = _resolve_input_images(input_images)
+
+    if model.client == "openai":
+        images = await _draw_with_openai(
+            model=model,
+            api_key=api_key,
+            prompt=prompt,
+            size=size,
+            number=number,
+            input_images=resolved_input_images,
+        )
+    elif model.client == "openrouter":
+        images = await _draw_with_openrouter(
+            model=model,
+            api_key=api_key,
+            prompt=prompt,
+            size=size,
+            number=number,
+            input_images=resolved_input_images,
+        )
+    elif model.client == "gemini-interactions":
+        images = await _draw_with_gemini_interactions(
+            model=model,
+            api_key=api_key,
+            prompt=prompt,
+            size=size,
+            number=number,
+            input_images=resolved_input_images,
+        )
+    elif model.client == "gemini-generate-content":
+        images = await _draw_with_gemini_generate_content(
+            model=model,
+            api_key=api_key,
+            prompt=prompt,
+            size=size,
+            number=number,
+            input_images=resolved_input_images,
+        )
+    else:
+        logger.debug("Unsupported image client resolved: %s", model.client)
+        raise ValueError(f"Unsupported client: {model.client}")
+
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.info(
+        "Finished image generation: model_path=%s images=%s total_bytes=%s "
+        "elapsed=%.2fs",
+        model_path,
+        len(images),
+        _total_image_bytes(images),
+        elapsed_seconds,
+    )
+    return images
+
+
+def _get_image_model(model_path: str) -> ImageModel:
+    model = IMAGE_MODELS.get(model_path)
+    if model is not None:
+        logger.debug(
+            "Resolved image model: model_path=%s display_name=%s client=%s",
+            model_path,
+            model.model_displayname,
+            model.client,
+        )
+        return model
+
+    available_models = ", ".join(sorted(IMAGE_MODELS))
+    logger.debug("Unknown image model requested: model_path=%s", model_path)
+    raise ValueError(
+        f"Unknown model_path: {model_path}. Available models: {available_models}"
+    )
+
+
+def _get_api_key(model: ImageModel) -> str:
+    _load_project_dotenv()
+
+    api_key = os.environ.get(model.api_key_env)
+    if api_key:
+        logger.debug("Resolved API key from environment: env=%s", model.api_key_env)
+        return api_key
+
+    logger.debug("Missing API key environment variable: env=%s", model.api_key_env)
+    raise RuntimeError(
+        f"Missing API key environment variable {model.api_key_env} for "
+        f"{model.model_displayname}"
+    )
+
+
+def _load_project_dotenv() -> None:
+    env_path = Path(__file__).resolve().parents[1] / ".env"
+    logger.debug("Loading dotenv file if present: path=%s", env_path)
+    load_dotenv(dotenv_path=env_path, override=False)
+
+
+def _resolve_input_images(
+    input_images: Sequence[str] | None,
+) -> list[_ResolvedInputImage]:
+    if not input_images:
+        logger.debug("No input images provided")
+        return []
+
+    resolved_images: list[_ResolvedInputImage] = []
+    for index, source in enumerate(input_images, start=1):
+        normalized_source = source.strip()
+        if not normalized_source:
+            logger.debug("Rejecting empty input image value: index=%s", index)
+            raise ValueError("input_images cannot contain empty values")
+        if _is_http_url(normalized_source):
+            resolved_images.append(_resolve_url_input_image(normalized_source))
+        else:
+            resolved_image = _resolve_local_input_image(normalized_source)
+            resolved_images.append(resolved_image)
+            logger.debug(
+                "Resolved local input image: index=%s filename=%s mime_type=%s "
+                "bytes=%s",
+                index,
+                resolved_image.path.name,
+                resolved_image.mime_type,
+                _file_size_or_none(resolved_image.path),
+            )
+
+    logger.debug("Resolved input images: count=%s", len(resolved_images))
+
+    return resolved_images
+
+
+def _is_http_url(value: str) -> bool:
+    parsed = urllib.parse.urlparse(value)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)
+
+
+def _resolve_local_input_image(source: str) -> _ResolvedInputImage:
+    path = Path(source).expanduser()
+    if not path.exists():
+        logger.debug("Local input image does not exist: filename=%s", path.name)
+        raise FileNotFoundError(f"Input image does not exist: {path}")
+    if not path.is_file():
+        logger.debug("Local input image is not a file: filename=%s", path.name)
+        raise ValueError(f"Input image is not a file: {path}")
+
+    mime_type = _infer_image_mime_type(path=path)
+    if mime_type is None:
+        logger.debug(
+            "Could not infer local input image MIME type: filename=%s", path.name
+        )
+        raise ValueError(f"Could not infer image MIME type for: {path}")
+
+    return _ResolvedInputImage(path=path, mime_type=mime_type)
+
+
+def _resolve_url_input_image(url: str) -> _ResolvedInputImage:
+    url_hash = _hash_url(url)
+    host = urllib.parse.urlparse(url).netloc
+    cache_dir = URL_INPUT_IMAGE_CACHE_DIR / hashlib.sha256(url.encode()).hexdigest()
+    metadata_path = cache_dir / "metadata.json"
+    cached_image = _read_cached_url_input_image(url, metadata_path)
+    if cached_image is not None:
+        logger.info(
+            "Using cached URL input image: url_hash=%s host=%s mime_type=%s bytes=%s",
+            url_hash,
+            host,
+            cached_image.mime_type,
+            _file_size_or_none(cached_image.path),
+        )
+        return cached_image
+
+    logger.info("Downloading URL input image: url_hash=%s host=%s", url_hash, host)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    request = urllib.request.Request(url, headers={"User-Agent": "tena/0.1.0"})
+    with urllib.request.urlopen(
+        request,
+        timeout=URL_DOWNLOAD_TIMEOUT_SECONDS,
+    ) as response:
+        data = response.read()
+        header_mime_type = response.headers.get_content_type()
+
+    mime_type = _infer_image_mime_type(
+        path=Path(urllib.parse.urlparse(url).path),
+        data=data,
+        declared_mime_type=header_mime_type,
+    )
+    if mime_type is None:
+        logger.debug(
+            "URL input image MIME type inference failed: url_hash=%s host=%s "
+            "declared_mime_type=%s bytes=%s",
+            url_hash,
+            host,
+            header_mime_type,
+            len(data),
+        )
+        raise ValueError(f"URL did not return a supported image: {url}")
+
+    suffix = _suffix_for_mime_type(mime_type)
+    image_path = cache_dir / f"source{suffix}"
+    temporary_path = cache_dir / f".source{suffix}.tmp"
+    temporary_path.write_bytes(data)
+    temporary_path.replace(image_path)
+
+    metadata = {
+        "url": url,
+        "filename": image_path.name,
+        "mime_type": mime_type,
+    }
+    metadata_path.write_text(
+        json.dumps(metadata, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+
+    logger.info(
+        "Downloaded URL input image: url_hash=%s host=%s mime_type=%s bytes=%s",
+        url_hash,
+        host,
+        mime_type,
+        len(data),
+    )
+    return _ResolvedInputImage(path=image_path, mime_type=mime_type)
+
+
+def _read_cached_url_input_image(
+    url: str,
+    metadata_path: Path,
+) -> _ResolvedInputImage | None:
+    url_hash = _hash_url(url)
+    if not metadata_path.exists():
+        logger.debug("URL input image cache metadata missing: url_hash=%s", url_hash)
+        return None
+
+    try:
+        metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    except OSError:
+        logger.debug(
+            "Could not read URL input image cache metadata: url_hash=%s",
+            url_hash,
+            exc_info=True,
+        )
+        return None
+    except json.JSONDecodeError:
+        logger.debug(
+            "Invalid URL input image cache metadata JSON: url_hash=%s",
+            url_hash,
+            exc_info=True,
+        )
+        return None
+
+    if metadata.get("url") != url:
+        logger.debug(
+            "URL input image cache metadata URL mismatch: url_hash=%s", url_hash
+        )
+        return None
+
+    filename = metadata.get("filename")
+    mime_type = metadata.get("mime_type")
+    if not isinstance(filename, str) or not _is_image_mime_type(mime_type):
+        logger.debug("URL input image cache metadata invalid: url_hash=%s", url_hash)
+        return None
+
+    image_path = metadata_path.parent / filename
+    if not image_path.is_file():
+        logger.debug("URL input image cache file missing: url_hash=%s", url_hash)
+        return None
+
+    return _ResolvedInputImage(path=image_path, mime_type=mime_type)
+
+
+def _infer_image_mime_type(
+    *,
+    path: Path,
+    data: bytes | None = None,
+    declared_mime_type: str | None = None,
+) -> str | None:
+    if _is_image_mime_type(declared_mime_type):
+        return declared_mime_type
+
+    guessed_mime_type, _ = mimetypes.guess_type(path.name)
+    if _is_image_mime_type(guessed_mime_type):
+        return guessed_mime_type
+
+    if data is None:
+        try:
+            data = path.read_bytes()[:32]
+        except OSError:
+            return None
+
+    return _infer_image_mime_type_from_bytes(data)
+
+
+def _infer_image_mime_type_from_bytes(data: bytes) -> str | None:
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if data.startswith((b"GIF87a", b"GIF89a")):
+        return "image/gif"
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    if data.startswith(b"BM"):
+        return "image/bmp"
+    return None
+
+
+def _is_image_mime_type(mime_type: object) -> bool:
+    return isinstance(mime_type, str) and mime_type.startswith("image/")
+
+
+def _suffix_for_mime_type(mime_type: str) -> str:
+    suffix = IMAGE_SUFFIXES.get(mime_type) or mimetypes.guess_extension(mime_type)
+    return suffix or ".img"
+
+
+async def _draw_with_openai(
+    *,
+    model: ImageModel,
+    api_key: str,
+    prompt: str,
+    size: str,
+    number: int,
+    input_images: Sequence[_ResolvedInputImage],
+) -> list[GeneratedImage]:
+    client = AsyncOpenAI(api_key=api_key, base_url=model.base_url)
+    request: dict[str, Any] = {
+        "model": model.model_realname,
+        "prompt": prompt,
+        "n": number,
+    }
+    if size:
+        request["size"] = size
+
+    start_time = time.perf_counter()
+    if input_images:
+        logger.debug(
+            "Calling OpenAI-compatible image edit: model=%s input_images=%s",
+            model.model_realname,
+            len(input_images),
+        )
+        with ExitStack() as stack:
+            request["image"] = [
+                stack.enter_context(input_image.path.open("rb"))
+                for input_image in input_images
+            ]
+            result = await client.images.edit(**request)
+    else:
+        logger.debug(
+            "Calling OpenAI-compatible image generation: model=%s number=%s",
+            model.model_realname,
+            number,
+        )
+        result = await client.images.generate(**request)
+
+    images: list[GeneratedImage] = []
+    for item in result.data:
+        image_base64 = getattr(item, "b64_json", None)
+        if not image_base64:
+            logger.debug("Skipping OpenAI-compatible response item without b64_json")
+            continue
+        mime_type = getattr(item, "mime_type", None) or model.default_mime_type
+        images.append(
+            GeneratedImage(
+                data=base64.b64decode(image_base64),
+                mime_type=mime_type,
+            )
+        )
+
+    if not images:
+        logger.debug("OpenAI-compatible response did not include image data")
+        raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.debug(
+        "OpenAI-compatible image call completed: model=%s response_items=%s "
+        "decoded_images=%s total_bytes=%s elapsed=%.2fs",
+        model.model_realname,
+        len(result.data),
+        len(images),
+        _total_image_bytes(images),
+        elapsed_seconds,
+    )
+    return images
+
+
+async def _draw_with_openrouter(
+    *,
+    model: ImageModel,
+    api_key: str,
+    prompt: str,
+    size: str,
+    number: int,
+    input_images: Sequence[_ResolvedInputImage],
+) -> list[GeneratedImage]:
+    url = _openrouter_images_url(model)
+    request = _build_openrouter_image_request(
+        model=model,
+        prompt=prompt,
+        size=size,
+        number=number,
+        input_images=input_images,
+    )
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    timeout = httpx.Timeout(
+        OPENROUTER_REQUEST_TIMEOUT_SECONDS,
+        connect=URL_DOWNLOAD_TIMEOUT_SECONDS,
+    )
+
+    start_time = time.perf_counter()
+    logger.debug(
+        "Calling OpenRouter image generation: model=%s number=%s input_images=%s",
+        model.model_realname,
+        number,
+        len(input_images),
+    )
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.post(url, headers=headers, json=request)
+    except httpx.RequestError as exc:
+        logger.debug(
+            "OpenRouter image request failed before response: model=%s",
+            model.model_realname,
+            exc_info=True,
+        )
+        raise RuntimeError(f"OpenRouter image request failed: {exc}") from exc
+
+    if response.is_error:
+        message = _extract_openrouter_error_message(response)
+        logger.debug(
+            "OpenRouter image request failed: model=%s status=%s message=%s",
+            model.model_realname,
+            response.status_code,
+            message,
+        )
+        raise RuntimeError(
+            "OpenRouter image request failed with HTTP "
+            f"{response.status_code}: {message}"
+        )
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        logger.debug("OpenRouter response was not valid JSON", exc_info=True)
+        raise RuntimeError(
+            f"Invalid JSON response returned for {model.model_displayname}"
+        ) from exc
+
+    images = _extract_openrouter_images(payload, model)
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.debug(
+        "OpenRouter image call completed: model=%s decoded_images=%s "
+        "total_bytes=%s elapsed=%.2fs",
+        model.model_realname,
+        len(images),
+        _total_image_bytes(images),
+        elapsed_seconds,
+    )
+    return images
+
+
+def _openrouter_images_url(model: ImageModel) -> str:
+    base_url = model.base_url or "https://openrouter.ai/api/v1"
+    return f"{base_url.rstrip('/')}/images"
+
+
+def _build_openrouter_image_request(
+    *,
+    model: ImageModel,
+    prompt: str,
+    size: str,
+    number: int,
+    input_images: Sequence[_ResolvedInputImage],
+) -> dict[str, Any]:
+    request: dict[str, Any] = {
+        "model": model.model_realname,
+        "prompt": prompt,
+        "n": number,
+    }
+    if size:
+        request["size"] = size
+    if input_images:
+        request["input_references"] = [
+            _build_openrouter_input_reference(input_image)
+            for input_image in input_images
+        ]
+    return request
+
+
+def _build_openrouter_input_reference(
+    input_image: _ResolvedInputImage,
+) -> dict[str, dict[str, str] | str]:
+    return {
+        "type": "image_url",
+        "image_url": {
+            "url": _build_image_data_url(input_image),
+        },
+    }
+
+
+def _build_image_data_url(input_image: _ResolvedInputImage) -> str:
+    image_base64 = base64.b64encode(input_image.path.read_bytes()).decode("utf-8")
+    return f"data:{input_image.mime_type};base64,{image_base64}"
+
+
+def _extract_openrouter_images(
+    payload: object,
+    model: ImageModel,
+) -> list[GeneratedImage]:
+    if not isinstance(payload, Mapping):
+        logger.debug("OpenRouter response JSON was not an object")
+        raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+    data = payload.get("data")
+    if not isinstance(data, Sequence) or isinstance(data, (str, bytes, bytearray)):
+        logger.debug("OpenRouter response did not include a data array")
+        raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+    images: list[GeneratedImage] = []
+    for item in data:
+        if not isinstance(item, Mapping):
+            logger.debug("Skipping OpenRouter response item that is not an object")
+            continue
+
+        image_base64 = item.get("b64_json")
+        if not isinstance(image_base64, str) or not image_base64:
+            logger.debug("Skipping OpenRouter response item without b64_json")
+            continue
+
+        media_type = item.get("media_type")
+        mime_type = (
+            media_type if isinstance(media_type, str) else model.default_mime_type
+        )
+        images.append(
+            GeneratedImage(
+                data=base64.b64decode(image_base64),
+                mime_type=mime_type,
+            )
+        )
+
+    if not images:
+        logger.debug("OpenRouter response did not include image data")
+        raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+    return images
+
+
+def _extract_openrouter_error_message(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        message = response.text.strip()
+        return message or response.reason_phrase
+
+    if not isinstance(payload, Mapping):
+        return response.reason_phrase
+
+    error = payload.get("error")
+    if isinstance(error, Mapping):
+        message = error.get("message")
+        if isinstance(message, str) and message:
+            return message
+
+    return response.reason_phrase
+
+
+async def _draw_with_gemini_interactions(
+    *,
+    model: ImageModel,
+    api_key: str,
+    prompt: str,
+    size: str,
+    number: int,
+    input_images: Sequence[_ResolvedInputImage],
+) -> list[GeneratedImage]:
+    start_time = time.perf_counter()
+    logger.debug(
+        "Calling Gemini Interactions image generation: model=%s number=%s "
+        "input_images=%s",
+        model.model_realname,
+        number,
+        len(input_images),
+    )
+    images = await asyncio.gather(
+        *(
+            asyncio.to_thread(
+                _draw_one_with_gemini_interactions,
+                model=model,
+                api_key=api_key,
+                prompt=prompt,
+                size=size,
+                input_images=input_images,
+            )
+            for _ in range(number)
+        )
+    )
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.debug(
+        "Gemini Interactions image calls completed: model=%s decoded_images=%s "
+        "total_bytes=%s elapsed=%.2fs",
+        model.model_realname,
+        len(images),
+        _total_image_bytes(images),
+        elapsed_seconds,
+    )
+    return images
+
+
+def _draw_one_with_gemini_interactions(
+    *,
+    model: ImageModel,
+    api_key: str,
+    prompt: str,
+    size: str,
+    input_images: Sequence[_ResolvedInputImage],
+) -> GeneratedImage:
+    start_time = time.perf_counter()
+    client = genai.Client(
+        api_key=api_key,
+        http_options=HttpOptions(base_url=model.base_url) if model.base_url else None,
+    )
+    request: dict[str, Any] = {
+        "model": model.model_realname,
+        "input": _build_gemini_input(prompt, input_images),
+    }
+    response_format = _parse_gemini_size(size)
+    if response_format is not None:
+        request["response_format"] = response_format
+
+    interaction = client.interactions.create(**request)
+    output_image = getattr(interaction, "output_image", None)
+    if output_image is None:
+        logger.debug("Gemini response did not include output_image")
+        raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+    image_base64 = getattr(output_image, "data", None)
+    if not image_base64:
+        logger.debug("Gemini output_image did not include data")
+        raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+    mime_type = getattr(output_image, "mime_type", None) or model.default_mime_type
+    image = GeneratedImage(
+        data=base64.b64decode(image_base64),
+        mime_type=mime_type,
+    )
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.debug(
+        "Gemini single image call completed: model=%s mime_type=%s bytes=%s "
+        "elapsed=%.2fs",
+        model.model_realname,
+        image.mime_type,
+        len(image.data),
+        elapsed_seconds,
+    )
+    return image
+
+
+async def _draw_with_gemini_generate_content(
+    *,
+    model: ImageModel,
+    api_key: str,
+    prompt: str,
+    size: str,
+    number: int,
+    input_images: Sequence[_ResolvedInputImage],
+) -> list[GeneratedImage]:
+    start_time = time.perf_counter()
+    logger.debug(
+        "Calling Gemini Generate Content image generation: model=%s number=%s "
+        "input_images=%s",
+        model.model_realname,
+        number,
+        len(input_images),
+    )
+    images = await asyncio.gather(
+        *(
+            asyncio.to_thread(
+                _draw_one_with_gemini_generate_content,
+                model=model,
+                api_key=api_key,
+                prompt=prompt,
+                size=size,
+                input_images=input_images,
+            )
+            for _ in range(number)
+        )
+    )
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.debug(
+        "Gemini Generate Content image calls completed: model=%s decoded_images=%s "
+        "total_bytes=%s elapsed=%.2fs",
+        model.model_realname,
+        len(images),
+        _total_image_bytes(images),
+        elapsed_seconds,
+    )
+    return images
+
+
+def _draw_one_with_gemini_generate_content(
+    *,
+    model: ImageModel,
+    api_key: str,
+    prompt: str,
+    size: str,
+    input_images: Sequence[_ResolvedInputImage],
+) -> GeneratedImage:
+    start_time = time.perf_counter()
+    client = genai.Client(
+        api_key=api_key,
+        http_options=HttpOptions(base_url=model.base_url) if model.base_url else None,
+    )
+    response = client.models.generate_content(
+        model=model.model_realname,
+        contents=_build_gemini_generate_content_contents(prompt, input_images),
+        config=_build_gemini_generate_content_config(size),
+    )
+    image = _extract_gemini_generate_content_image(response, model)
+
+    elapsed_seconds = time.perf_counter() - start_time
+    logger.debug(
+        "Gemini Generate Content single image call completed: model=%s "
+        "mime_type=%s bytes=%s elapsed=%.2fs",
+        model.model_realname,
+        image.mime_type,
+        len(image.data),
+        elapsed_seconds,
+    )
+    return image
+
+
+def _build_gemini_input(
+    prompt: str,
+    input_images: Sequence[_ResolvedInputImage],
+) -> str | list[dict[str, str]]:
+    if not input_images:
+        return prompt
+
+    logger.debug("Building Gemini multimodal input: input_images=%s", len(input_images))
+    input_parts: list[dict[str, str]] = []
+    for input_image in input_images:
+        input_parts.append(
+            {
+                "type": "image",
+                "data": base64.b64encode(input_image.path.read_bytes()).decode("utf-8"),
+                "mime_type": input_image.mime_type,
+            }
+        )
+    input_parts.append({"type": "text", "text": prompt})
+    return input_parts
+
+
+def _build_gemini_generate_content_contents(
+    prompt: str,
+    input_images: Sequence[_ResolvedInputImage],
+) -> list[types.Part]:
+    parts = [types.Part.from_text(text=prompt)]
+    for input_image in input_images:
+        parts.append(
+            types.Part.from_bytes(
+                data=input_image.path.read_bytes(),
+                mime_type=input_image.mime_type,
+            )
+        )
+    return parts
+
+
+def _build_gemini_generate_content_config(
+    size: str,
+) -> types.GenerateContentConfig:
+    response_format = _parse_gemini_size(size)
+    image_config = None
+    if response_format is not None:
+        image_config = types.ImageConfig(
+            aspect_ratio=response_format.get("aspect_ratio"),
+            image_size=response_format.get("image_size"),
+        )
+    return types.GenerateContentConfig(
+        response_modalities=["TEXT", "IMAGE"],
+        image_config=image_config,
+    )
+
+
+def _extract_gemini_generate_content_image(
+    response: types.GenerateContentResponse,
+    model: ImageModel,
+) -> GeneratedImage:
+    for part in response.parts or ():
+        inline_data = getattr(part, "inline_data", None)
+        if inline_data is None:
+            continue
+
+        image_data = getattr(inline_data, "data", None)
+        if not image_data:
+            logger.debug("Skipping Gemini Generate Content part without image data")
+            continue
+
+        mime_type = getattr(inline_data, "mime_type", None) or model.default_mime_type
+        if isinstance(image_data, str):
+            image_bytes = base64.b64decode(image_data)
+        else:
+            image_bytes = image_data
+        return GeneratedImage(data=image_bytes, mime_type=mime_type)
+
+    logger.debug("Gemini Generate Content response did not include image data")
+    raise RuntimeError(f"No image data returned for {model.model_displayname}")
+
+
+def _parse_gemini_size(size: str) -> dict[str, str] | None:
+    # Gemini does not use the same size string contract as OpenAI image APIs.
+    # Keep the public `draw` signature simple by translating one string into
+    # Gemini's `response_format` fields here.
+    normalized_size = size.strip()
+    if not normalized_size or normalized_size == "auto":
+        return None
+
+    response_format = {"type": "image"}
+    if "@" in normalized_size:
+        aspect_ratio, image_size = normalized_size.split("@", maxsplit=1)
+        aspect_ratio = aspect_ratio.strip()
+        image_size = image_size.strip()
+        if aspect_ratio:
+            response_format["aspect_ratio"] = aspect_ratio
+        if image_size:
+            response_format["image_size"] = image_size
+        return response_format
+
+    if ":" in normalized_size:
+        response_format["aspect_ratio"] = normalized_size
+        return response_format
+
+    response_format["image_size"] = normalized_size
+    return response_format
+
+
+def _hash_url(url: str) -> str:
+    return hashlib.sha256(url.encode()).hexdigest()[:12]
+
+
+def _file_size_or_none(path: Path) -> int | None:
+    try:
+        return path.stat().st_size
+    except OSError:
+        logger.debug("Could not stat file: filename=%s", path.name, exc_info=True)
+        return None
+
+
+def _total_image_bytes(images: Sequence[GeneratedImage]) -> int:
+    return sum(len(image.data) for image in images)

tena/main.py

@@ -0,0 +1,168 @@
+# coding=utf-8
+#
+# main.py CLI 入口
+#
+#
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from tena.image import IMAGE_MODELS, GeneratedImage, draw
+
+logger = logging.getLogger(__name__)
+
+LOG_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+
+def _build_cli_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tena",
+        description="Generate images with a registered text-to-image model.",
+    )
+    parser.add_argument(
+        "--model-path",
+        choices=sorted(IMAGE_MODELS),
+        required=True,
+        help="Registered image model path.",
+    )
+    parser.add_argument(
+        "--prompt",
+        required=True,
+        help="Text prompt. Use '-' to read the prompt from stdin.",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        required=True,
+        help="Required output image path.",
+    )
+    parser.add_argument(
+        "--size",
+        default="auto",
+        help="Model-specific image size. Defaults to 'auto'.",
+    )
+    parser.add_argument(
+        "--number",
+        type=int,
+        default=1,
+        help="Number of images to generate. Defaults to 1.",
+    )
+    parser.add_argument(
+        "--input-image",
+        action="append",
+        dest="input_images",
+        default=None,
+        help="Reference image path or URL. Repeat to provide multiple images.",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        type=_parse_log_level,
+        metavar="LEVEL",
+        help=(
+            "Log level for stderr output: DEBUG, INFO, WARNING, ERROR, or "
+            "CRITICAL. Defaults to INFO."
+        ),
+    )
+    return parser
+
+
+def _parse_log_level(value: str) -> int:
+    normalized_value = value.upper()
+    level = LOG_LEVELS.get(normalized_value)
+    if level is None:
+        expected_levels = ", ".join(LOG_LEVELS)
+        raise argparse.ArgumentTypeError(
+            f"invalid log level: {value}. Expected one of: {expected_levels}"
+        )
+    return level
+
+
+def _configure_logging(log_level: int) -> None:
+    logging.basicConfig(
+        level=log_level,
+        format="%(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def _read_cli_prompt(prompt: str) -> str:
+    if prompt == "-":
+        return sys.stdin.read()
+    return prompt
+
+
+def _numbered_output_path(output_path: Path, index: int) -> Path:
+    if index == 0:
+        return output_path
+
+    return output_path.with_name(f"{output_path.stem}-{index + 1}{output_path.suffix}")
+
+
+def _write_images(images: Sequence[GeneratedImage], output_path: Path) -> list[Path]:
+    output_path = output_path.expanduser()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    written_paths: list[Path] = []
+    for index, image in enumerate(images):
+        image_path = _numbered_output_path(output_path, index)
+        image_path.write_bytes(image.data)
+        written_paths.append(image_path)
+        logger.debug(
+            "Wrote generated image: path=%s mime_type=%s bytes=%s",
+            image_path,
+            image.mime_type,
+            len(image.data),
+        )
+
+    return written_paths
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_cli_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(args.log_level)
+
+    try:
+        logger.debug(
+            "Starting tena CLI: model_path=%s size=%s number=%s input_images=%s",
+            args.model_path,
+            args.size,
+            args.number,
+            len(args.input_images or ()),
+        )
+        prompt = _read_cli_prompt(args.prompt)
+        images = asyncio.run(
+            draw(
+                model_path=args.model_path,
+                prompt=prompt,
+                size=args.size,
+                number=args.number,
+                input_images=args.input_images,
+            )
+        )
+        written_paths = _write_images(images, args.output)
+    except Exception as exc:
+        logger.debug("tena CLI failed", exc_info=True)
+        print(f"tena: error: {exc}", file=sys.stderr)
+        return 1
+
+    for image_path in written_paths:
+        print(image_path)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tena-0.1.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: tena
+Version: 0.1.0
+Summary: My Text-to-Image kits
+Requires-Python: >=3.10
+Requires-Dist: google-genai>=2.10.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: openai>=2.44.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-dotenv>=1.2.1
+Description-Content-Type: text/markdown
+
+# tena
+
+`tena` provides a small async wrapper for text-to-image model calls.
+
+## Install
+
+Prerequisites:
+
+- Python 3.10+
+- uv
+
+Dependencies are declared in `pyproject.toml`:
+
+- `openai`
+- `google-genai`
+- `httpx`
+- `pytest`
+- `python-dotenv`
+
+## Image generation
+
+### Python API
+
+Use `draw` with a registered `model_path`. The function returns a list of
+`GeneratedImage` objects. Each object contains image bytes and a MIME type.
+
+```python
+import asyncio
+from pathlib import Path
+
+from tena import draw, suffix_for_mime_type
+
+
+async def main() -> None:
+    images = await draw(
+        model_path="openrouter/gpt-image-2",
+        prompt="A clean product photo of a ceramic cup",
+        size="1024x1024",
+        number=1,
+        input_images=[
+            "./reference-1.png",
+            "https://example.com/reference-2.png",
+        ],
+    )
+
+    image = images[0]
+    suffix = suffix_for_mime_type(image.mime_type)
+    Path(f"result{suffix}").write_bytes(image.data)
+
+
+asyncio.run(main())
+```
+
+The package exports the reusable API from `tena/__init__.py`. `tena/main.py` is
+only the CLI entrypoint; core image generation logic lives in `tena/image.py`.
+
+### CLI
+
+The `tena` command is a thin wrapper around the Python API.
+
+Generate one image and write it to a required output path:
+
+```bash
+uv run tena --model-path openrouter/gpt-image-2 --prompt "A clean product photo of a ceramic cup" --output ./result.png --size 1024x1024
+```
+
+The output path supports `~`, including `--output ~/Downloads/result.png` and
+`--output=~/Downloads/result.png`.
+
+Use `-` as the prompt to read from stdin:
+
+```bash
+echo "A simple red cube on a clean white background" | uv run tena --model-path openrouter/gpt-image-2 --prompt - --output ./result.png --size 1024x1024
+```
+
+Generate multiple images with `--number`. The first image uses the exact output
+path, and later images are numbered:
+
+```bash
+uv run tena --model-path zenmux/gpt-image-2 --prompt "A blue sphere" --output ./result.png --number 2 --size 1024x1024
+```
+
+This writes `result.png` and `result-2.png`.
+
+Provide reference images with repeated `--input-image` arguments. Each value can
+be a local file path or an `http`/`https` URL:
+
+```bash
+uv run tena \
+  --model-path openrouter/gpt-image-2 \
+  --prompt "Create a studio product photo using the reference objects" \
+  --input-image ./reference-1.png \
+  --input-image https://example.com/reference-2.png \
+  --output ./result.png \
+  --size 1024x1024
+```
+
+URL images are downloaded to `/tmp/tena/input_images` and cached by URL, so the
+same URL is reused on later runs instead of downloaded again.
+
+CLI logs are written to stderr and default to `INFO`. The generated output paths
+are still written to stdout. Use `--log-level WARNING` to hide normal progress
+logs, or `--log-level DEBUG` for diagnostic details:
+
+```bash
+uv run tena --model-path openrouter/gpt-image-2 --prompt "A blue sphere" --output ./result.png --log-level WARNING
+```
+
+INFO logs include concise request metadata, URL cache/download status, byte
+counts, and elapsed times. DEBUG logs include more detailed SDK and input image
+diagnostics. Logs do not include API keys, full prompts, full input URLs, or
+image data.
+
+### Return object
+
+```python
+@dataclass(frozen=True)
+class GeneratedImage:
+    data: bytes
+    mime_type: str
+```
+
+### Registered models
+
+Models are currently registered in code. `model_path` is the lookup key, and
+`model_realname` is the model id sent to the upstream API.
+
+```python
+@dataclass(frozen=True)
+class ImageModel:
+    model_displayname: str
+    model_realname: str
+    client: Literal[
+        "openai",
+        "openrouter",
+        "gemini-interactions",
+        "gemini-generate-content",
+    ]
+    api_key_env: str
+    base_url: str | None = None
+    default_mime_type: str = "image/png"
+```
+
+Current model paths:
+
+- `302ai/gpt-image-2`
+- `302ai/gemini-3.1-flash-image-preview`
+- `google/gemini-3.1-flash-image`
+- `openrouter/gpt-image-2`
+- `zenmux/gpt-image-2`
+- `zenmux/gemini-3.1-flash-image`
+
+`client` means which upstream API contract is used. OpenAI-compatible gateways
+can use `client="openai"` with a custom `base_url`. OpenRouter uses
+`client="openrouter"` and calls its `/images` unified image generation endpoint
+directly.
+
+Gemini image models use two different API contracts:
+
+- `gemini-interactions` uses Google's Interactions API and is used for direct
+  Google Gemini access.
+- `gemini-generate-content` uses the Generate Content API and is used for
+  Gemini-compatible gateways such as Zenmux and 302AI.
+
+### Environment variables
+
+Set the API key required by the selected model entry. Values can be provided by
+the process environment or by a project-root `.env` file:
+
+- `OPENROUTER_API_KEY`
+- `ZENMUX_API_KEY`
+- `AI302_API_KEY`
+- `GEMINI_API_KEY`
+
+### Gemini size format
+
+Gemini image models use a single `size` string that is parsed into
+the Gemini image response configuration. Interactions requests use
+`response_format`; Generate Content requests use `image_config`.
+
+- `16:9` -> `aspect_ratio`
+- `2K` or `4K` -> `image_size`
+- `16:9@2K` -> both `aspect_ratio` and `image_size`
+- `auto` -> no explicit Gemini `response_format`
+
+OpenAI-compatible and OpenRouter clients pass `size` through as the API `size`
+parameter.
+
+## Not implemented yet
+
+The following parameters are part of the public function signature but are not
+implemented yet:
+
+- `web_search`
+
+Passing `web_search` raises `NotImplementedError`.
+
+## Integration tests
+
+Live image generation tests are grouped under `tests/integration`. Set the API
+key for the model you want to test in the environment or in the project `.env`
+file:
+
+- `OPENROUTER_API_KEY` for `openrouter/gpt-image-2`
+- `ZENMUX_API_KEY` for `zenmux/gpt-image-2`
+
+Then run:
+
+```bash
+pytest tests/integration
+```
+
+Tests with missing API keys are skipped. When a test succeeds, it writes the
+generated image to `~/Downloads` with a `tena-<provider>-gpt-image-2` filename
+prefix.

tena-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+tena/__init__.py,sha256=Rym9hGQdH7Ekw7trrB4JOrPfaEof0VlJRvqAHQD-Mho,154
+tena/image.py,sha256=99smWHfb7mq4BoKZkm3p_LHjOKFBPOqJFJf2EVMDD-Q,31026
+tena/main.py,sha256=pFY4cthIsZo8SGSrPaNFpRR2IDK8-iJiHBh5e2AvYe4,4425
+tena-0.1.0.dist-info/METADATA,sha256=Gts41nVYtGSPzU1_ZnB_NUsnkV9tkjR5JVEqPEKo4NQ,6245
+tena-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tena-0.1.0.dist-info/entry_points.txt,sha256=HphO135bSij_v6F6hX5wkMI-u8I2gufC_VApIZP4ZSc,40
+tena-0.1.0.dist-info/RECORD,,

tena-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tena-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tena = tena.main:main