rfx-protocols-system 0.2.0__py3-none-any.whl

protocols_system/__init__.py

@@ -0,0 +1,28 @@
+"""Protocols System — A self-describing, pluggable service locator.
+
+Provides decorator-based provider registration, singleton lifecycle management,
+and introspection-driven GUI discovery. Protocol and provider additions
+automatically surface in any UI that consumes the discovery layer.
+"""
+
+from .core import (
+    ConfigParam,
+    ProtocolSlot,
+    ProtocolsRegistry,
+    classify_widget,
+    get_all_provider_schemas,
+    get_protocol_slots,
+    get_provider_schema,
+    set_excluded_protocols,
+)
+
+__all__ = [
+    "ProtocolsRegistry",
+    "get_protocol_slots",
+    "get_provider_schema",
+    "get_all_provider_schemas",
+    "classify_widget",
+    "set_excluded_protocols",
+    "ProtocolSlot",
+    "ConfigParam",
+]

protocols_system/core/__init__.py

@@ -0,0 +1,32 @@
+"""Protocols System core — registry, discovery, and types."""
+
+from .discovery import (
+    classify_widget,
+    get_all_provider_schemas,
+    get_protocol_slots,
+    get_provider_schema,
+    set_excluded_protocols,
+)
+from .llm_support import (
+    ImageConversionError,
+    detect_mime,
+    prepare_image_for_vision,
+    validate_against_schema,
+)
+from .registry import ProtocolsRegistry
+from .types import ConfigParam, ProtocolSlot
+
+__all__ = [
+    "ProtocolsRegistry",
+    "get_protocol_slots",
+    "get_provider_schema",
+    "get_all_provider_schemas",
+    "classify_widget",
+    "set_excluded_protocols",
+    "ProtocolSlot",
+    "ConfigParam",
+    "validate_against_schema",
+    "prepare_image_for_vision",
+    "detect_mime",
+    "ImageConversionError",
+]

protocols_system/core/discovery.py

