Library

Assets (Library > Assets, /app/library/assets) are the reusable files that OrcAI searches to ground and cite answers.

The Library, its pickers and the OrcAI Assistant's find tools show the bots, blocks and assets of your active organisation that you can read: those made there and those it added from the Catalogue. A bot's blocks and a repository's assets open through the bot or repository, so what a shared bot contains is readable without appearing in your Library. Chat pickers and the bots on the home page offer only the bots shared with you in your active organisation.

Browsing the LibraryCopy Anchor Link

The Library (/app/library) shows everything your organisation can use. Its header has a search field and a New menu. A rail on the left (above the results on small screens) has:

• A switch between All and Mine. Mine shows only what you can edit, as owner or with Can edit or Can manage, directly or through a group. It stays on when you switch views, and the counts follow it.
• The views: Overview and one per kind (Bots, Behaviours, Repositories, Assets), each with its count.
• The view's filters, on a kind view or while searching. On narrow screens they open from Filters, which shows how many are set.

Show in Library on an upload's Activity entry opens the Assets view with only the assets of that upload, wherever they are now. A bar above the results names the entry, and its × or any filter returns to the whole view.

Origin tells apart what your organisation made (Made in this organisation) from what it added from the Catalogue (Added from the Catalogue). Assets are never added on their own, so searching for added items leaves them out.

The Overview shows shelves: with Mine, your Drafts first, then your Favourites, then each kind with See all, which opens that kind's view. With fewer than six items it shows them all in one grid.

Search matches names and titles. On the Overview it searches every kind at once, in one list and one pager, and on a kind view it searches only that kind. Results are sorted Newest or A to Z and paged under the grid. Search, filters, sort, page and Mine are part of the address, so Back from a page returns to the same results and scroll position. Changing the search, a filter, the sort or Mine starts over on the first page.

New offers Bot, Behaviour, Repository and Upload files, each for roles with the matching create_bot, create_block or create_asset permission. An empty Library says whether you can create something or wait for others to share, and offers Browse the Catalogue.

Every tile opens its page. Under its name it shows its owner, or "From" and the home organisation for what your organisation added from the Catalogue. Its corner holds the Favourite star for published bots and a … menu with the actions your role allows. Something added from the Catalogue is edited only in its home organisation. In your organisation, admins and managers share it for use and remove it with Remove from …, and they set an added bot's model on its page.

End-to-end flowCopy Anchor Link

1. Upload files on Add assets (/app/library/assets/add). Each file becomes an asset as soon as its upload finishes, and OrcAI keeps the original in S3-compatible object storage.
2. Add metadata to the new assets, right away or later. With a utility model, OrcAI generates it for Library uploads once the file is prepared.
3. A background job reads the file and extracts its text. The organisation's utility model describes each image, whether an image file or a figure inside a file, so its content can be found by search. An image with text is described in the language of that text, and an image without text in the language of the person who uploaded it. The descriptions are saved with the extracted text, and indexing in every repository reuses them. When the budget runs out partway through a file, the descriptions written so far are charged but not saved, so a retry describes those images again.
4. Add the asset to one or more repositories, from the repository editor or the bot editor's Repositories step.
5. For each repository the asset belongs to, a background job vectorises it into that repository's index. This runs when the asset is Ready and when the asset is added to a repository.
6. Repositories are used in bots or attached directly to chats.

Adding assetsCopy Anchor Link

New > Upload files in the Library opens /app/library/assets/add. It needs the create_asset permission.

Assets are added only by uploading files, in two steps:

1. Upload assets: select files and Upload files. Each file becomes an asset as soon as its upload finishes, so there is nothing else to save.
2. Uploaded assets: the new assets are listed. With a utility model, each shows Generating metadata until its generated title and description appear. You can leave, and the results land in the Library. The upload and its preparation also show in Activity. Metadata opens Edit metadata for a file, and Save stores it at once. Files that could not be added are listed with the reason. Upload more returns to the upload step, and Done, shown once a file was added, goes to the Assets view.

Leaving the page while files are still uploading asks for confirmation. Leaving anyway stops the upload, and those files are not added. Once a file's asset exists, leaving loses nothing.

The same flow runs inside an OrcAI Assistant conversation when the Assistant asks for files, and in the repository editor's Upload new assets dialog, which also adds the new assets to the repository.

Accepted file types:

• Images: JPEG, PNG, GIF, WebP
• PDF
• Text: TXT, CSV, Markdown
• Office: DOC, DOCX, XLS, XLSX, PPT, PPTX

A file can be up to 64 MB, and one upload takes up to 100 files.

Library and chat uploadsCopy Anchor Link

The Assets view's Kept in filter has two choices. Library (the default) lists the assets uploaded on Add assets, in the repository editor or through the Assistant. Chats lists the chat uploads, the assets uploaded with a chat message. OrcAI prepares them like any other asset, but the Library's counts and its Overview leave them out until someone adds them to the Library.

Add to Library in a chat upload's tile menu moves it to the Library and generates its metadata like a Library upload. It needs edit access to the asset. Deleting a chat keeps its uploads, which you delete from Kept in > Chats. Deleting an account deletes its chat uploads.

Only Library assets go into repositories. The repository editor's asset picker lists the Library only, and a chat upload goes into a repository once someone adds it to the Library. The chat composer's picker searches both and marks chat uploads with a Chat upload badge.

MetadataCopy Anchor Link

The metadata travels with the asset wherever it is reused and has these fields:

