@abyss-project/tools 1.0.5 → 1.1.1

package/src/types/interface/models/extraction-fetched-provenance.dto.test.ts

@@ -0,0 +1,193 @@
+// Type-level compile test — no jest runner in this package.
+// Verifies the FETCHED-extraction DTO (the GET extraction response / IExtraction)
+// surfaces the additive V2-P1 provenance + manifest fields type-safely, while
+// staying backward-compatible for old readers of value+confidence.
+// Run: npx tsc --noEmit (from packages/abyss_tools_core).
+
+import { ProviderKind, InterpreterKind, CombineStrategy } from '../../enum';
+import type { IExtraction } from './extraction.dto';
+import type { IFieldValue, IExecutionManifest, IGlobalConfidence } from './extraction-plan.dto';
+import type { IGetExtractionData } from '../api/responses/extraction.response';
+
+// A fully-populated plan-path field value (the IFieldValue superset).
+const fv: IFieldValue = {
+  value: 120,
+  confidence: 0.95,
+  chosen: {
+    provider: ProviderKind.TEXT,
+    interpreter: InterpreterKind.ALGORITHMIC,
+    providerId: 'pdf-auto',
+    interpreterId: 'algo-v1',
+  },
+  sources: [
+    {
+      mode: {
+        provider: ProviderKind.TEXT,
+        interpreter: InterpreterKind.ALGORITHMIC,
+        providerId: 'pdf-auto',
+        interpreterId: 'algo-v1',
+      },
+      value: 120,
+      confidence: 0.95,
+      signals: [],
+    },
+  ],
+  agreement: { agreed: false, distinctValues: 1 },
+  signals: [],
+};
+
+// A field value carrying NON-EMPTY signals — exercises every variant of the
+// ISignal discriminated union so a future drift between the SDK union and the
+// backend `Signal` shape (e.g. re-adding the invented `score` field, or
+// dropping `check`/`passed`/`agreed`/`modes`) fails compilation here.
+const fvWithSignals: IFieldValue = {
+  value: 'FR7630001007941234567890185',
+  confidence: 0.98,
+  chosen: {
+    provider: ProviderKind.TEXT,
+    interpreter: InterpreterKind.ALGORITHMIC,
+    providerId: 'pdf-auto',
+    interpreterId: 'algo-v1',
+  },
+  sources: [
+    {
+      mode: {
+        provider: ProviderKind.TEXT,
+        interpreter: InterpreterKind.ALGORITHMIC,
+        providerId: 'pdf-auto',
+        interpreterId: 'algo-v1',
+      },
+      value: 'FR7630001007941234567890185',
+      confidence: 0.98,
+      signals: [
+        { kind: 'format', check: 'iban_mod97', passed: true, weight: 0.2 },
+        { kind: 'anchor', detail: "matched near 'IBAN' label", weight: 0.1 },
+      ],
+    },
+  ],
+  agreement: { agreed: true, distinctValues: 1 },
+  signals: [
+    { kind: 'format', check: 'iban_mod97', passed: true, weight: 0.2 },
+    { kind: 'coherence', check: 'balance_reconciliation', passed: true, weight: 0.3 },
+    { kind: 'agreement', agreed: true, modes: 2, weight: 0.1 },
+  ],
+};
+void fvWithSignals;
+
+// A CONSUMER narrows the ISignal union by `kind` and reads the discriminant
+// fields that actually exist on the wire — type-safe, no cast.
+for (const sig of fvWithSignals.signals) {
+  if (sig.kind === 'format' || sig.kind === 'coherence') {
+    const _check: string = sig.check;
+    const _passed: boolean = sig.passed;
+    void _check; void _passed;
+  } else if (sig.kind === 'anchor') {
+    const _detail: string = sig.detail;
+    void _detail;
+  } else {
+    const _agreed: boolean = sig.agreed;
+    const _modes: number = sig.modes;
+    void _agreed; void _modes;
+  }
+}
+
+// Mirrors the persisted backend ExecutionManifest shape (resolvedPlan + combine
+// + passes + createdAt) — exactly what GET /extractions/:id surfaces via toJSON().
+const manifest: IExecutionManifest = {
+  resolvedPlan: {
+    stages: [
+      { runParallel: false, passes: [{ providerId: 'pdf-auto', interpreterId: 'algo-v1' }] },
+    ],
+    combine: CombineStrategy.MAX_CONFIDENCE,
+  },
+  combine: CombineStrategy.MAX_CONFIDENCE,
+  passes: [
+    { providerId: 'pdf-auto', providerVersion: '1.0.0', interpreterId: 'algo-v1', interpreterVersion: '1.0.0' },
+  ],
+  createdAt: '2026-06-28T00:00:00.000Z',
+};
+
+// Mirrors the persisted backend GlobalConfidence shape (stats + method +
+// aggregation + perPass + lowestFields).
+const globalConfidence: IGlobalConfidence = {
+  stats: {
+    overall: 0.95,
+    mean: 0.95,
+    highest: 0.95,
+    lowest: 0.95,
+    median: 0.95,
+    belowThreshold: { threshold: 0.7, count: 0 },
+    fieldCount: 1,
+  },
+  method: CombineStrategy.MAX_CONFIDENCE,
+  aggregation: 'weighted-by-field-importance',
+  perPass: [
+    {
+      mode: {
+        provider: ProviderKind.TEXT,
+        interpreter: InterpreterKind.ALGORITHMIC,
+        providerId: 'pdf-auto',
+        interpreterId: 'algo-v1',
+      },
+      confidence: 0.95,
+      fieldsContributed: 1,
+      ocrPageCount: 0,
+    },
+  ],
+  lowestFields: [{ fieldKey: 'totalTtc', confidence: 0.95 }],
+};
+
+// The fetched-extraction model carries provenance fieldsJson + manifest +
+// globalConfidence + usedOcr/ocrPageCount type-safely.
+const fetched: Partial<IExtraction> = {
+  fieldsJson: { totalTtc: fv },
+  executionManifest: manifest,
+  globalConfidence,
+  usedOcr: true,
+  ocrPageCount: 3,
+};
+void fetched;
+
+// A CONSUMER reading the chosen impl id + sources off the fetched field value —
+// no cast needed (this is the whole point of the surfacing fix).
+const totalTtc = (fetched.fieldsJson ?? {}).totalTtc;
+if (totalTtc) {
+  const _chosenId: string = totalTtc.chosen.interpreterId;
+  const _sourceCount: number = totalTtc.sources.length;
+  void _chosenId; void _sourceCount;
+}
+
+// Backward-compat: an old reader that only knows value+confidence still works.
+const _legacyRead: { value: unknown; confidence: number } | undefined =
+  (fetched.fieldsJson ?? {}).totalTtc;
+void _legacyRead;
+
+// The GET extraction response data exposes the same superset under `fields`
+// AND inherits manifest + globalConfidence from IExtraction.
+const getData: Partial<IGetExtractionData> = {
+  fields: { totalTtc: fv },
+  executionManifest: manifest,
+  globalConfidence,
+};
+void getData;
+
+// usedOcr/ocrPageCount remain readable as before.
+const _usedOcr: boolean | undefined = fetched.usedOcr;
+const _ocrPages: number | undefined = fetched.ocrPageCount;
+void _usedOcr; void _ocrPages;
+
+// A CONSUMER reads the manifest + globalConfidence fields that the backend
+// actually persists/surfaces (createdAt — NOT resolvedAt — and the stats block),
+// type-safely off the fetched extraction.
+if (fetched.executionManifest) {
+  const _createdAt: string = fetched.executionManifest.createdAt;
+  const _passCount: number = fetched.executionManifest.passes.length;
+  void _createdAt; void _passCount;
+}
+if (fetched.globalConfidence) {
+  const _overall: number = fetched.globalConfidence.stats.overall;
+  const _agg: 'weighted-by-field-importance' = fetched.globalConfidence.aggregation;
+  void _overall; void _agg;
+}
+
+export {};

