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}