@reactive-agents/prompts 0.10.2 → 0.10.4

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 (2) hide show
  1. package/README.md +113 -27
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @reactive-agents/prompts
2
2
 
3
- Prompt management for the [Reactive Agents](https://docs.reactiveagents.dev/) framework.
3
+ Prompt management for the [Reactive Agents](https://docs.reactiveagents.dev/) framework. **v0.10.3**
4
4
 
5
- A template engine with variable interpolation and a built-in library of agent prompts for common use cases.
5
+ A version-controlled template engine with `{{variable}}` interpolation, type-safe variable bindings, and a built-in library of agent prompts covering reasoning strategies (ReAct, Plan-Execute, Tree-of-Thought, Reflexion), evaluation judges (accuracy, relevance, completeness, safety), and tier-adaptive system prompts (frontier vs. local models).
6
6
 
7
7
  ## Installation
8
8
 
@@ -10,42 +10,93 @@ A template engine with variable interpolation and a built-in library of agent pr
10
10
  bun add @reactive-agents/prompts
11
11
  ```
12
12
 
13
+ Or via the umbrella:
14
+
15
+ ```bash
16
+ bun add reactive-agents
17
+ ```
18
+
13
19
  ## Features
14
20
 
15
- - **Template engine** — `{{variable}}` interpolation with type-safe bindings
16
- - **Prompt library** — pre-built system prompts for researcher, coder, analyst, and more
17
- - **Versioning** — store and retrieve prompt versions
21
+ - **Template engine** — `{{variable}}` interpolation with required/optional variables, defaults, and type guards
22
+ - **Built-in template library** — reasoning, verification, evaluation, and default agent system prompts
23
+ - **Tier-adaptive variants** — separate `react-system-frontier`, `react-system-local`, `react-thought-frontier`, `react-thought-local` for cost-aware prompt routing
24
+ - **Version-controlled** — every template carries a `version` integer; `PromptService` looks up the latest unless pinned
25
+ - **Token estimator** — `estimateTokens()` for budget planning before render
26
+ - **A/B experiments** — `ExperimentService` (unstable) for prompt variant evaluation
18
27
 
19
- ## Usage
28
+ ## Quick Example
20
29
 
21
30
  ```typescript
22
- import { PromptTemplate, PromptLibrary } from "@reactive-agents/prompts";
31
+ import { interpolate } from "@reactive-agents/prompts";
23
32
 
24
- // Use a built-in prompt
25
- const systemPrompt = PromptLibrary.get("researcher");
33
+ const rendered = interpolate(
34
+ "You are a {{role}} expert. Answer in {{language}}.",
35
+ { role: "TypeScript", language: "English" },
36
+ );
37
+ ```
26
38
 
27
- // Or define your own
28
- const template = PromptTemplate.create({
29
- template: "You are a {{role}} expert. Answer in {{language}}.",
30
- variables: { role: "TypeScript", language: "English" },
31
- });
39
+ ## Built-in Templates
32
40
 
33
- const prompt = template.render({ role: "React", language: "Spanish" });
34
- ```
41
+ ### Reasoning
42
+
43
+ | Template | Strategy / phase |
44
+ | ----------------------------------------- | ----------------------------------------- |
45
+ | `reactTemplate` | High-level ReAct loop prompt |
46
+ | `reactSystemTemplate` | ReAct system prompt |
47
+ | `reactThoughtTemplate` | ReAct thought-step prompt |
48
+ | `reactSystemFrontierTemplate` / `reactSystemLocalTemplate` | Tier-adaptive system variants |
49
+ | `reactThoughtFrontierTemplate` / `reactThoughtLocalTemplate` | Tier-adaptive thought variants |
50
+ | `planExecuteTemplate` | Plan-Execute high-level |
51
+ | `planExecutePlanTemplate` | Plan phase |
52
+ | `planExecuteExecuteTemplate` | Execute phase |
53
+ | `planExecuteReflectTemplate` | Reflect phase |
54
+ | `treeOfThoughtTemplate` | ToT high-level |
55
+ | `treeOfThoughtExpandTemplate` | Expand candidate thoughts |
56
+ | `treeOfThoughtScoreTemplate` | Score candidates |
57
+ | `treeOfThoughtSynthesizeTemplate` | Synthesize chosen branch |
58
+ | `reflexionTemplate` | Reflexion high-level |
59
+ | `reflexionGenerateTemplate` | Generate attempt |
60
+ | `reflexionCritiqueTemplate` | Critique prior attempt |
61
+ | `adaptiveClassifyTemplate` | Classify task complexity for routing |
62
+
63
+ ### Verification
64
+
65
+ | Template | Use |
66
+ | ------------------- | -------------------------------- |
67
+ | `factCheckTemplate` | Fact-check decomposed claims |
68
+
69
+ ### Evaluation (judges)
70
+
71
+ | Template | Dimension |
72
+ | ------------------------------ | --------------- |
73
+ | `judgeAccuracyTemplate` | Accuracy |
74
+ | `judgeRelevanceTemplate` | Relevance |
75
+ | `judgeCompletenessTemplate` | Completeness |
76
+ | `judgeSafetyTemplate` | Safety |
77
+ | `judgeGenericTemplate` | Generic rubric |
78
+
79
+ ### Agent
80
+
81
+ | Template | Use |
82
+ | ------------------------- | --------------------------------------- |
83
+ | `defaultSystemTemplate` | Default agent system prompt |
84
+
85
+ `allBuiltinTemplates` is a flat array of every template above — useful for bulk registration.
35
86
 
36
- With the builder:
87
+ ## Builder Integration
37
88
 
38
89
  ```typescript
39
90
  import { ReactiveAgents } from "reactive-agents";
40
91
 
41
- // Enable built-in prompt templates (reasoning, evaluation, agent)
92
+ // Enable all built-in templates
42
93
  const agent = await ReactiveAgents.create()
43
94
  .withName("researcher")
44
- .withProvider("anthropic")
45
- .withPrompts() // registers all built-in templates
95
+ .withProvider("anthropic", { model: "claude-sonnet-4-20250514" })
96
+ .withPrompts()
46
97
  .build();
47
98
 
48
- // Or register custom templates at build time:
99
+ // Or register custom templates at build time
49
100
  const customAgent = await ReactiveAgents.create()
50
101
  .withName("custom")
51
102
  .withProvider("anthropic")
@@ -58,12 +109,7 @@ const customAgent = await ReactiveAgents.create()
58
109
  template: "You are a {{role}} expert. Answer in {{language}}.",
59
110
  variables: [
60
111
  { name: "role", required: true, type: "string" },
61
- {
62
- name: "language",
63
- required: false,
64
- type: "string",
65
- defaultValue: "English",
66
- },
112
+ { name: "language", required: false, type: "string", defaultValue: "English" },
67
113
  ],
68
114
  },
69
115
  ],
@@ -71,6 +117,46 @@ const customAgent = await ReactiveAgents.create()
71
117
  .build();
72
118
  ```
73
119
 
120
+ ## Direct Service Usage
121
+
122
+ ```typescript
123
+ import { Effect } from "effect";
124
+ import { PromptService, PromptServiceLive } from "@reactive-agents/prompts";
125
+
126
+ const program = Effect.gen(function* () {
127
+ const prompts = yield* PromptService;
128
+ const compiled = yield* prompts.compile("react.system", {
129
+ role: "research assistant",
130
+ tools: ["web_search", "calculator"],
131
+ });
132
+ return compiled.text;
133
+ });
134
+ ```
135
+
136
+ ## A/B Experiments (unstable)
137
+
138
+ ```typescript
139
+ import { ExperimentService } from "@reactive-agents/prompts";
140
+ // Variant assignment, outcome capture, results aggregation.
141
+ // See AUDIT-overhaul-2026.md §11 #41 — surface may change in v0.10.x.
142
+ ```
143
+
144
+ ## Key Exports
145
+
146
+ | Export | Purpose |
147
+ | ------------------------------------------------ | ---------------------------------------------- |
148
+ | `PromptService`, `PromptServiceLive` | Template registration + compilation |
149
+ | `interpolate`, `estimateTokens` | Pure template-engine helpers |
150
+ | `allBuiltinTemplates` | Bulk registration array |
151
+ | `createPromptLayer` | Factory for the runtime layer |
152
+ | `ExperimentService`, `ExperimentServiceLive` | A/B experimentation (unstable) |
153
+ | `PromptTemplate`, `CompiledPrompt`, `PromptVariable` | Schemas + types |
154
+ | `PromptError`, `TemplateNotFoundError`, `VariableError` | Tagged errors |
155
+
74
156
  ## Documentation
75
157
 
76
158
  Full documentation at [docs.reactiveagents.dev](https://docs.reactiveagents.dev/)
159
+
160
+ ## License
161
+
162
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@reactive-agents/prompts",
3
- "version": "0.10.2",
3
+ "version": "0.10.4",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
11
11
  "test:watch": "bun test --watch"
12
12
  },
13
13
  "dependencies": {
14
- "@reactive-agents/core": "0.10.2"
14
+ "@reactive-agents/core": "0.10.4"
15
15
  },
16
16
  "devDependencies": {
17
17
  "typescript": "^5.7.0",