Skip to main content

maf-sandbox-document

PyPI Python License

Experimental. Releases before 1.0 may change or remove APIs. Importing this package emits MafSandboxDocumentExperimentalWarning.

Read PDF, DOCX, PPTX and RTF files or export Markdown reports to PDF through fixed converters in disposable sandboxes. The model chooses a listed file, output format and optional page range; it supplies no converter code. Parsers and archive/XML guards run in the guest.

Install the published package from PyPI:

pip install maf-sandbox-document

The package requires maf-sandbox>=0.53.0,<0.54 and agent-framework-core>=1.24.0,<1.25. The host supplies a verified image from a completed, currently eligible document release for reading, or a document-export release for export.

Markdown to PDF export

export_pdf is a host API that returns PDF bytes without reading or writing a store. Supply a router, host-owned identity and an explicit image built from the separate document-export profile; the reader image cannot export. Every export receives a fresh call identity and disposes its sandbox before returning bytes.

from maf_sandbox import SandboxKey
from maf_sandbox_document import ExportOptions, export_pdf

pdf = await export_pdf(
    "# Results\n\n```mermaid\nflowchart LR\n A --> B\n```",
    assets={},
    options=ExportOptions(title="Report", date="2026-11-07", page_size="A4"),
    router=router,
    key=SandboxKey(scope="host-scope", thread_id="host-thread", agent_id="reporter"),
    image="your-registry/document-export@sha256:<verified-digest>",
)

The fixed print layout includes wrapping code, GFM tables, Mermaid diagrams, passive SVG assets and page-number footers. page_size accepts A4 or Letter; title and date are literal text, each limited to 1024 UTF-8 bytes. Raw HTML is escaped. Assets are a mapping of relative names such as chart.svg or figures/chart.svg to UTF-8 SVG bytes. Names allow ASCII letters, digits, underscores and hyphens in each component (maximum 256 characters); supplied names containing traversal and non-SVG content are refused. Unsupplied image references are refused by default. The passive SVG subset supports shapes, text, gradients and local fragment references; CSS, scripts, event attributes, external references and embedded HTML are refused. Only SVG and XLink namespace declarations are supported. Each SVG is limited to 128 nested element levels and 100,000 elements, including its root, and is validated incrementally without building a tree. Invalid Mermaid renders as source with a visible note. Mermaid configuration directives are disabled.

By default, an image token that does not name a supplied SVG refuses the export. Set ExportOptions(unsupplied_images="placeholder") to render it as literal [Image: alt text] instead. This covers remote references, missing files and other image types without fetching them. Replacement uses the renderer's Markdown tokens, including reference-style images and images in tables; code examples stay code. Alt text retains code-span text and decoded entities, with formatting removed and HTML escaped. Each rendered occurrence counts separately; nested image descriptions contribute alt text, not additional replacements. Schemes the Markdown parser rejects, such as file:, stay literal Markdown and are not counted. Supplied assets still undergo every SVG and size check; placeholder mode does not accept invalid supplied assets.

Use export_pdf_result with the same arguments when the host needs a count. It returns an immutable ExportResult with pdf: bytes and images_replaced: int; export_pdf continues to return bytes. Both return only after successful disposal. The count is guest-derived metadata, not an independent host measurement. Placeholder mode requires a document-export image built with this option and replacement-count support; missing or invalid count metadata refuses delivery. The default refusal mode remains compatible with older images that omit the count, reporting zero replacements.

Hosts can preflight individual assets with is_valid_asset_name(name: str) -> bool and validate_svg(data: bytes) -> None, both exported from maf_sandbox_document. These are the exact name and passive-SVG checks used by export_pdf and its guest: validate_svg returns None for accepted bytes and raises ValueError with the same messages for rejected SVG. Neither helper checks the aggregate ExportOptions byte/count limits or guarantees that the complete export will succeed. A host can omit rejected assets and select ExportOptions(unsupplied_images="placeholder") to render their image references as placeholders. In the default refusal mode, the host must replace those references before exporting.

from maf_sandbox_document import is_valid_asset_name, validate_svg

def accepted_assets(candidates: dict[str, bytes]) -> dict[str, bytes]:
    assets: dict[str, bytes] = {}
    for name, data in candidates.items():
        if not is_valid_asset_name(name):
            continue
        try:
            validate_svg(data)
        except ValueError:
            continue
        assets[name] = data
    return assets
Export option Default Kind maximum
max_markdown_bytes (UTF-8) 1,000,000 2,000,000
max_asset_bytes (total) 5,000,000 10,000,000
max_assets 50 100
max_pages 100 500
max_pdf_bytes 16,000,000 32,000,000
deadline_seconds 60 300

Bounds are refusals, never truncation. Invalid inputs, guest guard refusals and invalid output metadata raise ValueError; operational or cleanup failures raise RuntimeError (backend exceptions may also propagate). The host deadline raises TimeoutError and covers acquisition, staging, rendering and output reads; disposal has a separate 30-second bound. Cancellation also attempts disposal. Returned bytes remain untrusted document content; a host controls any subsequent storage or streaming. There is no model-facing export tool or sink implicit in this API.

See the export image instructions for build, layout limits and live qualification. Image publication, signed consumer qualification and production acceptance are separate from source implementation.

Attach the reader tool

from maf_sandbox_document import make_document_tools

[document_read] = make_document_tools(
    router,
    file_store,
    "document-reader",
    context,
    sink,
    image=verified_document_image,
    formats=("text", "markdown"),  # Enable images only for a host that can consume them.
)

The host supplies a store with async read(name) -> bytes | None, and context.list_files(store) returns authorized ListedFile entries. Text-only AgentFileStore implementations need a binary adapter. Names are matched exactly, never interpreted as host paths, guest paths or URLs. The host must bound ingress bytes before the store returns them; the kind independently checks its 16 MiB input limit.