package/src/types/interface/models/extraction-plan.dto.test.ts

@@ -0,0 +1,47 @@
+// Type-level compile test — no jest runner in this package.
+// Each block verifies that the SDK types compile correctly.
+// Run: npx tsc --noEmit (from packages/abyss_tools_core).
+
+import { ProviderKind, InterpreterKind, CombineStrategy } from '../../enum';
+import type { IExtractionPlan, IFieldValue, IExtractModesData, IPositionedToken } from './extraction-plan.dto';
+
+// Verify enum string values match the api side.
+const _pk: string = ProviderKind.TEXT; // 'text'
+const _ik: string = InterpreterKind.TEMPLATE; // 'template'
+const _cs: string = CombineStrategy.MAX_CONFIDENCE; // 'maxConfidence'
+void _pk; void _ik; void _cs;
+
+// Verify IFieldValue is a structural superset of {value,confidence}.
+const fv: IFieldValue = {
+  value: 1,
+  confidence: 0.9,
+  chosen: {
+    provider: ProviderKind.TEXT,
+    interpreter: InterpreterKind.ALGORITHMIC,
+    providerId: 'pdf-text',
+    interpreterId: 'algo-v1',
+  },
+  sources: [],
+  signals: [],
+};
+// Must be assignable to the legacy shape without cast.
+const _legacy: { value: unknown; confidence: number } = fv;
+void _legacy;
+
+// Verify IExtractModesData typing compiles.
+const _modes: IExtractModesData = { providers: [], interpreters: [] };
+void _modes;
+
+// Verify IExtractionPlan typing compiles.
+const _plan: IExtractionPlan = {
+  stages: [{ runParallel: false, passes: [{ providerId: 'pdf-text', interpreterId: 'algo-v1' }] }],
+  combine: CombineStrategy.MAX_CONFIDENCE,
+};
+void _plan;
+
+// Verify IPositionedToken is { text, page, bbox{x,y,w,h}, conf? } (conf optional).
+const _tok: IPositionedToken = { text: 'IBAN', page: 1, bbox: { x: 1, y: 2, w: 3, h: 4 }, conf: 95 };
+const _tokNoConf: IPositionedToken = { text: 'x', page: 2, bbox: { x: 0, y: 0, w: 1, h: 1 } };
+void _tok; void _tokNoConf;
+
+export {};

