Skip to content

Documents

LegalDoc

Bases: BaseModel

Unified base model for all legal documents processed by Contractex.

Every document that passes through a Contractex pipeline is represented as a LegalDoc (or a typed subclass). The doc_type field acts as the discriminator for routing and rendering logic.

Key design principles

  • Privacy first — privacy_profile is attached at construction and travels with the document through every pipeline stage. The PrivacyAwareLLMRouter reads it before any external API call.
  • Provenance everywhere — provenance maps every extracted field to a SourceSpan (chunk ID, page, char offsets, verbatim snippet).
  • Composable — extracted is a free-form dict so task outputs can be layered without subclassing. Typed subclasses (Contract) overlay strongly-typed fields on top.
  • Confidence aware — confidences mirrors extracted so routing and review queues can be applied field-by-field.

Attributes

doc_id: Stable UUID string assigned at construction if not supplied. doc_type: Primary document classification (DocType enum). jurisdiction: Jurisdiction code (e.g. "US-Federal", "CA-ON"). language: BCP-47 language code (default "en"). full_text: Full extracted plain text of the document. metadata: Provenance and processing metadata. privacy_profile: Privacy controls — routing, sensitivity, redaction state. Populated lazily; callers should always attach one before passing the document to a pipeline that calls an LLM. extracted: Free-form extraction results keyed by field name. confidences: Per-field confidence scores (mirrors extracted). provenance: Maps field names to SourceSpan records. tags: Arbitrary string tags for filtering and grouping.

content_hash: str | None property

SHA-256 of full_text for deduplication. None if no text.

effective_jurisdiction_tag: Any | None property

Return the JurisdictionTag for this document.

If jurisdiction_tag is already set, returns it directly. Otherwise parses the flat jurisdiction string on-the-fly. Returns None when neither field is populated.

authority_weight: float property

Normalised authority weight [0.01, 1.00] for retrieval scoring.

Returns 0.01 (AuthorityLevel.UNKNOWN) when no authority_profile is attached.

provenance_coverage: float property

Fraction of extracted fields that have a SourceSpan.

is_privacy_restricted: bool property

True if a PrivacyProfile is attached and routing is not 'any'.

set_field(field_name: str, value: Any, confidence: float = 0.0, *, chunk_id: str | None = None, source_url: str | None = None, page: int | None = None, char_start: int | None = None, char_end: int | None = None, snippet: str | None = None) -> None

Set an extracted field together with its confidence score and optional provenance span in a single call.

add_provenance(field_name: str, chunk_id: str, *, source_url: str | None = None, page: int | None = None, char_start: int | None = None, char_end: int | None = None, snippet: str | None = None) -> None

Record a SourceSpan for field_name.

merge(other: LegalDoc) -> LegalDoc

Return a new LegalDoc that merges other's extracted fields and provenance into self. Fields in other overwrite self on collision. Immutable identity fields (doc_id, doc_type, full_text) are taken from self.

LegalDocMetadata = LegalDocumentMetadata module-attribute

DocType

Bases: str, Enum

Primary document classification.

SourceSpan

Bases: BaseModel

Precise provenance reference for a single extracted field or text span.

Maps a piece of extracted information back to its exact origin so that consumers can verify, cite, or re-read the raw text.

Attributes:

Name Type Description
chunk_id str

Stable ID of the source chunk (assigned by ProvenanceTracker).
source_url str | None

Canonical URL of the source document.
page int | None

1-based page number in the source document.
char_start int | None

Character offset of the match start within the full document.
char_end int | None

Character offset of the match end.
snippet str | None

Short verbatim excerpt (≤ 300 chars) from the source.