Use file_store_provenance for stores that may change during a call and requires_file_integrity when admission requires an established source label. Completion and the extracted/refused verdict are trusted. Document text, metadata, images, delivery references and converter diagnostics are guest-derived output. Core derives their effective label from the file read, model arguments and conversation.

The router must allow at least container isolation and supply POSIX EXEC, FILES_IN and FILES_OUT with closed egress. Every call requires its own sandbox and disposal, including refusal, failure and cancellation.

Tool contract

document_read(file, format="text", pages=None) accepts text, markdown or images. pages is a positive, 1-based inclusive range such as "2-5" or "3". PDF ranges select pages; PPTX ranges select slides. Both endpoints clamp to the available last page. DOCX has no reliable pagination without a layout engine, so an explicit range is refused. RTF ignores ranges.

Input Text / Markdown Images Limits
PDF PDFium text in reading order; Markdown retains that text PNG pages at the host's fixed DPI Supported PDF subset below; no OCR
DOCX Mammoth text or Markdown conversion Refused No pagination or faithful layout
PPTX Slide text, table cells and notes; Markdown slide headings Refused No office renderer
RTF (application/rtf, text/rtf) striprtf text, also usable as plain Markdown Refused Page range ignored

Outputs are document.txt (text/plain), document.md (text/markdown) or page-N.png (image/png), plus document.json (application/json). Image names preserve original page numbers. An extracted verdict requires delivery of every requested output. Guard refusals deliver only the metadata and diagnostic. Invalid arguments, missing files, acquisition failures, timeouts, operational exits and incomplete delivery return completed=False with no verdict.

Metadata schema version 1 contains media_type, format, supported_formats, pages (a page/slide count, or null), selected_pages, characters, truncated (always false), range_clamped, verdict, reason and files. A refusal never represents capped content as a successful extraction.

Host options and guards

Option Default Allowed
exec_timeout_seconds 60 Finite number greater than 0, at most 300
max_pages 200 1–10,000
max_chars 1,000,000 1–8,000,000
image_dpi 96 1–600
max_image_pixels 16,000,000 1–32,000,000 per page
max_image_pages 20 1–100 per call
formats text, markdown, images Nonempty tuple of distinct enabled formats

OOXML is checked before Mammoth or python-pptx opens it: at most 2,048 ZIP entries, 16 MiB per expanded member, 64 MiB total, and a declared expansion ratio at most 200. Absolute/traversing/duplicate names, symlinks, encryption, unsupported compression and nested archives are refused. Bounded decompression verifies stream completion, actual lengths and CRCs independently of declared member sizes; converters receive a rebuilt, stored-only ZIP. XML preflight refuses DTDs and entity declarations, including UTF-16 declarations and XML in nonstandard member names. python-pptx uses a parser with entity resolution, DTD loading and network access disabled. Mammoth's pinned minidom path receives only the preflighted XML; external file access and embedded style maps are disabled.

PDF preflight admits a single classic cross-reference table, bounded objects and streams with no compression, Flate, ASCII85 or ASCIIHex. Each decoded stream is at most 32 MiB, with 64 MiB total. Drawing syntax is checked in page content, forms, annotation appearances, tiling patterns and Type 3 glyph programs, with at most 64 MiB of content including repeated uses; binary image and font bytes are not interpreted as drawing commands. Object/cross-reference streams, incremental or encrypted PDFs, external streams, inline images, other filters (including JPEG/JPEG2000) and decoding parameters are refused. ASCII85 streams containing NUL or form-feed whitespace are also refused because the pinned PDFium decoder stops at those bytes. This deliberately restricts compatibility: PDFium has no public per-stream allocation limit, so unsupported structures are not passed to it. A host can prepare an accepted PDF before ingress; this kind never silently falls back to an unbounded parser. Text is capped at 100,000 characters per PDF page or PPTX slide as well as the configured total.

Outputs are capped at 32 MiB per file and 64 MiB total including metadata, independently of backend transfer limits. The execution deadline covers preflight and conversion together. Backend resource limits remain necessary for native parser allocations, CPU and temporary storage; these guards do not establish immunity to parser exploits.

See the document contract and image guide for verification and release evidence.

Metadata

Release files for maf-sandbox-document 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maf-sandbox-document 0.4.1
File Size Uploaded Provenance Actions
maf_sandbox_document-0.4.1.tar.gz 24.4 kB With provenance Details for maf_sandbox_document-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maf-sandbox-document 0.4.1
File Interpreter ABI Platform Actions
maf_sandbox_document-0.4.1-py3-none-any.whl Python 3 none any Details for maf_sandbox_document-0.4.1-py3-none-any.whl

Total release size: 51.5 kB

Release files / maf_sandbox_document-0.4.1.tar.gz

Download URL maf_sandbox_document-0.4.1.tar.gz
Size 24.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4fcd8a2c7aede93149000c884003b8f6fe7ac7980538cd9885d26cc26731a5d1
BLAKE2b-256 checksum
How to use checksums
7de71ad997606303f34736b0867d20a83a275e2b5a57c8b569fe60e0439a7240
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / maf_sandbox_document-0.4.1-py3-none-any.whl

Download URL maf_sandbox_document-0.4.1-py3-none-any.whl
Size 27.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d34bd1b51a5445c99abf01edfb029cca9e887d7be7dbe8ec45a6d09a7c6120dd
BLAKE2b-256 checksum
How to use checksums
dcd069f3155af3b77764e25d511c50ef17287a260b718648ffff177d4dfc1255
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for maf-sandbox-document 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for maf_sandbox_document-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page