@astratra/ai 1.0.1 → 1.1.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.
- package/README.md +20 -7
- package/package.json +4 -1
- package/src/agentLoop.js +32 -5
- package/src/index.d.ts +19 -0
package/README.md
CHANGED
|
@@ -74,7 +74,9 @@ const reponse = await runAgentLoop({
|
|
|
74
74
|
registry,
|
|
75
75
|
router,
|
|
76
76
|
userRole: 'doctor',
|
|
77
|
-
maxSteps: 5
|
|
77
|
+
maxSteps: 5,
|
|
78
|
+
onChunk: (chunk) => res.write(chunk), // streaming token par token, optionnel
|
|
79
|
+
confirmTool: async (toolCall) => askUser(toolCall) // confirmation avant exécution, optionnel
|
|
78
80
|
});
|
|
79
81
|
```
|
|
80
82
|
|
|
@@ -83,12 +85,23 @@ modèle, exécute l'outil correspondant enregistré (refuse si le rôle n'y a
|
|
|
83
85
|
pas accès), réinjecte le résultat sous forme de `<tool_result>`, et boucle
|
|
84
86
|
jusqu'à une réponse finale ou `maxSteps` atteint.
|
|
85
87
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
88
|
+
`onChunk(chunk)` est appelé pour chaque morceau reçu si `router.ask()`
|
|
89
|
+
retourne un flux (async iterable) — un vrai passthrough token par token vers
|
|
90
|
+
ton UI. La boucle continue d'accumuler le texte complet en interne (elle en
|
|
91
|
+
a besoin pour détecter un `<tool_call>`), donc le fournir ne change rien au
|
|
92
|
+
comportement, juste un point d'observation en plus.
|
|
93
|
+
|
|
94
|
+
`confirmTool(toolCall, ctx)` est attendu avant l'exécution d'un appel d'outil
|
|
95
|
+
détecté. Retourne `false` (ou une promesse résolue en `false`) pour refuser
|
|
96
|
+
— la boucle ne plante pas, elle informe le modèle (`{"denied": true, ...}`
|
|
97
|
+
comme résultat d'outil) et continue, il peut réagir (expliquer, proposer
|
|
98
|
+
autre chose, s'arrêter). Omis, chaque outil autorisé s'exécute automatiquement,
|
|
99
|
+
comme avant.
|
|
100
|
+
|
|
101
|
+
**Périmètre V0 — toujours volontairement exclu :** gestion d'images/vision.
|
|
102
|
+
Fonctionnalité non triviale dont une boucle d'agent de production a besoin,
|
|
103
|
+
mais dont le portage fidèle reste jugé trop ambitieux pour ce package. À
|
|
104
|
+
construire dans votre propre boucle, ou à couvrir dans un futur spec.
|
|
92
105
|
|
|
93
106
|
## Tests
|
|
94
107
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/ai",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
|
|
5
|
+
"engines": {
|
|
6
|
+
"node": ">=20"
|
|
7
|
+
},
|
|
5
8
|
"main": "src/index.js",
|
|
6
9
|
"types": "src/index.d.ts",
|
|
7
10
|
"type": "commonjs",
|
package/src/agentLoop.js
CHANGED
|
@@ -9,7 +9,9 @@ async function runAgentLoop({
|
|
|
9
9
|
registry,
|
|
10
10
|
router,
|
|
11
11
|
userRole,
|
|
12
|
-
maxSteps = DEFAULT_MAX_STEPS
|
|
12
|
+
maxSteps = DEFAULT_MAX_STEPS,
|
|
13
|
+
onChunk,
|
|
14
|
+
confirmTool
|
|
13
15
|
}) {
|
|
14
16
|
if (!registry) throw new AppError('agentLoop requires a registry', 500);
|
|
15
17
|
if (!router || typeof router.ask !== 'function') throw new AppError('agentLoop requires a router', 500);
|
|
@@ -19,11 +21,15 @@ async function runAgentLoop({
|
|
|
19
21
|
|
|
20
22
|
for (let step = 0; step < maxSteps; step += 1) {
|
|
21
23
|
const modelPrompt = buildPrompt(registry, userRole, messages);
|
|
24
|
+
// onChunk, when provided, is called with each chunk AS IT ARRIVES if
|
|
25
|
+
// router.ask() returns a stream — real token-by-token streaming to the
|
|
26
|
+
// caller. The loop itself still needs the fully-assembled text to
|
|
27
|
+
// detect a <tool_call>, so it accumulates in parallel regardless.
|
|
22
28
|
const response = await stringifyModelResponse(await router.ask(modelPrompt, {
|
|
23
29
|
complexity: 'agent',
|
|
24
30
|
intent: 'agent_loop',
|
|
25
31
|
estimatedTokens: estimateTokens(modelPrompt)
|
|
26
|
-
}, ctx));
|
|
32
|
+
}, ctx), onChunk);
|
|
27
33
|
const toolCall = parseToolCall(response);
|
|
28
34
|
|
|
29
35
|
if (!toolCall) {
|
|
@@ -38,6 +44,23 @@ async function runAgentLoop({
|
|
|
38
44
|
throw new AppError(`Tool "${toolCall.name}" is not allowed for role "${userRole}"`, 403);
|
|
39
45
|
}
|
|
40
46
|
|
|
47
|
+
// confirmTool, when provided, gates execution — e.g. a human approval
|
|
48
|
+
// step surfaced by the calling app before a write/delete tool actually
|
|
49
|
+
// runs. Denying doesn't crash the loop: the model gets told and can
|
|
50
|
+
// adjust course (ask something else, explain, stop), same as it would
|
|
51
|
+
// handle any other tool result.
|
|
52
|
+
if (typeof confirmTool === 'function') {
|
|
53
|
+
const approved = await confirmTool(toolCall, ctx);
|
|
54
|
+
if (!approved) {
|
|
55
|
+
messages.push({ role: 'assistant', content: response });
|
|
56
|
+
messages.push({
|
|
57
|
+
role: 'tool',
|
|
58
|
+
content: `<tool_result name="${tool.name}">${JSON.stringify({ denied: true, reason: 'Execution was not approved.' })}</tool_result>`
|
|
59
|
+
});
|
|
60
|
+
continue;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
41
64
|
const result = await tool.handler(toolCall.params, ctx);
|
|
42
65
|
messages.push({ role: 'assistant', content: response });
|
|
43
66
|
messages.push({
|
|
@@ -76,15 +99,19 @@ function parseToolCall(text) {
|
|
|
76
99
|
}
|
|
77
100
|
}
|
|
78
101
|
|
|
79
|
-
async function stringifyModelResponse(value) {
|
|
102
|
+
async function stringifyModelResponse(value, onChunk) {
|
|
80
103
|
if (isAsyncIterable(value)) {
|
|
81
104
|
let output = '';
|
|
82
105
|
for await (const chunk of value) {
|
|
83
|
-
|
|
106
|
+
const text = String(chunk);
|
|
107
|
+
output += text;
|
|
108
|
+
if (typeof onChunk === 'function') onChunk(text);
|
|
84
109
|
}
|
|
85
110
|
return output;
|
|
86
111
|
}
|
|
87
|
-
|
|
112
|
+
const text = String(value ?? '');
|
|
113
|
+
if (typeof onChunk === 'function') onChunk(text);
|
|
114
|
+
return text;
|
|
88
115
|
}
|
|
89
116
|
|
|
90
117
|
function isAsyncIterable(value) {
|
package/src/index.d.ts
CHANGED
|
@@ -88,6 +88,11 @@ export interface AgentRouter {
|
|
|
88
88
|
ask(prompt: string, request?: ProviderRequest, ctx?: Record<string, unknown>): Awaitable<string | AsyncIterable<unknown> | null | undefined>;
|
|
89
89
|
}
|
|
90
90
|
|
|
91
|
+
export interface ToolCall {
|
|
92
|
+
name: string;
|
|
93
|
+
params: Record<string, unknown>;
|
|
94
|
+
}
|
|
95
|
+
|
|
91
96
|
export interface AgentLoopOptions {
|
|
92
97
|
prompt: string;
|
|
93
98
|
ctx?: Record<string, unknown>;
|
|
@@ -96,6 +101,20 @@ export interface AgentLoopOptions {
|
|
|
96
101
|
router: AgentRouter;
|
|
97
102
|
userRole: string;
|
|
98
103
|
maxSteps?: number;
|
|
104
|
+
/**
|
|
105
|
+
* Called with each text chunk as it arrives, when router.ask() returns a
|
|
106
|
+
* stream — real token-by-token passthrough to your UI. The loop still
|
|
107
|
+
* needs the fully-assembled text to detect a tool call, so it keeps
|
|
108
|
+
* accumulating internally regardless of whether you pass this.
|
|
109
|
+
*/
|
|
110
|
+
onChunk?: (chunk: string) => void;
|
|
111
|
+
/**
|
|
112
|
+
* Awaited before a detected tool call actually executes. Return (or
|
|
113
|
+
* resolve to) false to deny — the loop tells the model the call was not
|
|
114
|
+
* approved and continues, rather than crashing. Omit to auto-execute
|
|
115
|
+
* every allowed tool call, unchanged from before.
|
|
116
|
+
*/
|
|
117
|
+
confirmTool?: (toolCall: ToolCall, ctx: Record<string, unknown>) => Awaitable<boolean>;
|
|
99
118
|
}
|
|
100
119
|
|
|
101
120
|
export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
|