Reference Implementation: Calendar Mapping Rules¶

What it is¶

This document defines the logic and formatting rules for mapping extracted metadata from LLMs to specific fields in a digital calendar (e.g., Google Calendar or Proton Calendar). It serves as a data contract for automation workflows.

What problem it solves¶

LLM extraction outputs are often unstructured or follow inconsistent naming conventions. This reference implementation ensures that data is sanitized, formatted, and enriched correctly before being pushed to the calendar API, preventing "trash" data from cluttering the user's schedule.

Where it fits in the stack¶

This logic resides in the Data Transformation step of a workflow. It acts as the bridge between the AI Service (LLM extraction) and the Productivity API (Calendar service), typically implemented within an orchestration tool like n8n.

Mapping Table¶

How extracted LLM fields map to Google Calendar event fields.

Extracted Field	Calendar Field	Logic / Format
`event_name`	Summary	Title Case
`start_date`	Start Time	ISO8601 string
`end_date`	End Time	If null, set to `start_date` + 1 hour
`location`	Location	Plain Text
`reasoning`	Description	Prepend "Auto-generated by AI:"
`doc_id`	Description	Append direct link to Paperless-ngx

Typical use cases¶

Automatic Bill Reminders: Mapping the due date of a scanned PDF bill to a calendar reminder.
Appointment Scheduling: Extracting dates from confirmation emails and creating events.
School Schedule Integration: Processing school newsletters to add holidays and parent-teacher meetings to the family calendar.

Strengths¶

Consistency: Ensures every AI-generated event follows the same structural pattern.
Enrichment: Adds value by linking back to the source document in Paperless-ngx.
Flexibility: The logic can be easily extended to support additional fields like "reminders" or "visibility".

Limitations¶

Timezone Sensitivity: Requires the extraction pipeline to be aware of the user's local timezone to avoid off-by-one errors.
Static Logic: Complex "recurring" events are difficult to map via simple table-based rules and may require more advanced LLM prompting.
API Dependencies: Limited by the target calendar's API capabilities (e.g., HTML support in descriptions).

When to use it¶

When automating the ingestion of documents that contain actionable dates.
When building a "Family Daily Briefing" system that relies on structured calendar data.
When you need a clear audit trail between a calendar event and its source document.

When not to use it¶

For manual event creation where the user provides all fields directly.
For extremely high-volume synchronization tasks where per-event enrichment might hit API rate limits.
If the source data is already in a structured format (like iCal feeds).

Google Calendar: The primary target for these mapping rules.
Paperless-ngx: The source of documents and doc_id references.
n8n: The orchestration engine that implements these rules.
Date Extraction Prompt: The LLM prompt used to generate the input for these rules.
HITL UI Design: The interface for reviewing these mappings before they are committed.
Vikunja: Alternative target for task-based "events".
Habitica: For mapping recurring habits or chores derived from documents.

Sources / references¶

Contribution Metadata¶

Last reviewed: 2026-05-11
Confidence: high