Attachments is a Python library that turns files, folders, URLs, and repositories into text and images ready for a large language model's context. One function, att(), takes any input and returns a list of artifacts with one output shape: extracted text, page images, and a typed metadata envelope with structural segments such as pages. Version 1.0 is a complete rewrite of the earlier 0.25 series.
Two independent registries meet in that artifact format. Source handlers decide where bytes come from (local files, directories, zip and tar archives, HTTP URLs, and github:// repositories), and processors decide what the bytes are (PDF, Excel, Word, PowerPoint, HTML, images, audio, notebooks, and over 20 text formats). A PDF from GitHub runs through the same processor as one from disk, and both registries accept custom handlers. Content detection routes a file by its magic bytes when the extension is missing or wrong.
Options are written inline in a small bracket syntax, such as report.pdf[pages: 1-4, images: true], and each processor declares its own option schema, which is discoverable at runtime. Unknown keys become warnings on the artifact, and errors come back as artifacts with typed error codes instead of exceptions, so one broken file does not stop a folder of a hundred. Format support is installed as optional extras, and a missing dependency can fall back to a hosted service or a self-hosted server that does the processing for clients with no local dependencies.
Results render straight into a prompt string, provider-neutral parts that interleave each page's text with its image, Claude Messages API payloads, OpenAI Chat Completions payloads, or segment-aware chunks for retrieval. A rough token estimate is attached to every result. The same ingestion is exposed as a CLI, as an MCP server with att and att_options tools, and as a skill that teaches Claude Code, Pi, and Codex to write code with the library.
Features
- One output shape: every input becomes a list of artifacts carrying text, images, and a typed metadata envelope with page or slide segments
- Input formats: PDF, XLSX, XLS, DOCX, PPTX, HTML and web pages, CSV and TSV, SVG, images, Jupyter notebooks, audio, legacy Office and OpenDocument files, and 20+ text formats
- Sources: local files, folders with skip rules and size limits, wildcard patterns, zip and tar archives, HTTP URLs, and GitHub repositories
- Inline option syntax: per-file options such as page ranges, sheet names, image resolution, and OCR are written in brackets next to the path, with keyword-argument equivalents
- OCR for scans: pages with no text layer are read locally and offline, turned upright, and read column by column
- Audio transcription: MP3, WAV, M4A, FLAC, OGG, and Opus files are transcribed with faster-whisper
- Folder safety: secrets, dependencies, generated files, and gitignored paths are skipped, and an overview lists what was read and skipped
- Typed errors: failures come back as artifacts with error codes, and an opt-in call raises one exception listing every failure
- Last-mile adapters: results render to a prompt string, neutral parts, Claude or OpenAI message payloads, or retrieval chunks
- Service fallback: a missing local dependency can route processing to a hosted service or a self-hosted server
- Agent access: an MCP server exposes att and att_options tools, and a skill installs into Claude Code, Pi, and Codex
- Extensible registries: decorators register new file processors and new source protocols
