ai-riksarkivet Document Viewer Tools
Three tools open the interactive document viewer. Choose based on what you have:
| Tool | When to use |
|---|---|
view_document |
You have a Riksarkivet reference code (e.g. from search results) |
view_manifest |
You have a IIIF manifest URL (e.g. from SDHK/MPO search or any IIIF source) |
view_document_urls |
You already have raw image URLs and text layer XML URLs |
All tools render the same interactive viewer with zoomable images, text-layer overlays (when ALTO XML is available), search, info panel, and fullscreen.
view_document — From Reference Code
Resolves a Riksarkivet reference code into IIIF image URLs and ALTO XML text layers automatically via BrowseOperations.
Required Arguments
| Argument | Type | Description |
|---|---|---|
reference_code |
string | Archive reference code (e.g. "SE/RA/420422/01") |
pages |
string | Page spec: "5", "1-10", or "5,7,9" |
Optional Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
highlight_term |
string | null | Pre-populate search bar and highlight matches |
max_pages |
int | 20 | Maximum pages to retrieve (max: 20) |
Examples
{"reference_code": "SE/RA/420422/01", "pages": "7"}
{"reference_code": "SE/RA/420422/01", "pages": "1-10", "highlight_term": "Stockholm"}
{"reference_code": "SE/RA/310187/1", "pages": "5,7,9"}
view_manifest — From IIIF Manifest URL
Fetches a IIIF manifest, extracts page images and ALTO text layers (from seeAlso), and opens the viewer. Works with any IIIF Presentation API v3 manifest — Riksarkivet, Wellcome Collection, or other providers.
Required Arguments
| Argument | Type | Description |
|---|---|---|
manifest_url |
string | Full IIIF manifest URL |
Optional Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
highlight_term |
string | null | Pre-populate search bar and highlight matches |
max_pages |
int | 20 | Maximum pages to load (max: 20) |
Examples
Riksarkivet police records (with ALTO transcription):
{"manifest_url": "https://lbiiif.riksarkivet.se/arkis!30002056/manifest"}
SDHK medieval charter (image only, no transcription):
{"manifest_url": "https://lbiiif.riksarkivet.se/sdhk!85/manifest"}
SDHK with Transkribus transcription (from Hugging Face):
{"manifest_url": "https://huggingface.co/buckets/Riksarkivet/sdhk_hack/resolve/transkribus/manifests/sdhk_R0001691.json"}
Wellcome Collection (external provider, with ALTO):
{"manifest_url": "https://iiif.wellcomecollection.org/presentation/b18035723", "max_pages": 10}
Note: Documents with ALTO XML in the manifest's seeAlso will have text overlays and transcription. Documents without show images only.
view_document_urls — From Raw URLs
Use when you already have image and text layer URLs (e.g. from external sources or manual construction). Prefer view_manifest when you have a manifest URL.
Required Arguments
| Argument | Type | Description |
|---|---|---|
image_urls |
list[string] | One image URL per page (JPEG or PNG) |
text_layer_urls |
list[string] | One XML URL per page (ALTO/PAGE), paired 1:1 with image_urls. Use "" for pages without transcription |
Both lists must have the same length.
Optional Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
document_info |
string | null | Markdown-formatted document metadata for the info panel |
highlight_term |
string | null | Pre-populate search bar and highlight matches |
Examples
{
"image_urls": ["https://lbiiif.riksarkivet.se/arkis!R0001203_00007/full/max/0/default.jpg"],
"text_layer_urls": ["https://sok.riksarkivet.se/dokument/alto/R000/R0001203/R0001203_00007.xml"]
}
With document info:
{
"image_urls": ["https://example.com/page1.jpg", "https://example.com/page2.jpg"],
"text_layer_urls": ["https://example.com/page1.xml", ""],
"document_info": "## My Document\n\n**Date:** 1902\n\n**Source:** Example archive"
}
viewer_go_to_page — Jump to a Page in Open Viewer
Use this when the user asks to "go to page 3" or "show page 5". Does NOT replace the loaded pages — just scrolls to that page within the already-loaded document.
| Argument | Type | Description |
|---|---|---|
page |
integer | Page number (1-based) |
{"page": 3}
viewer_set_highlight — Change Highlight in Open Viewer
IMPORTANT: Use this instead of calling view_document/view_document_urls again when the viewer is already open and the user just wants to highlight a different term. Calling the original tools again creates a duplicate viewer.
| Argument | Type | Description |
|---|---|---|
highlight_term |
string | Search term to highlight. Use "" to clear. |
{"highlight_term": "göteborg"}
viewer_navigate — Navigate to Different Pages in Open Viewer
IMPORTANT: Use this instead of calling view_document again when the viewer is already open and the user wants to see different pages. Calling the original tool again creates a duplicate viewer.
| Argument | Type | Description |
|---|---|---|
reference_code |
string | Archive reference code |
pages |
string | Page spec: "5", "1-10", or "5,7,9" |
highlight_term |
string (optional) | Search term to highlight |
{"reference_code": "SE/RA/420422/01", "pages": "20-30", "highlight_term": "Stockholm"}
Typical Workflow
- Search with
search_transcribed,search_metadata, ordiplomatics:search_sdhkto find documents. - Browse with
browse_documentto read the transcription text. - View with
view_document(reference code),view_manifest(IIIF URL), orview_document_urls(raw URLs). - Update with
viewer_set_highlightorviewer_navigateto change what's displayed without creating a new viewer.
When to Use Which Tool
| Scenario | Tool |
|---|---|
| Have a reference code from search | view_document |
| Have a IIIF manifest URL (SDHK, MPO, Wellcome, etc.) | view_manifest |
| Have raw image/ALTO URLs | view_document_urls |
| User asks to "go to page 3" | viewer_go_to_page |
| User asks to highlight/search a different term | viewer_set_highlight |
| User says "show the viewer again" / "open the document" | viewer_reopen |
| User asks to load a different set of pages | viewer_navigate or viewer_navigate_urls |
| User asks to view a completely different document | view_document, view_manifest, or view_document_urls |
Key rule: Never call the entry-point tools twice in the same conversation if the viewer is already open. Use the update tools instead.
Common Mistakes
| Mistake | Fix |
|---|---|
Calling view_document again to change the highlight |
Use viewer_set_highlight — it updates the existing viewer without creating a duplicate. |
Calling view_document again to show different pages |
Use viewer_navigate — it updates the existing viewer. |
Using view_document with a manifest URL |
Use view_manifest for IIIF manifest URLs. view_document takes reference_code + pages. |
Using view_document with a manifest ID like 30002056 |
Use a full reference code like SE/RA/.... Get it from search results. |
Mismatched list lengths in view_document_urls |
Every image_urls entry needs a corresponding text_layer_urls entry. |
Forgetting "" for missing text layers |
Use an empty string — do not omit the entry or use null. |
Using highlight_term on pages without text layers |
Highlights require ALTO/PAGE XML. Pages with "" text layers won't have matches. |