Complete Tutorial Guide

1. Getting Started

Accessing the App

Open your web browser and navigate to cataloging.098484.xyz. The app works best in modern browsers (Chrome, Firefox, Safari, Edge).

First Visit

When you open the app for the first time, you'll see a welcome dialog:

This dialog tells you three important things:

1. This is a PWA — All information is stored locally on your device
2. It's experimental — Frequent updates and changes may occur without notice
3. Use at your own risk — Always verify AI-generated headings against professional standards

Click "I Understand" to dismiss the dialog.

Home Page

After dismissing the welcome dialog, you'll see the home page with three action cards:

Installing the App (PWA)

The Cataloging Assistant is a Progressive Web App, which means you can install it on your device and use it like a native app — with its own window, icon, and faster loading.

2. Configuring Settings

Before you can use the Wizard, you must configure an AI model provider. Navigate to Settings by clicking "Open Settings" on the home page or "Settings" in the navigation bar.

Selecting a Provider

Click the "Provider" dropdown to see available cloud AI providers:

Adding Your API Key

After selecting a provider:

1. Enter your API key in the "Enter API key" field
2. Optionally give it a label (e.g., "Tutorial Key", "Work Key")
3. Click "Add" to save the key

Selecting a Model

With a provider and API key configured, select the specific AI model:

After selecting a model, your configuration is complete:

Testing the Connection

Click "Test Connection" to verify your configuration.

Common errors: 401 (invalid API key), 429 (quota exceeded), Model not found.

Custom Endpoints

If you're running a self-hosted model or using an OpenAI-compatible API, switch to the "Custom Endpoints" tab:

1. Provider Label (optional) — give your endpoint a friendly name
2. Base URL — enter the full base URL (e.g., http://localhost:11434/v1 for Ollama)
3. Fetch Models — click to discover available models
4. Model ID — select or type the model
5. API Key (optional) — add if your endpoint requires auth
6. Test Connection — verify everything works

System Prompt Customization

Scroll down on the Settings page to find the System Prompt section:

The default system prompt includes 13 LCSH selection rules that guide the AI. Edit the text directly to add institution-specific rules, or click "Reset to Default" to restore.

3. Using the Wizard: Complete Walkthrough

The Wizard is the core feature. Below is a complete walkthrough using "The Great Gatsby" by F. Scott Fitzgerald as our example.

Step 1: Enter Bibliographic Information

Navigate to the Wizard by clicking "Start Wizard" on the home page or "Wizard" in the nav bar.

*Title is required unless you upload an image.

Example: Filling Out the Form

Generating Suggestions

Click "Generate LCSH Suggestions". You'll see a loading spinner:

What happens behind the scenes:

1. Your bibliographic data is sent to the configured AI model
2. The AI generates subject heading suggestions with reasoning
3. Each suggestion is validated against the Library of Congress (LCSH + LCNAF)
4. Similarity scores are calculated using Levenshtein distance
5. Results automatically advance to Step 2

Processing typically takes 10–30 seconds.

Step 2: Reviewing Validated Suggestions

The Subject Analysis shows an AI-generated expert analysis of the work's themes. The Validation Summary shows overall quality.

Understanding Individual Terms

For each term, you'll see:

1. Status Icon — green checkmark (exact match) or yellow triangle (closest match)
2. Term Name — the suggested LCSH heading
3. Source Badge — LCSH or LCNAF
4. Similarity Score — color-coded percentage
5. AI Reasoning — why the AI chose this heading
6. Best Match — the official LOC heading
7. View on LOC — direct link to the authority record

Terms with an AI Additional badge were inferred from the work's themes beyond what was explicitly in the input.

Complete Results for "The Great Gatsby"

Step 3: Final Recommendations & MARC Records

Example MARC Records Generated

650 _0 $a American fiction $y 20th century
650 _0 $a Long Island (N.Y.) $x Fiction
650 _0 $a Social classes $x Fiction
650 _0 $a Wealth $x Fiction
650 _0 $a Nineteen twenties
650 _0 $a American Dream in literature
650 _0 $a Aristocracy (Social class) $x Fiction
650 _0 $a American Dream

Exporting Your Results

4. Managing Conversation History

History Table

The table shows date, title, author, term count, and action icons (view, export CSV, delete). Bulk actions at the top right: "Export All" and "Clear All".

Session Detail View

Click the eye icon on any session to open the detail dialog:

5. Understanding Validation Scores

The app uses Levenshtein distance-based similarity scoring to validate AI suggestions against official LOC headings.

Dual Authority Validation

Each term is validated against two Library of Congress databases: LCSH (topical, geographic, genre/form subjects) and LCNAF (personal and corporate names).

6. Working with MARC Records

Understanding the Tags

Reading the MARC Format

Example: 650 _0 $a American fiction $y 20th century

• 650 — MARC field tag (topical subject)
• _0 — Indicators (second indicator 0 = LCSH)
• $a — Main heading subfield
• $y — Chronological subdivision
• $x — General subdivision

Using MARC Records in Your Workflow

1. Copy to ILS — Use "Copy" or "Copy All MARC" to copy records, then paste into your ILS MARC editor
2. Export to CSV — Download CSV files for batch import
3. Review and Edit — Always review generated MARC records before adding to official catalog records

7. Tips & Best Practices

For Better AI Suggestions

1. Provide detailed abstracts — The abstract is the most impactful field.
2. Include table of contents — Chapter headings help the AI understand structure.
3. Upload images — Book covers often contain subject info not in text. (Requires vision-capable model.)
4. Be specific in notes — Mention audience, geographic focus, time period.
5. Use capable models — Larger models (Gemini 2.5 Pro, GPT-4o) produce better results.

For Better Validation

1. Check alternatives — When a suggestion has moderate similarity, expand the alternatives.
2. Verify LOC links — Click "View on LOC" to see the full authority record.
3. Review AI reasoning — The justification explains each heading choice.
4. Consider source badges — LCSH (650) for topics; LCNAF (600/610) for names.

For Your Workflow

1. Save sessions — Always click "Save & View History" to preserve your work.
2. Export regularly — Download CSV files as backups.
3. Customize the prompt — Tailor LCSH rules to your institution.
4. Test multiple providers — Different AI models produce different results.
5. Always verify — AI assists but doesn't replace professional judgment.

8. Troubleshooting