@theokit/di-agent 0.2.0 → 0.4.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/CHANGELOG.md +73 -10
- package/LICENSE +2 -2
- package/dist/index.cjs +10 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +183 -8
- package/dist/index.d.ts +183 -8
- package/dist/index.js +10 -8
- package/dist/index.js.map +1 -1
- package/package.json +14 -10
package/dist/index.d.cts
CHANGED
|
@@ -42,70 +42,181 @@ interface CreateAgentProviderOptions<TAgent> {
|
|
|
42
42
|
*/
|
|
43
43
|
declare function createAgentProvider<TAgent>(options: CreateAgentProviderOptions<TAgent>): FactoryProvider<TAgent>;
|
|
44
44
|
|
|
45
|
+
/**
|
|
46
|
+
* The class a class decorator was applied to, as seen by the reader helpers.
|
|
47
|
+
*
|
|
48
|
+
* Spelled as a constructor signature rather than `Function`. `Function` is the widest callable
|
|
49
|
+
* type there is — it accepts any argument list and returns `any` — so it documents nothing and
|
|
50
|
+
* silently admits things that are not classes at all. The constructor form says what the readers
|
|
51
|
+
* actually receive: something you could have written `new` in front of.
|
|
52
|
+
*
|
|
53
|
+
* `abstract` so an abstract base class is accepted, and `...args: never` because the readers only
|
|
54
|
+
* ever pass the value to `Reflect.getMetadata` and never construct it, so the parameter list is
|
|
55
|
+
* deliberately unusable rather than merely unconstrained.
|
|
56
|
+
*/
|
|
57
|
+
type DecoratedClass = abstract new (...args: never) => unknown;
|
|
58
|
+
|
|
59
|
+
/** What {@link Auth} declares: the identity `providers` this agent accepts, and any transport
|
|
60
|
+
* `sessionConfig` they need. */
|
|
45
61
|
interface AuthOptions {
|
|
46
62
|
providers?: string[];
|
|
47
63
|
sessionConfig?: unknown;
|
|
48
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* Declare how an agent class authenticates the caller.
|
|
67
|
+
*
|
|
68
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
69
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
70
|
+
*/
|
|
49
71
|
declare function Auth(options?: AuthOptions): ClassDecorator;
|
|
50
|
-
|
|
72
|
+
/** The `@Auth` of a class, or `undefined` when it has none.
|
|
73
|
+
*
|
|
74
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
75
|
+
* property and method decorators, which accumulate into a map. */
|
|
76
|
+
declare function readAuthMetadata(target: DecoratedClass): AuthOptions | undefined;
|
|
51
77
|
|
|
78
|
+
/** What {@link AutoSummarize} declares: the `triggerFraction` of the context window that starts a
|
|
79
|
+
* summarisation, how many recent turns to `keepNewest` verbatim, and optionally which `model`
|
|
80
|
+
* writes the summary. */
|
|
52
81
|
interface AutoSummarizeOptions {
|
|
53
82
|
triggerFraction?: number;
|
|
54
83
|
keepNewest?: number;
|
|
55
84
|
model?: string;
|
|
56
85
|
}
|
|
86
|
+
/**
|
|
87
|
+
* Declare that a conversation is summarised automatically as it approaches the context limit, so
|
|
88
|
+
* it can continue past the point where it would otherwise be truncated.
|
|
89
|
+
*
|
|
90
|
+
* Defaults are resolved at decoration time, so a reader of the metadata sees real values rather
|
|
91
|
+
* than having to know them.
|
|
92
|
+
*
|
|
93
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
94
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
95
|
+
*/
|
|
57
96
|
declare function AutoSummarize(options?: AutoSummarizeOptions): ClassDecorator;
|
|
58
|
-
|
|
97
|
+
/** The `@AutoSummarize` of a class with its defaults resolved, or `undefined` when it has none.
|
|
98
|
+
*
|
|
99
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
100
|
+
* property and method decorators, which accumulate into a map. */
|
|
101
|
+
declare function readAutoSummarizeMetadata(target: DecoratedClass): (Required<Omit<AutoSummarizeOptions, "model">> & {
|
|
59
102
|
model?: string;
|
|
60
103
|
}) | undefined;
|
|
61
104
|
|
|
105
|
+
/** What {@link Cron} declares: the `schedule` as a cron expression and the `timezone` it is read
|
|
106
|
+
* in. The expression is stored verbatim and never parsed here, so a malformed one surfaces
|
|
107
|
+
* wherever it is eventually scheduled. */
|
|
62
108
|
interface CronOptions {
|
|
63
109
|
schedule: string;
|
|
64
110
|
timezone?: string;
|
|
65
111
|
}
|
|
112
|
+
/** A stored `@Cron`, with the method it was applied to. The map is already keyed by that method;
|
|
113
|
+
* `methodKey` repeats it so an entry read on its own still says what it schedules. */
|
|
66
114
|
interface CronMetadata extends CronOptions {
|
|
67
115
|
methodKey: string | symbol;
|
|
68
116
|
}
|
|
117
|
+
/**
|
|
118
|
+
* `@Cron(options)` — declare a scheduled routine on a method.
|
|
119
|
+
*
|
|
120
|
+
* Accumulates per method, keyed by the method name, so a class may schedule as many
|
|
121
|
+
* routines as it has methods. It used to keep a single object per class, which meant a
|
|
122
|
+
* second `@Cron` on the same class silently discarded the first (#6).
|
|
123
|
+
*/
|
|
69
124
|
declare function Cron(options: CronOptions): MethodDecorator;
|
|
70
|
-
|
|
125
|
+
/** Read `@Cron()` metadata off a class constructor, keyed by method (insertion-ordered). */
|
|
126
|
+
declare function readCronMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, CronMetadata>;
|
|
71
127
|
|
|
128
|
+
/** What {@link EvalDecorator} declares: the evaluation's `name`, the `scorers` that judge a run,
|
|
129
|
+
* and the `dataset` it runs against. */
|
|
72
130
|
interface EvalOptions {
|
|
73
131
|
name?: string;
|
|
74
132
|
scorers?: unknown[];
|
|
75
133
|
dataset?: unknown;
|
|
76
134
|
}
|
|
135
|
+
/**
|
|
136
|
+
* Declare an agent class as the subject of an evaluation.
|
|
137
|
+
*
|
|
138
|
+
* Named `EvalDecorator` rather than `Eval` because `eval` is a reserved word in strict mode, and
|
|
139
|
+
* an export nobody can import under its own name is worse than a longer one.
|
|
140
|
+
*
|
|
141
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
142
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
143
|
+
*/
|
|
77
144
|
declare function EvalDecorator(options?: EvalOptions): ClassDecorator;
|
|
78
|
-
|
|
145
|
+
/** The `@EvalDecorator` of a class, or `undefined` when it has none.
|
|
146
|
+
*
|
|
147
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
148
|
+
* property and method decorators, which accumulate into a map. */
|
|
149
|
+
declare function readEvalDecoratorMetadata(target: DecoratedClass): EvalOptions | undefined;
|
|
79
150
|
|
|
151
|
+
/** What {@link Hitl} declares: the `tools` whose invocation needs a human decision, and the
|
|
152
|
+
* `timeoutMs` after which waiting stops. */
|
|
80
153
|
interface HitlOptions {
|
|
81
154
|
tools: string[];
|
|
82
155
|
timeoutMs?: number;
|
|
83
156
|
}
|
|
157
|
+
/** A stored `@Hitl`, with the method it was applied to. The map is already keyed by that method;
|
|
158
|
+
* `methodKey` repeats it so an entry read on its own still says what it guards. */
|
|
84
159
|
interface HitlMetadata extends HitlOptions {
|
|
85
160
|
methodKey: string | symbol;
|
|
86
161
|
}
|
|
162
|
+
/**
|
|
163
|
+
* `@Hitl(options)` — declare a human-in-the-loop approval handler on a method.
|
|
164
|
+
*
|
|
165
|
+
* Accumulates per method, keyed by the method name, so a class may declare as many
|
|
166
|
+
* handlers as it has methods. It used to keep a single object per class, which meant a
|
|
167
|
+
* second `@Hitl` on the same class silently discarded the first (#6).
|
|
168
|
+
*/
|
|
87
169
|
declare function Hitl(options: HitlOptions): MethodDecorator;
|
|
88
|
-
|
|
170
|
+
/** Read `@Hitl()` metadata off a class constructor, keyed by method (insertion-ordered). */
|
|
171
|
+
declare function readHitlMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, HitlMetadata>;
|
|
89
172
|
|
|
173
|
+
/** What {@link MemoryScopeDecorator} declares: the `path` naming this scope's place in the
|
|
174
|
+
* memory hierarchy. */
|
|
90
175
|
interface MemoryScopeOptions {
|
|
91
176
|
path: string;
|
|
92
177
|
}
|
|
178
|
+
/**
|
|
179
|
+
* Declare the memory scope a property reads and writes, so sibling scopes stay isolated from
|
|
180
|
+
* each other while a child can still see its parent.
|
|
181
|
+
*
|
|
182
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
183
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
184
|
+
*/
|
|
93
185
|
declare function MemoryScopeDecorator(options: MemoryScopeOptions): PropertyDecorator;
|
|
186
|
+
/** Every `@MemoryScopeDecorator` on a class, keyed by the property it was applied to. */
|
|
94
187
|
declare function readMemoryScopeMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, MemoryScopeOptions>;
|
|
95
188
|
|
|
189
|
+
/** What {@link Reranker} declares: which provider and model score the candidates, and how many
|
|
190
|
+
* survive (`topN`). */
|
|
96
191
|
interface RerankerOptions {
|
|
97
192
|
provider?: string;
|
|
98
193
|
model?: string;
|
|
99
194
|
topN?: number;
|
|
100
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* Declare a property as the reranking step that reorders what a retriever returned.
|
|
198
|
+
*
|
|
199
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
200
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
201
|
+
*/
|
|
101
202
|
declare function Reranker(options: RerankerOptions): PropertyDecorator;
|
|
203
|
+
/** Every `@Reranker` on a class, keyed by the property it was applied to. */
|
|
102
204
|
declare function readRerankerMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RerankerOptions>;
|
|
103
205
|
|
|
206
|
+
/** What {@link Retriever} declares: how many passages to return (`topK`) and the minimum score
|
|
207
|
+
* a passage needs to be worth returning at all (`threshold`). */
|
|
104
208
|
interface RetrieverOptions {
|
|
105
209
|
topK?: number;
|
|
106
210
|
threshold?: number;
|
|
107
211
|
}
|
|
212
|
+
/**
|
|
213
|
+
* Declare a property as the retrieval step of a RAG pipeline.
|
|
214
|
+
*
|
|
215
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
216
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
217
|
+
*/
|
|
108
218
|
declare function Retriever(options: RetrieverOptions): PropertyDecorator;
|
|
219
|
+
/** Every `@Retriever` on a class, keyed by the property it was applied to. */
|
|
109
220
|
declare function readRetrieverMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RetrieverOptions>;
|
|
110
221
|
|
|
111
222
|
/**
|
|
@@ -156,6 +267,9 @@ declare function Step(metadata?: StepMetadata): MethodDecorator;
|
|
|
156
267
|
/** Read `@Step()` metadata off a class constructor (insertion-ordered). */
|
|
157
268
|
declare function readStepMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, StepMetadata>;
|
|
158
269
|
|
|
270
|
+
/** What {@link SubAgent} declares: how the parent agent describes the delegate when deciding
|
|
271
|
+
* whether to hand work over, and optionally which model it runs on and how deep delegation may
|
|
272
|
+
* nest before it stops. */
|
|
159
273
|
interface SubAgentOptions {
|
|
160
274
|
name: string;
|
|
161
275
|
description: string;
|
|
@@ -163,48 +277,109 @@ interface SubAgentOptions {
|
|
|
163
277
|
model?: string;
|
|
164
278
|
maxDelegationDepth?: number;
|
|
165
279
|
}
|
|
280
|
+
/**
|
|
281
|
+
* Declare a property as a subagent this one may delegate to, exposed to the parent as a tool.
|
|
282
|
+
*
|
|
283
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
284
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
285
|
+
*/
|
|
166
286
|
declare function SubAgent(options: SubAgentOptions): PropertyDecorator;
|
|
287
|
+
/** Every `@SubAgent` on a class, keyed by the property it was applied to. */
|
|
167
288
|
declare function readSubAgentMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubAgentOptions>;
|
|
168
289
|
|
|
290
|
+
/** What {@link Subscription} declares: the event `name` to listen for, and optionally the
|
|
291
|
+
* `transport` it arrives on. */
|
|
169
292
|
interface SubscriptionOptions {
|
|
170
293
|
name: string;
|
|
171
294
|
transport?: string;
|
|
172
295
|
}
|
|
296
|
+
/**
|
|
297
|
+
* Declare a property as a subscription to an event stream.
|
|
298
|
+
*
|
|
299
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
300
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
301
|
+
*/
|
|
173
302
|
declare function Subscription(options: SubscriptionOptions): PropertyDecorator;
|
|
303
|
+
/** Every `@Subscription` on a class, keyed by the property it was applied to. */
|
|
174
304
|
declare function readSubscriptionMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubscriptionOptions>;
|
|
175
305
|
|
|
306
|
+
/** What {@link TextSplitter} declares: the splitting `strategy`, the target `chunkSize`, and how
|
|
307
|
+
* much `overlap` consecutive chunks share so a passage split mid-sentence is still retrievable
|
|
308
|
+
* from either side. */
|
|
176
309
|
interface TextSplitterOptions {
|
|
177
310
|
strategy?: string;
|
|
178
311
|
chunkSize?: number;
|
|
179
312
|
overlap?: number;
|
|
180
313
|
}
|
|
314
|
+
/**
|
|
315
|
+
* Declare a property as the step that breaks documents into indexable chunks.
|
|
316
|
+
*
|
|
317
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
318
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
319
|
+
*/
|
|
181
320
|
declare function TextSplitter(options: TextSplitterOptions): PropertyDecorator;
|
|
321
|
+
/** Every `@TextSplitter` on a class, keyed by the property it was applied to. */
|
|
182
322
|
declare function readTextSplitterMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, TextSplitterOptions>;
|
|
183
323
|
|
|
324
|
+
/** What {@link Tool} declares about one tool: the name and description an agent sees when
|
|
325
|
+
* choosing it, and optionally the schema its input must match. */
|
|
184
326
|
interface ToolOptions {
|
|
185
327
|
name: string;
|
|
186
328
|
description: string;
|
|
187
329
|
inputSchema?: unknown;
|
|
188
330
|
}
|
|
331
|
+
/**
|
|
332
|
+
* Declare a property as a tool an agent may call.
|
|
333
|
+
*
|
|
334
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
335
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
336
|
+
*/
|
|
189
337
|
declare function Tool(options: ToolOptions): PropertyDecorator;
|
|
338
|
+
/** Every `@Tool` on a class, keyed by the property it was applied to. Empty map when there are
|
|
339
|
+
* none — a class with no tools is ordinary, not an error. */
|
|
190
340
|
declare function readToolMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, ToolOptions>;
|
|
191
341
|
|
|
342
|
+
/** What {@link UseSandbox} declares: which `backend` isolates the execution, the `workDir` it
|
|
343
|
+
* starts in, and the `timeoutMs` after which it is abandoned. */
|
|
192
344
|
interface UseSandboxOptions {
|
|
193
345
|
backend?: "local" | "docker" | string;
|
|
194
346
|
workDir?: string;
|
|
195
347
|
timeoutMs?: number;
|
|
196
348
|
}
|
|
349
|
+
/**
|
|
350
|
+
* Declare that a property's work runs inside a sandbox rather than in this process.
|
|
351
|
+
*
|
|
352
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
353
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
354
|
+
*/
|
|
197
355
|
declare function UseSandbox(options?: UseSandboxOptions): PropertyDecorator;
|
|
356
|
+
/** Every `@UseSandbox` on a class, keyed by the property it was applied to. */
|
|
198
357
|
declare function readSandboxMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, UseSandboxOptions>;
|
|
199
358
|
|
|
359
|
+
/** What {@link Workflow} declares about a workflow class: its `name`, an optional `retryPolicy`,
|
|
360
|
+
* and the schemas its input and output are expected to match. */
|
|
200
361
|
interface WorkflowOptions {
|
|
201
362
|
name?: string;
|
|
202
363
|
retryPolicy?: unknown;
|
|
203
364
|
inputSchema?: unknown;
|
|
204
365
|
outputSchema?: unknown;
|
|
205
366
|
}
|
|
367
|
+
/**
|
|
368
|
+
* Mark a class as a workflow.
|
|
369
|
+
*
|
|
370
|
+
* This is the class-level marker only. The steps are declared with `@Step` on the methods, and
|
|
371
|
+
* `buildWorkflow` compiles the two together into a runnable `@theokit/sdk` Workflow — which makes
|
|
372
|
+
* it the one decorator in this package with a consumer that ships here.
|
|
373
|
+
*
|
|
374
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
375
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
376
|
+
*/
|
|
206
377
|
declare function Workflow(options?: WorkflowOptions): ClassDecorator;
|
|
207
|
-
|
|
378
|
+
/** The `@Workflow` of a class, or `undefined` when it has none.
|
|
379
|
+
*
|
|
380
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
381
|
+
* property and method decorators, which accumulate into a map. */
|
|
382
|
+
declare function readWorkflowMetadata(target: DecoratedClass): WorkflowOptions | undefined;
|
|
208
383
|
|
|
209
384
|
/**
|
|
210
385
|
* Parameter decorator — injects the REQUEST-scoped Agent into a constructor.
|
|
@@ -234,7 +409,7 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
|
|
|
234
409
|
* `@theokit/sdk` `Workflow`.
|
|
235
410
|
*
|
|
236
411
|
* This is the materializer/bridge for the decorator-driven workflow authoring
|
|
237
|
-
* surface
|
|
412
|
+
* surface. It COMPOSES the existing `Workflow` engine — it
|
|
238
413
|
* adds no orchestration logic of its own (same principle as `createSquad`).
|
|
239
414
|
* Steps are topologically ordered by their single `after` dependency into a
|
|
240
415
|
* linear `Workflow.then(...)` chain; each step's return value is threaded into
|
|
@@ -253,4 +428,4 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
|
|
|
253
428
|
*/
|
|
254
429
|
declare function buildWorkflow(instance: object): Workflow$1;
|
|
255
430
|
|
|
256
|
-
export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
|
|
431
|
+
export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, type DecoratedClass, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
|
package/dist/index.d.ts
CHANGED
|
@@ -42,70 +42,181 @@ interface CreateAgentProviderOptions<TAgent> {
|
|
|
42
42
|
*/
|
|
43
43
|
declare function createAgentProvider<TAgent>(options: CreateAgentProviderOptions<TAgent>): FactoryProvider<TAgent>;
|
|
44
44
|
|
|
45
|
+
/**
|
|
46
|
+
* The class a class decorator was applied to, as seen by the reader helpers.
|
|
47
|
+
*
|
|
48
|
+
* Spelled as a constructor signature rather than `Function`. `Function` is the widest callable
|
|
49
|
+
* type there is — it accepts any argument list and returns `any` — so it documents nothing and
|
|
50
|
+
* silently admits things that are not classes at all. The constructor form says what the readers
|
|
51
|
+
* actually receive: something you could have written `new` in front of.
|
|
52
|
+
*
|
|
53
|
+
* `abstract` so an abstract base class is accepted, and `...args: never` because the readers only
|
|
54
|
+
* ever pass the value to `Reflect.getMetadata` and never construct it, so the parameter list is
|
|
55
|
+
* deliberately unusable rather than merely unconstrained.
|
|
56
|
+
*/
|
|
57
|
+
type DecoratedClass = abstract new (...args: never) => unknown;
|
|
58
|
+
|
|
59
|
+
/** What {@link Auth} declares: the identity `providers` this agent accepts, and any transport
|
|
60
|
+
* `sessionConfig` they need. */
|
|
45
61
|
interface AuthOptions {
|
|
46
62
|
providers?: string[];
|
|
47
63
|
sessionConfig?: unknown;
|
|
48
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* Declare how an agent class authenticates the caller.
|
|
67
|
+
*
|
|
68
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
69
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
70
|
+
*/
|
|
49
71
|
declare function Auth(options?: AuthOptions): ClassDecorator;
|
|
50
|
-
|
|
72
|
+
/** The `@Auth` of a class, or `undefined` when it has none.
|
|
73
|
+
*
|
|
74
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
75
|
+
* property and method decorators, which accumulate into a map. */
|
|
76
|
+
declare function readAuthMetadata(target: DecoratedClass): AuthOptions | undefined;
|
|
51
77
|
|
|
78
|
+
/** What {@link AutoSummarize} declares: the `triggerFraction` of the context window that starts a
|
|
79
|
+
* summarisation, how many recent turns to `keepNewest` verbatim, and optionally which `model`
|
|
80
|
+
* writes the summary. */
|
|
52
81
|
interface AutoSummarizeOptions {
|
|
53
82
|
triggerFraction?: number;
|
|
54
83
|
keepNewest?: number;
|
|
55
84
|
model?: string;
|
|
56
85
|
}
|
|
86
|
+
/**
|
|
87
|
+
* Declare that a conversation is summarised automatically as it approaches the context limit, so
|
|
88
|
+
* it can continue past the point where it would otherwise be truncated.
|
|
89
|
+
*
|
|
90
|
+
* Defaults are resolved at decoration time, so a reader of the metadata sees real values rather
|
|
91
|
+
* than having to know them.
|
|
92
|
+
*
|
|
93
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
94
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
95
|
+
*/
|
|
57
96
|
declare function AutoSummarize(options?: AutoSummarizeOptions): ClassDecorator;
|
|
58
|
-
|
|
97
|
+
/** The `@AutoSummarize` of a class with its defaults resolved, or `undefined` when it has none.
|
|
98
|
+
*
|
|
99
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
100
|
+
* property and method decorators, which accumulate into a map. */
|
|
101
|
+
declare function readAutoSummarizeMetadata(target: DecoratedClass): (Required<Omit<AutoSummarizeOptions, "model">> & {
|
|
59
102
|
model?: string;
|
|
60
103
|
}) | undefined;
|
|
61
104
|
|
|
105
|
+
/** What {@link Cron} declares: the `schedule` as a cron expression and the `timezone` it is read
|
|
106
|
+
* in. The expression is stored verbatim and never parsed here, so a malformed one surfaces
|
|
107
|
+
* wherever it is eventually scheduled. */
|
|
62
108
|
interface CronOptions {
|
|
63
109
|
schedule: string;
|
|
64
110
|
timezone?: string;
|
|
65
111
|
}
|
|
112
|
+
/** A stored `@Cron`, with the method it was applied to. The map is already keyed by that method;
|
|
113
|
+
* `methodKey` repeats it so an entry read on its own still says what it schedules. */
|
|
66
114
|
interface CronMetadata extends CronOptions {
|
|
67
115
|
methodKey: string | symbol;
|
|
68
116
|
}
|
|
117
|
+
/**
|
|
118
|
+
* `@Cron(options)` — declare a scheduled routine on a method.
|
|
119
|
+
*
|
|
120
|
+
* Accumulates per method, keyed by the method name, so a class may schedule as many
|
|
121
|
+
* routines as it has methods. It used to keep a single object per class, which meant a
|
|
122
|
+
* second `@Cron` on the same class silently discarded the first (#6).
|
|
123
|
+
*/
|
|
69
124
|
declare function Cron(options: CronOptions): MethodDecorator;
|
|
70
|
-
|
|
125
|
+
/** Read `@Cron()` metadata off a class constructor, keyed by method (insertion-ordered). */
|
|
126
|
+
declare function readCronMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, CronMetadata>;
|
|
71
127
|
|
|
128
|
+
/** What {@link EvalDecorator} declares: the evaluation's `name`, the `scorers` that judge a run,
|
|
129
|
+
* and the `dataset` it runs against. */
|
|
72
130
|
interface EvalOptions {
|
|
73
131
|
name?: string;
|
|
74
132
|
scorers?: unknown[];
|
|
75
133
|
dataset?: unknown;
|
|
76
134
|
}
|
|
135
|
+
/**
|
|
136
|
+
* Declare an agent class as the subject of an evaluation.
|
|
137
|
+
*
|
|
138
|
+
* Named `EvalDecorator` rather than `Eval` because `eval` is a reserved word in strict mode, and
|
|
139
|
+
* an export nobody can import under its own name is worse than a longer one.
|
|
140
|
+
*
|
|
141
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
142
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
143
|
+
*/
|
|
77
144
|
declare function EvalDecorator(options?: EvalOptions): ClassDecorator;
|
|
78
|
-
|
|
145
|
+
/** The `@EvalDecorator` of a class, or `undefined` when it has none.
|
|
146
|
+
*
|
|
147
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
148
|
+
* property and method decorators, which accumulate into a map. */
|
|
149
|
+
declare function readEvalDecoratorMetadata(target: DecoratedClass): EvalOptions | undefined;
|
|
79
150
|
|
|
151
|
+
/** What {@link Hitl} declares: the `tools` whose invocation needs a human decision, and the
|
|
152
|
+
* `timeoutMs` after which waiting stops. */
|
|
80
153
|
interface HitlOptions {
|
|
81
154
|
tools: string[];
|
|
82
155
|
timeoutMs?: number;
|
|
83
156
|
}
|
|
157
|
+
/** A stored `@Hitl`, with the method it was applied to. The map is already keyed by that method;
|
|
158
|
+
* `methodKey` repeats it so an entry read on its own still says what it guards. */
|
|
84
159
|
interface HitlMetadata extends HitlOptions {
|
|
85
160
|
methodKey: string | symbol;
|
|
86
161
|
}
|
|
162
|
+
/**
|
|
163
|
+
* `@Hitl(options)` — declare a human-in-the-loop approval handler on a method.
|
|
164
|
+
*
|
|
165
|
+
* Accumulates per method, keyed by the method name, so a class may declare as many
|
|
166
|
+
* handlers as it has methods. It used to keep a single object per class, which meant a
|
|
167
|
+
* second `@Hitl` on the same class silently discarded the first (#6).
|
|
168
|
+
*/
|
|
87
169
|
declare function Hitl(options: HitlOptions): MethodDecorator;
|
|
88
|
-
|
|
170
|
+
/** Read `@Hitl()` metadata off a class constructor, keyed by method (insertion-ordered). */
|
|
171
|
+
declare function readHitlMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, HitlMetadata>;
|
|
89
172
|
|
|
173
|
+
/** What {@link MemoryScopeDecorator} declares: the `path` naming this scope's place in the
|
|
174
|
+
* memory hierarchy. */
|
|
90
175
|
interface MemoryScopeOptions {
|
|
91
176
|
path: string;
|
|
92
177
|
}
|
|
178
|
+
/**
|
|
179
|
+
* Declare the memory scope a property reads and writes, so sibling scopes stay isolated from
|
|
180
|
+
* each other while a child can still see its parent.
|
|
181
|
+
*
|
|
182
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
183
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
184
|
+
*/
|
|
93
185
|
declare function MemoryScopeDecorator(options: MemoryScopeOptions): PropertyDecorator;
|
|
186
|
+
/** Every `@MemoryScopeDecorator` on a class, keyed by the property it was applied to. */
|
|
94
187
|
declare function readMemoryScopeMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, MemoryScopeOptions>;
|
|
95
188
|
|
|
189
|
+
/** What {@link Reranker} declares: which provider and model score the candidates, and how many
|
|
190
|
+
* survive (`topN`). */
|
|
96
191
|
interface RerankerOptions {
|
|
97
192
|
provider?: string;
|
|
98
193
|
model?: string;
|
|
99
194
|
topN?: number;
|
|
100
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* Declare a property as the reranking step that reorders what a retriever returned.
|
|
198
|
+
*
|
|
199
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
200
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
201
|
+
*/
|
|
101
202
|
declare function Reranker(options: RerankerOptions): PropertyDecorator;
|
|
203
|
+
/** Every `@Reranker` on a class, keyed by the property it was applied to. */
|
|
102
204
|
declare function readRerankerMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RerankerOptions>;
|
|
103
205
|
|
|
206
|
+
/** What {@link Retriever} declares: how many passages to return (`topK`) and the minimum score
|
|
207
|
+
* a passage needs to be worth returning at all (`threshold`). */
|
|
104
208
|
interface RetrieverOptions {
|
|
105
209
|
topK?: number;
|
|
106
210
|
threshold?: number;
|
|
107
211
|
}
|
|
212
|
+
/**
|
|
213
|
+
* Declare a property as the retrieval step of a RAG pipeline.
|
|
214
|
+
*
|
|
215
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
216
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
217
|
+
*/
|
|
108
218
|
declare function Retriever(options: RetrieverOptions): PropertyDecorator;
|
|
219
|
+
/** Every `@Retriever` on a class, keyed by the property it was applied to. */
|
|
109
220
|
declare function readRetrieverMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RetrieverOptions>;
|
|
110
221
|
|
|
111
222
|
/**
|
|
@@ -156,6 +267,9 @@ declare function Step(metadata?: StepMetadata): MethodDecorator;
|
|
|
156
267
|
/** Read `@Step()` metadata off a class constructor (insertion-ordered). */
|
|
157
268
|
declare function readStepMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, StepMetadata>;
|
|
158
269
|
|
|
270
|
+
/** What {@link SubAgent} declares: how the parent agent describes the delegate when deciding
|
|
271
|
+
* whether to hand work over, and optionally which model it runs on and how deep delegation may
|
|
272
|
+
* nest before it stops. */
|
|
159
273
|
interface SubAgentOptions {
|
|
160
274
|
name: string;
|
|
161
275
|
description: string;
|
|
@@ -163,48 +277,109 @@ interface SubAgentOptions {
|
|
|
163
277
|
model?: string;
|
|
164
278
|
maxDelegationDepth?: number;
|
|
165
279
|
}
|
|
280
|
+
/**
|
|
281
|
+
* Declare a property as a subagent this one may delegate to, exposed to the parent as a tool.
|
|
282
|
+
*
|
|
283
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
284
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
285
|
+
*/
|
|
166
286
|
declare function SubAgent(options: SubAgentOptions): PropertyDecorator;
|
|
287
|
+
/** Every `@SubAgent` on a class, keyed by the property it was applied to. */
|
|
167
288
|
declare function readSubAgentMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubAgentOptions>;
|
|
168
289
|
|
|
290
|
+
/** What {@link Subscription} declares: the event `name` to listen for, and optionally the
|
|
291
|
+
* `transport` it arrives on. */
|
|
169
292
|
interface SubscriptionOptions {
|
|
170
293
|
name: string;
|
|
171
294
|
transport?: string;
|
|
172
295
|
}
|
|
296
|
+
/**
|
|
297
|
+
* Declare a property as a subscription to an event stream.
|
|
298
|
+
*
|
|
299
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
300
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
301
|
+
*/
|
|
173
302
|
declare function Subscription(options: SubscriptionOptions): PropertyDecorator;
|
|
303
|
+
/** Every `@Subscription` on a class, keyed by the property it was applied to. */
|
|
174
304
|
declare function readSubscriptionMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubscriptionOptions>;
|
|
175
305
|
|
|
306
|
+
/** What {@link TextSplitter} declares: the splitting `strategy`, the target `chunkSize`, and how
|
|
307
|
+
* much `overlap` consecutive chunks share so a passage split mid-sentence is still retrievable
|
|
308
|
+
* from either side. */
|
|
176
309
|
interface TextSplitterOptions {
|
|
177
310
|
strategy?: string;
|
|
178
311
|
chunkSize?: number;
|
|
179
312
|
overlap?: number;
|
|
180
313
|
}
|
|
314
|
+
/**
|
|
315
|
+
* Declare a property as the step that breaks documents into indexable chunks.
|
|
316
|
+
*
|
|
317
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
318
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
319
|
+
*/
|
|
181
320
|
declare function TextSplitter(options: TextSplitterOptions): PropertyDecorator;
|
|
321
|
+
/** Every `@TextSplitter` on a class, keyed by the property it was applied to. */
|
|
182
322
|
declare function readTextSplitterMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, TextSplitterOptions>;
|
|
183
323
|
|
|
324
|
+
/** What {@link Tool} declares about one tool: the name and description an agent sees when
|
|
325
|
+
* choosing it, and optionally the schema its input must match. */
|
|
184
326
|
interface ToolOptions {
|
|
185
327
|
name: string;
|
|
186
328
|
description: string;
|
|
187
329
|
inputSchema?: unknown;
|
|
188
330
|
}
|
|
331
|
+
/**
|
|
332
|
+
* Declare a property as a tool an agent may call.
|
|
333
|
+
*
|
|
334
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
335
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
336
|
+
*/
|
|
189
337
|
declare function Tool(options: ToolOptions): PropertyDecorator;
|
|
338
|
+
/** Every `@Tool` on a class, keyed by the property it was applied to. Empty map when there are
|
|
339
|
+
* none — a class with no tools is ordinary, not an error. */
|
|
190
340
|
declare function readToolMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, ToolOptions>;
|
|
191
341
|
|
|
342
|
+
/** What {@link UseSandbox} declares: which `backend` isolates the execution, the `workDir` it
|
|
343
|
+
* starts in, and the `timeoutMs` after which it is abandoned. */
|
|
192
344
|
interface UseSandboxOptions {
|
|
193
345
|
backend?: "local" | "docker" | string;
|
|
194
346
|
workDir?: string;
|
|
195
347
|
timeoutMs?: number;
|
|
196
348
|
}
|
|
349
|
+
/**
|
|
350
|
+
* Declare that a property's work runs inside a sandbox rather than in this process.
|
|
351
|
+
*
|
|
352
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
353
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
354
|
+
*/
|
|
197
355
|
declare function UseSandbox(options?: UseSandboxOptions): PropertyDecorator;
|
|
356
|
+
/** Every `@UseSandbox` on a class, keyed by the property it was applied to. */
|
|
198
357
|
declare function readSandboxMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, UseSandboxOptions>;
|
|
199
358
|
|
|
359
|
+
/** What {@link Workflow} declares about a workflow class: its `name`, an optional `retryPolicy`,
|
|
360
|
+
* and the schemas its input and output are expected to match. */
|
|
200
361
|
interface WorkflowOptions {
|
|
201
362
|
name?: string;
|
|
202
363
|
retryPolicy?: unknown;
|
|
203
364
|
inputSchema?: unknown;
|
|
204
365
|
outputSchema?: unknown;
|
|
205
366
|
}
|
|
367
|
+
/**
|
|
368
|
+
* Mark a class as a workflow.
|
|
369
|
+
*
|
|
370
|
+
* This is the class-level marker only. The steps are declared with `@Step` on the methods, and
|
|
371
|
+
* `buildWorkflow` compiles the two together into a runnable `@theokit/sdk` Workflow — which makes
|
|
372
|
+
* it the one decorator in this package with a consumer that ships here.
|
|
373
|
+
*
|
|
374
|
+
* Records metadata only. Nothing in this package acts on it — the runtime that does lives in
|
|
375
|
+
* `@theokit/sdk`, which is what lets the declaration and the execution version independently.
|
|
376
|
+
*/
|
|
206
377
|
declare function Workflow(options?: WorkflowOptions): ClassDecorator;
|
|
207
|
-
|
|
378
|
+
/** The `@Workflow` of a class, or `undefined` when it has none.
|
|
379
|
+
*
|
|
380
|
+
* Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
|
|
381
|
+
* property and method decorators, which accumulate into a map. */
|
|
382
|
+
declare function readWorkflowMetadata(target: DecoratedClass): WorkflowOptions | undefined;
|
|
208
383
|
|
|
209
384
|
/**
|
|
210
385
|
* Parameter decorator — injects the REQUEST-scoped Agent into a constructor.
|
|
@@ -234,7 +409,7 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
|
|
|
234
409
|
* `@theokit/sdk` `Workflow`.
|
|
235
410
|
*
|
|
236
411
|
* This is the materializer/bridge for the decorator-driven workflow authoring
|
|
237
|
-
* surface
|
|
412
|
+
* surface. It COMPOSES the existing `Workflow` engine — it
|
|
238
413
|
* adds no orchestration logic of its own (same principle as `createSquad`).
|
|
239
414
|
* Steps are topologically ordered by their single `after` dependency into a
|
|
240
415
|
* linear `Workflow.then(...)` chain; each step's return value is threaded into
|
|
@@ -253,4 +428,4 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
|
|
|
253
428
|
*/
|
|
254
429
|
declare function buildWorkflow(instance: object): Workflow$1;
|
|
255
430
|
|
|
256
|
-
export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
|
|
431
|
+
export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, type DecoratedClass, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
|