Extract source-backed product facts

Product Fact Provenance extracts product fields from supplied documents and attaches evidence to each value. A fact contains a field name, an optional value, and a list of source IDs with exact supporting quotes. The example uses Instructor for extraction and Pydantic for subsequent local verification.

Verification checks whether each cited document exists as text, whether the quote occurs in that document, and whether the extracted value appears in the quote after case and whitespace normalization. These are conservative text checks, performed without a second model call. A verified label reflects those checks rather than independent confirmation of the underlying document's truth.

Use this pattern when product facts need traceable support from supplier text, OCR output, or other supplied source documents. The example sources include a material statement, a capacity statement, and a general travel-oriented description. Their stable source identifiers keep evidence attached to the document from which it came.

Keep unsupported fields visible for review. The extraction instructions require null and an empty evidence list when the supplied sources do not support a value. The local check relies on the normalized value occurring inside a quoted passage, so it is suited to explicitly stated values rather than facts that require broad interpretation or external research.

The extract_product_facts function accepts a mapping of source identifiers to document strings. It serializes that mapping into the user message and also supplies it through validation context. The returned ProductExtraction contains a list of ProductFact records.

Each Evidence record exposes a computed verified flag, backed by a private attribute initially set to false. Each fact exposes computed status and confidence fields, initially unverified and zero. These values are derived by local validation rather than accepted as generated confidence claims.

When sources are not a mapping, or a fact lacks a value or evidence, the validator returns without promoting it. Otherwise, it checks every evidence item. Confidence becomes the fraction of evidence items that passed. The fact becomes verified only when all supplied evidence items pass; partial support leaves its status unverified.

Normalization case-folds text and collapses whitespace. The quote itself must still occur exactly in the original source document, while the value-in-quote comparison uses normalized text. This separates faithful quotation from conservative matching of a field value.

Instructor creates the structured extraction request with ProductExtraction as the response model. The example selects this provider:

    client = instructor.from_provider("openai/gpt-5-nano")

Pydantic supplies models, private attributes, computed fields, and the after-model validator. The executable entry point prints the resulting facts as indented JSON for inspection.