• Source title
• Description: two or three sentences on what the source is about, up to 300 characters. Cards show it, and the model reads it in the list of a repository's assets to pick what to search.
• Language: the source's language as a code such as en or de-CH.
• Source type: Book, Journal Article, Web Source or Legal Text. Each type adds its own fields:
  • Book: Author(s), Citation label, Chapter title, Page range
  • Journal Article: Author(s), Citation label, Journal name, Volume, Issue, Page range, DOI
  • Web Source: Author(s), Citation label, Website name, External URL, Access date
  • Legal Text: Citation label, Legal reference, Jurisdiction
• External URL (for types other than Web Source)

Edit metadata later with Edit metadata on the asset page, which opens /app/library/assets/<asset id>/edit. Saving stores only the fields you changed, so metadata generated while the editor was open is kept. When you save after changing the source type, the fields the new type does not have are removed.

Metadata generated with AICopy Anchor Link

When the organisation has a utility model, the model writes an asset's title, source type and its fields, a citation label in APA 7 style, a description and the language. For a chapter, the title is the book's, and the chapter's own title goes in its field. It works from the start of the extracted text and the details the parser found (title, authors, keywords, page count, language). Generated text is in the file's language. For an image file, the description written while preparing the image supplies the title, description and language. Each run draws on the utility model's quota pools.

Once a Library upload is prepared, OrcAI writes its metadata in the background. A chat upload gets it when it is added to the Library. Only empty fields are filled, and the title only while it is still the uploaded file name, so values you save in the meantime always win. Fields that do not fit the source type you chose are kept for review instead.

Generate with AI in the metadata editor generates a suggestion for an asset you can edit, also for assets uploaded before or edited since. While the editor shows Generating..., you can leave, and the asset page then says Suggestions ready with Review. Suggested metadata lists each field with its current and suggested value, with the empty fields selected. Use selected puts the chosen values into the form, and Save stores them. Dismiss drops the suggestion. The Suggestions to review filter on the Assets view lists every asset you can edit that has a suggestion waiting.

Generate missing metadata, above the Library uploads in the Assets view, fills the empty fields of every prepared Library asset of the organisation that you can edit and whose metadata was never generated or failed. It asks first and shows how many assets that is.

The OrcAI Assistant can do the same for assets you name, after you confirm. It never overwrites values, so to replace them, use Generate with AI or tell it the values.

While metadata is generated, cards, the upload list and the asset page show Generating metadata. A failed run says why on the asset page: the call to the utility model failed, its answer did not have the expected form or was cut off at its length limit, the budget ran out, or the text read from the file is missing. When the budget ran out, run it again once the pool resets. When the text read from the file is gone, OrcAI prepares the file again once and then generates the metadata. Without a utility model, nothing is generated, Generate with AI is disabled with a hint (admins get a link to the organisation settings), and Generate missing metadata is hidden. Generating metadata never affects whether an asset is ready for its repositories.

The asset pageCopy Anchor Link

The asset page (/app/library/assets/<asset id>) shows a preview of the file, its Metadata, and its Preparation status.

Depending on your access to the asset, the page offers Download for the original file, Edit metadata and Access & groups, and its More actions menu holds Prepare again and Delete asset.

Preparation status and preparing againCopy Anchor Link

Outside a repository, asset cards, the recent changes on Home and the Preparation status card on the asset page show how far preparation of the file is:

Inside a repository, each asset also has an indexing step, so its card on the repository page shows one more state, Indexing, between Processing and Ready. There, Ready means searchable in that repository.

A failing step is retried automatically, so an asset stays Processing until its last attempt has failed. A failed asset says why:

• OrcAI cannot read the file type, or the utility model cannot read images for an image file.
• No text or images were found, for example in a scanned PDF whose text cannot be recognised.
• The file could not be read.
• Preparing it took too long.
• The budget ran out while describing images.
• The call to the utility model failed while describing an image file, or its answer did not have the expected form or was cut off at its length limit.
• Another error.

The first two fail at once, since retrying cannot help. A used-up budget also fails at once, with nothing half prepared, and you can retry once the pool resets. An answer cut off at its length limit fails at once too, since the same request is cut off again. Without a utility model that reads images, figures in files are skipped and the rest of the file is prepared.

On the Preparation status card, Retry appears for a failed asset you can edit, unless retrying cannot help, and queues preparation again.

Prepare again is available from the tile menu in the Assets view and from the asset page, when the asset is not Queued or Processing and you can edit it. It asks for confirmation, then runs preparation again, and the asset's repositories index it again afterwards. Prepare again is useful after parser or configuration changes.

Each repository keeps the indexing state of each of its assets. Editing a repository indexes only the assets it adds, and the assets it keeps stay as they are. Activity shows the uploads and retries you started and the failures that need you. Operators find failed jobs in the worker logs and the pg-boss tables.

AccessCopy Anchor Link

Your access to an asset decides whether you can download, edit or delete it and manage who else has access. Access & groups opens the shared access dialog with its People and Groups tabs, described in Access control.

Relationship to retrievalCopy Anchor Link

Bots and chats do not retrieve from assets directly. Assets are added to repositories, which are then attached to bots or chats. See Bots and behaviour.

In a chat, you can also attach an asset to a single message with the paperclip (Attach files) > Choose existing assets. The model receives the file, or its extracted text, with that message. See Chat.

Instance dependenciesCopy Anchor Link

Assets rely on these parts of the instance:

• S3-compatible storage
• Worker preparation pipeline
• Embedding generation
• Qdrant indexing

Until an instance admin sets up embeddings, uploads still work and assets are prepared, but a repository card shows Waiting for the embedding setup in place of Indexing, and repository search fails with "Search is unavailable until an instance admin sets up embeddings." Once the setting is saved, the workers index every waiting asset within about a minute, so nothing has to be uploaded again. See Embeddings. When an instance admin changes the embedding model, every asset is embedded again, and until that finishes search finds only some assets. Chats that search repositories and repository pages say so in a notice.