FactSet Earnings Insight PDF Extractor

Convert each FactSet Earnings Insight PDF into a dated snapshot of the same evolving earnings-estimate system:

PDF -> extract -> normalize -> validate -> derive simple metrics -> persist

Run the extractor

1. Confirm the input is a FactSet Earnings Insight PDF, directory, or Phase 1 manifest.
2. Run factset-earnings extract --input <path> --db <sqlite> --output-dir <dir> from this skill's Python environment.
3. Review the structured run summary and every warning. Treat SUCCESS as safe, SUCCESS_WITH_WARNINGS as safe only with field-level quality filters, PARTIAL as unsafe for whole-report ingestion, and FAILED as unusable.
4. Preserve generated JSON and SQLite rows as historical snapshots. Use --force only to safely replace the extraction for the same SHA256.

Use --dry-run to validate without writing JSON or SQLite. Use --manifest to attach a Phase 1 manifest record. Use --verbose for parser diagnostics.

Apply extraction rules

• Extract the canonical report date from PDF content. Use the filename date only as a cross-check.
• Locate sections by headings and chart titles, never fixed page numbers.
• Prefer selectable text. Use deterministic coordinate-aware chart parsing only when the chart is a raster image.
• Never guess or persist chart-geometry estimates. Store null, attach LOW provenance, and emit a warning when an explicit label-value pair is uncertain.
• Extract every explicit annual and quarterly Bottom-Up EPS label-value pair. Do not substitute a line endpoint or interpolate a chart value.
• Assign ESTIMATED, BLENDED, or ACTUAL only from explicit FactSet wording; otherwise use UNKNOWN.
• Store percentages as percentage points: 49.7% -> 49.7.
• Keep FactSet values separate from derived leadership spreads, valuation premiums, and margin changes.
• Normalize sectors to the canonical 11-sector GICS universe.
• Do not equate calendar-year EPS with forward-12-month EPS.
• Do not use the Target Price section's index price to derive Forward 12M EPS.
• Omit a leadership classification whenever either required calendar-year input is missing.

Preserve the Phase 3 contract

Use the stable v_* analytical views rather than JSON blobs or physical-table implementation details. Trace any analytical field through v_observation_provenance.

Schema 1.x databases must be rebuilt from the raw PDFs into a new schema 2.1 database. Do not migrate extracted v1 rows in place because the old database discarded field-level provenance and the full quarterly EPS curve.

Read schema.md when changing models, tables, validation, migration, or downstream interfaces. Read extraction-notes.md when adding or modifying a parser or OCR backend.

Scope boundary

Do not predict markets, score the earnings regime, make investment recommendations, allocate portfolios, build dashboards, or download PDFs. This is Phase 2 only.