usecortex-ai 0.3.4__py3-none-any.whl → 0.3.6__py3-none-any.whl

usecortex_ai/sources/raw_client.py

@@ -16,6 +16,7 @@ from ..errors.service_unavailable_error import ServiceUnavailableError
 from ..errors.unauthorized_error import UnauthorizedError
 from ..errors.unprocessable_entity_error import UnprocessableEntityError
 from ..types.actual_error_response import ActualErrorResponse
+from ..types.graph_relations_response import GraphRelationsResponse
 from ..types.list_sources_response import ListSourcesResponse
 
 # this is used as the default value for optional parameters
@@ -297,6 +298,142 @@ class RawSourcesClient:
             raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
         raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
 
+    def get_graph_relations_by_id(
+        self,
+        *,
+        source_id: str,
+        tenant_id: typing.Optional[str] = None,
+        sub_tenant_id: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> HttpResponse[GraphRelationsResponse]:
+        """
+        Retrieve relations for a specific source.
+
+        Use this endpoint to fetch all relations associated with a specific source. This is useful when you need to understand the relationships between entities within a source.
+
+        Provide the source ID in the request body along with your tenant information to get the relations for that source.
+
+        Parameters
+        ----------
+        source_id : str
+            The source ID to fetch relations for
+
+        tenant_id : typing.Optional[str]
+            Unique identifier for the tenant/organization
+
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        HttpResponse[GraphRelationsResponse]
+            Successful Response
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "list/graph_relations_by_id",
+            method="GET",
+            params={
+                "source_id": source_id,
+                "tenant_id": tenant_id,
+                "sub_tenant_id": sub_tenant_id,
+            },
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    GraphRelationsResponse,
+                    parse_obj_as(
+                        type_=GraphRelationsResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 422:
+                raise UnprocessableEntityError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 503:
+                raise ServiceUnavailableError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
 
 class AsyncRawSourcesClient:
     def __init__(self, *, client_wrapper: AsyncClientWrapper):
@@ -572,3 +709,139 @@ class AsyncRawSourcesClient:
         except JSONDecodeError:
             raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
         raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def get_graph_relations_by_id(
+        self,
+        *,
+        source_id: str,
+        tenant_id: typing.Optional[str] = None,
+        sub_tenant_id: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncHttpResponse[GraphRelationsResponse]:
+        """
+        Retrieve relations for a specific source.
+
+        Use this endpoint to fetch all relations associated with a specific source. This is useful when you need to understand the relationships between entities within a source.
+
+        Provide the source ID in the request body along with your tenant information to get the relations for that source.
+
+        Parameters
+        ----------
+        source_id : str
+            The source ID to fetch relations for
+
+        tenant_id : typing.Optional[str]
+            Unique identifier for the tenant/organization
+
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncHttpResponse[GraphRelationsResponse]
+            Successful Response
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "list/graph_relations_by_id",
+            method="GET",
+            params={
+                "source_id": source_id,
+                "tenant_id": tenant_id,
+                "sub_tenant_id": sub_tenant_id,
+            },
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    GraphRelationsResponse,
+                    parse_obj_as(
+                        type_=GraphRelationsResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 403:
+                raise ForbiddenError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 422:
+                raise UnprocessableEntityError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 503:
+                raise ServiceUnavailableError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ActualErrorResponse,
+                        parse_obj_as(
+                            type_=ActualErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

usecortex_ai/types/__init__.py

@@ -10,6 +10,7 @@ from .batch_upload_data import BatchUploadData
 from .bm_25_operator_type import Bm25OperatorType
 from .body_scrape_webpage_upload_scrape_webpage_post import BodyScrapeWebpageUploadScrapeWebpagePost
 from .body_update_scrape_job_upload_update_webpage_patch import BodyUpdateScrapeJobUploadUpdateWebpagePatch
+from .chunk_graph_relations_response import ChunkGraphRelationsResponse
 from .content_model import ContentModel
 from .delete_memory_request import DeleteMemoryRequest
 from .delete_sources import DeleteSources
@@ -19,19 +20,26 @@ from .embeddings_create_collection_data import EmbeddingsCreateCollectionData
 from .embeddings_delete_data import EmbeddingsDeleteData
 from .embeddings_get_data import EmbeddingsGetData
 from .embeddings_search_data import EmbeddingsSearchData
+from .entity import Entity
 from .error_response import ErrorResponse
 from .extended_context import ExtendedContext
 from .fetch_content_data import FetchContentData
 from .file_upload_result import FileUploadResult
-from .generate_user_memory_response import GenerateUserMemoryResponse
+from .graph_relations_response import GraphRelationsResponse
 from .http_validation_error import HttpValidationError
 from .list_sources_response import ListSourcesResponse
 from .list_user_memories_response import ListUserMemoriesResponse
 from .markdown_upload_request import MarkdownUploadRequest
+from .path_triplet import PathTriplet
 from .processing_status import ProcessingStatus
 from .related_chunk import RelatedChunk
+from .relation_evidence import RelationEvidence
 from .relations import Relations
+from .retrieve_mode import RetrieveMode
+from .retrieve_response import RetrieveResponse
 from .retrieve_user_memory_response import RetrieveUserMemoryResponse
+from .scored_path_response import ScoredPathResponse
+from .scored_triplet_response import ScoredTripletResponse
 from .search_chunk import SearchChunk
 from .single_upload_data import SingleUploadData
 from .source import Source
@@ -39,9 +47,12 @@ from .source_model import SourceModel
 from .sub_tenant_ids_data import SubTenantIdsData
 from .tenant_create_data import TenantCreateData
 from .tenant_stats import TenantStats
+from .triple_with_evidence import TripleWithEvidence
+from .user_assistant_pair import UserAssistantPair
 from .user_memory import UserMemory
 from .validation_error import ValidationError
 from .validation_error_loc_item import ValidationErrorLocItem
+from .webpage_scrape_request import WebpageScrapeRequest
 
 __all__ = [
     "ActualErrorResponse",
@@ -52,6 +63,7 @@ __all__ = [
     "Bm25OperatorType",
     "BodyScrapeWebpageUploadScrapeWebpagePost",
     "BodyUpdateScrapeJobUploadUpdateWebpagePatch",
+    "ChunkGraphRelationsResponse",
     "ContentModel",
     "DeleteMemoryRequest",
     "DeleteSources",
@@ -61,19 +73,26 @@ __all__ = [
     "EmbeddingsDeleteData",
     "EmbeddingsGetData",
     "EmbeddingsSearchData",
+    "Entity",
     "ErrorResponse",
     "ExtendedContext",
     "FetchContentData",
     "FileUploadResult",
-    "GenerateUserMemoryResponse",
+    "GraphRelationsResponse",
     "HttpValidationError",
     "ListSourcesResponse",
     "ListUserMemoriesResponse",
     "MarkdownUploadRequest",
+    "PathTriplet",
     "ProcessingStatus",
     "RelatedChunk",
+    "RelationEvidence",
     "Relations",
+    "RetrieveMode",
+    "RetrieveResponse",
     "RetrieveUserMemoryResponse",
+    "ScoredPathResponse",
+    "ScoredTripletResponse",
     "SearchChunk",
     "SingleUploadData",
     "Source",
@@ -81,7 +100,10 @@ __all__ = [
     "SubTenantIdsData",
     "TenantCreateData",
     "TenantStats",
+    "TripleWithEvidence",
+    "UserAssistantPair",
     "UserMemory",
     "ValidationError",
     "ValidationErrorLocItem",
+    "WebpageScrapeRequest",
 ]

usecortex_ai/types/add_user_memory_response.py

@@ -21,11 +21,16 @@ class AddUserMemoryResponse(UniversalBaseModel):
     Confirms whether the memory was successfully stored in the system
     """
 
-    memory_id: typing.Optional[str] = pydantic.Field(default=None)
+    memory_id: str = pydantic.Field()
     """
     Unique identifier assigned to the newly created memory
     """
 
+    chunks_created: typing.Optional[int] = pydantic.Field(default=None)
+    """
+    Total number of chunks created from the memory
+    """
+
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
     else:

usecortex_ai/types/chunk_graph_relations_response.py

@@ -0,0 +1,33 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .scored_path_response import ScoredPathResponse
+from .scored_triplet_response import ScoredTripletResponse
+
+
+class ChunkGraphRelationsResponse(UniversalBaseModel):
+    """
+    Graph relations with group_id -> triplet mapping
+    """
+
+    entity_paths: typing.Optional[typing.List[ScoredPathResponse]] = pydantic.Field(default=None)
+    """
+    Multi-hop paths connecting entities from the query, reranked by relevance. Each path is a chain of connected triplets.
+    """
+
+    chunk_triplets: typing.Optional[typing.Dict[str, ScoredTripletResponse]] = pydantic.Field(default=None)
+    """
+    Mapping of group_id to scored triplet. Use chunk.graph_triplet_ids to find which groups belong to a chunk.
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

usecortex_ai/types/entity.py

@@ -0,0 +1,42 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+
+
+class Entity(UniversalBaseModel):
+    name: str = pydantic.Field()
+    """
+    Normalized entity name
+    """
+
+    type: str = pydantic.Field()
+    """
+    PERSON, ORGANIZATION, PROJECT, PRODUCT, ERROR_CODE, etc.
+    """
+
+    namespace: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Context category like 'employees', 'projects'
+    """
+
+    identifier: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Unique ID like email, employee_id, URL
+    """
+
+    entity_id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Internal unique entity ID from graph database
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

usecortex_ai/types/extended_context.py

@@ -4,12 +4,9 @@ import typing
 
 import pydantic
 from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
-from .related_chunk import RelatedChunk
 
 
 class ExtendedContext(UniversalBaseModel):
-    relations: typing.Optional[typing.List[RelatedChunk]] = None
-
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
     else:

usecortex_ai/types/graph_relations_response.py

@@ -0,0 +1,33 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .triple_with_evidence import TripleWithEvidence
+
+
+class GraphRelationsResponse(UniversalBaseModel):
+    relations: typing.List[typing.Optional[TripleWithEvidence]] = pydantic.Field()
+    """
+    List of relations retrieved
+    """
+
+    success: typing.Optional[bool] = pydantic.Field(default=None)
+    """
+    Indicates whether the request was successful
+    """
+
+    message: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Response message describing the operation result
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

usecortex_ai/types/{generate_user_memory_response.py → path_triplet.py}

@@ -4,22 +4,28 @@ import typing
 
 import pydantic
 from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
-from .user_memory import UserMemory
+from .entity import Entity
+from .relation_evidence import RelationEvidence
 
 
-class GenerateUserMemoryResponse(UniversalBaseModel):
+class PathTriplet(UniversalBaseModel):
     """
-    Response model for AI-generated user memories.
+    Single triplet within a path (without score, as the path is scored as a whole)
     """
 
-    success: bool = pydantic.Field()
+    source: Entity = pydantic.Field()
     """
-    Indicates whether the memory generation operation was successful
+    Source entity
     """
 
-    generated_user_memories: typing.Optional[typing.List[UserMemory]] = pydantic.Field(default=None)
+    target: Entity = pydantic.Field()
     """
-    Array of AI-generated memories based on your query and user context
+    Target entity
+    """
+
+    relation: RelationEvidence = pydantic.Field()
+    """
+    Relation between entities
     """
 
     if IS_PYDANTIC_V2:

usecortex_ai/types/relation_evidence.py

@@ -0,0 +1,53 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+
+
+class RelationEvidence(UniversalBaseModel):
+    relationship_id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Unique identifier for this specific relationship edge in the graph. The combination of source entity, target entity, and relationship_id allows disambiguation between multiple relations between the same source and target entities.
+    """
+
+    canonical_predicate: str = pydantic.Field()
+    """
+    Relationship phrase like 'works for', 'reports to'
+    """
+
+    raw_predicate: str = pydantic.Field()
+    """
+    Original predicate from text
+    """
+
+    context: str = pydantic.Field()
+    """
+    Rich contextual description of the relationship with surrounding information, details about how/why/when, and any relevant background. Should be comprehensive enough to understand the relationship without referring back to source.
+    """
+
+    temporal_details: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Temporal timing information extracted from text (e.g., 'last week', 'in 2023', 'yesterday')
+    """
+
+    chunk_id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    The chunk_id this relation came from
+    """
+
+    timestamp: typing.Optional[dt.datetime] = pydantic.Field(default=None)
+    """
+    Timestamp when this relation was introduced
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

usecortex_ai/types/retrieve_mode.py

@@ -0,0 +1,5 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+RetrieveMode = typing.Union[typing.Literal["fast", "accurate"], typing.Any]

usecortex_ai/types/retrieve_response.py

@@ -0,0 +1,34 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .chunk_graph_relations_response import ChunkGraphRelationsResponse
+from .search_chunk import SearchChunk
+
+
+class RetrieveResponse(UniversalBaseModel):
+    chunks: typing.Optional[typing.List[SearchChunk]] = pydantic.Field(default=None)
+    """
+    Retrieved content chunks
+    """
+
+    graph_relations: typing.Optional[ChunkGraphRelationsResponse] = pydantic.Field(default=None)
+    """
+    Graph relations with chunk_relations (by chunk_id) and entity_relations (top entity matches)
+    """
+
+    metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = pydantic.Field(default=None)
+    """
+    Additional metadata about the retrieval run
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

usecortex_ai/types/retrieve_user_memory_response.py

@@ -4,6 +4,7 @@ import typing
 
 import pydantic
 from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .scored_path_response import ScoredPathResponse
 from .user_memory import UserMemory
 
 
@@ -22,6 +23,11 @@ class RetrieveUserMemoryResponse(UniversalBaseModel):
     Array of user memories ranked by relevance to your search query
     """
 
+    relations: typing.Optional[typing.List[ScoredPathResponse]] = pydantic.Field(default=None)
+    """
+    Array of scored relations extracted from the user query via knowledge graph search
+    """
+
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
     else: