@framers/agentos 0.1.69 → 0.1.71

package/dist/orchestration/builders/AgentGraph.js

@@ -0,0 +1,338 @@
+/**
+ * @file AgentGraph.ts
+ * @description Fluent builder for constructing compiled agent execution graphs.
+ *
+ * `AgentGraph` provides a type-safe, chainable API for declaring nodes and edges —
+ * including static, conditional, discovery-based, and personality-driven routing —
+ * and then compiling the resulting graph into a `CompiledExecutionGraph` IR object
+ * that the `GraphRuntime` can execute.
+ *
+ * ```
+ * AgentGraph (builder)
+ *   → GraphCompiler.compile()  → CompiledExecutionGraph (IR)
+ *   → GraphValidator.validate() → validation gate
+ *   → CompiledAgentGraph        → GraphRuntime.invoke() / stream() / resume()
+ * ```
+ *
+ * Typical usage:
+ * ```ts
+ * const graph = new AgentGraph({ input: z.object({ topic: z.string() }), ... })
+ *   .addNode('search', toolNode('web_search'))
+ *   .addEdge(START, 'search')
+ *   .addEdge('search', END)
+ *   .compile();
+ *
+ * const result = await graph.invoke({ topic: 'AgentOS' });
+ * ```
+ */
+import { START, END } from '../ir/types.js';
+import { InMemoryCheckpointStore } from '../checkpoint/InMemoryCheckpointStore.js';
+import { GraphCompiler } from '../compiler/GraphCompiler.js';
+import { GraphValidator } from '../compiler/Validator.js';
+import { GraphRuntime } from '../runtime/GraphRuntime.js';
+import { NodeExecutor } from '../runtime/NodeExecutor.js';
+// Re-export sentinels so callers can import them from this module without reaching into ir/.
+export { START, END };
+// ---------------------------------------------------------------------------
+// AgentGraph (builder)
+// ---------------------------------------------------------------------------
+/**
+ * Fluent builder for agent execution graphs.
+ *
+ * Each mutating method returns `this` to support method chaining.  All state is held
+ * in private Maps/arrays; nothing is compiled or validated until `.compile()` is called.
+ *
+ * @template TState - Narrows the `GraphState` type used in conditional-edge callbacks.
+ *   Defaults to the base `GraphState` when not specified.
+ */
+export class AgentGraph {
+    /**
+     * @param stateSchema - Zod schemas for the three `GraphState` generic partitions.
+     *   - `input`     — shape of the frozen user-provided input passed to `invoke()`.
+     *   - `scratch`   — shape of the mutable node-to-node communication bag.
+     *   - `artifacts` — shape of the accumulated external outputs returned by `invoke()`.
+     * @param config - Optional graph-wide configuration overrides.
+     */
+    constructor(stateSchema, config) {
+        this.stateSchema = stateSchema;
+        this.config = config;
+        /** All user-declared nodes, keyed by their assigned id. */
+        this.nodes = new Map();
+        /** All directed edges declared via `addEdge`, `addConditionalEdge`, etc. */
+        this.edges = [];
+        /** Monotonically increasing counter used to generate unique edge ids. */
+        this.edgeCounter = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Node declaration
+    // ---------------------------------------------------------------------------
+    /**
+     * Add a node to the graph.
+     *
+     * The node's `id` field is overridden with the supplied `id` argument so the
+     * user-declared identifier is always canonical.
+     *
+     * @param id   - Unique node identifier within this graph.  Must not equal `START` or `END`.
+     * @param node - A `GraphNode` produced by one of the factory helpers in `builders/nodes.ts`.
+     * @returns `this` for chaining.
+     * @throws {Error} When `id` has already been registered.
+     */
+    addNode(id, node) {
+        if (this.nodes.has(id)) {
+            throw new Error(`Duplicate node ID: "${id}" — each node must have a unique identifier`);
+        }
+        // Override the factory-generated id with the user-supplied one.
+        node.id = id;
+        this.nodes.set(id, node);
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    // Edge declaration
+    // ---------------------------------------------------------------------------
+    /**
+     * Add an unconditional (static) edge that is always followed at runtime.
+     *
+     * Either `source` or `target` (or both) may be the `START` / `END` sentinels.
+     *
+     * @param source - Source node id (or `START`).
+     * @param target - Target node id (or `END`).
+     * @returns `this` for chaining.
+     */
+    addEdge(source, target) {
+        this.edges.push({
+            id: `edge-${++this.edgeCounter}`,
+            source,
+            target,
+            type: 'static',
+        });
+        return this;
+    }
+    /**
+     * Add a conditional edge whose target is determined at runtime by a callback.
+     *
+     * The `condition` function receives the current `GraphState` and returns the id of
+     * the next node to activate.  The returned id is resolved against the edge list at
+     * runtime; no compile-time validation of the returned id is performed.
+     *
+     * Because conditional edges encode the target resolution in a closure, the `target`
+     * field stored in the IR is set to the placeholder `'__CONDITIONAL__'`.
+     *
+     * @param source    - Source node id (or `START`).
+     * @param condition - Pure function `(state: TState) => string` returning the next node id.
+     * @returns `this` for chaining.
+     */
+    addConditionalEdge(source, condition) {
+        this.edges.push({
+            id: `edge-${++this.edgeCounter}`,
+            source,
+            // Placeholder target — the actual target is resolved by the condition function at runtime.
+            target: '__CONDITIONAL__',
+            type: 'conditional',
+            condition: {
+                type: 'function',
+                // Cast: the condition function accepts TState but the IR stores GraphState.
+                fn: condition,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a discovery edge whose target is resolved at runtime via the capability discovery engine.
+     *
+     * When discovery returns no result, execution falls back to `config.fallbackTarget` (if provided)
+     * or the placeholder `'__DISCOVERY__'`.
+     *
+     * @param source - Source node id.
+     * @param config - Discovery configuration.
+     * @param config.query          - Semantic search query forwarded to `CapabilityDiscoveryEngine`.
+     * @param config.kind           - Optional filter: restrict discovery to a specific capability kind.
+     * @param config.fallbackTarget - Node id to route to when discovery resolves no target.
+     * @returns `this` for chaining.
+     */
+    addDiscoveryEdge(source, config) {
+        this.edges.push({
+            id: `edge-${++this.edgeCounter}`,
+            source,
+            // Default target: the fallback when provided, otherwise a sentinel.
+            target: config.fallbackTarget ?? '__DISCOVERY__',
+            type: 'discovery',
+            discoveryQuery: config.query,
+            discoveryKind: config.kind,
+            discoveryFallback: config.fallbackTarget,
+        });
+        return this;
+    }
+    /**
+     * Add a personality edge whose target is chosen based on the agent's current trait value.
+     *
+     * At runtime the engine reads `config.trait` from the agent's HEXACO/PAD state and routes
+     * to `config.above` when the value is ≥ `config.threshold`, or `config.below` otherwise.
+     *
+     * @param source - Source node id.
+     * @param config - Personality routing configuration.
+     * @param config.trait     - HEXACO/PAD trait name to inspect (e.g. `'conscientiousness'`).
+     * @param config.threshold - Decision boundary (0–1).
+     * @param config.above     - Target node id when trait value ≥ threshold.
+     * @param config.below     - Target node id when trait value < threshold.
+     * @returns `this` for chaining.
+     */
+    addPersonalityEdge(source, config) {
+        // Emit two edges — one per branch — so the reachability checker can see both targets.
+        // The runtime selects between them by evaluating `personalityCondition` at execution time.
+        const baseId = ++this.edgeCounter;
+        this.edges.push({
+            id: `edge-${baseId}`,
+            source,
+            target: config.above,
+            type: 'personality',
+            personalityCondition: config,
+        });
+        this.edges.push({
+            id: `edge-${++this.edgeCounter}`,
+            source,
+            target: config.below,
+            type: 'personality',
+            personalityCondition: config,
+        });
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    // Compilation
+    // ---------------------------------------------------------------------------
+    /**
+     * Compile the builder state into a `CompiledAgentGraph` ready for execution.
+     *
+     * Compilation steps:
+     * 1. Call `GraphCompiler.compile()` to produce the raw `CompiledExecutionGraph` IR.
+     * 2. (Optional, default: enabled) Call `GraphValidator.validate()` to assert structural
+     *    correctness — any validation error or warning causes an exception.
+     * 3. Wrap the IR and a checkpoint store in a `CompiledAgentGraph` instance.
+     *
+     * Pass `{ validate: false }` to skip validation (e.g. for cyclic graphs under construction).
+     *
+     * @param options - Optional compilation flags.
+     * @param options.checkpointStore - Custom checkpoint store; defaults to `InMemoryCheckpointStore`.
+     * @param options.validate        - Set to `false` to skip structural validation (default: `true`).
+     * @returns A `CompiledAgentGraph` instance ready for `invoke()` / `stream()` / `resume()`.
+     * @throws {Error} When validation is enabled and the graph contains structural errors or warnings.
+     */
+    compile(options) {
+        // Step 1 — Compile builder state to IR.
+        const ir = GraphCompiler.compile({
+            name: 'agent-graph',
+            nodes: this.nodes,
+            edges: this.edges,
+            stateSchema: this.stateSchema,
+            reducers: this.config?.reducers ?? {},
+            memoryConsistency: this.config?.memoryConsistency ?? 'snapshot',
+            checkpointPolicy: this.config?.checkpointPolicy ?? 'none',
+        });
+        // Step 2 — Structural validation (opt-out with { validate: false }).
+        if (options?.validate !== false) {
+            // AgentGraph explicitly allows cycles (agent loops are a first-class pattern).
+            const result = GraphValidator.validate(ir, { requireAcyclic: false });
+            if (!result.valid) {
+                throw new Error(`Graph validation failed:\n  ${result.errors.join('\n  ')}`);
+            }
+            if (result.warnings.length > 0) {
+                // Promote warnings to compile-time errors for maximum safety.
+                // Authors who intentionally want orphan nodes must pass { validate: false }.
+                throw new Error(`Graph validation warnings (treated as errors at compile time):\n  ${result.warnings.join('\n  ')}`);
+            }
+        }
+        // Step 3 — Wrap in an executable CompiledAgentGraph.
+        const store = options?.checkpointStore ?? new InMemoryCheckpointStore();
+        return new CompiledAgentGraph(ir, store);
+    }
+}
+// ---------------------------------------------------------------------------
+// CompiledAgentGraph (execution wrapper)
+// ---------------------------------------------------------------------------
+/**
+ * A compiled, execution-ready agent graph.
+ *
+ * Returned by `AgentGraph.compile()` — do not instantiate directly.
+ *
+ * Wraps a `CompiledExecutionGraph` IR object and a `GraphRuntime` instance, exposing
+ * the three execution modes: synchronous `invoke()`, streaming `stream()`, and
+ * checkpoint-based `resume()`.
+ *
+ * @template TState - Type parameter threaded from the parent `AgentGraph`.
+ */
+export class CompiledAgentGraph {
+    /**
+     * @param ir              - Compiled execution graph IR produced by `GraphCompiler`.
+     * @param checkpointStore - Persistence backend for checkpoint snapshots.
+     */
+    constructor(ir, checkpointStore) {
+        this.ir = ir;
+        this.runtime = new GraphRuntime({
+            checkpointStore,
+            nodeExecutor: new NodeExecutor({}),
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Execution API
+    // ---------------------------------------------------------------------------
+    /**
+     * Execute the graph to completion and return the final `artifacts` payload.
+     *
+     * This is the simplest execution mode — it buffers all events internally and returns
+     * only the terminal output.  Use `stream()` when you need real-time progress updates.
+     *
+     * @param input - Initial user-provided input frozen into `GraphState.input`.
+     * @returns The `GraphState.artifacts` value after the last node completes.
+     */
+    async invoke(input) {
+        return this.runtime.invoke(this.ir, input);
+    }
+    /**
+     * Execute the graph while yielding `GraphEvent` values at each significant step.
+     *
+     * Events are emitted in strict causal order:
+     * `run_start` → (`node_start` → `node_end` → `edge_transition`?)+ → `run_end`
+     *
+     * @param input - Initial user-provided input frozen into `GraphState.input`.
+     * @yields {GraphEvent} Runtime events in causal order.
+     */
+    async *stream(input) {
+        yield* this.runtime.stream(this.ir, input);
+    }
+    /**
+     * Resume a previously interrupted run from its latest persisted checkpoint.
+     *
+     * The `patch` argument is accepted for API compatibility with future resume-with-patch
+     * support; it is not forwarded to the runtime in the current implementation.
+     *
+     * @param checkpointId - The run id returned by the original `stream()` call.
+     * @param patch        - Reserved for future use: optional partial state override.
+     * @returns The final `GraphState.artifacts` value after resumption completes.
+     * @throws {Error} When no checkpoint exists for the given `checkpointId`.
+     */
+    async resume(checkpointId, patch) {
+        // `patch` is not yet forwarded — tracked for implementation in a future PR.
+        void patch;
+        return this.runtime.resume(this.ir, checkpointId);
+    }
+    /**
+     * Inspect execution state for a completed or in-progress run.
+     *
+     * @param runId - The unique run identifier assigned at `stream()` call-time.
+     * @returns A stub object — full inspection support is tracked separately.
+     *
+     * @todo Implement with full runtime inspection once the run-registry subsystem lands.
+     */
+    async inspect(_runId) {
+        // Stub — run registry not yet implemented.
+        return {};
+    }
+    /**
+     * Return the underlying `CompiledExecutionGraph` IR.
+     *
+     * Useful for serialisation, debugging, or forwarding to external tooling.
+     */
+    toIR() {
+        return this.ir;
+    }
+}
+//# sourceMappingURL=AgentGraph.js.map

package/dist/orchestration/builders/AgentGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentGraph.js","sourceRoot":"","sources":["../../../src/orchestration/builders/AgentGraph.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/builders/MissionBuilder.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @file MissionBuilder.ts
+ * @description Fluent builder API for goal-oriented mission authoring.
+ *
+ * The `mission()` factory function returns a `MissionBuilder` that collects
+ * configuration through a chainable interface before compiling the mission into
+ * a `CompiledMission` — the execution-ready wrapper that exposes `invoke()`,
+ * `stream()`, `resume()`, `explain()`, and `toIR()`.
+ *
+ * Typical usage:
+ * ```ts
+ * const researchMission = mission('research')
+ *   .input(z.object({ topic: z.string() }))
+ *   .goal('Research {{topic}} and produce a concise summary')
+ *   .returns(z.object({ summary: z.string() }))
+ *   .planner({ strategy: 'linear', maxSteps: 6 })
+ *   .policy({ guardrails: ['content-safety'] })
+ *   .compile();
+ *
+ * const result = await researchMission.invoke({ topic: 'quantum computing' });
+ * ```
+ */
+import type { GraphNode, CompiledExecutionGraph, GraphState } from '../ir/types.js';
+import type { ICheckpointStore } from '../checkpoint/ICheckpointStore.js';
+import { type MissionConfig } from '../compiler/MissionCompiler.js';
+import type { GraphEvent } from '../events/GraphEvent.js';
+/**
+ * Create a new `MissionBuilder` for the named mission.
+ *
+ * @param name - Human-readable mission name; used as the compiled graph's display name
+ *               and as a stable slug prefix for run ids and checkpoint keys.
+ * @returns A fresh `MissionBuilder` instance ready to be configured.
+ *
+ * @example
+ * ```ts
+ * const m = mission('summarise-article')
+ *   .input(inputSchema)
+ *   .goal('Summarise {{url}} in three bullet points')
+ *   .returns(outputSchema)
+ *   .planner({ strategy: 'linear', maxSteps: 4 })
+ *   .compile();
+ * ```
+ */
+export declare function mission(name: string): MissionBuilder;
+/**
+ * Fluent builder that collects mission configuration and validates it at `.compile()` time.
+ *
+ * All setter methods return `this` for chaining.  No compilation work is performed until
+ * `.compile()` is called, ensuring fast construction of mission objects at module load time.
+ */
+export declare class MissionBuilder {
+    private readonly name;
+    /** @internal Zod or JSON-Schema describing the mission's input payload. */
+    private _inputSchema;
+    /** @internal Goal prompt template with optional `{{variable}}` placeholders. */
+    private _goalTemplate;
+    /** @internal Zod or JSON-Schema describing the mission's output artifacts. */
+    private _returnsSchema;
+    /** @internal Planner configuration (strategy, step budget, iteration caps). */
+    private _plannerConfig;
+    /** @internal Optional mission-level policy overrides. */
+    private _policyConfig;
+    /** @internal Declarative anchor node splice descriptors. */
+    private _anchors;
+    /**
+     * @param name - Display name for this mission; passed through to the compiled graph.
+     */
+    constructor(name: string);
+    /**
+     * Declare the input schema for this mission.
+     *
+     * Accepts a Zod schema object or a plain JSON-Schema `Record<string, unknown>`.
+     * The schema is stored in the compiled graph's `stateSchema.input` field and used
+     * by the runtime for optional input validation.
+     *
+     * @param schema - Zod or JSON-Schema object describing the expected input payload.
+     */
+    input(schema: any): this;
+    /**
+     * Set the goal template for this mission.
+     *
+     * The template is a free-form string that describes what the mission should achieve.
+     * It may include `{{variable}}` placeholders that will be interpolated with values
+     * from the input payload at plan generation time.
+     *
+     * Example: `'Research {{topic}} and produce a concise summary'`
+     *
+     * @param template - Goal prompt template string.
+     */
+    goal(template: string): this;
+    /**
+     * Declare the output (return) schema for this mission.
+     *
+     * Accepts a Zod schema object or a plain JSON-Schema `Record<string, unknown>`.
+     * The schema is stored in the compiled graph's `stateSchema.artifacts` field.
+     *
+     * @param schema - Zod or JSON-Schema object describing the expected artifact payload.
+     */
+    returns(schema: any): this;
+    /**
+     * Configure the planner used to decompose the goal into execution steps.
+     *
+     * @param config - Planner settings including strategy name, step budget, and
+     *                 per-node iteration and tool-parallelism caps.
+     */
+    planner(config: MissionConfig['plannerConfig']): this;
+    /**
+     * Apply mission-level policy overrides.
+     *
+     * Policies declared here are applied to **all** compiled nodes unless a node already
+     * carries its own policy declaration.  This is the preferred mechanism for setting
+     * blanket guardrails, memory consistency modes, or persona settings across a mission.
+     *
+     * @param config - Policy configuration object.
+     */
+    policy(config: NonNullable<MissionConfig['policyConfig']>): this;
+    /**
+     * Declare an anchor node that will be spliced into the execution order.
+     *
+     * Anchors let callers inject pre-built `GraphNode` objects (e.g. specialised tool
+     * invocations, human-in-the-loop checkpoints, or validation guardrails) at precise
+     * positions within the phase-ordered plan without modifying the planner output.
+     *
+     * @param id          - Unique node id assigned to the anchor in the compiled graph.
+     * @param node        - Pre-built `GraphNode` (from `gmiNode`, `toolNode`, etc.).
+     * @param constraints - Placement constraints: phase, `after` / `before` ordering.
+     */
+    anchor(id: string, node: GraphNode, constraints: MissionConfig['anchors'][0]['constraints']): this;
+    /**
+     * Validate configuration and compile this mission into a `CompiledMission`.
+     *
+     * Required fields: `input`, `goal`, `returns`, `planner`.
+     * Throws with a descriptive message if any required field is missing.
+     *
+     * @param options                - Optional compilation overrides.
+     * @param options.checkpointStore - Custom checkpoint store; defaults to `InMemoryCheckpointStore`.
+     * @returns A `CompiledMission` ready to `invoke()`, `stream()`, or `explain()`.
+     * @throws {Error} When required builder fields are missing.
+     */
+    compile(options?: {
+        checkpointStore?: ICheckpointStore;
+    }): CompiledMission;
+}
+/**
+ * Execution wrapper for a compiled mission.
+ *
+ * Lazily re-compiles the IR on each call so that changes to the underlying
+ * config are reflected without needing to rebuild the mission object.  In
+ * production callers typically compile once and reuse the `CompiledMission`
+ * for many invocations.
+ */
+export declare class CompiledMission {
+    private readonly config;
+    private readonly checkpointStore;
+    /**
+     * @param config          - Frozen mission configuration snapshot.
+     * @param checkpointStore - Checkpoint persistence backend.
+     */
+    constructor(config: MissionConfig, checkpointStore: ICheckpointStore);
+    /**
+     * Run `MissionCompiler.compile()` to produce a fresh `CompiledExecutionGraph`.
+     * Called lazily by each execution method so the IR is always up-to-date.
+     */
+    private compileIR;
+    /**
+     * Create a new `GraphRuntime` bound to this mission's checkpoint store.
+     * A fresh runtime is created per invocation to ensure full call isolation.
+     */
+    private createRuntime;
+    /**
+     * Execute the mission to completion and return the final artifacts.
+     *
+     * @param input - Input payload conforming to the mission's `inputSchema`.
+     * @returns The final `GraphState.artifacts` value once all nodes have completed.
+     */
+    invoke(input: unknown): Promise<unknown>;
+    /**
+     * Execute the mission while yielding `GraphEvent` values at each step.
+     *
+     * Useful for streaming progress updates to a UI or logging pipeline.
+     *
+     * @param input - Input payload conforming to the mission's `inputSchema`.
+     * @yields `GraphEvent` objects emitted by the runtime at each node lifecycle point.
+     */
+    stream(input: unknown): AsyncIterable<GraphEvent>;
+    /**
+     * Resume a previously interrupted run from its latest checkpoint.
+     *
+     * @param checkpointId - Id of the checkpoint to restore (from `GraphState.checkpointId`).
+     * @param _patch       - Optional partial `GraphState` to merge before resuming (reserved).
+     * @returns The final `GraphState.artifacts` value once execution completes.
+     */
+    resume(checkpointId: string, _patch?: Partial<GraphState>): Promise<unknown>;
+    /**
+     * Retrieve a diagnostic snapshot of a completed or in-progress run.
+     *
+     * @param _runId - Run id assigned by the runtime at invocation time.
+     * @returns A `RunInspection`-shaped object (stub — full implementation in Task 17+).
+     */
+    inspect(_runId: string): Promise<unknown>;
+    /**
+     * Return a human-readable execution plan without actually running the mission.
+     *
+     * Useful for debugging, testing, and displaying "what will happen" summaries in UIs.
+     *
+     * @param _input - Input payload (currently unused; reserved for future goal interpolation).
+     * @returns An object containing:
+     *   - `steps`: flat array of `{ id, type, config }` descriptors for each node.
+     *   - `ir`: the full `CompiledExecutionGraph` for deeper inspection.
+     */
+    explain(_input: unknown): Promise<{
+        steps: any[];
+        ir: CompiledExecutionGraph;
+    }>;
+    /**
+     * Export the compiled plan as a static `CompiledExecutionGraph`.
+     *
+     * Allows callers to "graduate" a dynamically-planned mission to a fixed workflow or
+     * graph for performance-sensitive deployments where replanning is not desired.
+     *
+     * @returns The compiled IR, suitable for passing directly to `GraphRuntime`.
+     */
+    toWorkflow(): CompiledExecutionGraph;
+    /**
+     * Alias of `toWorkflow()` — returns the compiled `CompiledExecutionGraph` IR.
+     *
+     * @returns The compiled IR.
+     */
+    toIR(): CompiledExecutionGraph;
+}
+//# sourceMappingURL=MissionBuilder.d.ts.map

package/dist/orchestration/builders/MissionBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MissionBuilder.d.ts","sourceRoot":"","sources":["../../../src/orchestration/builders/MissionBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAM1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAEpD;AAMD;;;;;GAKG;AACH,qBAAa,cAAc;IAiBb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAhBjC,2EAA2E;IAC3E,OAAO,CAAC,YAAY,CAAM;IAC1B,gFAAgF;IAChF,OAAO,CAAC,aAAa,CAAc;IACnC,8EAA8E;IAC9E,OAAO,CAAC,cAAc,CAAM;IAC5B,+EAA+E;IAC/E,OAAO,CAAC,cAAc,CAA6C;IACnE,yDAAyD;IACzD,OAAO,CAAC,aAAa,CAAgC;IACrD,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAgC;IAEhD;;OAEG;gBAC0B,IAAI,EAAE,MAAM;IAMzC;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI;IAKxB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI;IAK1B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI;IAKrD;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI;IAKhE;;;;;;;;;;OAUG;IACH,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GACtD,IAAI;IASP;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,gBAAgB,CAAA;KAAE,GAAG,eAAe;CA2B3E;AAMD;;;;;;;GAOG;AACH,qBAAa,eAAe;IAMxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe;IANlC;;;OAGG;gBAEgB,MAAM,EAAE,aAAa,EACrB,eAAe,EAAE,gBAAgB;IAOpD;;;OAGG;IACH,OAAO,CAAC,SAAS;IAIjB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAWrB;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAK9C;;;;;;;OAOG;IACI,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAAC,UAAU,CAAC;IAKxD;;;;;;OAMG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlF;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/C;;;;;;;;;OASG;IACG,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAAC,EAAE,EAAE,sBAAsB,CAAA;KAAE,CAAC;IAYrF;;;;;;;OAOG;IACH,UAAU,IAAI,sBAAsB;IAIpC;;;;OAIG;IACH,IAAI,IAAI,sBAAsB;CAG/B"}