Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Media-type-renderresourcesload · L-261008-ca302b (#1381)
Louis Choquel37138ad958bd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1f2a4da66..9f369e685 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,10 @@- **`pipelex init` asks where runs execute**: Enter takes the hosted Pipelex API, which signs you in unless a key is already set and asks for no provider key, and the other answer runs today's backend, routing and credential steps; the answer is written to `[run] execution`, with a warning when the working directory's project overrides it. `pipelex doctor --fix` keeps a `[run] execution` already set, keeps a `pipelex.toml` that sets none local, and takes the hosted default only for a brand-new home, `pipelex doctor` and `pipelex-agent doctor` judge a hosted setup by its Pipelex API key and report provider credentials as needed only for `--local` runs, and `pipelex-agent init` takes `"execution": "hosted"` in `--config` and reports `execution`.- **`pipelex migrate` cleans up what a former release left for the Pipelex Gateway**: a configuration set up by a release that ran on the Pipelex Gateway is refused at boot with the new `FormerReleaseConfigError`, which names what stops it and `pipelex migrate`. That command and `pipelex-agent migrate` (under the new `former_release` key) remove the Gateway's backend, routing profiles, routes and files and leave Pipelex Manifold's, which is not retired; they keep a copy of each file they change or remove, and report what they leave for a hand edit or what would still stop Pipelex from starting. `pipelex init` and `pipelex doctor --fix` offer the same cleanup, and `pipelex doctor` lists the files.+### Changed++- **`RenderResources.load` returns the media type with the bytes (Breaking)**: a document engine's `load` returns a `LoadedResource`, the file's bytes as `data` and as `mime_type` the type its source gives it, lowercased and without parameters: the `Content-Type` of an `https://` response, the type a `data:` URL declares, or the type the storage provider has for a `pipelex-storage://` key, and `None` when the source gives none. The plugin API version moves to 6, so a plugin declaring `targets_api = 5` is refused at discovery and is rebuilt against this release, reading `.data` where it read the bytes.+### Fixed- **The CLIs identify themselves as `pipelex-cli` to the hosted API**: every request `pipelex run --hosted`, `pipelex-agent run --hosted` and `pipelex login` send now leads its `User-Agent` with `pipelex-cli/<version>`, the token the client-identification spec reserves for these CLIs, so the hosted API counts their runs on its CLI surface instead of as calls from an SDK.diff --git a/docs/under-the-hood/document-engine-plugins.md b/docs/under-the-hood/document-engine-plugins.mdindex c2aaaa85c..953444b05 100644--- a/docs/under-the-hood/document-engine-plugins.md+++ b/docs/under-the-hood/document-engine-plugins.md@@ -119,11 +119,25 @@ def render(self, *, job: RenderJob, resources: RenderResources) -> RenderedDocum```- **`RenderJob`** is plain data, which Pipelex builds in the print stage from the step's composition and hands to the worker in the same process. It has a JSON round trip for an engine that prints in another process, in which the template's bytes are URL-safe base64 and a date or a time is its ISO text. It holds the format and source, the file's name with its suffix, the document's title, and exactly the payload its source names, `layout` (a `LayoutDocument` from `layout_tree.py`), `html`, or `template` with `data`, the inputs as plain data by input name. It carries no Pipelex object, so an ordinary Pipelex release does not break an engine; a change to it, or to the worker, is a change of the plugin contract.-- **`RenderResources.load(uri=…, position=…)`** is how an engine reads a file its document names, such as an image. It resolves `pipelex-storage://` keys through the run's storage provider, decodes `data:` URLs, fetches `https://` through the SSRF guard, and refuses what the run's read scope does not allow, a local path included, with `UriReadRefusedError`. An engine reads nothing any other way.+- **`RenderResources.load(uri=…, position=…)`** is how an engine reads a file its document names, such as an image or a stylesheet. It resolves `pipelex-storage://` keys through the run's storage provider, decodes `data:` URLs, fetches `https://` through the SSRF guard, and refuses what the run's read scope does not allow, a local path included, with `UriReadRefusedError`. An engine reads nothing any other way. It returns a **`LoadedResource`**: the file's bytes as `data`, and as `mime_type` the media type the file's source gives it, described below.- **`RenderedDocument`** holds the bytes. Their MIME type and suffix are the format's.`render` is synchronous and runs on a thread of a print pool of its own, never on the event loop's default executor, which the engine's reads need, while `RenderResources.load` hands each read back to the event loop the print started from. An engine keeps no state from one print into the next. It signals a document it cannot print by raising `DocGenRenderError`, which passes through; anything else it raises, beyond a Pipelex error, is reported as a `DocGenRenderError` naming the engine and the file.+### The media type of a file an engine reads++`LoadedResource.mime_type` is the type the file's source gives it, lowercased and without its parameters, such as `text/css`. Pipelex never guesses it, so it is `None` when the source gives none:++| Source | `mime_type` |+| --- | --- |+| `https://` | The final response's `Content-Type`, after redirects; `None` when the response sends none. |+| `data:` | The type the URL declares. |+| `pipelex-storage://` on S3 or GCS | The content type recorded when the file was stored. |+| `pipelex-storage://` on the local or in-memory provider | The type identified from the bytes, which covers binary formats only: a stylesheet or an SVG has none. |+| A local path, read only by an unscoped run | `None`: a file system records no type. |++A declared type is returned as declared, even a generic one such as `application/octet-stream`, and is not checked against the bytes. An engine that needs a type keeps its own guess, from the URI's extension or from the bytes, for a file whose source gives none or gives one that says nothing. An HTML engine is the case in point, since a print library such as WeasyPrint keeps a linked stylesheet only when its type is `text/css`, and a stylesheet served from a URL with no extension, as a web font service serves one, can be typed only by what its server declared. The built-in PDF engine reads images only and never looks at the type, because Pillow identifies an image from its bytes.+---## The template checkerdiff --git a/docs/under-the-hood/inference-backend-plugins.md b/docs/under-the-hood/inference-backend-plugins.mdindex 454154a8f..c22934bbd 100644--- a/docs/under-the-hood/inference-backend-plugins.md+++ b/docs/under-the-hood/inference-backend-plugins.md@@ -269,6 +269,7 @@ What an out-of-tree backend plugin imports *is* the contract. The published surf| `DocumentContent` | `pipelex.core.stuffs.document_content` | a source document a search result cites || `JudgmentWorkerAbstract` | `pipelex.cogt.judgment.judgment_worker_abstract` | the judgment worker contract || `DocGenWorkerAbstract` | `pipelex.cogt.doc_gen.doc_gen_worker_abstract` | the document-generation worker contract |+| `RenderJob`, `RenderedDocument`, `RenderResources`, `LoadedResource` | `pipelex.cogt.doc_gen.render_job` | the job a document engine prints, the file it returns, and how it reads a file the document names, with that file's media type || `NbTokensByCategoryDict`, `TokenCategory` | `pipelex.cogt.usage.token_category` | the token usage a worker reports || `BaseModelTypeVar` | `pipelex.tools.typing.pydantic_utils` | the schema type variable of a structured-output signature || `CogtError`, `SdkTypeError`, `ImgGenGenerationError`, `ImgGenParameterError`, `InferenceErrorCategory` | `pipelex.cogt.exceptions` | the inference error bases and categories a worker raises with |diff --git a/docs/under-the-hood/writing-an-inference-plugin.md b/docs/under-the-hood/writing-an-inference-plugin.mdindex 74d7583a4..36ddffe40 100644--- a/docs/under-the-hood/writing-an-inference-plugin.md+++ b/docs/under-the-hood/writing-an-inference-plugin.md@@ -110,7 +110,7 @@ class HelloInferencePlugin:name = "hello_inference"# The plugin API version this plugin was written against, as a literal: never import the# runtime's PLUGIN_API_VERSION here, or the check that catches a breaking runtime upgrade always passes.- targets_api = 5+ targets_api = 6def register(self, registrar: PluginRegistrar) -> None:registrar.add_inference_backend(family=InferenceFamily.LLM, sdk="hello", make_worker=_make_hello_llm_worker)diff --git a/pipelex/cogt/content_generation/doc_gen_generate.py b/pipelex/cogt/content_generation/doc_gen_generate.pyindex 68cb665c4..b0e7a84d9 100644--- a/pipelex/cogt/content_generation/doc_gen_generate.py+++ b/pipelex/cogt/content_generation/doc_gen_generate.py@@ -29,11 +29,11 @@ from pipelex.cogt.content_generation.read_authorization import authorize_assignmfrom pipelex.cogt.doc_gen.doc_gen_engine import get_doc_gen_inference_model, require_doc_gen_engine_installedfrom pipelex.cogt.doc_gen.doc_gen_worker_factory import DocGenWorkerFactoryfrom pipelex.cogt.doc_gen.exceptions import DocGenRenderError-from pipelex.cogt.doc_gen.render_job import RenderedDocument, RenderResources+from pipelex.cogt.doc_gen.render_job import LoadedResource, RenderedDocument, RenderResourcesfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.runtime_hub import get_report_delegatefrom pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract-from pipelex.tools.uri.uri_bytes import load_bytes_from_any_uri+from pipelex.tools.uri.uri_bytes import load_bytes_and_mime_type_from_any_urifrom pipelex.tools.uri.uri_read_scope import authorize_uri_read# How long an engine may wait for one file it reads, such as an image fetched over https.@@ -56,12 +56,13 @@ class RunRenderResources(RenderResources):self._loop = loopself._loop_thread_id = threading.get_ident()- async def _load(self, *, uri: str, position: str) -> bytes:+ async def _load(self, *, uri: str, position: str) -> LoadedResource:authorize_uri_read(uri=uri, read_scope=self._read_scope, position=position)- return await load_bytes_from_any_uri(uri, storage_provider=self._storage_provider)+ loaded = await load_bytes_and_mime_type_from_any_uri(uri, storage_provider=self._storage_provider)+ return LoadedResource(data=loaded.data, mime_type=loaded.mime_type)@override- def load(self, *, uri: str, position: str) -> bytes:+ def load(self, *, uri: str, position: str) -> LoadedResource:if threading.get_ident() == self._loop_thread_id:msg = "An engine reads its resources from the worker thread it prints in, never from the event loop's own thread."raise RuntimeError(msg)diff --git a/pipelex/cogt/doc_gen/render_job.py b/pipelex/cogt/doc_gen/render_job.pyindex dd20d60d6..93cae10a9 100644--- a/pipelex/cogt/doc_gen/render_job.py+++ b/pipelex/cogt/doc_gen/render_job.py@@ -6,8 +6,9 @@ engine returns. An engine is the worker of a `doc_gen` model (`DocGenWorkerAbstrthe plugin registrar's `add_inference_backend`, and the Pipelex document generation plugin registers its ownfrom outside this repository, so this module and the worker are that plugin's contract with Pipelex:everything an engine needs arrives as plain data in the job, and the one thing it reads from outside the job,-a file the document names (an image), it reads through the `RenderResources` it is handed, which applies the-run's read scope. The job never carries a Pipelex object, so an ordinary Pipelex release does not break an+a file the document names (an image, a stylesheet), it reads through the `RenderResources` it is handed, which+applies the run's read scope and returns the file as a `LoadedResource`, its bytes with the media type its source+gives it. The job never carries a Pipelex object, so an ordinary Pipelex release does not break anengine; changing this module is a change of the plugin contract, versioned by `PLUGIN_API_VERSION`."""@@ -74,6 +75,29 @@ class RenderedDocument(BaseModel):data: bytes+class LoadedResource(BaseModel):+ """What `RenderResources.load` returns: a file's bytes, and the media type its source gives it.++ `mime_type` is lowercased and without its parameters, such as `text/css`, and it is the source's word, never a+ guess, so it is `None` when the source gives none:++ - **`https://`**: the final response's `Content-Type`, after redirects; `None` when the response sends none.+ - **`data:`**: the type the URL declares.+ - **`pipelex-storage://`**: the type the storage provider has for the key. A cloud provider (S3, GCS) returns the+ content type recorded when the file was stored; the local and in-memory providers identify binary formats from+ the bytes and have none for a text format, such as a stylesheet or an SVG.+ - **A local path**, which only an unscoped run reads: `None`, since a file system records no type.++ A declared type is returned as declared, even a generic one such as `application/octet-stream`, and is not checked+ against the bytes. An engine that needs a type, such as an HTML engine that keeps a stylesheet only when it is+ `text/css`, falls back to its own guess from the URI or the bytes when the type is `None` or says nothing. A model+ rather than a tuple, so the contract can grow an optional field without breaking an engine.+ """++ data: bytes+ mime_type: str | None = None++class RenderResources(Protocol):"""How an engine reads a file its document names, such as the image of an image block.@@ -83,8 +107,8 @@ class RenderResources(Protocol):may be called from the thread the engine prints in."""- def load(self, *, uri: str, position: str) -> bytes:- """Return the bytes a URI points at.+ def load(self, *, uri: str, position: str) -> LoadedResource:+ """Return the bytes a URI points at, with the media type its source gives them (`LoadedResource`).Args:uri: The URI the document names.diff --git a/pipelex/plugins/contract.py b/pipelex/plugins/contract.pyindex 9cba47e0b..b46686ca2 100644--- a/pipelex/plugins/contract.py+++ b/pipelex/plugins/contract.py@@ -38,7 +38,12 @@ if TYPE_CHECKING:# a ``LogSinkFactoryFn`` receives it as the ``secrets_provider`` keyword argument, so a sink's settings can# name a secret. A factory written against v4 would be called with a keyword it does not accept and fail at# boot with a bare ``TypeError``; the bump turns that into a discovery-time mismatch naming the plugin.-PLUGIN_API_VERSION: int = 5+#+# v6 changed the document engine contract: ``RenderResources.load`` returns a ``LoadedResource``, a file's bytes with+# the media type its source gives it, where it returned the bytes alone. An engine written against v5 would receive+# the model where it expects bytes and fail in the middle of a print, with a ``TypeError`` raised deep inside its+# rendering library; the bump turns that into a discovery-time mismatch naming the plugin.+PLUGIN_API_VERSION: int = 6@runtime_checkablediff --git a/pipelex/providers/reportlab/reportlab_pdf_renderer.py b/pipelex/providers/reportlab/reportlab_pdf_renderer.pyindex b81f44421..aa4c44cee 100644--- a/pipelex/providers/reportlab/reportlab_pdf_renderer.py+++ b/pipelex/providers/reportlab/reportlab_pdf_renderer.py@@ -199,8 +199,9 @@ class _RenderImages:loaded = self._images.get(number)if loaded is None or loaded.url != url:position = f"image {number} of the document"- data = self._resources.load(uri=url, position=position)- loaded = _decode_image(url=url, data=data, position=position)+ # The media type goes unread: Pillow identifies the image from its bytes, whatever its source declared.+ resource = self._resources.load(uri=url, position=position)+ loaded = _decode_image(url=url, data=resource.data, position=position)self._images[number] = loadedreturn loadeddiff --git a/pipelex/tools/misc/filetype_utils.py b/pipelex/tools/misc/filetype_utils.pyindex 85fe16c7c..6942b8cff 100644--- a/pipelex/tools/misc/filetype_utils.py+++ b/pipelex/tools/misc/filetype_utils.py@@ -221,7 +221,7 @@ _FORMAT_KEY_LIST_NAMES: Final[dict[str, str]] = {}-def _base_mime_type(*, mime_type: str) -> str:+def base_mime_type(*, mime_type: str) -> str:"""The MIME type without its parameters, lowercased: `Text/Plain; charset=utf-8` → `text/plain`."""return mime_type.split(";", 1)[0].strip().lower()@@ -236,7 +236,7 @@ def format_key_from_mime_type(*, mime_type: str | None) -> str | None:"""if mime_type is None:return None- base = _base_mime_type(mime_type=mime_type)+ base = base_mime_type(mime_type=mime_type)if not base or base in _GENERIC_MIME_TYPES:return Noneif base.startswith("image/"):@@ -328,9 +328,9 @@ def identify_mime_type(*, head: bytes | None, declared_mime_type: str | None, finamed_mime_type = _MIME_DB.guess_type(file_name, strict=True)[0] if file_name else Nonecandidate_mime_types = [mime_type for mime_type in (declared_mime_type, named_mime_type) if mime_type is not None]for candidate_mime_type in candidate_mime_types:- if _base_mime_type(mime_type=candidate_mime_type).startswith(_ZIP_BASED_DOCUMENT_MIME_PREFIXES):+ if base_mime_type(mime_type=candidate_mime_type).startswith(_ZIP_BASED_DOCUMENT_MIME_PREFIXES):return candidate_mime_typefor candidate_mime_type in candidate_mime_types:- if _base_mime_type(mime_type=candidate_mime_type) == _ZIP_MIME_TYPE:+ if base_mime_type(mime_type=candidate_mime_type) == _ZIP_MIME_TYPE:return candidate_mime_typereturn Nonediff --git a/pipelex/tools/uri/uri_bytes.py b/pipelex/tools/uri/uri_bytes.pyindex 9920ab56d..e72fa35ed 100644--- a/pipelex/tools/uri/uri_bytes.py+++ b/pipelex/tools/uri/uri_bytes.py@@ -1,16 +1,23 @@-"""Load the bytes behind any URI a value carries, fetching remote content as needed.+"""Load the bytes behind any URI a value carries, with the media type its source gives them, fetching remote content as needed.It sits beside `uri_base64` and apart from `uri_resolver` for the same reason: resolving a URI is a purefunction the kernel layer needs everywhere, while loading one reaches the network through the fetch helper,which is kept out of the kernel's import closure. Loading does not check the run's read scope: a caller thatreads a value's URL authorizes it first (`uri_read_scope`).++The media type is the one the source gives, never a guess: the response's `Content-Type` for `https://`, the+type a `data:` URL declares, and the type the storage provider has for a `pipelex-storage://` key. A local+path has none, since a file system records no type. A caller that needs a type when the source gives none+guesses it itself, from the URI or the bytes, because only it knows what it needs the type for."""import base64from pathlib import Path+from typing import NamedTuple-from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx+from pipelex.tools.misc.file_fetch_utils import fetch_file_and_content_type_from_url_httpxfrom pipelex.tools.misc.file_utils import load_binary_async+from pipelex.tools.misc.filetype_utils import base_mime_typefrom pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstractfrom pipelex.tools.uri.resolved_uri import (ResolvedBase64DataUrl,@@ -21,12 +28,24 @@ from pipelex.tools.uri.resolved_uri import (from pipelex.tools.uri.uri_resolver import resolve_uri-async def load_bytes_from_any_uri(+class UriBytes(NamedTuple):+ """The bytes a URI points at, and the media type its source gives them."""++ data: bytes+ mime_type: str | None = None+++async def load_bytes_and_mime_type_from_any_uri(uri: str,*,storage_provider: StorageProviderAbstract | None = None,-) -> bytes:- """Load the bytes a URI points at, whichever kind of URI it is.+) -> UriBytes:+ """Load the bytes a URI points at, whichever kind of URI it is, with the media type its source gives them.++ The type is lowercased and without its parameters (`text/css`, never `Text/CSS; charset=utf-8`), and it is+ `None` when the source gives none: an `https://` response without a `Content-Type`, a storage provider that+ has no type for the key, a `data:` URL declaring none, and every local path. A declared type is returned as+ declared, even a generic one such as `application/octet-stream`, and is not checked against the bytes.Args:uri: A URI string (http(s)://, a local path, a data: URL, or pipelex-storage://)@@ -39,17 +58,37 @@ async def load_bytes_from_any_uri(SsrfBlockedError: The destination, or a redirect hop's, is a private, loopback, link-local or metadata address."""raw_bytes: bytes+ declared_mime_type: str | Noneresolved_uri = resolve_uri(uri)match resolved_uri:case ResolvedBase64DataUrl():raw_bytes = base64.b64decode(resolved_uri.base64_data)+ declared_mime_type = resolved_uri.mime_typecase ResolvedHttpUrl():- raw_bytes = await fetch_file_from_url_httpx(url=resolved_uri.url)+ raw_bytes, declared_mime_type = await fetch_file_and_content_type_from_url_httpx(resolved_uri.url)case ResolvedLocalPath():raw_bytes = await load_binary_async(path=Path(resolved_uri.path))+ declared_mime_type = Nonecase ResolvedPipelexStorage():if storage_provider is None:msg = f"Cannot load a pipelex-storage:// URI without a storage provider: {uri}"raise ValueError(msg)- raw_bytes = await storage_provider.load(uri=resolved_uri.storage_uri)- return raw_bytes+ raw_bytes, declared_mime_type = await storage_provider.load_with_metadata(uri=resolved_uri.storage_uri)+ mime_type = base_mime_type(mime_type=declared_mime_type) if declared_mime_type else None+ return UriBytes(data=raw_bytes, mime_type=mime_type or None)+++async def load_bytes_from_any_uri(+ uri: str,+ *,+ storage_provider: StorageProviderAbstract | None = None,+) -> bytes:+ """Load the bytes a URI points at, whichever kind of URI it is, for a caller that has no use for their media type.++ Raises:+ ValueError: If the URI is a pipelex-storage:// URI and no storage provider is given.+ RemoteFileFetchError: The server answered with an error status, refused the connection, or did not answer in time.+ SsrfBlockedError: The destination, or a redirect hop's, is a private, loopback, link-local or metadata address.+ """+ loaded = await load_bytes_and_mime_type_from_any_uri(uri, storage_provider=storage_provider)+ return loaded.datadiff --git a/subject_grants.toml b/subject_grants.tomlindex 497316312..da6ed3a72 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -6880,6 +6880,10 @@ rationale = "Factory from source: builds the result from the uri; single operandparam = "url"rationale = "Factory from source: builds the result from the url; single operand."+["pipelex/tools/uri/uri_bytes.py::load_bytes_and_mime_type_from_any_uri"]+param = "uri"+rationale = "Loads the bytes and media type one URI names."+["pipelex/tools/uri/uri_bytes.py::load_bytes_from_any_uri"]param = "uri"rationale = "Loads the bytes one URI names."diff --git a/tests/unit/pipelex/cogt/content_generation/test_doc_gen_render_resources.py b/tests/unit/pipelex/cogt/content_generation/test_doc_gen_render_resources.pyindex f3b67eb3b..44137b8c6 100644--- a/tests/unit/pipelex/cogt/content_generation/test_doc_gen_render_resources.py+++ b/tests/unit/pipelex/cogt/content_generation/test_doc_gen_render_resources.py@@ -6,25 +6,65 @@ from pytest_mock import MockerFixturefrom pipelex.cogt.content_generation import doc_gen_generatefrom pipelex.cogt.content_generation.doc_gen_generate import RunRenderResourcesfrom pipelex.cogt.doc_gen.exceptions import DocGenRenderError-from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract+from pipelex.cogt.doc_gen.render_job import LoadedResource+from pipelex.tools.storage.storage_provider_abstract import PIPELEX_STORAGE_SCHEME, StorageProviderAbstract, StoredData+from pipelex.tools.uri.exceptions import UriReadRefusedError+from pipelex.tools.uri.uri_bytes import UriBytes@pytest.mark.asyncio(loop_scope="class")class TestRunRenderResources:+ async def test_a_read_returns_the_bytes_with_the_type_the_source_gives(self, mocker: MockerFixture) -> None:+ """An engine reading from its worker thread gets the file's bytes and the media type its source gave them."""+ storage_uri = f"{PIPELEX_STORAGE_SCHEME}scope/assets/theme"+ storage_provider = mocker.MagicMock(spec=StorageProviderAbstract)+ storage_provider.load_with_metadata = mocker.AsyncMock(return_value=StoredData(data=b"body {}", mime_type="text/css; charset=utf-8"))+ resources = RunRenderResources(storage_provider=storage_provider, read_scope=None, loop=asyncio.get_running_loop())++ loaded = await asyncio.to_thread(resources.load, uri=storage_uri, position="stylesheet 1 of the document")++ assert loaded == LoadedResource(data=b"body {}", mime_type="text/css")++ async def test_a_read_whose_source_gives_no_type_returns_none(self, mocker: MockerFixture) -> None:+ mocker.patch.object(+ doc_gen_generate,+ "load_bytes_and_mime_type_from_any_uri",+ new_callable=mocker.AsyncMock,+ return_value=UriBytes(data=b"\x89PNG", mime_type=None),+ )+ resources = RunRenderResources(+ storage_provider=mocker.MagicMock(spec=StorageProviderAbstract), read_scope=None, loop=asyncio.get_running_loop()+ )++ loaded = await asyncio.to_thread(resources.load, uri="https://example.com/photo", position="image 1 of the document")++ assert loaded == LoadedResource(data=b"\x89PNG", mime_type=None)++ async def test_a_read_outside_the_scope_is_refused_before_loading(self, mocker: MockerFixture) -> None:+ loader = mocker.patch.object(doc_gen_generate, "load_bytes_and_mime_type_from_any_uri", new_callable=mocker.AsyncMock)+ resources = RunRenderResources(+ storage_provider=mocker.MagicMock(spec=StorageProviderAbstract), read_scope="scope-a", loop=asyncio.get_running_loop()+ )++ with pytest.raises(UriReadRefusedError):+ await asyncio.to_thread(resources.load, uri=f"{PIPELEX_STORAGE_SCHEME}scope-b/assets/theme.css", position="stylesheet 1 of the document")++ loader.assert_not_awaited()+async def test_a_read_that_times_out_is_a_render_error_and_is_cancelled(self, mocker: MockerFixture) -> None:"""A slow read fails the print with a `DocGenRenderError` naming its position, and stops running on the loop."""was_cancelled = asyncio.Event()- async def _never_answers(uri: str, *, storage_provider: StorageProviderAbstract) -> bytes: # ruff: ignore[unused-function-argument]+ async def _never_answers(uri: str, *, storage_provider: StorageProviderAbstract) -> UriBytes: # ruff: ignore[unused-function-argument]try:await asyncio.Event().wait()except asyncio.CancelledError:was_cancelled.set()raise- return b""+ return UriBytes(data=b"")mocker.patch.object(doc_gen_generate, "_RESOURCE_LOAD_TIMEOUT_SECONDS", 0.05)- mocker.patch.object(doc_gen_generate, "load_bytes_from_any_uri", _never_answers)+ mocker.patch.object(doc_gen_generate, "load_bytes_and_mime_type_from_any_uri", _never_answers)resources = RunRenderResources(storage_provider=mocker.MagicMock(spec=StorageProviderAbstract), read_scope=None, loop=asyncio.get_running_loop())diff --git a/tests/unit/pipelex/plugins/test_plugin_api_version_in_docs.py b/tests/unit/pipelex/plugins/test_plugin_api_version_in_docs.pynew file mode 100644index 000000000..07005ac60--- /dev/null+++ b/tests/unit/pipelex/plugins/test_plugin_api_version_in_docs.py@@ -0,0 +1,20 @@+"""The plugin tutorial writes `targets_api` as a literal, as an out-of-tree plugin must, so the literal follows the runtime's version.++A tutorial whose example declares an older version teaches a plugin that discovery refuses on its first boot.+"""++import re+from pathlib import Path++from pipelex.plugins.contract import PLUGIN_API_VERSION++_TESTS_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests")+_TUTORIAL_PATH = _TESTS_ROOT.parent / "docs" / "under-the-hood" / "writing-an-inference-plugin.md"+_LITERAL_TARGETS_API = re.compile(r"^\s*targets_api = (\d+)\s*$", re.MULTILINE)+++class TestPluginApiVersionInDocs:+ def test_the_tutorial_plugin_targets_the_current_plugin_api_version(self) -> None:+ declared_versions = [int(version) for version in _LITERAL_TARGETS_API.findall(_TUTORIAL_PATH.read_text(encoding="utf-8"))]+ assert declared_versions, f"{_TUTORIAL_PATH.name} no longer declares `targets_api` as a literal: update this test"+ assert declared_versions == [PLUGIN_API_VERSION] * len(declared_versions)diff --git a/tests/unit/pipelex/providers/reportlab/reportlab_test_helpers.py b/tests/unit/pipelex/providers/reportlab/reportlab_test_helpers.pyindex 2e910ec9e..70eb96343 100644--- a/tests/unit/pipelex/providers/reportlab/reportlab_test_helpers.py+++ b/tests/unit/pipelex/providers/reportlab/reportlab_test_helpers.py@@ -11,7 +11,7 @@ from typing_extensions import overridefrom pipelex.cogt.doc_gen.doc_gen_format import DocGenFormat, DocGenSourcefrom pipelex.cogt.doc_gen.layout_tree import LayoutBlock, LayoutDocument, MarkdownBlock-from pipelex.cogt.doc_gen.render_job import RenderJob, RenderResources+from pipelex.cogt.doc_gen.render_job import LoadedResource, RenderJob, RenderResourcesfrom pipelex.cogt.llm.thinking_mode import ThinkingModefrom pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.cogt.model_backends.model_type import ModelType@@ -27,21 +27,26 @@ class ResourceRead(NamedTuple):class StubRenderResources(RenderResources):- """Decodes `data:` URLs, or answers every read with `answer` when set, and records each read."""+ """Decodes `data:` URLs with the type each declares, or answers every read with `answer`, and records each read.- def __init__(self, *, answer: bytes | None = None):+ `answer_mime_type` is the type an answer comes with.+ """++ def __init__(self, *, answer: bytes | None = None, answer_mime_type: str | None = None):self.reads: list[ResourceRead] = []self._answer = answer+ self._answer_mime_type = answer_mime_type@override- def load(self, *, uri: str, position: str) -> bytes:+ def load(self, *, uri: str, position: str) -> LoadedResource:self.reads.append(ResourceRead(uri=uri, position=position))if self._answer is not None:- return self._answer+ return LoadedResource(data=self._answer, mime_type=self._answer_mime_type)header, _, payload = uri.partition(",")assert header.startswith("data:"), f"the stub reads data URLs only, not {uri[:40]}"assert header.endswith(";base64"), f"the stub reads base64 data URLs only, not {uri[:40]}"- return base64.b64decode(payload)+ declared_type = header.removeprefix("data:").removesuffix(";base64")+ return LoadedResource(data=base64.b64decode(payload), mime_type=declared_type or None)def reportlab_pdf_model() -> InferenceModelSpec:diff --git a/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.py b/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.pyindex 079b67b4b..ffa48fc9c 100644--- a/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.py+++ b/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.py@@ -38,6 +38,7 @@ from tests.unit.pipelex.providers.reportlab.reportlab_test_helpers import (image_count,page_texts,pdf_title,+ png_bytes,png_data_url,render_layout,)@@ -121,6 +122,12 @@ class TestReportlabPdfRenderer:assert len(page_texts(pdf_data=pdf_data)) == 1assert image_count(pdf_data=pdf_data) == 1+ def test_an_image_prints_whatever_type_its_source_declares(self) -> None:+ """Pillow identifies an image from its bytes, so a misleading declared type does not stop it printing."""+ resources = StubRenderResources(answer=png_bytes(width=64, height=32), answer_mime_type="text/plain")+ pdf_data = render_layout(blocks=[ImageBlock(url="pipelex-storage://run/chart", caption=None)], resources=resources)+ assert image_count(pdf_data=pdf_data) == 1+def test_a_file_that_is_not_an_image_is_refused_with_its_position(self) -> None:resources = StubRenderResources(answer=b"<svg xmlns='http://www.w3.org/2000/svg'/>")with pytest.raises(DocGenRenderError, match="image 1 of the document") as exc_info:diff --git a/tests/unit/pipelex/tools/uri/test_uri_bytes.py b/tests/unit/pipelex/tools/uri/test_uri_bytes.pynew file mode 100644index 000000000..7916335f6--- /dev/null+++ b/tests/unit/pipelex/tools/uri/test_uri_bytes.py@@ -0,0 +1,109 @@+import base64+from pathlib import Path++import httpx+import pytest+from pytest_mock import MockerFixture++from pipelex.tools.misc.file_fetch_utils import fetch_file_and_content_type_from_url_httpx+from pipelex.tools.storage.storage_provider_abstract import PIPELEX_STORAGE_SCHEME, StorageProviderAbstract, StoredData+from pipelex.tools.uri import uri_bytes+from pipelex.tools.uri.uri_bytes import UriBytes, load_bytes_and_mime_type_from_any_uri, load_bytes_from_any_uri++CSS_BYTES = b"body { color: navy; }"+STYLESHEET_URL = "https://fonts.example.com/css2?family=Inter"+++def _data_url(*, declared_type: str, body: bytes) -> str:+ return f"data:{declared_type};base64,{base64.b64encode(body).decode('ascii')}"+++def _serve_from(*, mocker: MockerFixture, response: httpx.Response) -> None:+ """Route the loader's fetch through a transport answering `response`, so the real header handling runs."""+ transport = httpx.MockTransport(lambda _request: response)++ async def _fetch_through_transport(url: str, **_kwargs: object) -> tuple[bytes, str | None]:+ return await fetch_file_and_content_type_from_url_httpx(url, transport=transport)++ mocker.patch.object(uri_bytes, "fetch_file_and_content_type_from_url_httpx", _fetch_through_transport)++[email protected](loop_scope="class")+class TestLoadBytesAndMimeTypeFromAnyUri:+ """The loader returns a file's bytes with the media type its source gives it, and never guesses one."""++ async def test_an_https_url_returns_the_type_the_response_declares(self, mocker: MockerFixture) -> None:+ """A URL with no extension still says what it serves: the response's `Content-Type`, bare and lowercased."""+ _serve_from(mocker=mocker, response=httpx.Response(200, content=CSS_BYTES, headers={"Content-Type": "Text/CSS; charset=utf-8"}))++ loaded = await load_bytes_and_mime_type_from_any_uri(STYLESHEET_URL)++ assert loaded == UriBytes(data=CSS_BYTES, mime_type="text/css")++ async def test_an_https_url_whose_response_declares_no_type_returns_none(self, mocker: MockerFixture) -> None:+ _serve_from(mocker=mocker, response=httpx.Response(200, content=CSS_BYTES))++ loaded = await load_bytes_and_mime_type_from_any_uri(STYLESHEET_URL)++ assert loaded == UriBytes(data=CSS_BYTES, mime_type=None)++ async def test_a_declared_octet_stream_is_returned_as_declared(self, mocker: MockerFixture) -> None:+ """A generic type says nothing, but deciding so is the engine's call: the loader reports it unchanged."""+ _serve_from(mocker=mocker, response=httpx.Response(200, content=CSS_BYTES, headers={"Content-Type": "application/octet-stream"}))++ loaded = await load_bytes_and_mime_type_from_any_uri(STYLESHEET_URL)++ assert loaded.mime_type == "application/octet-stream"++ @pytest.mark.parametrize(+ ("declared_type", "expected_mime_type"),+ [+ ("text/css", "text/css"),+ ("text/css;charset=utf-8", "text/css"),+ ("Image/SVG+XML", "image/svg+xml"),+ ("", None),+ ],+ )+ async def test_a_data_url_returns_the_type_it_declares(self, declared_type: str, expected_mime_type: str | None) -> None:+ loaded = await load_bytes_and_mime_type_from_any_uri(_data_url(declared_type=declared_type, body=CSS_BYTES))++ assert loaded == UriBytes(data=CSS_BYTES, mime_type=expected_mime_type)++ @pytest.mark.parametrize(+ ("recorded_type", "expected_mime_type"),+ [+ ("text/css", "text/css"),+ ("text/css; charset=UTF-8", "text/css"),+ (None, None),+ ],+ )+ async def test_a_storage_key_returns_the_type_the_provider_recorded(+ self, mocker: MockerFixture, recorded_type: str | None, expected_mime_type: str | None+ ) -> None:+ storage_uri = f"{PIPELEX_STORAGE_SCHEME}scope/assets/theme"+ load_with_metadata = mocker.AsyncMock(return_value=StoredData(data=CSS_BYTES, mime_type=recorded_type))+ storage_provider = mocker.MagicMock(spec=StorageProviderAbstract)+ storage_provider.load_with_metadata = load_with_metadata++ loaded = await load_bytes_and_mime_type_from_any_uri(storage_uri, storage_provider=storage_provider)++ assert loaded == UriBytes(data=CSS_BYTES, mime_type=expected_mime_type)+ load_with_metadata.assert_awaited_once_with(uri=storage_uri)++ async def test_a_storage_key_without_a_provider_is_refused(self) -> None:+ with pytest.raises(ValueError, match="without a storage provider"):+ await load_bytes_and_mime_type_from_any_uri(f"{PIPELEX_STORAGE_SCHEME}scope/assets/theme.css")++ async def test_a_local_path_returns_no_type(self, tmp_path: Path) -> None:+ """A file system records no type, and the loader does not read one off the file's name."""+ stylesheet_path = tmp_path / "theme.css"+ stylesheet_path.write_bytes(CSS_BYTES)++ loaded = await load_bytes_and_mime_type_from_any_uri(str(stylesheet_path))++ assert loaded == UriBytes(data=CSS_BYTES, mime_type=None)++ async def test_the_bytes_only_loader_returns_the_same_bytes(self, mocker: MockerFixture) -> None:+ _serve_from(mocker=mocker, response=httpx.Response(200, content=CSS_BYTES, headers={"Content-Type": "text/css"}))++ assert await load_bytes_from_any_uri(STYLESHEET_URL) == CSS_BYTES