retab 0.0.42__py3-none-any.whl → 0.0.44__py3-none-any.whl

retab/types/deprecated_evals.py

@@ -0,0 +1,195 @@
+import datetime
+from typing import Any, List, Literal, Optional
+
+import nanoid  # type: ignore
+from pydantic import BaseModel, Field, computed_field
+
+from ..utils.json_schema import generate_schema_data_id, generate_schema_id
+from .ai_models import Amount
+from .inference_settings import InferenceSettings
+from .mime import MIMEData
+
+# 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")
+
+
+class PredictionMetadata(BaseModel):
+    extraction_id: Optional[str] = Field(default=None, description="The ID of the extraction")
+    likelihoods: Optional[dict[str, Any]] = Field(default=None, description="The likelihoods of the extraction")
+    field_locations: Optional[dict[str, Any]] = Field(default=None, description="The field locations of the extraction")
+    agentic_field_locations: Optional[dict[str, Any]] = Field(default=None, description="The field locations of the extraction extracted by an llm")
+    consensus_details: Optional[list[dict[str, Any]]] = Field(default=None, description="The consensus details of the extraction")
+    api_cost: Optional[Amount] = Field(default=None, description="The cost of the API call for this document (if any -- ground truth for example)")
+
+
+class PredictionData(BaseModel):
+    prediction: dict[str, Any] = Field(default={}, description="The result of the extraction or manual annotation")
+    metadata: Optional[PredictionMetadata] = Field(default=None, description="The metadata of the prediction")
+
+
+class Iteration(BaseModel):
+    id: str = Field(default_factory=lambda: "eval_iter_" + nanoid.generate())
+    inference_settings: InferenceSettings
+    json_schema: dict[str, Any]
+    predictions: list[PredictionData] = Field(default_factory=list, 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 generate_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 generate_schema_id(self.json_schema)
+
+
+class AnnotatedDocument(BaseModel):
+    mime_data: MIMEData = Field(
+        description="The mime data of the document. Can also be a BaseMIMEData, which is why we have this id field (to be able to identify the file, but id is equal to mime_data.id)"
+    )
+    annotation: dict[str, Any] = Field(default={}, description="The ground truth of the document")
+
+
+class DocumentItem(AnnotatedDocument):
+    annotation_metadata: Optional[PredictionMetadata] = Field(default=None, description="The metadata of the annotation when the annotation is a prediction")
+
+
+class ProjectDocument(DocumentItem):
+    id: str = Field(description="The ID of the document. Equal to mime_data.id but robust to the case where mime_data is a BaseMIMEData")
+
+
+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
+
+
+class UpdateProjectDocumentRequest(BaseModel):
+    annotation: Optional[dict[str, Any]] = Field(default=None, description="The ground truth of the document")
+    annotation_metadata: Optional[PredictionMetadata] = Field(default=None, description="The metadata of the annotation when the annotation is a prediction")
+
+
+class UpdateProjectRequest(BaseModel):
+    name: Optional[str] = Field(default=None, description="The name of the document")
+    documents: Optional[list[ProjectDocument]] = Field(default=None, description="The documents of the evaluation")
+    iterations: Optional[list[Iteration]] = Field(default=None, description="The iterations of the evaluation")
+    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)")
+
+    @computed_field  # type: ignore
+    @property
+    def schema_data_id(self) -> Optional[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.
+        """
+        if self.json_schema is None:
+            return None
+
+        return generate_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) -> Optional[str]:
+        """Returns the SHA1 hash of the complete schema.
+
+        Returns:
+            str: A SHA1 hash string representing the complete schema version.
+        """
+        if self.json_schema is None:
+            return None
+        return generate_schema_id(self.json_schema)
+
+
+class Project(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
+    old_documents: list[ProjectDocument] | None = None
+    documents: list[ProjectDocument]
+    iterations: list[Iteration]
+    json_schema: dict[str, Any]
+
+    project_id: str = Field(description="The ID of the project", default="default_spreadsheets")
+    default_inference_settings: Optional[InferenceSettings] = Field(default=None, description="The default inference properties for the evaluation (mostly used in the frontend)")
+
+    # @field_validator('iterations')
+    # def validate_iterations_content_length(cls: Any, v: list[Iteration], values: Any) -> list[Iteration]:
+    #     if 'ground_truth' in values:
+    #         ground_truth_length = len(values['ground_truth'])
+    #         for iteration in v:
+    #             if len(iteration.content) != ground_truth_length:
+    #                 raise ValueError(f"Iteration content length must match ground_truth length ({ground_truth_length})")
+    #     return v
+
+    @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 generate_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 generate_schema_id(self.json_schema)
+
+
+class AddIterationFromJsonlRequest(BaseModel):
+    jsonl_gcs_path: str

retab/types/evaluations/__init__.py

@@ -1,6 +1,7 @@
-from .model import Evaluation, CreateEvaluation, PatchEvaluationRequest, ListEvaluationParams
+from .model import Evaluation, BaseEvaluation, CreateEvaluationRequest, PatchEvaluationRequest, ListEvaluationParams
 from .documents import AnnotatedDocument, DocumentItem, EvaluationDocument, CreateEvaluationDocumentRequest, PatchEvaluationDocumentRequest
 from .iterations import (
+    BaseIteration,
     Iteration,
     CreateIterationRequest,
     PatchIterationRequest,
@@ -13,7 +14,8 @@ from .iterations import (
 
 __all__ = [
     "Evaluation",
-    "CreateEvaluation",
+    "BaseEvaluation",
+    "CreateEvaluationRequest",
     "PatchEvaluationRequest",
     "ListEvaluationParams",
     "AnnotatedDocument",
@@ -21,6 +23,7 @@ __all__ = [
     "EvaluationDocument",
     "CreateEvaluationDocumentRequest",
     "PatchEvaluationDocumentRequest",
+    "BaseIteration",
     "Iteration",
     "CreateIterationRequest",
     "PatchIterationRequest",

retab/types/evaluations/iterations.py

@@ -1,59 +1,24 @@
-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 pydantic import BaseModel, 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):
+class BaseIteration(BaseModel):
     id: str = Field(default_factory=lambda: "eval_iter_" + nanoid.generate())
+    inference_settings: InferenceSettings
+    json_schema: dict[str, Any]
     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 Iteration(BaseIteration):
+    predictions: dict[str, PredictionData] = Field(default_factory=dict, description="The predictions of the iteration for all the documents")
 
 class CreateIterationRequest(BaseModel):
     """
@@ -71,13 +36,14 @@ class CreateIterationRequest(BaseModel):
     @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
+            return self
+        raise ValueError("Exactly one of from_iteration_id or json_schema must be provided")
 
 
 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")
+    version: Optional[int] = Field(default=None, description="Current version for optimistic locking")
 
 
 class ProcessIterationRequest(BaseModel):

retab/types/evaluations/model.py

@@ -1,31 +1,27 @@
 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 ...utils.json_schema import generate_schema_data_id, generate_schema_id
 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())
