reasoning_layer_python_sdk 1.0.0__py3-none-any.whl

reasoning_layer_python_sdk/generated/models/ingest_step_request.py

@@ -0,0 +1,92 @@
+# coding: utf-8
+
+"""
+    OSF Knowledge Base API
+
+    Order-Sorted Feature logic knowledge base with fuzzy reasoning, inference, and constraint solving. Note: Some endpoints are hidden from Swagger due to recursive type limitations but work via API calls.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Any, ClassVar, Dict, List
+from reasoning_layer_python_sdk.generated.models.trajectory_step_dto import TrajectoryStepDto
+from typing import Optional, Set
+from typing_extensions import Self
+from pydantic_core import to_jsonable_python
+
+class IngestStepRequest(BaseModel):
+    """
+    Request to ingest a single step into a live oversight session.
+    """ # noqa: E501
+    step: TrajectoryStepDto = Field(description="The trajectory step to ingest")
+    __properties: ClassVar[List[str]] = ["step"]
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        return json.dumps(to_jsonable_python(self.to_dict()))
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of IngestStepRequest from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # override the default output from pydantic by calling `to_dict()` of step
+        if self.step:
+            _dict['step'] = self.step.to_dict()
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of IngestStepRequest from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "step": TrajectoryStepDto.from_dict(obj["step"]) if obj.get("step") is not None else None
+        })
+        return _obj
+
+

reasoning_layer_python_sdk/generated/models/ingestion_config_dto.py

@@ -0,0 +1,153 @@
+# coding: utf-8
+
+"""
+    OSF Knowledge Base API
+
+    Order-Sorted Feature logic knowledge base with fuzzy reasoning, inference, and constraint solving. Note: Some endpoints are hidden from Swagger due to recursive type limitations but work via API calls.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictFloat, StrictInt, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional, Union
+from typing_extensions import Annotated
+from reasoning_layer_python_sdk.generated.models.evidence_derivation_config_dto import EvidenceDerivationConfigDto
+from reasoning_layer_python_sdk.generated.models.extraction_strategy_dto import ExtractionStrategyDto
+from typing import Optional, Set
+from typing_extensions import Self
+from pydantic_core import to_jsonable_python
+
+class IngestionConfigDto(BaseModel):
+    """
+    Configuration for ingestion
+    """ # noqa: E501
+    auto_create_sorts: Optional[StrictBool] = Field(default=None, description="Whether to automatically create new sorts for unrecognized entity types")
+    batch_size: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Batch size for parallel processing")
+    deduplication_threshold: Optional[Union[StrictFloat, StrictInt]] = Field(default=None, description="Confidence threshold for deduplication (0.0 - 1.0)")
+    document_id: Optional[StrictStr] = Field(default=None, description="Optional document ID for tracking sort provenance Used in SortOrigin::LlmExtracted to track which document triggered sort creation")
+    domain_instructions: Optional[List[StrictStr]] = Field(default=None, description="Domain-specific instructions for LLM extraction. These are injected into the extraction prompt to guide the LLM toward domain-relevant concepts. Example: - \"This content is from a training about sexual education.\" - \"Extract concepts specifically relevant to this domain.\"")
+    enable_description_consolidation: Optional[StrictBool] = Field(default=None, description="Enable cross-chunk description consolidation. Merges multiple descriptions of the same entity into one concise description. Default: true")
+    enable_entity_filtering: Optional[StrictBool] = Field(default=None, description="Enable post-extraction entity filtering. Removes structurally invalid entities (pure punctuation, repeated chars, placeholders). Default: true")
+    enable_evidence_enrichment: Optional[StrictBool] = Field(default=None, description="Enable LLM-based evidence enrichment with statistical features. After evidence terms are derived, makes one LLM call to extract statistical measures (p-value, HR, CI, sample size, study design) and attach them as features on evidence terms. Default: false")
+    enable_focused_extraction: Optional[StrictBool] = Field(default=None, description="Enable focused extraction prompts. When schema discovery found types, uses a simplified prompt asking only for entities and relations (no sorts/axioms/equivalences). Default: true")
+    enable_llm_coreference: Optional[StrictBool] = Field(default=None, description="Enable LLM-based coreference resolution for hard cases. When true, after structural deduplication the pipeline runs parallel per-pair LLM calls to resolve ambiguous coreferences (e.g., \"Stanley Reed\" vs \"Justice Reed\"). Adds LLM calls proportional to the number of candidate pairs — violates the 0-LLM-token guarantee for the LocalNer strategy, so disabled by default. Opt in to improve entity deduplication quality at the cost of extra LLM calls. Default: false")
+    enable_schema_discovery: Optional[StrictBool] = Field(default=None, description="Enable schema discovery before extraction. Samples the document to discover entity/relation types before per-chunk extraction. Adds one extra LLM call but improves extraction precision. Default: true")
+    enable_zero_degree_filtering: Optional[StrictBool] = Field(default=None, description="Enable zero-degree entity removal. Removes entities not referenced by any relation (only when entity filtering is enabled). Default: false")
+    evidence_derivation_config: Optional[EvidenceDerivationConfigDto] = Field(default=None, description="Configuration for deriving evidence terms from relational features. When set, entities with Reference features (from NER relations) automatically get linked evidence terms created, enabling OSFKB evidence assessment.")
+    extract_relations: Optional[StrictBool] = Field(default=None, description="Whether to extract relations between entities")
+    extraction_strategy: Optional[ExtractionStrategyDto] = Field(default=None, description="Extraction strategy -- an internally tagged object with a `\"type\"` discriminator.  Variants: - `{\"type\": \"llm\"}` -- LLM for all extraction (default, most capable) - `{\"type\": \"local_ner\"}` -- local NER model like GLiNER2 (fast, no API costs) - `{\"type\": \"hybrid\", \"ner_confidence_threshold\": 0.8}` -- NER first, LLM fallback - `{\"type\": \"schema_guided\", ...}` -- NER + pattern-based, LLM only when needed - `{\"type\": \"adaptive\", \"fallback\": {...}}` -- auto-select based on learned patterns")
+    force_extraction_strategy: Optional[StrictBool] = Field(default=None, description="When true, skip the auto-upgrade from Llm→LocalNer even if NER is available. Used for A/B comparison tests. Default: false.")
+    max_schema_tokens: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Maximum tokens for schema context passed to LLM")
+    ner_confidence_threshold: Optional[Union[StrictFloat, StrictInt]] = Field(default=None, description="NER confidence threshold (only used when extraction_strategy is \"local_ner\" or \"hybrid\") Entities below this threshold will be discarded (local_ner) or sent to LLM (hybrid) Default: 0.5")
+    ner_entity_labels: Optional[List[StrictStr]] = Field(default=None, description="Entity labels for NER extraction (optional, derives from schema if empty) Example: [\"Person\", \"Organization\", \"Location\", \"Drug\", \"Disease\"]")
+    ner_relation_confidence_threshold: Optional[Union[StrictFloat, StrictInt]] = Field(default=None, description="NER relation confidence threshold (0.0 - 1.0) Relations below this threshold will be discarded Default: 0.5")
+    ner_relation_labels: Optional[List[StrictStr]] = Field(default=None, description="Relation labels for NER relation extraction (optional) Used when extraction_strategy is \"local_ner\" with extract_relations=true Example: [\"works_at\", \"located_in\", \"founded\", \"ceo_of\"] If empty, default relations are used: works_at, located_in, part_of, etc.")
+    reject_anonymized_references: Optional[StrictBool] = Field(default=None, description="Reject anonymized reference patterns from case studies. Filters patterns like \"Monsieur X\", \"société A\", \"pays B\", \"Company A\". Only active when entity filtering is enabled. Default: true")
+    skip_fingerprint: Optional[StrictBool] = Field(default=None, description="Skip fingerprint check (force re-ingestion) When true, the document will be re-ingested even if it was previously ingested with the same content. Useful for re-extracting with different settings or after schema changes.")
+    skip_relation_completion: Optional[StrictBool] = Field(default=None, description="Skip the post-extraction LLM relation completion step. When true, skips the O(sort_pairs) LLM calls that find additional relations between entities after per-chunk extraction. Useful when the LLM API is slow or when relations from per-chunk extraction are sufficient. Default: false")
+    __properties: ClassVar[List[str]] = ["auto_create_sorts", "batch_size", "deduplication_threshold", "document_id", "domain_instructions", "enable_description_consolidation", "enable_entity_filtering", "enable_evidence_enrichment", "enable_focused_extraction", "enable_llm_coreference", "enable_schema_discovery", "enable_zero_degree_filtering", "evidence_derivation_config", "extract_relations", "extraction_strategy", "force_extraction_strategy", "max_schema_tokens", "ner_confidence_threshold", "ner_entity_labels", "ner_relation_confidence_threshold", "ner_relation_labels", "reject_anonymized_references", "skip_fingerprint", "skip_relation_completion"]
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        return json.dumps(to_jsonable_python(self.to_dict()))
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of IngestionConfigDto from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # override the default output from pydantic by calling `to_dict()` of evidence_derivation_config
+        if self.evidence_derivation_config:
+            _dict['evidence_derivation_config'] = self.evidence_derivation_config.to_dict()
+        # override the default output from pydantic by calling `to_dict()` of extraction_strategy
+        if self.extraction_strategy:
+            _dict['extraction_strategy'] = self.extraction_strategy.to_dict()
+        # set to None if document_id (nullable) is None
+        # and model_fields_set contains the field
+        if self.document_id is None and "document_id" in self.model_fields_set:
+            _dict['document_id'] = None
+
+        # set to None if evidence_derivation_config (nullable) is None
+        # and model_fields_set contains the field
+        if self.evidence_derivation_config is None and "evidence_derivation_config" in self.model_fields_set:
+            _dict['evidence_derivation_config'] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of IngestionConfigDto from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "auto_create_sorts": obj.get("auto_create_sorts"),
+            "batch_size": obj.get("batch_size"),
+            "deduplication_threshold": obj.get("deduplication_threshold"),
+            "document_id": obj.get("document_id"),
+            "domain_instructions": obj.get("domain_instructions"),
+            "enable_description_consolidation": obj.get("enable_description_consolidation"),
+            "enable_entity_filtering": obj.get("enable_entity_filtering"),
+            "enable_evidence_enrichment": obj.get("enable_evidence_enrichment"),
+            "enable_focused_extraction": obj.get("enable_focused_extraction"),
+            "enable_llm_coreference": obj.get("enable_llm_coreference"),
+            "enable_schema_discovery": obj.get("enable_schema_discovery"),
+            "enable_zero_degree_filtering": obj.get("enable_zero_degree_filtering"),
+            "evidence_derivation_config": EvidenceDerivationConfigDto.from_dict(obj["evidence_derivation_config"]) if obj.get("evidence_derivation_config") is not None else None,
+            "extract_relations": obj.get("extract_relations"),
+            "extraction_strategy": ExtractionStrategyDto.from_dict(obj["extraction_strategy"]) if obj.get("extraction_strategy") is not None else None,
+            "force_extraction_strategy": obj.get("force_extraction_strategy"),
+            "max_schema_tokens": obj.get("max_schema_tokens"),
+            "ner_confidence_threshold": obj.get("ner_confidence_threshold"),
+            "ner_entity_labels": obj.get("ner_entity_labels"),
+            "ner_relation_confidence_threshold": obj.get("ner_relation_confidence_threshold"),
+            "ner_relation_labels": obj.get("ner_relation_labels"),
+            "reject_anonymized_references": obj.get("reject_anonymized_references"),
+            "skip_fingerprint": obj.get("skip_fingerprint"),
+            "skip_relation_completion": obj.get("skip_relation_completion")
+        })
+        return _obj
+
+

