xyberos-vision 0.1.0__tar.gz

xyberos_vision-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: xyberos-vision
+Version: 0.1.0
+Summary: Vision plugin (RFC-0019, M8): describe images, OCR, generate images
+License: Apache-2.0
+Keywords: xyberos,plugin,vision,ocr,tesseract,image
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: ocr
+Requires-Dist: pytesseract; extra == "ocr"
+Requires-Dist: pillow; extra == "ocr"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# xyberos-vision
+
+**Vision plugin — RFC-0019, M8.** Describe images (vision model), extract text
+(OCR), and generate images — three tools, three contracts.
+
+## Install
+
+```bash
+pip install -e ./vision
+pip install xyberos-vision[ocr]    # optional: pytesseract + pillow for OCR
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_vision import VisionPlugin
+
+app = create_app()
+app.load_plugin(VisionPlugin())    # key from OPENAI_API_KEY
+
+app.tools.execute("vision_describe", None, image_path="photo.png", prompt="What's in this photo?")
+app.tools.execute("ocr_extract_text", None, image_path="scan.png")
+app.tools.execute("image_generate", None, prompt="a sunset over the ocean", output_path="out.png")
+```
+
+## Tools
+
+| Tool | Backed by |
+| ---- | --------- |
+| `vision_describe(image_path, prompt=...)` | `OpenAICompatibleVision` (`VISION_MODEL`, default `gpt-4o-mini`) |
+| `ocr_extract_text(image_path)` | `TesseractOCR` (lazy `pytesseract` + `pillow`) |
+| `image_generate(prompt, output_path)` | `OpenAIImageGenerator` (`dall-e-3`) |
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+Vision/image-gen are tested via injectable transports; OCR tests skip when
+`pytesseract` is absent.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — vision/multimodal (M8).

xyberos_vision-0.1.0/README.md

@@ -0,0 +1,47 @@
+# xyberos-vision
+
+**Vision plugin — RFC-0019, M8.** Describe images (vision model), extract text
+(OCR), and generate images — three tools, three contracts.
+
+## Install
+
+```bash
+pip install -e ./vision
+pip install xyberos-vision[ocr]    # optional: pytesseract + pillow for OCR
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_vision import VisionPlugin
+
+app = create_app()
+app.load_plugin(VisionPlugin())    # key from OPENAI_API_KEY
+
+app.tools.execute("vision_describe", None, image_path="photo.png", prompt="What's in this photo?")
+app.tools.execute("ocr_extract_text", None, image_path="scan.png")
+app.tools.execute("image_generate", None, prompt="a sunset over the ocean", output_path="out.png")
+```
+
+## Tools
+
+| Tool | Backed by |
+| ---- | --------- |
+| `vision_describe(image_path, prompt=...)` | `OpenAICompatibleVision` (`VISION_MODEL`, default `gpt-4o-mini`) |
+| `ocr_extract_text(image_path)` | `TesseractOCR` (lazy `pytesseract` + `pillow`) |
+| `image_generate(prompt, output_path)` | `OpenAIImageGenerator` (`dall-e-3`) |
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+Vision/image-gen are tested via injectable transports; OCR tests skip when
+`pytesseract` is absent.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — vision/multimodal (M8).

