@studio-foundation/ralph 0.3.0-beta.1
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.
- package/ARCHITECTURE.md +41 -0
- package/LICENSE +663 -0
- package/README.md +71 -0
- package/configs/examples/analysis.contract.yaml +19 -0
- package/configs/examples/code-generation.contract.yaml +21 -0
- package/package.json +42 -0
- package/src/context-enricher.ts +9 -0
- package/src/contracts.ts +28 -0
- package/src/index.ts +7 -0
- package/src/loop.ts +122 -0
- package/src/retry-strategy.ts +23 -0
- package/src/validator.ts +160 -0
- package/tests/loop.test.ts +355 -0
- package/tests/retry.test.ts +87 -0
- package/tests/validator.test.ts +625 -0
- package/tsconfig.json +24 -0
package/ARCHITECTURE.md
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# @studio-foundation/ralph
|
|
2
|
+
|
|
3
|
+
RALPH loop engine — retry intelligent avec validation.
|
|
4
|
+
"Recursive Automated Loop for Persistent Handling"
|
|
5
|
+
|
|
6
|
+
## Concept
|
|
7
|
+
|
|
8
|
+
`ralph<T>()` prend un `executor` générique et un `validator`. Il exécute, valide, retry si fail, s'arrête sur AbortSignal.
|
|
9
|
+
C'est tout. C'est générique. Ça marche pour n'importe quoi, pas juste des LLMs.
|
|
10
|
+
|
|
11
|
+
## Règles
|
|
12
|
+
|
|
13
|
+
- `ralph()` est UNE fonction. Pas une classe, pas un framework.
|
|
14
|
+
- Le `executor` est `() => Promise<T>` — ralph ne sait pas que c'est un LLM derrière
|
|
15
|
+
- La validation est composable via `compose(...validators)`
|
|
16
|
+
- Les stratégies de retry sont pluggables (`exponentialBackoff`, `fixedDelay`, `noDelay`)
|
|
17
|
+
- JAMAIS de dépendance sur `@studio-foundation/runner` ou `@studio-foundation/engine` — ralph est agnostique
|
|
18
|
+
- Dépend UNIQUEMENT de `@studio-foundation/contracts`
|
|
19
|
+
|
|
20
|
+
## Résultat
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
type RalphResult<T> =
|
|
24
|
+
| { status: 'success'; result: T; attempts: number }
|
|
25
|
+
| { status: 'exhausted'; lastResult: T; failures: string[]; attempts: number }
|
|
26
|
+
| { status: 'cancelled'; lastResult?: T; attempts: number } // AbortSignal
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Fichiers clés
|
|
30
|
+
|
|
31
|
+
- `loop.ts` — `ralph()` la fonction principale + `RalphConfig`, `RalphResult`
|
|
32
|
+
- `validator.ts` — `validateSchema`, `validateToolCalls`, `validateRequiredTools`, `compose`
|
|
33
|
+
- `retry-strategy.ts` — `exponentialBackoff(min, max)`, `fixedDelay(ms)`, `noDelay()`
|
|
34
|
+
- `context-enricher.ts` — enrichir contexte entre retries
|
|
35
|
+
- `contracts.ts` — types internes ralph
|
|
36
|
+
|
|
37
|
+
## Anti-patterns
|
|
38
|
+
|
|
39
|
+
- NE PAS mettre de logique LLM ici
|
|
40
|
+
- NE PAS importer `@studio-foundation/runner`
|
|
41
|
+
- NE PAS hardcoder des règles de validation — tout vient des contracts YAML
|