dimu 0.2.0__tar.gz

dimu-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nedomkull Mathematical Modeling
+
+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.

dimu-0.2.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: dimu
+Version: 0.2.0
+Summary: Transparent Python client and AI-friendly API for DigitaltMuseum
+Author-email: Henrik Blidh <henrik.blidh@nedomkull.com>
+Maintainer-email: Henrik Blidh <henrik.blidh@nedomkull.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: api
+Requires-Dist: fastapi<1,>=0.115; extra == "api"
+Requires-Dist: uvicorn<1,>=0.34; extra == "api"
+Provides-Extra: docs
+Requires-Dist: fastapi<1,>=0.115; extra == "docs"
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.6; extra == "docs"
+Requires-Dist: mkdocs-static-i18n<2,>=1.3.1; extra == "docs"
+Requires-Dist: mkdocstrings[python]<1.1,>=0.29; extra == "docs"
+Provides-Extra: test
+Requires-Dist: fastapi<1,>=0.115; extra == "test"
+Dynamic: license-file
+
+# dimu - Digitalt Museum-klient och FastAPI-proxy
+
+`dimu` är en transparent Python-klient och en valfri FastAPI-proxy för
+[DigitaltMuseums publika API](https://store-search.dimu.org/docs). Indata
+valideras med Pydantic, men lyckade sök- och objektsvar lämnas orörda.
+
+```python
+from dimu import DimuClient, SearchRequest, SearchTerm
+
+with DimuClient() as client:  # använder demo och varnar om DIMU_API_KEY saknas
+    response = client.search(SearchRequest(query="Uppsala slott", limit=5))
+    response.raise_for_status()
+    print(response.json())
+```
+
+Installera biblioteket med `pip install dimu`. För HTTP-tjänsten används
+`pip install "dimu[api]"` och följande miljövariabler:
+
+```text
+DIMU_API_KEY=<valfri produktionsnyckel från DigitaltMuseum>
+DIMU_SERVICE_TOKEN=<lång slumpmässig token>
+```
+
+Starta sedan tjänsten:
+
+```console
+uvicorn dimu.api:app --host 127.0.0.1 --port 8000
+```
+
+För en Ubuntu-server med Supervisor, Nginx och Let's Encrypt:
+
+```console
+sudo DIMU_SERVICE_TOKEN='byt-mig' DIMU_API_KEY='demo' \
+  bash deploy/ubuntu.sh api.example.se admin@example.se
+```
+
+En container kan byggas med `docker build -t dimu .` och köras med
+`docker run --rm -p 8000:8000 -e DIMU_SERVICE_TOKEN='byt-mig' dimu`.
+GitHub Actions publicerar Git-taggen och `latest` till GitHub Container
+Registry och skapar en GitHub Release när en Git-tagg pushas.
+
+Fullständig dokumentation på svenska och norskt bokmål finns i katalogen
+`docs/` och byggs med `mkdocs build --strict`. Tester körs med
+`python -m unittest discover -s tests -v`.
+
+Programvaran är licensierad under MIT. Metadata och bilder får återanvändas
+enligt licensen i respektive post. Paketet är ingen lokal spegel och lagrar
+inte DigitaltMuseums data.

dimu-0.2.0/README.md

@@ -0,0 +1,48 @@
+# dimu - Digitalt Museum-klient och FastAPI-proxy
+
+`dimu` är en transparent Python-klient och en valfri FastAPI-proxy för
+[DigitaltMuseums publika API](https://store-search.dimu.org/docs). Indata
+valideras med Pydantic, men lyckade sök- och objektsvar lämnas orörda.
+
+```python
+from dimu import DimuClient, SearchRequest, SearchTerm
+
+with DimuClient() as client:  # använder demo och varnar om DIMU_API_KEY saknas
+    response = client.search(SearchRequest(query="Uppsala slott", limit=5))
+    response.raise_for_status()
+    print(response.json())
+```
+
+Installera biblioteket med `pip install dimu`. För HTTP-tjänsten används
+`pip install "dimu[api]"` och följande miljövariabler:
+
+```text
+DIMU_API_KEY=<valfri produktionsnyckel från DigitaltMuseum>
+DIMU_SERVICE_TOKEN=<lång slumpmässig token>
+```
+
+Starta sedan tjänsten:
+
+```console
+uvicorn dimu.api:app --host 127.0.0.1 --port 8000
+```
+
+För en Ubuntu-server med Supervisor, Nginx och Let's Encrypt:
+
+```console
+sudo DIMU_SERVICE_TOKEN='byt-mig' DIMU_API_KEY='demo' \
+  bash deploy/ubuntu.sh api.example.se admin@example.se
+```
+
+En container kan byggas med `docker build -t dimu .` och köras med
+`docker run --rm -p 8000:8000 -e DIMU_SERVICE_TOKEN='byt-mig' dimu`.
+GitHub Actions publicerar Git-taggen och `latest` till GitHub Container
+Registry och skapar en GitHub Release när en Git-tagg pushas.
+
+Fullständig dokumentation på svenska och norskt bokmål finns i katalogen
+`docs/` och byggs med `mkdocs build --strict`. Tester körs med
+`python -m unittest discover -s tests -v`.
+
+Programvaran är licensierad under MIT. Metadata och bilder får återanvändas
+enligt licensen i respektive post. Paketet är ingen lokal spegel och lagrar
+inte DigitaltMuseums data.

dimu-0.2.0/dimu/__init__.py

@@ -0,0 +1,48 @@
+"""Transparent client for the DigitaltMuseum public API."""
+
+from .client import API_URL, DimuClient
+from .models import (
+    ArtifactFormat,
+    ArtifactRequest,
+    ArtifactType,
+    Collection,
+    CollectionsRequest,
+    Country,
+    FacetField,
+    MatchMode,
+    Occurrence,
+    SearchField,
+    SearchMode,
+    SearchRequest,
+    SearchTerm,
+    SortOrder,
+    StoredField,
+)
+
+__all__ = [
+    "API_URL",
+    "ArtifactFormat",
+    "ArtifactRequest",
+    "ArtifactType",
+    "Collection",
+    "CollectionsRequest",
+    "Country",
+    "DimuClient",
+    "FacetField",
+    "MatchMode",
+    "Occurrence",
+    "SearchField",
+    "SearchMode",
+    "SearchRequest",
+    "SearchTerm",
+    "SortOrder",
+    "StoredField",
+    "main",
+]
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command-line client."""
+    from .cli import main as cli_main
+
+    return cli_main(argv)

dimu-0.2.0/dimu/__main__.py

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

dimu-0.2.0/dimu/api.py

@@ -0,0 +1,205 @@
+"""FastAPI-proxy som validerar frågor och bevarar DigitaltMuseums svar."""
+
+from __future__ import annotations
+
+import copy
+import hmac
+import os
+from contextlib import asynccontextmanager
+from typing import Annotated, Any, Callable
+from xml.etree import ElementTree
+
+import httpx
+from fastapi import Depends, FastAPI, HTTPException, Path, Query, Request
+from fastapi.responses import JSONResponse, Response
+
+from .client import DimuClient
+from .models import (
+    ArtifactFormat,
+    ArtifactRequest,
+    Collection,
+    CollectionsRequest,
+    Country,
+    SearchRequest,
+)
+
+
+def _strict_schema(model: type[SearchRequest] | type[ArtifactRequest] | type[CollectionsRequest]) -> dict[str, Any]:
+    """Konvertera ett Pydantic-schema till OpenAI:s strict-format."""
+    schema = copy.deepcopy(model.model_json_schema())
+
+    def visit(value: Any) -> None:
+        if isinstance(value, dict):
+            value.pop("default", None)
+            if isinstance(value.get("format"), str):
+                value.pop("format")
+            properties = value.get("properties")
+            if isinstance(properties, dict):
+                value["additionalProperties"] = False
+                value["required"] = list(properties)
+            for child in value.values():
+                visit(child)
+        elif isinstance(value, list):
+            for child in value:
+                visit(child)
+
+    visit(schema)
+    return schema
+
+
+def openai_tools() -> list[dict[str, Any]]:
+    """Returnera verktygsdefinitioner för OpenAI Responses API."""
+    return [
+        {
+            "type": "function",
+            "name": "search_digitaltmuseum",
+            "description": (
+                "Sök oförändrade poster i DigitaltMuseum. Använd strukturerade fält i första hand; "
+                "raw_query och raw_filter_queries finns när exakt Solr-syntax behövs. Svaret är "
+                "DigitaltMuseums fullständiga råa JSON och ska inte antas ha en förenklad form."
+            ),
+            "parameters": _strict_schema(SearchRequest),
+            "strict": True,
+        },
+        {
+            "type": "function",
+            "name": "get_digitaltmuseum_artifact",
+            "description": (
+                "Hämta den fullständiga, oförändrade posten för ett unique_id eller uuid från en sökträff. "
+                "Använd simple_json för chatbotläsning och ABM eller ESE endast när originalformatet behövs."
+            ),
+            "parameters": _strict_schema(ArtifactRequest),
+            "strict": True,
+        },
+        {
+            "type": "function",
+            "name": "list_digitaltmuseum_collections",
+            "description": (
+                "Lista svenska och/eller norska museer och samlingar samt deras identifierare, så att en "
+                "senare sökning kan begränsas med collection_ids."
+            ),
+            "parameters": _strict_schema(CollectionsRequest),
+            "strict": True,
+        },
+    ]
+
+
+def _upstream(call: Callable[[], httpx.Response]) -> httpx.Response:
+    try:
+        response = call()
+    except httpx.TimeoutException as error:
+        raise HTTPException(status_code=504, detail="DigitaltMuseum svarade inte inom tidsgränsen.") from error
+    except httpx.RequestError as error:
+        raise HTTPException(status_code=502, detail="Det gick inte att kontakta DigitaltMuseum.") from error
+    if not response.is_success:
+        raise HTTPException(
+            status_code=502,
+            detail=f"DigitaltMuseum svarade med HTTP {response.status_code}.",
+        )
+    return response
+
+
+def _verbatim(response: httpx.Response) -> Response:
+    headers = {}
+    if content_type := response.headers.get("content-type"):
+        headers["content-type"] = content_type
+    return Response(content=response.content, status_code=response.status_code, headers=headers)
+
+
+def create_app(
+    *,
+    client: DimuClient | None = None,
+    api_key: str | None = None,
+    service_token: str | None = None,
+) -> FastAPI:
+    """Skapa API:t; miljökonfigurationen kontrolleras vid start."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        token = service_token or os.getenv("DIMU_SERVICE_TOKEN")
+        if not token:
+            raise RuntimeError("DIMU_SERVICE_TOKEN krävs")
+
+        app.state.service_token = token
+        app.state.dimu = client or DimuClient(api_key or os.getenv("DIMU_API_KEY"))
+        try:
+            yield
+        finally:
+            if client is None:
+                app.state.dimu.close()
+
+    app = FastAPI(
+        title="dimu",
+        description="Tunn, validerande proxy som lämnar DigitaltMuseums publicerade data oförändrad.",
+        version="0.2.0",
+        lifespan=lifespan,
+    )
+
+    def authenticate(request: Request) -> None:
+        supplied = request.headers.get("authorization", "")
+        expected = f"Bearer {request.app.state.service_token}"
+        if not hmac.compare_digest(supplied.encode(), expected.encode()):
+            raise HTTPException(
+                status_code=401,
+                detail="Ogiltig Bearer-token.",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+    def dimu(request: Request) -> DimuClient:
+        return request.app.state.dimu
+
+    secured = [Depends(authenticate)]
+
+    @app.get("/health", dependencies=secured)
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/v1/collections", dependencies=secured)
+    def collections(
+        countries: list[Country] = Query(
+            default=[Country.SWEDEN, Country.NORWAY], min_length=1, max_length=2
+        ),
+        dimu_client: DimuClient = Depends(dimu),
+    ) -> list[Collection]:
+        result: list[Collection] = []
+        for country in dict.fromkeys(countries):
+            response = _upstream(lambda country=country: dimu_client.collections_raw(country))
+            try:
+                root = ElementTree.fromstring(response.content)
+            except ElementTree.ParseError as error:
+                raise HTTPException(status_code=502, detail="DigitaltMuseum returnerade ogiltig XML.") from error
+            result.extend(
+                Collection(
+                    identifier=owner.findtext("identifier", ""),
+                    name=owner.findtext("name", ""),
+                    parent=owner.findtext("parent"),
+                    country=country,
+                )
+                for owner in root.findall("owner")
+            )
+        return result
+
+    @app.get("/v1/collections/{country}/raw", dependencies=secured)
+    def collections_raw(country: Country, dimu_client: DimuClient = Depends(dimu)) -> Response:
+        return _verbatim(_upstream(lambda: dimu_client.collections_raw(country)))
+
+    @app.post("/v1/search", dependencies=secured)
+    def search(search_request: SearchRequest, dimu_client: DimuClient = Depends(dimu)) -> Response:
+        return _verbatim(_upstream(lambda: dimu_client.search(search_request)))
+
+    @app.get("/v1/artifacts/{unique_id}", dependencies=secured)
+    def artifact(
+        unique_id: Annotated[str, Path(min_length=1, pattern=r".*\S.*")],
+        format: ArtifactFormat = ArtifactFormat.SIMPLE_JSON,
+        dimu_client: DimuClient = Depends(dimu),
+    ) -> Response:
+        return _verbatim(_upstream(lambda: dimu_client.artifact(unique_id, format)))
+
+    @app.get("/v1/openai-tools", dependencies=secured)
+    def tools() -> JSONResponse:
+        return JSONResponse(openai_tools())
+
+    return app
+
+
+app = create_app()

dimu-0.2.0/dimu/cli.py

@@ -0,0 +1,70 @@
+"""Command-line interface using the public client and request model."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from xml.etree.ElementTree import ParseError
+
+import httpx
+from pydantic import ValidationError
+
+from .client import DimuClient
+from .models import ArtifactFormat, Country, SearchRequest
+
+
+def _positive_int(value: str) -> int:
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return number
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Query the DigitaltMuseum API")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    owner_parser = commands.add_parser("owners", help="list museums/collections")
+    owner_parser.add_argument("--country", default="se", choices=("se", "no"))
+
+    search_parser = commands.add_parser("search", help="search published records")
+    search_parser.add_argument("query")
+    search_parser.add_argument("--owner", action="append", default=[], help="owner code; may be repeated")
+    search_parser.add_argument("--rows", type=_positive_int, default=10)
+    search_parser.add_argument("--pictures", action="store_true")
+
+    artifact_parser = commands.add_parser("artifact", help="fetch one full record")
+    artifact_parser.add_argument("unique_id")
+    artifact_parser.add_argument("--format", default="simple_json", choices=[item.value for item in ArtifactFormat])
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return a process exit code."""
+    args = _parser().parse_args(argv)
+    try:
+        with DimuClient() as client:
+            if args.command == "owners":
+                result = [item.model_dump(mode="json") for item in client.collections(Country(args.country))]
+                print(json.dumps(result, ensure_ascii=False, indent=2))
+                return 0
+            if args.command == "search":
+                response = client.search(
+                    SearchRequest(
+                        query=args.query,
+                        collection_ids=args.owner,
+                        limit=args.rows,
+                        has_pictures=True if args.pictures else None,
+                    )
+                )
+            else:
+                response = client.artifact(args.unique_id, args.format)
+            response.raise_for_status()
+            sys.stdout.buffer.write(response.content)
+            if not response.content.endswith(b"\n"):
+                sys.stdout.buffer.write(b"\n")
+            return 0
+    except (httpx.HTTPError, ValidationError, ValueError, ParseError) as error:
+        print(f"DigitaltMuseum request failed: {error}", file=sys.stderr)
+        return 1

dimu-0.2.0/dimu/client.py

@@ -0,0 +1,89 @@
+"""HTTP-klient för DigitaltMuseum utan normalisering av svar."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from xml.etree import ElementTree
+
+import httpx
+
+from .models import ArtifactFormat, ArtifactRequest, Collection, Country, SearchRequest
+
+API_URL = "https://api.dimu.org"
+
+
+class DimuClient:
+    """Återanvändbar synkron klient för DigitaltMuseums publika API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = API_URL,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("DIMU_API_KEY") or "demo"
+        if self.api_key == "demo":
+            warnings.warn(
+                "dimu använder DigitaltMuseums demo-nyckel; sätt DIMU_API_KEY för produktion",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=True,
+            headers={"User-Agent": "dimu/0.2"},
+        )
+
+    def __enter__(self) -> "DimuClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Stäng poolade nätverksanslutningar."""
+        self._client.close()
+
+    def _get(self, path: str, params: list[tuple[str, str]]) -> httpx.Response:
+        return self._client.get(path, params=[*params, ("api.key", self.api_key)])
+
+    def search(self, request: SearchRequest) -> httpx.Response:
+        """Kör en sökning och returnera DigitaltMuseums otolkade svar."""
+        return self._get("/api/solr/select", request.to_params())
+
+    def artifact(
+        self,
+        unique_id: str,
+        format: ArtifactFormat | str = ArtifactFormat.SIMPLE_JSON,
+    ) -> httpx.Response:
+        """Hämta ett fullständigt objekt och returnera det otolkade svaret."""
+        request = ArtifactRequest(unique_id=unique_id, format=format)
+        return self._get(
+            "/api/artifact",
+            [("unique_id", request.unique_id), ("mapping", request.format.value)],
+        )
+
+    def collections_raw(self, country: Country | str) -> httpx.Response:
+        """Hämta den ursprungliga XML-listan över publicister för ett land."""
+        return self._get("/api/owners", [("country", Country(country).value)])
+
+    def collections(self, country: Country | str) -> list[Collection]:
+        """Tolka publicistlistan till den lilla JSON-form som chatboten använder."""
+        selected_country = Country(country)
+        response = self.collections_raw(selected_country)
+        response.raise_for_status()
+        root = ElementTree.fromstring(response.content)
+        return [
+            Collection(
+                identifier=owner.findtext("identifier", ""),
+                name=owner.findtext("name", ""),
+                parent=owner.findtext("parent"),
+                country=selected_country,
+            )
+            for owner in root.findall("owner")
+        ]