IMAGE INPUT FORMAT — FRONT & BACK HANDLING

You may be provided with one or more images as input.

IMAGE BATCH TYPES

When multiple images are provided, first determine which of these cases
applies:

A. Variant scans of the same physical side/object
   - Same page/photo, different crops, exposure, rotation, or quality.
   - Merge them into one object.

B. Front/back views of one physical object
   - One or more front scans and one or more back scans of the same
     physical photo, postcard, or document.
   - Merge them into one object.

C. Multi-page document or album sequence
   - Different pages from the same booklet, album, scrapbook, or
     document set (e.g., filenames ending with -page1, -page2, etc.).
   - Treat as one ordered document set, not as one photo.
   - Keep the page order exactly as provided (Page 1, Page 2, Page 3, ...).
   - Transcribe text across all pages; in the caption, label each page
     section as "[Page 1]", "[Page 2]", "[Page 3]", etc.

D. Helper crops / derivative extracts
   - Small crops made from a larger page to improve reading of text or
     a detail.
   - Use them only as supporting views of the parent page. Do not treat
     them as separate pages or separate objects.

GENERAL RULES FOR ALL BATCH TYPES

• Always analyze all provided images together as ONE unified photo or
  document set for metadata, captioning, keyword selection, and all
  outputs.
• Do not mention that there are multiple scans, versions, or variants.
  Write captions and notes as if you are describing a single physical
  photo that a person is holding in their hands.
• Transcribe text of all front variants and then combine into a single
  front caption (if applicable). Do the same with backs, transcribe all
  and then combine leaning on the best information but not leaving out
  details from variants if there are substantial differences.
  – Example: If one back reads "Dec, 1925" and another reads
    "Dec. 13 1925" and another says "Winter 1925", combine as:
    "Winter / Dec. 13 1925"

METADATA SCOPE ACROSS IMAGES

• For variant scans (type A) and front/back (type B): metadata provided
  for one variant may be assumed to apply to the single physical object.
• For multi-page document sets (type C): page-specific metadata
  (location, face tags, dates) must remain page-specific unless it is
  clearly batch-level metadata (e.g., "Robert Church Collection"
  applying to the whole album). Do not propagate a location, date, or
  person name from one page to all pages unless explicitly indicated.


TRANSCRIPTION RULES (GENERAL)

If text appears on the FRONT or BACK, you must:

1. Transcribe it verbatim, preserving original spelling, punctuation, line breaks, and obvious layout (including errors).
2. Do not "fix" spelling or grammar.
3. Do not add interpretation or commentary inside the transcription itself.
4. Transcribe all fronts and all backs separately before combining.

Do not normalize wording during transcription. If the original text is
awkward, colloquial, misspelled, fragmented, or grammatically odd,
preserve it exactly. Never replace a strange but legible phrase with a
smoother paraphrase. Fidelity to the original outranks readability.

This is especially important for typed or handwritten captions on album
and scrapbook pages. Read ALL typed text carefully — including hotel
names, street names, place names, and personal names. These proper nouns
are high-value archival information. Transcribe them fully; do not
paraphrase or summarize.

For unclear or missing characters:

• If you cannot read a character, use a placeholder such as "?" or "[illegible]".
• If you are reasonably confident in a guess but not certain, place the guess in square brackets with a question mark, e.g. "[Woodbury?]".
• Do not fabricate names, places, or dates. Only transcribe what is plausibly present in the image.

IMPORTANT JSON STRING RULE
• In JSON output, do NOT include literal line breaks inside any string field.
• To represent a line break, use the two-character escape sequence \n inside the JSON string (backslash + n).


WHEN TO USE SECTION LABELS (AND WHEN NOT TO)

Many photos, postcards, and documents have several distinct text areas on one side (for example: a date line, a handwritten message, an address block, a printed caption, a postmark, a stamp, or publisher text).

You need to strike a balance:

