Heratio Help Center article. Category: AI & Automation.

AI Tools

User Guide

Powerful AI-powered tools for archival records: Named Entity Recognition (NER), Translation, Summarization, Spellcheck, Handwriting Text Recognition (HTR), and LLM Description Suggestions.

The AI tools are an optional paid subscription, not part of the base platform. They are dormant until an AHG AI gateway subscription is activated. See AI features - subscription service for what is included and how to subscribe.

Overview

Features Summary

Named Entity Recognition (NER)

What is NER?

NER automatically identifies and extracts named entities from your archival records: Entity Types Detected

Using NER from the Interface

Step 1: Navigate to Record

Go to any archival description (Information Object)

Step 2: Click Extract Entities

Step 3: View Results

Reviewing Extracted Entities

Access the Review Dashboard

Navigate to: Admin -> AI Tools -> NER Review

Review Dashboard

Entity Review Actions

• ACTIONS FOR EACH ENTITY
• CREATE & LINK Create new actor/place/subject and
• link to record
• LINK TO EXISTING Link to existing authority record
• (exact or fuzzy match suggested)
• APPROVE Mark as correct but don't link
• REJECT Mark as incorrect/not relevant

Editing Entities Before Saving

Auto-trigger NER on Document Upload

NER extraction can be automatically triggered when documents are uploaded, saving time and ensuring all uploaded content is processed.

Enabling Auto-trigger

Navigate to: Admin > AHG Settings > AI Services > NER

Enable the "Auto-extract on upload" setting.

How It Works

Supported Document Types for Auto-trigger

Processing Pending Queue

Uploaded documents are queued for background processing. The standard Heratio queue worker drains them automatically; you can also process the queue on demand:

# Process pending NER extractions
php artisan ahg:ai-process-pending --limit=20

This runs from Heratio's task scheduler/queue worker - no per-task crontab entry is required.

Translation

About Translation

Translate archival descriptions between languages using offline machine translation (Argos Translate).

Supported Languages

Using Translation

From the Command Line

# Translate a single record
php artisan ahg:ai-translate --from=en --to=af --object=12345

# Translate all records in a repository
php artisan ahg:ai-translate --from=en --to=af --repository=5 --limit=50

# Overwrite existing target-culture text instead of skipping
php artisan ahg:ai-translate --from=en --to=af --object=12345 --overwrite

# Preview what would be translated
php artisan ahg:ai-translate --from=en --to=af --object=12345 --dry-run

Translation Options

• TRANSLATION OPTIONS
• --from Source culture to read from (default: en)
• --to Target culture to write (required, e.g. af)
• --object Translate a specific information_object ID
• --repository Translate all in a repository ID
• --limit Maximum records to translate (0/blank = all)
• --overwrite Replace existing target text instead of skip
• --dry-run Preview without making changes

Translation Process

Summarization

About Summarization

Automatically generate summaries for records with attached PDF documents, saving time on cataloging.

Using Summarization

From the Interface

Result

From the Command Line

# Summarize a specific record
php artisan ahg:ai-summarize --object=12345

# Summarize records with empty Scope & Content
php artisan ahg:ai-summarize --all-empty --limit=50

# Summarize records in a repository
php artisan ahg:ai-summarize --repository=5 --limit=100

# Preview what would be processed
php artisan ahg:ai-summarize --all-empty --dry-run

Summarization Settings

• SUMMARIZATION OPTIONS
• --object Summarize specific object ID
• --repository Summarize all in repository ID
• --all-empty Process records with empty summary
• --field Target field (default: scope_and_content)
• --limit Maximum records to process
• --dry-run Preview without making changes

How It Works

LLM Description Suggestions

About Description Suggestions

Generate intelligent Scope and Content descriptions using Large Language Models (LLMs). The system combines OCR text, metadata, and contextual information to suggest comprehensive archival descriptions.

Supported LLM Providers

Using Description Suggestions

From the Interface

Step 1: Navigate to Record

Go to any archival description with OCR text or metadata

Step 2: Click Suggest Description

Step 3: Review Side-by-Side

Step 4: Make Decision

