rfx-protocols-system 0.2.0__tar.gz

rfx_protocols_system-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Build and Publish Wheel
+
+# Builds the rfx-protocols-system wheel and publishes it so the consuming apps
+# (PhotoStudio, Smart-Albums) can install a versioned artifact
+# (rfx-protocols-system==0.2.x) instead of resolving a git SHA — which removes the
+# need for `git` in every consumer Docker image and keeps both consumers
+# locked to the same published version (SIMPLIFICATION 2.2 / 4.2).
+#
+# Triggers:
+#   * version tags (v*)        -> release build, publishes to PyPI + attaches
+#                                 the wheel/sdist to a GitHub Release;
+#   * manual (workflow_dispatch) -> build + upload artifacts only (no publish).
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build wheel and sdist
+        run: python -m build --outdir dist
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    # Only publish from a version tag, and only after a successful build.
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC) — no stored API token.
+      id-token: write
+      contents: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Attach artifacts to the GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

rfx_protocols_system-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+.venv-verify/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+
+# pytest
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-specific
+*.log

rfx_protocols_system-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rfloresx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rfx_protocols_system-0.2.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: rfx-protocols-system
+Version: 0.2.0
+Summary: A self-describing, pluggable service locator: decorator-based provider registration, singleton lifecycle management, and introspection-driven GUI discovery.
+Project-URL: Homepage, https://github.com/rfloresx/ProtocolsSystem
+Project-URL: Repository, https://github.com/rfloresx/ProtocolsSystem
+Project-URL: Issues, https://github.com/rfloresx/ProtocolsSystem/issues
+Author: Roberto Flores
+License-Expression: MIT
+License-File: LICENSE
+Keywords: discovery,plugin,protocols,registry,service-locator
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: heif
+Requires-Dist: pillow-heif<1,>=0.16.0; extra == 'heif'
+Provides-Extra: huggingface
+Requires-Dist: torch>=2.0.0; extra == 'huggingface'
+Requires-Dist: transformers<5,>=4.38.0; extra == 'huggingface'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=1.0.0; extra == 'openai'
+Provides-Extra: providers
+Requires-Dist: googlemaps>=4.10; extra == 'providers'
+Requires-Dist: httpx>=0.27; extra == 'providers'
+Requires-Dist: immichpy<9,>=8.0; extra == 'providers'
+Requires-Dist: ollama>=0.4; extra == 'providers'
+Requires-Dist: pillow>=10.0; extra == 'providers'
+Requires-Dist: tenacity<10,>=9.0; extra == 'providers'
+Provides-Extra: webauth
+Requires-Dist: bcrypt>=4.0; extra == 'webauth'
+Description-Content-Type: text/markdown
+
+# Protocols System
+
+A self-describing, pluggable service locator for Python.
+
+Protocols System 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.
+
+It is shared across projects (PhotoStudio, Smart-Albums) as a standalone
+package so provider implementations and the registry live in one place.
+
+## Install
+
+```bash
+# Core only (registry, discovery, protocols). The importable package is
+# `protocols_system`; the distribution name is `rfx-protocols-system`.
+pip install rfx-protocols-system
+
+# With built-in provider implementations (Immich, Ollama, llama.cpp, Google Places, ...)
+pip install "rfx-protocols-system[providers]"
+```
+
+For local development against a checkout:
+
+```bash
+pip install -e "../ProtocolsSystem[providers]"
+```
+
+## Layout
+
+- `protocols_system.core` — registry, discovery, types, validation
+- `protocols_system.protocols` — protocol (interface) definitions: cache,
+  embedding, geo, health, image_library, llm, progress
+- `protocols_system.providers` — concrete provider implementations that
+  self-register via the `@ProtocolsRegistry.register` decorator
+
+## Usage
+
+```python
+from protocols_system import ProtocolsRegistry, get_protocol_slots
+from protocols_system.providers import register_builtin_providers
+
+# Import provider modules so they register themselves. Providers whose
+# optional dependencies are missing are skipped silently.
+register_builtin_providers()
+
+registry = ProtocolsRegistry()
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,providers]"
+pytest
+mypy
+ruff check
+```

