@mixedbread/sdk 0.1.0-alpha.8

package/src/error.ts

@@ -0,0 +1,130 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { castToError, Headers } from './core';
+
+export class MixedbreadError extends Error {}
+
+export class APIError<
+  TStatus extends number | undefined = number | undefined,
+  THeaders extends Headers | undefined = Headers | undefined,
+  TError extends Object | undefined = Object | undefined,
+> extends MixedbreadError {
+  /** HTTP status for the response that caused the error */
+  readonly status: TStatus;
+  /** HTTP headers for the response that caused the error */
+  readonly headers: THeaders;
+  /** JSON body of the response that caused the error */
+  readonly error: TError;
+
+  constructor(status: TStatus, error: TError, message: string | undefined, headers: THeaders) {
+    super(`${APIError.makeMessage(status, error, message)}`);
+    this.status = status;
+    this.headers = headers;
+    this.error = error;
+  }
+
+  private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+    const msg =
+      error?.message ?
+        typeof error.message === 'string' ?
+          error.message
+        : JSON.stringify(error.message)
+      : error ? JSON.stringify(error)
+      : message;
+
+    if (status && msg) {
+      return `${status} ${msg}`;
+    }
+    if (status) {
+      return `${status} status code (no body)`;
+    }
+    if (msg) {
+      return msg;
+    }
+    return '(no status code or body)';
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ): APIError {
+    if (!status || !headers) {
+      return new APIConnectionError({ message, cause: castToError(errorResponse) });
+    }
+
+    const error = errorResponse as Record<string, any>;
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers);
+    }
+
+    return new APIError(status, error, message, headers);
+  }
+}
+
+export class APIUserAbortError extends APIError<undefined, undefined, undefined> {
+  constructor({ message }: { message?: string } = {}) {
+    super(undefined, undefined, message || 'Request was aborted.', undefined);
+  }
+}
+
+export class APIConnectionError extends APIError<undefined, undefined, undefined> {
+  constructor({ message, cause }: { message?: string | undefined; cause?: Error | undefined }) {
+    super(undefined, undefined, message || 'Connection error.', undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
+  }
+}
+
+export class BadRequestError extends APIError<400, Headers> {}
+
+export class AuthenticationError extends APIError<401, Headers> {}
+
+export class PermissionDeniedError extends APIError<403, Headers> {}
+
+export class NotFoundError extends APIError<404, Headers> {}
+
+export class ConflictError extends APIError<409, Headers> {}
+
+export class UnprocessableEntityError extends APIError<422, Headers> {}
+
+export class RateLimitError extends APIError<429, Headers> {}
+
+export class InternalServerError extends APIError<number, Headers> {}

package/src/index.ts

@@ -0,0 +1,294 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { type Agent } from './_shims/index';
+import * as Core from './core';
+import * as Errors from './error';
+import * as Pagination from './pagination';
+import { type LimitOffsetParams, LimitOffsetResponse } from './pagination';
+import * as Uploads from './uploads';
+import * as API from './resources/index';
+import * as TopLevelAPI from './resources/top-level';
+import { InfoResponse } from './resources/top-level';
+import {
+  FileCreateParams,
+  FileDeleteResponse,
+  FileListParams,
+  FileObject,
+  FileObjectsLimitOffset,
+  FileUpdateParams,
+  Files,
+} from './resources/files';
+import { Extractions } from './resources/extractions/extractions';
+import { Parsing } from './resources/parsing/parsing';
+import {
+  ExpiresAfter,
+  FileCounts,
+  ScoredVectorStoreChunk,
+  VectorStore,
+  VectorStoreCreateParams,
+  VectorStoreDeleteResponse,
+  VectorStoreListParams,
+  VectorStoreQuestionAnsweringParams,
+  VectorStoreQuestionAnsweringResponse,
+  VectorStoreSearchOptions,
+  VectorStoreSearchParams,
+  VectorStoreSearchResponse,
+  VectorStoreUpdateParams,
+  VectorStores,
+  VectorStoresLimitOffset,
+} from './resources/vector-stores/vector-stores';
+
+const environments = {
+  production: 'https://api.mixedbread.ai',
+  local: 'http://127.0.0.1:8000',
+};
+type Environment = keyof typeof environments;
+
+export interface ClientOptions {
+  /**
+   * Api key to authenticate with Mixedbread
+   */
+  apiKey?: string | undefined;
+
+  /**
+   * Specifies the environment to use for the API.
+   *
+   * Each environment maps to a different base URL:
+   * - `production` corresponds to `https://api.mixedbread.ai`
+   * - `local` corresponds to `http://127.0.0.1:8000`
+   */
+  environment?: Environment | undefined;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   *
+   * Defaults to process.env['MIXEDBREAD_BASE_URL'].
+   */
+  baseURL?: string | null | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
+  timeout?: number | undefined;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
+  httpAgent?: Agent | undefined;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+   * defined globally.
+   */
+  fetch?: Core.Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
+  maxRetries?: number | undefined;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
+  defaultHeaders?: Core.Headers | undefined;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Core.DefaultQuery | undefined;
+}
+
+/**
+ * API Client for interfacing with the Mixedbread API.
+ */
+export class Mixedbread extends Core.APIClient {
+  apiKey: string;
+
+  private _options: ClientOptions;
+
+  /**
+   * API Client for interfacing with the Mixedbread API.
+   *
+   * @param {string | undefined} [opts.apiKey=process.env['MXBAI_API_KEY'] ?? undefined]
+   * @param {Environment} [opts.environment=production] - Specifies the environment URL to use for the API.
+   * @param {string} [opts.baseURL=process.env['MIXEDBREAD_BASE_URL'] ?? https://api.mixedbread.ai] - Override the default base URL for the API.
+   * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
+   * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+   * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+   * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+   */
+  constructor({
+    baseURL = Core.readEnv('MIXEDBREAD_BASE_URL'),
+    apiKey = Core.readEnv('MXBAI_API_KEY'),
+    ...opts
+  }: ClientOptions = {}) {
+    if (apiKey === undefined) {
+      throw new Errors.MixedbreadError(
+        "The MXBAI_API_KEY environment variable is missing or empty; either provide it, or instantiate the Mixedbread client with an apiKey option, like new Mixedbread({ apiKey: 'My API Key' }).",
+      );
+    }
+
+    const options: ClientOptions = {
+      apiKey,
+      ...opts,
+      baseURL,
+      environment: opts.environment ?? 'production',
+    };
+
+    if (baseURL && opts.environment) {
+      throw new Errors.MixedbreadError(
+        'Ambiguous URL; The `baseURL` option (or MIXEDBREAD_BASE_URL env var) and the `environment` option are given. If you want to use the environment you must pass baseURL: null',
+      );
+    }
+
+    super({
+      baseURL: options.baseURL || environments[options.environment || 'production'],
+      timeout: options.timeout ?? 60000 /* 1 minute */,
+      httpAgent: options.httpAgent,
+      maxRetries: options.maxRetries,
+      fetch: options.fetch,
+    });
+
+    this._options = options;
+
+    this.apiKey = apiKey;
+  }
+
+  parsing: API.Parsing = new API.Parsing(this);
+  files: API.Files = new API.Files(this);
+  vectorStores: API.VectorStores = new API.VectorStores(this);
+  extractions: API.Extractions = new API.Extractions(this);
+
+  /**
+   * Returns service information, including name and version.
+   *
+   * Returns: InfoResponse: A response containing the service name and version.
+   */
+  info(options?: Core.RequestOptions): Core.APIPromise<TopLevelAPI.InfoResponse> {
+    return this.get('/', options);
+  }
+
+  protected override defaultQuery(): Core.DefaultQuery | undefined {
+    return this._options.defaultQuery;
+  }
+
+  protected override defaultHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return {
+      ...super.defaultHeaders(opts),
+      ...this._options.defaultHeaders,
+    };
+  }
+
+  protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return { Authorization: `Bearer ${this.apiKey}` };
+  }
+
+  static Mixedbread = this;
+  static DEFAULT_TIMEOUT = 60000; // 1 minute
+
+  static MixedbreadError = Errors.MixedbreadError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static BadRequestError = Errors.BadRequestError;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
+
+  static toFile = Uploads.toFile;
+  static fileFromPath = Uploads.fileFromPath;
+}
+
+Mixedbread.Parsing = Parsing;
+Mixedbread.Files = Files;
+Mixedbread.FileObjectsLimitOffset = FileObjectsLimitOffset;
+Mixedbread.VectorStores = VectorStores;
+Mixedbread.VectorStoresLimitOffset = VectorStoresLimitOffset;
+Mixedbread.Extractions = Extractions;
+export declare namespace Mixedbread {
+  export type RequestOptions = Core.RequestOptions;
+
+  export import LimitOffset = Pagination.LimitOffset;
+  export { type LimitOffsetParams as LimitOffsetParams, type LimitOffsetResponse as LimitOffsetResponse };
+
+  export { type InfoResponse as InfoResponse };
+
+  export { Parsing as Parsing };
+
+  export {
+    Files as Files,
+    type FileObject as FileObject,
+    type FileDeleteResponse as FileDeleteResponse,
+    FileObjectsLimitOffset as FileObjectsLimitOffset,
+    type FileCreateParams as FileCreateParams,
+    type FileUpdateParams as FileUpdateParams,
+    type FileListParams as FileListParams,
+  };
+
+  export {
+    VectorStores as VectorStores,
+    type ExpiresAfter as ExpiresAfter,
+    type FileCounts as FileCounts,
+    type ScoredVectorStoreChunk as ScoredVectorStoreChunk,
+    type VectorStore as VectorStore,
+    type VectorStoreSearchOptions as VectorStoreSearchOptions,
+    type VectorStoreDeleteResponse as VectorStoreDeleteResponse,
+    type VectorStoreQuestionAnsweringResponse as VectorStoreQuestionAnsweringResponse,
+    type VectorStoreSearchResponse as VectorStoreSearchResponse,
+    VectorStoresLimitOffset as VectorStoresLimitOffset,
+    type VectorStoreCreateParams as VectorStoreCreateParams,
+    type VectorStoreUpdateParams as VectorStoreUpdateParams,
+    type VectorStoreListParams as VectorStoreListParams,
+    type VectorStoreQuestionAnsweringParams as VectorStoreQuestionAnsweringParams,
+    type VectorStoreSearchParams as VectorStoreSearchParams,
+  };
+
+  export { Extractions as Extractions };
+
+  export type SearchFilter = API.SearchFilter;
+  export type SearchFilterCondition = API.SearchFilterCondition;
+}
+
+export { toFile, fileFromPath } from './uploads';
+export {
+  MixedbreadError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  BadRequestError,
+  AuthenticationError,
+  InternalServerError,
+  PermissionDeniedError,
+  UnprocessableEntityError,
+} from './error';
+
+export default Mixedbread;

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/lib/polling.ts

