@deepagents/context 0.10.2 → 0.11.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.
Files changed (42) hide show
  1. package/README.md +114 -119
  2. package/dist/example-error-recovery.d.ts +2 -0
  3. package/dist/example-error-recovery.d.ts.map +1 -0
  4. package/dist/index.d.ts +16 -388
  5. package/dist/index.d.ts.map +1 -1
  6. package/dist/index.js +2391 -1062
  7. package/dist/index.js.map +4 -4
  8. package/dist/lib/agent.d.ts +86 -12
  9. package/dist/lib/agent.d.ts.map +1 -1
  10. package/dist/lib/engine.d.ts +323 -0
  11. package/dist/lib/engine.d.ts.map +1 -0
  12. package/dist/lib/estimate.d.ts +1 -1
  13. package/dist/lib/estimate.d.ts.map +1 -1
  14. package/dist/lib/fragments/domain.d.ts +440 -0
  15. package/dist/lib/fragments/domain.d.ts.map +1 -0
  16. package/dist/lib/fragments/user.d.ts +122 -0
  17. package/dist/lib/fragments/user.d.ts.map +1 -0
  18. package/dist/lib/fragments.d.ts +107 -0
  19. package/dist/lib/fragments.d.ts.map +1 -0
  20. package/dist/lib/guardrail.d.ts +138 -0
  21. package/dist/lib/guardrail.d.ts.map +1 -0
  22. package/dist/lib/renderers/abstract.renderer.d.ts +1 -1
  23. package/dist/lib/renderers/abstract.renderer.d.ts.map +1 -1
  24. package/dist/lib/sandbox/binary-bridges.d.ts +31 -0
  25. package/dist/lib/sandbox/binary-bridges.d.ts.map +1 -0
  26. package/dist/lib/sandbox/container-tool.d.ts +134 -0
  27. package/dist/lib/sandbox/container-tool.d.ts.map +1 -0
  28. package/dist/lib/sandbox/docker-sandbox.d.ts +471 -0
  29. package/dist/lib/sandbox/docker-sandbox.d.ts.map +1 -0
  30. package/dist/lib/sandbox/index.d.ts +4 -0
  31. package/dist/lib/sandbox/index.d.ts.map +1 -0
  32. package/dist/lib/skills/fragments.d.ts +24 -0
  33. package/dist/lib/skills/fragments.d.ts.map +1 -0
  34. package/dist/lib/skills/index.d.ts +31 -0
  35. package/dist/lib/skills/index.d.ts.map +1 -0
  36. package/dist/lib/skills/loader.d.ts +28 -0
  37. package/dist/lib/skills/loader.d.ts.map +1 -0
  38. package/dist/lib/skills/types.d.ts +40 -0
  39. package/dist/lib/skills/types.d.ts.map +1 -0
  40. package/package.json +7 -3
  41. package/dist/lib/context.d.ts +0 -56
  42. package/dist/lib/context.d.ts.map +0 -1
@@ -1,28 +1,102 @@
1
- import { type StreamTextTransform, type ToolChoice, type ToolSet, generateText } from 'ai';
1
+ import { type StreamTextResult, type StreamTextTransform, type ToolChoice, type ToolSet, generateText } from 'ai';
2
2
  import z from 'zod';
3
3
  import { type AgentModel } from '@deepagents/agent';
4
4
  import { type ContextEngine } from '../index.ts';
