@studio-foundation/ralph 0.3.0-beta.6 → 0.4.0-beta

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 +30 -14
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,25 +1,27 @@
1
1
  # @studio-foundation/ralph
2
2
 
3
- The retry engine. Execute → validate → retry with escalated feedback → repeat.
3
+ **Studio** is an agentic pipeline runtime that executes multi-stage LLM workflows with structural validation and automatic retry. This package is **ralph**: the retry engine. Execute → validate → retry with escalated feedback → repeat, until success or max attempts is reached.
4
4
 
5
5
  **RALPH** = Recursive Automated Loop for Persistent Handling.
6
6
 
7
- ## Role
7
+ ralph sits between [`engine`](https://www.npmjs.com/package/@studio-foundation/engine) (orchestration) and [`runner`](https://www.npmjs.com/package/@studio-foundation/runner) (LLM execution). It knows nothing about LLMs, it takes a generic `executor` function and a validator, and loops. That's why it's reusable outside Studio: anywhere you need "run this thing, validate its output, retry if it fails with escalating feedback", ralph works.
8
8
 
9
- ralph sits between the engine (orchestration) and runner (LLM execution). It knows nothing about LLMs — it takes a generic `executor` function and a contract, and loops until the output passes or max attempts is reached.
9
+ - Homepage: https://github.com/studio-foundation/studio
10
+ - Full docs: [README](https://github.com/studio-foundation/studio#readme) · [CONCEPTS](https://github.com/studio-foundation/studio/blob/main/CONCEPTS.md) · [INVARIANTS](https://github.com/studio-foundation/studio/blob/main/INVARIANTS.md)
11
+ - Use via the CLI: [`@studio-foundation/cli`](https://www.npmjs.com/package/@studio-foundation/cli)
10
12
 
11
- ```
12
- engine → ralph(executor, contract) → success | exhausted
13
- ↑
14
- executor = () => runner.runAgent(...)
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install @studio-foundation/ralph
17
+ # or
18
+ pnpm add @studio-foundation/ralph
15
19
  ```
16
20
 
17
- ## Key exports
21
+ ## Quick start
18
22
 
19
23
  ```typescript
20
- import { ralph, RalphConfig, RalphResult } from '@studio-foundation/ralph';
21
- import { validateSchema, validateToolCalls, validateRequiredTools, compose } from '@studio-foundation/ralph';
22
- import { exponentialBackoff, fixedDelay, noDelay } from '@studio-foundation/ralph';
24
+ import { ralph, compose, validateSchema, validateToolCalls, exponentialBackoff } from '@studio-foundation/ralph';
23
25
 
24
26
  const result = await ralph({
25
27
  executor: async (context) => runner.runAgent(context),
@@ -44,6 +46,14 @@ const result = await ralph({
44
46
  5. If max attempts reached → returns `{ status: 'exhausted', lastResult, failures, attempts }`
45
47
  6. If `signal` is aborted at any point → returns `{ status: 'cancelled', lastResult?, attempts }`
46
48
 
49
+ ## Architecture
50
+
51
+ ```
52
+ engine → ralph(executor, contract) → success | exhausted
53
+ ↑
54
+ executor = () => runner.runAgent(...)
55
+ ```
56
+
47
57
  ## Validators
48
58
 
49
59
  ralph exports composable validators that the engine uses to build per-stage validation:
@@ -53,7 +63,7 @@ ralph exports composable validators that the engine uses to build per-stage vali
53
63
  | `validateSchema(output, contract)` | Check required fields are present |
54
64
  | `validateToolCalls(count, reqs)` | Check minimum tool call count |
55
65
  | `validateRequiredTools(calls, reqs)` | Check specific tools were called |
56
- | `validateCountedTools(calls, reqs)` | OR semantics — any of these count toward minimum |
66
+ | `validateCountedTools(calls, reqs)` | OR semantics: any of these count toward minimum |
57
67
  | `compose(...validators)` | Combine multiple validators (all must pass) |
58
68
 
59
69
  ## Retry strategies
@@ -64,8 +74,14 @@ ralph exports composable validators that the engine uses to build per-stage vali
64
74
  | `fixedDelay(ms)` | Fixed wait between attempts |
65
75
  | `noDelay()` | No wait (prompt escalation handled by runner) |
66
76
 
67
- ## Rules
77
+ ## For contributors
78
+
79
+ Internal rules that govern this package:
68
80
 
69
81
  - **ralph doesn't know runner.** The `executor` is `() => Promise<T>`. ralph doesn't care what's behind it.
70
82
  - **ralph doesn't know engine.** It takes config, it returns a result. No pipeline state, no events.
71
- - Validation logic is in exported validators — the engine composes them per stage.
83
+ - Validation logic is in exported validators, the engine composes them per stage.
84
+
85
+ ## License
86
+
87
+ AGPL-3.0-only
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@studio-foundation/ralph",
3
- "version": "0.3.0-beta.6",
3
+ "version": "0.4.0-beta",
4
4
  "description": "RALPH loop engine - Recursive Automated Loop for Persistent Handling",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -24,7 +24,7 @@
24
24
  "license": "AGPL-3.0-only",
25
25
  "dependencies": {
26
26
  "js-yaml": "^4.1.1",
27
- "@studio-foundation/contracts": "0.3.0-beta.6"
27
+ "@studio-foundation/contracts": "0.4.0-beta"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/js-yaml": "^4.0.9",