devflow-engine 1.1.15__tar.gz → 1.1.16__tar.gz

{devflow_engine-1.1.15 → devflow_engine-1.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devflow-engine
-Version: 1.1.15
+Version: 1.1.16
 Summary: DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)
 Author: DevFlow
 License: Proprietary

{devflow_engine-1.1.15 → devflow_engine-1.1.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devflow-engine"
-version = "1.1.15"
+version = "1.1.16"
 description = "DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)"
 readme = "README.md"
 requires-python = ">=3.11"

devflow_engine-1.1.16/src/devflow_engine/errors/vision.py

@@ -0,0 +1,138 @@
+"""Image-aware vision queries via the configured vision tier.
+
+Pi (medium tier, MiniMax) cannot see images. When a clarify-chat
+submitter attaches a screenshot, pi calls this helper through its
+``ask_about_image`` extension tool to ask a specific question about
+the image. The vision tier (``tier.vision`` in the engine's baked
+``~/.devflow/config.toml`` — typically gpt-5.3-codex) sees the image
+content directly and returns a focused text answer.
+
+One image, one question, one round-trip. Pi can call this multiple
+times if it has multiple questions about the same image.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import mimetypes
+from pathlib import Path
+
+
+logger = logging.getLogger(__name__)
+
+
+_MAX_IMAGE_BYTES = 10 * 1024 * 1024  # 10 MB
+_ALLOWED_MIME_PREFIXES = ("image/",)
+_VISION_TIMEOUT_SECONDS = 120
+
+
+class VisionError(RuntimeError):
+    """Wraps any failure path so callers (sidecar route, pi extension)
+    get a stable error class instead of bare RuntimeError."""
+
+
+def _read_image_as_data_url(path: Path) -> str:
+    """Read the file from disk and encode as a data URL the Responses
+    API accepts directly (no separate file-upload round-trip)."""
+    if not path.is_file():
+        raise VisionError(f"image_not_found: {path}")
+    size = path.stat().st_size
+    if size > _MAX_IMAGE_BYTES:
+        raise VisionError(
+            f"image_too_large: {size} bytes > {_MAX_IMAGE_BYTES} cap"
+        )
+    mime, _ = mimetypes.guess_type(str(path))
+    if not mime or not mime.startswith(_ALLOWED_MIME_PREFIXES):
+        raise VisionError(f"image_bad_mime: {mime!r} (not image/*)")
+    data = path.read_bytes()
+    b64 = base64.b64encode(data).decode("ascii")
+    return f"data:{mime};base64,{b64}"
+
+
+def invoke_image_query(
+    *,
+    repo_root: Path,
+    image_path: Path,
+    question: str,
+) -> str:
+    """Ask the vision tier one focused question about one image.
+
+    Returns the assistant's plain-text answer. Raises VisionError on
+    any setup/IO/auth failure; raises through the underlying LLM
+    exception on provider failure.
+
+    Pi's extension prompt encourages ONE focused question per call
+    rather than 'describe the image' — the latter wastes context and
+    invites the model to invent details. Examples that work well:
+      'what error text is visible in this screenshot?'
+      'what colour is the highlighted button in the upper right?'
+      'is the Submit button enabled or greyed out?'
+    """
+    if not question.strip():
+        raise VisionError("question_empty")
+
+    # Local imports — keep module cheap on non-vision paths.
+    from ..llm.invoke import _load_global_llm_cfg, _tier_config
+    from ..llm.provider_api import (
+        load_openai_api_settings,
+        openai_response_text,
+        openai_responses_create,
+    )
+
+    data_url = _read_image_as_data_url(image_path)
+
+    # Resolve tier.vision config directly — invoke_llm doesn't have a
+    # content-blocks path (it's prompt:str-only), so we go straight to
+    # the provider helper with the resolved settings.
+    cfg = _load_global_llm_cfg()
+    tier = _tier_config("vision", cfg)
+    if not tier:
+        raise VisionError(
+            "vision_tier_not_configured: add [tiers.vision] with "
+            "mode='api', apiProvider='openai', apiModel='gpt-5.3-codex' "
+            "to ~/.devflow/config.toml"
+        )
+    provider = str(tier.get("apiProvider") or "openai").strip().lower()
+    if provider != "openai":
+        raise VisionError(
+            f"vision_tier_bad_provider: {provider!r} (only 'openai' supported)"
+        )
+    model = str(tier.get("apiModel") or "gpt-5.3-codex").strip()
+
+    settings = load_openai_api_settings(
+        repo_root=repo_root, provider="openai", model=model,
+    )
+
+    content_blocks = [
+        {"type": "input_image", "image_url": data_url, "detail": "auto"},
+        {
+            "type": "input_text",
+            "text": (
+                "You are answering a single targeted question about the "
+                "image above on behalf of an automated bug-triage agent. "
+                "Be precise and concise — your answer feeds back into a "
+                "downstream LLM that needs facts, not flowery prose. If "
+                "the image doesn't contain the information needed to "
+                "answer, say so plainly.\n\n"
+                f"Question: {question.strip()}"
+            ),
+        },
+    ]
+
+    logger.info(
+        "vision: invoking %s image=%s question_chars=%d",
+        model, image_path.name, len(question),
+    )
+    try:
+        response = openai_responses_create(
+            settings=settings,
+            content_blocks=content_blocks,
+            timeout_seconds=_VISION_TIMEOUT_SECONDS,
+        )
+    except RuntimeError as exc:
+        raise VisionError(f"vision_provider_error: {exc}") from exc
+    answer = openai_response_text(response).strip()
+    if not answer:
+        raise VisionError("vision_empty_response")
+    return answer

{devflow_engine-1.1.15 → devflow_engine-1.1.16}/src/devflow_engine/llm/provider_api.py

@@ -332,14 +332,33 @@ def _openai_text_format_for_response_contract(response_contract: str | None) ->
 def openai_responses_create(
     *,
     settings: OpenAiApiSettings,
-    prompt: str,
+    prompt: str | None = None,
+    content_blocks: list[dict[str, Any]] | None = None,
     timeout_seconds: int | None,
     response_contract: str | None = None,
 ) -> dict[str, Any]:
-    payload: dict[str, Any] = {
-        "model": settings.model,
-        "input": prompt,
-    }
+    """Call OpenAI's Responses API.
+
+    Two input shapes:
+    - ``prompt=<str>`` (legacy / default text-only): packed as
+      ``input: <str>`` per OpenAI's documented shorthand.
+    - ``content_blocks=[{...}]`` (vision / multimodal): packed as
+      ``input: [{role: 'user', content: [<blocks>]}]`` per the
+      Responses API content-array spec. Each block is a dict with at
+      least ``type`` ('input_text' or 'input_image'); image blocks
+      use ``image_url`` (data URL or HTTPS URL).
+
+    Callers must supply exactly one of the two; we raise otherwise."""
+    if (prompt is None) == (content_blocks is None):
+        raise ValueError(
+            "openai_responses_create: provide exactly one of prompt= or content_blocks="
+        )
+
+    payload: dict[str, Any] = {"model": settings.model}
+    if content_blocks is not None:
+        payload["input"] = [{"role": "user", "content": content_blocks}]
+    else:
+        payload["input"] = prompt
     text_format = _openai_text_format_for_response_contract(response_contract)
     if text_format is not None:
         payload["text"] = text_format

{devflow_engine-1.1.15 → devflow_engine-1.1.16}/uv.lock

@@ -172,7 +172,7 @@ wheels = [
 
 [[package]]
 name = "devflow-engine"
-version = "1.1.14"
+version = "1.1.16"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },