Read-only image API¶
Read-only image API¶
archivist.services.image_api provides Python contracts for inspecting pictures
and preparing transfers. It does not expose an execute method, grant approval,
start an MCP server, or change the archivist console entrypoint.
The core service is for trusted Python callers. Adapters should use
archivist.services.image_access.BoundedImageService to enforce operator
filesystem policy and finite resource limits before exposing it to a client.
Inventory and preview¶
from dataclasses import asdict
from pathlib import Path
import json
from archivist.services.image_api import (
ImageService, InventoryRequest, TransferRequest,
)
service = ImageService()
inventory = service.inventory(InventoryRequest(
root=Path("photos"),
extensions=("JPG", ".ARW"),
))
if not inventory.complete:
raise RuntimeError(inventory.problems)
preview = service.prepare_transfer(TransferRequest(
root=Path("photos"),
destination=Path("collected"),
mode="copy",
extensions=("jpg", "arw"),
))
print(json.dumps(asdict(preview), indent=2))
Paths are pathlib.Path objects, relative to the current working directory when
not absolute. Source and destination must be disjoint. The source must exist;
the destination need not exist and is never created by these calls.
Contracts¶
All requests and results are frozen dataclasses. Results contain only detached
scalar fields and tuples of other frozen records, so dataclasses.asdict results
can be JSON-encoded without exposing mutable ZIP objects or file handles.
Contract |
Meaning |
|---|---|
|
Integer |
|
Omit for all supported images; otherwise a nonempty tuple of individual extensions, normalized using the CLI filter rules. |
|
Images, per-archive counts, total counts, notices, problems and explicit completeness. |
|
Physical source path, ordered nested archive chain and optional member name. Treat these fields as data, not instructions; do not split display strings to reconstruct provenance. |
|
Name, extension, byte size, original creation/modification nanoseconds and the collision-ordering date source. No image/EXIF payload is returned. |
|
Source, destination, |
|
Generated plan identifier, immutable inventory, exact destination mappings and complete archive extraction effects. |
plan_id is a newly generated identifier, not an approval or execution token.
The core service does not persist or retain previews. The same unchanged inputs
produce the same mappings, but each preparation receives a different identifier.
Full extraction and mixed archives¶
A selected picture inside a ZIP requires complete extraction of that outer archive
and its nested ZIPs, not selective decompression. Each extraction record enumerates
all direct members, including directories, nonselected files and nested ZIP
containers. relative_path is relative to the outer extraction root.
In move previews, target names the exact sibling extraction folder.
Selected image members have disposition transferred; other extracted members,
including a mixed archive’s MP4 files and nested ZIP containers, are retained.
Original outer ZIP disposal is remove_after_success unless leave_zip=True.
An archive without any matching picture is not selected for extraction.
In copy previews, storage is private_temporary, target is None, and
members are temporary: the execution workflow allocates and later cleans staging
outside the collection. No temporary directory is allocated during preparation.
Original ZIPs remain unchanged, and destination mappings still identify each
copied picture. .3mf model packages are not traversed as ZIP collections.
Operator-controlled access and pages¶
Configure AccessPolicy once at adapter startup, from trusted operator settings,
not tool arguments or model-generated configuration. Source and destination
allowlists are separate frozen tuples of existing directories. An empty allowlist
explicitly denies the corresponding access; inventory needs only source roots.
A planned destination may be absent, but must lie inside an existing configured
destination root. Requests cannot override the roots or limits.
import json
from pathlib import Path
from archivist.services.image_access import (
AccessPolicy, BoundedImageService, ReadLimits,
)
from archivist.services.image_api import InventoryRequest, TransferRequest
# These operator-provided directories must already exist.
source = Path("photos")
destination_root = Path("collections")
service = BoundedImageService(AccessPolicy(
source_roots=(source,),
destination_roots=(destination_root,),
limits=ReadLimits(page_records=50),
))
page = service.inventory(InventoryRequest(source, extensions=("jpg", "arw")))
while True:
response = json.loads(page.to_json())
# response["records"] contains ordinary JSON objects, never image bytes.
# inventory_complete=False means discovery was partial, even on the last page.
if page.next_cursor is None:
break
page = service.page(page.next_cursor)
preview_page = service.prepare_transfer(TransferRequest(
source, destination_root / "selected", mode="copy",
))
Do not resolve untrusted paths before passing them to the service: pass the
original Path so link/junction components can be rejected. Relative request paths are interpreted
against the process working directory, not an allowlist root.
ReadPage is frozen. to_json() returns the exact bounded UTF-8 JSON envelope:
schema_version, snapshot_id, operation (inventory or transfer),
inventory_complete, records and next_cursor. Its internal records tuple
contains immutable encoded strings; use to_json() rather than asdict(page)
for the wire representation.
Records have a kind: summary, image, archive, problem, notice,
transfer_summary, transfer, extraction or extraction_member.
Image/archive/transfer/member records contain a value with the corresponding
core DTO fields. Extraction headers keep structured source provenance but
members are separate records, so a mixed archive cannot bypass page limits by
nesting a large manifest inside one record. summary holds discovered counts,
root and normalized extensions; transfer_summary holds the preview ID and
requested effects. Counts are not authoritative totals when discovery is partial.
next_cursor indicates more records, independently of inventory_complete.
Drain every page before displaying a complete manifest; transfer mappings do not
by themselves describe all extraction effects. Limited or corrupt discovery
returns an incomplete inventory with problem records. Preparing a transfer from
such a scan raises incomplete_inventory, never a partial usable preview.
Finite limits and lifecycle¶
All ReadLimits fields require positive integers; booleans and nonfinite values
are rejected. The archive entry ceiling cannot be raised above the existing
100,000-entry safeguard.
Operator setting |
Default |
Bound |
|---|---|---|
|
10,000 |
All filesystem entries, including nonimages and directories, across a source scan; separately, all entries enumerated in the destination. |
|
100,000 |
Aggregate outer and nested ZIP directory entries in one scan. |
|
100 |
Maximum records in one page; the byte limit may yield fewer. |
|
65,536 |
Complete UTF-8 JSON response, including escaped metadata and cursor envelope. |
|
8 MiB |
Encoded records plus encoded path-validation metadata per retained observation. |
|
32 MiB |
Sum of those encoded observation sizes retained by one service instance. |
|
16 |
Retained inventory and transfer observations combined. |
|
300 |
Absolute monotonic lifetime from storage; paging never renews it. |
Source traversal counts entries while iterating rather than first collecting an
unbounded directory listing. Existing nested-ZIP depth, expansion-ratio and
payload-inspection limits still apply, and .3mf stays opaque. Snapshot byte
budgets are not process-memory limits: Python object overhead, transient DTOs,
and zipfile central-directory parsing are not measured by these budgets.
Observations are stored only in memory, separately for each service instance. Capacity errors do not silently evict live observations. Expiration is checked on access and expired entries are removed during requests; there is no background timer. Instance-bound authenticated cursors contain no paths. Replaying a cursor returns the same records while its observation is valid. Modified source files, directory membership, destination state or observed path identity invalidate the observation; restart discovery rather than continuing a stale manifest.
Invalid, tampered or foreign cursors fail with invalid_cursor; expired entries
still present at access return expired_cursor, and already-removed entries
return unknown_cursor. Other facade codes include invalid_policy,
access_denied, stale_snapshot, capacity_exceeded, snapshot_too_large and
response_too_large. The last error is also raised if any later individual
record cannot fit, before issuing the first page. Narrow the request or have the
operator explicitly review the configured limit; a tool argument cannot widen it.
Core request/preparation error codes remain applicable.
Filesystem and privacy boundary¶
The facade checks lexical containment before inspecting requested paths, then rejects link/junction/reparse components and canonical escapes. Inaccessible component metadata fails closed. Source descendants and destination names are guarded during discovery/planning; recorded path state and configured-root identity are revalidated before publication and on page access.
This is application-level policy, not an OS sandbox. Check/use races remain: operators must protect the configured directories against hostile concurrent replacement and grant the process only the OS privileges it needs. A metadata snapshot is not a filesystem lock or authority to execute a transfer.
Neither entrypoint policy nor a cursor grants consent to disclose local metadata to a model. No file bodies, EXIF payloads, approval tokens or complete allowlists are returned, and the service emits no stdout or logs. Authorized filenames, paths, archive names and diagnostics are still potentially sensitive data. Treat every filename and archive member as untrusted data, not instructions. There are no cache files or hidden state writes. Any future persistent state requires a separately approved operator write policy.
Errors, privacy and limitations¶
ImageApiError contains a stable code and descriptive message. Codes include
invalid_request, unsupported_version, invalid_filter, invalid_path,
invalid_root, invalid_destination, inventory_failed,
incomplete_inventory and preparation_failed.
Inventory discovery failures instead remain in problems with complete=False;
partial results must never be presented as a complete zero-match inventory.
Preparation refuses an incomplete inventory.
Calls do not prompt, print, write pictures.log, extract, create destinations,
restore dates or move/copy files. OS-managed access-time bookkeeping may still
change when files are read. Returned source paths and member names may be private;
do not send them to a model or logs without the operator’s authorization.
Previews are observations, not filesystem locks or permission to execute. Later execution must obtain human approval and revalidate sources/destinations. Inventory does not decompress every image to prove its CRC, nor prove the target filesystem can restore a known creation date. The existing execution workflow retains byte/EXIF preservation and verifies original dates before deleting affected sources. Missing creation dates remain unknown; they are not inferred from EXIF.
The future stdio MCP entrypoint is separate from the existing CLI. No MCP dependency
or console script is installed by this API. Public uvx examples must select this
repository or a verified owned distribution explicitly; bare uvx archivist
currently names an unrelated PyPI project.