ai-riksarkivet Label Studio Feedback Workflow
Send document pages to Label Studio for human annotation and feedback.
Tool
label_import_to_label_studio— Import pages to a Label Studio project. Two modes:- With ALTO: pre-annotated tasks with polygons and transcriptions
- Images only: blank tasks for annotation from scratch
When to Use
- User asks to send pages for human review or annotation
- User wants to flag transcription or segmentation issues
- User wants to create Label Studio tasks from browse results
- User wants to send images for annotation from scratch
- User asks for quality assurance on specific pages
Two Modes
Mode 1: Pre-annotated (with ALTO XML)
Use when pages already have AI transcriptions. The tool fetches ALTO XML, extracts text line polygons and transcriptions, and creates VectorLabels pre-annotations.
{
"image_urls": [
"https://lbiiif.riksarkivet.se/arkis!30002056_00004/full/max/0/default.jpg"
],
"alto_urls": [
"https://sok.riksarkivet.se/dokument/alto/SE_RA_30002056_00004"
],
"feedback": [["Transcription"]]
}
Mode 2: Images only (no ALTO)
Use when there are no existing transcriptions — the user wants to annotate
from scratch. Just pass image URLs, omit alto_urls.
{
"image_urls": [
"https://lbiiif.riksarkivet.se/arkis!30002056_00004/full/max/0/default.jpg",
"https://lbiiif.riksarkivet.se/arkis!30002056_00005/full/max/0/default.jpg"
]
}
Choosing the Right Source for Pre-annotations
When the user wants to send pages with pre-annotations, choose the source based on what's available:
| Situation | Source | How |
|---|---|---|
Pages from browse_document results |
ALTO XML from Riksarkivet | Pass alto_urls from browse output |
| User has images without transcriptions | No pre-annotations | Omit alto_urls (image-only mode) |
| User has images and wants AI transcription first | HTR transcription | Use htr_transcribe first to generate ALTO XML, then pass the ALTO export URLs as alto_urls |
| User wants to label/annotate themselves | No pre-annotations | Omit alto_urls — blank tasks for manual annotation |
Tip: If the user has untranscribed images and wants pre-annotations, suggest
running htr_transcribe (see /htr-transcription skill) first to generate
ALTO XML, then feed those results into this tool.
Workflow
1. Get page URLs
From browse results: Call browse_document first (or use results
already in the conversation). Each page includes:
- ALTO XML URL:
https://sok.riksarkivet.se/dokument/alto/... - Image URL:
https://lbiiif.riksarkivet.se/arkis!.../full/max/0/default.jpg
From any image source: Any publicly accessible image URL works for image-only mode.
2. Determine feedback choices (optional, ALTO mode only)
| Value | Meaning |
|---|---|
Transcription |
Text recognition needs correction |
Segmentation |
Line/region boundaries need correction |
Each page gets its own list of feedback values. Use an empty list [] for pages
that need general review without a specific feedback flag.
3. Optionally assign to a user
Pass assign_to with a Label Studio user's email to auto-assign the imported
tasks for annotation. If omitted, tasks are created unassigned.
{
"image_urls": ["..."],
"alto_urls": ["..."],
"assign_to": "reviewer@example.com"
}
4. Call the tool
Label Studio URL, token, and project ID are configured via environment variables
(LS_URL, LS_TOKEN, LS_PROJECT_ID) — no need to pass them unless overriding.
5. Confirm to the user
The tool returns:
- Number of tasks imported and the mode (pre-annotated or image-only)
- Who the tasks were assigned to (if
assign_towas provided) - Direct links to each task in Label Studio for labeling
Share the task links with the user so they can go directly to Label Studio.
Dry Run — Preview Before Import
Set dry_run=true to see the converted Label Studio JSON without importing.
{
"image_urls": ["..."],
"alto_urls": ["..."],
"dry_run": true
}
Pairing Rules
When using alto_urls, all lists are paired by index — alto_urls[i],
image_urls[i], and feedback[i] refer to the same page.
| Rule | Detail |
|---|---|
image_urls is always required |
One image URL per page |
alto_urls is optional |
Omit for image-only tasks |
alto_urls and image_urls must match length |
One ALTO XML per image |
feedback must match length if provided |
One feedback list per page |
feedback requires alto_urls |
Feedback choices attach to ALTO text regions |
Extracting URLs from Browse Results
The browse_document tool returns per-page links in this format:
🔗 Links:
📝 ALTO XML: https://sok.riksarkivet.se/dokument/alto/SE_RA_30002056_00004
🖼️ Image: https://lbiiif.riksarkivet.se/arkis!30002056_00004/full/max/0/default.jpg
Collect the Image URLs (always needed) and ALTO XML URLs (only if you
want pre-annotations).
Batch Strategy
- Small sets (1-10 pages): Send all pages in a single call.
- Larger sets: Batch into groups of 10-20 pages per call to avoid timeouts. The tool has a 120-second timeout.
Common Mistakes
| Mistake | Fix |
|---|---|
| Mismatched list lengths | alto_urls and image_urls must be the same length |
| Passing feedback without alto_urls | Feedback requires ALTO (choices attach to text regions) |
| Passing feedback as flat list | Each entry must be a list of strings, e.g. [["Transcription"], []] not ["Transcription", ""] |
| Wrong ALTO URL format | Use the full URL from browse results, not just the page ID |
| Passing Label Studio credentials | Credentials are loaded from env vars — only pass if overriding |
Environment Variables
| Variable | Description |
|---|---|
LS_URL |
Label Studio instance URL |
LS_TOKEN |
Label Studio Personal Access Token (JWT PAT) |
LS_PROJECT_ID |
Target project ID |
These are configured in packages/mcps/label-mcp/.env and loaded automatically.