5
- export interface CreateAgent<COut, CIn = COut, Output = never> {
5
+ import { type Guardrail } from './guardrail.ts';
6
+ export interface CreateAgent<CIn, COut = CIn> {
6
7
  name: string;
7
- context: ContextEngine;
8
+ context?: ContextEngine;
8
9
  tools?: ToolSet;
9
- model: AgentModel;
10
+ model?: AgentModel;
10
11
  toolChoice?: ToolChoice<Record<string, COut>>;
11
- output?: z.Schema<Output>;
12
12
  providerOptions?: Parameters<typeof generateText>[0]['providerOptions'];
13
13
  logging?: boolean;
14
+ /**
15
+ * Guardrails to apply during streaming.
16
+ * Each guardrail inspects text chunks and can trigger self-correction retries.
17
+ */
18
+ guardrails?: Guardrail[];
19
+ /**
20
+ * Maximum number of retry attempts when guardrails fail (default: 3).
21
+ */
22
+ maxGuardrailRetries?: number;
14
23
  }
15
- declare class Agent<COut, CIn = COut, Output = never> {
24
+ declare class Agent<CIn, COut = CIn> {
16
25
  #private;
17
- constructor(options: CreateAgent<COut, CIn, Output>);
18
- generate<COut, CIn = COut, Output = never>(contextVariables: CIn, config?: {
26
+ readonly tools: ToolSet;
27
+ constructor(options: CreateAgent<CIn, COut>);
28
+ generate<COut, CIn = COut>(contextVariables: CIn, config?: {
19
29
  abortSignal?: AbortSignal;
20
- }): Promise<import("ai").GenerateTextResult<ToolSet, Output_1>>;
21
- stream<COut, CIn = COut, Output = never>(contextVariables: CIn, config?: {
30
+ }): Promise<import("ai").GenerateTextResult<ToolSet, never>>;
31
+ /**
32
+ * Stream a response from the agent.
33
+ *
34
+ * When guardrails are configured, `toUIMessageStream()` is wrapped to provide
35
+ * self-correction behavior. Direct access to fullStream/textStream bypasses guardrails.
36
+ *
37
+ * @example
38
+ * ```typescript
39
+ * const stream = await agent.stream({});
40
+ *
41
+ * // With guardrails - use toUIMessageStream for protection
42
+ * await printer.readableStream(stream.toUIMessageStream());
43
+ *
44
+ * // Or use printer.stdout which uses toUIMessageStream internally
45
+ * await printer.stdout(stream);
46
+ * ```
47
+ */
48
+ stream<COut, CIn = COut>(contextVariables: CIn, config?: {
22
49
  abortSignal?: AbortSignal;
23
50
  transform?: StreamTextTransform<ToolSet> | StreamTextTransform<ToolSet>[];
24
- }): Promise<import("ai").StreamTextResult<ToolSet, import("ai").DeepPartial<Output_1>>>;
51
+ maxRetries?: number;
52
+ }): Promise<StreamTextResult<ToolSet, never>>;
53
+ clone(overrides?: Partial<CreateAgent<CIn, COut>>): Agent<CIn, COut>;
25
54
  }
26
- export declare function agent<Output, CIn, COut = CIn>(options: CreateAgent<COut, CIn, Output>): Agent<COut, CIn, Output>;
55
+ export declare function agent<CIn, COut = CIn>(options: CreateAgent<CIn, COut>): Agent<CIn, COut>;
56
+ /**
57
+ * Options for creating a structured output handler.
58
+ */
59
+ export interface StructuredOutputOptions<TSchema extends z.ZodType> {
60
+ name: string;
61
+ context?: ContextEngine;
62
+ model?: AgentModel;
63
+ schema: TSchema;
64
+ providerOptions?: Parameters<typeof generateText>[0]['providerOptions'];
65
+ }
66
+ /**
67
+ * Create a structured output handler that provides simplified access to structured output.
68
+ *
69
+ * @param options - Configuration options including schema
70
+ * @returns Object with generate() and stream() methods
71
+ *
72
+ * @example
73
+ * ```typescript
74
+ * const output = structuredOutput({
75
+ * name: 'extractor',
76
+ * model: groq('...'),
77
+ * context,
78
+ * schema: z.object({
79
+ * name: z.string(),
80
+ * age: z.number(),
81
+ * }),
82
+ * });
83
+ *
84
+ * // Generate - returns only the structured output
85
+ * const result = await output.generate({});
86
+ * // result: { name: string, age: number }
87
+ *
88
+ * // Stream - returns the full stream
89
+ * const stream = await output.stream({});
90
+ * ```
91
+ */
92
+ export declare function structuredOutput<TSchema extends z.ZodType>(options: StructuredOutputOptions<TSchema>): {
93
+ generate<CIn>(contextVariables?: CIn, config?: {
94
+ abortSignal?: AbortSignal;
95
+ }): Promise<z.infer<TSchema>>;
96
+ stream<CIn>(contextVariables?: CIn, config?: {
97
+ abortSignal?: AbortSignal;
98
+ transform?: StreamTextTransform<ToolSet> | StreamTextTransform<ToolSet>[];
99
+ }): Promise<StreamTextResult<ToolSet, unknown>>;
100
+ };
27
101
  export {};
28
102
  //# sourceMappingURL=agent.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/lib/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,OAAO,EAGZ,YAAY,EAIb,MAAM,IAAI,CAAC;AAEZ,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,KAAK,aAAa,EAAe,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,MAAM,GAAG,KAAK;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1B,eAAe,CAAC,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,cAAM,KAAK,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,MAAM,GAAG,KAAK;;gBAE9B,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC;IAItC,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,MAAM,GAAG,KAAK,EACpD,gBAAgB,EAAE,GAAG,EACrB,MAAM,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,WAAW,CAAC;KAC3B;IAiCU,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,MAAM,GAAG,KAAK,EAClD,gBAAgB,EAAE,GAAG,EACrB,MAAM,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,SAAS,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;KAC3E;CAsEJ;AAED,wBAAgB,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,EAC3C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,GACtC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAE1B"}
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/lib/agent.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,323 @@
1
+ import { type EstimateResult } from './estimate.ts';
2
+ import type { ContextFragment } from './fragments.ts';
3
+ import type { Models } from './models.generated.ts';
4
+ import { type ContextRenderer } from './renderers/abstract.renderer.ts';
5
+ import { type BranchInfo, type CheckpointInfo, ContextStore, type GraphData, type MessageData } from './store/store.ts';
6
+ /**
7
+ * Result of resolving context - ready for AI SDK consumption.
8
+ */
9
+ export interface ResolveResult {
10
+ /** Rendered non-message fragments for system prompt */
11
+ systemPrompt: string;
12
+ /** Message fragments decoded to AI SDK format */
13
+ messages: unknown[];
14
+ }
15
+ /**
16
+ * Options for resolve().
17
+ */
18
+ export interface ResolveOptions {
19
+ /** Renderer to use for system prompt (defaults to XmlRenderer) */
20
+ renderer: ContextRenderer;
21
+ }
22
+ /**
23
+ * Options for creating a ContextEngine.
24
+ */
25
+ export interface ContextEngineOptions {
26
+ /** Store for persisting fragments (required) */
27
+ store: ContextStore;
28
+ /** Unique identifier for this chat (required) */
29
+ chatId: string;
30
+ /** Branch name (defaults to 'main') */
31
+ branch?: string;
32
+ }
33
+ /**
34
+ * Metadata about a chat.
35
+ */
36
+ export interface ChatMeta {
37
+ /** Unique chat identifier */
38
+ id: string;
39
+ /** When the chat was created */
40
+ createdAt: number;
41
+ /** When the chat was last updated */
42
+ updatedAt: number;
43
+ /** Optional user-provided title */
44
+ title?: string;
45
+ /** Optional custom metadata */
46
+ metadata?: Record<string, unknown>;
47
+ }
48
+ /**
49
+ * Options for context inspection.
50
+ */
51
+ export interface InspectOptions {
52
+ /** Model ID for cost estimation (required) */
53
+ modelId: Models;
54
+ /** Renderer for estimation (required) */
55
+ renderer: ContextRenderer;
56
+ }
57
+ /**
58
+ * Result of inspecting context state.
59
+ * Provides a comprehensive JSON-serializable snapshot for debugging.
60
+ */
61
+ export interface InspectResult {
62
+ /** Token usage and cost estimation */
63
+ estimate: EstimateResult;
64
+ /** Rendered output using the provided renderer */
65
+ rendered: string;
66
+ /** Fragment structure breakdown */
67
+ fragments: {
68
+ /** Non-message fragments (role, hints, etc.) */
69
+ context: ContextFragment[];
70
+ /** Pending messages not yet saved to store */
71
+ pending: ContextFragment[];
72
+ /** Persisted messages from the store */
73
+ persisted: MessageData[];
74
+ };
75
+ /** Conversation graph with branches and checkpoints */
76
+ graph: GraphData;
77
+ /** Inspection metadata */
78
+ meta: {
79
+ chatId: string;
80
+ branch: string;
81
+ timestamp: number;
82
+ };
83
+ }
84
+ /**
85
+ * Context engine for managing AI conversation context with graph-based storage.
86
+ *
87
+ * The engine uses a DAG (Directed Acyclic Graph) model for messages:
88
+ * - Messages are immutable nodes with parentId forming the graph
89
+ * - Branches are pointers to head (tip) messages
90
+ * - Checkpoints are pointers to specific messages
91
+ * - History is preserved through branching (rewind creates new branch)
92
+ */
93
+ export declare class ContextEngine {
94
+ #private;
95
+ constructor(options: ContextEngineOptions);
96
+ /**
97
+ * Get the current chat ID.
98
+ */
99
+ get chatId(): string;
100
+ /**
101
+ * Get the current branch name.
102
+ */
103
+ get branch(): string;
104
+ /**
105
+ * Get metadata for the current chat.
106
+ * Returns null if the chat hasn't been initialized yet.
107
+ */
108
+ get chat(): ChatMeta | null;
109
+ /**
110
+ * Add fragments to the context.
111
+ *
112
+ * - Message fragments (user/assistant) are queued for persistence
113
+ * - Non-message fragments (role/hint) are kept in memory for system prompt
114
+ */
115
+ set(...fragments: ContextFragment[]): this;
116
+ unset(fragmentId: string): void;
117
+ /**
118
+ * Render all fragments using the provided renderer.
119
+ * @internal Use resolve() instead for public API.
120
+ */
121
+ render(renderer: ContextRenderer): string;
122
+ /**
123
+ * Resolve context into AI SDK-ready format.
124
+ *
125
+ * - Initializes chat and branch if needed
126
+ * - Loads message history from the graph (walking parent chain)
127
+ * - Separates context fragments for system prompt
128
+ * - Combines with pending messages
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * const context = new ContextEngine({ store, chatId: 'chat-1' })
133
+ * .set(role('You are helpful'), user('Hello'));
134
+ *
135
+ * const { systemPrompt, messages } = await context.resolve();
136
+ * await generateText({ system: systemPrompt, messages });
137
+ * ```
138
+ */
139
+ resolve(options: ResolveOptions): Promise<ResolveResult>;
140
+ /**
141
+ * Save pending messages to the graph.
142
+ *
143
+ * Each message is added as a node with parentId pointing to the previous message.
144
+ * The branch head is updated to point to the last message.
145
+ *
146
+ * @example
147
+ * ```ts
148
+ * context.set(user('Hello'));
149
+ * // AI responds...
150
+ * context.set(assistant('Hi there!'));
151
+ * await context.save(); // Persist to graph
152
+ * ```
153
+ */
154
+ save(): Promise<void>;
155
+ /**
156
+ * Estimate token count and cost for the full context.
157
+ *
158
+ * Includes:
159
+ * - System prompt fragments (role, hints, etc.)
160
+ * - Persisted chat messages (from store)
161
+ * - Pending messages (not yet saved)
162
+ *
163
+ * @param modelId - Model ID (e.g., "openai:gpt-4o", "anthropic:claude-3-5-sonnet")
164
+ * @param options - Optional settings
165
+ * @returns Estimate result with token counts, costs, and per-fragment breakdown
166
+ */
167
+ estimate(modelId: Models, options?: {
168
+ renderer?: ContextRenderer;
169
+ }): Promise<EstimateResult>;
170
+ /**
171
+ * Rewind to a specific message by ID.
172
+ *
173
+ * Creates a new branch from that message, preserving the original branch.
174
+ * The new branch becomes active.
175
+ *
176
+ * @param messageId - The message ID to rewind to
177
+ * @returns The new branch info
178
+ *
179
+ * @example
180
+ * ```ts
181
+ * context.set(user('What is 2 + 2?', { id: 'q1' }));
182
+ * context.set(assistant('The answer is 5.', { id: 'wrong' })); // Oops!
183
+ * await context.save();
184
+ *
185
+ * // Rewind to the question, creates new branch
186
+ * const newBranch = await context.rewind('q1');
187
+ *
188
+ * // Now add correct answer on new branch
189
+ * context.set(assistant('The answer is 4.'));
190
+ * await context.save();
191
+ * ```
192
+ */
193
+ rewind(messageId: string): Promise<BranchInfo>;
194
+ /**
195
+ * Create a checkpoint at the current position.
196
+ *
197
+ * A checkpoint is a named pointer to the current branch head.
198
+ * Use restore() to return to this point later.
199
+ *
200
+ * @param name - Name for the checkpoint
201
+ * @returns The checkpoint info
202
+ *
203
+ * @example
204
+ * ```ts
205
+ * context.set(user('I want to learn a new skill.'));
206
+ * context.set(assistant('Would you like coding or cooking?'));
207
+ * await context.save();
208
+ *
209
+ * // Save checkpoint before user's choice
210
+ * const cp = await context.checkpoint('before-choice');
211
+ * ```
212
+ */
213
+ checkpoint(name: string): Promise<CheckpointInfo>;
214
+ /**
215
+ * Restore to a checkpoint by creating a new branch from that point.
216
+ *
217
+ * @param name - Name of the checkpoint to restore
218
+ * @returns The new branch info
219
+ *
220
+ * @example
221
+ * ```ts
222
+ * // User chose cooking, but wants to try coding path
223
+ * await context.restore('before-choice');
224
+ *
225
+ * context.set(user('I want to learn coding.'));
226
+ * context.set(assistant('Python is a great starting language!'));
227
+ * await context.save();
228
+ * ```
229
+ */
230
+ restore(name: string): Promise<BranchInfo>;
231
+ /**
232
+ * Switch to a different branch by name.
233
+ *
234
+ * @param name - Branch name to switch to
235
+ *
236
+ * @example
237
+ * ```ts
238
+ * // List branches (via store)
239
+ * const branches = await store.listBranches(context.chatId);
240
+ * console.log(branches); // [{name: 'main', ...}, {name: 'main-v2', ...}]
241
+ *
242
+ * // Switch to original branch
243
+ * await context.switchBranch('main');
244
+ * ```
245
+ */
246
+ switchBranch(name: string): Promise<void>;
247
+ /**
248
+ * Create a parallel branch from the current position ("by the way").
249
+ *
250
+ * Use this when you want to fork the conversation without leaving
251
+ * the current branch. Common use case: user wants to ask another
252
+ * question while waiting for the model to respond.
253
+ *
254
+ * Unlike rewind(), this method:
255
+ * - Uses the current HEAD (no messageId needed)
256
+ * - Does NOT switch to the new branch
257
+ * - Keeps pending messages intact
258
+ *
259
+ * @returns The new branch info (does not switch to it)
260
+ * @throws Error if no messages exist in the conversation
261
+ *
262
+ * @example
263
+ * ```ts
264
+ * // User asked a question, model is generating...
265
+ * context.set(user('What is the weather?'));
266
+ * await context.save();
267
+ *
268
+ * // User wants to ask something else without waiting
269
+ * const newBranch = await context.btw();
270
+ * // newBranch = { name: 'main-v2', ... }
271
+ *
272
+ * // Later, switch to the new branch and add the question
273
+ * await context.switchBranch(newBranch.name);
274
+ * context.set(user('Also, what time is it?'));
275
+ * await context.save();
276
+ * ```
277
+ */
278
+ btw(): Promise<BranchInfo>;
279
+ /**
280
+ * Update metadata for the current chat.
281
+ *
282
+ * @param updates - Partial metadata to merge (title, metadata)
283
+ *
284
+ * @example
285
+ * ```ts
286
+ * await context.updateChat({
287
+ * title: 'Coding Help Session',
288
+ * metadata: { tags: ['python', 'debugging'] }
289
+ * });
290
+ * ```
291
+ */
292
+ updateChat(updates: Partial<Pick<ChatMeta, 'title' | 'metadata'>>): Promise<void>;
293
+ /**
294
+ * Consolidate context fragments (no-op for now).
295
+ *
296
+ * This is a placeholder for future functionality that merges context fragments
297
+ * using specific rules. Currently, it does nothing.
298
+ *
299
+ * @experimental
300
+ */
301
+ consolidate(): void;
302
+ /**
303
+ * Inspect the full context state for debugging.
304
+ * Returns a comprehensive JSON-serializable object with all context information.
305
+ *
306
+ * @param options - Inspection options (modelId and renderer required)
307
+ * @returns Complete inspection data including estimates, rendered output, fragments, and graph
308
+ *
309
+ * @example
310
+ * ```ts
311
+ * const inspection = await context.inspect({
312
+ * modelId: 'openai:gpt-4o',
313
+ * renderer: new XmlRenderer(),
314
+ * });
315
+ * console.log(JSON.stringify(inspection, null, 2));
316
+ *
317
+ * // Or write to file for analysis
318
+ * await fs.writeFile('context-debug.json', JSON.stringify(inspection, null, 2));
319
+ * ```
320
+ */
321
+ inspect(options: InspectOptions): Promise<InspectResult>;
322
+ }
323
+ //# sourceMappingURL=engine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/lib/engine.ts"],"names":[],"mappings":"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"}
@@ -1,4 +1,4 @@
1
- import type { ContextFragment } from './context.ts';
1
+ import type { ContextFragment } from './fragments.ts';
2
2
  import type { Models } from './models.generated.ts';
3
3
  import type { ContextRenderer } from './renderers/abstract.renderer.ts';
4
4
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"estimate.d.ts","sourceRoot":"","sources":["../../src/lib/estimate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAO9B,CAAC;AAoBF;;;GAGG;AACH,qBAAa,cAAc;;IAMzB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B3B;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI3C;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAI7D;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAI/C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAWxC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc;CAyBzD;AAKD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,EACzB,GAAG,SAAS,EAAE,eAAe,EAAE,GAC9B,OAAO,CAAC,cAAc,CAAC,CA0CzB"}
1
+ {"version":3,"file":"estimate.d.ts","sourceRoot":"","sources":["../../src/lib/estimate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAO9B,CAAC;AAoBF;;;GAGG;AACH,qBAAa,cAAc;;IAMzB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B3B;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI3C;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAI7D;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAI/C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAWxC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc;CAyBzD;AAKD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,EACzB,GAAG,SAAS,EAAE,eAAe,EAAE,GAC9B,OAAO,CAAC,cAAc,CAAC,CA0CzB"}