Library document preparation, batch loading, and maintenance

Your documents are loaded, your Tasks answer from them, and the answers are not yet good enough.

During a Task, the model can use retrieved passages, so the documents you upload shape the available source material. The SDK does not expose the passages behind a completed Task Result. Each habit below improves or protects the material the model can read. You need access to upload or delete documents and a way to correct the source file. Access and isolation explains the required Library Grants.

Prepare a document that indexes well

Keep each logical record concise and on one page.

Duale AI splits each document page by page, and a passage never crosses a page boundary. Library retrieval explains that rule.

• Do not let a record straddle a page break. A table that breaks across a page becomes two passages, and neither carries the other one’s context.
• Keep a heading with the text it introduces. The passage that answers a question then holds the words that name its subject.
• Give every page readable text when the answer depends on words. OCR can recover words from a picture, but the result is best effort. A page without readable text produces no text passage; an extracted picture can still answer a visual question when an image-capable model can carry it.
• Supply a recording as a transcript or as a subtitle file. Duale AI reads text, not speech.

When extraction produces neither searchable text nor a searchable picture, correct the source file and upload it again. SDK errors names that failure and the other causes.

Limits lists the accepted kinds of file.

Extraction is best effort, so when visual meaning has to be exactly right, extract it yourself and upload the text.

Make exact references searchable

Put the exact string a person would quote into the text of the document.

The model can answer a question about meaning with ranked search and find an exact string with literal match. The model selects the Tool for each call, so you control the text available to both Tools.

• Keep every exact reference in the text, on one line. An invoice number, an error code, a part reference, or a symbol in code must appear in the document text. Literal match reads one line at a time, so a reference that a line break splits is not found. Do not rely on a filename or on OCR to recover it from a rendered image.
• Name the file for the string a person would type. A listing filters on part of a filename, so a name that carries the customer, the period, and the subject narrows a long list to the documents that matter.
• Say on the first page what the document holds. A question rarely uses the wording buried inside a document. A first page that names the subject, the period, and the parties gives the ranked search something to match.

Library design and Agent Identity access determine which documents a search can reach. Design your Libraries owns that structure. If an answer appears incomplete, Library retrieval explains the search-completion signal and what it means.

Load a batch without surprises

Upload each file once, then poll it until it is readable.

A large import becomes readable over time rather than all at once, and the order in which files finish is not guaranteed. Plan the import around that.

• Poll a document rather than uploading it again. Every upload creates a new document, so a second upload adds a copy instead of replacing the one in flight.
• Wait for a document to become readable before a task depends on it. A document that is still on its way appears in a listing with its current status, and a search does not reach it yet.
• Send a large batch well ahead of the deadline that needs it. You cannot predict which file finishes last, so leave room for the whole batch rather than for one file.

Manage libraries has the calls that upload, poll, and wait. When a duplicate reaches ready, delete the copy you do not want.

Keep the corpus current

Upload the new version, wait until it is readable, then delete the old one.

A document has no update in place. A new version of a file is a new document with its own identifier, so the order of those calls decides what a Task reads in between. Keep the order above and at least one version stays readable. The reverse order opens a gap until the new document is readable, and stopping after the upload leaves both versions answerable.

Delete a document when it stops answering a question, even when nothing replaces it. A superseded document you leave in place still competes with the current one.

Library actions lists the three SDK methods.

Optional: Skip unchanged files

For a recurring automated import, you can record your own compact file fingerprint in the document’s tags. On the next run, compare the source with that tag and upload only files whose fingerprint changed.

Duale AI does not tell you which of your files changed. A document reports its filename, size, and status, but nothing else you can compare with a source file. The fingerprint avoids unnecessary uploads, but your import must create and maintain it. For a small or manual corpus, use the replacement sequence above instead. Check the tag limit on Limits.

An update replaces the whole tag map instead of merging into it. Read the current tags first when you need to keep another key.

Keep storage predictable

Delete a document when you no longer need it.

Duale AI records stored document volume over time. Limits defines the measurement rules. Pricing and access states whether the applicable commercial terms bill that volume separately.

• Plan the deletion when you plan the upload. A deleted document waits in the Recently deleted window before it becomes eligible for asynchronous removal, and it counts as recorded stored volume for that whole window. Limits states the window and the other numbers.
• Library deletion is irreversible. Delete a task-scoped Library only after the Task and any planned continuations no longer need its files. Nothing expires that Library, and its documents remain part of recorded stored volume until someone deletes them.

Check the change

After you replace a document, ask one question whose answer depends on the changed text. Confirm that the completed result uses the current value and names the expected source. If the answer depends on an exact identifier or a figure, use that specific reference in the question.

After a batch upload, count the documents with ready status across every listing response and compare that count with the files you sent. After cleanup, list active and Recently deleted documents to confirm that the intended versions remain.

These checks show the completed result and Library state. They do not identify the passage or figure selected during a Task.