Skip to main content

lvv_macros/
lib.rs

1#![warn(missing_docs)]
2
3//! Derive macros for [`lvv`](https://docs.rs/lvv), turning Rust structs into
4//! vector points.
5//!
6//! - [`VectorDatabaseItem`] makes a record type produce one point: the text to
7//!   embed, a category, and the payload stored next to the vector.
8//! - [`VectorDatabase`] makes a container struct produce the points of every
9//!   item it holds.
10//!
11//! Both implement traits from
12//! [`lvv::points`](https://docs.rs/lvv/latest/lvv/points/index.html).
13//! The generated code refers to `::lvv`, so the crate using the derives must
14//! depend on `lvv` under that name. Enable lvv's `derive` feature instead of
15//! depending on this crate directly; it re-exports both macros next to the
16//! traits they implement:
17//!
18//! ```toml
19//! [dependencies]
20//! lvv = { version = "0.5", features = ["derive"] }
21//! serde = { version = "1", features = ["derive"] }
22//! ```
23//!
24//! # Example
25//!
26//! ```rust,ignore
27//! use lvv::points::{VectorDatabase, VectorDatabaseItem};
28//! use serde::{Deserialize, Serialize};
29//!
30//! #[derive(Serialize, Deserialize, VectorDatabaseItem)]
31//! struct Project {
32//!     #[lvv(description)]
33//!     name: String,
34//!     #[lvv(description)]
35//!     summary: String,
36//!     #[lvv(rename = "stack")]
37//!     technologies: Vec<String>,
38//!     #[lvv(skip)]
39//!     private_notes: String,
40//! }
41//!
42//! #[derive(VectorDatabase)]
43//! struct Portfolio {
44//!     projects: Vec<Project>,
45//!     featured: Option<Project>,
46//!     #[lvv(skip)]
47//!     owner: String,
48//! }
49//!
50//! # fn index(portfolio: &Portfolio) -> Result<(), lvv::points::PointError> {
51//! for draft in portfolio.point_drafts()? {
52//!     // Embed `draft.description`, store `draft.payload` next to the vector.
53//!     println!("{}: {}", draft.category, draft.description);
54//! }
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! For a complete lvv pipeline built on these derives, from reading files to
60//! writing Qdrant collections, see lvv's
61//! [`examples/derive.rs`](https://github.com/egonik-unlp/lvv/blob/main/examples/derive.rs).
62
63use proc_macro::TokenStream;
64use syn::{parse_macro_input, DeriveInput};
65mod attributes;
66mod types;
67mod vector_database;
68mod vector_database_item;
69
70/// Derives `VectorDatabase` for a struct whose fields hold
71/// [`VectorDatabaseItem`]s.
72///
73/// The generated `point_drafts` walks the fields in declaration order and
74/// collects one `VectorPointDraft` per item. Each field must have one of these
75/// shapes, where `T` implements `VectorDatabaseItem`:
76///
77/// | Field type                                    | Points                              |
78/// |-----------------------------------------------|-------------------------------------|
79/// | `T`                                           | one                                 |
80/// | `Vec<T>`                                      | one per element                     |
81/// | `BTreeMap<K, T>`, `HashMap<K, T>`             | one per value                       |
82/// | `Option<T>`                                   | one, or none for `None`             |
83/// | `Option<Vec<T>>`                              | one per element, or none for `None` |
84/// | `Option<BTreeMap<K, T>>`, `Option<HashMap<K, T>>` | one per value, or none for `None` |
85///
86/// Map keys are not used. `BTreeMap` values come in key order, `HashMap`
87/// values in arbitrary order.
88///
89/// Shapes are recognized by the type's last path segment, so
90/// `std::vec::Vec<T>` works but a type alias for `Vec<T>` is treated as a
91/// single item. Any other type is treated as a single item too and must
92/// implement `VectorDatabaseItem` (`Box<T>` works); skip fields that aren't
93/// items.
94///
95/// The container itself does not need to implement `Serialize` or
96/// `Deserialize`.
97///
98/// # Field attributes
99///
100/// - `#[lvv(skip)]`: ignore the field. It is the only command accepted here;
101///   any other `#[lvv(...)]` command is a compile error.
102///
103/// # Example
104///
105/// ```rust,ignore
106/// use lvv::points::VectorDatabase;
107///
108/// #[derive(VectorDatabase)]
109/// struct Portfolio {
110///     owner: Contact,                        // one point
111///     positions: Vec<Position>,              // one per position
112///     current: Option<Position>,             // zero or one
113///     publications: Option<Vec<Publication>>,
114///     projects: BTreeMap<String, Project>,   // one per value
115///     #[lvv(skip)]
116///     updated_at: String,                    // not an item
117/// }
118///
119/// let drafts = portfolio.point_drafts()?;
120/// ```
121#[proc_macro_derive(VectorDatabase, attributes(lvv))]
122pub fn vector_database(input: TokenStream) -> TokenStream {
123    let input = parse_macro_input!(input as DeriveInput);
124
125    match vector_database::expand(input) {
126        Ok(tokens) => tokens.into(),
127        Err(error) => error.to_compile_error().into(),
128    }
129}
130
131/// Derives `VectorDatabaseItem` for a struct, so each value becomes one
132/// vector point.
133///
134/// The generated implementation produces:
135///
136/// - **category**: the struct's name, such as `"Position"`.
137/// - **description**: the text to embed. It joins the fields marked
138///   `#[lvv(description)]` with newlines, in declaration order. Fields that
139///   render to an empty string, such as a `None`, are left out.
140/// - **payload**: the value serialized through its own `Serialize` impl,
141///   without `#[lvv(skip)]` fields, with `#[lvv(rename)]` applied, and with a
142///   `"category"` key added.
143///
144/// The struct must implement `serde::Serialize` and `serde::Deserialize`.
145/// Named, tuple and generic structs are supported; the bounds a generic struct
146/// needs are added to the impl.
147///
148/// # Field attributes
149///
150/// | Attribute                | Effect |
151/// |--------------------------|--------|
152/// | `#[lvv(description)]`    | Adds the field to the description. Its type must implement `IntoDescriptionValue`. |
153/// | `#[lvv(skip)]`           | Leaves the field out of the payload and the description. Wins over `description`. |
154/// | `#[lvv(rename = "key")]` | Stores the field under `key` in the payload. If given more than once, the last one wins. |
155///
156/// Commands can share one attribute: `#[lvv(description, rename = "role")]`.
157///
158/// `IntoDescriptionValue` is implemented for `String`, integer and float
159/// primitives, `Option<T>` and `Vec<T>`. Implement it for your own types to use
160/// them as description fields.
161///
162/// # Payload keys
163///
164/// `skip` and `rename` act on the key serde writes: the field's
165/// `#[serde(rename = "...")]`, or its name under the container's
166/// `#[serde(rename_all = "...")]`. Tuple struct fields use their index (`"0"`,
167/// `"1"`, ...) as the key. Fields marked `#[serde(flatten)]` are not tracked,
168/// so `skip` and `rename` have no effect on them.
169///
170/// # Compile errors
171///
172/// - The input is an enum or union.
173/// - No field is marked `#[lvv(description)]`.
174/// - A field would be stored under the reserved payload key `category`. Rename
175///   or skip it.
176/// - An `#[lvv(...)]` command other than `description`, `skip` or `rename`.
177///
178/// # Example
179///
180/// ```rust,ignore
181/// use lvv::points::VectorDatabaseItem;
182/// use serde::{Deserialize, Serialize};
183///
184/// #[derive(Serialize, Deserialize, VectorDatabaseItem)]
185/// #[serde(rename_all = "camelCase")]
186/// struct Position {
187///     // Embedded, and stored under `role` instead of `jobTitle`.
188///     #[lvv(description, rename = "role")]
189///     job_title: String,
190///     // Embedded when present.
191///     #[lvv(description)]
192///     organization: Option<String>,
193///     // Stored as `startedOn`, following serde.
194///     started_on: String,
195///     // Neither embedded nor stored.
196///     #[lvv(skip)]
197///     internal_id: u64,
198/// }
199///
200/// // Position { job_title: "Researcher", organization: Some("UNLP"), .. } becomes
201/// //   category:    "Position"
202/// //   description: "Researcher\nUNLP"
203/// //   payload:     {"role": "Researcher", "organization": "UNLP",
204/// //                 "startedOn": "2020-03-01", "category": "Position"}
205/// ```
206#[proc_macro_derive(VectorDatabaseItem, attributes(lvv))]
207pub fn vector_database_item(input: TokenStream) -> TokenStream {
208    let input = parse_macro_input!(input as DeriveInput);
209
210    match vector_database_item::expand(input) {
211        Ok(tokens) => tokens.into(),
212        Err(error) => error.to_compile_error().into(),
213    }
214}