minimalcode 1.5.2__py3-none-any.whl

minimalcode/vision.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import base64
+import math
+import time
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx2
+
+from .config import provider_api_key
+from .errors import ToolError
+from .httpclient import (
+    build_client,
+    build_headers,
+    join_url_path,
+    merge_headers,
+    post_json,
+)
+
+# The provider judges formats by content, not by file name, so the tool does the
+# same and labels the data URL with the detected type.
+SUPPORTED_IMAGE_FORMATS = "JPEG, PNG, GIF, or WebP"
+_DETAIL_LEVELS = {"low", "high", "original", "auto"}
+
+
+def image_media_type(data: bytes) -> str | None:
+    """Return the MIME type of a supported image, detected from its bytes."""
+    if not isinstance(data, (bytes, bytearray)):
+        return 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"
+    return None
+
+
+def _message_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict) and isinstance(item.get("text"), str):
+                parts.append(item["text"])
+        return "".join(parts)
+    return ""
+
+
+class ProviderVisionClient:
+    """Provider-hosted image understanding over an OpenAI-compatible endpoint."""
+
+    def __init__(
+        self,
+        name: str,
+        config: dict[str, Any],
+        *,
+        model: str | None = None,
+        transport: httpx2.BaseTransport | None = None,
+    ):
+        self.name = name
+        self.enabled = False
+        self.model = ""
+        self.detail = "auto"
+        self.max_image_bytes = 0
+        self.max_chars = 0
+        self._endpoint = ""
+        self._client: httpx2.Client | None = None
+
+        vision = config.get("vision")
+        if not isinstance(vision, dict):
+            return
+        enabled = vision.get("enabled", False)
+        if not isinstance(enabled, bool):
+            raise ToolError(f"provider {name!r} vision.enabled must be a boolean")
+        if not enabled:
+            return
+
+        base_url = str(vision.get("base_url") or config.get("base_url") or "").rstrip(
+            "/"
+        )
+        try:
+            parsed = urlsplit(base_url)
+            hostname = parsed.hostname
+            _ = parsed.port
+        except ValueError as exc:
+            raise ToolError(
+                f"provider {name!r} has an invalid vision.base_url: {exc}"
+            ) from exc
+        if parsed.scheme not in {"http", "https"} or not hostname:
+            raise ToolError(f"provider {name!r} has an invalid vision.base_url")
+
+        chosen_model = str(vision.get("model") or model or config.get("model") or "")
+        if not chosen_model:
+            raise ToolError(f"provider {name!r} vision requires a model")
+
+        try:
+            timeout = float(vision.get("timeout_seconds", 120))
+            self.max_image_bytes = int(vision.get("max_image_bytes", 32 * 1024 * 1024))
+            self.max_chars = int(vision.get("max_chars", 8000))
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ToolError(
+                f"provider {name!r} has invalid vision numeric settings"
+            ) from exc
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ToolError(f"provider {name!r} has an invalid vision timeout")
+        if self.max_image_bytes < 1 or self.max_chars < 1:
+            raise ToolError(f"provider {name!r} has invalid vision limits")
+
+        detail = str(vision.get("detail", "auto"))
+        if detail not in _DETAIL_LEVELS:
+            raise ToolError(
+                f"provider {name!r} vision.detail must be one of "
+                f"{', '.join(sorted(_DETAIL_LEVELS))}"
+            )
+
+        api_key = provider_api_key(vision) or provider_api_key(config)
+        self._client = build_client(
+            base_url=base_url,
+            headers=build_headers(
+                api_key, merge_headers(config.get("headers"), vision.get("headers"))
+            ),
+            timeout=timeout,
+            transport=transport,
+            trust_env=vision.get("trust_env", config.get("trust_env")),
+        )
+        self._timeout_seconds = timeout
+        self._endpoint = (
+            base_url
+            if urlsplit(base_url).path.rstrip("/").endswith("/chat/completions")
+            else join_url_path(base_url, "chat/completions")
+        )
+        self.model = chosen_model
+        self.detail = detail
+        self.enabled = True
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+
+    def describe(
+        self,
+        media_type: str,
+        data: bytes,
+        *,
+        question: str | None = None,
+    ) -> str:
+        if not self.enabled or self._client is None:
+            raise ToolError(f"read_image is not enabled for provider {self.name!r}")
+        if not isinstance(data, bytes) or not data:
+            raise ToolError("image data must be non-empty bytes")
+        if len(data) > self.max_image_bytes:
+            raise ToolError(
+                f"image is too large: {len(data)} bytes exceeds "
+                f"vision.max_image_bytes ({self.max_image_bytes})"
+            )
+        actual_type = image_media_type(data)
+        if actual_type is None:
+            raise ToolError(
+                f"image data is not one of the supported formats "
+                f"({SUPPORTED_IMAGE_FORMATS})"
+            )
+        if question is not None and not isinstance(question, str):
+            raise ToolError("question must be a string or null")
+        prompt = (question or "").strip() or (
+            "Describe this image in detail and transcribe all visible text verbatim."
+        )
+        encoded = base64.b64encode(data).decode("ascii")
+        payload = {
+            "model": self.model,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": prompt},
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": f"data:{actual_type};base64,{encoded}",
+                                "detail": self.detail,
+                            },
+                        },
+                    ],
+                }
+            ],
+        }
+        body = post_json(
+            self._client,
+            self._endpoint,
+            payload,
+            label="vision",
+            timeout=self._timeout_seconds,
+            deadline=time.monotonic() + self._timeout_seconds,
+        )
+
+        text = self._parse_text(body)
+        if not text.strip():
+            raise ToolError("provider returned an empty image description")
+        if len(text) > self.max_chars:
+            text = text[: self.max_chars] + "\n<description truncated>"
+        return text
+
+    @staticmethod
+    def _parse_text(body: Any) -> str:
+        if not isinstance(body, dict):
+            raise ToolError("provider vision response must be an object")
+        if body.get("error"):
+            raise ToolError(f"provider vision response failed: {body['error']}")
+        choices = body.get("choices")
+        if not isinstance(choices, list) or not choices:
+            raise ToolError("provider vision response has no choices")
+        choice = choices[0]
+        if not isinstance(choice, dict):
+            raise ToolError("provider vision response choice must be an object")
+        message = choice.get("message")
+        if not isinstance(message, dict):
+            raise ToolError("provider vision response has no message")
+        return _message_text(message.get("content"))
+
+
+__all__ = [
+    "SUPPORTED_IMAGE_FORMATS",
+    "ProviderVisionClient",
+    "image_media_type",
+]