rfx_protocols_system-0.2.0/README.md

@@ -0,0 +1,58 @@
+# Protocols System
+
+A self-describing, pluggable service locator for Python.
+
+Protocols System 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.
+
+It is shared across projects (PhotoStudio, Smart-Albums) as a standalone
+package so provider implementations and the registry live in one place.
+
+## Install
+
+```bash
+# Core only (registry, discovery, protocols). The importable package is
+# `protocols_system`; the distribution name is `rfx-protocols-system`.
+pip install rfx-protocols-system
+
+# With built-in provider implementations (Immich, Ollama, llama.cpp, Google Places, ...)
+pip install "rfx-protocols-system[providers]"
+```
+
+For local development against a checkout:
+
+```bash
+pip install -e "../ProtocolsSystem[providers]"
+```
+
+## Layout
+
+- `protocols_system.core` — registry, discovery, types, validation
+- `protocols_system.protocols` — protocol (interface) definitions: cache,
+  embedding, geo, health, image_library, llm, progress
+- `protocols_system.providers` — concrete provider implementations that
+  self-register via the `@ProtocolsRegistry.register` decorator
+
+## Usage
+
+```python
+from protocols_system import ProtocolsRegistry, get_protocol_slots
+from protocols_system.providers import register_builtin_providers
+
+# Import provider modules so they register themselves. Providers whose
+# optional dependencies are missing are skipped silently.
+register_builtin_providers()
+
+registry = ProtocolsRegistry()
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,providers]"
+pytest
+mypy
+ruff check
+```

rfx_protocols_system-0.2.0/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "rfx-protocols-system"
+version = "0.2.0"
+description = "A self-describing, pluggable service locator: decorator-based provider registration, singleton lifecycle management, and introspection-driven GUI discovery."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Roberto Flores" },
+]
+keywords = ["service-locator", "registry", "protocols", "plugin", "discovery"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# Built-in provider implementations pull optional third-party clients.
+# The registry skips providers whose dependencies are missing, so these
+# are opt-in per consumer.
+providers = [
+    "httpx>=0.27",
+    "immichpy>=8.0,<9",
+    "tenacity>=9.0,<10",
+    "ollama>=0.4",
+    "googlemaps>=4.10",
+    "Pillow>=10.0",
+]
+# OpenAI-compatible LLM provider (openai_llm).
+openai = [
+    "openai>=1.0.0,<3",
+]
+# HEIC/HEIF decoding for the vision image-preparation path (pillow-heif).
+# Without it, HEIC input reports a clear error rather than sending
+# undecodable bytes to a vision API.
+heif = [
+    "pillow-heif>=0.16.0,<1",
+]
+# Local CLIP-family image embeddings (huggingface_embedding). Heavy — pulls
+# torch — so kept separate from the core providers extra.
+huggingface = [
+    "transformers>=4.38.0,<5",
+    "torch>=2.0.0",
+]
+# Shared web-auth primitives (protocols_system.webauth): bcrypt hashing and
+# timing-safe verification used by consumer web GUIs.
+webauth = [
+    "bcrypt>=4.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/rfloresx/ProtocolsSystem"
+Repository = "https://github.com/rfloresx/ProtocolsSystem"
+Issues = "https://github.com/rfloresx/ProtocolsSystem/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/protocols_system"]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src"]
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["protocols_system"]
+mypy_path = ["src"]
+
+# immichpy has no py.typed / stubs; ollama and googlemaps are suppressed
+# inline via `type: ignore` at their import sites.
+[[tool.mypy.overrides]]
+module = [
+    "immichpy.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"

rfx_protocols_system-0.2.0/src/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",
+]

rfx_protocols_system-0.2.0/src/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",
+]

rfx_protocols_system-0.2.0/src/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