• DECISION OPTIONS
• APPROVE Accept suggestion as-is, save to record
• EDIT & APPROVE Modify suggestion, then save to record
• REJECT Discard suggestion, add rejection notes

Review Dashboard

Access via: Admin -> AI Tools -> Suggestion Review

From the Command Line

# Generate suggestion for specific record
php artisan ahg:ai-suggest-description --object=12345

# Process records with empty scope_and_content
php artisan ahg:ai-suggest-description --empty-only --limit=50

# Prefer records that have OCR text
php artisan ahg:ai-suggest-description --with-ocr --limit=100

# Process records in a specific repository
php artisan ahg:ai-suggest-description --repository=5 --limit=50

# Preview what would be processed (dry run)
php artisan ahg:ai-suggest-description --empty-only --dry-run

# Use specific prompt template
php artisan ahg:ai-suggest-description --template=2 --limit=20

# Use specific LLM configuration
php artisan ahg:ai-suggest-description --llm-config=1 --limit=20

Command Options

• SUGGEST DESCRIPTION OPTIONS
• --object=ID Process specific object ID
• --repository=ID Process all in repository ID
• --level=LEVEL Filter by level (fonds, series, file, item)
• --empty-only Only records with empty scope_and_content
• --with-ocr Only records that have OCR text available
• --limit=N Maximum records to process (default: 50)
• --template=ID Prompt template ID to use
• --llm-config=ID LLM configuration ID
• --dry-run Preview without generating suggestions
• --delay=MS Delay between API calls (default: 1000)

How It Works

Prompt Templates

The system includes default templates that can be customized:

Template Variables

Cron Job Scheduling

Schedule description-suggestion generation through Heratio's task scheduler, or run on demand:

# Generate for empty records
php artisan ahg:ai-suggest-description --empty-only --limit=100

# Prefer records with OCR text
php artisan ahg:ai-suggest-description --with-ocr --limit=200

Best Practices

Spellcheck

About Spellcheck

Check spelling and grammar in metadata fields to improve data quality.

Using Spellcheck

From the Command Line

# Check a specific record
php artisan ahg:ai-spellcheck --object=12345

# Check all records in a repository
php artisan ahg:ai-spellcheck --repository=5 --limit=100

# Check all records
php artisan ahg:ai-spellcheck --all --limit=100

# Specify the i18n culture
php artisan ahg:ai-spellcheck --all --culture=en

# Preview what would be checked
php artisan ahg:ai-spellcheck --all --dry-run

Spellcheck Options

• SPELLCHECK OPTIONS
• --object Check specific object ID
• --repository Check all in repository ID
• --all Check all objects
• --language Language code (default: en_US)
• --limit Maximum records to check
• --dry-run Preview without making changes

Spellcheck Results

• SPELLCHECK OUTPUT
• Checked 50 objects (lang: en)
• Object 12345: 3 issues
• Object 12346: 0 issues
• Object 12347: 5 issues
• Done: 50 checked, 12 with issues

Handwriting Text Recognition (HTR)

About HTR

Extract text from handwritten documents using AI-powered recognition with zone detection.

How HTR Works

HTR Recognition Modes

CLI Commands Reference

Installation & Setup

# Install AI database tables (idempotent)
php artisan ahg:ai-install

# Parse and count statements without executing
php artisan ahg:ai-install --dry-run

NER Commands

# Extract entities from all matching records
php artisan ahg:ai-ner

# Only objects with no entities extracted yet
php artisan ahg:ai-ner --unprocessed --limit=100

# Read descriptions in a specific culture
php artisan ahg:ai-ner --culture=en --limit=50

# Preview (dry run)
php artisan ahg:ai-ner --dry-run

Training Data Sync

# Export pending corrections to a JSONL training file (default action)
php artisan ahg:ai-ner-sync --export

# Export to a specific path
php artisan ahg:ai-ner-sync --export --out=storage/app/ner-training/corrections.jsonl

# View correction statistics
php artisan ahg:ai-ner-sync --stats

