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