immich-api 0.2.0__py3-none-any.whl

immich_api/error_authority.py

@@ -0,0 +1,248 @@
+#!/usr/bin/python
+"""One representation authority for agent-readable HTTP errors.
+
+The generated module is deliberately framework-neutral.  HTTP, MCP, and A2A
+adapters construct one :class:`ProblemDetails` value and negotiate only its
+representation; they do not independently translate exceptions or retry
+metadata.  Browser HTML remains available, but agent clients receive RFC 9457
+JSON or structured Markdown when they ask for it.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from agent_connector_sdk.privacy import sanitize_for_persistence
+
+from .error_rendering import (
+    AGENT_ERROR_ACCEPT,
+    BROWSER_HTML_MEDIA_TYPE,
+    PROBLEM_JSON_MEDIA_TYPE,
+    STRUCTURED_MARKDOWN_MEDIA_TYPE,
+    RenderedError,
+    negotiate_media_type,
+    render_error,
+)
+
+MAX_DETAIL_CHARS = 2048
+MAX_INSTANCE_CHARS = 512
+MAX_TYPE_CHARS = 256
+MAX_RETRY_AFTER_S = 3600.0
+
+_CODE_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]{0,63}$")
+_DENIAL_CODES = frozenset(
+    {
+        "access_denied",
+        "authentication_required",
+        "forbidden",
+        "not_authorized",
+        "permission_denied",
+        "policy_denied",
+        "unauthorized",
+    }
+)
+_DEFAULT_TITLES = {
+    "dependency_unavailable": "Dependency unavailable",
+    "engine_degraded": "Service temporarily unavailable",
+    "invalid_request": "Invalid request",
+    "operation_failed": "Operation failed",
+    "permission_denied": "Permission denied",
+}
+_METADATA_FIELDS = (
+    "status",
+    "code",
+    "type",
+    "instance",
+    "retryable",
+    "retry_after_s",
+)
+
+
+def _safe_text(value: Any, *, limit: int, fallback: str) -> str:
+    """Sanitize and bound text before it crosses a public response boundary."""
+    candidate = "" if isinstance(value, BaseException) else str(value or "")
+    sanitized, _ = sanitize_for_persistence(candidate)
+    text = str(sanitized).replace("\x00", "").strip()
+    return text[:limit] or fallback
+
+
+def _safe_code(value: Any) -> str:
+    candidate = str(value or "operation_failed").strip().lower()
+    return candidate if _CODE_RE.fullmatch(candidate) else "operation_failed"
+
+
+def _bounded_retry_after(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        retry_after = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(retry_after) or retry_after < 0:
+        return None
+    return min(retry_after, MAX_RETRY_AFTER_S)
+
+
+@dataclass(frozen=True)
+class ProblemDetails:
+    """Canonical RFC 9457 problem details plus agent retry metadata."""
+
+    status: int
+    code: str
+    instance: str
+    detail: str
+    type_uri: str = ""
+    title: str = ""
+    retryable: bool = False
+    retry_after_s: float | None = None
+
+    def __post_init__(self) -> None:
+        status = int(self.status)
+        if not 100 <= status <= 599:
+            raise ValueError("problem status must be between 100 and 599")
+
+        code = _safe_code(self.code)
+        denied = status in {401, 403} or code in _DENIAL_CODES
+        type_uri = _safe_text(
+            self.type_uri,
+            limit=MAX_TYPE_CHARS,
+            fallback=f"urn:agent-error:{code}",
+        )
+        instance = _safe_text(
+            self.instance,
+            limit=MAX_INSTANCE_CHARS,
+            fallback="urn:agent-error-instance:unknown",
+        )
+        title = _safe_text(
+            self.title,
+            limit=256,
+            fallback=_DEFAULT_TITLES.get(code, "Operation failed"),
+        )
+        detail = _safe_text(
+            self.detail,
+            limit=MAX_DETAIL_CHARS,
+            fallback="The request could not be completed.",
+        )
+        retryable = bool(self.retryable) and not denied
+        retry_after_s = _bounded_retry_after(self.retry_after_s) if retryable else None
+
+        object.__setattr__(self, "status", status)
+        object.__setattr__(self, "code", code)
+        object.__setattr__(self, "type_uri", type_uri)
+        object.__setattr__(self, "instance", instance)
+        object.__setattr__(self, "title", title)
+        object.__setattr__(self, "detail", detail)
+        object.__setattr__(self, "retryable", retryable)
+        object.__setattr__(self, "retry_after_s", retry_after_s)
+
+    def metadata(self) -> dict[str, Any]:
+        """Return the representation-invariant agent metadata."""
+        return {
+            "status": self.status,
+            "code": self.code,
+            "type": self.type_uri,
+            "instance": self.instance,
+            "retryable": self.retryable,
+            "retry_after_s": self.retry_after_s,
+        }
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return an RFC 9457-compatible object with stable extension fields."""
+        return {
+            "type": self.type_uri,
+            "title": self.title,
+            "status": self.status,
+            "detail": self.detail,
+            "instance": self.instance,
+            "code": self.code,
+            "retryable": self.retryable,
+            "retry_after_s": self.retry_after_s,
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(
+            self.as_dict(), ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        )
+
+    def to_markdown(self) -> str:
+        """Render structured Markdown from the same metadata object as JSON."""
+        metadata = self.metadata()
+        lines = ["---"]
+        for field in _METADATA_FIELDS:
+            rendered = json.dumps(metadata[field], ensure_ascii=False)
+            lines.append(f"{field}: {rendered}")
+        lines.extend(
+            [
+                "---",
+                f"# {self.title}",
+                "",
+                "## Detail",
+            ]
+        )
+        lines.extend(f"> {line}" if line else ">" for line in self.detail.splitlines())
+        return "\n".join(lines) + "\n"
+
+    def to_html(self) -> str:
+        """Render the retained browser surface with escaped bounded fields."""
+        metadata = self.metadata()
+        attrs = " ".join(
+            'data-error-{}="{}"'.format(
+                field.replace("_", "-"), html.escape(str(value), quote=True)
+            )
+            for field, value in metadata.items()
+        )
+        detail = html.escape(self.detail, quote=False).replace("\n", "<br>")
+        return (
+            '<!doctype html>\n<html lang="en"><head>'
+            f'<meta name="error-status" content="{self.status}">'
+            f"<title>{html.escape(self.title)}</title></head>\n"
+            f"<body><main {attrs}><h1>{html.escape(self.title)}</h1>"
+            f"<p>{detail}</p></main></body></html>\n"
+        )
+
+
+def error_response(
+    *,
+    status: int,
+    code: str,
+    instance: str,
+    detail: str,
+    type_uri: str = "",
+    title: str = "",
+    retryable: bool = False,
+    retry_after_s: float | None = None,
+    accept: str | None = None,
+) -> RenderedError:
+    """Construct and render a problem through the single package authority."""
+    return render_error(
+        ProblemDetails(
+            status=status,
+            code=code,
+            instance=instance,
+            detail=detail,
+            type_uri=type_uri,
+            title=title,
+            retryable=retryable,
+            retry_after_s=retry_after_s,
+        ),
+        accept=accept,
+    )
+
+
+__all__ = [
+    "BROWSER_HTML_MEDIA_TYPE",
+    "AGENT_ERROR_ACCEPT",
+    "MAX_DETAIL_CHARS",
+    "PROBLEM_JSON_MEDIA_TYPE",
+    "ProblemDetails",
+    "RenderedError",
+    "STRUCTURED_MARKDOWN_MEDIA_TYPE",
+    "error_response",
+    "negotiate_media_type",
+    "render_error",
+]

immich_api/error_rendering.py

@@ -0,0 +1,105 @@
+"""Negotiate and render canonical problems without changing their metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .error_authority import ProblemDetails
+
+
+PROBLEM_JSON_MEDIA_TYPE = "application/problem+json"
+STRUCTURED_MARKDOWN_MEDIA_TYPE = "text/markdown"
+BROWSER_HTML_MEDIA_TYPE = "text/html"
+AGENT_ERROR_ACCEPT = (
+    f"{PROBLEM_JSON_MEDIA_TYPE}, "
+    f"{STRUCTURED_MARKDOWN_MEDIA_TYPE};q=0.9, "
+    f"{BROWSER_HTML_MEDIA_TYPE};q=0.5"
+)
+
+
+@dataclass(frozen=True)
+class RenderedError:
+    """A transport-neutral response ready for an HTTP/MCP adapter."""
+
+    status_code: int
+    media_type: str
+    body: str
+    headers: Mapping[str, str]
+
+
+def _quality(parameters: list[str]) -> float | None:
+    """Read one bounded q value; preserve the default for malformed parameters."""
+    try:
+        quality = next(
+            float(part.split("=", 1)[1].strip())
+            for part in parameters
+            if part.lower().startswith("q=")
+        )
+    except (StopIteration, ValueError):
+        quality = 1.0
+    return quality if 0.0 <= quality <= 1.0 else None
+
+
+def _specificity(token: str, offered: str) -> int:
+    if token == offered:
+        return 2
+    return 1 if token in {"*/*", offered.split("/", 1)[0] + "/*"} else -1
+
+
+def _accept_quality(accept: str, offered: str) -> tuple[float, int, int]:
+    """Return q, specificity, and source order for one offered media type."""
+    best_match = (-1, 0.0, -10_000)
+    for order, item in enumerate(accept.split(",")):
+        bits = [part.strip() for part in item.split(";")]
+        quality = _quality(bits[1:])
+        specificity = _specificity(bits[0].lower(), offered)
+        if quality is not None and specificity >= 0:
+            best_match = max(best_match, (specificity, quality, -order))
+    specificity, quality, source_order = best_match
+    return quality, specificity, source_order
+
+
+def negotiate_media_type(accept: str | None) -> str:
+    """Prefer agent formats, while retaining HTML for browser Accept headers."""
+    if not accept or not accept.strip():
+        return PROBLEM_JSON_MEDIA_TYPE
+    offered = (
+        PROBLEM_JSON_MEDIA_TYPE,
+        STRUCTURED_MARKDOWN_MEDIA_TYPE,
+        BROWSER_HTML_MEDIA_TYPE,
+    )
+    ranked = [
+        (*_accept_quality(accept, media_type), -priority, media_type)
+        for priority, media_type in enumerate(offered)
+    ]
+    supported = [candidate for candidate in ranked if candidate[0] > 0]
+    return max(supported)[-1] if supported else PROBLEM_JSON_MEDIA_TYPE
+
+
+def render_error(
+    problem: ProblemDetails, *, accept: str | None = None
+) -> RenderedError:
+    """Negotiate one bounded representation without changing its semantics."""
+    media_type = negotiate_media_type(accept)
+    if media_type == STRUCTURED_MARKDOWN_MEDIA_TYPE:
+        body = problem.to_markdown()
+    elif media_type == BROWSER_HTML_MEDIA_TYPE:
+        body = problem.to_html()
+    else:
+        media_type = PROBLEM_JSON_MEDIA_TYPE
+        body = problem.to_json()
+    headers = {
+        "Content-Type": f"{media_type}; charset=utf-8",
+        "Vary": "Accept",
+    }
+    if problem.retry_after_s is not None:
+        headers["Retry-After"] = str(problem.retry_after_s)
+    return RenderedError(
+        status_code=problem.status,
+        media_type=media_type,
+        body=body,
+        headers=headers,
+    )

immich_api/immich_input_models.py

@@ -0,0 +1,12 @@
+#!/usr/bin/python
+"""Pydantic input models for Immich Api API request parameters."""
+
+from pydantic import BaseModel, Field
+
+
+class SystemStatusInput(BaseModel):
+    """Input model for system status queries."""
+
+    verbose: bool | None = Field(
+        default=False, description="Return extended status details."
+    )

immich_api/immich_response_models.py

@@ -0,0 +1,15 @@
+#!/usr/bin/python
+"""Pydantic response models for Immich Api API payloads."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SystemStatusResponse(BaseModel):
+    """Response model for system status queries."""
+
+    status: str | None = Field(default=None, description="Service status string.")
+    raw: dict[str, Any] | None = Field(
+        default=None, description="Raw response payload."
+    )

immich_api/kg_ingest.py

@@ -0,0 +1,75 @@
+"""Explicit album metadata submission through the SDK; no implicit ingestion."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from agent_connector_sdk.ingest import (
+    ChangeSet,
+    Entity,
+    IngestBinding,
+    KnowledgeIngest,
+    current_ingest,
+)
+from agent_connector_sdk.ingest.request import build_request
+from epistemic_graph.generated.source_ingestion import SourceIngestionMode
+
+from .album_metadata import album_graph_properties, project_album
+
+
+async def ingest_album_metadata(
+    records: list[dict],
+    *,
+    source_scope: str,
+    ingest: KnowledgeIngest | None = None,
+):
+    """Submit at most five metadata records and return the unmodified EG receipt.
+
+    source_scope is an operator-assigned opaque label unique to the provider
+    instance AND account/authorization scope. It is not a URL or credential.
+    The caller must separately authorize graph persistence; this is not an MCP
+    tool and listing/calling provider tools never invokes it automatically.
+    No photos, person observations, links, withdrawals or reconciliation occur.
+    """
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", source_scope):
+        raise ValueError("source_scope must be an opaque instance/account label")
+    if not 1 <= len(records) <= 5:
+        raise ValueError("ingest_album_metadata requires one to five records")
+    projected = [project_album(record) for record in records]
+    if len({record["id"] for record in projected}) != len(projected):
+        raise ValueError("duplicate album identity")
+    scope = hashlib.sha256(source_scope.encode()).hexdigest()
+    binding = IngestBinding(
+        connector="immich-api",
+        stream=f"album-metadata:{scope}",
+        server="Immich Api",
+        tool="album_metadata_sample",
+        strict_schema=True,
+    )
+    changes = _album_changes(projected)
+    _validate_privacy(binding, changes)
+    service = ingest if ingest is not None else current_ingest()
+    return await service.submit(binding, changes)
+
+
+def _album_changes(projected):
+    entities = tuple(
+        Entity(
+            id=record["id"],
+            node_type="ImmichAlbum",
+            properties=album_graph_properties(record),
+            updated_at=record["updatedAt"],
+        )
+        for record in projected
+    )
+    return ChangeSet(entities=entities, mode=SourceIngestionMode.DELTA)
+
+
+def _validate_privacy(binding, changes):
+    preview = build_request(binding, changes, previous=None)
+    if any(
+        record.payload.get("immichAlbumId") != record.record_id
+        for record in preview.records
+    ):
+        raise ValueError("SDK privacy guard changed album identity; no submission")

immich_api/mcp/__init__.py

@@ -0,0 +1,21 @@
+"""Catalog-bound registrars preserving the SDK's per-domain toggles."""
+
+from functools import partial
+
+from ..auth import get_client
+from ..openapi_runtime import CONTRACT, register_domain
+from .album_sample import register_album_sample_tools as register_album_sample_tools
+
+
+def _domain_registrar(domain):
+    registrar = partial(register_domain, domain=domain, client_factory=get_client)
+    registrar.__name__ = f"register_{domain}_tools"
+    return registrar
+
+
+globals().update(
+    {
+        f"register_{domain}_tools": _domain_registrar(domain)
+        for domain in sorted(CONTRACT["domains"])
+    }
+)

immich_api/mcp/album_sample.py

@@ -0,0 +1,38 @@
+"""One bounded read-only capability built from an allowlisted OpenAPI operation."""
+
+from typing import Annotated
+
+from agent_connector_sdk.mcp.concurrency import run_blocking
+from fastmcp import FastMCP
+from pydantic import Field
+
+from ..album_metadata import AlbumSample, album_sample
+from ..auth import get_client
+
+
+def register_album_sample_tools(mcp: FastMCP):
+    @mcp.tool(
+        tags={"album_sample", "read-only"},
+        annotations={
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "idempotentHint": True,
+            "openWorldHint": True,
+        },
+    )
+    async def album_metadata_sample(
+        limit: Annotated[int, Field(ge=1, le=5)] = 1,
+    ) -> AlbumSample:
+        """Sample up to five owned albums; omit membership, paths and share secrets.
+
+        Uses getAllAlbums with isOwned=true. The API has no server-side limit;
+        its existing response byte/time limits still apply. This read capability
+        returns a non-authoritative sample and never ingests or withdraws.
+        CONCEPT:IMMICH-001
+        """
+        response = await run_blocking(
+            get_client().execute,
+            "albums",
+            {"action": "getAllAlbums", "query": {"isOwned": True}},
+        )
+        return album_sample(response["data"], limit)

immich_api/mcp_config.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

immich_api/mcp_server.py

@@ -0,0 +1,50 @@
+import sys
+from pathlib import Path
+
+from agent_connector_sdk.config import load_config
+from agent_connector_sdk.mcp.content import ConnectorContent
+from agent_connector_sdk.mcp.server import create_mcp_server
+from agent_connector_sdk.mcp.tool_surface import register_tool_surface
+
+from . import mcp as tool_modules
+
+__version__ = "0.1.0"
+
+
+def get_mcp_instance(*, command_args=None):
+    """Construct one SDK-governed server and its native package content."""
+    load_config()
+    package_root = Path(__file__).resolve().parent
+    args, mcp, middlewares = create_mcp_server(
+        name="Immich Api",
+        version=__version__,
+        instructions="Immich Api API + MCP Server",
+        command_args=command_args,
+        content=ConnectorContent(
+            connector="immich-api",
+            package_root=package_root,
+            package_version=__version__,
+            manifest_path=package_root / "connector_manifest.yml",
+        ),
+    )
+    register_tool_surface(mcp, service="immich-api", tools_module=tool_modules)
+    for middleware in middlewares:
+        mcp.add_middleware(middleware)
+    return mcp, args, middlewares
+
+
+def build_server(*, command_args=None):
+    return get_mcp_instance(command_args=command_args)[0]
+
+
+def mcp_server():
+    mcp, args, _ = get_mcp_instance()
+    print("Starting Immich Api MCP", file=sys.stderr)
+    options = (
+        {} if args.transport == "stdio" else {"host": args.host, "port": args.port}
+    )
+    mcp.run(transport=args.transport, **options)
+
+
+if __name__ == "__main__":
+    mcp_server()

immich_api/ontology/__init__.py

@@ -0,0 +1,6 @@
+"""Immich Api ontology contribution (CONCEPT:AU-KG.ontology.federation-provider-leg).
+
+Data-only subpackage carrying ``immich.ttl`` (the ``owl:Ontology``
+``http://knuckles.team/kg/immich`` module) which the agent-utilities hub
+federates via the ``agent_utilities.ontology_providers`` entry-point.
+"""