Reading Uploaded Files

Dispatch table

PDF

Never cat a PDF — it prints binary garbage.

Quick first move — get the page count and check if text is extractable:

pdfinfo /mnt/user-data/uploads/report.pdf
pdftotext -f 1 -l 1 /mnt/user-data/uploads/report.pdf - | head -20

Then peek at the text content:

from pypdf import PdfReader
r = PdfReader("/mnt/user-data/uploads/report.pdf")
print(f"{len(r.pages)} pages")
print(r.pages[0].extract_text()[:2000])

For anything beyond a quick peek — figures, tables, attachments, forms, scanned PDFs, visual inspection, or choosing a reading strategy — go read /mnt/skills/public/pdf-reading/SKILL.md. It covers content inventory, text extraction vs. page rasterization, embedded content extraction, and document-type-aware reading strategies.

For PDF form filling, creation, merging, splitting, or watermarking, go read /mnt/skills/public/pdf/SKILL.md.

DOCX / DOC

The docx skill covers editing, creating, tracked changes, images. Read it if you need any of those. For a quick look:

pandoc /mnt/user-data/uploads/memo.docx -t markdown | head -200

Legacy .doc (not .docx) must be converted first — see the docx skill.

XLSX / XLS / spreadsheets

The xlsx skill covers formulas, formatting, charts, creating. Read it if you need any of those. For a quick look at .xlsx / .xlsm:

from openpyxl import load_workbook
wb = load_workbook("/mnt/user-data/uploads/data.xlsx", read_only=True)
print("Sheets:", wb.sheetnames)
ws = wb.active
for row in ws.iter_rows(max_row=5, values_only=True):
    print(row)

read_only=True matters — without it, openpyxl loads the entire workbook into memory, which breaks on large files. Do not trust ws.max_row in read-only mode: many non-Excel writers omit the dimension record, so it comes back None or wrong. If you need a row count, iterate or use pandas.

Legacy .xls — openpyxl raises InvalidFileException. Use:

import pandas as pd
df = pd.read_excel("/mnt/user-data/uploads/old.xls", engine="xlrd", nrows=5)

.ods (OpenDocument) — openpyxl also rejects this. Use:

import pandas as pd
df = pd.read_excel("/mnt/user-data/uploads/data.ods", engine="odf", nrows=5)

PPTX

from itertools import islice
from pptx import Presentation
p = Presentation("/mnt/user-data/uploads/deck.pptx")
print(f"{len(p.slides)} slides")
for i, slide in enumerate(islice(p.slides, 3), 1):
    texts = [s.text for s in slide.shapes if s.has_text_frame]
    print(f"Slide {i}:", " | ".join(t for t in texts if t))

p.slides is not subscriptable — p.slides[:3] raises AttributeError. Use islice or list(p.slides)[:3].

Legacy .ppt — python-pptx only reads OOXML. Convert to .pptx first via LibreOffice; see /mnt/skills/public/pptx/SKILL.md for the sandbox-safe scripts/office/soffice.py wrapper (bare soffice hangs here because the seccomp filter blocks the AF_UNIX sockets LibreOffice uses for instance management).

For anything beyond reading, go to /mnt/skills/public/pptx/SKILL.md.

CSV / TSV

Do not cat or head these blindly. A CSV with a 50KB quoted cell in row 1 will wreck your head -5. Use pandas with nrows:

import pandas as pd
df = pd.read_csv("/mnt/user-data/uploads/data.csv", nrows=5)
print(df)
print()
print(df.dtypes)

Approximate row count without loading (over-counts if the file has RFC-4180 quoted newlines — the same quoted-cell case this section warned about above):

wc -l /mnt/user-data/uploads/data.csv

Full analysis only after you know the shape:

df = pd.read_csv("/mnt/user-data/uploads/data.csv")
print(df.describe())

TSV: same, with sep="\t".

JSON / JSONL

Structure first, content second:

jq 'type' /mnt/user-data/uploads/data.json
jq 'if type == "array" then length elif type == "object" then keys else . end' /mnt/user-data/uploads/data.json

(keys errors on scalar JSON roots — a bare "hello" or 42 is valid JSON per RFC 7159 — so guard the branch.)

Then drill into what the user actually asked about.

JSONL (one object per line) — do not jq the whole file; work line by line:

head -3 /mnt/user-data/uploads/data.jsonl | jq .
wc -l /mnt/user-data/uploads/data.jsonl

Images (JPG / PNG / GIF / WEBP)

You can already see uploaded images. They are injected into your context as vision inputs alongside the <uploaded_files> pointer. You do not need to read them from disk to describe them.

The disk copy is only needed if you are going to process the image