immich-api 0.2.0__py3-none-any.whl

immich_api/__init__.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+import warnings
+
+warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+
+__all__: list[str] = []
+
+CORE_MODULES = [
+    "immich_api.api",
+    "immich_api.error_authority",
+]
+
+OPTIONAL_MODULES = {
+    "immich_api.mcp_server": "mcp",
+}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    try:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+    except ImportError:
+        pass
+
+for module_name, extra_name in OPTIONAL_MODULES.items():
+    module = _import_module_safely(module_name)
+    if module is not None:
+        _expose_members(module)
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
+    else:
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
+
+__all__.extend(["_MCP_AVAILABLE"])

immich_api/__main__.py

@@ -0,0 +1,4 @@
+from .mcp_server import mcp_server
+
+if __name__ == "__main__":
+    mcp_server()

immich_api/album_metadata.py

@@ -0,0 +1,119 @@
+"""Bounded, explicit projection of album metadata; no network or graph work."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import TypedDict
+from uuid import UUID
+
+
+class AlbumMetadata(TypedDict):
+    id: str
+    node_type: str
+    albumName: str
+    assetCount: int
+    shared: bool
+    hasSharedLink: bool
+    createdAt: str
+    updatedAt: str
+
+
+class AlbumSample(TypedDict):
+    records: list[AlbumMetadata]
+    complete: bool
+    authoritative: bool
+    source_action: str
+    source_schema_sha256: str
+
+
+SOURCE_SHA256 = "7db8383741eeb5c5c8c87a6221cd1cdd1206c8b1190b83363c64223a00bb020b"
+
+
+def album_graph_properties(record: dict) -> dict[str, str | int | bool]:
+    """Map selected provider fields to the actual ontology predicate keys."""
+    projected = project_album(record)
+    provenance = json.loads(
+        (Path(__file__).parent / "ontology/schema-provenance.json").read_text()
+    )
+    targets = {
+        item["source_pointer"].rsplit("/", 1)[1]: item["property"]
+        for item in provenance["properties"]
+        if item["class"] == "ImmichAlbum" and item["range"].startswith("xsd:")
+    }
+    return {
+        targets[field]: value
+        for field, value in projected.items()
+        if field != "node_type"
+    }
+
+
+def _validate_timestamp(value):
+    try:
+        valid = (
+            isinstance(value, str)
+            and datetime.fromisoformat(value.replace("Z", "+00:00")).tzinfo is not None
+        )
+    except ValueError:
+        valid = False
+    if not valid:
+        raise ValueError("album metadata requires timestamps with time zones")
+
+
+def _validate_album_fields(record):
+    name, count = record.get("albumName"), record.get("assetCount")
+    if not isinstance(name, str) or type(count) is not int:
+        raise ValueError("album metadata does not satisfy its source schema")
+    if not 0 <= count <= 9007199254740991:
+        raise ValueError("album metadata does not satisfy its source schema")
+    for key in ("shared", "hasSharedLink"):
+        if type(record.get(key)) is not bool:
+            raise ValueError("album metadata does not satisfy its source schema")
+    for key in ("createdAt", "updatedAt"):
+        _validate_timestamp(record.get(key))
+
+
+def project_album(record: dict) -> AlbumMetadata:
+    """Retain only declared fields; private nested values never leave this function."""
+    record_id = record.get("id")
+    if not isinstance(record_id, str) or UUID(record_id).version != 4:
+        raise ValueError("album requires a stable UUID v4 identity")
+    _validate_album_fields(record)
+    return AlbumMetadata(
+        id=record_id,
+        node_type="ImmichAlbum",
+        albumName=record["albumName"],
+        assetCount=record["assetCount"],
+        shared=record["shared"],
+        hasSharedLink=record["hasSharedLink"],
+        createdAt=record["createdAt"],
+        updatedAt=record["updatedAt"],
+    )
+
+
+def _validate_source(records):
+    if not isinstance(records, list) or any(
+        not isinstance(record, dict) for record in records
+    ):
+        raise ValueError("album source must return a list of objects")
+    identities = [record.get("id") for record in records]
+    if any(not isinstance(value, str) for value in identities):
+        raise ValueError("album source identities must be unique strings")
+    if len(set(identities)) != len(identities):
+        raise ValueError("album source identities must be unique strings")
+
+
+def album_sample(records: list[dict], limit: int = 1) -> AlbumSample:
+    """Return a deterministic bounded sample, never an authoritative live set."""
+    if type(limit) is not int or not 1 <= limit <= 5:
+        raise ValueError("album sample limit must be between one and five")
+    _validate_source(records)
+    selected = sorted(records, key=lambda record: record["id"])[:limit]
+    return AlbumSample(
+        records=[project_album(record) for record in selected],
+        complete=len(records) <= limit,
+        authoritative=False,
+        source_action="getAllAlbums",
+        source_schema_sha256=SOURCE_SHA256,
+    )

immich_api/api/__init__.py

@@ -0,0 +1,3 @@
+from .api_client_system import ApiClientSystem
+
+__all__ = ["ApiClientSystem"]

immich_api/api/api_client_system.py

@@ -0,0 +1,7 @@
+"""Provider client with operation-bound OpenAPI dispatch."""
+
+from ..openapi_runtime import OpenApiClient
+
+
+class ApiClientSystem(OpenApiClient):
+    """Use the canonical client factory with validated domain actions."""

immich_api/auth.py

@@ -0,0 +1,94 @@
+"""Resolve provider credentials and delegated caller auth through canonical SDK APIs."""
+
+from contextlib import ExitStack
+
+import httpx
+from agent_connector_sdk.auth.delegation import DelegatedTokenAuth, DelegationSettings
+from agent_connector_sdk.auth.static import api_key_auth, bearer_auth
+from agent_connector_sdk.config import load_config, setting
+from agent_connector_sdk.http.client import create_http_client
+from agent_connector_sdk.http.options import HttpClientOptions
+from agent_connector_sdk.tls.resolve import resolve_tls_profile
+
+from .api import ApiClientSystem
+from .openapi_auth_scheme import AuthKind, declared_scheme
+from .openapi_runtime import CONTRACT
+
+_client = None
+_resources = ExitStack()
+
+
+def _bearer_scheme(definition):
+    return definition is not None and definition.kind is AuthKind.BEARER
+
+
+def _delegated_auth(delegation, resources):
+    token_tls = resolve_tls_profile("oidc")
+    resources.callback(token_tls.cleanup)
+    token_client = create_http_client(
+        HttpClientOptions(base_url=delegation.token_endpoint, tls=token_tls)
+    )
+    resources.callback(token_client.close)
+    return DelegatedTokenAuth(delegation, http_client=token_client)
+
+
+def _static_auth(reference, definition):
+    if definition is None:
+        raise ValueError("A credential requires a declared authentication scheme")
+    if definition.kind is AuthKind.HEADER:
+        return api_key_auth(reference, header=definition.header)
+    return bearer_auth(reference)
+
+
+def _resolve_auth(resources):
+    scheme = setting("IMMICH_API_AUTH_SCHEME", "api_key")
+    definition = declared_scheme(scheme, CONTRACT["security_schemes"])
+    delegation = DelegationSettings.from_settings()
+    if delegation.enabled:
+        if not _bearer_scheme(definition):
+            raise ValueError("Delegation requires a declared HTTP bearer auth scheme")
+        return _delegated_auth(delegation, resources), scheme
+    reference = setting("IMMICH_API_TOKEN_REF", "")
+    if not reference:
+        return httpx.Auth(), None
+    return _static_auth(reference, definition), scheme
+
+
+def get_client():
+    """Build one client; delegated auth resolves the verified caller per request."""
+    global _client, _resources
+    if _client is not None:
+        return _client
+    load_config()
+    base_url = setting("IMMICH_API_BASE_URL", "")
+    if not base_url:
+        raise ValueError("Provider base URL is required")
+    with ExitStack() as resources:
+        tls = resolve_tls_profile("immich-api")
+        resources.callback(tls.cleanup)
+        auth, credential_scheme = _resolve_auth(resources)
+        client = ApiClientSystem(
+            base_url=base_url,
+            auth=auth,
+            tls_profile=tls,
+            credential_scheme=credential_scheme,
+            write_mode=(
+                "read-write"
+                if setting("IMMICH_API_ALLOW_WRITES", False)
+                else "read-only"
+            ),
+            allow_plaintext=setting("IMMICH_API_ALLOW_PLAINTEXT", False),
+        )
+        resources.callback(client.close)
+        _resources = resources.pop_all()
+        _client = client
+    return client
+
+
+def close_client():
+    """Close the cached client, token client and materialized TLS resources."""
+    global _client
+    try:
+        _resources.close()
+    finally:
+        _client = None

immich_api/connector_manifest.yml

@@ -0,0 +1,212 @@
+{
+  "connector": "immich-api",
+  "ontology_source": "immich",
+  "schema_version": "1",
+  "resources": [
+    {
+      "name": "ImmichAsset",
+      "relations": [
+        {
+          "name": "immichAssetOwner",
+          "target": "ImmichUser",
+          "label": "owner"
+        },
+        {
+          "name": "immichAssetPeople",
+          "target": "ImmichPersonRecord",
+          "label": "people"
+        },
+        {
+          "name": "immichAssetTags",
+          "target": "ImmichTag",
+          "label": "tags"
+        },
+        {
+          "name": "immichAssetStack",
+          "target": "ImmichAssetStack",
+          "label": "stack"
+        }
+      ]
+    },
+    {
+      "name": "ImmichAlbum",
+      "relations": [
+        {
+          "name": "immichAlbumAlbumUsers",
+          "target": "ImmichAlbumMembership",
+          "label": "albumUsers"
+        }
+      ]
+    },
+    {
+      "name": "ImmichPersonRecord",
+      "relations": []
+    },
+    {
+      "name": "ImmichUser",
+      "relations": []
+    },
+    {
+      "name": "ImmichLibrary",
+      "relations": []
+    },
+    {
+      "name": "ImmichAlbumMembership",
+      "relations": [
+        {
+          "name": "immichAlbumMembershipUser",
+          "target": "ImmichUser",
+          "label": "user"
+        }
+      ]
+    },
+    {
+      "name": "ImmichTag",
+      "relations": []
+    },
+    {
+      "name": "ImmichAssetStack",
+      "relations": []
+    }
+  ],
+  "identity": {
+    "id_field": {
+      "ImmichAsset": "immichAssetId",
+      "ImmichAlbum": "immichAlbumId",
+      "ImmichPersonRecord": "immichPersonRecordId",
+      "ImmichUser": "immichUserId",
+      "ImmichLibrary": "immichLibraryId",
+      "ImmichTag": "immichTagId",
+      "ImmichAssetStack": "immichAssetStackId"
+    },
+    "title_field": {
+      "ImmichAlbum": "immichAlbumAlbumName",
+      "ImmichPersonRecord": "immichPersonRecordName",
+      "ImmichUser": "immichUserName",
+      "ImmichLibrary": "immichLibraryName",
+      "ImmichTag": "immichTagName"
+    },
+    "updated_field": {
+      "ImmichAlbum": "immichAlbumUpdatedAt",
+      "ImmichAsset": "immichAssetUpdatedAt"
+    }
+  },
+  "schema_mappings": {
+    "ImmichAsset": {
+      "ontology_class": "ImmichAsset",
+      "fields": {
+        "immichAssetId": "xsd:string",
+        "immichAssetType": "xsd:string",
+        "immichAssetOriginalMimeType": "xsd:string",
+        "immichAssetDuration": "xsd:integer",
+        "immichAssetWidth": "xsd:integer",
+        "immichAssetHeight": "xsd:integer",
+        "immichAssetFileCreatedAt": "xsd:dateTime",
+        "immichAssetUpdatedAt": "xsd:dateTime",
+        "immichAssetIsFavorite": "xsd:boolean",
+        "immichAssetIsArchived": "xsd:boolean",
+        "immichAssetIsTrashed": "xsd:boolean",
+        "immichAssetVisibility": "xsd:string"
+      }
+    },
+    "ImmichAlbum": {
+      "ontology_class": "ImmichAlbum",
+      "fields": {
+        "immichAlbumId": "xsd:string",
+        "immichAlbumAlbumName": "xsd:string",
+        "immichAlbumAssetCount": "xsd:integer",
+        "immichAlbumShared": "xsd:boolean",
+        "immichAlbumHasSharedLink": "xsd:boolean",
+        "immichAlbumCreatedAt": "xsd:dateTime",
+        "immichAlbumUpdatedAt": "xsd:dateTime",
+        "immichAlbumAlbumThumbnailAssetId": "xsd:string"
+      }
+    },
+    "ImmichPersonRecord": {
+      "ontology_class": "ImmichPersonRecord",
+      "fields": {
+        "immichPersonRecordId": "xsd:string",
+        "immichPersonRecordName": "xsd:string",
+        "immichPersonRecordIsHidden": "xsd:boolean",
+        "immichPersonRecordIsFavorite": "xsd:boolean",
+        "immichPersonRecordUpdatedAt": "xsd:dateTime"
+      }
+    },
+    "ImmichUser": {
+      "ontology_class": "ImmichUser",
+      "fields": {
+        "immichUserId": "xsd:string",
+        "immichUserName": "xsd:string"
+      }
+    },
+    "ImmichLibrary": {
+      "ontology_class": "ImmichLibrary",
+      "fields": {
+        "immichLibraryId": "xsd:string",
+        "immichLibraryName": "xsd:string",
+        "immichLibraryAssetCount": "xsd:integer",
+        "immichLibraryCreatedAt": "xsd:dateTime",
+        "immichLibraryUpdatedAt": "xsd:dateTime"
+      }
+    },
+    "ImmichAlbumMembership": {
+      "ontology_class": "ImmichAlbumMembership",
+      "fields": {
+        "immichAlbumMembershipRole": "xsd:string"
+      }
+    },
+    "ImmichTag": {
+      "ontology_class": "ImmichTag",
+      "fields": {
+        "immichTagId": "xsd:string",
+        "immichTagName": "xsd:string",
+        "immichTagCreatedAt": "xsd:dateTime",
+        "immichTagUpdatedAt": "xsd:dateTime"
+      }
+    },
+    "ImmichAssetStack": {
+      "ontology_class": "ImmichAssetStack",
+      "fields": {
+        "immichAssetStackId": "xsd:string",
+        "immichAssetStackAssetCount": "xsd:integer",
+        "immichAssetStackPrimaryAssetId": "xsd:string"
+      }
+    }
+  },
+  "sync": [],
+  "provenance": {
+    "generated_by": "scripts/generate_immich_content.py",
+    "source_artifacts": [
+      "openapi_contract.json",
+      "ontology/schema-provenance.json",
+      "ontology/immich.ttl",
+      "ontology/shapes/immich.ttl"
+    ],
+    "integrity": {
+      "algorithm": "sha256",
+      "hash": "c68d2270fcfbcacb40369011d3f65fdf625e6ea1eabba10bf4309f7c007e391d"
+    }
+  },
+  "review_todos": [
+    "Structural schema declarations are not evidence of live EG capture or semantic identity alignment.",
+    "Only the bounded album metadata projection is implemented for ingestion; remaining DTO classes are structural declarations.",
+    "Require explicit source/account binding, existing scoped credentials and a verified EG receipt/readback before enabling ingestion.",
+    "Ontology integrity is a byte SHA256, not canonical RDF or release certification."
+  ],
+  "policy": {
+    "pii_fields": {
+      "ImmichAlbum": [
+        "immichAlbumAlbumName"
+      ],
+      "ImmichPersonRecord": [
+        "immichPersonRecordName"
+      ],
+      "ImmichUser": [
+        "immichUserName"
+      ],
+      "ImmichTag": [
+        "immichTagName"
+      ]
+    }
+  }
+}

immich_api/connectors/mcp_source_presets.json

@@ -0,0 +1,3 @@
+{
+  "_comment": "No ingestion preset is enabled. The pinned SDK uses the preset name as stream identity, so this package cannot bind a shared preset to a provider/account scope. The read-only album_metadata_sample tool remains available. Its authoritative=false flag does not govern SDK source mode; no FULL/DELTA sweep is configured."
+}

immich_api/connectors/tool_schema_fingerprints.json

@@ -0,0 +1 @@
+{"algorithm":"agent-connector-sdk:mcp-tool-contract-compat:v2","connector":"immich-api","tools":{}}