// File generated from our OpenAPI spec by sdkgen. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as ContentAPI from '../extractions/content';
import * as Shared from '../shared';
import * as FilesAPI from './files';
import { APIPromise } from '../../core/api-promise';
import { Cursor, PagePromise, type CursorParams } from '../../core/pagination';
import { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';
import {
  type StoreCopyAndPollHelperParams,
  type StoreHelpers,
  type StorePollHelperParams,
  withStoreHelpers,
} from '../../lib/stores';
import {
  AudioURLInputChunk,
  FileCreateAndPollHelperParams,
  FileCreateParams,
  FileDeleteParams,
  FileDeleteResponse,
  FileListParams,
  FileListResponse,
  FilePollHelperParams,
  FileRetrieveParams,
  FileUpdateParams,
  FileUploadAndPollHelperParams,
  FileUploadHelperParams,
  Files,
  ImageURLInputChunk,
  StoreFile,
  StoreFileConfig,
  StoreFileHelpers,
  StoreFileStatus,
  TextInputChunk,
  VideoURLInputChunk,
} from './files';
export type { StorePollHelperParams, StoreCopyAndPollHelperParams, StoreHelpers };

export class StoresBase extends APIResource {
  files: FilesAPI.Files = new FilesAPI.Files(this._client);

  /**
   * Create a new vector store.
   *
   * Args: vector_store_create: VectorStoreCreate object containing the name,
   * description, and metadata.
   *
   * Returns: VectorStore: The response containing the created vector store details.
   */
  create(body: StoreCreateParams, options?: RequestOptions): APIPromise<Store> {
    return this._client.post('/v1/stores', { body, ...options });
  }

  /**
   * Get a store by ID or name.
   *
   * Args: store_identifier: The ID or name of the store to retrieve.
   *
   * Returns: Store: The response containing the store details.
   */
  retrieve(storeIdentifier: string, options?: RequestOptions): APIPromise<Store> {
    return this._client.get(path`/v1/stores/${storeIdentifier}`, options);
  }

  /**
   * Update a store by ID or name.
   *
   * Args: store_identifier: The ID or name of the store to update. store_update:
   * StoreCreate object containing the name, description, and metadata.
   *
   * Returns: Store: The response containing the updated store details.
   */
  update(storeIdentifier: string, body: StoreUpdateParams, options?: RequestOptions): APIPromise<Store> {
    return this._client.put(path`/v1/stores/${storeIdentifier}`, { body, ...options });
  }

  /**
   * List all stores with optional search.
   *
   * Args: pagination: The pagination options. q: Optional search query to filter
   * vector stores.
   *
   * Returns: StoreListResponse: The list of stores.
   */
  list(
    query: StoreListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<StoresCursor, Store> {
    return this._client.getAPIList('/v1/stores', Cursor<Store>, { query, ...options });
  }

  /**
   * Delete a store by ID or name.
   *
   * Args: store_identifier: The ID or name of the store to delete.
   *
   * Returns: Store: The response containing the deleted store details.
   */
  delete(storeIdentifier: string, options?: RequestOptions): APIPromise<StoreDeleteResponse> {
    return this._client.delete(path`/v1/stores/${storeIdentifier}`, options);
  }

  /**
   * Copy a store into a new store with the given name.
   *
   * The copy keeps every file, its metadata and its indexed chunks, without
   * re-parsing or re-embedding anything. It runs in the background: both stores
   * report the progress in `copy_state`, and the new store's `status` is
   * `in_progress` until the copy completes. Neither store accepts file changes while
   * the copy runs, and the source must have no files still being processed.
   *
   * Args: store_identifier: The ID or name of the store to copy. params: The name of
   * the copy and optional description and metadata overrides.
   *
   * Returns: Store: The new store.
   */
  copy(storeIdentifier: string, body: StoreCopyParams, options?: RequestOptions): APIPromise<Store> {
    return this._client.post(path`/v1/stores/${storeIdentifier}/copy`, { body, ...options });
  }

  /**
   * Match store chunks against a regular expression.
   *
   * Unlike `/stores/search`, this runs your regex against the literal text of each
   * chunk. Use it to find chunks containing a specific token, identifier, error
   * code, or literal phrase.
   *
   * grep matches across all requested stores and returns at most `top_k` chunks in
   * total. Matches are unranked and interleaved across stores in the order
   * requested, preserving each store's result order. Pagination is not supported;
   * raise `top_k` to retrieve more matches.
   *
   * Args: grep_params: Grep configuration including:
   *
   * - pattern: RE2 regular expression matched against chunk text - targets: chunk
   * content groups to match (`text`, `generated`) - case_sensitive: whether the
   * pattern is case-sensitive - store_identifiers: IDs or names of the stores to
   * grep - file_ids: optional list of file IDs to filter chunks by - filters:
   * optional metadata filter conditions - top_k: number of matches to return
   *
   * Returns: StoreGrepResponse containing the list of matching chunks.
   *
   * Raises: HTTPException (400): If grep parameters are invalid HTTPException (404):
   * If the store is not found
   */
  grep(params: StoreGrepParams, options?: RequestOptions): APIPromise<StoreGrepResponse> {
    const { 'X-Mxbai-Tool-Ticket': xMxbaiToolTicket, ...body } = params;
    return this._client.post('/v1/stores/grep', {
      body,
      ...options,
      headers: buildHeaders([{ 'X-Mxbai-Tool-Ticket': xMxbaiToolTicket }, options?.headers]),
    });
  }

  /**
   * List store chunks purely by metadata filters — no embeddings, no semantic
   * similarity, no reranking.
   *
   * Unlike `/stores/search`, this endpoint does not require a query and never runs a
   * vector lookup. It returns chunks whose file and chunk metadata satisfy
   * `filters`, optionally ordered by a numeric metadata field via `sort_by`. Useful
   * for ranked retrieval over numeric attributes (e.g. price, BPM) and for
   * reproducing the agentic `filter_chunks` tool externally.
   *
   * list-chunks filters across all requested stores and returns at most `top_k`
   * chunks in total. With `sort_by`, results are ordered globally by that field.
   * Otherwise results are interleaved across stores in the order requested,
   * preserving each store's result order. Pagination is not supported; raise `top_k`
   * to retrieve more chunks.
   *
   * Args: filter_params: Filter configuration including:
   *
   * - store_identifiers: IDs or names of the stores to filter against - filters:
   * optional metadata filter conditions - file_ids: optional list of file IDs to
   * filter chunks by - sort_by: optional metadata field path, or `(field,
   * ascending)` tuple, for numeric ordering - top_k: number of chunks to return
   *
   * Returns: StoreListChunksResponse containing the list of matching chunks.
   *
   * Raises: HTTPException (400): If filter parameters are invalid HTTPException
   * (404): If the store is not found
   */
  listChunks(body: StoreListChunksParams, options?: RequestOptions): APIPromise<StoreListChunksResponse> {
    return this._client.post('/v1/stores/list-chunks', { body, ...options });
  }

  /**
   * Get metadata facets
   */
  metadataFacets(
    body: StoreMetadataFacetsParams,
    options?: RequestOptions,
  ): APIPromise<StoreMetadataFacetsResponse> {
    return this._client.post('/v1/stores/metadata-facets', { body, ...options });
  }

  /**
   * Question answering
   */
  questionAnswering(
    body: StoreQuestionAnsweringParams,
    options?: RequestOptions,
  ): APIPromise<StoreQuestionAnsweringResponse> {
    return this._client.post('/v1/stores/question-answering', { body, ...options });
  }

  /**
   * Perform semantic search across store chunks.
   *
   * This endpoint searches through store chunks using semantic similarity matching.
   * It supports complex search queries with filters and returns relevance-scored
   * results. Agentic searches can set `stream=true` to receive live trace events as
   * server-sent events while the search runs, followed by the final search response.
   *
   * For the special 'mixedbread/web' store, this endpoint performs web search using
   * a mixture of different providers instead of semantic search. Web search results
   * are always reranked for consistent scoring.
   *
   * Args: search_params: Search configuration including:
   *
   * - query text or embeddings - store_identifiers: List of store identifiers to
   * search - file_ids: Optional list of file IDs to filter chunks by (or tuple of
   * list and condition operator) - metadata filters - pagination parameters -
   * sorting preferences _state: API state dependency _ctx: Service context
   * dependency
   *
   * Returns: StoreSearchResponse containing:
   *
   * - List of matched chunks with relevance scores - Pagination details including
   * total result count
   *
   * Raises: HTTPException (400): If search parameters are invalid HTTPException
   * (404): If no vector stores are found to search
   */
  search(params: StoreSearchParams, options?: RequestOptions): APIPromise<StoreSearchResponse> {
    const { 'X-Mxbai-Tool-Ticket': xMxbaiToolTicket, ...body } = params;
    return this._client.post('/v1/stores/search', {
      body,
      ...options,
      headers: buildHeaders([{ 'X-Mxbai-Tool-Ticket': xMxbaiToolTicket }, options?.headers]),
    });
  }
}

export class Stores extends withStoreHelpers(StoresBase) {}

export type StoresCursor = Cursor<Store>;

export interface ScoredVideoURLInputChunk {
  /**
   * position of the chunk in a file
   */
  chunk_index: number;

  /**
   * mime type of the chunk
   */
  mime_type?: string;

  /**
   * metadata of the chunk
   */
  generated_metadata?: ScoredVideoURLInputChunk.GeneratedMetadata | null;

  /**
   * model used for this chunk
   */
  model?: string | null;

  /**
   * score of the chunk
   */
  score: number;

  /**
   * file id
   */
  file_id: string;

  /**
   * filename
   */
  filename: string;

  /**
   * store id
   */
  store_id: string;

  /**
   * external identifier for this file
   */
  external_id?: string | null;

  /**
   * file metadata
   */
  metadata?: unknown;

  /**
   * Input type identifier
   */
  type?: 'video_url';

  /**
   * speech recognition (sr) text of the video
   */
  transcription?: string | null;

  /**
   * LLM-generated context that situates this video chunk within its source file
   */
  context?: string | null;

  /**
   * summary of the video
   */
  summary?: string | null;

  /**
   * Model for video URL validation.
   */
  video_url?: VideoURL | null;
}

export namespace ScoredVideoURLInputChunk {
  export type GeneratedMetadata =
    | MarkdownChunkGeneratedMetadata
    | TextChunkGeneratedMetadata
    | PdfChunkGeneratedMetadata
    | CodeChunkGeneratedMetadata
    | AudioChunkGeneratedMetadata
    | VideoChunkGeneratedMetadata
    | ImageChunkGeneratedMetadata
    | null;
}

/**
 * Represents an expiration policy for a store.
 */
export interface ExpiresAfter {
  /**
   * Anchor date for the expiration policy
   */
  anchor?: 'last_active_at';

  /**
   * Number of days after which the store expires
   */
  days?: number;
}

export interface ScoredAudioURLInputChunk {
  /**
   * position of the chunk in a file
   */
  chunk_index: number;

  /**
   * mime type of the chunk
   */
  mime_type?: string;

  /**
   * metadata of the chunk
   */
  generated_metadata?: ScoredAudioURLInputChunk.GeneratedMetadata | null;

  /**
   * model used for this chunk
   */
  model?: string | null;

  /**
   * score of the chunk
   */
  score: number;

  /**
   * file id
   */
  file_id: string;

  /**
   * filename
   */
  filename: string;

  /**
   * store id
   */
  store_id: string;

  /**
   * external identifier for this file
   */
  external_id?: string | null;

  /**
   * file metadata
   */
  metadata?: unknown;

  /**
   * Input type identifier
   */
  type?: 'audio_url';

  /**
   * speech recognition (sr) text of the audio
   */
  transcription?: string | null;

  /**
   * LLM-generated context that situates this audio chunk within its source file
   */
  context?: string | null;

  /**
   * summary of the audio
   */
  summary?: string | null;

  /**
   * Model for audio URL validation.
   */
  audio_url?: AudioURL | null;

  /**
   * The sampling rate of the audio.
   */
  sampling_rate: number;
}

export namespace ScoredAudioURLInputChunk {
  export type GeneratedMetadata =
    | MarkdownChunkGeneratedMetadata
    | TextChunkGeneratedMetadata
    | PdfChunkGeneratedMetadata
    | CodeChunkGeneratedMetadata
    | AudioChunkGeneratedMetadata
    | VideoChunkGeneratedMetadata
    | ImageChunkGeneratedMetadata
    | null;
}

export interface ScoredImageURLInputChunk {
  /**
   * position of the chunk in a file
   */
  chunk_index: number;

  /**
   * mime type of the chunk
   */
  mime_type?: string;

  /**
   * metadata of the chunk
   */
  generated_metadata?: ScoredImageURLInputChunk.GeneratedMetadata | null;

  /**
   * model used for this chunk
   */
  model?: string | null;

  /**
   * score of the chunk
   */
  score: number;

  /**
   * file id
   */
  file_id: string;

  /**
   * filename
   */
  filename: string;

  /**
   * store id
   */
  store_id: string;

  /**
   * external identifier for this file
   */
  external_id?: string | null;

  /**
   * file metadata
   */
  metadata?: unknown;

  /**
   * Input type identifier
   */
  type?: 'image_url';

  /**
   * ocr text of the image
   */
  ocr_text?: string | null;

  /**
   * LLM-generated context that situates this image within its source document
   */
  context?: string | null;

  /**
   * summary of the image
   */
  summary?: string | null;

  /**
   * Model for image URL validation.
   */
  image_url?: ImageURLOutput | null;
}

export namespace ScoredImageURLInputChunk {
  export type GeneratedMetadata =
    | MarkdownChunkGeneratedMetadata
    | TextChunkGeneratedMetadata
    | PdfChunkGeneratedMetadata
    | CodeChunkGeneratedMetadata
    | AudioChunkGeneratedMetadata
    | VideoChunkGeneratedMetadata
    | ImageChunkGeneratedMetadata
    | null;
}

export interface ScoredTextInputChunk {
  /**
   * position of the chunk in a file
   */
  chunk_index: number;

  /**
   * mime type of the chunk
   */
  mime_type?: string;

  /**
   * metadata of the chunk
   */
  generated_metadata?: ScoredTextInputChunk.GeneratedMetadata | null;

  /**
   * model used for this chunk
   */
  model?: string | null;

  /**
   * score of the chunk
   */
  score: number;

  /**
   * file id
   */
  file_id: string;

  /**
   * filename
   */
  filename: string;

  /**
   * store id
   */
  store_id: string;

  /**
   * external identifier for this file
   */
  external_id?: string | null;

  /**
   * file metadata
   */
  metadata?: unknown;

  /**
   * Input type identifier
   */
  type?: 'text';

  /**
   * The offset of the text in the file relative to the start of the file.
   */
  offset?: number;

  /**
   * Text content
   */
  text?: string | null;

  /**
   * LLM-generated context that situates this chunk within its source document
   */
  context?: string | null;

  /**
   * summary of the text chunk
   */
  summary?: string | null;
}

export namespace ScoredTextInputChunk {
  export type GeneratedMetadata =
    | MarkdownChunkGeneratedMetadata
    | TextChunkGeneratedMetadata
    | PdfChunkGeneratedMetadata
    | CodeChunkGeneratedMetadata
    | AudioChunkGeneratedMetadata
    | VideoChunkGeneratedMetadata
    | ImageChunkGeneratedMetadata
    | null;
}

/**
 * Model representing a store with its metadata and timestamps.
 */
export interface Store {
  /**
   * Unique identifier for the store
   */
  id: string;

  /**
   * Name of the store
   */
  name: string;

  /**
   * Detailed description of the store's purpose and contents
   */
  description?: string | null;

  /**
   * Whether the store can be accessed by anyone with valid login credentials
   */
  is_public?: boolean;

  /**
   * License for public stores
   */
  license?: string | null;

  /**
   * Additional metadata associated with the store
   */
  metadata?: unknown;

  /**
   * Configuration for a store.
   */
  config?: StoreConfig | null;

  /**
   * Customer bucket backing this store's storage; null = platform default
   */
  bucket_id?: string | null;

  /**
   * Counts of files in different states
   */
  file_counts?: FileCounts;

  /**
   * Represents an expiration policy for a store.
   */
  expires_after?: ExpiresAfter | null;

  /**
   * Processing status of the store
   */
  status?: 'expired' | 'in_progress' | 'completed' | 'failed';

  /**
   * Timestamp when the store was created
   */
  created_at: string;

  /**
   * Timestamp when the store was last updated
   */
  updated_at: string;

  /**
   * Timestamp when the store was last used
   */
  last_active_at?: string | null;

  /**
   * Total storage usage in bytes
   */
  usage_bytes?: number;

  /**
   * Total storage usage in tokens
   */
  usage_tokens?: number;

  /**
   * Optional expiration timestamp for the store
   */
  expires_at?: string | null;

  /**
   * Progress of a store copy, present on both the source and the target while it
   * runs.
   */
  copy_state?: Store.CopyState | null;

  /**
   * Type of the object
   */
  object?: 'store';
}

export namespace Store {
  /**
   * Progress of a store copy, present on both the source and the target while it
   * runs.
   */
  export interface CopyState {
    /**
     * Whether this store is copied from or into
     */
    role: 'source' | 'target';

    /**
     * Progress of the copy
     */
    status: 'in_progress' | 'failed';

    /**
     * The other store of the copy
     */
    peer_store_id: string;

    /**
     * When the copy was requested
     */
    started_at: string;

    /**
     * Why the copy failed, when it did
     */
    error?: string | null;
  }
}

/**
 * Options for configuring store chunk searches.
 */
export interface StoreChunkSearchOptions {
  /**
   * Minimum similarity score threshold
   */
  score_threshold?: number;

  /**
   * Whether to rewrite the query. Ignored when agentic is enabled (the agent handles
   * query decomposition).
   */
  rewrite_query?: boolean;

  /**
   * Whether to rerank results and optional reranking configuration. Ignored when
   * agentic is enabled (the agent handles ranking).
   */
  rerank?: StoreChunkSearchOptions.Rerank | null;

  /**
   * Whether to use agentic multi-query search with automatic query decomposition and
   * ranking. When enabled, rewrite_query and rerank options are ignored.
   */
  agentic?: StoreChunkSearchOptions.Agentic | null;

  /**
   * Whether to apply the learned scoring function to second-stage scoring. Requires
   * weights configured for the searched stores; silently skipped otherwise.
   */
  lsf?: boolean | null;

  /**
   * Whether to return file metadata
   */
  return_metadata?: boolean;

  /**
   * Whether to apply search rules
   */
  apply_search_rules?: boolean;
}

export namespace StoreChunkSearchOptions {
  export type Rerank = boolean | RerankConfig | null;

  export type Agentic = boolean | AgenticSearchConfig | null;
}

export interface MarkdownChunkGeneratedMetadata {
  type?: 'markdown';

  file_type?: 'text/markdown';

  language?: string | null;

  word_count?: number | null;

  file_size?: number | null;

  chunk_headings?: Array<MarkdownHeading>;

  heading_context?: Array<MarkdownHeading>;

  start_line?: number;

  num_lines?: number;

  file_extension?: string | null;

  frontmatter?: { [key: string]: unknown };
}

export interface MarkdownHeading {
  level: number;

  text: string;
}

export interface TextChunkGeneratedMetadata {
  type?: 'text';

  file_type?: 'text/plain' | 'message/rfc822';

  language?: string | null;

  word_count?: number | null;

  file_size?: number | null;

  start_line?: number;

  num_lines?: number;

  file_extension?: string | null;
}

export interface PdfChunkGeneratedMetadata {
  type?: 'pdf';

  file_type?: 'application/pdf';

  total_pages?: number | null;

  total_size?: number | null;

  file_extension?: string | null;

  /**
   * Per-page layout for chunks parsed in high-quality (visual) mode.
   *
   * ``elements`` are ordered by reading order (list position == reading order).
   * ``width``/``height`` are the page-image dimensions the ``bbox`` coords are
   * relative to, so consumers can normalize/render without a second fetch.
   *
   * Layout is part of the generated metadata payload and is returned with the chunk
   * whenever present.
   */
  layout?: PdfChunkGeneratedMetadata.Layout | null;
}

export namespace PdfChunkGeneratedMetadata {
  /**
   * Per-page layout for chunks parsed in high-quality (visual) mode.
   *
   * ``elements`` are ordered by reading order (list position == reading order).
   * ``width``/``height`` are the page-image dimensions the ``bbox`` coords are
   * relative to, so consumers can normalize/render without a second fetch.
   *
   * Layout is part of the generated metadata payload and is returned with the chunk
   * whenever present.
   */
  export interface Layout {
    width?: number | null;

    height?: number | null;

    elements?: Array<PdfChunkGeneratedMetadata.LayoutElement>;
  }

  /**
   * A single detected layout element and its location on the page image.
   */
  export interface LayoutElement {
    bbox: Array<unknown>;

    type: string;

    text?: string | null;
  }
}

export interface CodeChunkGeneratedMetadata {
  type?: 'code';

  file_type: string;

  language?: string | null;

  word_count?: number | null;

  file_size?: number | null;

  start_line?: number;

  num_lines?: number;

  file_extension?: string | null;
}

export interface AudioChunkGeneratedMetadata {
  type?: 'audio';

  file_type?: string;

  file_size?: number | null;

  total_duration_seconds?: number | null;

  sample_rate?: number | null;

  channels?: number | null;

  audio_format?: number | null;

  bpm?: number | null;

  file_extension?: string | null;
}

export interface VideoChunkGeneratedMetadata {
  type?: 'video';

  file_type?: string;

  file_size?: number | null;

  total_duration_seconds?: number | null;

  fps?: number | null;

  width?: number | null;

  height?: number | null;

  frame_count?: number | null;

  has_audio_stream?: boolean;

  bpm?: number | null;

  file_extension?: string | null;
}

export interface ImageChunkGeneratedMetadata {
  type?: 'image';

  file_type?: string;

  file_size?: number | null;

  width?: number | null;

  height?: number | null;

  file_extension?: string | null;

  /**
   * Per-page layout for chunks parsed in high-quality (visual) mode.
   *
   * ``elements`` are ordered by reading order (list position == reading order).
   * ``width``/``height`` are the page-image dimensions the ``bbox`` coords are
   * relative to, so consumers can normalize/render without a second fetch.
   *
   * Layout is part of the generated metadata payload and is returned with the chunk
   * whenever present.
   */
  layout?: ImageChunkGeneratedMetadata.Layout | null;
}

export namespace ImageChunkGeneratedMetadata {
  /**
   * Per-page layout for chunks parsed in high-quality (visual) mode.
   *
   * ``elements`` are ordered by reading order (list position == reading order).
   * ``width``/``height`` are the page-image dimensions the ``bbox`` coords are
   * relative to, so consumers can normalize/render without a second fetch.
   *
   * Layout is part of the generated metadata payload and is returned with the chunk
   * whenever present.
   */
  export interface Layout {
    width?: number | null;

    height?: number | null;

    elements?: Array<ImageChunkGeneratedMetadata.LayoutElement>;
  }

  /**
   * A single detected layout element and its location on the page image.
   */
  export interface LayoutElement {
    bbox: Array<unknown>;

    type: string;

    text?: string | null;
  }
}

/**
 * Model for audio URL validation.
 */
export interface AudioURL {
  /**
   * The audio URL. Can be either a URL or a Data URI.
   */
  url: string;
}

/**
 * Model for image URL validation.
 */
export interface ImageURLOutput {
  /**
   * The image URL. Can be either a URL or a Data URI.
   */
  url: string;

  /**
   * The image format/mimetype
   */
  format?: string;
}

/**
 * Model for video URL validation.
 */
export interface VideoURL {
  /**
   * The video URL. Can be either a URL or a Data URI.
   */
  url: string;
}

/**
 * Configuration for a store.
 */
export interface StoreConfig {
  /**
   * Include additional context when embedding chunks.
   */
  contextualization?: StoreConfig.Contextualization;

  /**
   * Whether to save original content in the store. When False, only vectors are
   * indexed without the original content (index-only mode). This is useful for data
   * privacy. Note: Reranking is not supported when content is not saved.
   */
  save_content?: boolean;

  /**
   * Learned-scoring-function settings a store opts into; an empty object enables it.
   */
  lsf?: { [key: string]: unknown } | null;
}

export namespace StoreConfig {
  export type Contextualization = boolean | ContextualizationConfig;
}

export interface ContextualizationConfig {
  /**
   * Include all metadata or specific fields in the contextualization. Supports dot
   * notation for nested fields (e.g., 'author.name'). When True, all metadata is
   * included (flattened). When a list, only specified fields are included.
   */
  with_metadata?: boolean | Array<string>;

  /**
   * Use an LLM to generate a short context for each chunk that situates it within
   * the full document, improving retrieval accuracy.
   */
  with_file_context?: boolean;
}

/**
 * Tracks counts of files in different states within a store.
 */
export interface FileCounts {
  /**
   * Number of files waiting to be processed
   */
  pending?: number;

  /**
   * Number of files currently being processed
   */
  in_progress?: number;

  /**
   * Number of files whose processing was cancelled
   */
  cancelled?: number;

  /**
   * Number of successfully processed files
   */
  completed?: number;

  /**
   * Number of files that failed processing
   */
  failed?: number;

  /**
   * Total number of files
   */
  total?: number;
}

/**
 * Represents a reranking configuration.
 */
export interface RerankConfig {
  /**
   * The name of the reranking model
   */
  model?: string;

  /**
   * Whether to include metadata in the reranked results
   */
  with_metadata?: boolean | Array<string>;

  /**
   * Maximum number of results to return after reranking. If None, returns all
   * reranked results.
   */
  top_k?: number | null;
}

/**
 * Configuration for agentic multi-query search.
 */
export interface AgenticSearchConfig {
  /**
   * Maximum number of search rounds
   */
  max_rounds?: number;

  /**
   * Maximum queries per round
   */
  queries_per_round?: number;

  /**
   * Whether the agent fills the final ranking to top_k chunks from what it
   * retrieved, capped at top_k, instead of returning only the chunks it judged
   * relevant
   */
  strict_top_k?: boolean;

  /**
   * Controls when retrieved image content is provided to the agent. `auto` sends
   * images only when no OCR text or summary is available, `never` disables image
   * content, and `always` sends image content when available. Currently not
   * forwarded: the search agent runs without image content.
   */
  media_content?: 'auto' | 'never' | 'always';

  /**
   * Additional custom instructions (followed only when not in conflict with existing
   * rules)
   */
  instructions?: string | null;

  /**
   * Internal: when set, the response includes a `trace` field with the full
   * tool-call timeline. Used by the Mixedbread playground; not part of the
   * documented public API.
   */
  verbose?: boolean;
}

/**
 * Response model for store deletion.
 */
export interface StoreDeleteResponse {
  /**
   * ID of the deleted store
   */
  id: string;

  /**
   * Whether the deletion was successful
   */
  deleted: boolean;

  /**
   * Type of the deleted object
   */
  object?: 'store';
}

export interface StoreGrepResponse {
  /**
   * The object type of the response
   */
  object?: 'list';

  /**
   * The list of chunks matching the pattern
   */
  data: Array<StoreGrepResponse.Data>;
}

export namespace StoreGrepResponse {
  export type Data =
    | ScoredTextInputChunk
    | ScoredImageURLInputChunk
    | ScoredAudioURLInputChunk
    | ScoredVideoURLInputChunk;
}

export interface StoreListChunksResponse {
  /**
   * The object type of the response
   */
  object?: 'list';

  /**
   * The list of chunks matching the metadata filters
   */
  data: Array<StoreListChunksResponse.Data>;
}

export namespace StoreListChunksResponse {
  export type Data =
    | ScoredTextInputChunk
    | ScoredImageURLInputChunk
    | ScoredAudioURLInputChunk
    | ScoredVideoURLInputChunk;
}

/**
 * Represents metadata facets for a store.
 */
export interface StoreMetadataFacetsResponse {
  /**
   * Metadata facets
   */
  facets: { [key: string]: { [key: string]: unknown } };
}

/**
 * Results from a question answering operation.
 */
export interface StoreQuestionAnsweringResponse {
  /**
   * The answer generated by the LLM
   */
  answer: string;

  /**
   * Source documents used to generate the answer
   */
  sources?: Array<StoreQuestionAnsweringResponse.Source>;
}

export namespace StoreQuestionAnsweringResponse {
  export type Source =
    | ScoredTextInputChunk
    | ScoredImageURLInputChunk
    | ScoredAudioURLInputChunk
    | ScoredVideoURLInputChunk;
}

export interface StoreSearchResponse {
  /**
   * The object type of the response
   */
  object?: 'list';

  /**
   * The list of scored store file chunks
   */
  data: Array<StoreSearchResponse.Data>;
}

export namespace StoreSearchResponse {
  export type Data =
    | ScoredTextInputChunk
    | ScoredImageURLInputChunk
    | ScoredAudioURLInputChunk
    | ScoredVideoURLInputChunk;
}

export interface StoreCreateParams {
  /**
   * Name for the new store. Can only contain lowercase letters, numbers, periods
   * (.), and hyphens (-).
   */
  name?: string | null;

  /**
   * Description of the store
   */
  description?: string | null;

  /**
   * Whether the store can be accessed by anyone with valid login credentials
   */
  is_public?: boolean;

  /**
   * License for public stores
   */
  license?: string | null;

  /**
   * Represents an expiration policy for a store.
   */
  expires_after?: ExpiresAfter | null;

  /**
   * Optional metadata key-value pairs
   */
  metadata?: unknown;

  /**
   * Configuration for a store.
   */
  config?: StoreConfig | null;

  /**
   * Optional list of file IDs
   */
  file_ids?: Array<string> | null;
}

export interface StoreUpdateParams {
  /**
   * New name for the store. Can only contain lowercase letters, numbers, periods
   * (.), and hyphens (-).
   */
  name?: string | null;

  /**
   * New description
   */
  description?: string | null;

  /**
   * Whether the store can be accessed by anyone with valid login credentials
   */
  is_public?: boolean | null;

  /**
   * License for public stores
   */
  license?: string | null;

  /**
   * Represents an expiration policy for a store.
   */
  expires_after?: ExpiresAfter | null;

  /**
   * Optional metadata key-value pairs
   */
  metadata?: unknown;
}

export interface StoreListParams extends CursorParams {
  /**
   * Search query for fuzzy matching over name and description fields
   */
  q?: string | null;
}

export interface StoreCopyParams {
  /**
   * Name for the copy. Can only contain lowercase letters, numbers, periods (.), and
   * hyphens (-).
   */
  name: string;

  /**
   * Description of the copy; defaults to the source store's description
   */
  description?: string | null;

  /**
   * Metadata for the copy; defaults to the source store's metadata
   */
  metadata?: unknown;
}

export interface StoreGrepParams {
  /**
   * Header param: Ticket from a chat completion's `tool_tickets`, proving this call
   * runs a tool call that completion asked for. Redeems once, and bills the
   * operation at the discounted agent rate.
   */
  'X-Mxbai-Tool-Ticket'?: string;

  /**
   * Body param: IDs or names of stores
   */
  store_identifiers: Array<string>;

  /**
   * Body param: Number of results to return
   */
  top_k?: number;

  /**
   * Body param: Optional filter conditions
   */
  filters?: StoreGrepParams.Filters | null;

  /**
   * Body param: Optional list of file IDs to filter chunks by (inclusion filter)
   */
  file_ids?: Array<unknown> | Array<string> | null;

  /**
   * Body param: Regular expression (RE2 syntax) matched against chunk text
   */
  pattern: string;

  /**
   * Body param: Chunk content groups to match against. `text` matches the original
   * text of text chunks; `generated` matches ingestion-derived fields
   * (transcription, OCR text, summaries).
   */
  targets?: Array<'text' | 'generated'>;

  /**
   * Body param: Whether the regular expression is case-sensitive
   */
  case_sensitive?: boolean;

  /**
   * Body param: Whether to return file metadata
   */
  return_metadata?: boolean;
}

export namespace StoreGrepParams {
  export type FiltersUnionMember2 = Shared.SearchFilter | Shared.SearchFilterCondition;

  export type Filters =
    | Shared.SearchFilter
    | Shared.SearchFilterCondition
    | Array<StoreGrepParams.FiltersUnionMember2>
    | null;
}

export interface StoreListChunksParams {
  /**
   * IDs or names of stores
   */
  store_identifiers: Array<string>;

  /**
   * Number of results to return
   */
  top_k?: number;

  /**
   * Optional filter conditions
   */
  filters?: StoreListChunksParams.Filters | null;

  /**
   * Optional list of file IDs to filter chunks by (inclusion filter)
   */
  file_ids?: Array<unknown> | Array<string> | null;

  /**
   * Optional sort applied to the returned chunks. Pass a metadata field path or a
   * tuple of (field path, ascending). Unprefixed dot paths target file metadata;
   * generated_metadata.* targets chunk metadata.
   */
  sort_by?: string | Array<unknown> | null;

  /**
   * Search configuration options
   */
  search_options?: StoreChunkSearchOptions;
}

export namespace StoreListChunksParams {
  export type FiltersUnionMember2 = Shared.SearchFilter | Shared.SearchFilterCondition;

  export type Filters =
    | Shared.SearchFilter
    | Shared.SearchFilterCondition
    | Array<StoreListChunksParams.FiltersUnionMember2>
    | null;
}

export interface StoreMetadataFacetsParams {
  /**
   * IDs or names of stores
   */
  store_identifiers: Array<string>;

  /**
   * Number of results to return
   */
  top_k?: number;

  /**
   * Optional filter conditions
   */
  filters?: StoreMetadataFacetsParams.Filters | null;

  /**
   * Optional list of file IDs to filter chunks by (inclusion filter)
   */
  file_ids?: Array<unknown> | Array<string> | null;

  /**
   * Search query text
   */
  query?: string | null;

  /**
   * Search configuration options
   */
  search_options?: StoreChunkSearchOptions;

  /**
   * Optional list of facets to return. Use dot for nested fields.
   */
  facets?: Array<string> | null;

  /**
   * Maximum number of distinct metadata fields (keys) to return.
   */
  max_fields?: number;

  /**
   * Maximum number of distinct values returned per field, ranked by count.
   */
  max_values_per_field?: number;

  /**
   * Maximum number of store files scanned to compute facets.
   */
  max_files?: number;
}

export namespace StoreMetadataFacetsParams {
  export type FiltersUnionMember2 = Shared.SearchFilter | Shared.SearchFilterCondition;

  export type Filters =
    | Shared.SearchFilter
    | Shared.SearchFilterCondition
    | Array<StoreMetadataFacetsParams.FiltersUnionMember2>
    | null;
}

export interface StoreQuestionAnsweringParams {
  /**
   * IDs or names of stores
   */
  store_identifiers: Array<string>;

  /**
   * Number of results to return
   */
  top_k?: number;

  /**
   * Optional filter conditions
   */
  filters?: StoreQuestionAnsweringParams.Filters | null;

  /**
   * Optional list of file IDs to filter chunks by (inclusion filter)
   */
  file_ids?: Array<unknown> | Array<string> | null;

  /**
   * Question to answer. If not provided, the question will be extracted from the
   * passed messages.
   */
  query?: string;

  /**
   * Search configuration options
   */
  search_options?: StoreChunkSearchOptions;

  /**
   * Internal: when set, the response is a server-sent event stream of the retrieved
   * chunks, live trace events, and finally the answer. Used by the Mixedbread
   * playground; not part of the documented public API.
   */
  stream?: boolean;

  /**
   * Additional custom instructions (followed only when not in conflict with existing
   * rules)
   */
  instructions?: string | null;

  /**
   * Question answering configuration options
   */
  qa_options?: StoreQuestionAnsweringParams.QaOptions;
}

export namespace StoreQuestionAnsweringParams {
  export type FiltersUnionMember2 = Shared.SearchFilter | Shared.SearchFilterCondition;

  export type Filters =
    | Shared.SearchFilter
    | Shared.SearchFilterCondition
    | Array<StoreQuestionAnsweringParams.FiltersUnionMember2>
    | null;

  /**
   * Question answering configuration options
   */
  export interface QaOptions {
    /**
     * Whether to use citations
     */
    cite?: boolean;

    /**
     * Whether to use multimodal context
     */
    multimodal?: boolean;
  }
}

export interface StoreSearchParams {
  /**
   * Header param: Ticket from a chat completion's `tool_tickets`, proving this call
   * runs a tool call that completion asked for. Redeems once, and bills the
   * operation at the discounted agent rate.
   */
  'X-Mxbai-Tool-Ticket'?: string;

  /**
   * Body param: IDs or names of stores
   */
  store_identifiers: Array<string>;

  /**
   * Body param: Number of results to return
   */
  top_k?: number;

  /**
   * Body param: Optional filter conditions
   */
  filters?: StoreSearchParams.Filters | null;

  /**
   * Body param: Optional list of file IDs to filter chunks by (inclusion filter)
   */
  file_ids?: Array<unknown> | Array<string> | null;

  /**
   * Body param: Search query text
   */
  query: StoreSearchParams.Query;

  /**
   * Body param: Search configuration options
   */
  search_options?: StoreChunkSearchOptions;

  /**
   * Body param: When true, return the search as a server-sent event stream: live
   * agentic-search trace events when the search is agentic, and nothing before the
   * results otherwise. A successful stream ends with a search.completed event
   * containing the final search response, followed by [DONE].
   */
  stream?: boolean;
}

export namespace StoreSearchParams {
  export type FiltersUnionMember2 = Shared.SearchFilter | Shared.SearchFilterCondition;

  export type Filters =
    | Shared.SearchFilter
    | Shared.SearchFilterCondition
    | Array<StoreSearchParams.FiltersUnionMember2>
    | null;

  export type Query = string | ContentAPI.ImageURLInput | ContentAPI.TextInput;
}

Stores.Files = Files;

export declare namespace Stores {
  export {
    type ScoredVideoURLInputChunk as ScoredVideoURLInputChunk,
    type ExpiresAfter as ExpiresAfter,
    type ScoredAudioURLInputChunk as ScoredAudioURLInputChunk,
    type ScoredImageURLInputChunk as ScoredImageURLInputChunk,
    type ScoredTextInputChunk as ScoredTextInputChunk,
    type Store as Store,
    type StoreChunkSearchOptions as StoreChunkSearchOptions,
    type MarkdownChunkGeneratedMetadata as MarkdownChunkGeneratedMetadata,
    type MarkdownHeading as MarkdownHeading,
    type TextChunkGeneratedMetadata as TextChunkGeneratedMetadata,
    type PdfChunkGeneratedMetadata as PdfChunkGeneratedMetadata,
    type CodeChunkGeneratedMetadata as CodeChunkGeneratedMetadata,
    type AudioChunkGeneratedMetadata as AudioChunkGeneratedMetadata,
    type VideoChunkGeneratedMetadata as VideoChunkGeneratedMetadata,
    type ImageChunkGeneratedMetadata as ImageChunkGeneratedMetadata,
    type AudioURL as AudioURL,
    type ImageURLOutput as ImageURLOutput,
    type VideoURL as VideoURL,
    type StoreConfig as StoreConfig,
    type ContextualizationConfig as ContextualizationConfig,
    type FileCounts as FileCounts,
    type RerankConfig as RerankConfig,
    type AgenticSearchConfig as AgenticSearchConfig,
    type StoreDeleteResponse as StoreDeleteResponse,
    type StoreGrepResponse as StoreGrepResponse,
    type StoreListChunksResponse as StoreListChunksResponse,
    type StoreMetadataFacetsResponse as StoreMetadataFacetsResponse,
    type StoreQuestionAnsweringResponse as StoreQuestionAnsweringResponse,
    type StoreSearchResponse as StoreSearchResponse,
    type StoresCursor as StoresCursor,
    type StoreCreateParams as StoreCreateParams,
    type StoreUpdateParams as StoreUpdateParams,
    type StoreListParams as StoreListParams,
    type StoreCopyParams as StoreCopyParams,
    type StoreGrepParams as StoreGrepParams,
    type StoreListChunksParams as StoreListChunksParams,
    type StoreMetadataFacetsParams as StoreMetadataFacetsParams,
    type StoreQuestionAnsweringParams as StoreQuestionAnsweringParams,
    type StoreSearchParams as StoreSearchParams,
    type StorePollHelperParams as StorePollHelperParams,
    type StoreCopyAndPollHelperParams as StoreCopyAndPollHelperParams,
    type StoreHelpers as StoreHelpers,
  };

  export {
    Files as Files,
    type StoreFileStatus as StoreFileStatus,
    type StoreFile as StoreFile,
    type StoreFileConfig as StoreFileConfig,
    type TextInputChunk as TextInputChunk,
    type ImageURLInputChunk as ImageURLInputChunk,
    type AudioURLInputChunk as AudioURLInputChunk,
    type VideoURLInputChunk as VideoURLInputChunk,
    type FileListResponse as FileListResponse,
    type FileDeleteResponse as FileDeleteResponse,
    type FileCreateParams as FileCreateParams,
    type FileRetrieveParams as FileRetrieveParams,
    type FileUpdateParams as FileUpdateParams,
    type FileListParams as FileListParams,
    type FileDeleteParams as FileDeleteParams,
    type FilePollHelperParams as FilePollHelperParams,
    type FileCreateAndPollHelperParams as FileCreateAndPollHelperParams,
    type FileUploadHelperParams as FileUploadHelperParams,
    type FileUploadAndPollHelperParams as FileUploadAndPollHelperParams,
    type StoreFileHelpers as StoreFileHelpers,
  };
}