@emabuild/ai 0.1.1 → 0.9.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 (45) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +139 -13
  3. package/dist/cli.js +45 -7
  4. package/dist/cli.js.map +1 -1
  5. package/dist/handler.d.ts +3 -2
  6. package/dist/handler.d.ts.map +1 -1
  7. package/dist/handler.js +4 -1
  8. package/dist/handler.js.map +1 -1
  9. package/dist/index.d.ts +9 -2
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +9 -2
  12. package/dist/index.js.map +1 -1
  13. package/dist/loop.d.ts +26 -0
  14. package/dist/loop.d.ts.map +1 -0
  15. package/dist/loop.js +215 -0
  16. package/dist/loop.js.map +1 -0
  17. package/dist/providers/anthropic.d.ts +58 -0
  18. package/dist/providers/anthropic.d.ts.map +1 -0
  19. package/dist/providers/anthropic.js +217 -0
  20. package/dist/providers/anthropic.js.map +1 -0
  21. package/dist/providers/errors.d.ts +12 -0
  22. package/dist/providers/errors.d.ts.map +1 -0
  23. package/dist/providers/errors.js +39 -0
  24. package/dist/providers/errors.js.map +1 -0
  25. package/dist/providers/model-call.d.ts +17 -0
  26. package/dist/providers/model-call.d.ts.map +1 -0
  27. package/dist/providers/model-call.js +117 -0
  28. package/dist/providers/model-call.js.map +1 -0
  29. package/dist/providers/openai-format.d.ts +125 -0
  30. package/dist/providers/openai-format.d.ts.map +1 -0
  31. package/dist/providers/openai-format.js +214 -0
  32. package/dist/providers/openai-format.js.map +1 -0
  33. package/dist/providers/types.d.ts +193 -0
  34. package/dist/providers/types.d.ts.map +1 -0
  35. package/dist/providers/types.js +22 -0
  36. package/dist/providers/types.js.map +1 -0
  37. package/dist/run.d.ts +40 -38
  38. package/dist/run.d.ts.map +1 -1
  39. package/dist/run.js +44 -323
  40. package/dist/run.js.map +1 -1
  41. package/dist/usage.d.ts +7 -1
  42. package/dist/usage.d.ts.map +1 -1
  43. package/dist/usage.js +35 -6
  44. package/dist/usage.js.map +1 -1
  45. package/package.json +24 -8
