@framers/agentos-ext-ml-classifiers 0.1.0

package/dist/classifiers/ToxicityClassifier.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Toxicity content classifier using the `unitary/toxic-bert` model.
+ *
+ * This classifier uses a multi-label BERT-based model trained on the Jigsaw
+ * Toxic Comment dataset.  It assigns independent confidence scores to six
+ * toxicity categories and surfaces the highest-scoring label as `bestClass`.
+ *
+ * The model is loaded lazily the first time `classify()` is called and
+ * cached in the shared service registry so it is only initialised once even
+ * if multiple parts of the system hold a reference to this classifier.
+ *
+ * Graceful degradation
+ * --------------------
+ * If the model fails to load (e.g. network unavailable, ONNX runtime missing)
+ * the classifier sets `unavailable = true` and returns a **pass result**
+ * `{ bestClass: 'benign', confidence: 0, allScores: [] }` on every subsequent
+ * call instead of throwing.  This ensures the guardrail pipeline degrades
+ * gracefully rather than crashing the agent.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/classifiers/ToxicityClassifier
+ */
+import type { ClassificationResult } from '@framers/agentos';
+import type { ISharedServiceRegistry } from '@framers/agentos';
+import type { IContentClassifier } from '../IContentClassifier';
+import type { ClassifierConfig } from '../types';
+/**
+ * Multi-label toxicity classifier backed by `unitary/toxic-bert`.
+ *
+ * Evaluates text against six toxicity categories:
+ *  - `toxic`
+ *  - `severe_toxic`
+ *  - `obscene`
+ *  - `threat`
+ *  - `insult`
+ *  - `identity_hate`
+ *
+ * Each category receives an independent confidence score.  The label with
+ * the highest score is reported as `bestClass` and its score as `confidence`.
+ * All six scores are included in `allScores` so the pack orchestrator can
+ * apply per-label thresholds.
+ *
+ * @implements {IContentClassifier}
+ *
+ * @example
+ * ```typescript
+ * const classifier = new ToxicityClassifier(serviceRegistry);
+ * const result = await classifier.classify('You are terrible!');
+ * // result.bestClass === 'insult', result.confidence ≈ 0.87
+ * ```
+ */
+export declare class ToxicityClassifier implements IContentClassifier {
+    private readonly services;
+    private readonly config?;
+    /** Unique service identifier for this classifier. */
+    readonly id = "toxicity";
+    /** Human-readable name for dashboards and log output. */
+    readonly displayName = "Toxicity Classifier";
+    /** Short description of what this classifier detects. */
+    readonly description: string;
+    /**
+     * Default Hugging Face model ID.
+     * Overridable via {@link ClassifierConfig.modelId}.
+     */
+    readonly modelId = "unitary/toxic-bert";
+    /**
+     * Whether the model weights are fully loaded and the classifier is ready
+     * to accept `classify()` calls.
+     */
+    private _isLoaded;
+    /**
+     * Set to `true` when the model fails to load.  Once `unavailable`, every
+     * subsequent `classify()` call immediately returns the pass result rather
+     * than retrying the expensive model load.
+     */
+    private unavailable;
+    /**
+     * @param services - Shared service registry used to lazily create and cache
+     *   the underlying HuggingFace pipeline instance.
+     * @param config - Optional per-classifier configuration.  When
+     *   `config.modelId` is provided it overrides the default `modelId` when
+     *   loading the model.
+     */
+    constructor(services: ISharedServiceRegistry, config?: ClassifierConfig | undefined);
+    /**
+     * Whether the underlying model pipeline has been successfully initialised.
+     * The flag is set to `true` after the first successful `classify()` call.
+     */
+    get isLoaded(): boolean;
+    /**
+     * Run toxicity inference on `text`.
+     *
+     * Lazily loads the pipeline on the first call via the shared service
+     * registry, then calls it with `{ topk: null }` to retrieve scores for
+     * every label.
+     *
+     * @param text - The text to evaluate.
+     * @returns A promise that resolves with the classification result.  If the
+     *   model is unavailable the pass result is returned instead of throwing.
+     */
+    classify(text: string): Promise<ClassificationResult>;
+    /**
+     * Release the pipeline instance from the shared service registry.
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Returns a "pass" result used when the model is unavailable.
+     *
+     * A pass result reports `bestClass: 'benign'` with zero confidence so the
+     * guardrail orchestrator will always choose {@link GuardrailAction.ALLOW}.
+     */
+    private passResult;
+    /**
+     * Map the raw pipeline output (array of `{ label, score }` objects) to a
+     * {@link ClassificationResult}.
+     *
+     * The label with the highest score becomes `bestClass` / `confidence`.
+     * Every label is included in `allScores` for downstream threshold logic.
+     *
+     * @param raw - Array returned by the pipeline when called with `topk: null`.
+     */
+    private mapResult;
+}
+//# sourceMappingURL=ToxicityClassifier.d.ts.map