Note: Pushing corrections to a central training server (--retrain) is not yet wired (see #1268). Export + stats work today.

Pending Queue Processing

# Process pending NER extractions from the queue
php artisan ahg:ai-process-pending --limit=50

# Preview what would be processed (dry run)
php artisan ahg:ai-process-pending --dry-run

Note: --task-type currently supports only ner. Auto-triggered NER jobs from document uploads are queued and drained by this command (or by the standard Heratio queue worker).

Translation Commands

# Translate a single record into Afrikaans
php artisan ahg:ai-translate --to=af --object=12345

# Translate a repository's records
php artisan ahg:ai-translate --to=af --repository=5 --limit=50

# Overwrite existing target-culture text instead of skipping
php artisan ahg:ai-translate --to=af --object=12345 --overwrite

Summarization Commands

# Summarize a single record
php artisan ahg:ai-summarize --object=12345

# Summarize records whose target field is empty
php artisan ahg:ai-summarize --all-empty --limit=50

Spellcheck Commands

# Check a single record
php artisan ahg:ai-spellcheck --object=12345

# Check all records with description text
php artisan ahg:ai-spellcheck --all --limit=100

Description Suggestion Commands

# Generate a suggestion for a single record
php artisan ahg:ai-suggest-description --object=12345

# Process records with an empty scope_and_content
php artisan ahg:ai-suggest-description --empty-only --limit=50

# Prefer objects that have OCR text
php artisan ahg:ai-suggest-description --with-ocr --limit=100

# Use a specific prompt template and LLM config
php artisan ahg:ai-suggest-description --template=2 --llm-config=1 --limit=20

# Preview what would be processed
php artisan ahg:ai-suggest-description --empty-only --dry-run

NER Review Workflow

Complete Workflow

• NER REVIEW WORKFLOW
• 1. EXTRACTION
• Run extraction via UI or CLI
• -> Entities stored with 'pending' status
• 2. REVIEW
• Open NER Review Dashboard
• -> Select object to review
• -> Edit entity values/types if needed
• -> Choose action for each entity
• 3. SAVE DECISIONS
• Click "Save All Decisions"
• -> Entities processed in batches
• -> Access points created/linked
• 4. TRAINING FEEDBACK
• Corrections tracked for model improvement
• -> Run ahg:ai-ner-sync --export to export training data

Entity Linking Results

Training Data Export

Correction Types Tracked

Export Training Data

# View correction statistics
php artisan ahg:ai-ner-sync --stats

# Output:
# value_edit: 45 total, 20 exported, 25 pending
# type_change: 12 total, 8 exported, 4 pending
# rejected: 30 total, 25 exported, 5 pending

# Export to a specific file
php artisan ahg:ai-ner-sync --export --out=storage/app/ner-training/corrections.jsonl

# Export pending corrections (default action)
php artisan ahg:ai-ner-sync --export

AHG Central Configuration

Training data sync requires AHG Central integration. Configure it at:

Admin > AHG Settings > AHG Central

You can test the connection before saving to verify your credentials.

Best Practices

NER Best Practices

Translation Best Practices

Summarization Best Practices

Troubleshooting

Common Issues

Error Messages

Error Messages

• "No text content found"
• -> Record has no title, scope, or extractable PDF text
• "Language package not installed"
• -> Install the X->Y language pair in the Argos backend
• "Summarizer service not available"
• -> Check AI API is running and accessible
• "NER is disabled in settings"
• -> Enable in ahg_ai_settings table (feature='ner', key='enabled')
• "LLM provider not available"
• -> Check Ollama: curl http://localhost:11434/api/tags
• -> Or configure OpenAI/Anthropic API keys
• "No LLM configuration found"
• -> Run database migration to create default configs
• -> Or add config in ahg_llm_config table
• "Suggestion requires review"
• -> Suggestions are pending - approve via Review Dashboard

Checking Service Health

# Check AI API health
curl http://localhost:5004/ai/v1/health

# Expected response:
# {"status": "healthy", "services": {"ner": true, "summarizer": true, "translate": true}}

# Check Ollama health (for LLM suggestions)
curl http://localhost:11434/api/tags

# Expected response:
# {"models": [{"name": "llama3.1:8b", ...}]}

# Check LLM health via Heratio
curl https://your-site.com/ai/llm/health

Configuration

Settings Table

LLM Configurations

Need Help?

Contact your system administrator if you experience issues.

Part of the Heratio AHG Framework