@@ -0,0 +1,193 @@
1
+ /**
2
+ * @module providers/types
3
+ *
4
+ * How the agent loop talks to a model. The loop owns everything about the
5
+ * editor (prompts, tools, validation, retries, events); a model is only asked
6
+ * to answer one turn of a conversation.
7
+ *
8
+ * Two ways to plug a model in:
9
+ * - `callModel(request) => response`: the simplest. The library hands out the
10
+ * system prompt, the conversation (in a neutral, OpenAI-like format) and the
11
+ * tools; your code calls any model and returns its answer.
12
+ * - a {@link ModelAdapter}: full control over streaming and the provider's own
13
+ * conversation format (the built-in Anthropic adapter is one).
14
+ */
15
+ import type { AIEffort } from '../run.js';
16
+ /** Why a model turn ended */
17
+ export type StopReason = 'end' | 'tool_calls' | 'max_tokens' | 'refusal' | 'pause';
18
+ /** Tokens of one model turn, normalized across providers */
19
+ export interface NormalizedUsage {
20
+ /** Uncached input tokens */
21
+ input: number;
22
+ output: number;
23
+ /** Input tokens read from a prompt cache */
24
+ cacheRead?: number;
25
+ /** Input tokens written to a prompt cache (5-minute TTL where the provider has TTLs) */
26
+ cacheWrite?: number;
27
+ /** Part of `cacheWrite` written with a 1-hour TTL */
28
+ cacheWrite1h?: number;
29
+ }
30
+ /** A tool, provider-neutral (JSON Schema input) */
31
+ export interface ToolSpec {
32
+ name: string;
33
+ description: string;
34
+ /** JSON Schema of the arguments (uses anyOf / const / additionalProperties: do not send it as "strict") */
35
+ inputSchema: Record<string, unknown>;
36
+ }
37
+ /** A tool call made by the model */
38
+ export interface ToolCall {
39
+ id: string;
40
+ name: string;
41
+ /** Arguments as a JSON string, exactly as the model produced them */
42
+ arguments: string;
43
+ }
44
+ /** The conversation, in a neutral format close to OpenAI Chat Completions */
45
+ export type ConversationMessage = {
46
+ role: 'user';
47
+ content: string;
48
+ } | {
49
+ role: 'assistant';
50
+ content: string;
51
+ toolCalls?: ToolCall[];
52
+ } | {
53
+ role: 'tool';
54
+ toolCallId: string;
55
+ content: string;
56
+ isError?: boolean;
57
+ };
58
+ /** What `callModel` receives: everything needed to ask any model for the next turn */
59
+ export interface ModelRequest {
60
+ /** System prompt (stable parts first: good for providers that cache prefixes) */
61
+ system: string;
62
+ messages: ConversationMessage[];
63
+ tools: ToolSpec[];
64
+ /** Output cap requested by the caller, if any */
65
+ maxTokens?: number;
66
+ /** Reasoning effort requested by the caller; map it where your model supports it */
67
+ effort: AIEffort | null;
68
+ /** Aborted when the editor cancels the run */
69
+ signal?: AbortSignal;
70
+ }
71
+ /** What `callModel` returns: the model's answer for this turn */
72
+ export interface ModelResponse {
73
+ /** Assistant text, if any (shown to the user as a message) */
74
+ text?: string;
75
+ toolCalls?: ToolCall[];
76
+ /** Why the turn ended; inferred from `toolCalls` when omitted */
77
+ stop?: StopReason;
78
+ /** Token usage, for the `usage` event and cost estimate */
79
+ usage?: NormalizedUsage;
80
+ /** Model that served the turn (for pricing); defaults to the configured model name */
81
+ model?: string;
82
+ }
83
+ /**
84
+ * A streamed answer: yield events as the model produces them. Each `toolCall`
85
+ * is applied in the editor as soon as it arrives (send it when its arguments
86
+ * are complete); `text` segments are shown as messages.
87
+ */
88
+ export type ModelStreamEvent = {
89
+ type: 'text';
90
+ text: string;
91
+ } | {
92
+ type: 'status';
93
+ text: string;
94
+ } | {
95
+ type: 'toolCall';
96
+ call: ToolCall;
97
+ } | {
98
+ type: 'usage';
99
+ usage: NormalizedUsage;
100
+ model?: string;
101
+ } | {
102
+ type: 'stop';
103
+ reason: StopReason;
104
+ };
105
+ /**
106
+ * Ask a model for the next turn; called once per turn by the agent loop.
107
+ * Return the whole answer, or a stream of {@link ModelStreamEvent}s.
108
+ */
109
+ export type ModelCall = (request: ModelRequest) => Promise<ModelResponse> | AsyncIterable<ModelStreamEvent>;
110
+ /** What a provider stream turns into */
111
+ export type AdapterEvent =
112
+ /** The complete text of one assistant text block */
113
+ {
114
+ type: 'text';
115
+ text: string;
116
+ }
117
+ /** A progress note / reasoning summary, when the provider streams them */
118
+ | {
119
+ type: 'status';
120
+ text: string;
121
+ }
122
+ /** A tool call started (its arguments are still streaming) */
123
+ | {
124
+ type: 'toolStart';
125
+ id: string;
126
+ name: string;
127
+ }
128
+ /** A complete tool call */
129
+ | {
130
+ type: 'toolCall';
131
+ call: ToolCall;
132
+ }
133
+ /** Token usage of the turn (absent when unknown), with the model that served it */
134
+ | {
135
+ type: 'usage';
136
+ model: string;
137
+ usage?: NormalizedUsage;
138
+ }
139
+ /**
140
+ * The turn ended. `toolCallIds` lists every tool call of the turn, including
141
+ * ones cut off before they completed (e.g. at max_tokens), in order.
142
+ */
143
+ | {
144
+ type: 'stop';
145
+ reason: StopReason;
146
+ toolCallIds: string[];
147
+ };
148
+ /** One block of the system prompt; `cache` marks a stable prefix worth caching */
149
+ export interface SystemPart {
150
+ text: string;
151
+ cache?: boolean;
152
+ }
153
+ /** Result of one tool call, sent back to the model */
154
+ export interface ToolResult {
155
+ id: string;
156
+ content: string;
157
+ isError?: boolean;
158
+ }
159
+ /** Per-run settings the loop hands to an adapter */
160
+ export interface TurnSettings {
161
+ system: SystemPart[];
162
+ tools: ToolSpec[];
163
+ maxTokens?: number;
164
+ effort: AIEffort | null;
165
+ signal?: AbortSignal;
166
+ }
167
+ /**
168
+ * A model provider with streaming and its own conversation format. One
169
+ * instance serves one run. The conversation object `C` is opaque to the loop.
170
+ */
171
+ export interface ModelAdapter<C = unknown> {
172
+ /** Model id, used for pricing when the provider does not report one */
173
+ readonly model: string;
174
+ /** Start a conversation with the first user message */
175
+ createConversation(userPrompt: string, settings: TurnSettings): C | Promise<C>;
176
+ /** Run one model turn and stream normalized events */
177
+ streamTurn(conversation: C, settings: TurnSettings): AsyncIterable<AdapterEvent>;
178
+ /** Append the assistant turn that was just streamed */
179
+ commitAssistantTurn(conversation: C): void;
180
+ /** Append tool results for the last assistant turn */
181
+ addToolResults(conversation: C, results: ToolResult[]): void;
182
+ /** User-facing message for a provider error, or undefined if it is not one */
183
+ describeError(error: unknown): string | undefined;
184
+ /** The error comes from the provider API: report it, do not retry */
185
+ isProviderError(error: unknown): boolean;
186
+ /** The error means the request was aborted */
187
+ isAbortError(error: unknown): boolean;
188
+ }
189
+ /** Error that must not be retried (missing SDK, bad configuration) */
190
+ export declare class ProviderSetupError extends Error {
191
+ readonly fatal = true;
192
+ }
193
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,22 @@
1
+ /**
2
+ * @module providers/types
3
+ *
4
+ * How the agent loop talks to a model. The loop owns everything about the
5
+ * editor (prompts, tools, validation, retries, events); a model is only asked
6
+ * to answer one turn of a conversation.
7
+ *
8
+ * Two ways to plug a model in:
9
+ * - `callModel(request) => response`: the simplest. The library hands out the
10
+ * system prompt, the conversation (in a neutral, OpenAI-like format) and the
11
+ * tools; your code calls any model and returns its answer.
12
+ * - a {@link ModelAdapter}: full control over streaming and the provider's own
13
+ * conversation format (the built-in Anthropic adapter is one).
14
+ */
15
+ /** Error that must not be retried (missing SDK, bad configuration) */
16
+ export class ProviderSetupError extends Error {
17
+ constructor() {
18
+ super(...arguments);
19
+ this.fatal = true;
20
+ }
21
+ }
22
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwJH,sEAAsE;AACtE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAA7C;;QACW,UAAK,GAAG,IAAI,CAAC;IACxB,CAAC;CAAA"}
package/dist/run.d.ts CHANGED
@@ -1,26 +1,43 @@
1
- import Anthropic from '@anthropic-ai/sdk';
1
+ /**
2
+ * @module run
3
+ *
4
+ * `runAI(request, options)`: turns an editor AI request into a stream of
5
+ * editor events. The flow (prompts, tools, validation, retries) lives in
6
+ * `loop.ts`; the model answering each turn is, in order of precedence:
7
+ *
8
+ * 1. `options.adapter` — a full {@link ModelAdapter};
9
+ * 2. `options.callModel` — your function: it gets the prompt, conversation and
10
+ * tools, calls any model, and returns the answer;
11
+ * 3. the built-in Claude adapter (default; needs `@anthropic-ai/sdk`).
12
+ */
13
+ import type Anthropic from '@anthropic-ai/sdk';
2
14
  import type { AIRequest, AIStreamEvent, FreeImage, FreeImageSearchOptions } from '@emabuild/types';
