@fastpaca/cria 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/README.md +37 -27
  2. package/dist/dsl/builder.d.ts +275 -0
  3. package/dist/dsl/builder.d.ts.map +1 -0
  4. package/dist/dsl/builder.js +569 -0
  5. package/dist/dsl/builder.js.map +1 -0
  6. package/dist/dsl/index.d.ts +78 -0
  7. package/dist/dsl/index.d.ts.map +1 -0
  8. package/dist/dsl/index.js +92 -0
  9. package/dist/dsl/index.js.map +1 -0
  10. package/dist/dsl/strategies.d.ts +29 -0
  11. package/dist/dsl/strategies.d.ts.map +1 -0
  12. package/dist/dsl/strategies.js +62 -0
  13. package/dist/dsl/strategies.js.map +1 -0
  14. package/dist/dsl/summary.d.ts +51 -0
  15. package/dist/dsl/summary.d.ts.map +1 -0
  16. package/dist/dsl/summary.js +56 -0
  17. package/dist/dsl/summary.js.map +1 -0
  18. package/dist/dsl/templating.d.ts +31 -0
  19. package/dist/dsl/templating.d.ts.map +1 -0
  20. package/dist/dsl/templating.js +83 -0
  21. package/dist/dsl/templating.js.map +1 -0
  22. package/dist/{components → dsl}/vector-search.d.ts +11 -34
  23. package/dist/dsl/vector-search.d.ts.map +1 -0
  24. package/dist/{components → dsl}/vector-search.js +12 -34
  25. package/dist/dsl/vector-search.js.map +1 -0
  26. package/dist/eval/index.d.ts +16 -2
  27. package/dist/eval/index.d.ts.map +1 -1
  28. package/dist/eval/judge.d.ts +7 -5
  29. package/dist/eval/judge.d.ts.map +1 -1
  30. package/dist/eval/judge.js +18 -5
  31. package/dist/eval/judge.js.map +1 -1
  32. package/dist/index.d.ts +12 -11
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +8 -8
  35. package/dist/index.js.map +1 -1
  36. package/dist/instrumentation/otel.js +5 -14
  37. package/dist/instrumentation/otel.js.map +1 -1
  38. package/dist/memory/chroma/index.js +4 -4
  39. package/dist/protocols/chat-completions.d.ts +38 -0
  40. package/dist/protocols/chat-completions.d.ts.map +1 -0
  41. package/dist/protocols/chat-completions.js +94 -0
  42. package/dist/protocols/chat-completions.js.map +1 -0
  43. package/dist/protocols/responses.d.ts +80 -0
  44. package/dist/protocols/responses.d.ts.map +1 -0
  45. package/dist/protocols/responses.js +148 -0
  46. package/dist/protocols/responses.js.map +1 -0
  47. package/dist/provider.d.ts +94 -0
  48. package/dist/provider.d.ts.map +1 -0
  49. package/dist/provider.js +60 -0
  50. package/dist/provider.js.map +1 -0
  51. package/dist/providers/ai-sdk.d.ts +44 -0
  52. package/dist/providers/ai-sdk.d.ts.map +1 -0
  53. package/dist/providers/ai-sdk.js +144 -0
  54. package/dist/providers/ai-sdk.js.map +1 -0
  55. package/dist/providers/anthropic.d.ts +48 -0
  56. package/dist/providers/anthropic.d.ts.map +1 -0
  57. package/dist/providers/anthropic.js +279 -0
  58. package/dist/providers/anthropic.js.map +1 -0
  59. package/dist/providers/openai.d.ts +64 -0
  60. package/dist/providers/openai.d.ts.map +1 -0
  61. package/dist/providers/openai.js +411 -0
  62. package/dist/providers/openai.js.map +1 -0
  63. package/dist/render.d.ts +25 -22
  64. package/dist/render.d.ts.map +1 -1
  65. package/dist/render.js +194 -63
  66. package/dist/render.js.map +1 -1
  67. package/dist/testing/plaintext.d.ts +29 -0
  68. package/dist/testing/plaintext.d.ts.map +1 -0
  69. package/dist/testing/plaintext.js +106 -0
  70. package/dist/testing/plaintext.js.map +1 -0
  71. package/dist/types.d.ts +186 -174
  72. package/dist/types.d.ts.map +1 -1
  73. package/dist/types.js +22 -104
  74. package/dist/types.js.map +1 -1
  75. package/package.json +25 -49
  76. package/dist/components/index.d.ts +0 -147
  77. package/dist/components/index.d.ts.map +0 -1
  78. package/dist/components/index.js +0 -181
  79. package/dist/components/index.js.map +0 -1
  80. package/dist/components/summary.d.ts +0 -89
  81. package/dist/components/summary.d.ts.map +0 -1
  82. package/dist/components/summary.js +0 -118
  83. package/dist/components/summary.js.map +0 -1
  84. package/dist/components/vector-search.d.ts.map +0 -1
  85. package/dist/components/vector-search.js.map +0 -1
  86. package/dist/dsl.d.ts +0 -233
  87. package/dist/dsl.d.ts.map +0 -1
  88. package/dist/dsl.js +0 -428
  89. package/dist/dsl.js.map +0 -1
  90. package/dist/integrations/ai-sdk.d.ts +0 -22
  91. package/dist/integrations/ai-sdk.d.ts.map +0 -1
  92. package/dist/integrations/ai-sdk.js +0 -172
  93. package/dist/integrations/ai-sdk.js.map +0 -1
  94. package/dist/integrations/anthropic.d.ts +0 -50
  95. package/dist/integrations/anthropic.d.ts.map +0 -1
  96. package/dist/integrations/anthropic.js +0 -220
  97. package/dist/integrations/anthropic.js.map +0 -1
  98. package/dist/integrations/openai.d.ts +0 -48
  99. package/dist/integrations/openai.d.ts.map +0 -1
  100. package/dist/integrations/openai.js +0 -265
  101. package/dist/integrations/openai.js.map +0 -1
  102. package/dist/jsx/index.d.ts +0 -6
  103. package/dist/jsx/index.d.ts.map +0 -1
  104. package/dist/jsx/index.js +0 -7
  105. package/dist/jsx/index.js.map +0 -1
  106. package/dist/jsx/jsx-dev-runtime.d.ts +0 -2
  107. package/dist/jsx/jsx-dev-runtime.d.ts.map +0 -1
  108. package/dist/jsx/jsx-dev-runtime.js +0 -3
  109. package/dist/jsx/jsx-dev-runtime.js.map +0 -1
  110. package/dist/jsx/jsx-runtime.d.ts +0 -40
  111. package/dist/jsx/jsx-runtime.d.ts.map +0 -1
  112. package/dist/jsx/jsx-runtime.js +0 -40
  113. package/dist/jsx/jsx-runtime.js.map +0 -1
  114. package/dist/renderers/markdown.d.ts +0 -3
  115. package/dist/renderers/markdown.d.ts.map +0 -1
  116. package/dist/renderers/markdown.js +0 -43
  117. package/dist/renderers/markdown.js.map +0 -1
  118. package/dist/renderers/shared.d.ts +0 -82
  119. package/dist/renderers/shared.d.ts.map +0 -1
  120. package/dist/renderers/shared.js +0 -156
  121. package/dist/renderers/shared.js.map +0 -1
  122. package/dist/snapshot.d.ts +0 -47
  123. package/dist/snapshot.d.ts.map +0 -1
  124. package/dist/snapshot.js +0 -144
  125. package/dist/snapshot.js.map +0 -1
  126. package/dist/tokenizers.d.ts +0 -14
  127. package/dist/tokenizers.d.ts.map +0 -1
  128. package/dist/tokenizers.js +0 -45
  129. package/dist/tokenizers.js.map +0 -1
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  <h1 align="center">Cria</h1>
2
2
 