xyberos_vision-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xyberos-vision"
+version = "0.1.0"
+description = "Vision plugin (RFC-0019, M8): describe images, OCR, generate images"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = ["xyberos>=1.0"]
+keywords = ["xyberos", "plugin", "vision", "ocr", "tesseract", "image"]
+
+[project.optional-dependencies]
+ocr = ["pytesseract", "pillow"]
+test = ["pytest"]
+
+[project.entry-points."xyberos.plugins"]
+vision = "xyberos_vision.plugin:plugin"
+
+[tool.setuptools]
+packages = ["xyberos_vision"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xyberos_vision-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xyberos_vision-0.1.0/tests/test_adapters.py

@@ -0,0 +1,56 @@
+"""Tests for the vision adapters (injectable transports / skips, no network)."""
+
+from __future__ import annotations
+
+import base64
+import importlib.util
+
+import pytest
+from xyberos.exceptions.provider import ProviderError
+
+from xyberos_vision import OpenAICompatibleVision, OpenAIImageGenerator, TesseractOCR
+
+
+def _tiny_png(tmp_path) -> str:
+    # A 1x1 PNG so image reading + base64 works without real image deps.
+    path = tmp_path / "img.png"
+    path.write_bytes(b"\x89PNG\r\n\x1a\n\x00\x00\x00\rioEND")
+    return str(path)
+
+
+def test_vision_describe(tmp_path):
+    captured = {}
+
+    def request(method, url, **kwargs):
+        captured.update(kwargs)
+        return 200, {"choices": [{"message": {"content": "A cat"}}]}
+
+    image = _tiny_png(tmp_path)
+    vision = OpenAICompatibleVision(api_key="k", request=request)
+    assert vision.describe(image, "What is this?") == "A cat"
+    content = captured["json_body"]["messages"][0]["content"]
+    assert content[0]["text"] == "What is this?"
+    assert content[1]["type"] == "image_url"
+    assert content[1]["image_url"]["url"].startswith("data:image/png;base64,")
+
+
+def test_vision_requires_key():
+    with pytest.raises(ProviderError, match="OPENAI_API_KEY"):
+        OpenAICompatibleVision(api_key=None, request=lambda *a, **k: (200, {})).describe("x.png", "p")
+
+
+def test_image_generate(tmp_path):
+    def request(method, url, **kwargs):
+        return 200, {"data": [{"b64_json": base64.b64encode(b"PNGDATA").decode("ascii")}]}
+
+    output = tmp_path / "gen.png"
+    gen = OpenAIImageGenerator(api_key="k", request=request)
+    assert gen.generate("a dog", str(output)) == str(output)
+    assert output.read_bytes() == b"PNGDATA"
+
+
+def test_ocr():
+    if importlib.util.find_spec("pytesseract") is None:
+        pytest.skip("pytesseract is not installed")
+    ocr = TesseractOCR()
+    assert isinstance(ocr, TesseractOCR)

xyberos_vision-0.1.0/tests/test_plugin.py

@@ -0,0 +1,32 @@
+"""Tests for loading the vision plugin into a Xyberos app."""
+
+from __future__ import annotations
+
+import base64
+
+from xyberos import create_app
+
+from xyberos_vision import VisionPlugin
+
+
+def test_plugin_registers_tools(tmp_path):
+    def request(method, url, **kwargs):
+        if url.endswith("/images/generations"):
+            return 200, {"data": [{"b64_json": base64.b64encode(b"PNG").decode("ascii")}]}
+        return 200, {"choices": [{"message": {"content": "A cat"}}]}
+
+    image = tmp_path / "img.png"
+    image.write_bytes(b"\x89PNG\r\n\x1a\n\x00\x00\x00\rioEND")
+
+    app = create_app()
+    app.load_plugin(VisionPlugin(api_key="k", request=request))
+    assert "vision_describe" in app.tools.names
+    assert "ocr_extract_text" in app.tools.names
+    assert "image_generate" in app.tools.names
+
+    assert app.tools.execute("vision_describe", None, image_path=str(image)) == "A cat"
+    output = tmp_path / "gen.png"
+    assert app.tools.execute("image_generate", None, prompt="a dog", output_path=str(output)) == str(output)
+    assert output.read_bytes() == b"PNG"
+
+    app.unload_plugin("vision")

xyberos_vision-0.1.0/xyberos_vision/__init__.py

@@ -0,0 +1,15 @@
+"""Vision plugin (RFC-0019, M8)."""
+
+from .adapters import OpenAICompatibleVision, OpenAIImageGenerator, TesseractOCR
+from .contract import ImageGenerator, OCR, VisionModel
+from .plugin import VisionPlugin
+
+__all__ = [
+    "ImageGenerator",
+    "OCR",
+    "OpenAICompatibleVision",
+    "OpenAIImageGenerator",
+    "TesseractOCR",
+    "VisionModel",
+    "VisionPlugin",
+]

xyberos_vision-0.1.0/xyberos_vision/adapters.py

@@ -0,0 +1,140 @@
+"""Vision adapters: OpenAI-compatible vision, Tesseract OCR, image generation."""
+
+from __future__ import annotations
+
+import base64
+import importlib
+import mimetypes
+import os
+from pathlib import Path
+from typing import Any
+
+from xyberos.exceptions.provider import ProviderError
+
+from .http import RequestTransport, default_request
+
+
+def _raise_for_status(status: int, body: Any) -> None:
+    if 200 <= status < 300:
+        return
+    message = body if isinstance(body, str) else str(body)
+    raise ProviderError(f"vision API returned HTTP {status}: {message[:200]}")
+
+
+def _image_data_url(image_path: str) -> str:
+    path = Path(image_path)
+    if not path.is_file():
+        raise FileNotFoundError(image_path)
+    mime = mimetypes.guess_type(str(path))[0] or "image/png"
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime};base64,{encoded}"
+
+
+class OpenAICompatibleVision:
+    """Chat-completions vision model (works with OpenAI / Gemini-compatible)."""
+
+    name = "openai_compatible"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        model: str = "gpt-4o-mini",
+        base_url: str = "https://api.openai.com/v1",
+        request: RequestTransport | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self._api_key = api_key if api_key is not None else os.getenv("OPENAI_API_KEY")
+        self._model = model
+        self._base_url = base_url.rstrip("/")
+        self._request = request or default_request
+        self._timeout = timeout
+
+    def describe(self, image_path: str, prompt: str) -> str:
+        if not self._api_key:
+            raise ProviderError("vision requires an API key (set OPENAI_API_KEY)")
+        status, body = self._request(
+            "POST",
+            f"{self._base_url}/chat/completions",
+            json_body={
+                "model": self._model,
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": [
+                            {"type": "text", "text": prompt},
+                            {"type": "image_url", "image_url": {"url": _image_data_url(image_path)}},
+                        ],
+                    }
+                ],
+            },
+            headers={"Authorization": f"Bearer {self._api_key}"},
+            timeout=self._timeout,
+        )
+        _raise_for_status(status, body)
+        try:
+            return body["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise ProviderError(f"vision returned an unexpected response: {body}") from exc
+
+
+class TesseractOCR:
+    """Local OCR via Tesseract (lazy ``pytesseract`` + ``Pillow``)."""
+
+    name = "tesseract"
+
+    def __init__(self, lang: str = "eng") -> None:
+        self._lang = lang
+
+    def extract_text(self, image_path: str) -> str:
+        try:
+            pytesseract = importlib.import_module("pytesseract")
+            Image = importlib.import_module("PIL.Image")
+        except ImportError as exc:
+            raise ProviderError(
+                "OCR requires 'pytesseract' and 'pillow'; install with "
+                "'pip install xyberos-vision[ocr]' (plus the tesseract binary)"
+            ) from exc
+        return pytesseract.image_to_string(Image.open(image_path), lang=self._lang).strip()
+
+
+class OpenAIImageGenerator:
+    """Image generation via the OpenAI images API (b64_json)."""
+
+    name = "openai"
+    url = "https://api.openai.com/v1/images/generations"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        model: str = "dall-e-3",
+        size: str = "1024x1024",
+        request: RequestTransport | None = None,
+        timeout: float = 120.0,
+    ) -> None:
+        self._api_key = api_key if api_key is not None else os.getenv("OPENAI_API_KEY")
+        self._model = model
+        self._size = size
+        self._request = request or default_request
+        self._timeout = timeout
+
+    def generate(self, prompt: str, output_path: str) -> str:
+        if not self._api_key:
+            raise ProviderError("image generation requires an API key (set OPENAI_API_KEY)")
+        status, body = self._request(
+            "POST",
+            self.url,
+            json_body={"model": self._model, "prompt": prompt, "n": 1, "size": self._size, "response_format": "b64_json"},
+            headers={"Authorization": f"Bearer {self._api_key}"},
+            timeout=self._timeout,
+        )
+        _raise_for_status(status, body)
+        try:
+            encoded = body["data"][0]["b64_json"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise ProviderError(f"image generation returned an unexpected response: {body}") from exc
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(base64.b64decode(encoded))
+        return str(path)

xyberos_vision-0.1.0/xyberos_vision/contract.py

@@ -0,0 +1,38 @@
+"""Vision / OCR / image-generation contracts (RFC-0019, M8)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class VisionModel(Protocol):
+    """Anything that describes an image given a prompt."""
+
+    name: str
+
+    def describe(self, image_path: str, prompt: str) -> str:
+        """Return a text description of the image at ``image_path``."""
+        ...
+
+
+@runtime_checkable
+class OCR(Protocol):
+    """Anything that extracts text from an image."""
+
+    name: str
+
+    def extract_text(self, image_path: str) -> str:
+        """Return the text found in the image at ``image_path``."""
+        ...
+
+
+@runtime_checkable
+class ImageGenerator(Protocol):
+    """Anything that turns a prompt into an image file."""
+
+    name: str
+
+    def generate(self, prompt: str, output_path: str) -> str:
+        """Write a generated image to ``output_path`` and return the path."""
+        ...

xyberos_vision-0.1.0/xyberos_vision/http.py

@@ -0,0 +1,90 @@
+"""A tiny stdlib HTTP helper (no third-party deps).
+
+Supports JSON bodies, raw bytes bodies, and both parsed-JSON and raw-bytes
+responses. Both transports are injectable so tests run without a network.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+#: (method, url, *, json_body, raw_body, headers, query, timeout) -> (status, body)
+RequestTransport = Callable[..., tuple[int, Any]]
+RawRequestTransport = Callable[..., tuple[int, bytes]]
+
+
+def _build(
+    method: str,
+    url: str,
+    *,
+    json_body: Any,
+    raw_body: bytes | None,
+    headers: dict[str, str] | None,
+    query: dict[str, Any] | None,
+) -> urllib.request.Request:
+    final_url = url
+    if query:
+        separator = "&" if "?" in url else "?"
+        final_url = url + separator + urllib.parse.urlencode(query)
+
+    data: bytes | None = None
+    request_headers = dict(headers or {})
+    if raw_body is not None:
+        data = raw_body
+    elif json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        request_headers.setdefault("Content-Type", "application/json")
+    return urllib.request.Request(
+        final_url, data=data, headers=request_headers, method=method
+    )
+
+
+def default_request(
+    method: str,
+    url: str,
+    *,
+    json_body: Any = None,
+    raw_body: bytes | None = None,
+    headers: dict[str, str] | None = None,
+    query: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> tuple[int, Any]:
+    """Send one request and return ``(status, parsed_json_or_text)``."""
+    request = _build(method, url, json_body=json_body, raw_body=raw_body, headers=headers, query=query)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+            content_type = response.headers.get("Content-Type", "")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", errors="replace")
+
+    text = raw.decode("utf-8", errors="replace")
+    if "application/json" in content_type or text.lstrip().startswith("{"):
+        try:
+            return 200, json.loads(text)
+        except json.JSONDecodeError:
+            return 200, text
+    return 200, text
+
+
+def default_raw_request(
+    method: str,
+    url: str,
+    *,
+    json_body: Any = None,
+    raw_body: bytes | None = None,
+    headers: dict[str, str] | None = None,
+    query: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> tuple[int, bytes]:
+    """Send one request and return ``(status, raw_bytes)``."""
+    request = _build(method, url, json_body=json_body, raw_body=raw_body, headers=headers, query=query)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return int(getattr(response, "status", 200)), response.read()
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read()

xyberos_vision-0.1.0/xyberos_vision/plugin.py

@@ -0,0 +1,85 @@
+"""Vision plugin entry point (RFC-0019, M8)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, cast
+
+from xyberos.contracts import Plugin, Tool
+from xyberos.tools import FunctionTool
+
+from .adapters import OpenAICompatibleVision, OpenAIImageGenerator, TesseractOCR
+from .http import RequestTransport
+
+
+def _pop_tool(registry: Any, name: str) -> None:
+    unregister = getattr(registry, "unregister", None)
+    if callable(unregister):
+        unregister(name)
+        return
+    store = getattr(registry, "_tools", None)
+    if isinstance(store, dict):
+        cast(dict[str, Any], store).pop(name, None)
+
+
+class VisionPlugin(Plugin):
+    """Registers vision / OCR / image-generation tools."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        env_prefix: str = "VISION",
+        request: RequestTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._env_prefix = env_prefix
+        self._request = request
+        self._model = os.getenv(f"{env_prefix}_MODEL", "gpt-4o-mini")
+
+    @property
+    def name(self) -> str:
+        return "vision"
+
+    def vision_model(self) -> OpenAICompatibleVision:
+        return OpenAICompatibleVision(self._api_key, model=self._model, request=self._request)
+
+    def ocr(self) -> TesseractOCR:
+        return TesseractOCR()
+
+    def image_generator(self) -> OpenAIImageGenerator:
+        return OpenAIImageGenerator(self._api_key, request=self._request)
+
+    def tools(self) -> list[Tool]:
+        vision = self.vision_model()
+        ocr = self.ocr()
+        generator = self.image_generator()
+
+        def _describe(image_path: str, prompt: str = "Describe this image in detail.") -> str:
+            return vision.describe(image_path, prompt)
+
+        def _ocr(image_path: str) -> str:
+            return ocr.extract_text(image_path)
+
+        def _generate(prompt: str, output_path: str) -> str:
+            return generator.generate(prompt, output_path)
+
+        return [
+            FunctionTool("vision_describe", _describe, description="Describe an image with a vision model."),
+            FunctionTool("ocr_extract_text", _ocr, description="Extract text from an image with OCR."),
+            FunctionTool("image_generate", _generate, description="Generate an image from a prompt."),
+        ]
+
+    def register(self, kernel: object) -> None:
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            registry.register(tool)
+
+    def unregister(self, kernel: object) -> None:
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            _pop_tool(registry, tool.name)
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = VisionPlugin()

xyberos_vision-0.1.0/xyberos_vision.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: xyberos-vision
+Version: 0.1.0
+Summary: Vision plugin (RFC-0019, M8): describe images, OCR, generate images
+License: Apache-2.0
+Keywords: xyberos,plugin,vision,ocr,tesseract,image
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: ocr
+Requires-Dist: pytesseract; extra == "ocr"
+Requires-Dist: pillow; extra == "ocr"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# xyberos-vision
+
+**Vision plugin — RFC-0019, M8.** Describe images (vision model), extract text
+(OCR), and generate images — three tools, three contracts.
+
+## Install
+
+```bash
+pip install -e ./vision
+pip install xyberos-vision[ocr]    # optional: pytesseract + pillow for OCR
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_vision import VisionPlugin
+
+app = create_app()
+app.load_plugin(VisionPlugin())    # key from OPENAI_API_KEY
+
+app.tools.execute("vision_describe", None, image_path="photo.png", prompt="What's in this photo?")
+app.tools.execute("ocr_extract_text", None, image_path="scan.png")
+app.tools.execute("image_generate", None, prompt="a sunset over the ocean", output_path="out.png")
+```
+
+## Tools
+
+| Tool | Backed by |
+| ---- | --------- |
+| `vision_describe(image_path, prompt=...)` | `OpenAICompatibleVision` (`VISION_MODEL`, default `gpt-4o-mini`) |
+| `ocr_extract_text(image_path)` | `TesseractOCR` (lazy `pytesseract` + `pillow`) |
+| `image_generate(prompt, output_path)` | `OpenAIImageGenerator` (`dall-e-3`) |
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+Vision/image-gen are tested via injectable transports; OCR tests skip when
+`pytesseract` is absent.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — vision/multimodal (M8).

xyberos_vision-0.1.0/xyberos_vision.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+tests/test_adapters.py
+tests/test_plugin.py
+xyberos_vision/__init__.py
+xyberos_vision/adapters.py
+xyberos_vision/contract.py
+xyberos_vision/http.py
+xyberos_vision/plugin.py
+xyberos_vision.egg-info/PKG-INFO
+xyberos_vision.egg-info/SOURCES.txt
+xyberos_vision.egg-info/dependency_links.txt
+xyberos_vision.egg-info/entry_points.txt
+xyberos_vision.egg-info/requires.txt
+xyberos_vision.egg-info/top_level.txt

xyberos_vision-0.1.0/xyberos_vision.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xyberos_vision-0.1.0/xyberos_vision.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+vision = xyberos_vision.plugin:plugin

xyberos_vision-0.1.0/xyberos_vision.egg-info/requires.txt

@@ -0,0 +1,8 @@
+xyberos>=1.0
+
+[ocr]
+pytesseract
+pillow
+
+[test]
+pytest

xyberos_vision-0.1.0/xyberos_vision.egg-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_vision