1import type * as runtime from "@cloudflare/workers-types";
2import * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { RuntimeContext } from "../../RuntimeContext.ts";
5import type { QuerySearchClient, SearchError } from "./QuerySearch.ts";
6import type { SearchNamespace } from "./SearchNamespace.ts";
7
8/**
9 * Bind a {@link SearchNamespace} to a Worker and obtain the Effect-native
10 * namespace client whose `.get(name)` selects an instance at runtime. The
11 * `ai_search_namespace` binding resolves to a runtime `SearchNamespace`
12 * whose `.get(name)` selects an instance within the namespace at runtime.
13 *
14 * `QuerySearchNamespace` is a single identifier that is simultaneously the binding's
15 * Context tag, its type, and the callable —
16 * `yield* Cloudflare.AI.QuerySearchNamespace(namespace)`.
17 *
18 * Provide {@link QuerySearchNamespaceBinding} in the Worker's runtime layer.
19 *
20 *
21 * ### Querying a namespace
22 * **Example:** Select an instance at runtime
23 * ```typescript
24 * const ns = yield* Cloudflare.AI.QuerySearchNamespace(namespace);
25 *
26 * return {
27 * fetch: Effect.gen(function* () {
28 * const answer = yield* ns.get("docs-search").chatCompletions({
29 * messages: [{ role: "user", content: query }],
30 * });
31 * return yield* HttpServerResponse.json(answer);
32 * }),
33 * };
34 * ```
35 *
36 * @binding
37 * @category AI
38 */
39export interface QuerySearchNamespace extends Binding.Service<
40 QuerySearchNamespace,
41 "Cloudflare.AI.SearchNamespace",
42 (namespace: SearchNamespace) => Effect.Effect<QuerySearchNamespaceClient>
43> {}
44
45export const QuerySearchNamespace = Binding.Service<QuerySearchNamespace>(
46 "Cloudflare.AI.SearchNamespace",
47);
48
49/**
50 * Effect-native client for an `ai_search_namespace` binding, wrapping the
51 * runtime `SearchNamespace`. `.get(name)` selects an instance within the
52 * bound namespace and returns its {@link QuerySearchClient}; `list` / `search`
53 * operate across the namespace.
54 */
55export interface QuerySearchNamespaceClient {
56 /**
57 * Effect resolving to the raw underlying Cloudflare `SearchNamespace`
58 * binding. Use this for operations not surfaced below (`create`, `delete`,
59 * multi-instance `chatCompletions`).
60 */
61 raw: Effect.Effect<runtime.AiSearchNamespace, never, RuntimeContext>;
62 /**
63 * Select an instance within the bound namespace by name.
64 */
65 get(instanceName: string): QuerySearchClient;
66 /**
67 * List the instances within the bound namespace.
68 */
69 list(
70 params?: runtime.AiSearchListInstancesParams,
71 ): Effect.Effect<runtime.AiSearchListResponse, SearchError, RuntimeContext>;
72 /**
73 * Search across multiple instances in the bound namespace (requires
74 * `ai_search_options.instance_ids`).
75 */
76 search(
77 params: runtime.AiSearchMultiSearchRequest,
78 ): Effect.Effect<
79 runtime.AiSearchMultiSearchResponse,
80 SearchError,
81 RuntimeContext
82 >;
83}