retab 0.0.36__py3-none-any.whl → 0.0.37__py3-none-any.whl

retab/types/evaluations/iterations.py

@@ -0,0 +1,112 @@
+import copy
+import datetime
+import json
+from typing import Any, Optional, Self
+
+import nanoid  # type: ignore
+from pydantic import BaseModel, Field, computed_field, model_validator
+
+from ..._utils.json_schema import clean_schema
+from ..._utils.mime import generate_blake2b_hash_from_string
+from ..inference_settings import InferenceSettings
+from ..metrics import MetricResult
+from ..predictions import PredictionData
+
+
+class Iteration(BaseModel):
+    id: str = Field(default_factory=lambda: "eval_iter_" + nanoid.generate())
+    updated_at: datetime.datetime = Field(
+        default_factory=lambda: datetime.datetime.now(tz=datetime.timezone.utc),
+        description="The last update date of inference settings or json schema",
+    )
+    inference_settings: InferenceSettings
+    json_schema: dict[str, Any]
+    predictions: dict[str, PredictionData] = Field(default_factory=dict, description="The predictions of the iteration for all the documents")
+    metric_results: Optional[MetricResult] = Field(default=None, description="The metric results of the iteration")
+
+    @computed_field  # type: ignore
+    @property
+    def schema_data_id(self) -> str:
+        """Returns the SHA1 hash of the schema data, ignoring all prompt/description/default fields.
+
+        Returns:
+            str: A SHA1 hash string representing the schema data version.
+        """
+        return "sch_data_id_" + generate_blake2b_hash_from_string(
+            json.dumps(
+                clean_schema(
+                    copy.deepcopy(self.json_schema),
+                    remove_custom_fields=True,
+                    fields_to_remove=["description", "default", "title", "required", "examples", "deprecated", "readOnly", "writeOnly"],
+                ),
+                sort_keys=True,
+            ).strip()
+        )
+
+    # This is a computed field, it is exposed when serializing the object
+    @computed_field  # type: ignore
+    @property
+    def schema_id(self) -> str:
+        """Returns the SHA1 hash of the complete schema.
+
+        Returns:
+            str: A SHA1 hash string representing the complete schema version.
+        """
+        return "sch_id_" + generate_blake2b_hash_from_string(json.dumps(self.json_schema, sort_keys=True).strip())
+
+
+class CreateIterationRequest(BaseModel):
+    """
+    Request model for performing a new iteration with custom inference settings and optional JSON schema.
+    """
+
+    inference_settings: InferenceSettings
+    json_schema: Optional[dict[str, Any]] = None
+    from_iteration_id: Optional[str] = Field(
+        default=None,
+        description="The ID of the iteration to copy the JSON Schema from.",
+    )
+
+    # validate that exactly one of from_iteration_id or json_schema is provided
+    @model_validator(mode="after")
+    def validate_one_of_from_iteration_id_or_json_schema(self) -> Self:
+        if (self.from_iteration_id is None) ^ (self.json_schema is None):
+            raise ValueError("Exactly one of from_iteration_id or json_schema must be provided")
+        return self
+
+
+class PatchIterationRequest(BaseModel):
+    inference_settings: Optional[InferenceSettings] = Field(default=None, description="The new inference settings of the iteration")
+    json_schema: Optional[dict[str, Any]] = Field(default=None, description="The new json schema of the iteration")
+
+
+class ProcessIterationRequest(BaseModel):
+    """Request model for processing an iteration - running extractions on documents."""
+
+    document_ids: Optional[list[str]] = Field(default=None, description="Specific document IDs to process. If None, all documents will be processed.")
+    only_outdated: bool = Field(default=True, description="Only process documents that need updates (prediction.updated_at is None or older than iteration.updated_at)")
+
+
+class DocumentStatus(BaseModel):
+    """Status of a document within an iteration."""
+
+    document_id: str
+    filename: str
+    needs_update: bool = Field(description="True if prediction is missing or outdated")
+    has_prediction: bool = Field(description="True if any prediction exists")
+    prediction_updated_at: Optional[datetime.datetime] = Field(description="When the prediction was last updated")
+    iteration_updated_at: datetime.datetime = Field(description="When the iteration settings were last updated")
+
+
+class IterationDocumentStatusResponse(BaseModel):
+    """Response showing the status of all documents in an iteration."""
+
+    iteration_id: str
+    documents: list[DocumentStatus]
+    total_documents: int
+    documents_needing_update: int
+    documents_up_to_date: int
+
+
+class AddIterationFromJsonlRequest(BaseModel):
+    jsonl_gcs_path: str