package/src/types/interface/models/extraction-plan.dto.ts

@@ -0,0 +1,241 @@
+// ──────────────────────────────────────────────
+// Extraction Plan DTOs.
+// Mirror server-side plan.types.ts shapes. Use SDK enums for kinds.
+// IFieldValue is a structural superset of { value; confidence } so existing
+// consumers do not break.
+// ──────────────────────────────────────────────
+
+import { ProviderKind, CostTier } from '../../enum/provider-kind.enum';
+import { InterpreterKind } from '../../enum/interpreter-kind.enum';
+import { CombineStrategy } from '../../enum/combine-strategy.enum';
+
+// Re-export for consumers that import from this barrel.
+export { ProviderKind, CostTier, InterpreterKind, CombineStrategy };
+
+// ─── Plan building blocks ──────────────────────────────────────────────────
+
+/** Reference to the provider+interpreter pair that produced a field value. */
+export interface IModeRef {
+  provider: ProviderKind;
+  interpreter: InterpreterKind;
+  providerId: string;
+  interpreterId: string;
+}
+
+/** Fallback gate used between stages — the executor continues when not met. */
+export interface IFallbackGate {
+  /** Minimum confidence required to skip the next stage. */
+  minConfidence: number;
+  /**
+   * 'global' = global score; 'requiredFields' = min over required fields.
+   * Mirrors the backend FallbackGate.scope shape.
+   */
+  scope: 'global' | 'requiredFields';
+}
+
+/** A single provider+interpreter pass. */
+export interface IPass {
+  providerId: string;
+  interpreterId: string;
+  /** If set, forces the interpreter to this document type (skips detect()). */
+  documentType?: string;
+  /** For template interpreters. */
+  templateId?: string;
+}
+
+/** One stage — a group of passes run sequentially or in parallel. */
+export interface IStage {
+  passes: IPass[];
+  runParallel: boolean;
+  /** When present, executor checks this gate after the stage; if not met continues to the next stage. */
+  fallback?: IFallbackGate;
+}
+
+/** Top-level execution plan handed to the executor. */
+export interface IExtractionPlan {
+  stages: IStage[];
+  combine: CombineStrategy;
+}
+
+// ─── Confidence / provenance ───────────────────────────────────────────────
+
+/**
+ * An evidence signal contributing to a field's confidence score.
+ *
+ * Discriminated union mirroring the backend `Signal` (plan/plan.types.ts) shape
+ * VERBATIM so a consumer reading `IFieldValue.signals[i]` sees exactly what is
+ * persisted/surfaced on the wire:
+ *  - `format`/`coherence` carry `{ check, passed, weight }` (e.g. siret_luhn,
+ *    iban_mod97, ht_vat_ttc, actif_passif, balance_reconciliation);
+ *  - `anchor` carries `{ detail, weight }`;
+ *  - `agreement` carries `{ agreed, modes, weight }` and explains the
+ *    `IFieldValue.agreement` summary (`modes` = number of contributing sources).
+ */
+export type ISignal =
+  | { kind: 'format'; check: string; passed: boolean; weight: number }
+  | { kind: 'coherence'; check: string; passed: boolean; weight: number }
+  | { kind: 'anchor'; detail: string; weight: number }
+  | { kind: 'agreement'; agreed: boolean; modes: number; weight: number };
+
+/** One source contribution to a combined field value. */
+export interface IFieldSource {
+  mode: IModeRef;
+  value: unknown;
+  confidence: number;
+  signals: ISignal[];
+}
+
+/**
+ * Combined field value with full provenance.
+ * value + confidence are at the SAME path as today's ExtractedField
+ * (structural superset — backward-compatible).
+ */
+export interface IFieldValue {
+  value: unknown;
+  confidence: number;
+  chosen: IModeRef;
+  sources: IFieldSource[];
+  agreement?: {
+    agreed: boolean;
+    distinctValues: number;
+  };
+  signals: ISignal[];
+  provenanceTruncated?: boolean;
+}
+
+/** Per-field importance entry (mirrors field-importance.ts). */
+export interface IFieldImportance {
+  fieldKey: string;
+  weight: number;
+  required: boolean;
+}
+
+/**
+ * Confidence statistics over an extraction's fields.
+ * Mirrors the backend ConfidenceStats shape (plan/plan.types.ts) exactly so a
+ * consumer reading globalConfidence.stats off a fetched extraction is type-safe.
+ */
+export interface IConfidenceStats {
+  overall: number;
+  mean: number;
+  highest: number;
+  lowest: number;
+  median: number;
+  belowThreshold: { threshold: number; count: number };
+  fieldCount: number;
+}
+
+/**
+ * Per-pass contribution in the global confidence summary.
+ * Mirrors the backend PassContribution shape (plan/plan.types.ts).
+ */
+export interface IPassContribution {
+  mode: IModeRef;
+  confidence: number;
+  fieldsContributed: number;
+  ocrPageCount: number;
+}
+
+/**
+ * Global confidence summary for an extraction run.
+ * Mirrors the backend GlobalConfidence shape (plan/plan.types.ts) — the JSON
+ * persisted in extractions.globalConfidence and surfaced by GET /extractions/:id.
+ */
+export interface IGlobalConfidence {
+  stats: IConfidenceStats;
+  method: CombineStrategy;
+  aggregation: 'weighted-by-field-importance';
+  perPass: IPassContribution[];
+  lowestFields: { fieldKey: string; confidence: number }[];
+}
+
+// ─── Execution manifest ────────────────────────────────────────────────────
+
+/**
+ * A pass entry in the execution manifest.
+ * Mirrors the backend ManifestPass shape (plan/plan.types.ts).
+ */
+export interface IManifestPass {
+  providerId: string;
+  providerVersion: string;
+  interpreterId: string;
+  interpreterVersion: string;
+  /** Pinned template version id, when the pass used a template interpreter. */
+  templateVersionId?: string;
+  /** OCR provider engine + versions, when the pass used the OCR provider. */
+  ocrEngine?: string;
+  ocrEngineVersion?: string;
+  ocrLangpackVersion?: string;
+}
+
+/**
+ * Frozen manifest of the exact recipe used for an extraction run.
+ * Mirrors the backend ExecutionManifest shape (plan/plan.types.ts) — the JSON
+ * persisted in extractions.executionManifest and surfaced by GET /extractions/:id.
+ */
+export interface IExecutionManifest {
+  resolvedPlan: IExtractionPlan;
+  combine: CombineStrategy;
+  passes: IManifestPass[];
+  createdAt: string;
+}
+
+// ─── Plan presets ──────────────────────────────────────────────────────────
+
+/** A saved extraction plan preset (DB row + virtual system presets). */
+export interface IExtractionPlanPreset {
+  id: string;
+  name: string;
+  scope:
+    | { kind: 'user'; userId: string }
+    | { kind: 'org'; organizationId: string };
+  plan: IExtractionPlan;
+  isDefault: boolean;
+  system: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ─── Modes (capabilities endpoint) ────────────────────────────────────────
+
+/** Provider capability entry returned by GET /extract/modes. */
+export interface IProviderMode {
+  id: string;
+  kind: ProviderKind;
+  label: string;
+  cost: CostTier;
+  version: string;
+}
+
+/** Interpreter capability entry returned by GET /extract/modes. */
+export interface IInterpreterMode {
+  id: string;
+  kind: InterpreterKind;
+  label: string;
+  cost: CostTier;
+  version: string;
+  supports: string[];
+  accepts: ProviderKind[];
+}
+
+/** Shape of the data block returned by GET /extract/modes. */
+export interface IExtractModesData {
+  providers: IProviderMode[];
+  interpreters: IInterpreterMode[];
+}
+
+// ─── Positioned tokens (OCR word-bbox channel, V2-P2) ──────────────────────
+
+/**
+ * A single OCR word with its bounding box (mirrors backend PositionedToken).
+ * bbox is in image pixels at the OCR raster scale (origin top-left); a consumer
+ * normalizes to 0..1 of the page using the per-page pixel dimensions carried in
+ * the provider meta. `page` is 1-based. ADDITIVE — surfaced for V2-P3 spatial
+ * templates + auditable per-word confidence; existing consumers are unaffected.
+ */
+export interface IPositionedToken {
+  text: string;
+  page: number;
+  bbox: { x: number; y: number; w: number; h: number };
+  conf?: number;
+}

package/src/types/interface/models/extraction-spatial-template.dto.test.ts

@@ -0,0 +1,27 @@
+// Type-level compile test — no jest runner in this package.
+// Each block verifies that the SDK spatial-template DTO types compile correctly.
+// Run: npx tsc --noEmit (from packages/abyss_tools_core).
+
+import type {
+  ISpatialZone, ISpatialTemplateConfig, IExtractionTemplateVersionDto, ISpatialZoneExtractor,
+} from './extraction-spatial-template.dto';
+import { DocumentType } from '../../enum/document-type.enum';
+
+// A spatial zone + config type correctly (mirrors the backend schema).
+const zone: ISpatialZone = { fieldKey: 'totalTtc', page: 1, rect: { x: 0.6, y: 0.8, w: 0.3, h: 0.05 }, extractor: 'amount', amountLocale: 'fr' };
+const config: ISpatialTemplateConfig = { kind: 'spatial', documentType: DocumentType.INVOICE, zones: [zone] };
+// The fieldKey + kind discriminant are reachable.
+const _fieldKey: string = config.zones[0].fieldKey; // 'totalTtc'
+const _kind: 'spatial' = config.kind;
+void _fieldKey; void _kind;
+
+// Every extractor literal is assignable to the union.
+const _extractors: ISpatialZoneExtractor[] = ['raw', 'regex', 'date', 'amount', 'iban'];
+void _extractors;
+
+// A template version dto types (serialized dates, nullable comment).
+const v: IExtractionTemplateVersionDto = { id: 'v1', templateId: 't1', version: 1, templateJson: { kind: 'spatial' }, comment: null, createdAt: '2026-06-28T00:00:00.000Z' };
+const _version: number = v.version; // 1
+void _version;
+
+export {};

package/src/types/interface/models/extraction-spatial-template.dto.ts

@@ -0,0 +1,48 @@
+// packages/abyss_tools_core/src/types/interface/models/extraction-spatial-template.dto.ts
+//
+// Spatial (Karmen) template DTOs. Mirror the backend spatial-template.schema +
+// extraction-template-version shapes VERBATIM so the V2-P4 zone editor types its
+// CRUD payloads/responses. ADDITIVE — does not touch existing template DTOs.
+import { DocumentType } from '../../enum/document-type.enum';
+
+export type ISpatialZoneExtractor = 'raw' | 'regex' | 'date' | 'amount' | 'iban';
+
+/** A single zone: a normalized 0..1 rect on a page + how to coerce the tokens inside it. */
+export interface ISpatialZone {
+  fieldKey: string;
+  /** 1-based page number. */
+  page: number;
+  /** Normalized 0..1 of the page (origin top-left). */
+  rect: { x: number; y: number; w: number; h: number };
+  extractor: ISpatialZoneExtractor;
+  regex?: string;
+  captureGroup?: number;
+  amountLocale?: 'fr' | 'en';
+}
+
+/** The spatial config stored inside a template version's templateJson. */
+export interface ISpatialTemplateConfig {
+  kind: 'spatial';
+  documentType: DocumentType;
+  zones: ISpatialZone[];
+}
+
+/** A template version row (mirrors backend IExtractionTemplateVersion, dates serialized). */
+export interface IExtractionTemplateVersionDto {
+  id: string;
+  templateId: string;
+  version: number;
+  templateJson: Record<string, unknown>;
+  comment: string | null;
+  createdAt: string;
+}
+
+/** A template list item (the spatial-aware list the editor renders). */
+export interface ISpatialTemplateListItem {
+  id: string;
+  name: string;
+  description: string | null;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}