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

import { APIResource } from '../resource';
import { isRequestOptions } from '../core';
import * as Core from '../core';

export class Indexes extends APIResource {
  /**
   * Creates an Index.
   *
   * Indexes are created with unique IDs like `idx_rHlXLhCTma74w1E_xbRXl`. These IDs
   * are unique and cannot be changed. In a future release we will be adding the
   * ability to alias Indexes, supporting names.
   *
   * This is an asynchronous operation.
   *
   * ## Index configuration
   *
   * ### Index types
   *
   * Indexes have an index type that determines how the data inserted is processed.
   *
   * We currently support 5 Index types:
   *
   * 1. text - semantically search text through the optimized combination of
   *    lexical/keyword and neural search capabilities that leverage state-of-the-art
   *    embeddings.
   * 2. multimodal - combines lexical/keyword search and neural search for both text
   *    and image data. Enables searching over text and images with both keyword
   *    precision and semantic understanding.
   * 3. image - semantically search images with text using image embeddings for
   *    search.
   * 4. text-neural - semantically search text content using state of the art text
   *    embeddings for search.
   * 5. multimodal-neural - semantically search text AND image content using
   *    multimodal embeddings for search.
   *
   * ### Indexing fields from Objects
   *
   * Indexes support configuring how fields in Objects that are indexed are
   * processed. The following configurations are supported at a field level:
   *
   * 1. Crawlable - fields which will be crawled and made available for search. Read
   *    more about [crawling](/apis/ingestion/crawling).
   * 2. Searchable - fields which will contribute to search relevance.
   * 3. Filterable - fields which may be filtered upon. Read more about
   *    [filtering](/apis/search/overview#filtering-search-results).
   * 4. Types - A mapping of fields to data types for filterable fields. By default
   *    all filterable fields are considered strings, unless specified here. For more
   *    info on supported types see
   *    [field types](/apis/search/filtering#field-types).
   *
   * **Defaults:**
   *
   * 1. Crawlable - no fields are crawled
   * 2. Filterable - no fields are filterable
   *
   * ### Finetuning
   *
   * Indexes can learn from your feedback, training your index to retrieve more
   * relevant results that better match your unique business needs. To configure
   * `finetuning` set your base index using `base_index_id` and provide `feedback` in
   * the form of `query`, `object_id`, and `label`. Check out the Quickstart guide to
   * get started.
   *
   * Acceptable labels are:
   *
   * - **GREAT**: For objects that you want to encourage retrieving for the specified
   *   query.
   * - **OK**: For objects that have a loose connection to the query but you do not
   *   want to reward.
   * - **BAD**: For objects that you want to discourage retrieving for the specified
   *   query.
   *
   * Constraints:
   *
   * - You must include at least 50 queries
   * - Each query must have at least one object with a “GREAT” label and one object
   *   with a “BAD” label.
   */
  create(body: IndexCreateParams, options?: Core.RequestOptions): Core.APIPromise<IndexCreateResponse> {
    return this._client.post('/indexes', { body, ...options });
  }

  /**
   * Get Indexes
   */
  list(options?: Core.RequestOptions): Core.APIPromise<IndexListResponse> {
    return this._client.get('/indexes', options);
  }

  /**
   * Schedules an Index for deletion.
   *
   * This is an asynchronous operation. If no such Index exists, this does nothing.
   *
   * Search results and other APIs are cached for several minutes not just by this
   * API but possibly by third-party servers out of our control. See
   * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
   * regarding the standard HTTP caching mechanism that we use to improve
   * performance.
   *
   * Returns a JSON object with the ID of the deleted Index.
   */
  delete(indexId: string, options?: Core.RequestOptions): Core.APIPromise<IndexDeleteResponse> {
    return this._client.delete(`/indexes/${indexId}`, options);
  }

