Perception
Sources
Parse, Split, Classify, Extract and Ground take the document as their SOURCE argument:
SOURCE | What it is |
|---|---|
https://... | A public link the document service downloads. See URLs. |
| A local file path | Uploaded to the server first, then read from there. See Local files. |
ws:<workspace_id>/<file_id> | A file already uploaded: what nace upload prints. |
job:<job_id> | One of your finished parse jobs, so the document isn't parsed and paid for again. Not for classify, and not with -p on parse or extract, --mode medium or high, or --password. |
Anything else, such as an http:// link or a path that doesn't exist, exits 2 before any request.
URLs
The document service picks the parser from the file name's extension, so a URL source carries a file_name:
nacetakes it from the URL's last path segment when that has an extension, without the query and percent-decoded:https://example.com/files/Q3%20report.pdfgivesQ3 report.pdf.- When the segment has none, the command exits
2. Name the file with--file-name. - Pass
--file-nametoo when the segment only looks like it has an extension, as inhttps://arxiv.org/pdf/1706.03762.
# The file name comes from the URL
nace parse https://example.com/files/Q3%20report.pdf
# The URL has no file name: give one
nace parse "https://example.com/download?id=7" --file-name report.pdf
# ".03762" is not an extension
nace parse https://arxiv.org/pdf/1706.03762 --file-name attention.pdf--file-name applies only to an https:// source.
Local files
A local file is uploaded to the server first, like nace upload, then read from there. Stderr shows uploading <name>, then uploaded ws:<workspace_id>/<file_id>, and stdout has the result as usual:
nace parse ./invoice.pdfuploading invoice.pdf
uploaded ws:0f8b7c2e-.../3a91c5...Pass the uploaded value as SOURCE next time instead of uploading again:
nace parse ws:0f8b7c2e-.../3a91c5... --chunk pageWithout options the file is stored under its own name. Set the path yourself, and what happens when a different file already has it, with these flags:
nace parse ./q3.pdf --upload-path reports/2026/q3.pdf --on-conflict new_version| Flag | What it does |
|---|---|
--upload-path PATH | The file's path in your workspace. Default: its file name. Keep the file's extension: the document service types an upload from its first bytes, and from this extension when those don't settle it. |
--on-conflict {reject,new_version} | What happens when a different file already has that path. reject, the default, fails with 409 path_conflict. new_version adds a version of that file, which jobs on it that haven't started yet then read. |
Uploading the same bytes to the same path again reuses the file already there. An edited file under the same name fails with path_conflict, and stderr says how to go on: pass another --upload-path, or --on-conflict new_version. Both flags apply only to a local-file source. See Same path again.