anil.recoil.org
OCaml bindings to the Typesense embeddings search API
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Authenticated Typesense client with session persistence and profile support.
7
8 This module provides a high-level client that wraps the generated
9 {!Typesense} module with authentication support. Sessions are stored in
10 profile-specific directories.
11
12 {2 Usage}
13
14 {[
15 let t = Client.login ~sw ~env
16 ~server_url:"http://localhost:8108"
17 ~api_key:"xyz123"
18 () in
19 let collections = Typesense.Collections.list_collections (Client.client t) ()
20 ]}
21
22 {2 Resuming Sessions}
23
24 {[
25 match Session.load fs () with
26 | Some session ->
27 let t = Client.resume ~sw ~env ~session () in
28 ...
29 | None ->
30 Fmt.epr "Not logged in@."
31 ]} *)
32
33type t
34(** Authenticated client state. *)
35
36(** {1 Authentication} *)
37
38val login :
39 sw:Eio.Switch.t ->
40 env:< clock : _ Eio.Time.clock
41 ; net : _ Eio.Net.t
42 ; fs : Eio.Fs.dir_ty Eio.Path.t
43 ; .. > ->
44 ?requests_config:Requests.Cmd.config ->
45 ?profile:string ->
46 server_url:string ->
47 api_key:string ->
48 unit ->
49 t
50(** [login ~sw ~env ?requests_config ?profile ~server_url ~api_key ()]
51 authenticates using an API key. The API key is sent in the
52 [X-TYPESENSE-API-KEY] header for all requests.
53
54 @param requests_config Optional Requests.Cmd.config for HTTP settings
55 @param profile Profile name (default: "default") *)
56
57val resume :
58 sw:Eio.Switch.t ->
59 env:< clock : _ Eio.Time.clock
60 ; net : _ Eio.Net.t
61 ; fs : Eio.Fs.dir_ty Eio.Path.t
62 ; .. > ->
63 ?requests_config:Requests.Cmd.config ->
64 ?profile:string ->
65 session:Session.t ->
66 unit ->
67 t
68(** [resume ~sw ~env ?requests_config ?profile ~session ()] resumes from a saved session.
69
70 @param requests_config Optional Requests.Cmd.config for HTTP settings *)
71
72val logout : t -> unit
73(** [logout t] clears the session from disk. *)
74
75(** {1 Client Access} *)
76
77val client : t -> Typesense.t
78(** [client t] returns the underlying Typesense client for API calls. *)
79
80val session : t -> Session.t
81(** [session t] returns the current session. *)
82
83val profile : t -> string option
84(** [profile t] returns the current profile name, if set. *)
85
86val fs : t -> Eio.Fs.dir_ty Eio.Path.t
87(** [fs t] returns the filesystem capability. *)
88
89(** {1 JSONL Import/Export}
90
91 These functions provide bulk document operations using JSONL format,
92 which is more efficient than individual API calls for large batches. *)
93
94type import_action = Create | Upsert | Update | Emplace
95(** The action to perform for each imported document. *)
96
97type import_result = {
98 success : bool;
99 error : string option;
100 document : string option;
101}
102(** Result of importing a single document. *)
103
104val import :
105 t ->
106 collection:string ->
107 ?action:import_action ->
108 ?batch_size:int ->
109 ?return_doc:bool ->
110 ?return_id:bool ->
111 Jsont.json list ->
112 import_result list
113(** [import t ~collection documents] imports documents using JSONL format.
114
115 @param action Import action (default: Upsert)
116 @param batch_size Documents per batch (default: 40)
117 @param return_doc Include document in result (default: false)
118 @param return_id Include ID in result (default: false) *)
119
120type export_params = {
121 filter_by : string option;
122 include_fields : string list option;
123 exclude_fields : string list option;
124}
125(** Parameters for document export. *)
126
127val export_params :
128 ?filter_by:string ->
129 ?include_fields:string list ->
130 ?exclude_fields:string list ->
131 unit ->
132 export_params
133(** Create export parameters. *)
134
135val export :
136 t ->
137 collection:string ->
138 ?params:export_params ->
139 unit ->
140 Jsont.json list
141(** [export t ~collection ?params ()] exports documents as JSONL. *)