@@ -0,0 +1,115 @@
+/**
+ * Utilities for polling operations
+ */
+
+type ConditionFunction<T> = (result: T) => boolean;
+type IntervalFunction<T> = (result: T) => number;
+type ErrorHandlerFunction = (error: Error) => number | null;
+type RetryCallback<T> = (result: T, attempt: number) => void;
+
+// Use a more generic setTimeout type
+declare const setTimeout: (callback: (...args: any[]) => void, ms: number) => any;
+
+/**
+ * Configuration options for the poll function.
+ */
+export interface PollOptions<T> {
+  /** Async function that performs the operation to be polled */
+  fn: () => Promise<T>;
+  /** Function that evaluates if the polling should continue */
+  condition: ConditionFunction<T>;
+  /** Maximum number of polling attempts (undefined for infinite) */
+  maxAttempts?: number;
+  /** Maximum total time to poll in seconds (undefined for infinite) */
+  timeoutSeconds?: number;
+  /** Time between polls in seconds, or function that returns interval */
+  intervalSeconds?: number | IntervalFunction<T>;
+  /** Optional callback for each retry attempt */
+  onRetry?: RetryCallback<T>;
+  /** Optional callback for handling exceptions during polling */
+  errorHandler?: ErrorHandlerFunction;
+}
+
+/**
+ * Asynchronously polls an operation until a condition is met or timeout/max attempts are reached.
+ *
+ * @param options - Configuration options for polling
+ * @returns The result of the operation once condition is met
+ * @throws Error if maxAttempts is reached
+ * @throws Error if timeoutSeconds is reached
+ *
+ * @example
+ * ```typescript
+ * const result = await poll({
+ *   fn: () => fetchData(),
+ *   condition: (result) => result.status === 'completed',
+ *   maxAttempts: 5,
+ *   timeoutSeconds: 60,
+ *   intervalSeconds: 2
+ * });
+ * ```
+ */
+export async function poll<T>(options: PollOptions<T>): Promise<T> {
+  const {
+    fn,
+    condition,
+    maxAttempts,
+    timeoutSeconds,
+    intervalSeconds = 1.0,
+    onRetry,
+    errorHandler,
+  } = options;
+
+  const startTime = new Date();
+  let attempt = 0;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    attempt += 1;
+
+    try {
+      const result = await fn();
+
+      if (condition(result)) {
+        return result;
+      }
+
+      if (onRetry) {
+        onRetry(result, attempt);
+      }
+
+      let waitTime: number;
+
+      if (typeof intervalSeconds === 'function') {
+        waitTime = intervalSeconds(result);
+      } else {
+        waitTime = intervalSeconds;
+      }
+
+      // Check timeout and attempts before sleeping
+      if (maxAttempts && attempt >= maxAttempts) {
+        throw new Error(`Maximum attempts (${maxAttempts}) reached`);
+      }
+
+      if (timeoutSeconds) {
+        const elapsed = (new Date().getTime() - startTime.getTime()) / 1000;
+        if (elapsed >= timeoutSeconds) {
+          throw new Error(`Timeout (${timeoutSeconds}s) reached`);
+        }
+      }
+
+      // Sleep asynchronously
+      await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
+    } catch (e) {
+      if (errorHandler && e instanceof Error) {
+        const sleepTime = errorHandler(e);
+        if (sleepTime !== null) {
+          // Sleep and continue
+          await new Promise((resolve) => setTimeout(resolve, sleepTime * 1000));
+          continue;
+        }
+      }
+      throw e;
+    }
+  }
+}

