Skip to content
rachel/workerd
File

Blob: types/defines/ai-search.d.ts

typescript859 lines
1// ============ AI Search Error Interfaces ============
2 
3export interface AiSearchInternalError extends Error {}
4export interface AiSearchNotFoundError extends Error {}
5 
6// ============ AI Search Common Types ============
7 
8/** A single message in a conversation-style search or chat request. */
9export type AiSearchMessage = {
10  role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
11  content: string | null;
12};
13 
14/**
15 * Common shape for `ai_search_options` used by both single-instance and multi-instance requests.
16 * Contains retrieval, query rewrite, reranking, and cache sub-options.
17 */
18export type AiSearchOptions = {
19  retrieval?: {
20    /** Which retrieval backend to use. Defaults to the instance's configured index_method. */
21    retrieval_type?: 'vector' | 'keyword' | 'hybrid';
22    /** Fusion method for combining vector + keyword results. */
23    fusion_method?: 'max' | 'rrf';
24    /** How keyword terms are combined: "and" = all terms must match, "or" = any term matches. */
25    keyword_match_mode?: 'and' | 'or';
26    /** Minimum similarity score (0-1) for a result to be included. Default 0.4. */
27    match_threshold?: number;
28    /** Maximum number of results to return (1-50). Default 10. */
29    max_num_results?: number;
30    /** Vectorize metadata filters applied to the search. */
31    filters?: VectorizeVectorMetadataFilter;
32    /** Number of surrounding chunks to include for context (0-3). Default 0. */
33    context_expansion?: number;
34    /** If true, return only item metadata without chunk text. */
35    metadata_only?: boolean;
36    /** If true (default), return empty results on retrieval failure instead of throwing. */
37    return_on_failure?: boolean;
38    /** Boost results by metadata field values. Max 3 entries. */
39    boost_by?: Array<{
40      field: string;
41      direction?: 'asc' | 'desc' | 'exists' | 'not_exists';
42    }>;
43    [key: string]: unknown;
44  };
45  query_rewrite?: {
46    enabled?: boolean;
47    model?: string;
48    rewrite_prompt?: string;
49    [key: string]: unknown;
50  };
51  reranking?: {
52    enabled?: boolean;
53    model?: string;
54    /** Match threshold (0-1, default 0.4) */
55    match_threshold?: number;
56    [key: string]: unknown;
57  };
58  cache?: {
59    enabled?: boolean;
60    cache_threshold?:
61      | 'super_strict_match'
62      | 'close_enough'
63      | 'flexible_friend'
64      | 'anything_goes';
65  };
66  [key: string]: unknown;
67};
68 
69// ============ AI Search Request Types ============
70 
71/**
72 * Request body for single-instance search.
73 * Exactly one of `query` or `messages` must be provided.
74 */
75export type AiSearchSearchRequest =
76  | {
77      /** Simple query string. */
78      query: string;
79      messages?: never;
80      ai_search_options?: AiSearchOptions;
81    }
82  | {
83      query?: never;
84      /** Conversation-style input. At least one user message with non-empty content is required. */
85      messages: AiSearchMessage[];
86      ai_search_options?: AiSearchOptions;
87    };
88 
89export type AiSearchChatCompletionsRequest = {
90  messages: AiSearchMessage[];
91  model?: string;
92  stream?: boolean;
93  ai_search_options?: AiSearchOptions;
94  [key: string]: unknown;
95};
96 
97// ============ AI Search Multi-Instance Types (Namespace-Scoped) ============
98 
99/** `ai_search_options` shape for multi-instance requests — requires `instance_ids`. */
100export type AiSearchMultiSearchOptions = AiSearchOptions & {
101  /** Instance IDs to search across (1-10). */
102  instance_ids: string[];
103};
104 
105/**
106 * Request for searching across multiple instances within a namespace.
107 * `ai_search_options` is required and must include `instance_ids`.
108 * Exactly one of `query` or `messages` must be provided.
109 */
110export type AiSearchMultiSearchRequest =
111  | {
112      /** Simple query string. */
113      query: string;
114      messages?: never;
115      ai_search_options: AiSearchMultiSearchOptions;
116    }
117  | {
118      query?: never;
119      /** Conversation-style input. */
120      messages: AiSearchMessage[];
121      ai_search_options: AiSearchMultiSearchOptions;
122    };
123 
124/** A search result chunk tagged with the instance it originated from. */
125export type AiSearchMultiSearchChunk =
126  AiSearchSearchResponse['chunks'][number] & {
127    instance_id: string;
128  };
129 
130/** Describes a per-instance error during a multi-instance operation. */
131export type AiSearchMultiSearchError = {
132  instance_id: string;
133  message: string;
134};
135 
136/** Response from a multi-instance search, with chunks tagged by instance and optional partial-failure errors. */
137export type AiSearchMultiSearchResponse = {
138  search_query: string;
139  chunks: AiSearchMultiSearchChunk[];
140  errors?: AiSearchMultiSearchError[];
141};
142 
143/** Request for chat completions across multiple instances within a namespace. `ai_search_options` is required and must include `instance_ids`. */
144export type AiSearchMultiChatCompletionsRequest = Omit<
145  AiSearchChatCompletionsRequest,
146  'ai_search_options'
147> & {
148  ai_search_options: AiSearchMultiSearchOptions;
149};
150 
151/** Response from multi-instance chat completions, with chunks tagged by instance and optional partial-failure errors. */
152export type AiSearchMultiChatCompletionsResponse = Omit<
153  AiSearchChatCompletionsResponse,
154  'chunks'
155> & {
156  chunks: AiSearchMultiSearchChunk[];
157  errors?: AiSearchMultiSearchError[];
158};
159 
160// ============ AI Search Response Types ============
161 
162export type AiSearchSearchResponse = {
163  search_query: string;
164  chunks: Array<{
165    id: string;
166    type: string;
167    /** Match score (0-1) */
168    score: number;
169    text: string;
170    item: {
171      timestamp?: number;
172      key: string;
173      metadata?: Record<string, unknown>;
174    };
175    scoring_details?: {
176      /** Keyword match score (0-1) */
177      keyword_score?: number;
178      /** Vector similarity score (0-1) */
179      vector_score?: number;
180      /** Keyword rank position */
181      keyword_rank?: number;
182      /** Vector rank position */
183      vector_rank?: number;
184      /** Reranking model score */
185      reranking_score?: number;
186      /** Fusion method used to combine results */
187      fusion_method?: 'rrf' | 'max';
188      [key: string]: unknown;
189    };
190  }>;
191};
192 
193export type AiSearchChatCompletionsResponse = {
194  id?: string;
195  object?: string;
196  model?: string;
197  choices: Array<{
198    index?: number;
199    message: {
200      role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
201      content: string | null;
202      [key: string]: unknown;
203    };
204    [key: string]: unknown;
205  }>;
206  chunks: AiSearchSearchResponse['chunks'];
207  [key: string]: unknown;
208};
209 
210export type AiSearchStatsResponse = {
211  queued?: number;
212  running?: number;
213  completed?: number;
214  error?: number;
215  skipped?: number;
216  outdated?: number;
217  last_activity?: string;
218  /** Storage engine statistics. */
219  engine?: {
220    vectorize?: {
221      vectorsCount: number;
222      dimensions: number;
223    };
224    r2?: {
225      payloadSizeBytes: number;
226      metadataSizeBytes: number;
227      objectCount: number;
228    };
229  };
230};
231 
232// ============ AI Search Instance Info Types ============
233 
234export type AiSearchInstanceInfo = {
235  id: string;
236  type?: 'r2' | 'web-crawler' | string;
237  source?: string;
238  source_params?: unknown;
239  paused?: boolean;
240  status?: string;
241  namespace?: string;
242  created_at?: string;
243  modified_at?: string;
244  token_id?: string;
245  ai_gateway_id?: string;
246  rewrite_query?: boolean;
247  reranking?: boolean;
248  embedding_model?: string;
249  ai_search_model?: string;
250  rewrite_model?: string;
251  reranking_model?: string;
252  /** @deprecated Use index_method instead. */
253  hybrid_search_enabled?: boolean;
254  /** Controls which storage backends are active. */
255  index_method?: { vector?: boolean; keyword?: boolean };
256  /** Fusion method for combining vector and keyword results. */
257  fusion_method?: 'max' | 'rrf';
258  indexing_options?: { keyword_tokenizer?: 'porter' | 'trigram' } | null;
259  retrieval_options?: {
260    keyword_match_mode?: 'and' | 'or';
261    boost_by?: Array<{
262      field: string;
263      direction?: 'asc' | 'desc' | 'exists' | 'not_exists';
264    }>;
265  } | null;
266  chunk?: boolean;
267  chunk_size?: number;
268  chunk_overlap?: number;
269  score_threshold?: number;
270  max_num_results?: number;
271  cache?: boolean;
272  cache_threshold?:
273    | 'super_strict_match'
274    | 'close_enough'
275    | 'flexible_friend'
276    | 'anything_goes';
277  custom_metadata?: Array<{
278    field_name: string;
279    data_type: 'text' | 'number' | 'boolean' | 'datetime';
280  }>;
281  /** Sync interval in seconds. */
282  sync_interval?: 3600 | 7200 | 14400 | 21600 | 43200 | 86400;
283  metadata?: Record<string, unknown>;
284  [key: string]: unknown;
285};
286 
287/** Pagination, search, and ordering parameters for listing instances within a namespace. */
288export type AiSearchListInstancesParams = {
289  page?: number;
290  per_page?: number;
291  /** Search instances by ID. */
292  search?: string;
293  /** Field to sort by. */
294  order_by?: 'created_at';
295  /** Sort direction. */
296  order_by_direction?: 'asc' | 'desc';
297};
298 
299export type AiSearchListResponse = {
300  result: AiSearchInstanceInfo[];
301  result_info?: {
302    count: number;
303    page: number;
304    per_page: number;
305    total_count: number;
306  };
307};
308 
309// ============ AI Search Config Types ============
310 
311export type AiSearchConfig = {
312  /** Instance ID (1-32 chars, pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$) */
313  id: string;
314  /** Instance type. Omit to create with built-in storage. */
315  type?: 'r2' | 'web-crawler' | string;
316  /** Source URL (required for web-crawler type). */
317  source?: string;
318  source_params?: unknown;
319  /** Token ID (UUID format) */
320  token_id?: string;
321  ai_gateway_id?: string;
322  /** Enable query rewriting (default false) */
323  rewrite_query?: boolean;
324  /** Enable reranking (default false) */
325  reranking?: boolean;
326  embedding_model?: string;
327  ai_search_model?: string;
328  rewrite_model?: string;
329  reranking_model?: string;
330  /** @deprecated Use index_method instead. */
331  hybrid_search_enabled?: boolean;
332  /** Controls which storage backends are used during indexing. Defaults to vector-only. */
333  index_method?: { vector?: boolean; keyword?: boolean };
334  /** Fusion method for combining vector and keyword results. "rrf" = reciprocal rank fusion (default), "max" = maximum score. */
335  fusion_method?: 'max' | 'rrf';
336  indexing_options?: { keyword_tokenizer?: 'porter' | 'trigram' } | null;
337  retrieval_options?: {
338    keyword_match_mode?: 'and' | 'or';
339    boost_by?: Array<{
340      field: string;
341      direction?: 'asc' | 'desc' | 'exists' | 'not_exists';
342    }>;
343  } | null;
344  chunk?: boolean;
345  chunk_size?: number;
346  chunk_overlap?: number;
347  /** Minimum similarity score (0-1) for a result to be included. */
348  score_threshold?: number;
349  max_num_results?: number;
350  cache?: boolean;
351  /** Similarity threshold for cache hits. Stricter = fewer cache hits but higher relevance. */
352  cache_threshold?:
353    | 'super_strict_match'
354    | 'close_enough'
355    | 'flexible_friend'
356    | 'anything_goes';
357  custom_metadata?: Array<{
358    field_name: string;
359    data_type: 'text' | 'number' | 'boolean' | 'datetime';
360  }>;
361  namespace?: string;
362  /** Sync interval in seconds. 3600=1h, 7200=2h, 14400=4h, 21600=6h, 43200=12h, 86400=24h. */
363  sync_interval?: 3600 | 7200 | 14400 | 21600 | 43200 | 86400;
364  metadata?: Record<string, unknown>;
365  [key: string]: unknown;
366};
367 
368// ============ AI Search Item Types ============
369 
370export type AiSearchItemInfo = {
371  id: string;
372  key: string;
373  status: 'completed' | 'error' | 'skipped' | 'queued' | 'running' | 'outdated';
374  next_action?: 'INDEX' | 'DELETE' | null;
375  error?: string;
376  checksum?: string;
377  namespace?: string;
378  chunks_count?: number | null;
379  file_size?: number | null;
380  source_id?: string | null;
381  last_seen_at?: string;
382  created_at?: string;
383  metadata?: Record<string, unknown>;
384  [key: string]: unknown;
385};
386 
387export type AiSearchItemContentResult = {
388  body: ReadableStream;
389  contentType: string;
390  filename: string;
391  size: number;
392};
393 
394export type AiSearchUploadItemOptions = {
395  metadata?: Record<string, unknown>;
396};
397 
398export type AiSearchListItemsParams = {
399  page?: number;
400  per_page?: number;
401  /** Search items by key name. */
402  search?: string;
403  /** Sort order for results. */
404  sort_by?: 'status' | 'modified_at';
405  /** Filter items by processing status. */
406  status?:
407    | 'queued'
408    | 'running'
409    | 'completed'
410    | 'error'
411    | 'skipped'
412    | 'outdated';
413  /** Filter items by source (e.g. "builtin" or "web-crawler:https://example.com"). */
414  source?: string;
415  /** JSON-encoded Vectorize filter for metadata filtering. */
416  metadata_filter?: string;
417};
418 
419export type AiSearchListItemsResponse = {
420  result: AiSearchItemInfo[];
421  result_info?: {
422    count: number;
423    page: number;
424    per_page: number;
425    total_count: number;
426  };
427};
428 
429// ============ AI Search Item Logs Types ============
430 
431export type AiSearchItemLogsParams = {
432  /** Maximum number of log entries to return (1-100, default 50). */
433  limit?: number;
434  /** Opaque cursor for pagination. Pass the `cursor` value from a previous response. */
435  cursor?: string;
436};
437 
438export type AiSearchItemLog = {
439  timestamp: string;
440  action: string;
441  message: string;
442  fileKey?: string;
443  chunkCount?: number;
444  processingTimeMs?: number;
445  errorType?: string;
446};
447 
448/** Paginated response for item processing logs (cursor-based). */
449export type AiSearchItemLogsResponse = {
450  result: AiSearchItemLog[];
451  result_info: {
452    count: number;
453    per_page: number;
454    cursor: string | null;
455    truncated: boolean;
456  };
457};
458 
459// ============ AI Search Item Chunks Types ============
460 
461export type AiSearchItemChunksParams = {
462  /** Maximum number of chunks to return (1-100, default 20). */
463  limit?: number;
464  /** Offset into the chunks list (default 0). */
465  offset?: number;
466};
467 
468/** A single indexed chunk belonging to an item, including its text content and byte range. */
469export type AiSearchItemChunk = {
470  id: string;
471  text: string;
472  start_byte: number;
473  end_byte: number;
474  item?: {
475    timestamp?: number;
476    key: string;
477    metadata?: Record<string, unknown>;
478  };
479};
480 
481/** Paginated response for item chunks (offset-based). */
482export type AiSearchItemChunksResponse = {
483  result: AiSearchItemChunk[];
484  result_info: {
485    count: number;
486    total: number;
487    limit: number;
488    offset: number;
489  };
490};
491 
492// ============ AI Search Job Types ============
493 
494export type AiSearchJobInfo = {
495  id: string;
496  source: 'user' | 'schedule';
497  description?: string;
498  last_seen_at?: string;
499  started_at?: string;
500  ended_at?: string;
501  end_reason?: string;
502};
503 
504export type AiSearchJobLog = {
505  id: number;
506  message: string;
507  message_type: number;
508  created_at: number;
509};
510 
511export type AiSearchCreateJobParams = {
512  description?: string;
513};
514 
515export type AiSearchListJobsParams = {
516  page?: number;
517  per_page?: number;
518};
519 
520export type AiSearchListJobsResponse = {
521  result: AiSearchJobInfo[];
522  result_info?: {
523    count: number;
524    page: number;
525    per_page: number;
526    total_count: number;
527  };
528};
529 
530export type AiSearchJobLogsParams = {
531  page?: number;
532  per_page?: number;
533};
534 
535export type AiSearchJobLogsResponse = {
536  result: AiSearchJobLog[];
537  result_info?: {
538    count: number;
539    page: number;
540    per_page: number;
541    total_count: number;
542  };
543};
544 
545// ============ AI Search Sub-Service Classes ============
546 
547/**
548 * Single item service for an AI Search instance.
549 * Provides info, download, sync, logs, and chunks operations on a specific item.
550 */
551export declare abstract class AiSearchItem {
552  /** Get metadata about this item. */
553  info(): Promise<AiSearchItemInfo>;
554 
555  /**
556   * Download the item's content.
557   * @returns Object with body stream, content type, filename, and size.
558   */
559  download(): Promise<AiSearchItemContentResult>;
560 
561  /**
562   * Trigger re-indexing of this item.
563   * @returns The updated item info.
564   */
565  sync(): Promise<AiSearchItemInfo>;
566 
567  /**
568   * Retrieve processing logs for this item (cursor-based pagination).
569   * @param params Optional pagination parameters (limit, cursor).
570   * @returns Paginated log entries for this item.
571   */
572  logs(params?: AiSearchItemLogsParams): Promise<AiSearchItemLogsResponse>;
573 
574  /**
575   * List indexed chunks for this item (offset-based pagination).
576   * @param params Optional pagination parameters (limit, offset).
577   * @returns Paginated chunk entries for this item.
578   */
579  chunks(
580    params?: AiSearchItemChunksParams
581  ): Promise<AiSearchItemChunksResponse>;
582}
583 
584/**
585 * Items collection service for an AI Search instance.
586 * Provides list, upload, and access to individual items.
587 */
588export declare abstract class AiSearchItems {
589  /** List items in this instance. */
590  list(params?: AiSearchListItemsParams): Promise<AiSearchListItemsResponse>;
591 
592  /**
593   * Upload a file as an item. Behaves as an upsert: if an item with the same
594   * filename already exists, it is overwritten and re-indexed.
595   * @param name Filename for the uploaded item.
596   * @param content File content as a ReadableStream, Blob, or string.
597   * @param options Optional metadata to attach to the item.
598   * @returns The created item info.
599   */
600  upload(
601    name: string,
602    content: ReadableStream | Blob | string,
603    options?: AiSearchUploadItemOptions
604  ): Promise<AiSearchItemInfo>;
605 
606  /**
607   * Upload a file and poll until processing completes.
608   * Behaves as an upsert: if an item with the same filename already exists,
609   * it is overwritten and re-indexed.
610   * @param name Filename for the uploaded item.
611   * @param content File content as a ReadableStream, Blob, or string.
612   * @param options Optional metadata and polling configuration.
613   * @returns The item info after processing completes (or timeout).
614   */
615  uploadAndPoll(
616    name: string,
617    content: ReadableStream | Blob | string,
618    options?: AiSearchUploadItemOptions & {
619      /** Polling interval in milliseconds (default 1000). */
620      pollIntervalMs?: number;
621      /** Maximum time to wait in milliseconds (default 30000). */
622      timeoutMs?: number;
623    }
624  ): Promise<AiSearchItemInfo>;
625 
626  /**
627   * Get an item by ID.
628   * @param itemId The item identifier.
629   * @returns Item service for info, download, sync, logs, and chunks operations.
630   */
631  get(itemId: string): AiSearchItem;
632 
633  /**
634   * Delete an item from the instance.
635   * @param itemId The item identifier.
636   */
637  delete(itemId: string): Promise<void>;
638}
639 
640/**
641 * Single job service for an AI Search instance.
642 * Provides info, logs, and cancel operations for a specific job.
643 */
644export declare abstract class AiSearchJob {
645  /** Get metadata about this job. */
646  info(): Promise<AiSearchJobInfo>;
647 
648  /** Get logs for this job. */
649  logs(params?: AiSearchJobLogsParams): Promise<AiSearchJobLogsResponse>;
650 
651  /**
652   * Cancel a running job.
653   * @returns The updated job info.
654   * @throws AiSearchNotFoundError if the job does not exist.
655   */
656  cancel(): Promise<AiSearchJobInfo>;
657}
658 
659/**
660 * Jobs collection service for an AI Search instance.
661 * Provides list, create, and access to individual jobs.
662 */
663export declare abstract class AiSearchJobs {
664  /** List jobs for this instance. */
665  list(params?: AiSearchListJobsParams): Promise<AiSearchListJobsResponse>;
666 
667  /**
668   * Create a new indexing job.
669   * @param params Optional job parameters.
670   * @returns The created job info.
671   */
672  create(params?: AiSearchCreateJobParams): Promise<AiSearchJobInfo>;
673 
674  /**
675   * Get a job by ID.
676   * @param jobId The job identifier.
677   * @returns Job service for info, logs, and cancel operations.
678   */
679  get(jobId: string): AiSearchJob;
680}
681 
682// ============ AI Search Binding Classes ============
683 
684/**
685 * Instance-level AI Search service.
686 *
687 * Used as:
688 * - The return type of `AiSearchNamespace.get(name)` (namespace binding)
689 * - The type of `env.BLOG_SEARCH` (single instance binding via `ai_search`)
690 *
691 * Provides search, chat, update, stats, items, and jobs operations.
692 *
693 * @example
694 * ```ts
695 * // Via namespace binding
696 * const instance = env.AI_SEARCH.get("blog");
697 * const results = await instance.search({
698 *   query: "How does caching work?",
699 * });
700 *
701 * // Via single instance binding
702 * const results = await env.BLOG_SEARCH.search({
703 *   messages: [{ role: "user", content: "How does caching work?" }],
704 * });
705 * ```
706 */
707export declare abstract class AiSearchInstance {
708  /**
709   * Search the AI Search instance for relevant chunks.
710   * @param params Search request with query or messages and optional AI search options.
711   * @returns Search response with matching chunks and search query.
712   */
713  search(params: AiSearchSearchRequest): Promise<AiSearchSearchResponse>;
714 
715  /**
716   * Generate chat completions with AI Search context (streaming).
717   * @param params Chat completions request with stream: true.
718   * @returns ReadableStream of server-sent events.
719   */
720  chatCompletions(
721    params: AiSearchChatCompletionsRequest & { stream: true }
722  ): Promise<ReadableStream>;
723 
724  /**
725   * Generate chat completions with AI Search context.
726   * @param params Chat completions request.
727   * @returns Chat completion response with choices and RAG chunks.
728   */
729  chatCompletions(
730    params: AiSearchChatCompletionsRequest
731  ): Promise<AiSearchChatCompletionsResponse>;
732 
733  /**
734   * Update the instance configuration.
735   * @param config Partial configuration to update.
736   * @returns Updated instance info.
737   */
738  update(config: Partial<AiSearchConfig>): Promise<AiSearchInstanceInfo>;
739 
740  /** Get metadata about this instance. */
741  info(): Promise<AiSearchInstanceInfo>;
742 
743  /**
744   * Get instance statistics (item count, indexing status, etc.).
745   * @returns Statistics with counts per status, last activity time, and engine details.
746   */
747  stats(): Promise<AiSearchStatsResponse>;
748 
749  /** Items collection — list, upload, and manage items in this instance. */
750  get items(): AiSearchItems;
751 
752  /** Jobs collection — list, create, and inspect indexing jobs. */
753  get jobs(): AiSearchJobs;
754}
755 
756/**
757 * Namespace-level AI Search service.
758 *
759 * Used as the type of `env.AI_SEARCH` (namespace binding via `ai_search_namespaces`).
760 * Scoped to a single namespace. Provides dynamic instance access, creation, deletion,
761 * and multi-instance search/chat operations.
762 *
763 * @example
764 * ```ts
765 * // Access an instance within the namespace
766 * const blog = env.AI_SEARCH.get("blog");
767 * const results = await blog.search({ query: "How does caching work?" });
768 *
769 * // List all instances in the namespace
770 * const instances = await env.AI_SEARCH.list();
771 *
772 * // Create a new instance with built-in storage
773 * const tenant = await env.AI_SEARCH.create({ id: "tenant-123" });
774 *
775 * // Upload items into the instance
776 * await tenant.items.upload("doc.pdf", fileContent);
777 *
778 * // Search across multiple instances
779 * const multi = await env.AI_SEARCH.search({
780 *   query: "caching",
781 *   ai_search_options: { instance_ids: ["blog", "docs"] },
782 * });
783 *
784 * // Delete an instance
785 * await env.AI_SEARCH.delete("tenant-123");
786 * ```
787 */
788export declare abstract class AiSearchNamespace {
789  /**
790   * Get an instance by name within the bound namespace.
791   * @param name Instance name.
792   * @returns Instance service for search, chat, update, stats, items, and jobs.
793   */
794  get(name: string): AiSearchInstance;
795 
796  /**
797   * List instances in the bound namespace.
798   * @param params Optional pagination, search, and ordering parameters.
799   * @returns Array of instance metadata with pagination info.
800   */
801  list(params?: AiSearchListInstancesParams): Promise<AiSearchListResponse>;
802 
803  /**
804   * Create a new instance within the bound namespace.
805   * @param config Instance configuration. Only `id` is required — omit `type` and `source` to create with built-in storage.
806   * @returns Instance service for the newly created instance.
807   *
808   * @example
809   * ```ts
810   * // Create with built-in storage (upload items manually)
811   * const instance = await env.AI_SEARCH.create({ id: "my-search" });
812   *
813   * // Create with web crawler source
814   * const instance = await env.AI_SEARCH.create({
815   *   id: "docs-search",
816   *   type: "web-crawler",
817   *   source: "https://developers.cloudflare.com",
818   * });
819   * ```
820   */
821  create(config: AiSearchConfig): Promise<AiSearchInstance>;
822 
823  /**
824   * Delete an instance from the bound namespace.
825   * @param name Instance name to delete.
826   */
827  delete(name: string): Promise<void>;
828 
829  /**
830   * Search across multiple instances within the bound namespace.
831   * Fans out to the specified instance_ids and merges results.
832   * @param params Search request with required `ai_search_options.instance_ids`.
833   * @returns Search response with chunks tagged by instance_id and optional partial-failure errors.
834   */
835  search(
836    params: AiSearchMultiSearchRequest
837  ): Promise<AiSearchMultiSearchResponse>;
838 
839  /**
840   * Generate chat completions across multiple instances within the bound namespace (streaming).
841   * Fans out to the specified instance_ids, merges context, and generates a response.
842   * @param params Chat completions request with stream: true and required `ai_search_options.instance_ids`.
843   * @returns ReadableStream of server-sent events.
844   */
845  chatCompletions(
846    params: AiSearchMultiChatCompletionsRequest & { stream: true }
847  ): Promise<ReadableStream>;
848 
849  /**
850   * Generate chat completions across multiple instances within the bound namespace.
851   * Fans out to the specified instance_ids, merges context, and generates a response.
852   * @param params Chat completions request with required `ai_search_options.instance_ids`.
853   * @returns Chat completion response with choices, chunks tagged by instance_id, and optional partial-failure errors.
854   */
855  chatCompletions(
856    params: AiSearchMultiChatCompletionsRequest
857  ): Promise<AiSearchMultiChatCompletionsResponse>;
858}