+class BaseEvaluation(BaseModel):
+    id: str = Field(default_factory=lambda: "proj_" + nanoid.generate())
+    name: str = Field(default="", description="The name of the evaluation")
+    json_schema: dict[str, Any] = Field(default_factory=dict, description="The json schema of the evaluation")
+    default_inference_settings: InferenceSettings = Field(default=InferenceSettings(), description="The default inference properties for the evaluation.")
     updated_at: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(tz=datetime.timezone.utc))
 
-    name: str
+
+# Actual Object stored in DB
+class Evaluation(BaseEvaluation):
     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
@@ -35,7 +31,7 @@ class Evaluation(BaseModel):
         Returns:
             str: A SHA1 hash string representing the schema data version.
         """
-        return compute_schema_data_id(self.json_schema)
+        return generate_schema_data_id(self.json_schema)
 
     # This is a computed field, it is exposed when serializing the object
     @computed_field  # type: ignore
@@ -46,26 +42,25 @@ class Evaluation(BaseModel):
         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.")
+        return generate_schema_id(self.json_schema)
 
 
 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 CreateEvaluationRequest(BaseModel):
+    name: str
+    json_schema: dict[str, Any]
+    default_inference_settings: InferenceSettings
+
+
+# This is basically the same as BaseEvaluation, but everything is optional.
+# Could be achieved by convert_basemodel_to_partial_basemodel(BaseEvaluation) but we prefer explicitness
 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)")
 
 

retab/types/extractions.py

@@ -77,6 +77,7 @@ class Extraction(BaseModel):
         default=None,
         description="The effort level for the model to reason about the input data.",
     )
+    n_consensus: int = Field(default=1, description="Number of consensus models used for the extraction")
     timings: list[ExtractionTimingStep] = Field(default_factory=list, description="Timings of the extraction")
 
     # Infered from the schema

retab/types/jobs/base.py

@@ -47,7 +47,7 @@ class AnnotationInputData(BaseModel):
 
 
 # This is the input data for the evaluation job
-class EvaluationInputData(BaseModel):
+class ProjectInputData(BaseModel):
     eval_data_file: str
     schema_id: str
     inference_settings_1: InferenceSettings | None = None

retab/types/jobs/evaluation.py

@@ -6,7 +6,7 @@ from ..inference_settings import InferenceSettings
 # It will then evaluate the two datasets using the evaluation metrics and return an EvalMetrics object
 
 
-class EvaluationInputData(BaseModel):
+class ProjectInputData(BaseModel):
     original_dataset_id: str
     schema_id: str
     schema_data_id: str

retab/types/logs.py

@@ -7,8 +7,7 @@ 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_validator
 
-from ..utils.json_schema import compute_schema_data_id
-from ..utils.mime import generate_blake2b_hash_from_string
+from ..utils.json_schema import generate_schema_data_id, generate_schema_id
 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 RetabParsedChatCompletion
@@ -47,7 +46,7 @@ class ProcessorConfig(BaseModel):
         Returns:
             str: A SHA1 hash string representing the schema data version.
         """
-        return compute_schema_data_id(self.json_schema)
+        return generate_schema_data_id(self.json_schema)
 
     # This is a computed field, it is exposed when serializing the object
     @computed_field  # type: ignore