package/dist/classifiers/ToxicityClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToxicityClassifier.d.ts","sourceRoot":"","sources":["../../src/classifiers/ToxicityClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAsBjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAmDzD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IA/C1B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,cAAc;IAEzB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,yBAAyB;IAE7C,yDAAyD;IACzD,QAAQ,CAAC,WAAW,SAEiD;IAErE;;;OAGG;IACH,QAAQ,CAAC,OAAO,wBAAwB;IAMxC;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAS;IAM5B;;;;;;OAMG;gBAEgB,QAAQ,EAAE,sBAAsB,EAChC,MAAM,CAAC,EAAE,gBAAgB,YAAA;IAO5C;;;OAGG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAMD;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAoD3D;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAIlB;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;CAuBlB"}

package/dist/classifiers/ToxicityClassifier.js

@@ -0,0 +1,212 @@
+/**
+ * @fileoverview Toxicity content classifier using the `unitary/toxic-bert` model.
+ *
+ * This classifier uses a multi-label BERT-based model trained on the Jigsaw
+ * Toxic Comment dataset.  It assigns independent confidence scores to six
+ * toxicity categories and surfaces the highest-scoring label as `bestClass`.
+ *
+ * The model is loaded lazily the first time `classify()` is called and
+ * cached in the shared service registry so it is only initialised once even
+ * if multiple parts of the system hold a reference to this classifier.
+ *
+ * Graceful degradation
+ * --------------------
+ * If the model fails to load (e.g. network unavailable, ONNX runtime missing)
+ * the classifier sets `unavailable = true` and returns a **pass result**
+ * `{ bestClass: 'benign', confidence: 0, allScores: [] }` on every subsequent
+ * call instead of throwing.  This ensures the guardrail pipeline degrades
+ * gracefully rather than crashing the agent.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/classifiers/ToxicityClassifier
+ */
+import { ML_CLASSIFIER_SERVICE_IDS } from '../types';
+// ---------------------------------------------------------------------------
+// ToxicityClassifier
+// ---------------------------------------------------------------------------
+/**
+ * Multi-label toxicity classifier backed by `unitary/toxic-bert`.
+ *
+ * Evaluates text against six toxicity categories:
+ *  - `toxic`
+ *  - `severe_toxic`
+ *  - `obscene`
+ *  - `threat`
+ *  - `insult`
+ *  - `identity_hate`
+ *
+ * Each category receives an independent confidence score.  The label with
+ * the highest score is reported as `bestClass` and its score as `confidence`.
+ * All six scores are included in `allScores` so the pack orchestrator can
+ * apply per-label thresholds.
+ *
+ * @implements {IContentClassifier}
+ *
+ * @example
+ * ```typescript
+ * const classifier = new ToxicityClassifier(serviceRegistry);
+ * const result = await classifier.classify('You are terrible!');
+ * // result.bestClass === 'insult', result.confidence ≈ 0.87
+ * ```
+ */
+export class ToxicityClassifier {
+    services;
+    config;
+    // -------------------------------------------------------------------------
+    // IContentClassifier identity fields
+    // -------------------------------------------------------------------------
+    /** Unique service identifier for this classifier. */
+    id = 'toxicity';
+    /** Human-readable name for dashboards and log output. */
+    displayName = 'Toxicity Classifier';
+    /** Short description of what this classifier detects. */
+    description = 'Detects toxic, hateful, or abusive language across six categories: ' +
+        'toxic, severe_toxic, obscene, threat, insult, and identity_hate.';
+    /**
+     * Default Hugging Face model ID.
+     * Overridable via {@link ClassifierConfig.modelId}.
+     */
+    modelId = 'unitary/toxic-bert';
+    // -------------------------------------------------------------------------
+    // Internal state
+    // -------------------------------------------------------------------------
+    /**
+     * Whether the model weights are fully loaded and the classifier is ready
+     * to accept `classify()` calls.
+     */
+    _isLoaded = false;
+    /**
+     * Set to `true` when the model fails to load.  Once `unavailable`, every
+     * subsequent `classify()` call immediately returns the pass result rather
+     * than retrying the expensive model load.
+     */
+    unavailable = false;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param services - Shared service registry used to lazily create and cache
+     *   the underlying HuggingFace pipeline instance.
+     * @param config - Optional per-classifier configuration.  When
+     *   `config.modelId` is provided it overrides the default `modelId` when
+     *   loading the model.
+     */
+    constructor(services, config) {
+        this.services = services;
+        this.config = config;
+    }
+    // -------------------------------------------------------------------------
+    // IContentClassifier.isLoaded (getter)
+    // -------------------------------------------------------------------------
+    /**
+     * Whether the underlying model pipeline has been successfully initialised.
+     * The flag is set to `true` after the first successful `classify()` call.
+     */
+    get isLoaded() {
+        return this._isLoaded;
+    }
+    // -------------------------------------------------------------------------
+    // classify
+    // -------------------------------------------------------------------------
+    /**
+     * Run toxicity inference on `text`.
+     *
+     * Lazily loads the pipeline on the first call via the shared service
+     * registry, then calls it with `{ topk: null }` to retrieve scores for
+     * every label.
+     *
+     * @param text - The text to evaluate.
+     * @returns A promise that resolves with the classification result.  If the
+     *   model is unavailable the pass result is returned instead of throwing.
+     */
+    async classify(text) {
+        // Return the pass result immediately if the model previously failed to load.
+        if (this.unavailable) {
+            return this.passResult();
+        }
+        // Lazily obtain (or create) the HuggingFace pipeline instance from the
+        // shared service registry.  The registry ensures the model is only loaded
+        // once even under concurrent calls.
+        let pipeline;
+        try {
+            pipeline = await this.services.getOrCreate(ML_CLASSIFIER_SERVICE_IDS.TOXICITY_PIPELINE, async () => {
+                // Dynamic import keeps the heavy ONNX runtime out of the initial
+                // bundle and allows environments without the package to skip loading.
+                const { pipeline: createPipeline } = await import('@huggingface/transformers');
+                return createPipeline('text-classification', 
+                // Honour a caller-supplied model override; fall back to the default.
+                this.config?.modelId ?? this.modelId, { quantized: true });
+            }, {
+                /** Release ONNX/WASM resources when the registry entry is evicted. */
+                dispose: async (p) => p?.dispose?.(),
+                /** Tags used for diagnostics and capability discovery. */
+                tags: ['ml', 'classifier', 'toxicity', 'onnx'],
+            });
+            // Mark the classifier as ready now that the pipeline is available.
+            this._isLoaded = true;
+        }
+        catch {
+            // Model failed to load — mark as unavailable and return the pass result
+            // so the guardrail pipeline can continue operating.
+            this.unavailable = true;
+            return this.passResult();
+        }
+        // Run inference — request scores for ALL labels (topk: null).
+        const raw = await pipeline(text, { topk: null });
+        return this.mapResult(raw);
+    }
+    // -------------------------------------------------------------------------
+    // dispose (optional IContentClassifier lifecycle hook)
+    // -------------------------------------------------------------------------
+    /**
+     * Release the pipeline instance from the shared service registry.
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    async dispose() {
+        await this.services.release(ML_CLASSIFIER_SERVICE_IDS.TOXICITY_PIPELINE);
+        this._isLoaded = false;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Returns a "pass" result used when the model is unavailable.
+     *
+     * A pass result reports `bestClass: 'benign'` with zero confidence so the
+     * guardrail orchestrator will always choose {@link GuardrailAction.ALLOW}.
+     */
+    passResult() {
+        return { bestClass: 'benign', confidence: 0, allScores: [] };
+    }
+    /**
+     * Map the raw pipeline output (array of `{ label, score }` objects) to a
+     * {@link ClassificationResult}.
+     *
+     * The label with the highest score becomes `bestClass` / `confidence`.
+     * Every label is included in `allScores` for downstream threshold logic.
+     *
+     * @param raw - Array returned by the pipeline when called with `topk: null`.
+     */
+    mapResult(raw) {
+        if (!raw || raw.length === 0) {
+            // No output from the model — treat as benign.
+            return this.passResult();
+        }
+        // Find the label with the maximum confidence score.
+        let best = raw[0];
+        for (const item of raw) {
+            if (item.score > best.score) {
+                best = item;
+            }
+        }
+        return {
+            bestClass: best.label,
+            confidence: best.score,
+            allScores: raw.map((item) => ({
+                classLabel: item.label,
+                score: item.score,
+            })),
+        };
+    }
+}
+//# sourceMappingURL=ToxicityClassifier.js.map