3
+ > **Note:** Cria is under active development. We're iterating heavily and the API may change before 2.0. Use in production at your own discretion.
4
+
3
5
  <p align="center">
4
6
  <i>Your prompts deserve the same structure as your code.</i>
5
7
  </p>
@@ -24,14 +26,12 @@ Cria is a lightweight prompt composition library for structured prompt engineeri
24
26
 
25
27
  ```ts
26
28
  const messages = await cria
27
- .prompt()
29
+ .prompt(provider)
28
30
  .system("You are a research assistant.")
29
31
  .vectorSearch({ store, query: question, limit: 10 })
30
- .provider(provider, (p) =>
31
- p.summary(conversation, { store: memory }).last(conversation, { N: 20 })
32
- )
32
+ .summary(conversation, { id: "history", store: memory, priority: 2 })
33
33
  .user(question)
34
- .render({ budget: 200_000, renderer });
34
+ .render({ budget: 200_000 });
35
35
  ```
36
36
 
37
37
  Start with **[Quickstart](docs/quickstart.md)**, then use **[Docs](docs/README.md)** to jump to the right how-to.
@@ -43,24 +43,24 @@ Start with **[Quickstart](docs/quickstart.md)**, then use **[Docs](docs/README.m
43
43
  - **Need to cap history but keep structure?** Use `.last(...)`.
44
44
  - **Need to drop optional context when the context window is full?** Use `.omit(...)`.
45
45
  - **Using AI SDK?** Plug and play with `@fastpaca/cria/ai-sdk`!
46
- - **Prefer TSX?** Import the optional JSX surface from `@fastpaca/cria/jsx`.
47
46
 
48
- ## Integrations
47
+ ## Providers
49
48
 
50
49
  <details>
51
50
  <summary><strong>OpenAI Chat Completions</strong></summary>
52
51
 
53
52
  ```ts
54
53
  import OpenAI from "openai";
55
- import { chatCompletions } from "@fastpaca/cria/openai";
54
+ import { createProvider } from "@fastpaca/cria/openai";
56
55
  import { cria } from "@fastpaca/cria";
57
56
 
58
57
  const client = new OpenAI();
58
+ const provider = createProvider(client, "gpt-4o-mini");
59
59
  const messages = await cria
60
- .prompt()
60
+ .prompt(provider)
61
61
  .system("You are helpful.")
62
62
  .user(userQuestion)
63
- .render({ budget, tokenizer, renderer: chatCompletions });
63
+ .render({ budget });
64
64
  const response = await client.chat.completions.create({ model: "gpt-4o-mini", messages });
65
65
  ```
66
66
  </details>
@@ -70,15 +70,16 @@ const response = await client.chat.completions.create({ model: "gpt-4o-mini", me
70
70
 
71
71
  ```ts
72
72
  import OpenAI from "openai";
73
- import { responses } from "@fastpaca/cria/openai";
73
+ import { createResponsesProvider } from "@fastpaca/cria/openai";
74
74
  import { cria } from "@fastpaca/cria";
75
75
 
76
76
  const client = new OpenAI();
77
+ const provider = createResponsesProvider(client, "gpt-5-nano");
77
78
  const input = await cria
78
- .prompt()
79
+ .prompt(provider)
79
80
  .system("You are helpful.")
80
81
  .user(userQuestion)
81
- .render({ budget, tokenizer, renderer: responses });
82
+ .render({ budget });
82
83
  const response = await client.responses.create({ model: "gpt-5-nano", input });
83
84
  ```
84
85
  </details>
@@ -88,15 +89,16 @@ const response = await client.responses.create({ model: "gpt-5-nano", input });
88
89
 
89
90
  ```ts
90
91
  import Anthropic from "@anthropic-ai/sdk";
91
- import { anthropic } from "@fastpaca/cria/anthropic";
92
+ import { createProvider } from "@fastpaca/cria/anthropic";
92
93
  import { cria } from "@fastpaca/cria";
93
94
 
94
95
  const client = new Anthropic();
96
+ const provider = createProvider(client, "claude-haiku-4-5");
95
97
  const { system, messages } = await cria
96
- .prompt()
98
+ .prompt(provider)
97
99
  .system("You are helpful.")
98
100
  .user(userQuestion)
99
- .render({ budget, tokenizer, renderer: anthropic });
101
+ .render({ budget });
100
102
  const response = await client.messages.create({ model: "claude-haiku-4-5", system, messages });
101
103
  ```
102
104
  </details>
@@ -105,15 +107,16 @@ const response = await client.messages.create({ model: "claude-haiku-4-5", syste
105
107
  <summary><strong>Vercel AI SDK</strong></summary>
106
108
 
107
109
  ```ts
108
- import { renderer } from "@fastpaca/cria/ai-sdk";
110
+ import { createProvider } from "@fastpaca/cria/ai-sdk";
109
111
  import { cria } from "@fastpaca/cria";
110
112
  import { generateText } from "ai";
111
113
 
114
+ const provider = createProvider(model);
112
115
  const messages = await cria
113
- .prompt()
116
+ .prompt(provider)
114
117
  .system("You are helpful.")
115
118
  .user(userQuestion)
116
- .render({ budget, tokenizer, renderer });
119
+ .render({ budget });
117
120
  const { text } = await generateText({ model, messages });
118
121
  ```
119
122
  </details>
@@ -147,26 +150,33 @@ await judge(prompt).toPass(c`Helpfulness in addressing the user's question`);
147
150
  **Done**
148
151
 
149
152
  - [x] Fluent DSL and priority-based eviction
150
- - [x] Components: Region, Message, Truncate, Omit, Last, Summary, VectorSearch, ToolCall, ToolResult, Reasoning, Examples, CodeBlock, Separator
151
- - [x] Renderers: OpenAI (Chat Completions + Responses), Anthropic, AI SDK
152
- - [x] AI SDK helpers: Messages component, DEFAULT_PRIORITIES
153
- - [x] Memory: InMemoryStore, Redis, Postgres, Chroma, Qdrant
154
- - [x] Observability: render hooks, validation schemas, snapshots, OpenTelemetry
155
- - [x] Tokenizer helpers
153
+ - [x] Providers/Integrations
154
+ - [x] OpenAI (Chat Completions + Responses)
155
+ - [x] Anthropic
156
+ - [x] AI SDK
157
+ - [x] Memory:
158
+ - [x] Key Value Stores for Summaries
159
+ - [x] Redis
160
+ - [x] Postgres
161
+ - [x] Vector Store / RAG
162
+ - [x] Chroma
163
+ - [x] Qdrant
164
+ - [x] Observability
165
+ - [x] render hooks
166
+ - [x] OpenTelemetry
156
167
  - [x] Prompt eval / testing functionality
157
168
 
158
169
  **Planned**
159
170
 
160
171
  - [ ] Next.js adapter
161
- - [ ] GenAI semantic conventions for OpenTelemetry
162
172
  - [ ] Visualization tool
173
+ - [ ] Seamless provider integration (type system, no hoops)
163
174
 
164
175
  ## Contributing
165
176
 
166
177
  - Issues and PRs are welcome.
167
178
  - Keep changes small and focused.
168
179
  - If you add a feature, include a short example or doc note.
169
- - Prefer DSL-based examples in contributions; JSX lives under `@fastpaca/cria/jsx` as optional sugar.
170
180
 
171
181
  ## Support
172
182
 
@@ -0,0 +1,275 @@
1
+ /**
2
+ * Fluent builders for constructing prompts.
3
+ */
4
+ import type { KVMemory, VectorMemory } from "../memory";
5
+ import type { InputLayout, ModelProvider, PromptInput } from "../provider";
6
+ import type { RenderOptions } from "../render";
7
+ import type { CriaContext, PromptLayout, PromptNode, PromptPart, PromptRole, PromptTree, ProviderToolIO, ToolIOForProvider, ToolResultPart } from "../types";
8
+ import type { StoredSummary, Summarizer } from "./summary";
9
+ import { type TextInput } from "./templating";
10
+ import type { ResultFormatter } from "./vector-search";
11
+ /**
12
+ * Content that can be passed to scope-level operations like truncate/omit.
13
+ */
14
+ type AnyPromptBuilder = PromptBuilder<unknown>;
15
+ /**
16
+ * Type flow in the DSL:
17
+ * - P is the bound provider type (or unknown when unbound).
18
+ * - ToolIOForProvider<P> extracts the provider's tool IO contract.
19
+ * - PromptPart/PromptNode/etc. are all parameterized by that tool IO so tool calls
20
+ * stay typed from builder → tree → layout → codec.
21
+ * - When P is unknown, ToolIOForProvider<P> resolves to "never" for tool IO,
22
+ * preventing tool parts until a provider is bound.
23
+ */
24
+ type ToolIOFor<P> = ToolIOForProvider<P>;
25
+ type PromptPartFor<P> = PromptPart<ToolIOFor<P>>;
26
+ type PromptNodeFor<P> = PromptNode<ToolIOFor<P>>;
27
+ type PromptTreeFor<P> = PromptTree<ToolIOFor<P>>;
28
+ type ToolResultPartFor<P> = ToolResultPart<ToolIOFor<P>>;
29
+ type TextInputFor<P> = TextInput<ToolIOFor<P>>;
30
+ type InputFor<P> = P extends ModelProvider<infer TRendered, infer _TToolIO> ? PromptInput<TRendered> : never;
31
+ type InputLayoutFor<P> = InputLayout<ToolIOFor<P>>;
32
+ export type ScopeContent<P = unknown> = PromptNodeFor<P> | PromptBuilder<P> | AnyPromptBuilder | InputFor<P> | InputLayoutFor<P> | Promise<PromptNodeFor<P>> | readonly ScopeContent<P>[];
33
+ /**
34
+ * Children can include promises (async components like VectorSearch).
35
+ * These are resolved when `.build()` resolves the tree.
36
+ */
37
+ export type BuilderChild<P = unknown> = PromptNodeFor<P> | PromptPartFor<P> | PromptBuilder<P> | AnyPromptBuilder | string | number | boolean | Promise<PromptNodeFor<P> | PromptPartFor<P> | string | number | boolean>;
38
+ type BoundProvider = ModelProvider<unknown, ProviderToolIO>;
39
+ type RenderedForProvider<P> = P extends ModelProvider<infer TOutput, infer _TToolIO> ? TOutput : unknown;
40
+ /**
41
+ * Provider binding helpers:
42
+ * - BoundProvider captures any provider with a codec + tool IO contract.
43
+ * - RenderedForProvider ties render() return types to a specific provider.
44
+ * - RenderOptionsWithoutProvider omits provider when the builder is already bound.
45
+ */
46
+ type RenderOptionsWithoutProvider<TRendered, TToolIO extends ProviderToolIO> = Omit<RenderOptions<TRendered, TToolIO>, "provider">;
47
+ /**
48
+ * Shared fluent API for prompt-level and message-level builders.
49
+ */
50
+ export declare abstract class BuilderBase<TBuilder extends BuilderBase<TBuilder, P>, P> {
51
+ readonly children: BuilderChild<P>[];
52
+ readonly context: CriaContext | undefined;
53
+ protected constructor(children?: BuilderChild<P>[], context?: CriaContext | undefined);
54
+ protected abstract create(children: BuilderChild<P>[], context: CriaContext | undefined): TBuilder;
55
+ /**
56
+ * Merge another builder's contents into this one (zod-like merge).
57
+ * Contexts must be compatible (either identical or undefined).
58
+ */
59
+ merge(...builders: TBuilder[]): TBuilder;
60
+ protected addChild(child: BuilderChild<P>): TBuilder;
61
+ protected addChildren(children: readonly BuilderChild<P>[]): TBuilder;
62
+ }
63
+ export declare class MessageBuilder<P = unknown> extends BuilderBase<MessageBuilder<P>, P> {
64
+ constructor(children?: BuilderChild<P>[], context?: CriaContext | undefined);
65
+ protected create(children: BuilderChild<P>[], context: CriaContext | undefined): MessageBuilder<P>;
66
+ append(content: TextInputFor<P>): MessageBuilder<P>;
67
+ /**
68
+ * Add vector search results as message content (async, resolved at render time).
69
+ */
70
+ vectorSearch<T = unknown>(opts: {
71
+ store: VectorMemory<T>;
72
+ query: string;
73
+ limit?: number;
74
+ threshold?: number;
75
+ formatter?: ResultFormatter<T>;
76
+ }): MessageBuilder<P>;
77
+ /**
78
+ * Add a formatted list of examples.
79
+ */
80
+ examples(title: string, items: string[]): MessageBuilder<P>;
81
+ buildChildren(): Promise<PromptPartFor<P>[]>;
82
+ }
83
+ /**
84
+ * Fluent builder for constructing prompt trees.
85
+ *
86
+ * Every method returns a new immutable builder instance; large chains will copy
87
+ * child arrays, so keep prompts reasonably sized.
88
+ * Call `.build()` to get the final `PromptTree`.
89
+ */
90
+ export declare class PromptBuilder<P = unknown> extends BuilderBase<PromptBuilder<P>, P> {
91
+ private readonly boundProvider;
92
+ private constructor();
93
+ /**
94
+ * Create a new empty prompt builder.
95
+ */
96
+ static create(): PromptBuilder<unknown>;
97
+ static create<TProvider extends BoundProvider>(provider: TProvider): PromptBuilder<TProvider>;
98
+ protected create(children: BuilderChild<P>[], context: CriaContext | undefined): PromptBuilder<P>;
99
+ /**
100
+ * Bind this prompt builder to a provider.
101
+ * Enables provider-specific rendering without passing a provider at render time.
102
+ * This also locks tool-call input/output types for the rest of the builder chain.
103
+ */
104
+ provider<TProvider extends BoundProvider>(this: PromptBuilder<unknown> | PromptBuilder<TProvider>, modelProvider: TProvider): PromptBuilder<TProvider>;
105
+ scope(fn: (builder: PromptBuilder<P>) => PromptBuilder<P>, opts?: {
106
+ id?: string;
107
+ }): PromptBuilder<P>;
108
+ /**
109
+ * Add content that will be truncated when over budget.
110
+ */
111
+ truncate(content: ScopeContent<P>, opts: {
112
+ budget: number;
113
+ from?: "start" | "end";
114
+ priority?: number;
115
+ id?: string;
116
+ }): PromptBuilder<P>;
117
+ /**
118
+ * Add content that will be entirely removed when over budget.
119
+ */
120
+ omit(content: ScopeContent<P>, opts?: {
121
+ priority?: number;
122
+ id?: string;
123
+ }): PromptBuilder<P>;
124
+ /**
125
+ * Create a provider scope for AI-powered operations like Summary.
126
+ *
127
+ * @example
128
+ * ```typescript
129
+ * import { createProvider } from "@fastpaca/cria/ai-sdk";
130
+ * import { openai } from "@ai-sdk/openai";
131
+ *
132
+ * const provider = createProvider(openai("gpt-4o"));
133
+ * cria.prompt()
134
+ * .providerScope(provider, (p) =>
135
+ * p.summary(content, { id: "conv", store })
136
+ * )
137
+ * ```
138
+ */
139
+ providerScope<TProvider extends BoundProvider>(this: PromptBuilder<unknown> | PromptBuilder<TProvider>, modelProvider: TProvider, fn: (builder: PromptBuilder<TProvider>) => PromptBuilder<TProvider>): PromptBuilder<TProvider>;
140
+ /**
141
+ * Add provider-native input (requires a bound provider).
142
+ */
143
+ input<TRendered, TToolIO extends ProviderToolIO>(this: PromptBuilder<ModelProvider<TRendered, TToolIO>>, content: TRendered): PromptBuilder<ModelProvider<TRendered, TToolIO>>;
144
+ /**
145
+ * Add a PromptLayout input.
146
+ */
147
+ inputLayout(content: PromptLayout<ToolIOFor<P>>): PromptBuilder<P>;
148
+ /**
149
+ * Add vector search results (async, resolved at render time).
150
+ */
151
+ vectorSearch<T = unknown>(opts: {
152
+ store: VectorMemory<T>;
153
+ query: string;
154
+ limit?: number;
155
+ threshold?: number;
156
+ formatter?: ResultFormatter<T>;
157
+ priority?: number;
158
+ id?: string;
159
+ }): PromptBuilder<P>;
160
+ /**
161
+ * Add content that will be summarized when over budget.
162
+ */
163
+ summary(content: ScopeContent<P>, opts: {
164
+ id: string;
165
+ store: KVMemory<StoredSummary>;
166
+ summarize?: Summarizer;
167
+ priority?: number;
168
+ }): PromptBuilder<P>;
169
+ /**
170
+ * Keep only the last N messages from the content.
171
+ *
172
+ * @example
173
+ * ```typescript
174
+ * cria.prompt()
175
+ * .system("You are helpful.")
176
+ * .last(conversationHistory, { n: 20 })
177
+ * .user("What's next?")
178
+ * ```
179
+ */
180
+ last(content: ScopeContent<P>, opts: {
181
+ n: number;
182
+ id?: string;
183
+ }): PromptBuilder<P>;
184
+ /**
185
+ * Add a raw PromptNode (escape hatch for advanced usage).
186
+ */
187
+ raw(element: PromptNodeFor<P> | Promise<PromptNodeFor<P>>): PromptBuilder<P>;
188
+ /**
189
+ * Merge builders or raw nodes into this one.
190
+ * Accepts PromptBuilders, individual PromptNodes, or arrays of PromptNodes.
191
+ *
192
+ * @example
193
+ * ```typescript
194
+ * // Merge builders
195
+ * cria.prompt().system("A").merge(otherBuilder)
196
+ *
197
+ * // Merge raw nodes
198
+ * cria.prompt().system("A").merge(...scope.children)
199
+ * ```
200
+ */
201
+ merge(...items: (PromptBuilder<P> | PromptBuilder<unknown> | PromptNodeFor<P> | readonly PromptNodeFor<P>[])[]): PromptBuilder<P>;
202
+ private mergeItem;
203
+ /**
204
+ * Conditionally apply a transformation to the builder.
205
+ *
206
+ * @example
207
+ * ```typescript
208
+ * cria.prompt()
209
+ * .system("Hello")
210
+ * .when(hasContext, (p) => p.user("Context: ..."))
211
+ * .user("Question")
212
+ * ```
213
+ */
214
+ when(condition: boolean, fn: (builder: PromptBuilder<P>) => PromptBuilder<P>): PromptBuilder<P>;
215
+ /**
216
+ * Add a system message.
217
+ */
218
+ system(content: TextInputFor<P> | ((builder: MessageBuilder<P>) => MessageBuilder<P>), opts?: {
219
+ id?: string;
220
+ }): PromptBuilder<P>;
221
+ /**
222
+ * Add a developer message.
223
+ */
224
+ developer(content: TextInputFor<P> | ((builder: MessageBuilder<P>) => MessageBuilder<P>), opts?: {
225
+ id?: string;
226
+ }): PromptBuilder<P>;
227
+ /**
228
+ * Add a user message.
229
+ */
230
+ user(content: TextInputFor<P> | ((builder: MessageBuilder<P>) => MessageBuilder<P>), opts?: {
231
+ id?: string;
232
+ }): PromptBuilder<P>;
233
+ /**
234
+ * Add an assistant message.
235
+ */
236
+ assistant(content: TextInputFor<P> | ((builder: MessageBuilder<P>) => MessageBuilder<P>), opts?: {
237
+ id?: string;
238
+ }): PromptBuilder<P>;
239
+ /**
240
+ * Add a tool result message.
241
+ */
242
+ tool<TProvider extends BoundProvider>(this: PromptBuilder<TProvider>, result: ToolResultPartFor<TProvider> | readonly ToolResultPartFor<TProvider>[], opts?: {
243
+ id?: string;
244
+ }): PromptBuilder<TProvider>;
245
+ /**
246
+ * Add a message with a custom role.
247
+ */
248
+ message(role: PromptRole, content: TextInputFor<P> | ((builder: MessageBuilder<P>) => MessageBuilder<P>), opts?: {
249
+ id?: string;
250
+ }): PromptBuilder<P>;
251
+ buildChildren(): Promise<PromptNodeFor<P>[]>;
252
+ /**
253
+ * Build the final PromptTree.
254
+ */
255
+ build(): Promise<PromptTreeFor<P>>;
256
+ /**
257
+ * Render the prompt directly using the provided options.
258
+ * Equivalent to `render(await builder.build(), options)`.
259
+ *
260
+ * Overloads:
261
+ * - Bound builder: provider is implicit.
262
+ * - Unbound builder: provider must be supplied to establish tool IO types.
263
+ */
264
+ render<TProvider extends BoundProvider>(this: PromptBuilder<TProvider>, options?: RenderOptionsWithoutProvider<RenderedForProvider<TProvider>, ToolIOForProvider<TProvider>>): Promise<RenderedForProvider<TProvider>>;
265
+ render<TProvider extends BoundProvider>(this: PromptBuilder<unknown>, options: RenderOptions<RenderedForProvider<TProvider>, ToolIOForProvider<TProvider>> & {
266
+ provider: TProvider;
267
+ }): Promise<RenderedForProvider<TProvider>>;
268
+ private addMessage;
269
+ }
270
+ /**
271
+ * Prompt type alias for external use.
272
+ */
273
+ export type Prompt<P = unknown> = PromptBuilder<P>;
274
+ export {};
275
+ //# sourceMappingURL=builder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/dsl/builder.ts"],"names":[],"mappings":"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"}