reasoning_layer_python_sdk/generated/models/ingestion_session_response.py

@@ -0,0 +1,102 @@
+# coding: utf-8
+
+"""
+    OSF Knowledge Base API
+
+    Order-Sorted Feature logic knowledge base with fuzzy reasoning, inference, and constraint solving. Note: Some endpoints are hidden from Swagger due to recursive type limitations but work via API calls.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Any, ClassVar, Dict, List
+from typing_extensions import Annotated
+from uuid import UUID
+from reasoning_layer_python_sdk.generated.models.ingestion_session_status_dto import IngestionSessionStatusDto
+from typing import Optional, Set
+from typing_extensions import Self
+from pydantic_core import to_jsonable_python
+
+class IngestionSessionResponse(BaseModel):
+    """
+    Response from starting an ingestion session
+    """ # noqa: E501
+    created_at: datetime = Field(description="When session was created")
+    processed_documents: Annotated[int, Field(strict=True, ge=0)] = Field(description="Documents that have been processed")
+    session_id: UUID = Field(description="Unique session identifier")
+    status: IngestionSessionStatusDto = Field(description="Current status of the session")
+    total_documents: Annotated[int, Field(strict=True, ge=0)] = Field(description="Total documents in session")
+    updated_at: datetime = Field(description="When session was last updated")
+    __properties: ClassVar[List[str]] = ["created_at", "processed_documents", "session_id", "status", "total_documents", "updated_at"]
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        return json.dumps(to_jsonable_python(self.to_dict()))
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of IngestionSessionResponse from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of IngestionSessionResponse from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "created_at": obj.get("created_at"),
+            "processed_documents": obj.get("processed_documents"),
+            "session_id": obj.get("session_id"),
+            "status": obj.get("status"),
+            "total_documents": obj.get("total_documents"),
+            "updated_at": obj.get("updated_at")
+        })
+        return _obj
+
+

reasoning_layer_python_sdk/generated/models/ingestion_session_status_dto.py

@@ -0,0 +1,39 @@
+# coding: utf-8
+
+"""
+    OSF Knowledge Base API
+
+    Order-Sorted Feature logic knowledge base with fuzzy reasoning, inference, and constraint solving. Note: Some endpoints are hidden from Swagger due to recursive type limitations but work via API calls.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import json
+from enum import Enum
+from typing_extensions import Self
+
+
+class IngestionSessionStatusDto(str, Enum):
+    """
+    Session status enum
+    """
+
+    """
+    allowed enum values
+    """
+    ACTIVE = 'active'
+    PAUSED = 'paused'
+    COMPLETE = 'complete'
+    FAILED = 'failed'
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self:
+        """Create an instance of IngestionSessionStatusDto from a JSON string"""
+        return cls(json.loads(json_str))
+
+

