attachments

Attachments 1.0: any file to text and images for a model

att("report.pdf") reads almost anything and returns Artifacts: a list of plain dicts, one per file, each {text, images, audio, video, meta}. Most of the library is that one call; this page covers what goes wrong around it. All option names: options.md next to this file (generated from the code).

1. Make sure it is 1.0 (check before writing code)

python -c "import attachments as a; print(a.__version__, hasattr(a, 'att'))"

• False, or no module: install 1.0 (a project pinned below it still has 0.25, the old API):

  uv add "attachments[pdf,image]>=1.0"
  pip install "attachments[pdf,image]>=1.0"
  

  A local checkout: uv add --editable /path/to/attachments.

• Never write 0.25 code, which models remember: Attachments("f.pdf"), attach(...) | load.x | present.y, ctx.images as base64 strings, [format: ...], adapt.claude(...).

• Extras: pdf, image, docx, xlsx, pptx, html, all-local; ocr and audio are large; browser (web page screenshots) also needs playwright install chromium. The core has no dependencies and reads text, code, CSV and JSON. A missing extra raises nothing: that file comes back with error code missing-dependency and the exact pip install command. Pictures you ask for that cannot be drawn here (no LibreOffice, Chromium, PyMuPDF or cairosvg) never cost the text: the file is read, and a warning in meta["warnings"] names what is missing.

2. The one call

from attachments import att

a = att("report.pdf[pages: 2-4, images: true]")  # options in [...]
a = att("report.pdf", pages="2-4", images=True)  # the same, as keywords
a = att("docs/")                                 # a folder (recursive); also .zip, .tar
a = att("scans/*.pdf")                           # a wildcard (anywhere: "*/a.md")
a = att("https://example.com/paper.pdf")         # a URL
a = att("github://owner/repo[ref: main]")        # a repository
a = att(["report.pdf", "chart.png"])             # several inputs (str or Path)