@@ -0,0 +1,199 @@
+"""Introspection-driven discovery for dynamic GUI rendering.
+
+This module provides the bridge between the ProtocolsRegistry catalog and a UI
+framework. It introspects protocols (via docstrings) and providers (via __init__
+signatures) so that settings forms can be rendered without any per-provider UI code.
+"""
+
+from __future__ import annotations
+
+import re
+from inspect import Parameter, signature
+from typing import Any
+
+from .registry import ProtocolsRegistry
+from .types import ConfigParam, ProtocolSlot
+
+# Protocols in this set won't appear in user-facing settings UI.
+_EXCLUDED_PROTOCOLS: set[type] = set()
+
+# Hints that indicate a parameter should be rendered as a password field.
+_SECRET_HINTS = ("api_key", "password", "secret", "token", "credentials")
+
+
+def set_excluded_protocols(protocols: set[type]) -> None:
+    """Configure which protocols are excluded from the settings UI.
+
+    Call this once at app startup after defining your infrastructure protocols.
+    """
+    global _EXCLUDED_PROTOCOLS
+    _EXCLUDED_PROTOCOLS = protocols
+
+
+def get_protocol_slots() -> list[ProtocolSlot]:
+    """Discover all configurable protocol slots from the registry.
+
+    Returns a list of ProtocolSlot objects suitable for rendering a settings page.
+    Infrastructure protocols in the exclusion set are filtered out.
+    """
+    slots: list[ProtocolSlot] = []
+    for protocol_cls in ProtocolsRegistry.get_protocols():
+        if protocol_cls in _EXCLUDED_PROTOCOLS:
+            continue
+        name = _derive_slot_name(protocol_cls)
+        label, description = _parse_protocol_doc(protocol_cls)
+        slots.append(ProtocolSlot(name, protocol_cls, label, description))
+    return slots
+
+
+def get_provider_schema(protocol: type, provider_name: str) -> list[ConfigParam]:
+    """Introspect a provider's __init__ to produce a list of config parameters.
+
+    Args:
+        protocol: The protocol type.
+        provider_name: The registered provider name.
+
+    Returns:
+        List of ConfigParam objects describing each constructor parameter.
+
+    Raises:
+        ValueError: If the protocol or provider is not registered.
+    """
+    providers = ProtocolsRegistry.get_providers(protocol)
+    if provider_name not in providers:
+        raise ValueError(
+            f"No provider named '{provider_name}' for protocol {protocol.__name__}"
+        )
+    cls = providers[provider_name]
+    return _introspect_init(cls)
+
+
+def get_all_provider_schemas(protocol: type) -> dict[str, list[ConfigParam]]:
+    """Return schemas for all providers registered under a protocol.
+
+    Returns:
+        Dict mapping provider_name -> list[ConfigParam].
+    """
+    providers = ProtocolsRegistry.get_providers(protocol)
+    return {name: _introspect_init(cls) for name, cls in providers.items()}
+
+
+def classify_widget(key: str, annotation: str, default: Any) -> str:
+    """Classify a parameter into a UI widget kind.
+
+    Args:
+        key: Parameter name.
+        annotation: Type annotation as string.
+        default: Default value (or Parameter.empty).
+
+    Returns:
+        One of: "bool", "password", "float", "int", "str".
+    """
+    # Bool detection
+    if "bool" in annotation.lower() or isinstance(default, bool):
+        return "bool"
+
+    # Secret-looking parameter names
+    if any(hint in key.lower() for hint in _SECRET_HINTS):
+        return "password"
+
+    # Numeric types
+    if "float" in annotation.lower() or isinstance(default, float):
+        return "float"
+    if "int" in annotation.lower() or isinstance(default, int):
+        return "int"
+
+    return "str"
+
+
+# ------------------------------------------------------------------
+# Internal helpers
+# ------------------------------------------------------------------
+
+
+def _derive_slot_name(protocol_cls: type) -> str:
+    """Derive a config-friendly slot name from a protocol class name.
+
+    IImageGenerationClient -> "image_generation"
+    ILLMClient             -> "llm"
+    IStorageClient         -> "storage"
+    ICacheManager          -> "cache_manager"
+    """
+    name = protocol_cls.__name__
+
+    # Strip leading "I"
+    if name.startswith("I") and len(name) > 1 and name[1].isupper():
+        name = name[1:]
+
+    # Strip trailing "Client" or "Manager" or "Provider"
+    for suffix in ("Client", "Manager", "Provider", "Service"):
+        if name.endswith(suffix) and len(name) > len(suffix):
+            name = name[: -len(suffix)]
+            break
+
+    # CamelCase to snake_case
+    name = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    name = re.sub(r"([a-z\d])([A-Z])", r"\1_\2", name)
+    return name.lower()
+
+
+def _parse_protocol_doc(protocol_cls: type) -> tuple[str, str]:
+    """Parse protocol docstring into (label, description).
+
+    Expected format: "Label:Description text here."
+    Falls back to class name if docstring is missing or malformed.
+    """
+    doc = protocol_cls.__doc__ or ""
+    first_line = doc.strip().split("\n")[0].strip()
+
+    if ":" in first_line:
+        label, description = first_line.split(":", 1)
+        return label.strip(), description.strip()
+
+    # Fallback: derive label from class name
+    label = _derive_slot_name(protocol_cls).replace("_", " ").title()
+    return label, first_line or f"Provider for {label}."
+
+
+def _introspect_init(cls: type) -> list[ConfigParam]:
+    """Extract ConfigParam list from a class's __init__ signature."""
+    try:
+        sig = signature(cls.__init__)  # type: ignore[misc]
+    except (ValueError, TypeError):
+        return []
+
+    params: list[ConfigParam] = []
+    for name, param in sig.parameters.items():
+        if name == "self":
+            continue
+        if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
+            continue
+
+        # Resolve annotation
+        if param.annotation is not Parameter.empty:
+            annotation = (
+                param.annotation.__name__
+                if hasattr(param.annotation, "__name__")
+                else str(param.annotation)
+            )
+        else:
+            annotation = "str"
+
+        # Resolve default
+        has_default = param.default is not Parameter.empty
+        default = param.default if has_default else None
+        required = not has_default
+
+        # Classify widget
+        widget_kind = classify_widget(name, annotation, default)
+
+        params.append(
+            ConfigParam(
+                key=name,
+                annotation=annotation,
+                default=default,
+                required=required,
+                widget_kind=widget_kind,
+            )
+        )
+    return params