3
15
  import { type ModelPricing } from './usage.js';
4
- type StreamParams = Anthropic.Beta.Messages.MessageCreateParamsStreaming;
5
- /** Request parameters shared by every turn of a run (everything except `messages`) */
6
- export type RequestParams = Omit<StreamParams, 'messages' | 'stream'>;
7
- /** Default model: Claude Opus 5.5 (the current Opus) */
8
- export declare const DEFAULT_MODEL = "claude-opus-5-5";
9
- /** Default per-response output cap (streamed, so large values are safe) */
10
- export declare const DEFAULT_MAX_TOKENS = 64000;
16
+ import type { ModelAdapter, ModelCall } from './providers/types.js';
17
+ export { buildRequestParams, DEFAULT_MODEL, DEFAULT_MAX_TOKENS, type RequestParams } from './providers/anthropic.js';
11
18
  /** Default cap on model round-trips per run */
12
19
  export declare const DEFAULT_MAX_TURNS = 30;
13
- /** Effort levels accepted by `output_config.effort` */
20
+ /** Effort levels (Claude `output_config.effort`; map them for other models in `callModel`) */
14
21
  export type AIEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
15
22
  /** Options for {@link runAI} */
16
23
  export interface RunAIOptions {
17
- /** Pre-configured Anthropic client (takes precedence over `apiKey`) */
24
+ /**
25
+ * Answer each model turn with your own code (any provider: OpenAI, Azure,
26
+ * Cerebras, a local model…). The library keeps the flow; you only call the model.
27
+ */
28
+ callModel?: ModelCall;
29
+ /** Full adapter with streaming (takes precedence over `callModel`) */
30
+ adapter?: ModelAdapter;
31
+ /** Pre-configured Anthropic client (built-in Claude adapter; takes precedence over `apiKey`) */
18
32
  client?: Anthropic;
19
- /** API key; defaults to the SDK's credential resolution (ANTHROPIC_API_KEY, profiles…) */
33
+ /** API key of the built-in Claude adapter; defaults to the SDK's credential resolution */
20
34
  apiKey?: string;
21
- /** Model id (default {@link DEFAULT_MODEL}) */
35
+ /**
36
+ * Model id. Built-in adapter: the Claude model (default {@link DEFAULT_MODEL}).
37
+ * With `callModel`: the name used for pricing when the response does not report one.
38
+ */
22
39
  model?: string;
23
- /** Max output tokens per model response (default {@link DEFAULT_MAX_TOKENS}) */
40
+ /** Max output tokens per model turn (built-in adapter default: DEFAULT_MAX_TOKENS) */
24
41
  maxTokens?: number;
25
42
  /** Aborts the run and the in-flight model request */
26
43
  signal?: AbortSignal;
@@ -29,48 +46,33 @@ export interface RunAIOptions {
29
46
  /** Max model round-trips (default {@link DEFAULT_MAX_TURNS}) */
30
47
  maxTurns?: number;
31
48
  /**
32
- * `output_config.effort` (default "medium"). Pass `null` to omit it, e.g. for
33
- * models that do not support effort.
49
+ * Reasoning effort (default "medium"). Claude: `output_config.effort`; with
50
+ * `callModel` it is passed on for you to map. `null` omits it.
34
51
  */
35
52
  effort?: AIEffort | null;
36
- /**
37
- * Server-side refusal fallbacks (`fallbacks: "default"`). Defaults to true on
38
- * models that support it on the Claude API; set false on Bedrock/Vertex/Foundry
39
- * or behind proxies that reject beta parameters.
40
- */
53
+ /** Claude only: server-side refusal fallbacks; on by default for supported models */
41
54
  fallbacks?: boolean;
42
- /**
43
- * Request progress-update thinking blocks (`thinking.display: "updates"`) and
44
- * forward them as `status` events. Defaults to true on models that support it.
45
- */
55
+ /** Claude only: progress-update thinking blocks as `status` events; on by default for supported models */
46
56
  progressUpdates?: boolean;
47
57
  /**
48
58
  * Free-image search behind the `search_images` tool. Defaults to Openverse
49
- * (CC0 / public domain); pass a custom search, or `false` to disable the tool.
59
+ * (CC0 / public domain) with Wikimedia Commons as the fallback; pass a custom
60
+ * search, or `false` to disable the tool.
50
61
  */
51
62
  imageSearch?: ((query: string, options: FreeImageSearchOptions) => Promise<FreeImage[]>) | false;
52
- /**
53
- * Send a `usage` event (tokens + estimated cost) before `done` / `error`.
54
- * Default true; set false to keep usage server side.
55
- */
63
+ /** Send a `usage` event (tokens + estimated cost) before `done` / `error`. Default true */
56
64
  reportUsage?: boolean;
57
- /** Prices (USD / 1M tokens) merged over the built-in Claude API list prices, keyed by model id */
65
+ /** Prices (USD / 1M tokens) merged over the built-in list prices, keyed by model id */
58
66
  pricing?: Record<string, ModelPricing>;
59
67
  }
60
68
  /**
61
- * Builds the static request parameters for a run. Exported for testing and for
62
- * callers that want to inspect what is sent.
63
- */
64
- export declare function buildRequestParams(request: AIRequest, options?: RunAIOptions): RequestParams;
65
- /**
66
- * Runs an AI request against Claude and streams editor events.
69
+ * Runs an AI request and streams editor events.
67
70
  *
68
71
  * The model edits the design through an `apply_operations` tool; each
69
72
  * completed tool call is validated and yielded immediately as an
70
73
  * `operations` event, so the editor can apply it live. Invalid batches are
71
74
  * returned to the model as error tool results so it can fix them. The
72
- * generator never throws for API errors — it yields an `error` event instead.
75
+ * generator never throws for model errors — it yields an `error` event instead.
73
76
  */
74
77
  export declare function runAI(request: AIRequest, options?: RunAIOptions): AsyncGenerator<AIStreamEvent>;
75
- export {};
76
78
  //# sourceMappingURL=run.d.ts.map
package/dist/run.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAmB,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAKpH,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAI1E,KAAK,YAAY,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,4BAA4B,CAAC;AACzE,sFAAsF;AACtF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;AAEtE,wDAAwD;AACxD,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAC/C,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,uDAAuD;AACvD,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAEnE,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;IACjG;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kGAAkG;IAClG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAOD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,EAClB,OAAO,GAAE,YAAiB,GACzB,aAAa,CAiCf;AAoBD;;;;;;;;GAQG;AACH,wBAAuB,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,GAAE,YAAiB,GAAG,cAAc,CAAC,aAAa,CAAC,CAS1G"}
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEnG,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAI1E,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAgB,MAAM,sBAAsB,CAAC;AAElF,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAErH,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,8FAA8F;AAC9F,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAEnE,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,sEAAsE;IACtE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,gGAAgG;IAChG,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzB,qFAAqF;IACrF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0GAA0G;IAC1G,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;IACjG,2FAA2F;IAC3F,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AASD;;;;;;;;GAQG;AACH,wBAAuB,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,GAAE,YAAiB,GAAG,cAAc,CAAC,aAAa,CAAC,CAU1G"}