retab/types/evaluations/model.py

@@ -0,0 +1,73 @@
+import datetime
+import json
+from typing import Any, Optional
+
+import nanoid  # type: ignore
+from pydantic import BaseModel, Field, computed_field
+
+from ..._utils.json_schema import compute_schema_data_id
+from ..._utils.mime import generate_blake2b_hash_from_string
+from ..inference_settings import InferenceSettings
+from .documents import EvaluationDocument
+from .iterations import Iteration
+
+
+# Actual Object stored in DB
+class Evaluation(BaseModel):
+    id: str = Field(default_factory=lambda: "eval_" + nanoid.generate())
+    updated_at: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(tz=datetime.timezone.utc))
+
+    name: str
+    documents: list[EvaluationDocument] = Field(default_factory=list)
+    iterations: list[Iteration] = Field(default_factory=list)
+    json_schema: dict[str, Any]
+
+    project_id: str = Field(description="The ID of the project", default="default_spreadsheets")
+    default_inference_settings: InferenceSettings = Field(
+        default=InferenceSettings(), description="The default inference properties for the evaluation (mostly used in the frontend)"
+    )
+
+    @computed_field  # type: ignore
+    @property
+    def schema_data_id(self) -> str:
+        """Returns the SHA1 hash of the schema data, ignoring all prompt/description/default fields.
+
+        Returns:
+            str: A SHA1 hash string representing the schema data version.
+        """
+        return compute_schema_data_id(self.json_schema)
+
+    # This is a computed field, it is exposed when serializing the object
+    @computed_field  # type: ignore
+    @property
+    def schema_id(self) -> str:
+        """Returns the SHA1 hash of the complete schema.
+
+        Returns:
+            str: A SHA1 hash string representing the complete schema version.
+        """
+        return "sch_id_" + generate_blake2b_hash_from_string(json.dumps(self.json_schema, sort_keys=True).strip())
+
+
+class CreateEvaluation(BaseModel):
+    name: str
+    json_schema: dict[str, Any]
+    project_id: str = Field(description="The ID of the project", default="default_spreadsheets")
+    default_inference_settings: InferenceSettings = Field(default=InferenceSettings(), description="The default inference properties for the evaluation.")
+
+
+class ListEvaluationParams(BaseModel):
+    project_id: Optional[str] = Field(default=None, description="The ID of the project")
+    schema_id: Optional[str] = Field(default=None, description="The ID of the schema")
+    schema_data_id: Optional[str] = Field(default=None, description="The ID of the schema data")
+
+
+class PatchEvaluationRequest(BaseModel):
+    name: Optional[str] = Field(default=None, description="The name of the document")
+    json_schema: Optional[dict[str, Any]] = Field(default=None, description="The json schema of the evaluation")
+    project_id: Optional[str] = Field(default=None, description="The ID of the project")
+    default_inference_settings: Optional[InferenceSettings] = Field(default=None, description="The default inference properties for the evaluation (mostly used in the frontend)")
+
+
+class AddIterationFromJsonlRequest(BaseModel):
+    jsonl_gcs_path: str

retab/types/events.py

