femic.document_figures Module

The femic.document_figures module owns FEMIC-side artifact and provenance conventions for optional document-figure recovery workflows.

It intentionally does not import figrecover. This keeps the normal FEMIC runtime independent of optional PDF, computer-vision, and VLM dependencies.

Responsibilities

  • resolve the ignored runtime/document_ingestion/<corpus_id>/ layout;

  • create document-ingestion artifact directories;

  • compute SHA256 checksums for source, crop, and recovered-table artifacts;

  • validate provenance records before recovered values can be referenced;

  • encode review-status and downstream-use vocabularies; and

  • write JSON sidecars and JSONL review manifests.

Review Gate

Reviewed or accepted statuses require reviewer and timestamp provenance. This prevents raw recovered values from silently entering planning or model-input contracts.

API

Helpers for FEMIC document-figure recovery artifacts and provenance.

The functions in this module define FEMIC-side conventions for wrapping figrecover outputs. They intentionally do not import figrecover so the normal FEMIC runtime remains independent of optional figure-recovery tooling.

class femic.document_figures.DocumentFigureArtifactPaths(corpus_root, source_manifest_path, pages_dir, figure_candidates_path, crops_dir, calibration_dir, recovered_dir, overlays_dir, review_manifest_path, accepted_dir)[source]

Bases: object

Resolved artifact paths for one document-figure recovery corpus.

Parameters:

  • corpus_root (Path)

  • source_manifest_path (Path)

  • pages_dir (Path)

  • figure_candidates_path (Path)

  • crops_dir (Path)

  • calibration_dir (Path)

  • recovered_dir (Path)

  • overlays_dir (Path)

  • review_manifest_path (Path)

  • accepted_dir (Path)

accepted_dir: Path
as_dict()[source]

Return JSON-friendly string paths for this corpus layout.

Return type:

dict[str, str]

calibration_dir: Path
corpus_root: Path
crops_dir: Path
ensure_directories()[source]

Create the directory structure used by a figure-recovery corpus.

Return type:

None

figure_candidates_path: Path
overlays_dir: Path
pages_dir: Path
recovered_dir: Path
review_manifest_path: Path
source_manifest_path: Path
exception femic.document_figures.DocumentFigureProvenanceError[source]

Bases: ValueError

Raised when a document-figure provenance record is incomplete.

class femic.document_figures.DocumentFigureProvenanceRecord(corpus_id, document_title, page_number, series_name, visual_selection_rule, figrecover_version, extraction_method, output_path, output_checksum, review_status, downstream_use_classification, source_url=None, source_path=None, source_checksum=None, package_component=None, figure_id=None, table_id=None, crop_path=None, crop_checksum=None, calibration_spec=None, extraction_parameters=None, reviewer=None, review_timestamp=None, created_timestamp=None)[source]

Bases: object

Provenance for one recovered figure-derived table or series.

A record is intentionally compact enough to store in a JSONL review manifest while still capturing the minimum evidence FEMIC needs before a recovered value can be referenced by planning or model-input work.

Parameters:

  • corpus_id (str)

  • document_title (str)

  • page_number (int)

  • series_name (str)

  • visual_selection_rule (str)

  • figrecover_version (str)

  • extraction_method (str)

  • output_path (Path)

  • output_checksum (str)

  • review_status (str)

  • downstream_use_classification (str)

  • source_url (str | None)

  • source_path (Path | None)

  • source_checksum (str | None)

  • package_component (str | None)

  • figure_id (str | None)

  • table_id (str | None)

  • crop_path (Path | None)

  • crop_checksum (str | None)

  • calibration_spec (dict[str, Any] | None)

  • extraction_parameters (dict[str, Any] | None)

  • reviewer (str | None)

  • review_timestamp (str | None)

  • created_timestamp (str | None)

as_dict()[source]

Return a JSON-serializable representation of the provenance record.

Return type:

dict[str, Any]

calibration_spec: dict[str, Any] | None = None
corpus_id: str
created_timestamp: str | None = None
crop_checksum: str | None = None
crop_path: Path | None = None
document_title: str
downstream_use_classification: str
extraction_method: str
extraction_parameters: dict[str, Any] | None = None
figrecover_version: str
figure_id: str | None = None
output_checksum: str
output_path: Path
package_component: str | None = None
page_number: int
review_status: str
review_timestamp: str | None = None
reviewer: str | None = None
series_name: str
source_checksum: str | None = None
source_path: Path | None = None
source_url: str | None = None
table_id: str | None = None
visual_selection_rule: str
femic.document_figures.append_document_figure_review_manifest_jsonl(record, path)[source]

Append one provenance record to a JSONL review manifest.

Parameters:
Return type:

Path

femic.document_figures.build_document_figure_artifact_paths(corpus_root)[source]

Resolve FEMIC’s standard artifact paths for a figure-recovery corpus.

Parameters:

corpus_root (str | Path)

Return type:

DocumentFigureArtifactPaths

femic.document_figures.build_document_figure_corpus_root(instance_root, corpus_id)[source]

Return the default ignored runtime root for a document-figure corpus.

Parameters:

  • instance_root (str | Path)

  • corpus_id (str)

Return type:

Path

femic.document_figures.compute_document_figure_file_sha256(path)[source]

Return the SHA256 checksum for a local document-figure artifact.

Parameters:

path (str | Path)

Return type:

str

femic.document_figures.current_document_figure_review_timestamp()[source]

Return a UTC ISO-8601 timestamp for human-review provenance.

Return type:

str

femic.document_figures.validate_document_figure_provenance(record)[source]

Validate FEMIC’s minimum provenance requirements for recovered figures.

Parameters:

record (DocumentFigureProvenanceRecord)

Return type:

None

femic.document_figures.write_document_figure_provenance_json(record, path)[source]

Write one provenance record as formatted JSON and return its path.

Parameters:
Return type:

Path