@abyss-project/tools 1.0.5 → 1.2.0

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;
+}