nucliadb-models 6.9.7.post5550__py3-none-any.whl → 6.10.0.post5792__py3-none-any.whl

nucliadb_models/notifications.py

@@ -49,7 +49,7 @@ class ResourceIndexed(BaseModel):
     seqid: int = Field(
         ...,
         title="Sequence ID",
-        description="Sequence ID of the resource operation. This can be used to track completion of specific operations.",  # noqa: E501
+        description="Sequence ID of the resource operation. This can be used to track completion of specific operations.",
     )
 
 
@@ -59,7 +59,7 @@ class ResourceWritten(BaseModel):
     seqid: int = Field(
         ...,
         title="Sequence ID",
-        description="Sequence ID of the resource operation. This can be used to track completion of specific operations.",  # noqa: E501
+        description="Sequence ID of the resource operation. This can be used to track completion of specific operations.",
     )
     operation: ResourceOperationType = Field(
         ..., title="Operation", description="Type of resource write operation."
@@ -77,7 +77,7 @@ class ResourceProcessed(BaseModel):
     seqid: int = Field(
         ...,
         title="Sequence ID",
-        description="Sequence ID of the resource operation. This can be used to track completion of specific operations.",  # noqa: E501
+        description="Sequence ID of the resource operation. This can be used to track completion of specific operations.",
     )
     ingestion_succeeded: bool = Field(
         default=True,

nucliadb_models/processing.py

@@ -12,10 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import Optional
 
 from pydantic import BaseModel
 
 
 class PushProcessingOptions(BaseModel):
-    ml_text: Optional[bool] = True
+    ml_text: bool | None = True

nucliadb_models/resource.py

@@ -16,7 +16,7 @@
 import string
 from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
@@ -72,44 +72,35 @@ class ExtractedDataTypeName(str, Enum):
     QA = "question_answers"
 
 
-class ReleaseChannel(str, Enum):
-    """
-    Deprecated. No longer used.
-    """
-
-    STABLE = "STABLE"
-    EXPERIMENTAL = "EXPERIMENTAL"
-
-
 class KnowledgeBoxConfig(BaseModel):
-    slug: Optional[SlugString] = Field(
+    slug: SlugString | None = Field(
         default=None, title="Slug", description="Slug for the Knowledge Box."
     )
-    title: Optional[str] = Field(default=None, title="Title", description="Title for the Knowledge Box.")
-    description: Optional[str] = Field(
+    title: str | None = Field(default=None, title="Title", description="Title for the Knowledge Box.")
+    description: str | None = Field(
         default=None,
         title="Description",
         description="Description for the Knowledge Box.",
     )
-    learning_configuration: Optional[Dict[str, Any]] = Field(
+    learning_configuration: dict[str, Any] | None = Field(
         default=None,
         title="Learning Configuration",
-        description="Learning configuration for the Knowledge Box. If provided, NucliaDB will set the learning configuration for the Knowledge Box.",  # noqa: E501
+        description="Learning configuration for the Knowledge Box. If provided, NucliaDB will set the learning configuration for the Knowledge Box.",
     )
 
-    external_index_provider: Optional[ExternalIndexProvider] = Field(
+    external_index_provider: ExternalIndexProvider | None = Field(
         default=None,
         title="External Index Provider",
         description="External index provider for the Knowledge Box.",
     )
 
-    configured_external_index_provider: Optional[dict[str, Any]] = Field(
+    configured_external_index_provider: dict[str, Any] | None = Field(
         default=None,
         title="Configured External Index Provider",
         description="Metadata for the configured external index provider (if any)",
     )
 
-    similarity: Optional[VectorSimilarity] = Field(
+    similarity: VectorSimilarity | None = Field(
         default=None,
         description="This field is deprecated. Use 'learning_configuration' instead.",
     )
@@ -126,7 +117,7 @@ class KnowledgeBoxConfig(BaseModel):
 
     @field_validator("slug")
     @classmethod
-    def id_check(cls, v: Optional[str]) -> Optional[str]:
+    def id_check(cls, v: str | None) -> str | None:
         if v is None:
             return v
 
@@ -145,7 +136,7 @@ class KnowledgeBoxConfig(BaseModel):
 
 
 class KnowledgeBoxObjSummary(BaseModel):
-    slug: Optional[SlugString] = None
+    slug: SlugString | None = None
     uuid: str
 
 
@@ -158,25 +149,25 @@ class KnowledgeBoxObj(BaseModel):
     The API representation of a Knowledge Box object.
     """
 
-    slug: Optional[SlugString] = None
+    slug: SlugString | None = None
     uuid: str
-    config: Optional[KnowledgeBoxConfig] = None
-    model: Optional[SemanticModelMetadata] = None
+    config: KnowledgeBoxConfig | None = None
+    model: SemanticModelMetadata | None = None
 
 
 class KnowledgeBoxList(BaseModel):
-    kbs: List[KnowledgeBoxObjSummary] = []
+    kbs: list[KnowledgeBoxObjSummary] = []
 
 
 # Resources
 
 
 class ExtractedData(BaseModel):
-    text: Optional[ExtractedText] = None
-    metadata: Optional[FieldComputedMetadata] = None
-    large_metadata: Optional[LargeComputedMetadata] = None
-    vectors: Optional[VectorObject] = None
-    question_answers: Optional[FieldQuestionAnswers] = None
+    text: ExtractedText | None = None
+    metadata: FieldComputedMetadata | None = None
+    large_metadata: LargeComputedMetadata | None = None
+    vectors: VectorObject | None = None
+    question_answers: FieldQuestionAnswers | None = None
 
 
 class TextFieldExtractedData(ExtractedData):
@@ -184,32 +175,31 @@ class TextFieldExtractedData(ExtractedData):
 
 
 class FileFieldExtractedData(ExtractedData):
-    file: Optional[FileExtractedData] = None
+    file: FileExtractedData | None = None
 
 
 class LinkFieldExtractedData(ExtractedData):
-    link: Optional[LinkExtractedData] = None
+    link: LinkExtractedData | None = None
 
 
 class ConversationFieldExtractedData(ExtractedData):
     pass
 
 
-ExtractedDataType = Optional[
-    Union[
-        TextFieldExtractedData,
-        FileFieldExtractedData,
-        LinkFieldExtractedData,
-        ConversationFieldExtractedData,
-    ]
-]
+ExtractedDataType = (
+    TextFieldExtractedData
+    | FileFieldExtractedData
+    | LinkFieldExtractedData
+    | ConversationFieldExtractedData
+    | None
+)
 
 
 class Error(BaseModel):
     body: str
     code: int
     code_str: str
-    created: Optional[datetime]
+    created: datetime | None
     severity: str
 
 
@@ -217,51 +207,51 @@ class FieldData(BaseModel): ...
 
 
 class TextFieldData(BaseModel):
-    value: Optional[FieldText] = None
-    extracted: Optional[TextFieldExtractedData] = None
-    error: Optional[Error] = None
-    status: Optional[str] = None
-    errors: Optional[list[Error]] = None
+    value: FieldText | None = None
+    extracted: TextFieldExtractedData | None = None
+    error: Error | None = None
+    status: str | None = None
+    errors: list[Error] | None = None
 
 
 class FileFieldData(BaseModel):
-    value: Optional[FieldFile] = None
-    extracted: Optional[FileFieldExtractedData] = None
-    error: Optional[Error] = None
-    status: Optional[str] = None
-    errors: Optional[list[Error]] = None
+    value: FieldFile | None = None
+    extracted: FileFieldExtractedData | None = None
+    error: Error | None = None
+    status: str | None = None
+    errors: list[Error] | None = None
 
 
 class LinkFieldData(BaseModel):
-    value: Optional[FieldLink] = None
-    extracted: Optional[LinkFieldExtractedData] = None
-    error: Optional[Error] = None
-    status: Optional[str] = None
-    errors: Optional[list[Error]] = None
+    value: FieldLink | None = None
+    extracted: LinkFieldExtractedData | None = None
+    error: Error | None = None
+    status: str | None = None
+    errors: list[Error] | None = None
 
 
 class ConversationFieldData(BaseModel):
-    value: Optional[FieldConversation] = None
-    extracted: Optional[ConversationFieldExtractedData] = None
-    error: Optional[Error] = None
-    status: Optional[str] = None
-    errors: Optional[list[Error]] = None
+    value: FieldConversation | None = None
+    extracted: ConversationFieldExtractedData | None = None
+    error: Error | None = None
+    status: str | None = None
+    errors: list[Error] | None = None
 
 
 class GenericFieldData(BaseModel):
-    value: Optional[str] = None
-    extracted: Optional[TextFieldExtractedData] = None
-    error: Optional[Error] = None
-    status: Optional[str] = None
-    errors: Optional[list[Error]] = None
+    value: str | None = None
+    extracted: TextFieldExtractedData | None = None
+    error: Error | None = None
+    status: str | None = None
+    errors: list[Error] | None = None
 
 
 class ResourceData(BaseModel):
-    texts: Optional[Dict[str, TextFieldData]] = None
-    files: Optional[Dict[str, FileFieldData]] = None
-    links: Optional[Dict[str, LinkFieldData]] = None
-    conversations: Optional[Dict[str, ConversationFieldData]] = None
-    generics: Optional[Dict[str, GenericFieldData]] = None
+    texts: dict[str, TextFieldData] | None = None
+    files: dict[str, FileFieldData] | None = None
+    links: dict[str, LinkFieldData] | None = None
+    conversations: dict[str, ConversationFieldData] | None = None
+    generics: dict[str, GenericFieldData] | None = None
 
 
 class QueueType(str, Enum):
@@ -273,29 +263,29 @@ class Resource(BaseModel):
     id: str
 
     # This first block of attributes correspond to Basic fields
-    slug: Optional[str] = None
-    title: Optional[str] = None
-    summary: Optional[str] = None
-    icon: Optional[str] = None
-    thumbnail: Optional[str] = None
-    metadata: Optional[Metadata] = None
-    usermetadata: Optional[UserMetadata] = None
-    fieldmetadata: Optional[List[UserFieldMetadata]] = None
-    computedmetadata: Optional[ComputedMetadata] = None
-    created: Optional[datetime] = None
-    modified: Optional[datetime] = None
-    last_seqid: Optional[int] = None
-    last_account_seq: Optional[int] = None
-    queue: Optional[QueueType] = None
-    hidden: Optional[bool] = None
-
-    origin: Optional[Origin] = None
-    extra: Optional[Extra] = None
-    relations: Optional[List[Relation]] = None
-
-    data: Optional[ResourceData] = None
-
-    security: Optional[ResourceSecurity] = Field(
+    slug: str | None = None
+    title: str | None = None
+    summary: str | None = None
+    icon: str | None = None
+    thumbnail: str | None = None
+    metadata: Metadata | None = None
+    usermetadata: UserMetadata | None = None
+    fieldmetadata: list[UserFieldMetadata] | None = None
+    computedmetadata: ComputedMetadata | None = None
+    created: datetime | None = None
+    modified: datetime | None = None
+    last_seqid: int | None = None
+    last_account_seq: int | None = None
+    queue: QueueType | None = None
+    hidden: bool | None = None
+
+    origin: Origin | None = None
+    extra: Extra | None = None
+    relations: list[Relation] | None = None
+
+    data: ResourceData | None = None
+
+    security: ResourceSecurity | None = Field(
         default=None,
         title="Security",
         description="Resource security metadata",
@@ -309,19 +299,12 @@ class ResourcePagination(BaseModel):
 
 
 class ResourceList(BaseModel):
-    resources: List[Resource]
+    resources: list[Resource]
     pagination: ResourcePagination
 
 
 class ResourceField(BaseModel):
     field_type: FieldTypeName
     field_id: str
-    value: Optional[
-        Union[
-            FieldText,
-            FieldFile,
-            FieldLink,
-            Conversation,
-        ]
-    ] = None
+    value: FieldText | FieldFile | FieldLink | Conversation | None = None
     extracted: ExtractedDataType = None

nucliadb_models/retrieval.py

@@ -0,0 +1,147 @@
+# Copyright 2025 Bosutech XXI S.L.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from nucliadb_models.filters import FilterExpression
+from nucliadb_models.graph.requests import GraphPathQuery
+from nucliadb_models.search import RankFusion, RankFusionName, SearchParamDefaults
+from nucliadb_models.security import RequestSecurity
+
+
+class KeywordQuery(BaseModel):
+    query: str
+    min_score: float = 0.0
+    with_synonyms: bool = False
+
+
+class SemanticQuery(BaseModel):
+    query: list[float]
+    vectorset: str
+    min_score: float = -1.0
+
+
+class GraphQuery(BaseModel):
+    query: GraphPathQuery
+
+
+class Query(BaseModel):
+    keyword: KeywordQuery | None = None
+    semantic: SemanticQuery | None = None
+    graph: GraphQuery | None = None
+
+
+class Filters(BaseModel):
+    filter_expression: FilterExpression | None = (
+        SearchParamDefaults.filter_expression.to_pydantic_field()
+    )
+    show_hidden: bool = SearchParamDefaults.show_hidden.to_pydantic_field()
+    security: RequestSecurity | None = None
+    with_duplicates: bool = False
+
+
+class RetrievalRequest(BaseModel):
+    query: Query
+    top_k: int = Field(default=20, gt=0, le=500)
+    filters: Filters = Field(default_factory=Filters)
+    rank_fusion: RankFusionName | RankFusion = Field(default=RankFusionName.RECIPROCAL_RANK_FUSION)
+
+
+class ScoreSource(str, Enum):
+    INDEX = "index"
+    RANK_FUSION = "rank_fusion"
+    RERANKER = "reranker"
+
+
+class ScoreType(str, Enum):
+    SEMANTIC = "semantic"
+    KEYWORD = "keyword"
+    GRAPH = "graph"
+    RRF = "rrf"
+    WCOMB_SUM = "wCombSUM"
+    DEFAULT_RERANKER = "default_reranker"
+
+
+class KeywordScore(BaseModel):
+    score: float
+    source: Literal[ScoreSource.INDEX] = ScoreSource.INDEX
+    type: Literal[ScoreType.KEYWORD] = ScoreType.KEYWORD
+
+
+class SemanticScore(BaseModel):
+    score: float
+    source: Literal[ScoreSource.INDEX] = ScoreSource.INDEX
+    type: Literal[ScoreType.SEMANTIC] = ScoreType.SEMANTIC
+
+
+class GraphScore(BaseModel):
+    score: float
+    source: Literal[ScoreSource.INDEX] = ScoreSource.INDEX
+    type: Literal[ScoreType.GRAPH] = ScoreType.GRAPH
+
+
+class RrfScore(BaseModel):
+    score: float
+    source: Literal[ScoreSource.RANK_FUSION] = ScoreSource.RANK_FUSION
+    type: Literal[ScoreType.RRF] = ScoreType.RRF
+
+
+class WeightedCombSumScore(BaseModel):
+    score: float
+    source: Literal[ScoreSource.RANK_FUSION] = ScoreSource.RANK_FUSION
+    type: Literal[ScoreType.WCOMB_SUM] = ScoreType.WCOMB_SUM
+
+
+class RerankerScore(BaseModel):
+    score: float
+    source: Literal[ScoreSource.RERANKER] = ScoreSource.RERANKER
+    type: Literal[ScoreType.DEFAULT_RERANKER] = ScoreType.DEFAULT_RERANKER
+
+
+Score = KeywordScore | SemanticScore | GraphScore | RrfScore | WeightedCombSumScore | RerankerScore
+
+
+class Scores(BaseModel):
+    value: float
+    source: ScoreSource
+    type: ScoreType
+    history: list[Score]
+
+
+class Metadata(BaseModel):
+    field_labels: list[str]
+    paragraph_labels: list[str]
+
+    is_an_image: bool
+    is_a_table: bool
+
+    # for extracted from visual content (ocr, inception, tables)
+    source_file: str | None
+
+    # for documents (pdf, docx...) only
+    page: int | None
+    in_page_with_visual: bool | None
+
+
+class RetrievalMatch(BaseModel):
+    id: str
+    score: Scores
+    metadata: Metadata
+
+
+class RetrievalResponse(BaseModel):
+    matches: list[RetrievalMatch]