minimalcode/web.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import math
+import time
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx2
+
+from .config import provider_api_key
+from .errors import ToolError
+from .httpclient import (
+    build_client,
+    build_headers,
+    join_url_path,
+    merge_headers,
+    post_json,
+)
+
+_MAX_NESTED_ITEMS = 32
+
+
+class ProviderWebClient:
+    """Configurable provider-hosted web tools."""
+
+    def __init__(
+        self,
+        name: str,
+        config: dict[str, Any],
+        *,
+        transport: httpx2.BaseTransport | None = None,
+    ):
+        self.name = name
+        self.enabled = False
+        self.default_count = 0
+        self.max_count = 0
+        self.max_content_chars = 0
+        self._search_path = ""
+        self._fetch_path = ""
+        self._client: httpx2.Client | None = None
+
+        web = config.get("web_tools")
+        if not isinstance(web, dict):
+            return
+        enabled = web.get("enabled", False)
+        if not isinstance(enabled, bool):
+            raise ToolError(f"provider {name!r} web_tools.enabled must be a boolean")
+        if not enabled:
+            return
+
+        base_url = str(web.get("base_url") or "").rstrip("/")
+        try:
+            parsed = urlsplit(base_url)
+            hostname = parsed.hostname
+            _ = parsed.port
+        except ValueError as exc:
+            raise ToolError(
+                f"provider {name!r} has an invalid web_tools.base_url: {exc}"
+            ) from exc
+        if parsed.scheme not in {"http", "https"} or not hostname:
+            raise ToolError(f"provider {name!r} has an invalid web_tools.base_url")
+        required = (
+            web.get("search_path"),
+            web.get("fetch_path"),
+            web.get("timeout_seconds"),
+            web.get("default_count"),
+            web.get("max_count"),
+            web.get("max_content_chars"),
+        )
+        if any(value in (None, "") for value in required):
+            raise ToolError(
+                f"provider {name!r} web_tools requires paths, timeout, "
+                "counts, and max_content_chars"
+            )
+
+        try:
+            timeout = float(web["timeout_seconds"])
+            self.default_count = int(web["default_count"])
+            self.max_count = int(web["max_count"])
+            self.max_content_chars = int(web["max_content_chars"])
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ToolError(
+                f"provider {name!r} has invalid web_tools numeric settings"
+            ) from exc
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ToolError(f"provider {name!r} has invalid web_tools timeout")
+        if self.default_count < 1 or self.max_count < self.default_count:
+            raise ToolError(f"provider {name!r} has invalid web result limits")
+        if self.max_content_chars < 1:
+            raise ToolError(f"provider {name!r} has invalid max_content_chars")
+        self._timeout_seconds = timeout
+
+        api_key = provider_api_key(web) or provider_api_key(config)
+        self._client = build_client(
+            base_url=base_url,
+            headers=build_headers(
+                api_key, merge_headers(config.get("headers"), web.get("headers"))
+            ),
+            timeout=timeout,
+            transport=transport,
+            trust_env=web.get("trust_env", config.get("trust_env")),
+        )
+        self._endpoint = base_url
+        self._search_path = str(web["search_path"]).strip("/")
+        self._fetch_path = str(web["fetch_path"]).strip("/")
+        self.enabled = True
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        if not self.enabled or self._client is None:
+            raise ToolError(f"web tools are not enabled for provider {self.name!r}")
+        return post_json(
+            self._client,
+            join_url_path(self._endpoint, path),
+            payload,
+            label="web",
+            timeout=self._timeout_seconds,
+            deadline=time.monotonic() + self._timeout_seconds,
+        )
+
+    def search(
+        self,
+        query: str,
+        count: int | None = None,
+        need_content: bool = False,
+        ori_question: str | None = None,
+        localization: str | None = None,
+    ) -> dict[str, Any]:
+        if not self.enabled:
+            raise ToolError(f"web tools are not enabled for provider {self.name!r}")
+        if not isinstance(query, str) or not query.strip() or len(query) > 128:
+            raise ToolError("query must contain 1-128 characters")
+        if count is not None and (
+            not isinstance(count, int) or isinstance(count, bool)
+        ):
+            raise ToolError("count must be an integer")
+        if not isinstance(need_content, bool):
+            raise ToolError("need_content must be a boolean")
+        if ori_question is not None and not isinstance(ori_question, str):
+            raise ToolError("ori_question must be a string or null")
+        if localization is not None and not isinstance(localization, str):
+            raise ToolError("localization must be a string or null")
+        effective_count = self.default_count if count is None else count
+        if not 1 <= effective_count <= self.max_count:
+            raise ToolError(f"count must be from 1 to {self.max_count}")
+        payload: dict[str, Any] = {
+            "query": query.strip(),
+            "count": effective_count,
+            "need_content": need_content,
+        }
+        if ori_question:
+            payload["ori_question"] = ori_question
+        if localization:
+            payload["localization"] = localization
+        data = self._post(self._search_path, payload)
+        results = data.get("results", [])
+        if not isinstance(results, list):
+            raise ToolError("provider web search results must be a list")
+        # Provider output is untrusted: keep only object results, cap the count,
+        # and bound every text field so one search cannot flood the context.
+        objects = [item for item in results if isinstance(item, dict)]
+        normalized = [
+            self._normalize_result(item)
+            for item in objects[: min(effective_count, self.max_count)]
+        ]
+        return {"status": "success", "results": normalized}
+
+    def _normalize_result(self, item: dict[str, Any]) -> dict[str, Any]:
+        return {key: self._normalize_value(value) for key, value in item.items()}
+
+    def _normalize_value(self, value: Any, depth: int = 0) -> Any:
+        if isinstance(value, str):
+            if len(value) > self.max_content_chars:
+                return value[: self.max_content_chars] + "\n<content truncated>"
+            return value
+        if depth >= 32:
+            return "<nested value omitted>"
+        if isinstance(value, dict):
+            items = list(value.items())
+            normalized = {
+                key: self._normalize_value(item, depth + 1)
+                for key, item in items[:_MAX_NESTED_ITEMS]
+            }
+            if len(items) > _MAX_NESTED_ITEMS:
+                normalized.setdefault("<truncated>", "<more object keys omitted>")
+            return normalized
+        if isinstance(value, list):
+            normalized = [
+                self._normalize_value(item, depth + 1)
+                for item in value[:_MAX_NESTED_ITEMS]
+            ]
+            if len(value) > _MAX_NESTED_ITEMS:
+                normalized.append("<more list items omitted>")
+            return normalized
+        return value
+
+    def fetch(self, url: str) -> dict[str, Any]:
+        if not self.enabled:
+            raise ToolError(f"web tools are not enabled for provider {self.name!r}")
+        try:
+            parsed = urlsplit(url) if isinstance(url, str) else None
+            hostname = parsed.hostname if parsed is not None else None
+            if parsed is not None:
+                _ = parsed.port
+        except ValueError as exc:
+            raise ToolError(
+                f"url must be an absolute HTTP or HTTPS URL: {exc}"
+            ) from exc
+        if parsed is None or parsed.scheme not in {"http", "https"} or not hostname:
+            raise ToolError("url must be an absolute HTTP or HTTPS URL")
+        data = self._post(self._fetch_path, {"url": url})
+        title = data.get("title")
+        if title is None:
+            title = ""
+        content = data.get("content")
+        if content is None:
+            # An explicit JSON null means "no readable content", the same way a
+            # null title is tolerated above.
+            content = ""
+        if not isinstance(title, str):
+            raise ToolError("provider web fetch title must be a string")
+        if not isinstance(content, str):
+            raise ToolError("provider web fetch content must be a string")
+        title_truncated = len(title) > self.max_content_chars
+        if title_truncated:
+            title = title[: self.max_content_chars] + "...<title truncated>"
+        truncated = len(content) > self.max_content_chars
+        if truncated:
+            content = content[: self.max_content_chars] + "\n<content truncated>"
+        return {
+            "status": "success",
+            "title": title,
+            "content": content,
+            "truncated": truncated or title_truncated,
+        }