protocols_system/core/llm_support.py

@@ -0,0 +1,194 @@
+"""Shared helpers for the LLM vision providers (ollama, llamacpp, openai).
+
+Centralizes two things that were previously copy-pasted (and subtly wrong) in
+each provider client:
+
+* :func:`validate_against_schema` — a stricter simplified-JSON-schema
+  validator. Earlier per-client copies didn't verify the result was a dict,
+  accepted ``bool`` as a number, ignored ``minimum``/``maximum``/``enum``/
+  ``integer``, and let NaN through.
+* :func:`prepare_image_for_vision` — normalizes arbitrary image bytes to a
+  format the vision APIs actually accept. Earlier per-client code only
+  converted WebP, mislabeled everything else as ``image/jpeg`` while sending
+  the original (HEIC/TIFF/BMP/GIF) bytes, never registered ``pillow-heif`` (so
+  HEIC couldn't decode at all), and on conversion failure sent the bad bytes
+  anyway.
+
+These helpers carry no network/transport concern — they are pure, importable
+without any optional provider dependency, and shared by every LLM provider.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import math
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Try to register HEIC/HEIF support so iPhone images can be decoded.
+# pillow-heif is an optional dependency; if it isn't installed, HEIC input
+# simply can't be converted and prepare_image_for_vision reports an error
+# rather than silently sending undecodable bytes.
+try:  # pragma: no cover - depends on optional dependency being installed
+    import pillow_heif  # type: ignore
+
+    pillow_heif.register_heif_opener()
+    _HEIF_AVAILABLE = True
+except Exception:  # pragma: no cover
+    _HEIF_AVAILABLE = False
+
+# Formats the vision endpoints accept directly without re-encoding.
+_PASSTHROUGH_MIME = ("image/jpeg", "image/png")
+
+# Target max pixels when downscaling (~2 megapixels). Large images waste
+# tokens/VRAM and some endpoints reject them outright.
+_MAX_PIXELS = 2_000_000
+
+
+class ImageConversionError(RuntimeError):
+    """Raised when image bytes can't be decoded/converted for a vision API."""
+
+
+def detect_mime(image_bytes: bytes) -> str:
+    """Best-effort MIME detection from magic bytes.
+
+    Returns one of image/png, image/webp, image/jpeg, image/gif, image/bmp,
+    image/tiff, image/heic, or "application/octet-stream" when unknown.
+    """
+    if image_bytes[:4] == b"\x89PNG":
+        return "image/png"
+    if image_bytes[:4] == b"RIFF" and image_bytes[8:12] == b"WEBP":
+        return "image/webp"
+    if image_bytes[:2] == b"\xff\xd8":
+        return "image/jpeg"
+    if image_bytes[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if image_bytes[:2] == b"BM":
+        return "image/bmp"
+    if image_bytes[:4] in (b"II*\x00", b"MM\x00*"):
+        return "image/tiff"
+    # HEIC/HEIF: "ftyp" box with a heic/heif/mif1 brand near the start.
+    if image_bytes[4:8] == b"ftyp" and image_bytes[8:12] in (
+        b"heic", b"heix", b"hevc", b"heif", b"mif1", b"msf1",
+    ):
+        return "image/heic"
+    return "application/octet-stream"
+
+
+def prepare_image_for_vision(image_bytes: bytes) -> tuple[bytes, str]:
+    """Return ``(bytes, mime_type)`` safe to send to a vision API.
+
+    JPEG/PNG are passed through unchanged. Everything else (WebP, HEIC, TIFF,
+    BMP, GIF, or unknown) is decoded via Pillow and re-encoded to JPEG, and the
+    result is downscaled to roughly 2 MP. A decode/convert failure raises
+    :class:`ImageConversionError` instead of returning the original bytes with
+    a bogus ``image/jpeg`` label — the caller turns that into a proper
+    per-image error rather than sending garbage to the model.
+    """
+    mime = detect_mime(image_bytes)
+    if mime in _PASSTHROUGH_MIME:
+        return image_bytes, mime
+
+    if mime == "image/heic" and not _HEIF_AVAILABLE:
+        raise ImageConversionError(
+            "HEIC image received but pillow-heif is not installed, so it "
+            "cannot be converted for the vision API. Install the 'heif' "
+            "extra (pillow-heif) or supply JPEG/PNG."
+        )
+
+    try:
+        from PIL import Image
+
+        img = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+        # Downscale large images to ~2 MP to bound token/VRAM cost.
+        pixels = img.width * img.height
+        if pixels > _MAX_PIXELS:
+            scale = math.sqrt(_MAX_PIXELS / pixels)
+            new_size = (max(1, int(img.width * scale)), max(1, int(img.height * scale)))
+            img = img.resize(new_size)
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=90)
+        return buf.getvalue(), "image/jpeg"
+    except ImageConversionError:
+        raise
+    except Exception as exc:
+        raise ImageConversionError(
+            f"Failed to convert {mime} image to JPEG for the vision API: {exc}"
+        ) from exc
+
+
+def validate_against_schema(data: Any, schema: dict[str, Any]) -> str | None:
+    """Validate ``data`` against a simplified JSON schema.
+
+    Checks required keys and basic type constraints from the schema's
+    ``properties`` definitions. Supports types: integer, number, string,
+    boolean, array, object. Also enforces ``minimum``/``maximum`` and ``enum``.
+
+    Returns ``None`` if valid, else an error message string.
+    """
+    if not isinstance(data, dict):
+        return f"Expected a JSON object, got {type(data).__name__}"
+
+    required_keys = schema.get("required", [])
+    properties = schema.get("properties", {})
+
+    for key in required_keys:
+        if key not in data:
+            return f"Missing required key: '{key}'"
+
+    for key, prop_schema in properties.items():
+        if key not in data:
+            continue
+        value = data[key]
+        err = _validate_value(key, value, prop_schema)
+        if err is not None:
+            return err
+
+    return None
+
+
+def _validate_value(key: str, value: Any, prop_schema: dict[str, Any]) -> str | None:
+    expected_type = prop_schema.get("type")
+
+    if expected_type == "integer":
+        # bool is a subclass of int but is not an integer value here.
+        if isinstance(value, bool) or not isinstance(value, int):
+            return f"Key '{key}' expected integer, got {type(value).__name__}"
+    elif expected_type == "number":
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            return f"Key '{key}' expected number, got {type(value).__name__}"
+        if not math.isfinite(float(value)):
+            return f"Key '{key}' must be a finite number, got {value!r}"
+    elif expected_type == "string":
+        if not isinstance(value, str):
+            return f"Key '{key}' expected string, got {type(value).__name__}"
+    elif expected_type == "boolean":
+        if not isinstance(value, bool):
+            return f"Key '{key}' expected boolean, got {type(value).__name__}"
+    elif expected_type == "array":
+        if not isinstance(value, list):
+            return f"Key '{key}' expected array, got {type(value).__name__}"
+    elif expected_type == "object":
+        if not isinstance(value, dict):
+            return f"Key '{key}' expected object, got {type(value).__name__}"
+
+    # Range + enum constraints.
+    if (
+        expected_type in ("number", "integer")
+        and isinstance(value, (int, float))
+        and not isinstance(value, bool)
+    ):
+        minimum = prop_schema.get("minimum")
+        maximum = prop_schema.get("maximum")
+        if minimum is not None and value < minimum:
+            return f"Key '{key}' must be >= {minimum}, got {value!r}"
+        if maximum is not None and value > maximum:
+            return f"Key '{key}' must be <= {maximum}, got {value!r}"
+
+    enum = prop_schema.get("enum")
+    if enum is not None and value not in enum:
+        return f"Key '{key}' must be one of {enum}, got {value!r}"
+
+    return None