  /**
   * Finetune a base index given feedback. Read more about finetuning in our
   * [docs](https://www.objective.inc/docs/quality/finetuning).
   */
  finetune(
    indexId: string,
    body: IndexFinetuneParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<IndexFinetuneResponse> {
    return this._client.post(`/indexes/${indexId}:finetune`, { body, ...options });
  }

  /**
   * Get Index by ID
   *
   * This is an asynchronous operation. If no such Index exists, it will return
   * a 404.
   */
  get(indexId: string, options?: Core.RequestOptions): Core.APIPromise<IndexGetResponse> {
    return this._client.get(`/indexes/${indexId}`, options);
  }

  /**
   * Search for a query in an index
   */
  search(
    indexId: string,
    query?: IndexSearchParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<IndexSearchResponse>;
  search(indexId: string, options?: Core.RequestOptions): Core.APIPromise<IndexSearchResponse>;
  search(
    indexId: string,
    query: IndexSearchParams | Core.RequestOptions = {},
    options?: Core.RequestOptions,
  ): Core.APIPromise<IndexSearchResponse> {
    if (isRequestOptions(query)) {
      return this.search(indexId, {}, query);
    }
    return this._client.get(`/indexes/${indexId}/search`, { query, ...options });
  }

  /**
   * Get an index's status by ID.
   *
   * ## Status
   *
   * Objects within an index can have 4 different status types.
   *
   * 1. `UPLOADED` - The state of an object that is in the object store but is
   *    pending processing.
   * 2. `PROCESSING` - The state of an object that is currently being indexed.
   * 3. `READY` - The state of an object that is live and searchable.
   * 4. `ERROR` - The state of an object that has encountered errors during
   *    processing; you can find out more information about the error by using the
   *    object status API.
   */
  status(indexId: string, options?: Core.RequestOptions): Core.APIPromise<IndexStatusResponse> {
    return this._client.get(`/indexes/${indexId}/status`, options);
  }

  /**
   * Get an index's status by ID and status type.
   *
   * ## Status
   *
   * Objects within an index can have 4 different status types.
   *
   * 1. `UPLOADED` - The state of an object that is in the object store but is
   *    pending processing.
   * 2. `PROCESSING` - The state of an object that is currently being indexed.
   * 3. `READY` - The state of an object that is live and searchable.
   * 4. `ERROR` - The state of an object that has encountered errors during
   *    processing; you can find out more information about the error by using the
   *    object status API.
   */
  statusByType(
    indexId: string,
    indexStatusType: 'UPLOADED' | 'PROCESSING' | 'READY' | 'ERROR' | 'INCOMPLETE',
    options?: Core.RequestOptions,
  ): Core.APIPromise<IndexStatusByTypeResponse> {
    return this._client.get(`/indexes/${indexId}/status/${indexStatusType}`, options);
  }
}

export interface IndexCreateResponse {
  /**
   * Index ID
   */
  id: string;
}

export interface IndexListResponse {
  indexes: Array<IndexListResponse.Index>;

  pagination: IndexListResponse.Pagination;
}

export namespace IndexListResponse {
  export interface Index {
    id: string;

    createdAt: string;

    updatedAt: string;
  }

  export interface Pagination {
    next: string;

    prev: string;
  }
}

export interface IndexDeleteResponse {
  id: string;
}

export interface IndexFinetuneResponse {
  id: string;
}

export interface IndexGetResponse {
  id: string;

  configuration: IndexGetResponse.Configuration;

  created_at: string;
}

export namespace IndexGetResponse {
  export interface Configuration {
    fields: Configuration.Fields;

    index_type: Configuration.IndexType;
  }

  export namespace Configuration {
    export interface Fields {
      crawlable: Fields.Crawlable;

      filterable: Fields.Filterable;

      searchable: Fields.Searchable;

      types: Record<string, 'string' | 'int' | 'float' | 'bool' | 'datetime' | 'geo'>;
    }

    export namespace Fields {
      export interface Crawlable {
        allow: Array<string>;
      }

      export interface Filterable {
        allow: Array<string>;
      }

      export interface Searchable {
        allow: Array<string>;
      }
    }

    export interface IndexType {
      name: string;

      version: string;
    }
  }
}

export interface IndexSearchResponse {
  pagination: IndexSearchResponse.Pagination;

  results: Array<IndexSearchResponse.Result>;
}

export namespace IndexSearchResponse {
  export interface Pagination {
    next: Pagination.Next;

    page: number;

    pages: number;
  }

  export namespace Pagination {
    export interface Next {
      limit: number;

      offset: number;
    }
  }

  export interface Result {
    id: string;

    object?: unknown;
  }
}

export interface IndexStatusResponse {
  status: IndexStatusResponse.Status;
}

export namespace IndexStatusResponse {
  export interface Status {
    ERROR?: number;

    INCOMPLETE?: number;

    PROCESSING?: number;

    READY?: number;

    UPLOADED?: number;
  }
}

export interface IndexStatusByTypeResponse {
  status: IndexStatusByTypeResponse.Status;
}

export namespace IndexStatusByTypeResponse {
  export interface Status {
    ERROR?: number;

    INCOMPLETE?: number;

    PROCESSING?: number;

    READY?: number;

    UPLOADED?: number;
  }
}

export interface IndexCreateParams {
  configuration: IndexCreateParams.Configuration;
}

export namespace IndexCreateParams {
  export interface Configuration {
    fields: Configuration.Fields;

    index_type?: Configuration.IndexType;
  }

  export namespace Configuration {
    export interface Fields {
      searchable: Fields.Searchable;

      crawlable?: Fields.Crawlable;

      fast_filters?: Array<string>;

      filterable?: Fields.Filterable;

      segment_delimiter?: Record<string, unknown>;

      types?: Record<string, string>;
    }

    export namespace Fields {
      export interface Searchable {
        allow: Array<string>;
      }

      export interface Crawlable {
        allow?: Array<string>;
      }

      export interface Filterable {
        allow?: Array<string>;
      }
    }

    export interface IndexType {
      name: 'multimodal' | 'text' | 'image' | 'multimodal-neural' | 'text-neural' | (string & {});

      finetuning?: IndexType.Finetuning;

      highlights?: IndexType.Highlights;

      version?: string;
    }

    export namespace IndexType {
      export interface Finetuning {
        base_index_id: string;

        feedback: Array<Finetuning.Feedback>;
      }

      export namespace Finetuning {
        export interface Feedback {
          query: string;

          label?: 'GREAT' | 'OK' | 'BAD';

          object_id?: string;
        }
      }

      export interface Highlights {
        text?: boolean;
      }
    }
  }
}

export interface IndexFinetuneParams {
  feedback: Array<IndexFinetuneParams.Feedback>;
}

export namespace IndexFinetuneParams {
  export interface Feedback {
    query: string;

    label?: 'GREAT' | 'OK' | 'BAD';

    object_id?: string;
  }
}

export interface IndexSearchParams {
  filter_query?: string;

  limit?: number;

  object_fields?: string;

  offset?: number;

  query?: string;

  ranking_expr?: string;

  relevance_cutoff?: string;

  result_fields?: string;
}

export declare namespace Indexes {
  export {
    type IndexCreateResponse as IndexCreateResponse,
    type IndexListResponse as IndexListResponse,
    type IndexDeleteResponse as IndexDeleteResponse,
    type IndexFinetuneResponse as IndexFinetuneResponse,
    type IndexGetResponse as IndexGetResponse,
    type IndexSearchResponse as IndexSearchResponse,
    type IndexStatusResponse as IndexStatusResponse,
    type IndexStatusByTypeResponse as IndexStatusByTypeResponse,
    type IndexCreateParams as IndexCreateParams,
    type IndexFinetuneParams as IndexFinetuneParams,
    type IndexSearchParams as IndexSearchParams,
  };
}