# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Optional
from typing_extensions import Literal, overload

import httpx

from .groups import (
    GroupsResource,
    AsyncGroupsResource,
    GroupsResourceWithRawResponse,
    AsyncGroupsResourceWithRawResponse,
    GroupsResourceWithStreamingResponse,
    AsyncGroupsResourceWithStreamingResponse,
)
from .memory import (
    MemoryResource,
    AsyncMemoryResource,
    MemoryResourceWithRawResponse,
    AsyncMemoryResourceWithRawResponse,
    MemoryResourceWithStreamingResponse,
    AsyncMemoryResourceWithStreamingResponse,
)
from ...types import (
    vault_create_params,
    vault_delete_params,
    vault_search_params,
    vault_update_params,
    vault_upload_params,
    vault_confirm_upload_params,
)
from .objects import (
    ObjectsResource,
    AsyncObjectsResource,
    ObjectsResourceWithRawResponse,
    AsyncObjectsResourceWithRawResponse,
    ObjectsResourceWithStreamingResponse,
    AsyncObjectsResourceWithStreamingResponse,
)
from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
from ..._utils import path_template, required_args, maybe_transform, async_maybe_transform
from .graphrag import (
    GraphragResource,
    AsyncGraphragResource,
    GraphragResourceWithRawResponse,
    AsyncGraphragResourceWithRawResponse,
    GraphragResourceWithStreamingResponse,
    AsyncGraphragResourceWithStreamingResponse,
)
from ..._compat import cached_property
from .multipart import (
    MultipartResource,
    AsyncMultipartResource,
    MultipartResourceWithRawResponse,
    AsyncMultipartResourceWithRawResponse,
    MultipartResourceWithStreamingResponse,
    AsyncMultipartResourceWithStreamingResponse,
)
from ..._resource import SyncAPIResource, AsyncAPIResource
from ..._response import (
    to_raw_response_wrapper,
    to_streamed_response_wrapper,
    async_to_raw_response_wrapper,
    async_to_streamed_response_wrapper,
)
from .events.events import (
    EventsResource,
    AsyncEventsResource,
    EventsResourceWithRawResponse,
    AsyncEventsResourceWithRawResponse,
    EventsResourceWithStreamingResponse,
    AsyncEventsResourceWithStreamingResponse,
)
from ..._base_client import make_request_options
from ...types.vault_list_response import VaultListResponse
from ...types.vault_create_response import VaultCreateResponse
from ...types.vault_delete_response import VaultDeleteResponse
from ...types.vault_ingest_response import VaultIngestResponse
from ...types.vault_search_response import VaultSearchResponse
from ...types.vault_update_response import VaultUpdateResponse
from ...types.vault_upload_response import VaultUploadResponse
from ...types.vault_retrieve_response import VaultRetrieveResponse
from ...types.vault_confirm_upload_response import VaultConfirmUploadResponse

__all__ = ["VaultResource", "AsyncVaultResource"]


