Source file qdrant.ml

(** Qdrant Vector Database Client for OCaml

    Pure OCaml client for Qdrant REST API.
    Supports vector search, collection management, and point operations.

    Reference: https://qdrant.tech/documentation/
*)

open Lwt.Syntax

(** {1 Configuration} *)

type config = {
  base_url: string;
  api_key: string option;
  timeout_s: float;
}

(** Default configuration - pure constant, no environment access *)
let default_config = {
  base_url = "http://localhost:6333";
  api_key = None;
  timeout_s = 30.0;
}

(** Create config from environment variables.
    Reads QDRANT_URL and QDRANT_API_KEY from environment.
    Explicit is better than implicit - call this when you want env config.

    @param timeout_s Override default timeout (default: 30.0)
    @return config with values from environment *)
let config_from_env ?timeout_s () = {
  base_url = Sys.getenv_opt "QDRANT_URL" |> Option.value ~default:"http://localhost:6333";
  api_key = Sys.getenv_opt "QDRANT_API_KEY";
  timeout_s = Option.value timeout_s ~default:30.0;
}

(** {1 Types} *)

(** Distance metrics for vector similarity *)
type distance =
  | Cosine
  | Euclid
  | Dot
  | Manhattan

let distance_to_string = function
  | Cosine -> "Cosine"
  | Euclid -> "Euclid"
  | Dot -> "Dot"
  | Manhattan -> "Manhattan"

(** Vector configuration *)
type vector_config = {
  size: int;
  distance: distance;
}

(** Point with vector and payload *)
type point = {
  id: string;
  vector: float array;
  payload: (string * Yojson.Safe.t) list;
}

(** Search result *)
type search_result = {
  id: string;
  score: float;
  payload: Yojson.Safe.t;
  vector: float array option;
}

(** Collection info *)
type collection_info = {
  status: string;
  vectors_count: int;
  points_count: int;
  segments_count: int;
}

(** {1 Errors} *)

(** Error type - pragmatic, not over-engineered *)
type error =
  | ConnectionError of string
  | ApiError of int * string      (** HTTP status code + message *)
  | ParseError of string
  | ValidationError of string     (** Simple string, no sum type overhead *)
  | Timeout
  | NotFound of string

let error_to_string = function
  | ConnectionError msg -> Printf.sprintf "Connection error: %s" msg
  | ApiError (code, msg) -> Printf.sprintf "API error %d: %s" code msg
  | ParseError msg -> Printf.sprintf "Parse error: %s" msg
  | ValidationError msg -> Printf.sprintf "Validation error: %s" msg
  | Timeout -> "Request timeout"
  | NotFound name -> Printf.sprintf "Not found: %s" name

(** {1 Validation} *)

(** Check if string contains path injection characters *)
let has_path_injection s =
  String.contains s '/' || String.contains s '\\' || String.contains s '\x00'

(** Validate collection name is not empty and safe for URL path *)
let validate_collection name =
  if String.length name = 0 then
    Error (ValidationError "Collection name cannot be empty")
  else if has_path_injection name then
    Error (ValidationError (Printf.sprintf "Collection name contains invalid characters: %s" name))
  else
    Ok ()

(** Validate vector is not empty *)
let validate_vector vector =
  if Array.length vector = 0 then
    Error (ValidationError "Vector cannot be empty")
  else
    Ok ()

(** Validate limit is positive *)
let validate_limit limit =
  if limit <= 0 then
    Error (ValidationError (Printf.sprintf "Limit must be positive, got: %d" limit))
  else
    Ok ()

(** Validate vector dimension size *)
let validate_vector_size size =
  if size <= 0 then
    Error (ValidationError (Printf.sprintf "Vector size must be positive, got: %d" size))
  else
    Ok ()

(** Validate ID is safe for URL path *)
let validate_id id =
  if String.length id = 0 then
    Error (ValidationError "ID cannot be empty")
  else if has_path_injection id then
    Error (ValidationError (Printf.sprintf "ID contains invalid characters: %s" id))
  else
    Ok ()

