cognis-macros 0.3.1

Procedural macros for Cognis: #[tool] attribute for tool definitions and #[derive(GraphState)] for graph state with per-field reducers.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Proc macros for the Cognis framework.
//!
//! # Macros
//!
//! - [`tool`] — `#[cognis::tool]` attribute that generates a
//!   `cognis_core::tools::BaseTool` implementation from an `async fn` (or
//!   from an `impl` block containing one). Uses [`schemars`] under the hood
//!   for parameter schema generation.
//! - [`GraphState`] — derive macro for graph state schemas with per-field
//!   reducers (see attributes `#[reducer(append|last_value|add|merge)]`).
//!
//! # JSON Schema generation
//!
//! For `#[derive(JsonSchema)]` on your own structs/enums, use the re-export
//! at `cognis_core::JsonSchema` (which is `schemars::JsonSchema`). The legacy
//! hand-rolled `JsonSchema` / `ToolSchema` derives in this crate were removed
//! in favor of the upstream `schemars` crate, which supports recursive types,
//! `$ref`/`definitions`, doc-comment → `description`, and richer attribute
//! syntax.
//!
//! ```ignore
//! use cognis_core::JsonSchema;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(JsonSchema, Serialize, Deserialize)]
//! struct SearchFilter {
//!     /// Minimum relevance score
//!     min_score: f64,
//!     /// Categories to include
//!     categories: Vec<String>,
//! }
//!
//! let schema = serde_json::to_value(schemars::schema_for!(SearchFilter)).unwrap();
//! ```

mod graph_state;
mod graph_state_v2;
mod schema_attr;
mod tool_attr;
mod tools_impl_attr;

use proc_macro::TokenStream;
use proc_macro2::TokenStream as TokenStream2;
use syn::{parse_macro_input, DeriveInput};

// ---------------------------------------------------------------------------
// #[derive(GraphState)]
// ---------------------------------------------------------------------------

/// Derive macro for generating graph state schemas with per-field reducers.
///
/// # Attributes
///
/// - `#[reducer(append)]` — append arrays/values
/// - `#[reducer(last_value)]` — overwrite with latest (default)
/// - `#[reducer(add)]` — add numeric values
/// - `#[reducer(merge)]` — deep-merge JSON objects
#[proc_macro_derive(GraphState, attributes(reducer))]
pub fn derive_graph_state(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    graph_state::derive_graph_state(input).into()
}

// ---------------------------------------------------------------------------
// #[cognis::tool] attribute macro
// ---------------------------------------------------------------------------

/// `#[cognis::tool]` — attribute macro that generates a
/// [`cognis_core::tools::BaseTool`] implementation from an `async fn`.
///
/// Applies to either a standalone `async fn` or an `impl` block that
/// contains exactly one `async fn` (the stateful form, where the tool
/// struct holds configuration such as HTTP clients or API keys).
///
/// # Arguments
///
/// - `name = "..."` — overrides the tool name (defaults to the fn name).
/// - `description = "..."` — overrides the fn's doc-comment description.
/// - `return_direct = true|false` — passes through to `BaseTool::return_direct`.
///
/// # Field validators
///
/// `#[schema(range(...))]`, `#[schema(length(...))]`, `#[schema(pattern(...))]`,
/// `#[schema(enum_values(...))]`, and `#[schema(format(...))]` on fn arguments
/// emit matching runtime checks. Range/length/pattern are also translated into
/// `#[schemars(...)]` attributes on the generated args struct so they appear
/// in the JSON Schema produced via `schemars::schema_for!`. Enum-values and
/// format are merged into the schema during `args_schema()` post-processing.
///
/// See `cognis_core::tools::validation` for the runtime helpers the
/// generated code invokes.
#[proc_macro_attribute]
pub fn tool(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as tool_attr::ToolArgs);
    let item_ts: TokenStream2 = item.into();
    match tool_attr::expand(args, item_ts) {
        Ok(ts) => ts.into(),
        Err(e) => e.to_compile_error().into(),
    }
}

/// `#[derive(GraphStateV2)]` — v2-shape state derive that emits a typed
/// sibling `<Name>Update` struct and an `impl GraphState for <Name>`. Use
/// in v2 code via the re-export `cognis_core::GraphState` (the rename
/// happens in cognis-core's lib.rs in Plan #2).
#[proc_macro_derive(GraphStateV2, attributes(reducer, graph_state))]
pub fn derive_graph_state_v2(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    graph_state_v2::derive_graph_state_v2(input).into()
}

/// `#[tools_impl]` — outer attribute that scans an `impl` block for inner
/// `#[tool]`-marked async methods and generates one [`cognis_core::tools::BaseTool`]
/// wrapper per method, plus an `into_tools()` collector method on the user's
/// struct.
///
/// # Arguments
///
/// - `crate_path = "..."` — override the framework crate (default: `"cognis_core"`).
///
/// Inner `#[tool]` markers on methods follow the same syntax as the standalone
/// `#[tool]` attribute (name, description, return_direct, crate_path).
#[proc_macro_attribute]
pub fn tools_impl(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as tools_impl_attr::ToolsImplArgs);
    let item_ts: TokenStream2 = item.into();
    match tools_impl_attr::expand(args, item_ts) {
        Ok(ts) => ts.into(),
        Err(e) => e.to_compile_error().into(),
    }
}