src/tools/image_analysis.py

"""
Frox AI — Image Analysis Tool

Deliberately thin: this just calls MorphInferenceEngine.understand_image(),
which runs Morph's own vision encoder + LLM (see
multimodal/vision/encoder.py and inference/engine/morph_engine.py).
No external vision API — "image analysis" here means Morph looking at
the image itself, not a wrapper around someone else's vision model.
"""
from __future__ import annotations

from tools.registry import tool, ToolContext


@tool(
    name="image_analysis",
    description="Analyze an image and answer a question about it",
    timeout=30.0,
)
def image_analysis(ctx: ToolContext, image_path: str, question: str = "Describe this image.") -> dict:
    """
    Args:
        image_path: Path to the image file on disk.
        question: What to ask about the image.

    Plain `def`, not `async def`: engine.understand_image() is a
    synchronous, GPU-bound call — thread-offloaded by the registry
    rather than blocking the event loop for the duration of inference.
    """
    if ctx.engine is None:
        raise RuntimeError("No engine configured in ToolContext (needed for vision)")

    answer = ctx.engine.understand_image(image_path, question)
    return {"image_path": image_path, "question": question, "answer": answer}