protocols_system/core/registry.py

@@ -0,0 +1,178 @@
+"""ProtocolsRegistry — Decorator-based service locator with singleton lifecycle.
+
+Usage:
+    @ProtocolsRegistry.register("openai", ILLMClient)
+    class OpenAIClient:
+        def __init__(self, api_key: str, model: str = "gpt-4o-mini"): ...
+
+    # Later, instantiate with user config:
+    client = ProtocolsRegistry.create(ILLMClient, "openai", {"api_key": "sk-..."})
+
+    # Retrieve the live singleton:
+    client = ProtocolsRegistry.get_instance(ILLMClient)
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class ProtocolsRegistry:
+    """Static registry mapping protocol types to named provider classes.
+
+    Maintains two separate stores:
+    - _registry: catalog of protocol -> {provider_name: provider_class}  (permanent)
+    - _instances: protocol -> live singleton instance  (clearable between runs)
+    """
+
+    _registry: dict[type, dict[str, type]] = {}
+    _instances: dict[type, Any] = {}
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def register(name: str, protocol: type) -> Any:
+        """Decorator that registers a class as a named provider for a protocol.
+
+        A single class can be registered under multiple protocols by stacking
+        decorators.
+
+        Args:
+            name: Provider name (e.g. "openai", "ollama", "s3").
+            protocol: The protocol type this class implements.
+
+        Returns:
+            A decorator that registers the class and returns it unchanged.
+        """
+
+        def decorator(cls: type) -> type:
+            if protocol not in ProtocolsRegistry._registry:
+                ProtocolsRegistry._registry[protocol] = {}
+            ProtocolsRegistry._registry[protocol][name] = cls
+            return cls
+
+        return decorator
+
+    # ------------------------------------------------------------------
+    # Catalog queries
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def get_registry() -> dict[type, dict[str, type]]:
+        """Return the full registry mapping (protocol -> {name: class})."""
+        return ProtocolsRegistry._registry
+
+    @staticmethod
+    def get_protocols() -> list[type]:
+        """Return all protocol types that have at least one registered provider."""
+        return list(ProtocolsRegistry._registry.keys())
+
+    @staticmethod
+    def get_providers(protocol: type) -> dict[str, type]:
+        """Return {name: class} for all providers registered under a protocol."""
+        return ProtocolsRegistry._registry.get(protocol, {})
+
+    # ------------------------------------------------------------------
+    # Instance lifecycle
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def create(protocol: type[T], name: str, config: dict[str, Any] | None = None) -> T:
+        """Instantiate a provider and store it as the active singleton for the protocol.
+
+        Args:
+            protocol: The protocol type to resolve.
+            name: The registered provider name.
+            config: Keyword arguments passed to the provider's __init__.
+
+        Returns:
+            The newly created instance.
+
+        Raises:
+            ValueError: If the protocol or provider name is not registered.
+        """
+        if protocol not in ProtocolsRegistry._registry:
+            raise ValueError(f"No providers registered for protocol {protocol.__name__}")
+        providers = ProtocolsRegistry._registry[protocol]
+        if name not in providers:
+            available = ", ".join(sorted(providers.keys())) or "(none)"
+            raise ValueError(
+                f"No provider named '{name}' for protocol {protocol.__name__}. "
+                f"Available: {available}"
+            )
+        instance = providers[name](**(config or {}))
+        ProtocolsRegistry._instances[protocol] = instance
+        return instance  # type: ignore[no-any-return]
+
+    @staticmethod
+    def build_provider(
+        protocol: type[T], name: str, config: dict[str, Any] | None = None
+    ) -> T:
+        """Instantiate a provider WITHOUT storing it as the active singleton.
+
+        Use this when a composite provider (e.g. a multiplexer) needs to build
+        the sub-providers it delegates to, without replacing the protocol's live
+        singleton (which is the composite itself).
+
+        Args:
+            protocol: The protocol type to resolve.
+            name: The registered provider name.
+            config: Keyword arguments passed to the provider's __init__.
+
+        Returns:
+            The newly created instance.
+
+        Raises:
+            ValueError: If the protocol or provider name is not registered.
+        """
+        if protocol not in ProtocolsRegistry._registry:
+            raise ValueError(f"No providers registered for protocol {protocol.__name__}")
+        providers = ProtocolsRegistry._registry[protocol]
+        if name not in providers:
+            available = ", ".join(sorted(providers.keys())) or "(none)"
+            raise ValueError(
+                f"No provider named '{name}' for protocol {protocol.__name__}. "
+                f"Available: {available}"
+            )
+        return providers[name](**(config or {}))  # type: ignore[no-any-return]
+
+    @staticmethod
+    def get_instance(protocol: type[T]) -> T | None:
+        """Retrieve the live singleton for a protocol, or None if not yet created."""
+        return ProtocolsRegistry._instances.get(protocol)
+
+    @staticmethod
+    def set_instance(protocol: type, instance: Any) -> None:
+        """Manually inject an instance (useful for testing or webgui overrides)."""
+        ProtocolsRegistry._instances[protocol] = instance
+
+    @staticmethod
+    def remove_instance(protocol: type) -> Any:
+        """Drop the active singleton for a SINGLE protocol.
+
+        Unlike ``clear_instances()`` (which wipes every protocol's instance),
+        this removes only the one protocol — e.g. clearing the Geo provider
+        without tearing down an unrelated live image mux.
+
+        Args:
+            protocol: The protocol type whose live instance should be removed.
+
+        Returns:
+            The removed instance, or None if no instance was registered.
+        """
+        return ProtocolsRegistry._instances.pop(protocol, None)
+
+    @staticmethod
+    def clear_instances() -> None:
+        """Clear all live instances. Catalog remains intact."""
+        ProtocolsRegistry._instances.clear()
+
+    @staticmethod
+    def reset() -> None:
+        """Clear both catalog and instances. Intended for test isolation."""
+        ProtocolsRegistry._registry.clear()
+        ProtocolsRegistry._instances.clear()

protocols_system/core/types.py

@@ -0,0 +1,42 @@
+"""Data classes used by the Protocols System discovery layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProtocolSlot:
+    """A discoverable protocol slot for the settings UI.
+
+    Attributes:
+        name: Derived config key (e.g. "llm", "image_generation").
+        protocol: The protocol type class.
+        label: Human-readable label (parsed from protocol docstring).
+        description: Description text (parsed from protocol docstring).
+    """
+
+    name: str
+    protocol: type
+    label: str
+    description: str
+
+
+@dataclass(frozen=True)
+class ConfigParam:
+    """A single configuration parameter introspected from a provider's __init__.
+
+    Attributes:
+        key: Parameter name.
+        annotation: Type annotation string (e.g. "str", "int", "float").
+        default: Default value, or MISSING sentinel if required.
+        required: Whether the parameter must be supplied.
+        widget_kind: Suggested UI widget type ("str", "int", "float", "bool", "password").
+    """
+
+    key: str
+    annotation: str = "str"
+    default: Any = field(default=None)
+    required: bool = False
+    widget_kind: str = "str"

protocols_system/core/validation.py

@@ -0,0 +1,13 @@
+"""Shared validation utilities for protocol providers.
+
+The canonical implementation now lives in :mod:`protocols_system.core.llm_support`
+(the stricter validator used by every LLM provider). This module re-exports it
+so existing ``from protocols_system.core.validation import validate_against_schema``
+imports keep working against a single source of truth.
+"""
+
+from __future__ import annotations
+
+from .llm_support import validate_against_schema
+
+__all__ = ["validate_against_schema"]