class VaultResource(SyncAPIResource):
    """Secure document storage with semantic search and GraphRAG"""

    @cached_property
    def events(self) -> EventsResource:
        return EventsResource(self._client)

    @cached_property
    def graphrag(self) -> GraphragResource:
        """Secure document storage with semantic search and GraphRAG"""
        return GraphragResource(self._client)

    @cached_property
    def groups(self) -> GroupsResource:
        """Secure document storage with semantic search and GraphRAG"""
        return GroupsResource(self._client)

    @cached_property
    def multipart(self) -> MultipartResource:
        """Secure document storage with semantic search and GraphRAG"""
        return MultipartResource(self._client)

    @cached_property
    def objects(self) -> ObjectsResource:
        """Secure document storage with semantic search and GraphRAG"""
        return ObjectsResource(self._client)

    @cached_property
    def memory(self) -> MemoryResource:
        """Secure document storage with semantic search and GraphRAG"""
        return MemoryResource(self._client)

    @cached_property
    def with_raw_response(self) -> VaultResourceWithRawResponse:
        """
        This property can be used as a prefix for any HTTP method call to return
        the raw response object instead of the parsed content.

        For more information, see https://www.github.com/CaseMark/casedev-python#accessing-raw-response-data-eg-headers
        """
        return VaultResourceWithRawResponse(self)

    @cached_property
    def with_streaming_response(self) -> VaultResourceWithStreamingResponse:
        """
        An alternative to `.with_raw_response` that doesn't eagerly read the response body.

        For more information, see https://www.github.com/CaseMark/casedev-python#with_streaming_response
        """
        return VaultResourceWithStreamingResponse(self)

    def create(
        self,
        *,
        name: str,
        description: str | Omit = omit,
        enable_graph: bool | Omit = omit,
        enable_indexing: bool | Omit = omit,
        group_id: str | Omit = omit,
        metadata: object | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultCreateResponse:
        """
        Creates a new secure vault with dedicated S3 storage and vector search
        capabilities. Each vault provides isolated document storage with semantic
        search, OCR processing, and optional GraphRAG knowledge graph features for legal
        document analysis and discovery.

        Args:
          name: Display name for the vault

          description: Optional description of the vault's purpose

          enable_graph: Enable knowledge graph for entity relationship mapping. Only applies when
              enableIndexing is true.

          enable_indexing: Enable vector indexing and search capabilities. Set to false for storage-only
              vaults.

          group_id: Assign the vault to a vault group for access control. Required when using a
              group-scoped API key.

          metadata: Optional metadata to attach to the vault (e.g., { containsPHI: true } for HIPAA
              compliance tracking)

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        return self._post(
            "/vault",
            body=maybe_transform(
                {
                    "name": name,
                    "description": description,
                    "enable_graph": enable_graph,
                    "enable_indexing": enable_indexing,
                    "group_id": group_id,
                    "metadata": metadata,
                },
                vault_create_params.VaultCreateParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultCreateResponse,
        )

    def retrieve(
        self,
        id: str,
        *,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultRetrieveResponse:
        """
        Retrieve detailed information about a specific vault, including storage
        configuration, chunking strategy, and usage statistics. Returns vault metadata,
        bucket information, and vector storage details.

        Args:
          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return self._get(
            path_template("/vault/{id}", id=id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultRetrieveResponse,
        )

    def update(
        self,
        id: str,
        *,
        description: Optional[str] | Omit = omit,
        enable_graph: bool | Omit = omit,
        group_id: Optional[str] | Omit = omit,
        name: str | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultUpdateResponse:
        """Update vault settings including name, description, and enableGraph.

        Changing
        enableGraph only affects future document uploads - existing documents retain
        their current graph/non-graph state.

        Args:
          description: New description for the vault. Set to null to remove.

          enable_graph: Whether to enable GraphRAG for future document uploads

          group_id: Move the vault to a different group, or set to null to remove from its current
              group.

          name: New name for the vault

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return self._patch(
            path_template("/vault/{id}", id=id),
            body=maybe_transform(
                {
                    "description": description,
                    "enable_graph": enable_graph,
                    "group_id": group_id,
                    "name": name,
                },
                vault_update_params.VaultUpdateParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultUpdateResponse,
        )

    def list(
        self,
        *,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultListResponse:
        """List all vaults for the authenticated organization.

        Returns vault metadata
        including name, description, storage configuration, and usage statistics.
        """
        return self._get(
            "/vault",
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultListResponse,
        )

    def delete(
        self,
        id: str,
        *,
        async_: bool | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultDeleteResponse:
        """
        Permanently deletes a vault and all its contents including documents, vectors,
        graph data, and S3 buckets. This operation cannot be undone. For large vaults,
        use the async=true query parameter to queue deletion in the background.

        Args:
          async_: If true and vault has many objects, queue deletion in background and return
              immediately

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return self._delete(
            path_template("/vault/{id}", id=id),
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                query=maybe_transform({"async_": async_}, vault_delete_params.VaultDeleteParams),
            ),
            cast_to=VaultDeleteResponse,
        )

    @overload
    def confirm_upload(
        self,
        object_id: str,
        *,
        id: str,
        size_bytes: int,
        success: Literal[True],
        etag: str | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultConfirmUploadResponse:
        """Confirm whether a direct-to-S3 vault upload succeeded or failed.

        This endpoint
        emits vault.upload.completed or vault.upload.failed events and is idempotent for
        repeated confirmations.

        Args:
          size_bytes: Uploaded file size in bytes

          success: Whether the upload succeeded

          etag: S3 ETag for the uploaded object (optional if client cannot access ETag header)

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        ...

    @overload
    def confirm_upload(
        self,
        object_id: str,
        *,
        id: str,
        error_code: str,
        error_message: str,
        success: Literal[False],
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultConfirmUploadResponse:
        """Confirm whether a direct-to-S3 vault upload succeeded or failed.

        This endpoint
        emits vault.upload.completed or vault.upload.failed events and is idempotent for
        repeated confirmations.

        Args:
          error_code: Client-side error code

          error_message: Client-side error message

          success: Whether the upload succeeded

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        ...

    @required_args(["id", "size_bytes", "success"], ["id", "error_code", "error_message", "success"])
    def confirm_upload(
        self,
        object_id: str,
        *,
        id: str,
        size_bytes: int | Omit = omit,
        success: Literal[True] | Literal[False],
        etag: str | Omit = omit,
        error_code: str | Omit = omit,
        error_message: str | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultConfirmUploadResponse:
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        if not object_id:
            raise ValueError(f"Expected a non-empty value for `object_id` but received {object_id!r}")
        return self._post(
            path_template("/vault/{id}/upload/{object_id}/confirm", id=id, object_id=object_id),
            body=maybe_transform(
                {
                    "size_bytes": size_bytes,
                    "success": success,
                    "etag": etag,
                    "error_code": error_code,
                    "error_message": error_message,
                },
                vault_confirm_upload_params.VaultConfirmUploadParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultConfirmUploadResponse,
        )

    def ingest(
        self,
        object_id: str,
        *,
        id: str,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultIngestResponse:
        """
        Triggers ingestion workflow for a vault object to extract text, generate chunks,
        and create embeddings. For supported file types (PDF, DOCX, PPTX, TXT, RTF, XML,
        ZIP, audio, video), processing happens asynchronously. ZIP archives are unpacked
        recursively up to 5 levels, and each extracted file is created as an independent
        vault object and ingested via the normal pipeline. For unsupported types
        (images, etc.), the file is marked as completed immediately without text
        extraction. GraphRAG indexing must be triggered separately via POST
        /vault/:id/graphrag/:objectId.

        Args:
          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        if not object_id:
            raise ValueError(f"Expected a non-empty value for `object_id` but received {object_id!r}")
        return self._post(
            path_template("/vault/{id}/ingest/{object_id}", id=id, object_id=object_id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultIngestResponse,
        )

    def search(
        self,
        id: str,
        *,
        query: str,
        filters: vault_search_params.Filters | Omit = omit,
        method: Literal["vector", "graph", "hybrid", "global", "local", "fast", "entity"] | Omit = omit,
        top_k: int | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultSearchResponse:
        """
        Search across vault documents using multiple methods including hybrid vector +
        graph search, GraphRAG global search, entity-based search, and fast similarity
        search. Returns relevant documents and contextual answers based on the search
        method.

        Args:
          query: Search query or question to find relevant documents

          filters: Filters to narrow search results to specific documents

          method: Search method: 'global' for comprehensive questions, 'entity' for specific
              entities, 'fast' for quick similarity search, 'hybrid' for combined approach

          top_k: Maximum number of results to return

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return self._post(
            path_template("/vault/{id}/search", id=id),
            body=maybe_transform(
                {
                    "query": query,
                    "filters": filters,
                    "method": method,
                    "top_k": top_k,
                },
                vault_search_params.VaultSearchParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultSearchResponse,
        )

    def upload(
        self,
        id: str,
        *,
        content_type: str,
        filename: str,
        auto_index: bool | Omit = omit,
        metadata: object | Omit = omit,
        path: str | Omit = omit,
        size_bytes: int | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultUploadResponse:
        """
        Generate a presigned URL for uploading files directly to a vault's S3 storage.
        After uploading to S3, confirm the upload result via POST
        /vault/:vaultId/upload/:objectId/confirm before triggering ingestion.

        Args:
          content_type: MIME type of the file (e.g., application/pdf, image/jpeg)

          filename: Name of the file to upload

          auto_index: Whether to automatically process and index the file for search

          metadata: Additional metadata to associate with the file

          path: Optional folder path for hierarchy preservation. Allows integrations to maintain
              source folder structure from systems like NetDocs, Clio, or Smokeball. Example:
              '/Discovery/Depositions/2024'

          size_bytes: File size in bytes (optional, max 5GB for single PUT uploads). When provided,
              enforces exact file size at S3 level.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return self._post(
            path_template("/vault/{id}/upload", id=id),
            body=maybe_transform(
                {
                    "content_type": content_type,
                    "filename": filename,
                    "auto_index": auto_index,
                    "metadata": metadata,
                    "path": path,
                    "size_bytes": size_bytes,
                },
                vault_upload_params.VaultUploadParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultUploadResponse,
        )


class AsyncVaultResource(AsyncAPIResource):
    """Secure document storage with semantic search and GraphRAG"""

    @cached_property
    def events(self) -> AsyncEventsResource:
        return AsyncEventsResource(self._client)

    @cached_property
    def graphrag(self) -> AsyncGraphragResource:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncGraphragResource(self._client)

    @cached_property
    def groups(self) -> AsyncGroupsResource:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncGroupsResource(self._client)

    @cached_property
    def multipart(self) -> AsyncMultipartResource:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncMultipartResource(self._client)

    @cached_property
    def objects(self) -> AsyncObjectsResource:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncObjectsResource(self._client)

    @cached_property
    def memory(self) -> AsyncMemoryResource:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncMemoryResource(self._client)

    @cached_property
    def with_raw_response(self) -> AsyncVaultResourceWithRawResponse:
        """
        This property can be used as a prefix for any HTTP method call to return
        the raw response object instead of the parsed content.

        For more information, see https://www.github.com/CaseMark/casedev-python#accessing-raw-response-data-eg-headers
        """
        return AsyncVaultResourceWithRawResponse(self)

    @cached_property
    def with_streaming_response(self) -> AsyncVaultResourceWithStreamingResponse:
        """
        An alternative to `.with_raw_response` that doesn't eagerly read the response body.

        For more information, see https://www.github.com/CaseMark/casedev-python#with_streaming_response
        """
        return AsyncVaultResourceWithStreamingResponse(self)

    async def create(
        self,
        *,
        name: str,
        description: str | Omit = omit,
        enable_graph: bool | Omit = omit,
        enable_indexing: bool | Omit = omit,
        group_id: str | Omit = omit,
        metadata: object | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultCreateResponse:
        """
        Creates a new secure vault with dedicated S3 storage and vector search
        capabilities. Each vault provides isolated document storage with semantic
        search, OCR processing, and optional GraphRAG knowledge graph features for legal
        document analysis and discovery.

        Args:
          name: Display name for the vault

          description: Optional description of the vault's purpose

          enable_graph: Enable knowledge graph for entity relationship mapping. Only applies when
              enableIndexing is true.

          enable_indexing: Enable vector indexing and search capabilities. Set to false for storage-only
              vaults.

          group_id: Assign the vault to a vault group for access control. Required when using a
              group-scoped API key.

          metadata: Optional metadata to attach to the vault (e.g., { containsPHI: true } for HIPAA
              compliance tracking)

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        return await self._post(
            "/vault",
            body=await async_maybe_transform(
                {
                    "name": name,
                    "description": description,
                    "enable_graph": enable_graph,
                    "enable_indexing": enable_indexing,
                    "group_id": group_id,
                    "metadata": metadata,
                },
                vault_create_params.VaultCreateParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultCreateResponse,
        )

    async def retrieve(
        self,
        id: str,
        *,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultRetrieveResponse:
        """
        Retrieve detailed information about a specific vault, including storage
        configuration, chunking strategy, and usage statistics. Returns vault metadata,
        bucket information, and vector storage details.

        Args:
          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return await self._get(
            path_template("/vault/{id}", id=id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultRetrieveResponse,
        )

    async def update(
        self,
        id: str,
        *,
        description: Optional[str] | Omit = omit,
        enable_graph: bool | Omit = omit,
        group_id: Optional[str] | Omit = omit,
        name: str | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultUpdateResponse:
        """Update vault settings including name, description, and enableGraph.

        Changing
        enableGraph only affects future document uploads - existing documents retain
        their current graph/non-graph state.

        Args:
          description: New description for the vault. Set to null to remove.

          enable_graph: Whether to enable GraphRAG for future document uploads

          group_id: Move the vault to a different group, or set to null to remove from its current
              group.

          name: New name for the vault

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return await self._patch(
            path_template("/vault/{id}", id=id),
            body=await async_maybe_transform(
                {
                    "description": description,
                    "enable_graph": enable_graph,
                    "group_id": group_id,
                    "name": name,
                },
                vault_update_params.VaultUpdateParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultUpdateResponse,
        )

    async def list(
        self,
        *,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultListResponse:
        """List all vaults for the authenticated organization.

        Returns vault metadata
        including name, description, storage configuration, and usage statistics.
        """
        return await self._get(
            "/vault",
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultListResponse,
        )

    async def delete(
        self,
        id: str,
        *,
        async_: bool | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultDeleteResponse:
        """
        Permanently deletes a vault and all its contents including documents, vectors,
        graph data, and S3 buckets. This operation cannot be undone. For large vaults,
        use the async=true query parameter to queue deletion in the background.

        Args:
          async_: If true and vault has many objects, queue deletion in background and return
              immediately

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return await self._delete(
            path_template("/vault/{id}", id=id),
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                query=await async_maybe_transform({"async_": async_}, vault_delete_params.VaultDeleteParams),
            ),
            cast_to=VaultDeleteResponse,
        )

    @overload
    async def confirm_upload(
        self,
        object_id: str,
        *,
        id: str,
        size_bytes: int,
        success: Literal[True],
        etag: str | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultConfirmUploadResponse:
        """Confirm whether a direct-to-S3 vault upload succeeded or failed.

        This endpoint
        emits vault.upload.completed or vault.upload.failed events and is idempotent for
        repeated confirmations.

        Args:
          size_bytes: Uploaded file size in bytes

          success: Whether the upload succeeded

          etag: S3 ETag for the uploaded object (optional if client cannot access ETag header)

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        ...

    @overload
    async def confirm_upload(
        self,
        object_id: str,
        *,
        id: str,
        error_code: str,
        error_message: str,
        success: Literal[False],
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultConfirmUploadResponse:
        """Confirm whether a direct-to-S3 vault upload succeeded or failed.

        This endpoint
        emits vault.upload.completed or vault.upload.failed events and is idempotent for
        repeated confirmations.

        Args:
          error_code: Client-side error code

          error_message: Client-side error message

          success: Whether the upload succeeded

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        ...

    @required_args(["id", "size_bytes", "success"], ["id", "error_code", "error_message", "success"])
    async def confirm_upload(
        self,
        object_id: str,
        *,
        id: str,
        size_bytes: int | Omit = omit,
        success: Literal[True] | Literal[False],
        etag: str | Omit = omit,
        error_code: str | Omit = omit,
        error_message: str | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultConfirmUploadResponse:
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        if not object_id:
            raise ValueError(f"Expected a non-empty value for `object_id` but received {object_id!r}")
        return await self._post(
            path_template("/vault/{id}/upload/{object_id}/confirm", id=id, object_id=object_id),
            body=await async_maybe_transform(
                {
                    "size_bytes": size_bytes,
                    "success": success,
                    "etag": etag,
                    "error_code": error_code,
                    "error_message": error_message,
                },
                vault_confirm_upload_params.VaultConfirmUploadParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultConfirmUploadResponse,
        )

    async def ingest(
        self,
        object_id: str,
        *,
        id: str,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultIngestResponse:
        """
        Triggers ingestion workflow for a vault object to extract text, generate chunks,
        and create embeddings. For supported file types (PDF, DOCX, PPTX, TXT, RTF, XML,
        ZIP, audio, video), processing happens asynchronously. ZIP archives are unpacked
        recursively up to 5 levels, and each extracted file is created as an independent
        vault object and ingested via the normal pipeline. For unsupported types
        (images, etc.), the file is marked as completed immediately without text
        extraction. GraphRAG indexing must be triggered separately via POST
        /vault/:id/graphrag/:objectId.

        Args:
          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        if not object_id:
            raise ValueError(f"Expected a non-empty value for `object_id` but received {object_id!r}")
        return await self._post(
            path_template("/vault/{id}/ingest/{object_id}", id=id, object_id=object_id),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultIngestResponse,
        )

    async def search(
        self,
        id: str,
        *,
        query: str,
        filters: vault_search_params.Filters | Omit = omit,
        method: Literal["vector", "graph", "hybrid", "global", "local", "fast", "entity"] | Omit = omit,
        top_k: int | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultSearchResponse:
        """
        Search across vault documents using multiple methods including hybrid vector +
        graph search, GraphRAG global search, entity-based search, and fast similarity
        search. Returns relevant documents and contextual answers based on the search
        method.

        Args:
          query: Search query or question to find relevant documents

          filters: Filters to narrow search results to specific documents

          method: Search method: 'global' for comprehensive questions, 'entity' for specific
              entities, 'fast' for quick similarity search, 'hybrid' for combined approach

          top_k: Maximum number of results to return

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return await self._post(
            path_template("/vault/{id}/search", id=id),
            body=await async_maybe_transform(
                {
                    "query": query,
                    "filters": filters,
                    "method": method,
                    "top_k": top_k,
                },
                vault_search_params.VaultSearchParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultSearchResponse,
        )

    async def upload(
        self,
        id: str,
        *,
        content_type: str,
        filename: str,
        auto_index: bool | Omit = omit,
        metadata: object | Omit = omit,
        path: str | Omit = omit,
        size_bytes: int | Omit = omit,
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
        # The extra values given here take precedence over values defined on the client or passed to this method.
        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
    ) -> VaultUploadResponse:
        """
        Generate a presigned URL for uploading files directly to a vault's S3 storage.
        After uploading to S3, confirm the upload result via POST
        /vault/:vaultId/upload/:objectId/confirm before triggering ingestion.

        Args:
          content_type: MIME type of the file (e.g., application/pdf, image/jpeg)

          filename: Name of the file to upload

          auto_index: Whether to automatically process and index the file for search

          metadata: Additional metadata to associate with the file

          path: Optional folder path for hierarchy preservation. Allows integrations to maintain
              source folder structure from systems like NetDocs, Clio, or Smokeball. Example:
              '/Discovery/Depositions/2024'

          size_bytes: File size in bytes (optional, max 5GB for single PUT uploads). When provided,
              enforces exact file size at S3 level.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not id:
            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
        return await self._post(
            path_template("/vault/{id}/upload", id=id),
            body=await async_maybe_transform(
                {
                    "content_type": content_type,
                    "filename": filename,
                    "auto_index": auto_index,
                    "metadata": metadata,
                    "path": path,
                    "size_bytes": size_bytes,
                },
                vault_upload_params.VaultUploadParams,
            ),
            options=make_request_options(
                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
            ),
            cast_to=VaultUploadResponse,
        )


class VaultResourceWithRawResponse:
    def __init__(self, vault: VaultResource) -> None:
        self._vault = vault

        self.create = to_raw_response_wrapper(
            vault.create,
        )
        self.retrieve = to_raw_response_wrapper(
            vault.retrieve,
        )
        self.update = to_raw_response_wrapper(
            vault.update,
        )
        self.list = to_raw_response_wrapper(
            vault.list,
        )
        self.delete = to_raw_response_wrapper(
            vault.delete,
        )
        self.confirm_upload = to_raw_response_wrapper(
            vault.confirm_upload,
        )
        self.ingest = to_raw_response_wrapper(
            vault.ingest,
        )
        self.search = to_raw_response_wrapper(
            vault.search,
        )
        self.upload = to_raw_response_wrapper(
            vault.upload,
        )

    @cached_property
    def events(self) -> EventsResourceWithRawResponse:
        return EventsResourceWithRawResponse(self._vault.events)

    @cached_property
    def graphrag(self) -> GraphragResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return GraphragResourceWithRawResponse(self._vault.graphrag)

    @cached_property
    def groups(self) -> GroupsResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return GroupsResourceWithRawResponse(self._vault.groups)

    @cached_property
    def multipart(self) -> MultipartResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return MultipartResourceWithRawResponse(self._vault.multipart)

    @cached_property
    def objects(self) -> ObjectsResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return ObjectsResourceWithRawResponse(self._vault.objects)

    @cached_property
    def memory(self) -> MemoryResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return MemoryResourceWithRawResponse(self._vault.memory)


class AsyncVaultResourceWithRawResponse:
    def __init__(self, vault: AsyncVaultResource) -> None:
        self._vault = vault

        self.create = async_to_raw_response_wrapper(
            vault.create,
        )
        self.retrieve = async_to_raw_response_wrapper(
            vault.retrieve,
        )
        self.update = async_to_raw_response_wrapper(
            vault.update,
        )
        self.list = async_to_raw_response_wrapper(
            vault.list,
        )
        self.delete = async_to_raw_response_wrapper(
            vault.delete,
        )
        self.confirm_upload = async_to_raw_response_wrapper(
            vault.confirm_upload,
        )
        self.ingest = async_to_raw_response_wrapper(
            vault.ingest,
        )
        self.search = async_to_raw_response_wrapper(
            vault.search,
        )
        self.upload = async_to_raw_response_wrapper(
            vault.upload,
        )

    @cached_property
    def events(self) -> AsyncEventsResourceWithRawResponse:
        return AsyncEventsResourceWithRawResponse(self._vault.events)

    @cached_property
    def graphrag(self) -> AsyncGraphragResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncGraphragResourceWithRawResponse(self._vault.graphrag)

    @cached_property
    def groups(self) -> AsyncGroupsResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncGroupsResourceWithRawResponse(self._vault.groups)

    @cached_property
    def multipart(self) -> AsyncMultipartResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncMultipartResourceWithRawResponse(self._vault.multipart)

    @cached_property
    def objects(self) -> AsyncObjectsResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncObjectsResourceWithRawResponse(self._vault.objects)

    @cached_property
    def memory(self) -> AsyncMemoryResourceWithRawResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncMemoryResourceWithRawResponse(self._vault.memory)


class VaultResourceWithStreamingResponse:
    def __init__(self, vault: VaultResource) -> None:
        self._vault = vault

        self.create = to_streamed_response_wrapper(
            vault.create,
        )
        self.retrieve = to_streamed_response_wrapper(
            vault.retrieve,
        )
        self.update = to_streamed_response_wrapper(
            vault.update,
        )
        self.list = to_streamed_response_wrapper(
            vault.list,
        )
        self.delete = to_streamed_response_wrapper(
            vault.delete,
        )
        self.confirm_upload = to_streamed_response_wrapper(
            vault.confirm_upload,
        )
        self.ingest = to_streamed_response_wrapper(
            vault.ingest,
        )
        self.search = to_streamed_response_wrapper(
            vault.search,
        )
        self.upload = to_streamed_response_wrapper(
            vault.upload,
        )

    @cached_property
    def events(self) -> EventsResourceWithStreamingResponse:
        return EventsResourceWithStreamingResponse(self._vault.events)

    @cached_property
    def graphrag(self) -> GraphragResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return GraphragResourceWithStreamingResponse(self._vault.graphrag)

    @cached_property
    def groups(self) -> GroupsResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return GroupsResourceWithStreamingResponse(self._vault.groups)

    @cached_property
    def multipart(self) -> MultipartResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return MultipartResourceWithStreamingResponse(self._vault.multipart)

    @cached_property
    def objects(self) -> ObjectsResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return ObjectsResourceWithStreamingResponse(self._vault.objects)

    @cached_property
    def memory(self) -> MemoryResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return MemoryResourceWithStreamingResponse(self._vault.memory)


class AsyncVaultResourceWithStreamingResponse:
    def __init__(self, vault: AsyncVaultResource) -> None:
        self._vault = vault

        self.create = async_to_streamed_response_wrapper(
            vault.create,
        )
        self.retrieve = async_to_streamed_response_wrapper(
            vault.retrieve,
        )
        self.update = async_to_streamed_response_wrapper(
            vault.update,
        )
        self.list = async_to_streamed_response_wrapper(
            vault.list,
        )
        self.delete = async_to_streamed_response_wrapper(
            vault.delete,
        )
        self.confirm_upload = async_to_streamed_response_wrapper(
            vault.confirm_upload,
        )
        self.ingest = async_to_streamed_response_wrapper(
            vault.ingest,
        )
        self.search = async_to_streamed_response_wrapper(
            vault.search,
        )
        self.upload = async_to_streamed_response_wrapper(
            vault.upload,
        )

    @cached_property
    def events(self) -> AsyncEventsResourceWithStreamingResponse:
        return AsyncEventsResourceWithStreamingResponse(self._vault.events)

    @cached_property
    def graphrag(self) -> AsyncGraphragResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncGraphragResourceWithStreamingResponse(self._vault.graphrag)

    @cached_property
    def groups(self) -> AsyncGroupsResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncGroupsResourceWithStreamingResponse(self._vault.groups)

    @cached_property
    def multipart(self) -> AsyncMultipartResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncMultipartResourceWithStreamingResponse(self._vault.multipart)

    @cached_property
    def objects(self) -> AsyncObjectsResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncObjectsResourceWithStreamingResponse(self._vault.objects)

    @cached_property
    def memory(self) -> AsyncMemoryResourceWithStreamingResponse:
        """Secure document storage with semantic search and GraphRAG"""
        return AsyncMemoryResourceWithStreamingResponse(self._vault.memory)