@@ -0,0 +1,79 @@
+import datetime
+from typing import Any, Literal, Optional
+
+import nanoid  # type: ignore
+from pydantic import BaseModel, Field
+
+metadata_key = Literal[
+    "automation",
+    "cron",
+    "data_structure",
+    "dataset",
+    "dataset_membership",
+    "endpoint",
+    "evaluation",
+    "extraction",
+    "file",
+    "files",
+    "link",
+    "mailbox",
+    "organization",
+    "outlook",
+    "preprocessing",
+    "preprocessing",
+    "reconciliation",
+    "schema",
+    "schema_data",
+    "template",
+    "user",
+    "webhook",
+]
+
+event_type = Literal[
+    "extraction.created",
+    "messages.created",
+    "document.orientation_corrected",
+    "consensus.reconciled",
+    "automation.created",
+    "automation.updated",
+    "automation.deleted",
+    "automation.webhook",
+    "preprocessing.created",
+    "link.created",
+    "link.updated",
+    "link.deleted",
+    "link.webhook",
+    "mailbox.created",
+    "mailbox.updated",
+    "mailbox.deleted",
+    "mailbox.webhook",
+    "outlook.created",
+    "outlook.updated",
+    "outlook.deleted",
+    "outlook.webhook",
+    "schema.generated",
+    "schema.promptified",
+    "schema.system_promptfile.created",
+    "file.updated",
+    "file.deleted",
+    "template.created",
+    "template.deleted",
+    "template.sample_document_uploaded",
+    "template.sample_document_deleted",
+    "template.updated",
+]
+
+
+class Event(BaseModel):
+    object: Literal["event"] = "event"
+    id: str = Field(default_factory=lambda: "event_" + nanoid.generate(), description="Unique identifier for the event")
+    event: str = Field(..., description="A string that distinguishes the event type. Ex: user.created, user.updated, user.deleted, etc.")
+    created_at: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(datetime.timezone.utc))
+    data: dict[str, Any] = Field(..., description="Event payload. Payloads match the corresponding API objects.")
+    metadata: Optional[dict[metadata_key, str]] = Field(
+        default=None, description="Ids giving informations about the event. Ex: user.created.metadata = {'user': 'usr_8478973619047837'}"
+    )
+
+
+class StoredEvent(Event):
+    organization_id: str = Field(..., description="Organization ID")

{uiform → retab}/types/extractions.py

@@ -4,12 +4,12 @@ from typing import Any, Literal, Optional
 import nanoid  # type: ignore
 from openai.types.chat import ChatCompletion
 from openai.types.chat.chat_completion_reasoning_effort import ChatCompletionReasoningEffort
-from pydantic import BaseModel, Field, computed_field
+from pydantic import BaseModel, Field, computed_field, model_validator
 
 from uiform.types.chat import ChatCompletionUiformMessage
 from uiform.types.documents.extractions import UiParsedChatCompletion
 
-from .._utils.usage.usage import compute_cost_from_model, compute_cost_from_model_with_breakdown, CostBreakdown
+from .._utils.usage.usage import CostBreakdown, compute_cost_from_model, compute_cost_from_model_with_breakdown
 from .ai_models import Amount
 from .modalities import Modality
 
@@ -17,13 +17,14 @@ ValidationsState = Literal["pending", "validated", "invalid"]
 
 
 class ExtractionSource(BaseModel):
