apud 0.0.1__tar.gz

apud-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store

apud-0.0.1/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: apud
+Version: 0.0.1
+Summary: IIIF-grounded, citable vision for historical documents: region crops for VLMs, W3C annotations out
+Author: cadeos
+License-Expression: Apache-2.0
+Keywords: digital-humanities,htr,iiif,manuscripts,vlm,web-annotation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# apud
+
+Core library of [apud](https://github.com/cadeos/apud): IIIF Image/Presentation API parsing,
+model-sized region requests, W3C Web Annotations and IIIF Content State citations.

apud-0.0.1/README.md

@@ -0,0 +1,4 @@
+# apud
+
+Core library of [apud](https://github.com/cadeos/apud): IIIF Image/Presentation API parsing,
+model-sized region requests, W3C Web Annotations and IIIF Content State citations.

apud-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "apud"
+version = "0.0.1"
+description = "IIIF-grounded, citable vision for historical documents: region crops for VLMs, W3C annotations out"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "cadeos" }]
+keywords = ["iiif", "htr", "manuscripts", "digital-humanities", "vlm", "web-annotation"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+  "Topic :: Text Processing :: Linguistic",
+]
+dependencies = ["httpx>=0.27"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apud"]

apud-0.0.1/src/apud/__init__.py

@@ -0,0 +1,3 @@
+"""apud: IIIF-grounded, citable vision for historical documents."""
+
+__version__ = "0.0.1"

apud-0.0.1/src/apud/annotations.py

@@ -0,0 +1,79 @@
+"""W3C Web Annotations anchored to IIIF canvases, plus IIIF Content State links for citation."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+from urllib.parse import quote, unquote
+
+from apud.iiif.image import Region
+
+_FRAGMENT_SPEC = "http://www.w3.org/TR/media-frags/"
+
+
+def _target(canvas_id: str, manifest_id: str, region: Region) -> dict[str, Any]:
+    return {
+        "type": "SpecificResource",
+        "source": {
+            "id": canvas_id,
+            "type": "Canvas",
+            "partOf": [{"id": manifest_id, "type": "Manifest"}],
+        },
+        "selector": {
+            "type": "FragmentSelector",
+            "conformsTo": _FRAGMENT_SPEC,
+            "value": f"xywh={region.xywh}",
+        },
+    }
+
+
+def transcription_annotation(
+    annotation_id: str,
+    canvas_id: str,
+    manifest_id: str,
+    region: Region,
+    text: str,
+    *,
+    language: str | None = None,
+    generator: str | None = None,
+) -> dict[str, Any]:
+    """A transcription of ``region`` (canvas coordinates) as a Presentation 3 annotation."""
+    body: dict[str, Any] = {"type": "TextualBody", "value": text, "format": "text/plain"}
+    if language:
+        body["language"] = language
+    annotation: dict[str, Any] = {
+        "id": annotation_id,
+        "type": "Annotation",
+        "motivation": "supplementing",
+        "body": body,
+        "target": _target(canvas_id, manifest_id, region),
+    }
+    if generator:
+        annotation["generator"] = generator
+    return annotation
+
+
+def annotation_page(page_id: str, items: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "@context": "http://iiif.io/api/presentation/3/context.json",
+        "id": page_id,
+        "type": "AnnotationPage",
+        "items": items,
+    }
+
+
+def encode_content_state(canvas_id: str, manifest_id: str, region: Region) -> str:
+    """Encode a IIIF Content State pointing at a canvas region, for ``?iiif-content=`` links."""
+    state = {
+        "id": f"{canvas_id}#xywh={region.xywh}",
+        "type": "Canvas",
+        "partOf": [{"id": manifest_id, "type": "Manifest"}],
+    }
+    uri_encoded = quote(json.dumps(state, separators=(",", ":")), safe="-_.!~*'()")
+    return base64.urlsafe_b64encode(uri_encoded.encode()).decode().rstrip("=")
+
+
+def decode_content_state(encoded: str) -> dict[str, Any]:
+    padded = encoded + "=" * (-len(encoded) % 4)
+    return json.loads(unquote(base64.urlsafe_b64decode(padded).decode()))

apud-0.0.1/src/apud/client.py

@@ -0,0 +1,53 @@
+"""Thin HTTP client for IIIF endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from apud import __version__
+from apud.iiif.image import ImageService, Region, RegionRequest, parse_info
+from apud.iiif.manifest import Manifest, parse_manifest
+
+USER_AGENT = f"apud/{__version__} (+https://github.com/cadeos/apud)"
+
+
+class IIIFClient:
+    def __init__(self, timeout: float = 30.0, client: httpx.Client | None = None) -> None:
+        self._http = client or httpx.Client(
+            timeout=timeout, follow_redirects=True, headers={"User-Agent": USER_AGENT}
+        )
+
+    def __enter__(self) -> IIIFClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _json(self, url: str) -> dict[str, Any]:
+        response = self._http.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    def manifest(self, url: str) -> Manifest:
+        return parse_manifest(self._json(url))
+
+    def image_service(self, service_id: str) -> ImageService:
+        url = (
+            service_id
+            if service_id.endswith("info.json")
+            else f"{service_id.rstrip('/')}/info.json"
+        )
+        return parse_info(self._json(url))
+
+    def region(
+        self, service: ImageService, region: Region, max_side: int
+    ) -> tuple[RegionRequest, bytes]:
+        request = service.region_request(region, max_side)
+        response = self._http.get(request.url)
+        response.raise_for_status()
+        return request, response.content

apud-0.0.1/src/apud/iiif/__init__.py

@@ -0,0 +1,21 @@
+from apud.iiif.image import ImageService, Region, RegionRequest, UnsupportedRequest, parse_info
+from apud.iiif.manifest import (
+    Canvas,
+    Manifest,
+    canvas_to_image,
+    image_to_canvas,
+    parse_manifest,
+)
+
+__all__ = [
+    "Canvas",
+    "ImageService",
+    "Manifest",
+    "Region",
+    "RegionRequest",
+    "UnsupportedRequest",
+    "canvas_to_image",
+    "image_to_canvas",
+    "parse_info",
+    "parse_manifest",
+]

apud-0.0.1/src/apud/iiif/image.py

@@ -0,0 +1,124 @@
+"""IIIF Image API: parse info.json (v2 and v3) and build region requests sized for a model."""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+_LEVEL_RE = re.compile(r"level([012])")
+
+
+class UnsupportedRequest(ValueError):
+    """The image service cannot serve the request at its declared compliance level."""
+
+
+@dataclass(frozen=True)
+class Region:
+    """A rectangle in full-resolution image pixels."""
+
+    x: int
+    y: int
+    w: int
+    h: int
+
+    def __post_init__(self) -> None:
+        if self.w <= 0 or self.h <= 0:
+            raise ValueError(f"region must have positive size, got {self.w}x{self.h}")
+        if self.x < 0 or self.y < 0:
+            raise ValueError(f"region origin must be non-negative, got {self.x},{self.y}")
+
+    def clamp(self, width: int, height: int) -> Region:
+        """Crop the region to the image bounds, as an IIIF server would."""
+        if self.x >= width or self.y >= height:
+            raise ValueError("region lies entirely outside the image")
+        return Region(self.x, self.y, min(self.w, width - self.x), min(self.h, height - self.y))
+
+    @property
+    def xywh(self) -> str:
+        return f"{self.x},{self.y},{self.w},{self.h}"
+
+
+@dataclass(frozen=True)
+class RegionRequest:
+    """A ready-to-fetch region URL plus the scale needed to map model output back to the image."""
+
+    url: str
+    region: Region
+    width: int
+    height: int
+
+    @property
+    def scale(self) -> float:
+        """Requested pixels per full-resolution pixel (<= 1, servers are never asked to upscale)."""
+        return self.width / self.region.w
+
+    def to_image(self, x: float, y: float) -> tuple[float, float]:
+        """Map a point in the returned crop to full-resolution image coordinates."""
+        return self.region.x + x / self.scale, self.region.y + y / self.scale
+
+
+@dataclass(frozen=True)
+class ImageService:
+    id: str
+    width: int
+    height: int
+    version: int
+    level: int
+    sizes: list[tuple[int, int]] = field(default_factory=list)
+    max_width: int | None = None
+    max_height: int | None = None
+    max_area: int | None = None
+
+    def region_request(self, region: Region, max_side: int, fmt: str = "jpg") -> RegionRequest:
+        """Build a region URL whose longer side is at most ``max_side``, honouring server limits.
+
+        Uses pixel regions and explicit ``w,h`` sizes, the forms required from Level 1 upward.
+        """
+        if self.level < 1:
+            raise UnsupportedRequest(
+                "Level 0 services do not support region requests; stitch tiles or use `sizes`"
+            )
+        region = region.clamp(self.width, self.height)
+        limit = max_side
+        if self.max_width is not None:
+            limit = min(limit, self.max_width, self.max_height or self.max_width)
+        if self.max_area is not None:
+            limit = min(limit, math.isqrt(self.max_area))
+        factor = min(1.0, limit / max(region.w, region.h))
+        w = max(1, math.floor(region.w * factor))
+        h = max(1, math.floor(region.h * factor))
+        url = f"{self.id.rstrip('/')}/{region.xywh}/{w},{h}/0/default.{fmt}"
+        return RegionRequest(url=url, region=region, width=w, height=h)
+
+
+def parse_info(info: dict[str, Any]) -> ImageService:
+    """Parse an Image API v2 or v3 info.json document."""
+    context = info.get("@context", "")
+    contexts = context if isinstance(context, list) else [context]
+    version = 3 if any("image/3" in str(c) for c in contexts) else 2
+    service_id = info.get("id") or info.get("@id")
+    if not service_id:
+        raise ValueError("info.json has no id")
+    sizes = [(s["width"], s["height"]) for s in info.get("sizes", [])]
+    return ImageService(
+        id=service_id,
+        width=int(info["width"]),
+        height=int(info["height"]),
+        version=version,
+        level=_parse_level(info.get("profile")),
+        sizes=sizes,
+        max_width=info.get("maxWidth"),
+        max_height=info.get("maxHeight"),
+        max_area=info.get("maxArea"),
+    )
+
+
+def _parse_level(profile: Any) -> int:
+    # v3: "level2"; v2: ["http://iiif.io/api/image/2/level2.json", {...}]
+    candidates = profile if isinstance(profile, list) else [profile]
+    for candidate in candidates:
+        if isinstance(candidate, str) and (match := _LEVEL_RE.search(candidate)):
+            return int(match.group(1))
+    return 0

apud-0.0.1/src/apud/iiif/manifest.py

@@ -0,0 +1,112 @@
+"""IIIF Presentation API: lenient extraction of canvases from v2 and v3 manifests.
+
+Real-world manifests are often inconsistent (mixed v2/v3 keys, canvas sizes that differ from
+the image), so this module reads only what it needs and does not validate the whole document.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from apud.iiif.image import Region
+
+
+@dataclass(frozen=True)
+class Canvas:
+    id: str
+    width: int
+    height: int
+    label: str | None
+    image_service: str | None
+
+
+@dataclass(frozen=True)
+class Manifest:
+    id: str
+    label: str | None
+    canvases: list[Canvas]
+
+
+def parse_manifest(data: dict[str, Any]) -> Manifest:
+    manifest_id = data.get("id") or data.get("@id")
+    if not manifest_id:
+        raise ValueError("manifest has no id")
+    if "items" in data:
+        raw_canvases = data["items"]
+        to_canvas = _canvas_v3
+    else:
+        sequences = data.get("sequences") or [{}]
+        raw_canvases = sequences[0].get("canvases", [])
+        to_canvas = _canvas_v2
+    return Manifest(
+        id=manifest_id,
+        label=_label(data.get("label")),
+        canvases=[to_canvas(c) for c in raw_canvases],
+    )
+
+
+def image_to_canvas(region: Region, image_width: int, image_height: int, canvas: Canvas) -> Region:
+    """Rescale a region from image pixels to canvas coordinates (they can legitimately differ)."""
+    sx = canvas.width / image_width
+    sy = canvas.height / image_height
+    return Region(
+        round(region.x * sx), round(region.y * sy), round(region.w * sx), round(region.h * sy)
+    )
+
+
+def canvas_to_image(region: Region, image_width: int, image_height: int, canvas: Canvas) -> Region:
+    """Rescale a region from canvas coordinates to image pixels."""
+    sx = image_width / canvas.width
+    sy = image_height / canvas.height
+    return Region(
+        round(region.x * sx), round(region.y * sy), round(region.w * sx), round(region.h * sy)
+    )
+
+
+def _canvas_v3(c: dict[str, Any]) -> Canvas:
+    service = None
+    for page in c.get("items", []):
+        for anno in page.get("items", []):
+            service = _service_id(anno.get("body", {}))
+            if service:
+                break
+        if service:
+            break
+    return Canvas(c["id"], int(c["width"]), int(c["height"]), _label(c.get("label")), service)
+
+
+def _canvas_v2(c: dict[str, Any]) -> Canvas:
+    service = None
+    for image in c.get("images", []):
+        service = _service_id(image.get("resource", {}))
+        if service:
+            break
+    return Canvas(c["@id"], int(c["width"]), int(c["height"]), _label(c.get("label")), service)
+
+
+def _service_id(resource: dict[str, Any] | list[Any]) -> str | None:
+    if isinstance(resource, list):
+        resource = resource[0] if resource else {}
+    services = resource.get("service", [])
+    for service in services if isinstance(services, list) else [services]:
+        if isinstance(service, dict) and (sid := service.get("id") or service.get("@id")):
+            return sid
+    return None
+
+
+def _label(label: Any) -> str | None:
+    # v3 language map {"en": ["..."]}, v2 plain string or list of {"@value": ...}
+    if label is None:
+        return None
+    if isinstance(label, str):
+        return label
+    if isinstance(label, dict):
+        for values in label.values():
+            if values:
+                return str(values[0])
+        return None
+    if isinstance(label, list) and label:
+        first = label[0]
+        return first.get("@value") if isinstance(first, dict) else str(first)
+    return None

apud-0.0.1/tests/conftest.py

@@ -0,0 +1,28 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from samples import V2_INFO, V2_MANIFEST, V3_INFO, V3_MANIFEST
+
+
+@pytest.fixture
+def v3_info():
+    return dict(V3_INFO)
+
+
+@pytest.fixture
+def v2_info():
+    return dict(V2_INFO)
+
+
+@pytest.fixture
+def v3_manifest():
+    return V3_MANIFEST
+
+
+@pytest.fixture
+def v2_manifest():
+    return V2_MANIFEST

apud-0.0.1/tests/samples.py

@@ -0,0 +1,78 @@
+"""Sample IIIF documents shared by the core and MCP test suites."""
+
+V3_INFO = {
+    "@context": "http://iiif.io/api/image/3/context.json",
+    "id": "https://iiif.example.org/iiif/3/page1",
+    "type": "ImageService3",
+    "profile": "level2",
+    "width": 4000,
+    "height": 6000,
+    "maxWidth": 3000,
+    "sizes": [{"width": 500, "height": 750}],
+}
+
+V2_INFO = {
+    "@context": "http://iiif.io/api/image/2/context.json",
+    "@id": "https://iiif.example.org/iiif/2/page1",
+    "profile": ["http://iiif.io/api/image/2/level1.json", {"formats": ["jpg"]}],
+    "width": 2000,
+    "height": 3000,
+}
+
+V3_MANIFEST = {
+    "@context": "http://iiif.io/api/presentation/3/context.json",
+    "id": "https://iiif.example.org/manifest.json",
+    "type": "Manifest",
+    "label": {"en": ["Test codex"]},
+    "items": [
+        {
+            "id": "https://iiif.example.org/canvas/1",
+            "type": "Canvas",
+            "label": {"none": ["1r"]},
+            "width": 2000,
+            "height": 3000,
+            "items": [
+                {
+                    "type": "AnnotationPage",
+                    "items": [
+                        {
+                            "type": "Annotation",
+                            "motivation": "painting",
+                            "body": {
+                                "id": "https://iiif.example.org/iiif/3/page1/full/max/0/default.jpg",
+                                "type": "Image",
+                                "service": [
+                                    {
+                                        "id": "https://iiif.example.org/iiif/3/page1",
+                                        "type": "ImageService3",
+                                    }
+                                ],
+                            },
+                        }
+                    ],
+                }
+            ],
+        }
+    ],
+}
+
+V2_MANIFEST = {
+    "@context": "http://iiif.io/api/presentation/2/context.json",
+    "@id": "https://iiif.example.org/v2/manifest.json",
+    "label": "Old codex",
+    "sequences": [
+        {
+            "canvases": [
+                {
+                    "@id": "https://iiif.example.org/v2/canvas/1",
+                    "label": "1r",
+                    "width": 1000,
+                    "height": 1500,
+                    "images": [
+                        {"resource": {"service": {"@id": "https://iiif.example.org/iiif/2/page1"}}}
+                    ],
+                }
+            ]
+        }
+    ],
+}

apud-0.0.1/tests/test_annotations.py

@@ -0,0 +1,39 @@
+from apud.annotations import (
+    annotation_page,
+    decode_content_state,
+    encode_content_state,
+    transcription_annotation,
+)
+from apud.iiif import Region
+
+CANVAS = "https://iiif.example.org/canvas/1"
+MANIFEST = "https://iiif.example.org/manifest.json"
+
+
+def test_transcription_annotation_targets_canvas_fragment():
+    anno = transcription_annotation(
+        "urn:a1", CANVAS, MANIFEST, Region(1, 2, 3, 4), "Nel mezzo", language="it"
+    )
+    assert anno["motivation"] == "supplementing"
+    assert anno["body"] == {
+        "type": "TextualBody",
+        "value": "Nel mezzo",
+        "format": "text/plain",
+        "language": "it",
+    }
+    assert anno["target"]["source"]["id"] == CANVAS
+    assert anno["target"]["source"]["partOf"] == [{"id": MANIFEST, "type": "Manifest"}]
+    assert anno["target"]["selector"]["value"] == "xywh=1,2,3,4"
+
+
+def test_annotation_page_wraps_items():
+    page = annotation_page("urn:p", [{"id": "urn:a"}])
+    assert page["type"] == "AnnotationPage" and page["items"] == [{"id": "urn:a"}]
+
+
+def test_content_state_round_trip():
+    encoded = encode_content_state(CANVAS, MANIFEST, Region(10, 20, 30, 40))
+    assert "=" not in encoded and "+" not in encoded and "/" not in encoded
+    state = decode_content_state(encoded)
+    assert state["id"] == f"{CANVAS}#xywh=10,20,30,40"
+    assert state["partOf"][0]["id"] == MANIFEST

apud-0.0.1/tests/test_image.py

@@ -0,0 +1,58 @@
+import pytest
+
+from apud.iiif import Region, UnsupportedRequest, parse_info
+
+
+def test_parse_v3(v3_info):
+    service = parse_info(v3_info)
+    assert (service.version, service.level) == (3, 2)
+    assert service.max_width == 3000
+    assert service.sizes == [(500, 750)]
+
+
+def test_parse_v2_profile_list(v2_info):
+    service = parse_info(v2_info)
+    assert (service.version, service.level) == (2, 1)
+    assert service.id == "https://iiif.example.org/iiif/2/page1"
+
+
+def test_missing_profile_is_level0(v3_info):
+    del v3_info["profile"]
+    assert parse_info(v3_info).level == 0
+
+
+def test_region_request_downscales_to_max_side(v3_info):
+    request = parse_info(v3_info).region_request(Region(100, 200, 2000, 1000), max_side=1000)
+    assert (
+        request.url
+        == "https://iiif.example.org/iiif/3/page1/100,200,2000,1000/1000,500/0/default.jpg"
+    )
+    assert request.scale == 0.5
+    assert request.to_image(10, 20) == (120, 240)
+
+
+def test_region_request_never_upscales(v3_info):
+    request = parse_info(v3_info).region_request(Region(0, 0, 300, 200), max_side=2000)
+    assert (request.width, request.height) == (300, 200)
+
+
+def test_region_request_respects_server_limits(v3_info):
+    v3_info["maxArea"] = 1_000_000
+    request = parse_info(v3_info).region_request(Region(0, 0, 4000, 4000), max_side=5000)
+    assert max(request.width, request.height) == 1000
+
+
+def test_region_is_clamped_to_image(v3_info):
+    request = parse_info(v3_info).region_request(Region(3900, 5900, 500, 500), max_side=2000)
+    assert request.region == Region(3900, 5900, 100, 100)
+
+
+def test_level0_rejects_regions(v3_info):
+    v3_info["profile"] = "level0"
+    with pytest.raises(UnsupportedRequest):
+        parse_info(v3_info).region_request(Region(0, 0, 10, 10), max_side=100)
+
+
+def test_invalid_region():
+    with pytest.raises(ValueError):
+        Region(0, 0, 0, 10)

apud-0.0.1/tests/test_manifest.py

@@ -0,0 +1,27 @@
+from apud.iiif import Region, canvas_to_image, image_to_canvas, parse_manifest
+
+
+def test_parse_v3_manifest(v3_manifest):
+    manifest = parse_manifest(v3_manifest)
+    assert manifest.label == "Test codex"
+    [canvas] = manifest.canvases
+    assert canvas.label == "1r"
+    assert canvas.image_service == "https://iiif.example.org/iiif/3/page1"
+
+
+def test_parse_v2_manifest(v2_manifest):
+    manifest = parse_manifest(v2_manifest)
+    [canvas] = manifest.canvases
+    assert (canvas.id, canvas.width, canvas.height) == (
+        "https://iiif.example.org/v2/canvas/1",
+        1000,
+        1500,
+    )
+    assert canvas.image_service == "https://iiif.example.org/iiif/2/page1"
+
+
+def test_canvas_image_round_trip(v3_manifest):
+    [canvas] = parse_manifest(v3_manifest).canvases  # 2000x3000 canvas
+    image_region = canvas_to_image(Region(100, 150, 200, 300), 4000, 6000, canvas)
+    assert image_region == Region(200, 300, 400, 600)
+    assert image_to_canvas(image_region, 4000, 6000, canvas) == Region(100, 150, 200, 300)