(** Validate chunk_size is positive *)
let validate_chunk_size size =
  if size <= 0 then
    Error (ValidationError (Printf.sprintf "Chunk size must be positive, got: %d" size))
  else
    Ok ()

(** Chain multiple validations *)
let ( let*? ) result f =
  match result with
  | Error e -> Lwt.return_error e
  | Ok () -> f ()

(** {1 Internal HTTP} *)

(** Internal: HTTP request with timeout *)
let make_request ~config ~meth ~path ?(body=`Null) () =
  (* Validate API key if present *)
  match config.api_key with
  | Some key when String.contains key '\r' || String.contains key '\n' ->
    Lwt.return_error (ValidationError "API key cannot contain CR/LF characters")
  | _ ->
  let uri = Uri.of_string (config.base_url ^ path) in
  let headers =
    let base = Cohttp.Header.init () in
    let base = Cohttp.Header.add base "Content-Type" "application/json" in
    match config.api_key with
    | Some key -> Cohttp.Header.add base "api-key" key
    | None -> base
  in
  let body_str = match body with
    | `Null -> ""
    | json -> Yojson.Safe.to_string json
  in

  (* HTTP request task *)
  let http_task () =
    try%lwt
      let* (resp, resp_body) = match meth with
        | `POST ->
          let body = Cohttp_lwt.Body.of_string body_str in
          Cohttp_lwt_unix.Client.post ~headers ~body uri
        | `PUT ->
          let body = Cohttp_lwt.Body.of_string body_str in
          Cohttp_lwt_unix.Client.put ~headers ~body uri
        | `DELETE ->
          Cohttp_lwt_unix.Client.delete ~headers uri
        | `GET ->
          Cohttp_lwt_unix.Client.get ~headers uri
        | `PATCH ->
          let body = Cohttp_lwt.Body.of_string body_str in
          Cohttp_lwt_unix.Client.patch ~headers ~body uri
      in
      let status = Cohttp.Response.status resp in
      let code = Cohttp.Code.code_of_status status in
      let* body_str = Cohttp_lwt.Body.to_string resp_body in

      if Cohttp.Code.is_success code then
        Lwt.return_ok body_str
      else if code = 404 then
        Lwt.return_error (NotFound path)
      else
        Lwt.return_error (ApiError (code, body_str))
    with
    | Unix.Unix_error (err, _, _) ->
      Lwt.return_error (ConnectionError (Unix.error_message err))
    | exn ->
      Lwt.return_error (ConnectionError (Printexc.to_string exn))
  in

  (* Apply timeout using Lwt.pick *)
  Lwt.pick [
    http_task ();
    (let%lwt () = Lwt_unix.sleep config.timeout_s in Lwt.return_error Timeout)
  ]

(** {1 Health & Info} *)

(** Check if Qdrant is healthy.
    Returns Ok true if healthy, Ok false if unhealthy response,
    Error if cannot determine (connection failure, timeout, etc.) *)
let health ?(config=default_config) () =
  let* result = make_request ~config ~meth:`GET ~path:"/healthz" () in
  match result with
  | Ok _ -> Lwt.return_ok true
  | Error (NotFound _) ->
    (* Fallback to root for older versions *)
    let* result = make_request ~config ~meth:`GET ~path:"/" () in
    (match result with
     | Ok _ -> Lwt.return_ok true
     | Error e -> Lwt.return_error e)
  | Error (ApiError (code, _)) when code >= 500 ->
    (* Server error = unhealthy *)
    Lwt.return_ok false
  | Error e -> Lwt.return_error e

(** Get Qdrant version *)
let version ?(config=default_config) () =
  let* result = make_request ~config ~meth:`GET ~path:"/" () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let version = json
        |> Yojson.Safe.Util.member "version"
        |> Yojson.Safe.Util.to_string
      in
      Lwt.return_ok version
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** {1 Collections} *)