reasoning_layer_python_sdk/generated/models/ingestion_stats_dto.py

@@ -0,0 +1,190 @@
+# coding: utf-8
+
+"""
+    OSF Knowledge Base API
+
+    Order-Sorted Feature logic knowledge base with fuzzy reasoning, inference, and constraint solving. Note: Some endpoints are hidden from Swagger due to recursive type limitations but work via API calls.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictFloat, StrictInt, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional, Union
+from typing_extensions import Annotated
+from uuid import UUID
+from reasoning_layer_python_sdk.generated.models.alignment_stats_dto import AlignmentStatsDto
+from reasoning_layer_python_sdk.generated.models.chunk_failure_dto import ChunkFailureDto
+from reasoning_layer_python_sdk.generated.models.community_stats_dto import CommunityStatsDto
+from reasoning_layer_python_sdk.generated.models.entity_merge_audit_dto import EntityMergeAuditDto
+from reasoning_layer_python_sdk.generated.models.grounding_stats_dto import GroundingStatsDto
+from reasoning_layer_python_sdk.generated.models.pipeline_quality_stats_dto import PipelineQualityStatsDto
+from reasoning_layer_python_sdk.generated.models.token_usage_dto import TokenUsageDto
+from typing import Optional, Set
+from typing_extensions import Self
+from pydantic_core import to_jsonable_python
+
+class IngestionStatsDto(BaseModel):
+    """
+    Ingestion statistics
+    """ # noqa: E501
+    alignment_stats: Optional[AlignmentStatsDto] = Field(default=None, description="Source text alignment statistics (entity-to-source mapping quality)")
+    chunks_failed: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of chunks that failed extraction")
+    chunks_processed: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of text chunks processed")
+    community_stats: Optional[CommunityStatsDto] = Field(default=None, description="Community detection statistics (GraphRAG-style clustering)")
+    entities_created: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of new entities created")
+    entities_extracted: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of entities extracted from text")
+    entities_filtered_low_quality: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Number of entities filtered out due to low-quality names")
+    entities_merged: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of entities merged (deduplicated)")
+    entities_pending_review: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of entities pending human review")
+    entity_merge_audit: Optional[List[EntityMergeAuditDto]] = Field(default=None, description="Audit trail for substring-based entity merges (surface-form coreference). E.g., \"Brown v. Board\" merged into \"Brown v. Board of Education of Topeka\".")
+    estimated_cost_usd: Optional[Union[StrictFloat, StrictInt]] = Field(default=None, description="Estimated USD cost of LLM API calls (if model pricing is available)")
+    failed_chunks: Optional[List[ChunkFailureDto]] = Field(default=None, description="Details of failed chunks (first 5)")
+    grounding_stats: Optional[GroundingStatsDto] = Field(default=None, description="Entity grounding statistics (linking to external ontologies)")
+    model: Optional[StrictStr] = Field(default=None, description="LLM model used for extraction (e.g., \"claude-3-5-haiku-20241022\")")
+    pipeline_quality: Optional[PipelineQualityStatsDto] = Field(default=None, description="Pipeline quality statistics (inference rules, validation, feedback loop)")
+    processing_time_ms: Annotated[int, Field(strict=True, ge=0)] = Field(description="Processing time in milliseconds")
+    references_resolved: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of references resolved")
+    references_unresolved: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of unresolved references (residuated - waiting for more information)")
+    relations_extracted: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of relations extracted from text")
+    relations_integrated: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of relations integrated as features on entities")
+    relations_orphaned: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Number of suspended relations that remained unresolved (orphaned)")
+    relations_resumed: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Number of suspended relations successfully resumed when endpoints became available")
+    relations_suspended: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Number of relations suspended (endpoints not yet available)")
+    sort_names: List[StrictStr] = Field(description="Names of created/reused sorts")
+    sorts_created: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of new sorts created")
+    sorts_reused: Annotated[int, Field(strict=True, ge=0)] = Field(description="Number of existing sorts reused")
+    term_ids: List[UUID] = Field(description="IDs of created/updated terms")
+    token_usage: Optional[TokenUsageDto] = Field(default=None, description="Token usage from LLM API calls during this ingestion")
+    __properties: ClassVar[List[str]] = ["alignment_stats", "chunks_failed", "chunks_processed", "community_stats", "entities_created", "entities_extracted", "entities_filtered_low_quality", "entities_merged", "entities_pending_review", "entity_merge_audit", "estimated_cost_usd", "failed_chunks", "grounding_stats", "model", "pipeline_quality", "processing_time_ms", "references_resolved", "references_unresolved", "relations_extracted", "relations_integrated", "relations_orphaned", "relations_resumed", "relations_suspended", "sort_names", "sorts_created", "sorts_reused", "term_ids", "token_usage"]
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        return json.dumps(to_jsonable_python(self.to_dict()))
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of IngestionStatsDto from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # override the default output from pydantic by calling `to_dict()` of alignment_stats
+        if self.alignment_stats:
+            _dict['alignment_stats'] = self.alignment_stats.to_dict()
+        # override the default output from pydantic by calling `to_dict()` of community_stats
+        if self.community_stats:
+            _dict['community_stats'] = self.community_stats.to_dict()
+        # override the default output from pydantic by calling `to_dict()` of each item in entity_merge_audit (list)
+        _items = []
+        if self.entity_merge_audit:
+            for _item_entity_merge_audit in self.entity_merge_audit:
+                if _item_entity_merge_audit:
+                    _items.append(_item_entity_merge_audit.to_dict())
+            _dict['entity_merge_audit'] = _items
+        # override the default output from pydantic by calling `to_dict()` of each item in failed_chunks (list)
+        _items = []
+        if self.failed_chunks:
+            for _item_failed_chunks in self.failed_chunks:
+                if _item_failed_chunks:
+                    _items.append(_item_failed_chunks.to_dict())
+            _dict['failed_chunks'] = _items
+        # override the default output from pydantic by calling `to_dict()` of grounding_stats
+        if self.grounding_stats:
+            _dict['grounding_stats'] = self.grounding_stats.to_dict()
+        # override the default output from pydantic by calling `to_dict()` of pipeline_quality
+        if self.pipeline_quality:
+            _dict['pipeline_quality'] = self.pipeline_quality.to_dict()
+        # override the default output from pydantic by calling `to_dict()` of token_usage
+        if self.token_usage:
+            _dict['token_usage'] = self.token_usage.to_dict()
+        # set to None if estimated_cost_usd (nullable) is None
+        # and model_fields_set contains the field
+        if self.estimated_cost_usd is None and "estimated_cost_usd" in self.model_fields_set:
+            _dict['estimated_cost_usd'] = None
+
+        # set to None if model (nullable) is None
+        # and model_fields_set contains the field
+        if self.model is None and "model" in self.model_fields_set:
+            _dict['model'] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of IngestionStatsDto from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "alignment_stats": AlignmentStatsDto.from_dict(obj["alignment_stats"]) if obj.get("alignment_stats") is not None else None,
+            "chunks_failed": obj.get("chunks_failed"),
+            "chunks_processed": obj.get("chunks_processed"),
+            "community_stats": CommunityStatsDto.from_dict(obj["community_stats"]) if obj.get("community_stats") is not None else None,
+            "entities_created": obj.get("entities_created"),
+            "entities_extracted": obj.get("entities_extracted"),
+            "entities_filtered_low_quality": obj.get("entities_filtered_low_quality"),
+            "entities_merged": obj.get("entities_merged"),
+            "entities_pending_review": obj.get("entities_pending_review"),
+            "entity_merge_audit": [EntityMergeAuditDto.from_dict(_item) for _item in obj["entity_merge_audit"]] if obj.get("entity_merge_audit") is not None else None,
+            "estimated_cost_usd": obj.get("estimated_cost_usd"),
+            "failed_chunks": [ChunkFailureDto.from_dict(_item) for _item in obj["failed_chunks"]] if obj.get("failed_chunks") is not None else None,
+            "grounding_stats": GroundingStatsDto.from_dict(obj["grounding_stats"]) if obj.get("grounding_stats") is not None else None,
+            "model": obj.get("model"),
+            "pipeline_quality": PipelineQualityStatsDto.from_dict(obj["pipeline_quality"]) if obj.get("pipeline_quality") is not None else None,
+            "processing_time_ms": obj.get("processing_time_ms"),
+            "references_resolved": obj.get("references_resolved"),
+            "references_unresolved": obj.get("references_unresolved"),
+            "relations_extracted": obj.get("relations_extracted"),
+            "relations_integrated": obj.get("relations_integrated"),
+            "relations_orphaned": obj.get("relations_orphaned"),
+            "relations_resumed": obj.get("relations_resumed"),
+            "relations_suspended": obj.get("relations_suspended"),
+            "sort_names": obj.get("sort_names"),
+            "sorts_created": obj.get("sorts_created"),
+            "sorts_reused": obj.get("sorts_reused"),
+            "term_ids": obj.get("term_ids"),
+            "token_usage": TokenUsageDto.from_dict(obj["token_usage"]) if obj.get("token_usage") is not None else None
+        })
+        return _obj
+
+