package/src/pagination.ts

@@ -0,0 +1,82 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
+
+export interface LimitOffsetResponse<Item> {
+  data: Array<Item>;
+
+  pagination: LimitOffsetResponse.Pagination;
+}
+
+export namespace LimitOffsetResponse {
+  export interface Pagination {
+    total?: number;
+
+    offset?: number;
+  }
+}
+
+export interface LimitOffsetParams {
+  /**
+   * The number of elements to skip.
+   */
+  offset?: number;
+
+  /**
+   * The maximum number of elements to fetch.
+   */
+  limit?: number;
+}
+
+export class LimitOffset<Item> extends AbstractPage<Item> implements LimitOffsetResponse<Item> {
+  data: Array<Item>;
+
+  pagination: LimitOffsetResponse.Pagination;
+
+  constructor(
+    client: APIClient,
+    response: Response,
+    body: LimitOffsetResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.data = body.data || [];
+    this.pagination = body.pagination || {};
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  // @deprecated Please use `nextPageInfo()` instead
+  nextPageParams(): Partial<LimitOffsetParams> | null {
+    const info = this.nextPageInfo();
+    if (!info) return null;
+    if ('params' in info) return info.params;
+    const params = Object.fromEntries(info.url.searchParams);
+    if (!Object.keys(params).length) return null;
+    return params;
+  }
+
+  nextPageInfo(): PageInfo | null {
+    const offset = this.pagination?.offset;
+    if (!offset) {
+      return null;
+    }
+
+    const length = this.getPaginatedItems().length;
+    const currentCount = offset + length;
+
+    const totalCount = this.pagination?.total;
+    if (!totalCount) {
+      return null;
+    }
+
+    if (currentCount < totalCount) {
+      return { params: { offset: currentCount } };
+    }
+
+    return null;
+  }
+}

package/src/resource.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import type { Mixedbread } from './index';
+
+export class APIResource {
+  protected _client: Mixedbread;
+
+  constructor(client: Mixedbread) {
+    this._client = client;
+  }
+}

package/src/resources/extractions/content.ts

@@ -0,0 +1,43 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class Content extends APIResource {
+  /**
+   * Extract content from a string using the provided schema.
+   *
+   * Args: params: The parameters for extracting content from a string.
+   *
+   * Returns: The extracted content.
+   */
+  create(body: ContentCreateParams, options?: Core.RequestOptions): Core.APIPromise<ExtractionResult> {
+    return this._client.post('/v1/extractions/content', { body, ...options });
+  }
+}
+
+/**
+ * Result of an extraction operation.
+ */
+export interface ExtractionResult {
+  /**
+   * The extracted data
+   */
+  data: unknown;
+}
+
+export interface ContentCreateParams {
+  /**
+   * The content to extract from
+   */
+  content: string;
+
+  /**
+   * The JSON schema to use for extraction
+   */
+  json_schema: unknown;
+}
+
+export declare namespace Content {
+  export { type ExtractionResult as ExtractionResult, type ContentCreateParams as ContentCreateParams };
+}