(** List all collections *)
let list_collections ?(config=default_config) () =
  let* result = make_request ~config ~meth:`GET ~path:"/collections" () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let collections = json
        |> Yojson.Safe.Util.member "result"
        |> Yojson.Safe.Util.member "collections"
        |> Yojson.Safe.Util.to_list
        |> List.map (fun c ->
          c |> Yojson.Safe.Util.member "name" |> Yojson.Safe.Util.to_string)
      in
      Lwt.return_ok collections
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** Check if collection exists *)
let collection_exists ?(config=default_config) ~name () =
  let*? () = validate_collection name in
  let path = Printf.sprintf "/collections/%s/exists" name in
  let* result = make_request ~config ~meth:`GET ~path () in
  match result with
  | Error (NotFound _) -> Lwt.return_ok false
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let exists = json
        |> Yojson.Safe.Util.member "result"
        |> Yojson.Safe.Util.member "exists"
        |> Yojson.Safe.Util.to_bool
      in
      Lwt.return_ok exists
    with exn ->
      Lwt.return_error (ParseError (Printf.sprintf "Failed to parse exists response: %s" (Printexc.to_string exn)))

(** Get collection info *)
let get_collection ?(config=default_config) ~name () =
  let*? () = validate_collection name in
  let path = Printf.sprintf "/collections/%s" name in
  let* result = make_request ~config ~meth:`GET ~path () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let result = json |> Yojson.Safe.Util.member "result" in
      let status = result
        |> Yojson.Safe.Util.member "status"
        |> Yojson.Safe.Util.to_string
      in
      let vectors_count = result
        |> Yojson.Safe.Util.member "vectors_count"
        |> Yojson.Safe.Util.to_int_option
        |> Option.value ~default:0
      in
      let points_count = result
        |> Yojson.Safe.Util.member "points_count"
        |> Yojson.Safe.Util.to_int_option
        |> Option.value ~default:0
      in
      let segments_count = result
        |> Yojson.Safe.Util.member "segments_count"
        |> Yojson.Safe.Util.to_int_option
        |> Option.value ~default:0
      in
      Lwt.return_ok { status; vectors_count; points_count; segments_count }
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** Create a collection *)
let create_collection ?(config=default_config) ~name ~vector_config () =
  let*? () = validate_collection name in
  let*? () = validate_vector_size vector_config.size in
  let path = Printf.sprintf "/collections/%s" name in
  let body = `Assoc [
    ("vectors", `Assoc [
      ("size", `Int vector_config.size);
      ("distance", `String (distance_to_string vector_config.distance));
    ]);
  ] in
  let* result = make_request ~config ~meth:`PUT ~path ~body () in
  match result with
  | Ok _ -> Lwt.return_ok ()
  | Error e -> Lwt.return_error e

(** Delete a collection *)
let delete_collection ?(config=default_config) ~name () =
  let*? () = validate_collection name in
  let path = Printf.sprintf "/collections/%s" name in
  let* result = make_request ~config ~meth:`DELETE ~path () in
  match result with
  | Ok _ -> Lwt.return_ok ()
  | Error (NotFound _) -> Lwt.return_ok ()  (* Already deleted *)
  | Error e -> Lwt.return_error e

(** {1 Points} *)

(** Convert ID to JSON (integer if numeric, otherwise UUID string).
    Uses Intlit for large integers to avoid overflow. *)
let id_to_json id =
  (* Check if it's a valid numeric string (digits only, no leading zeros except "0") *)
  let is_numeric s =
    String.length s > 0 &&
    (s = "0" || (s.[0] <> '0' && String.for_all (fun c -> c >= '0' && c <= '9') s))
  in
  if is_numeric id then
    (* Use Intlit for arbitrary precision integers *)
    `Intlit id
  else
    `String id  (* UUID or other string ID *)

(** Parse ID from JSON response. Handles string, int, and intlit. *)
let id_of_json = function
  | `String s -> s
  | `Int i -> string_of_int i
  | `Intlit s -> s
  | json -> failwith (Printf.sprintf "Invalid ID type: %s" (Yojson.Safe.to_string json))

(** Upsert points into a collection *)
let upsert ?(config=default_config) ~collection ~(points:point list) () =
  let*? () = validate_collection collection in
  let path = Printf.sprintf "/collections/%s/points?wait=true" collection in
  let points_json = List.map (fun (p:point) ->
    `Assoc [
      ("id", id_to_json p.id);
      ("vector", `List (Array.to_list (Array.map (fun f -> `Float f) p.vector)));
      ("payload", `Assoc p.payload);
    ]
  ) points in
  let body = `Assoc [("points", `List points_json)] in
  let* result = make_request ~config ~meth:`PUT ~path ~body () in
  match result with
  | Ok _ -> Lwt.return_ok (List.length points)
  | Error e -> Lwt.return_error e

(** Delete points by IDs *)
let delete_points ?(config=default_config) ~collection ~ids () =
  let*? () = validate_collection collection in
  let path = Printf.sprintf "/collections/%s/points/delete?wait=true" collection in
  let body = `Assoc [
    ("points", `List (List.map id_to_json ids));
  ] in
  let* result = make_request ~config ~meth:`POST ~path ~body () in
  match result with
  | Ok _ -> Lwt.return_ok ()
  | Error e -> Lwt.return_error e

(** Get point by ID *)
let get_point ?(config=default_config) ~collection ~id () =
  let*? () = validate_collection collection in
  let*? () = validate_id id in
  let path = Printf.sprintf "/collections/%s/points/%s" collection id in
  let* result = make_request ~config ~meth:`GET ~path () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let result = json |> Yojson.Safe.Util.member "result" in
      let id = result |> Yojson.Safe.Util.member "id" |> id_of_json in
      let vector = result
        |> Yojson.Safe.Util.member "vector"
        |> Yojson.Safe.Util.to_list
        |> List.map Yojson.Safe.Util.to_float
        |> Array.of_list
      in
      let payload = result |> Yojson.Safe.Util.member "payload" in
      Lwt.return_ok { id; score = 1.0; payload; vector = Some vector }
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** {1 Search} *)

(** Search for similar vectors *)
let search ?(config=default_config) ~collection ~vector ~limit
    ?(score_threshold=0.0) ?(with_vector=false) () =
  let*? () = validate_collection collection in
  let*? () = validate_vector vector in
  let*? () = validate_limit limit in
  let path = Printf.sprintf "/collections/%s/points/search" collection in
  let body = `Assoc [
    ("vector", `List (Array.to_list (Array.map (fun f -> `Float f) vector)));
    ("limit", `Int limit);
    ("score_threshold", `Float score_threshold);
    ("with_payload", `Bool true);
    ("with_vector", `Bool with_vector);
  ] in
  let* result = make_request ~config ~meth:`POST ~path ~body () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let results = json
        |> Yojson.Safe.Util.member "result"
        |> Yojson.Safe.Util.to_list
        |> List.map (fun item ->
          let id = item |> Yojson.Safe.Util.member "id" |> id_of_json in
          let score = item |> Yojson.Safe.Util.member "score" |> Yojson.Safe.Util.to_float in
          let payload = item |> Yojson.Safe.Util.member "payload" in
          let vector = if with_vector then
            Some (item
              |> Yojson.Safe.Util.member "vector"
              |> Yojson.Safe.Util.to_list
              |> List.map Yojson.Safe.Util.to_float
              |> Array.of_list)
          else None
          in
          { id; score; payload; vector }
        )
      in
      Lwt.return_ok results
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** Search with filter *)
let search_with_filter ?(config=default_config) ~collection ~vector ~limit
    ~filter ?(score_threshold=0.0) ?(with_vector=false) () =
  let*? () = validate_collection collection in
  let*? () = validate_vector vector in
  let*? () = validate_limit limit in
  let path = Printf.sprintf "/collections/%s/points/search" collection in
  let body = `Assoc [
    ("vector", `List (Array.to_list (Array.map (fun f -> `Float f) vector)));
    ("limit", `Int limit);
    ("score_threshold", `Float score_threshold);
    ("with_payload", `Bool true);
    ("with_vector", `Bool with_vector);
    ("filter", filter);
  ] in
  let* result = make_request ~config ~meth:`POST ~path ~body () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let results = json
        |> Yojson.Safe.Util.member "result"
        |> Yojson.Safe.Util.to_list
        |> List.map (fun item ->
          let id = item |> Yojson.Safe.Util.member "id" |> id_of_json in
          let score = item |> Yojson.Safe.Util.member "score" |> Yojson.Safe.Util.to_float in
          let payload = item |> Yojson.Safe.Util.member "payload" in
          let vector = if with_vector then
            Some (item
              |> Yojson.Safe.Util.member "vector"
              |> Yojson.Safe.Util.to_list
              |> List.map Yojson.Safe.Util.to_float
              |> Array.of_list)
          else None
          in
          { id; score; payload; vector }
        )
      in
      Lwt.return_ok results
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** {1 Scroll} *)

(** Scroll through all points *)
let scroll ?(config=default_config) ~collection ?(limit=10) ?offset () =
  let*? () = validate_collection collection in
  let path = Printf.sprintf "/collections/%s/points/scroll" collection in
  let body = `Assoc (
    [("limit", `Int limit); ("with_payload", `Bool true); ("with_vector", `Bool false)]
    @ (match offset with Some o -> [("offset", `String o)] | None -> [])
  ) in
  let* result = make_request ~config ~meth:`POST ~path ~body () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let result_obj = json |> Yojson.Safe.Util.member "result" in
      let points = result_obj
        |> Yojson.Safe.Util.member "points"
        |> Yojson.Safe.Util.to_list
        |> List.map (fun item ->
          let id = item |> Yojson.Safe.Util.member "id" |> id_of_json in
          let payload = item |> Yojson.Safe.Util.member "payload" in
          { id; score = 0.0; payload; vector = None }
        )
      in
      let next_offset = result_obj
        |> Yojson.Safe.Util.member "next_page_offset"
        |> (function
          | `String s -> Some s
          | `Int i -> Some (string_of_int i)
          | `Intlit s -> Some s
          | `Null -> None
          | _ -> None)
      in
      Lwt.return_ok (points, next_offset)
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** Count points in collection *)
let count ?(config=default_config) ~collection () =
  let*? () = validate_collection collection in
  let path = Printf.sprintf "/collections/%s/points/count" collection in
  let body = `Assoc [("exact", `Bool true)] in
  let* result = make_request ~config ~meth:`POST ~path ~body () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let count = json
        |> Yojson.Safe.Util.member "result"
        |> Yojson.Safe.Util.member "count"
        |> Yojson.Safe.Util.to_int
      in
      Lwt.return_ok count
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))