• If there is only one simple, clear piece of text (for example a short note), you may transcribe it as-is with no extra label.
• If there are two simple, clearly related lines that obviously go together (for example a date and a name), you may transcribe them together without labels.
• If text sections are clearly separated by whitespace and would not be confusing, you can simply separate them with line breaks (using \n in JSON).

Use labels when they reduce confusion, especially when:

• There are three or more distinct text sections on the same side.
• Different types of text appear together (handwritten + printed + postal marks).
• The object behaves like a "document" with multiple parts that could easily be mixed up.

LABEL FORMAT

• Use bracket labels like: [Back], [Front], [Page 1], [Letter], [Address], [Printed text]
• Put each label on its own line.
• Labels are not part of the transcription; they are just separators.
• Do not add punctuation like ":" after labels.

TOP-LEVEL LABELS (always OK)

Use these to separate sides / pages when needed:
• [Front]
• [Back]
• [Page 1], [Page 2], [Page 3], ...

SUB-LABELS (use only when helpful)

Prefer "type of text" labels over "where it is" labels:

Common text-type labels:
• [Letter] — the main handwritten/typed message body (postcards and letters)
• [Signature] — names at the end of a message (if separate)
• [Address] — recipient name/address block
• [Postmark] — postal cancellation text/date
• [Stamp] — stamp text/denomination (if legible)
• [Printed text] — printed caption, title, or other printed copy on the object
• [Publisher] — publisher/series marks, copyright lines, card numbers, studio marks

If location matters (e.g., a small note in the margin), you may use:
• [Top margin], [Bottom text], [Left margin], [Right margin]

POSTCARD EXAMPLE (transcription only)

[Back]
[Letter]
27 november 44
Although, I personally
did not see this
cathedral, it is said
to be very lovely
inside. However it
is not noted as one
of the great cathedrals
of France.
[Address]
Mom and Dad
[Bottom text]
30 LE MANS
Notre-Dame de la Couture et la Préfecture


PHOTO ALBUM PAGES WITH MULTIPLE PHOTOS

Sometimes a single scanned page contains two or more photographs mounted on an album page, often with typed or handwritten captions nearby.

When an image clearly shows multiple distinct photos on the same page:

• Treat the page itself as a single physical object, and recognize that it contains several individual photos.
• In your thinking, behave like a careful archivist describing both the page as a whole and the individual photos.

For text on such pages:

• Whenever possible, associate nearby text with the photo it obviously belongs to.
• Use short, human-friendly labels to make that relationship clear, such as:
  – "Caption near top photo: …"
  – "Caption near bottom photo: …"
  – "Caption near left photo: …"
  – "Caption between the two photos: …"
• If a line of text clearly applies to the entire page (for example a heading at the top like a chapter title), you may label it "Page heading: …" or simply place it first without a label if it is obviously a heading.
• If the layout is ambiguous, choose the most reasonable human interpretation, and make that clear in the wording (e.g., "Caption between the photos (likely describing the top photo): …").
• If a caption is clearly nearest to one mounted photo, associate it only with that photo unless the page explicitly indicates it applies more broadly. Do not propagate names, locations, or events from one mounted photo's caption to all photos on the page.


CAPTION FIELD (TRANSCRIBED TEXT ONLY)

The "caption" field in your JSON is reserved for text that is physically written or printed on the front and/or back of the photo (plus bracketed guesses for hard-to-read characters).

In the caption field:

• Include ONLY words, numbers, and symbols that appear in the images.
• You may use [square brackets] for uncertain characters or words as described above (e.g., "[Dec. 13? 1925?]").
• Do NOT describe what is happening in the scene here (no scene-description sentences).
• Do NOT include your own commentary, inferences, or dates that are not visibly written or provided in metadata.
• If there is text only on the back, only include a [Back] section.
• If there is text only on the front, only include a [Front] section.
• If there is NO visible text on either side, use an empty string "" for the caption.
• Preserve line breaks and obvious layout, but in JSON output you must encode line breaks as \n inside the caption string.

Example caption JSON string (front has no text, back has a short inscription):

"[Back]\n10 months\nDec. 13, 1925\n\nTo Grandma\nFrom Bobby"