package/dist/classifiers/ToxicityClassifier.js.map

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

package/dist/classifiers/WorkerClassifierProxy.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview WorkerClassifierProxy — wraps an IContentClassifier to run
+ * inference inside a Web Worker, with automatic main-thread fallback.
+ *
+ * ## Why a proxy?
+ * ML inference (even quantized ONNX / WASM pipelines) can block the main
+ * thread for 50–500 ms per classification.  Moving classification into a
+ * Web Worker keeps the UI responsive.  This proxy makes the switch
+ * transparent to callers: they still call `classify(text)` and receive a
+ * `ClassificationResult`; the underlying transport (Worker vs. direct call)
+ * is an implementation detail.
+ *
+ * ## Fallback policy
+ * The proxy falls back to direct (main-thread) delegation whenever:
+ *  - The global `Worker` constructor is undefined (Node.js, older browsers).
+ *  - `browserConfig.useWebWorker` is explicitly `false`.
+ *  - Worker creation throws (e.g. strict CSP that blocks `blob:` URLs).
+ *
+ * Once a fallback has been triggered by a Worker creation error the proxy
+ * sets `workerFailed = true` and remains in fallback mode for all subsequent
+ * calls.
+ *
+ * ## IContentClassifier contract
+ * The proxy forwards all identity fields (`id`, `displayName`, `description`,
+ * `modelId`) and the `isLoaded` state directly from the wrapped classifier so
+ * it is completely transparent to the orchestrator.
+ *
+ * @module agentos/extensions/packs/ml-classifiers/classifiers/WorkerClassifierProxy
+ */
+import type { ClassificationResult } from '@framers/agentos';
+import type { IContentClassifier } from '../IContentClassifier';
+import type { BrowserConfig } from '../types';
+/**
+ * Transparent proxy around an {@link IContentClassifier} that offloads
+ * `classify()` calls to a Web Worker when the browser environment supports it.
+ *
+ * In all other environments (Node.js, strict CSP, explicit opt-out) the proxy
+ * delegates calls directly to the wrapped classifier on the main thread.
+ *
+ * @implements {IContentClassifier}
+ *
+ * @example Browser context — Web Worker path
+ * ```typescript
+ * const toxicity = new ToxicityClassifier(serviceRegistry);
+ * const proxy = new WorkerClassifierProxy(toxicity, { useWebWorker: true });
+ * const result = await proxy.classify('some text');
+ * ```
+ *
+ * @example Node.js / forced fallback path
+ * ```typescript
+ * const proxy = new WorkerClassifierProxy(toxicity, { useWebWorker: false });
+ * // Delegates directly to toxicity.classify() on the same thread.
+ * ```
+ */
+export declare class WorkerClassifierProxy implements IContentClassifier {
+    private readonly wrapped;
+    private readonly browserConfig?;
+    /**
+     * {@inheritDoc IContentClassifier.id}
+     * Delegated from the wrapped classifier so this proxy is transparent in
+     * the orchestrator's service-ID lookups.
+     */
+    get id(): string;
+    /**
+     * {@inheritDoc IContentClassifier.displayName}
+     * Returns the wrapped classifier's display name with a `(Worker)` suffix
+     * when the Web Worker path is active, so logs clearly indicate the mode.
+     */
+    get displayName(): string;
+    /**
+     * {@inheritDoc IContentClassifier.description}
+     * Delegated directly from the wrapped classifier.
+     */
+    get description(): string;
+    /**
+     * {@inheritDoc IContentClassifier.modelId}
+     * Delegated directly from the wrapped classifier.
+     */
+    get modelId(): string;
+    /**
+     * {@inheritDoc IContentClassifier.isLoaded}
+     *
+     * Reflects the wrapped classifier's `isLoaded` state.  The wrapped
+     * instance is the authoritative source because it owns the model weights
+     * (whether they live in the Worker or on the main thread).
+     */
+    get isLoaded(): boolean;
+    /**
+     * IContentClassifier requires `isLoaded` to be settable via the interface
+     * contract (`isLoaded: boolean`).  We store the value through the wrapped
+     * classifier so the authoritative state lives in one place.
+     */
+    set isLoaded(value: boolean);
+    /**
+     * Set to `true` after a Worker creation failure.  Once set, all subsequent
+     * `classify()` calls are routed directly to the wrapped classifier without
+     * attempting to re-create the Worker.
+     */
+    private workerFailed;
+    /**
+     * Create a WorkerClassifierProxy.
+     *
+     * @param wrapped       - The real classifier to delegate to.  In Worker
+     *                        mode this classifier is still responsible for
+     *                        model loading and inference; the proxy just
+     *                        changes the thread on which it executes.
+     * @param browserConfig - Optional browser-side configuration.  Controls
+     *                        whether Worker mode is attempted
+     *                        (`useWebWorker`, default `true`).
+     */
+    constructor(wrapped: IContentClassifier, browserConfig?: BrowserConfig | undefined);
+    /**
+     * Classify the provided text, routing to a Web Worker when available.
+     *
+     * ### Routing decision (evaluated once per call)
+     * 1. `typeof Worker === 'undefined'` → fallback (Node.js / no Worker API).
+     * 2. `browserConfig.useWebWorker === false` → fallback (explicit opt-out).
+     * 3. `workerFailed === true` → fallback (previous Worker creation error).
+     * 4. Otherwise → attempt to run in a Web Worker.
+     *
+     * If the Worker is created but fails to post a result within the
+     * classification request, the error is propagated as a rejected promise
+     * (not silently swallowed) so the orchestrator can log and fall back at
+     * a higher level.
+     *
+     * @param text - The text to classify.  Must not be empty.
+     * @returns A promise that resolves with the classification result.
+     */
+    classify(text: string): Promise<ClassificationResult>;
+    /**
+     * Release resources held by the wrapped classifier.
+     *
+     * Delegates to `wrapped.dispose()` if it exists.  Idempotent.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Determine whether the current environment and configuration support
+     * running inference in a Web Worker.
+     *
+     * @returns `true` when Web Worker mode should be attempted.
+     */
+    private shouldUseWebWorker;
+    /**
+     * Run `classify(text)` inside a transient Web Worker.
+     *
+     * Each call creates a new Worker, sends a single `classify` message,
+     * awaits the `result` or `error` response, then terminates the Worker.
+     *
+     * If Worker creation itself throws (e.g. CSP violation), `workerFailed`
+     * is set to `true` and the call falls back to the wrapped classifier on
+     * the main thread.
+     *
+     * @param text - The text to classify inside the Worker.
+     * @returns A promise resolving with the {@link ClassificationResult}.
+     */
+    private classifyInWorker;
+}
+//# sourceMappingURL=WorkerClassifierProxy.d.ts.map

package/dist/classifiers/WorkerClassifierProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerClassifierProxy.d.ts","sourceRoot":"","sources":["../../src/classifiers/WorkerClassifierProxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAoE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAsF5D,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAlFjC;;;;OAIG;IACH,IAAI,EAAE,IAAI,MAAM,CAEf;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;;OAMG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACH,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAE1B;IAMD;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAS;IAM7B;;;;;;;;;;OAUG;gBAEgB,OAAO,EAAE,kBAAkB,EAC3B,aAAa,CAAC,EAAE,aAAa,YAAA;IAOhD;;;;;;;;;;;;;;;;OAgBG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiB3D;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;;;;;;;;;;;OAYG;YACW,gBAAgB;CA8D/B"}