-    type: Literal["api", "annotation","processor", "automation.link", "automation.mailbox", "automation.cron", "automation.outlook", "automation.endpoint", "schema.extract"] = Field(
-        description="Type of extraction"
+    type: Literal["api", "annotation", "processor", "automation.link", "automation.mailbox", "automation.cron", "automation.outlook", "automation.endpoint", "schema.extract"] = (
+        Field(description="Type of extraction")
     )
     id: str | None = Field(default=None, description="ID the trigger of the extraction")
 
 
-ExtractionSteps = str | Literal['initialization', 'prepare_messages', 'yield_first_token', 'completion']  # Steps are meant to not overlap
+ExtractionSteps = str | Literal["initialization", "prepare_messages", "yield_first_token", "completion"]  # Steps are meant to not overlap
+BrowserCanvas = Literal["A3", "A4", "A5"]
 
 
 class ExtractionTimingStep(BaseModel):
@@ -36,8 +37,11 @@ class Extraction(BaseModel):
     id: str = Field(default_factory=lambda: "extr_" + nanoid.generate(), description="Unique identifier of the analysis")
     messages: list[ChatCompletionUiformMessage] = Field(default_factory=list)
     messages_gcs: str = Field(..., description="GCS path to the messages")
-    file_gcs: str = Field(..., description="GCS path to the file")
-    file_id: str = Field(..., description="ID of the file")
+    file_gcs_paths: list[str] = Field(..., description="GCS paths to the files")
+    file_ids: list[str] = Field(..., description="IDs of the files")
+    # Legacy fields for backward compatibility
+    file_gcs: str = Field(default="", description="GCS path to the first file (deprecated)")
+    file_id: str = Field(default="", description="ID of the first file (deprecated)")
 
     status: Literal["success", "failed"] = Field(..., description="Whether the analysis was successful")
     completion: UiParsedChatCompletion | ChatCompletion = Field(..., description="Response generated by the analysis")
@@ -46,7 +50,9 @@ class Extraction(BaseModel):
     temperature: float = Field(default=0.0, description="Temperature used for the analysis")
     source: ExtractionSource = Field(..., description="Source of the extraction")
     image_resolution_dpi: int = Field(default=96, description="Resolution of the image sent to the LLM")
-    browser_canvas: Literal['A3', 'A4', 'A5'] = Field(default='A4', description="Sets the size of the browser canvas for rendering documents in browser-based processing. Choose a size that matches the document type.")
+    browser_canvas: BrowserCanvas = Field(
+        default="A4", description="Sets the size of the browser canvas for rendering documents in browser-based processing. Choose a size that matches the document type."
+    )
     modality: Modality = Field(default="native", description="Modality of the extraction")
     reasoning_effort: Optional[ChatCompletionReasoningEffort] = Field(default=None, description="The effort level for the model to reason about the input data.")
     timings: list[ExtractionTimingStep] = Field(default_factory=list, description="Timings of the extraction")
@@ -60,7 +66,24 @@ class Extraction(BaseModel):
     validation_state: Optional[ValidationsState] = Field(default=None, description="Validation state of the extraction")
     billed: bool = Field(default=False, description="Whether the extraction has been billed or not")
 
-    @computed_field
+    @model_validator(mode="before")
+    def handle_legacy_fields(cls, data):
+        """Handle backward compatibility for legacy file_gcs and file_id fields."""
+        if isinstance(data, dict):
+            # If only legacy fields are provided, convert to new format
+            if "file_gcs" in data and "file_gcs_paths" not in data:
+                data["file_gcs_paths"] = [data["file_gcs"]]
+            if "file_id" in data and "file_ids" not in data:
+                data["file_ids"] = [data["file_id"]]
+
+            # Set legacy fields from new format for backward compatibility
+            if "file_gcs_paths" in data and data["file_gcs_paths"]:
+                data["file_gcs"] = data["file_gcs_paths"][0]
+            if "file_ids" in data and data["file_ids"]:
+                data["file_id"] = data["file_ids"][0]
+        return data
+
+    @computed_field  # type: ignore
     @property
     def api_cost(self) -> Optional[Amount]:
         if self.completion and self.completion.usage:
@@ -71,7 +94,7 @@ class Extraction(BaseModel):
                 print(f"Error computing cost: {e}")
                 return None
         return None
-    
+
     @computed_field  # type: ignore
     @property
     def cost_breakdown(self) -> Optional[CostBreakdown]:

retab/types/inference_settings.py

@@ -0,0 +1,15 @@
+from openai.types.chat.chat_completion_reasoning_effort import ChatCompletionReasoningEffort
+from pydantic import BaseModel, Field
+
+from .browser_canvas import BrowserCanvas
+from .modalities import Modality
+
+
+class InferenceSettings(BaseModel):
+    model: str = "gpt-4.1-mini"
+    temperature: float = 0.0
+    modality: Modality = "native"
+    reasoning_effort: ChatCompletionReasoningEffort = "medium"
+    image_resolution_dpi: int = 96
+    browser_canvas: BrowserCanvas = "A4"
+    n_consensus: int = Field(default=1, description="Number of consensus rounds to perform")

retab/types/jobs/base.py

@@ -0,0 +1,54 @@
+from typing import Literal, Optional, Self
+
+from pydantic import BaseModel, model_validator
+from ..inference_settings import InferenceSettings
+
+SelectionMode = Literal["all", "manual"]
+
+
+# This is the input data for the prepare_dataset job
+class PrepareDatasetInputData(BaseModel):
+    dataset_id: Optional[str] = None
+    schema_id: Optional[str] = None
+    schema_data_id: Optional[str] = None
+
+    selection_model: SelectionMode = "all"
+
+    @model_validator(mode="after")
+    def validate_input(self) -> Self:
+        # The preference is:
+        # 1. dataset_id
+        # 2. schema_id
+        # 3. schema_data_id
+        if self.dataset_id is None and self.schema_id is None and self.schema_data_id is None:
+            raise ValueError("At least one of dataset_id, schema_id, or schema_data_id must be provided")
+
+        return self
+
+
+# This is the input data for the split_dataset job
+class DatasetSplitInputData(BaseModel):
+    dataset_id: str
+    train_size: Optional[int | float] = None
+    eval_size: Optional[int | float] = None
+
+    @model_validator(mode="after")
+    def validate_input(self) -> Self:
+        if self.train_size is not None and self.eval_size is not None:
+            raise ValueError("train_size and eval_size cannot both be provided")
+        return self
+
+
+# This is the input data for the batch annotation job
+class AnnotationInputData(BaseModel):
+    data_file: str
+    schema_id: str
+    inference_settings: InferenceSettings
+
+
+# This is the input data for the evaluation job
+class EvaluationInputData(BaseModel):
+    eval_data_file: str
+    schema_id: str
+    inference_settings_1: InferenceSettings | None = None
+    inference_settings_2: InferenceSettings

retab/types/jobs/batch_annotation.py

@@ -0,0 +1,12 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+from ..inference_settings import InferenceSettings
+
+
+class AnnotationInputData(BaseModel):
+    dataset_id: str
+    files_ids: Optional[list[str]] = None
+    upsert: bool = False
+    inference_settings: InferenceSettings

{uiform → retab}/types/jobs/evaluation.py

@@ -1,7 +1,6 @@
 from pydantic import BaseModel
 
-from ..._utils.benchmarking import EvalMetrics, SingleFileEval, compute_dict_difference
-from .batch_annotation import AnnotationInputData, InferenceSettings
+from ..inference_settings import InferenceSettings
 
 # This job will generate two datasets from the original dataset, one with the first annotation and one with the second annotation
 # It will then evaluate the two datasets using the evaluation metrics and return an EvalMetrics object

{uiform → retab}/types/logs.py

@@ -1,22 +1,21 @@
-import copy
 import datetime
 import json
 from typing import Any, Dict, List, Literal, Optional
 
 import nanoid  # type: ignore
-from openai import OpenAI
+from openai.types.chat.chat_completion import ChatCompletion
 from openai.types.chat.chat_completion_reasoning_effort import ChatCompletionReasoningEffort
-from pydantic import BaseModel, EmailStr, Field, HttpUrl, computed_field, field_serializer
-from pydantic_core import Url
+from pydantic import BaseModel, EmailStr, Field, HttpUrl, computed_field, field_validator
 
-from .._utils.json_schema import clean_schema, compute_schema_data_id
+from .._utils.json_schema import compute_schema_data_id
 from .._utils.mime import generate_blake2b_hash_from_string
-from .._utils.usage.usage import compute_cost_from_model, compute_cost_from_model_with_breakdown, CostBreakdown
+from .._utils.usage.usage import CostBreakdown, compute_cost_from_model, compute_cost_from_model_with_breakdown
 from .ai_models import Amount
 from .documents.extractions import UiParsedChatCompletion
 from .mime import BaseMIMEData
 from .modalities import Modality
 from .pagination import ListMetadata
+from .browser_canvas import BrowserCanvas
 
 
 class ProcessorConfig(BaseModel):
@@ -27,7 +26,9 @@ class ProcessorConfig(BaseModel):
 
     modality: Modality
     image_resolution_dpi: int = Field(default=96, description="Resolution of the image sent to the LLM")
-    browser_canvas: Literal['A3', 'A4', 'A5'] = Field(default='A4', description="Sets the size of the browser canvas for rendering documents in browser-based processing. Choose a size that matches the document type.")
+    browser_canvas: BrowserCanvas = Field(
+        default="A4", description="Sets the size of the browser canvas for rendering documents in browser-based processing. Choose a size that matches the document type."
+    )
 
     # New attributes
     model: str = Field(..., description="Model used for chat completion")
@@ -61,7 +62,11 @@ class ProcessorConfig(BaseModel):
 
 
 class AutomationConfig(BaseModel):
-    object: str = Field(default="automation", description="Type of the object")
+    @computed_field
+    @property
+    def object(self) -> str:
+        return "automation"
+
     id: str = Field(default_factory=lambda: "auto_" + nanoid.generate(), description="Unique identifier for the automation")
     name: str = Field(..., description="Name of the automation")
     processor_id: str = Field(..., description="ID of the processor to use for the automation")
@@ -70,14 +75,16 @@ class AutomationConfig(BaseModel):
     default_language: str = Field(default="en", description="Default language for the automation")
 
     # HTTP Config
-    webhook_url: HttpUrl = Field(..., description="Url of the webhook to send the data to")
+    webhook_url: str = Field(..., description="Url of the webhook to send the data to")
     webhook_headers: Dict[str, str] = Field(default_factory=dict, description="Headers to send with the request")
 
     need_validation: bool = Field(default=False, description="If the automation needs to be validated before running")
 
-    @field_serializer('webhook_url')
-    def url2str(self, val: HttpUrl) -> str:
-        return str(val)
+    @field_validator("webhook_url", mode="after")
+    def validate_httpurl(cls, val: Any) -> Any:
+        if isinstance(val, str):
+            HttpUrl(val)
+        return val
 
 
 class UpdateProcessorRequest(BaseModel):
@@ -87,7 +94,7 @@ class UpdateProcessorRequest(BaseModel):
     name: Optional[str] = None
     modality: Optional[Modality] = None
     image_resolution_dpi: Optional[int] = None
-    browser_canvas: Optional[Literal['A3', 'A4', 'A5']] = None
+    browser_canvas: Optional[BrowserCanvas] = None
     model: Optional[str] = None
     json_schema: Optional[Dict] = None
     temperature: Optional[float] = None
@@ -121,24 +128,24 @@ class UpdateProcessorRequest(BaseModel):
 
 class UpdateAutomationRequest(BaseModel):
     name: Optional[str] = None
-    processor_id: Optional[str] = None
+    # processor_id: Optional[str] = None  # TODO: Is it allowed to change the processor_id?
 
     default_language: Optional[str] = None
 
-    webhook_url: Optional[HttpUrl] = None
-    webhook_headers: Optional[Dict[str, str]] = None
-    
-    need_validation: Optional[bool] = None
+    webhook_url: Optional[str] = None
+    webhook_headers: Optional[dict[str, str]] = None
 
+    need_validation: Optional[bool] = None
 
-    @field_serializer('webhook_url')
-    def url2str(self, val: HttpUrl | None) -> str | None:
-        if isinstance(val, HttpUrl):
-            return str(val)
+    @field_validator("webhook_url", mode="after")
+    def validate_httpurl(cls, val: Any) -> Any:
+        if isinstance(val, str):
+            HttpUrl(val)
         return val
 
+
 class OpenAIRequestConfig(BaseModel):
-    object: Literal['openai_request'] = "openai_request"
+    object: Literal["openai_request"] = "openai_request"
     id: str = Field(default_factory=lambda: "openai_req_" + nanoid.generate(), description="Unique identifier for the openai request")
     model: str
     json_schema: dict[str, Any]
@@ -160,7 +167,7 @@ class OpenAIRequestConfig(BaseModel):
 
 
 class ExternalRequestLog(BaseModel):
-    webhook_url: Optional[HttpUrl]
+    webhook_url: Optional[str]
     request_body: dict[str, Any]
     request_headers: dict[str, str]
     request_at: datetime.datetime
@@ -173,24 +180,20 @@ class ExternalRequestLog(BaseModel):
     error: Optional[str] = None
     duration_ms: float
 
-    @field_serializer('webhook_url')
-    def url2str(self, val: HttpUrl | None) -> str | None:
-        if isinstance(val, HttpUrl):
-            return str(val)
+    @field_validator("webhook_url", mode="after")
+    def validate_httpurl(cls, val: Any) -> Any:
+        if isinstance(val, str):
+            HttpUrl(val)
         return val
 
 
-from openai.types.chat import completion_create_params
-from openai.types.chat.chat_completion import ChatCompletion
-
-
 class LogCompletionRequest(BaseModel):
     json_schema: dict[str, Any]
     completion: ChatCompletion
 
 
 class AutomationLog(BaseModel):
-    object: Literal['automation_log'] = "automation_log"
+    object: Literal["automation_log"] = "automation_log"
     id: str = Field(default_factory=lambda: "log_auto_" + nanoid.generate(), description="Unique identifier for the automation log")
     user_email: Optional[EmailStr]  # When the user is logged or when he forwards an email
     organization_id: str
@@ -212,7 +215,7 @@ class AutomationLog(BaseModel):
                 print(f"Error computing cost: {e}")
                 return None
         return None
-    
+
     @computed_field  # type: ignore
     @property
     def cost_breakdown(self) -> Optional[CostBreakdown]:

retab/types/metrics.py

@@ -0,0 +1,32 @@
+from typing import Any, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+# Define the type alias for MetricType
+MetricType = Literal["levenshtein", "jaccard", "hamming"]
+
+
+# Define the structure for an individual item metric
+class ItemMetric(BaseModel):
+    id: str = Field(description="The ID of the item being measured")
+    name: str = Field(description="The name of the item being measured")
+    similarity: float = Field(description="The similarity score between 0 and 1")
+    similarities: dict[str, Any] = Field(description="The similarity scores for each item in the list")
+    flat_similarities: dict[str, Optional[float]] = Field(description="The similarity scores for each item in the list in dot notation format")
+    aligned_similarity: float = Field(description="The similarity score between 0 and 1, after alignment")
+    aligned_similarities: dict[str, Any] = Field(description="The similarity scores for each item in the list, after alignment")
+    aligned_flat_similarities: dict[str, Optional[float]] = Field(description="The similarity scores for each item in the list in dot notation format, after alignment")
+
+
+# Define the main MetricResult model
+class MetricResult(BaseModel):
+    item_metrics: list[ItemMetric] = Field(description="List of similarity metrics for individual items")
+    mean_similarity: float = Field(description="The average similarity score across all items")
+    aligned_mean_similarity: float = Field(description="The average similarity score across all items, after alignment")
+    metric_type: MetricType = Field(description="The type of similarity metric used for comparison")
+
+
+class DistancesResult(BaseModel):
+    distances: dict[str, Any] = Field(description="List of distances for individual items")
+    mean_distance: float = Field(description="The average distance across all items")
+    metric_type: MetricType = Field(description="The type of distance metric used for comparison")