@@ -58,7 +57,7 @@ class ProcessorConfig(BaseModel):
         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())
+        return generate_schema_id(self.json_schema)
 
 
 class AutomationConfig(BaseModel):
@@ -111,7 +110,7 @@ class UpdateProcessorRequest(BaseModel):
         """
         if self.json_schema is None:
             return None
-        return compute_schema_data_id(self.json_schema)
+        return generate_schema_data_id(self.json_schema)
 
     @computed_field  # type: ignore
     @property
@@ -123,7 +122,7 @@ class UpdateProcessorRequest(BaseModel):
         """
         if self.json_schema is None:
             return None
-        return "sch_id_" + generate_blake2b_hash_from_string(json.dumps(self.json_schema, sort_keys=True).strip())
+        return generate_schema_id(self.json_schema)
 
 
 class UpdateAutomationRequest(BaseModel):

retab/types/mime.py

@@ -1,21 +1,12 @@
 import base64
 import datetime
 import gzip
-import hashlib
 import mimetypes
 import re
 from typing import Any, Optional, Self, Sequence
 
 from pydantic import BaseModel, Field, field_validator
-
-
-def generate_blake2b_hash_from_bytes(bytes_: bytes) -> str:
-    return hashlib.blake2b(bytes_, digest_size=8).hexdigest()
-
-
-def generate_blake2b_hash_from_base64(base64_string: str) -> str:
-    return generate_blake2b_hash_from_bytes(base64.b64decode(base64_string))
-
+from ..utils.hashing import generate_blake2b_hash_from_base64
 
 # **** OCR DATACLASSES (DocumentAI-compatible) ****
 class Point(BaseModel):

retab/types/projects/__init__.py

@@ -0,0 +1,34 @@
+from .model import Project, BaseProject, CreateProjectRequest, PatchProjectRequest, ListProjectParams
+from .documents import AnnotatedDocument, DocumentItem, ProjectDocument, CreateProjectDocumentRequest, PatchProjectDocumentRequest
+from .iterations import (
+    BaseIteration,
+    Iteration,
+    CreateIterationRequest,
+    PatchIterationRequest,
+    ProcessIterationRequest,
+    DocumentStatus,
+    IterationDocumentStatusResponse,
+    AddIterationFromJsonlRequest,
+)
+
+
+__all__ = [
+    "Project",
+    "BaseProject",
+    "CreateProjectRequest",
+    "PatchProjectRequest",
+    "ListProjectParams",
+    "AnnotatedDocument",
+    "DocumentItem",
+    "ProjectDocument",
+    "CreateProjectDocumentRequest",
+    "PatchProjectDocumentRequest",
+    "BaseIteration",
+    "Iteration",
+    "CreateIterationRequest",
+    "PatchIterationRequest",
+    "ProcessIterationRequest",
+    "DocumentStatus",
+    "IterationDocumentStatusResponse",
+    "AddIterationFromJsonlRequest",
+]

retab/types/projects/documents.py

@@ -0,0 +1,30 @@
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from ..mime import MIMEData
+from ..predictions import PredictionMetadata
+
+
+class AnnotatedDocument(BaseModel):
+    mime_data: MIMEData = Field(
+        description="The mime data of the document. Can also be a BaseMIMEData, which is why we have this id field (to be able to identify the file, but id is equal to mime_data.id)"
+    )
+    annotation: dict[str, Any] = Field(default={}, description="The ground truth of the document")
+
+
+class DocumentItem(AnnotatedDocument):
+    annotation_metadata: Optional[PredictionMetadata] = Field(default=None, description="The metadata of the annotation when the annotation is a prediction")
+
+
+class ProjectDocument(DocumentItem):
+    id: str = Field(description="The ID of the document. Equal to mime_data.id but robust to the case where mime_data is a BaseMIMEData")
+
+
+class CreateProjectDocumentRequest(DocumentItem):
+    pass
+
+
+class PatchProjectDocumentRequest(BaseModel):
+    annotation: Optional[dict[str, Any]] = Field(default=None, description="The ground truth of the document")
+    annotation_metadata: Optional[PredictionMetadata] = Field(default=None, description="The metadata of the annotation when the annotation is a prediction")

retab/types/projects/iterations.py

@@ -0,0 +1,78 @@
+import datetime
+from typing import Any, Optional, Self
+
+import nanoid  # type: ignore
+from pydantic import BaseModel, Field, model_validator
+
+from ..inference_settings import InferenceSettings
+from ..predictions import PredictionData
+
+
+class BaseIteration(BaseModel):
+    id: str = Field(default_factory=lambda: "eval_iter_" + nanoid.generate())
+    inference_settings: InferenceSettings
+    json_schema: dict[str, Any]
+    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",
+    )
+
+class Iteration(BaseIteration):
+    predictions: dict[str, PredictionData] = Field(default_factory=dict, description="The predictions of the iteration for all the documents")
+
+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):
+            return self
+        raise ValueError("Exactly one of from_iteration_id or json_schema must be provided")
+
+
+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")
+    version: Optional[int] = Field(default=None, description="Current version for optimistic locking")
+
+
+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