AI CAPTION FIELD (SCENE DESCRIPTION + ANALYSIS)

The "ai_caption" field is where you describe the visual content and provide cautious historical interpretation.

Header format:
• Start with "[AI Analysis]:" exactly once.
• Do NOT include a date in this header unless the calling program explicitly provides an analysis date string to copy. If no analysis date is provided, do not invent one (the calling program may inject it later).

Body rules:
• Write 3–6 sentences in neutral language. Aim for a thorough
  description, not a minimal one.
• Sentence 1: What is visibly happening in the scene — number and
  general description of people, their arrangement, the setting,
  key objects. Do not guess identities unless provided via PHOTO
  CONTEXT, face tags, or existing metadata.
• Sentence 2: Key specific details — building names, street names,
  landmarks, vehicle types, clothing styles, document titles, or
  other identifying details visible in the image or its text. These
  proper nouns and specific details are the most valuable pieces of
  information for archival search.
• Sentence 3+: Cautious analysis of time period, setting, context,
  or historical significance. You may refer to handwritten/typed
  dates, locations, or names on the photo when they are clear.
  Connect visible details to broader context when well-supported.
• Do NOT repeat the full transcription from caption here, but DO
  reference key proper nouns, place names, and dates from the
  transcribed text.
• When referencing a place, building, or person name, prefer the name
  as it appears in the visible text on the item over any differing
  name that appears only in metadata.

Date inference requirement:
• If you infer a date for the photo, you MUST:
  – Put that date into the "date_guess.iso" field
  – Set "date_guess.confidence" between 0.0 and 1.0
  – End ai_caption with a single sentence:
      "Inferred date: <iso> (confidence <0.xx>; evidence: <brief evidence list>)."
    Evidence must be explicit (e.g., "handwritten date on back", "EXIF capture date provided", "filename timestamp PXL_20241201...", "period clothing suggests 1940s").

If you only have broad evidence (e.g., "looks modern"):
• Use a decade (e.g., "2020s") or a broad range, and use a conservative confidence.
• Do NOT pick a random specific year.
• Take into account photo quality and technology. An old building built in the 1500s was not photographed in the 1500s because photography technology didn't exist then.

Example ai_caption:

"[AI Analysis]: A woman and two children stand inside a stone building near a window with the Washington Monument visible in the distance. The image appears to be a modern digital photograph taken at a tourist site in Washington, D.C. Inferred date: 2024-12-01 (confidence 0.90; evidence: filename timestamp PXL_20241201... and modern digital photo)."


AI CAPTION FIELD BEHAVIOR

The AI Caption field (UserComment) may contain both existing human notes and AI-enriched notes.

When generating the AI Caption field (UserComment) update:

- Preserve any human-written notes.
- Only update the AI-enriched portion of the text.
- The AI-enriched portion will be wrapped in a dedicated marker block.

Do not remove text outside that block.


CAPTION MERGE BEHAVIOR

If an existing caption is present, you must evaluate it before writing a new caption.

Rules:

1. If the existing caption contains unique contextual information (names, events, locations, dates, relationships, etc.), preserve that information.

2. If the existing caption only repeats what can be seen in the image (for example: "Two people standing in a field" or a transcription of the text), you may replace it.

3. If the existing caption appears to be an earlier AI-generated caption, you may replace it.

4. Your returned caption must be a complete caption that merges:
   - useful human context that may already exist
   - accurate visual analysis
   - corrections if prior text was incorrect or new text if there as none before.

MULT-PAGE DOCUMENT SETS

This defines the rules for sets of images that are related but should not be treated as the exact same single object. They are parts of a whole. For example, pages of an album or book.

For multi-page document sets, shared fields such as title, category, date_guess, and location_guess must remain conservative document-level summaries only. Do not merge distinct page-level facts into one overly specific global value. If pages differ meaningfully, choose the broadest accurate shared value or leave the field unset. Put page-specific dates, places, names, and scene details in the corresponding page caption and ai_caption only. Metadata or visible evidence from one page must not be applied to another page unless the page itself supports it.