(** {1 Typed Filter API}

    Type-safe, declarative filter construction using sum types.
    Follows functional programming principles: explicit, declarative, exhaustive.

    Example:
    {[
      let filter = Filter.(
        Must [
          MatchKeyword ("category", "tech");
          Range ("price", { gt = None; gte = Some 10.0; lt = None; lte = Some 100.0 });
        ]
      ) in
      search_with_filter ~collection:"items" ~vector ~limit:10
        ~filter:(Filter.to_json filter) ()
    ]}
*)

module Filter = struct
  (** {2 Sum Types} *)

  (** Primitive value types for matching *)
  type value =
    | String of string
    | Int of int
    | Float of float
    | Bool of bool

  (** Range bounds - at least one must be Some *)
  type 'a bounds = {
    gt: 'a option;
    gte: 'a option;
    lt: 'a option;
    lte: 'a option;
  }

  (** Geo point *)
  type geo_point = {
    lat: float;
    lon: float;
  }

  (** Filter condition - each case is explicit and typed *)
  type condition =
    | MatchKeyword of string * string       (** key, value *)
    | MatchInt of string * int              (** key, value *)
    | MatchBool of string * bool            (** key, value *)
    | MatchAny of string * string list      (** key, values *)
    | MatchText of string * string          (** key, text (full-text) *)
    | Range of string * float bounds        (** key, bounds *)
    | RangeInt of string * int bounds       (** key, bounds *)
    | GeoRadius of string * geo_point * float  (** key, center, radius_m *)
    | IsNull of string                      (** key *)
    | IsEmpty of string                     (** key *)
    | HasValue of string                    (** key (NOT null) *)
    | NotEmpty of string                    (** key (NOT empty) *)
    | Nested of t                           (** nested filter *)

  (** Filter combinator - how to combine conditions *)
  and t =
    | Must of condition list                (** AND: all must match *)
    | Should of condition list              (** OR: any must match *)
    | MustNot of condition list             (** NOT: none must match *)
    | And of t list                         (** Combine multiple filters with AND *)

  (** {2 Smart Constructors} *)

  (** Create bounds - validates at least one is present *)
  let bounds ?gt ?gte ?lt ?lte () : 'a bounds =
    match gt, gte, lt, lte with
    | None, None, None, None ->
      invalid_arg "Filter.bounds: at least one bound must be specified"
    | _ -> { gt; gte; lt; lte }

  (** Empty bounds for building incrementally *)
  let empty_bounds = { gt = None; gte = None; lt = None; lte = None }

  (** {2 Fluent Helper Functions}

      Go/Rust-inspired builder pattern for ergonomic filter construction.
      These are convenience wrappers around the sum types.

      Inspiration:
      - Go: github.com/qdrant/go-client (NewFilter, Must, MatchKeyword)
      - Rust: qdrant-client (Filter::must, Condition::matches)
  *)

  (** Create a condition matching a string keyword *)
  let match_keyword key value = MatchKeyword (key, value)

  (** Create a condition matching an integer *)
  let match_int key value = MatchInt (key, value)

  (** Create a condition matching a boolean *)
  let match_bool key value = MatchBool (key, value)

  (** Create a condition matching any of the given values *)
  let match_any key values = MatchAny (key, values)

  (** Create a full-text search condition *)
  let full_text key text = MatchText (key, text)

  (** Create a range condition for floats *)
  let range key ?gt ?gte ?lt ?lte () =
    Range (key, bounds ?gt ?gte ?lt ?lte ())

  (** Create a range condition for integers *)
  let range_int key ?gt ?gte ?lt ?lte () =
    RangeInt (key, bounds ?gt ?gte ?lt ?lte ())

  (** Create a geo radius condition *)
  let geo_radius key ~lat ~lon ~radius_m =
    GeoRadius (key, { lat; lon }, radius_m)

  (** Check if field is null *)
  let is_null key = IsNull key

  (** Check if field is not null (has value) *)
  let is_not_null key = HasValue key

  (** Check if field is empty *)
  let is_empty key = IsEmpty key

  (** Check if field is not empty *)
  let is_not_empty key = NotEmpty key

  (** Create a nested filter condition *)
  let nested filter = Nested filter

  (** Combine conditions with AND (all must match) *)
  let must conditions = Must conditions

  (** Combine conditions with OR (any must match) *)
  let should conditions = Should conditions

  (** Negate conditions (none must match) *)
  let must_not conditions = MustNot conditions

  (** Combine multiple filters with AND *)
  let combine filters = And filters

  (** {2 JSON Conversion} *)

  let value_to_json = function
    | String s -> `String s
    | Int i -> `Int i
    | Float f -> `Float f
    | Bool b -> `Bool b

  let bounds_to_json to_json b =
    let pairs = List.filter_map Fun.id [
      Option.map (fun v -> ("gt", to_json v)) b.gt;
      Option.map (fun v -> ("gte", to_json v)) b.gte;
      Option.map (fun v -> ("lt", to_json v)) b.lt;
      Option.map (fun v -> ("lte", to_json v)) b.lte;
    ] in
    `Assoc pairs

  (** Convert condition to JSON - pure, total function *)
  let rec condition_to_json = function
    | MatchKeyword (key, value) ->
      `Assoc [("key", `String key); ("match", `Assoc [("value", `String value)])]
    | MatchInt (key, value) ->
      `Assoc [("key", `String key); ("match", `Assoc [("value", `Int value)])]
    | MatchBool (key, value) ->
      `Assoc [("key", `String key); ("match", `Assoc [("value", `Bool value)])]
    | MatchAny (key, values) ->
      `Assoc [("key", `String key); ("match", `Assoc [("any", `List (List.map (fun v -> `String v) values))])]
    | MatchText (key, text) ->
      `Assoc [("key", `String key); ("match", `Assoc [("text", `String text)])]
    | Range (key, b) ->
      `Assoc [("key", `String key); ("range", bounds_to_json (fun f -> `Float f) b)]
    | RangeInt (key, b) ->
      `Assoc [("key", `String key); ("range", bounds_to_json (fun i -> `Int i) b)]
    | GeoRadius (key, center, radius) ->
      `Assoc [
        ("key", `String key);
        ("geo_radius", `Assoc [
          ("center", `Assoc [("lat", `Float center.lat); ("lon", `Float center.lon)]);
          ("radius", `Float radius);
        ]);
      ]
    | IsNull key ->
      `Assoc [("is_null", `Assoc [("key", `String key)])]
    | IsEmpty key ->
      `Assoc [("is_empty", `Assoc [("key", `String key)])]
    | HasValue key ->
      (* Desugars to must_not [is_null] *)
      `Assoc [("must_not", `List [`Assoc [("is_null", `Assoc [("key", `String key)])]])]
    | NotEmpty key ->
      (* Desugars to must_not [is_empty] *)
      `Assoc [("must_not", `List [`Assoc [("is_empty", `Assoc [("key", `String key)])]])]
    | Nested f ->
      to_json f

  (** Convert filter to JSON - the single point of serialization *)
  and to_json = function
    | Must conditions ->
      `Assoc [("must", `List (List.map condition_to_json conditions))]
    | Should conditions ->
      `Assoc [("should", `List (List.map condition_to_json conditions))]
    | MustNot conditions ->
      `Assoc [("must_not", `List (List.map condition_to_json conditions))]
    | And filters ->
      let pairs = List.concat_map (fun f ->
        match to_json f with
        | `Assoc pairs -> pairs
        | _ -> []
      ) filters in
      `Assoc pairs

end

(** {1 Batch Operations}

    Python-inspired batch operations with chunking.
*)

(** Batch upsert with automatic chunking *)
let batch_upsert ?(config=default_config) ~collection ~points ?(chunk_size=100) () =
  let*? () = validate_collection collection in
  let*? () = validate_chunk_size chunk_size in
  let chunks =
    let rec split acc = function
      | [] -> List.rev acc
      | lst ->
        let chunk, rest =
          let rec take n acc = function
            | [] -> (List.rev acc, [])
            | _ when n = 0 -> (List.rev acc, lst)
            | x :: xs -> take (n - 1) (x :: acc) xs
          in
          take chunk_size [] lst
        in
        split (chunk :: acc) rest
    in
    split [] points
  in

  let rec process_chunks total = function
    | [] -> Lwt.return_ok total
    | chunk :: rest ->
      let* result = upsert ~config ~collection ~points:chunk () in
      match result with
      | Error e -> Lwt.return_error e
      | Ok n -> process_chunks (total + n) rest
  in
  process_chunks 0 chunks

(** {1 Recommend API} *)

(** Recommend similar points based on positive/negative examples *)
let recommend ?(config=default_config) ~collection ~positive ?(negative=[]) ~limit () =
  let*? () = validate_collection collection in
  let*? () = validate_limit limit in
  let path = Printf.sprintf "/collections/%s/points/recommend" collection in
  let body = `Assoc [
    ("positive", `List (List.map id_to_json positive));
    ("negative", `List (List.map id_to_json negative));
    ("limit", `Int limit);
    ("with_payload", `Bool true);
  ] in
  let* result = make_request ~config ~meth:`POST ~path ~body () in
  match result with
  | Error e -> Lwt.return_error e
  | Ok body ->
    try
      let json = Yojson.Safe.from_string body in
      let results = json
        |> Yojson.Safe.Util.member "result"
        |> Yojson.Safe.Util.to_list
        |> List.map (fun item ->
          let id = item |> Yojson.Safe.Util.member "id" |> id_of_json in
          let score = item |> Yojson.Safe.Util.member "score" |> Yojson.Safe.Util.to_float in
          let payload = item |> Yojson.Safe.Util.member "payload" in
          { id; score; payload; vector = None }
        )
      in
      Lwt.return_ok results
    with exn ->
      Lwt.return_error (ParseError (Printexc.to_string exn))