@try-works/dsh-model-as-tool 0.0.0-stage → 0.1.0

package/lib/transport.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Command transports: reaching a model that is not an in-process npm package.
+ *
+ * Two transports share one shape:
+ *
+ * - **cli** — runs the Desert Ant CLI (`desertant`/`da`), which exposes every
+ *   shipping model as `desertant <verb> … --json` and runs on macOS and Linux.
+ * - **remote** — POSTs to a bridge the user runs on a machine that can execute
+ *   the model. This is what makes an Apple-only model such as Title reachable
+ *   from a Windows host.
+ *
+ * Both are injected with their side-effecting primitive (`CommandRunner`,
+ * `HttpPost`) so behaviour is testable without spawning a process or opening a
+ * socket, and so a deployment can substitute its own runner.
+ *
+ * @module @try-works/dsh-model-as-tool/transport
+ */
+import type { ModelCatalogEntry } from './types.ts';
+import { type JsonValue } from './adapters/types.ts';
+/** One invocation to route through a transport. */
+export interface TransportRequest {
+    /** The catalog entry being invoked. */
+    readonly entry: ModelCatalogEntry;
+    /** Validated tool arguments; the first declared parameter is the primary input. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Caller cancellation. */
+    readonly signal: AbortSignal;
+}
+/** Outcome of running one command. */
+export interface CommandOutcome {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Run a command to completion. Injectable so tests need no real process. */
+export type CommandRunner = (command: string, argv: readonly string[], signal: AbortSignal) => Promise<CommandOutcome>;
+/** Post a JSON body and read the response. Injectable for the same reason. */
+export type HttpPost = (url: string, body: unknown, headers: Readonly<Record<string, string>>, signal: AbortSignal) => Promise<{
+    readonly status: number;
+    readonly body: string;
+}>;
+/** A model invoked out-of-process. */
+export interface CommandTransport {
+    readonly kind: 'cli' | 'remote';
+    invoke(request: TransportRequest): Promise<Record<string, JsonValue>>;
+}
+/** The Desert Ant CLI's exit codes, as documented for agents. */
+export declare const CLI_EXIT_RUNTIME_ERROR = 1;
+export declare const CLI_EXIT_USAGE_ERROR = 64;
+/**
+ * Default command name. `da` is the short alias the CLI installs.
+ */
+export declare const DEFAULT_CLI_COMMAND = "desertant";
+/** The path every bridge must serve. */
+export declare const BRIDGE_PATH = "/invoke";
+/**
+ * Whether a command is on PATH.
+ *
+ * Probed by scanning PATH rather than by running the command, because this runs
+ * at plugin load and a capability probe must not start a process (or pay a
+ * CLI's startup cost) just to decide what to advertise.
+ * @param command - command name or an absolute path.
+ * @param pathValue - the PATH to search; defaults to the process environment.
+ * @returns whether an executable file of that name exists.
+ */
+export declare function commandExists(command: string, pathValue?: string): boolean;
+/**
+ * Split the tool arguments into the CLI's positional inputs and its
+ * `--option key=value` flags.
+ *
+ * The first declared catalog parameter is the primary input, matching how the
+ * registrar marks it required. A file model accepts several paths positionally
+ * (the CLI loads the model once for all of them), so a primary declared as a
+ * string list becomes several positionals. Everything else becomes an option,
+ * with lists comma-joined because the CLI's option syntax is `key=value`.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the positional inputs and the option list.
+ */
+export declare function splitArguments(entry: ModelCatalogEntry, args: Readonly<Record<string, unknown>>): {
+    positionals: string[];
+    options: [string, string][];
+};
+/**
+ * Build the CLI argv for one invocation.
+ *
+ * `--json` is what makes stdout a single JSON value, and it also implies
+ * `--no-color`, so no escape sequences have to be stripped.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the argv to run, after the command itself.
+ */
+export declare function buildArgv(entry: ModelCatalogEntry, args: Readonly<Record<string, unknown>>): string[];
+/**
+ * Parse the CLI's stdout into a canonical value.
+ *
+ * The CLI writes exactly one JSON value to stdout under `--json` and keeps every
+ * diagnostic on stderr, so a parse failure means the command did not behave as
+ * documented rather than that output needs cleaning.
+ * @param entry - the model, for error messages.
+ * @param outcome - the completed command.
+ * @returns the parsed value.
+ * @throws when the exit code is non-zero or stdout is not a single JSON value.
+ */
+export declare function parseCliOutcome(entry: ModelCatalogEntry, outcome: CommandOutcome): Record<string, JsonValue>;
+/** Spawn a command and capture its output. */
+export declare const spawnRunner: CommandRunner;
+/** POST JSON with the global fetch and read the response as text. */
+export declare const fetchPost: HttpPost;
+/** Options shared by both out-of-process transports. */
+export interface TransportOptions {
+    /** Command name or path for the CLI transport. */
+    readonly cliCommand?: string;
+    /** Bridge base URL for the remote transport. */
+    readonly endpoint?: string;
+    /** Optional bearer token sent to the bridge. */
+    readonly token?: string;
+    /** Injected command runner. */
+    readonly run?: CommandRunner;
+    /** Injected HTTP poster. */
+    readonly post?: HttpPost;
+}
+/**
+ * Build the CLI transport for one model.
+ * @param entry - the catalog entry, which must declare a CLI verb.
+ * @param options - command name and injected runner.
+ * @returns the transport.
+ */
+export declare function createCliTransport(entry: ModelCatalogEntry, options?: TransportOptions): CommandTransport;
+/**
+ * Build the remote transport for one model.
+ *
+ * The bridge contract is deliberately small so a user can implement it in a few
+ * lines on a machine that can run the model:
+ *
+ * ```
+ * POST <endpoint>/invoke
+ *   { "model": "title", "verb": "title", "input": "<primary>", "options": { "max-tokens": "96" } }
+ *   → 200 { "ok": true,  "result": <the model's JSON> }
+ *   → 4xx { "ok": false, "error": "<message>" }
+ * ```
+ * @param entry - the catalog entry to reach.
+ * @param options - endpoint, optional token, injected poster.
+ * @returns the transport.
+ */
+export declare function createRemoteTransport(entry: ModelCatalogEntry, options?: TransportOptions): CommandTransport;
+/**
+ * Interpret one bridge response.
+ * @param entry - the model, for error messages.
+ * @param response - the HTTP status and body.
+ * @returns the model's result as a canonical value.
+ * @throws when the bridge reports a failure or an unreadable body.
+ */
+export declare function parseBridgeResponse(entry: ModelCatalogEntry, response: {
+    readonly status: number;
+    readonly body: string;
+}): Record<string, JsonValue>;
+//# sourceMappingURL=transport.d.ts.map

package/lib/transport.d.ts.map

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

package/lib/transport.js

@@ -0,0 +1,332 @@
+/**
+ * Command transports: reaching a model that is not an in-process npm package.
+ *
+ * Two transports share one shape:
+ *
+ * - **cli** — runs the Desert Ant CLI (`desertant`/`da`), which exposes every
+ *   shipping model as `desertant <verb> … --json` and runs on macOS and Linux.
+ * - **remote** — POSTs to a bridge the user runs on a machine that can execute
+ *   the model. This is what makes an Apple-only model such as Title reachable
+ *   from a Windows host.
+ *
+ * Both are injected with their side-effecting primitive (`CommandRunner`,
+ * `HttpPost`) so behaviour is testable without spawning a process or opening a
+ * socket, and so a deployment can substitute its own runner.
+ *
+ * @module @try-works/dsh-model-as-tool/transport
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { throwIfAborted } from "./adapters/types.js";
+/** The Desert Ant CLI's exit codes, as documented for agents. */
+export const CLI_EXIT_RUNTIME_ERROR = 1;
+export const CLI_EXIT_USAGE_ERROR = 64;
+/**
+ * Default command name. `da` is the short alias the CLI installs.
+ */
+export const DEFAULT_CLI_COMMAND = 'desertant';
+/** The path every bridge must serve. */
+export const BRIDGE_PATH = '/invoke';
+/**
+ * Whether a command is on PATH.
+ *
+ * Probed by scanning PATH rather than by running the command, because this runs
+ * at plugin load and a capability probe must not start a process (or pay a
+ * CLI's startup cost) just to decide what to advertise.
+ * @param command - command name or an absolute path.
+ * @param pathValue - the PATH to search; defaults to the process environment.
+ * @returns whether an executable file of that name exists.
+ */
+export function commandExists(command, pathValue) {
+    // An explicit path is checked directly; a bare name is searched on PATH.
+    if (command.includes('/') || command.includes('\\')) {
+        return isExecutable(command);
+    }
+    const searchPath = pathValue ?? process.env.PATH ?? '';
+    const extensions = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+        : [''];
+    for (const directory of searchPath.split(delimiter)) {
+        if (directory.length === 0)
+            continue;
+        for (const extension of extensions) {
+            if (isExecutable(join(directory, command + extension)))
+                return true;
+        }
+    }
+    return false;
+}
+/** Whether a path is an existing executable file. */
+function isExecutable(candidate) {
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Split the tool arguments into the CLI's positional inputs and its
+ * `--option key=value` flags.
+ *
+ * The first declared catalog parameter is the primary input, matching how the
+ * registrar marks it required. A file model accepts several paths positionally
+ * (the CLI loads the model once for all of them), so a primary declared as a
+ * string list becomes several positionals. Everything else becomes an option,
+ * with lists comma-joined because the CLI's option syntax is `key=value`.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the positional inputs and the option list.
+ */
+export function splitArguments(entry, args) {
+    const names = Object.keys(entry.tool.params);
+    const primaryName = names[0];
+    if (primaryName === undefined) {
+        throw new Error(`${entry.name} declares no parameters, so its input cannot be addressed`);
+    }
+    const primaryValue = args[primaryName];
+    let positionals;
+    if (typeof primaryValue === 'string' && primaryValue.length > 0) {
+        positionals = [primaryValue];
+    }
+    else if (Array.isArray(primaryValue) && primaryValue.length > 0
+        && primaryValue.every(item => typeof item === 'string' && item.length > 0)) {
+        positionals = primaryValue;
+    }
+    else {
+        throw new Error(`argument "${primaryName}" must be a non-empty string or list of paths`);
+    }
+    const options = [];
+    for (const name of names.slice(1)) {
+        const value = args[name];
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            options.push([name.replaceAll('_', '-'), value.map(String).join(',')]);
+        }
+        else if (typeof value === 'boolean' || typeof value === 'number') {
+            options.push([name.replaceAll('_', '-'), String(value)]);
+        }
+        else if (typeof value === 'string') {
+            options.push([name.replaceAll('_', '-'), value]);
+        }
+        else {
+            throw new Error(`argument "${name}" must be a string, number, boolean or string list`);
+        }
+    }
+    return { positionals, options };
+}
+/**
+ * Build the CLI argv for one invocation.
+ *
+ * `--json` is what makes stdout a single JSON value, and it also implies
+ * `--no-color`, so no escape sequences have to be stripped.
+ * @param entry - the catalog entry being invoked.
+ * @param args - validated tool arguments.
+ * @returns the argv to run, after the command itself.
+ */
+export function buildArgv(entry, args) {
+    const verb = entry.cliVerb;
+    if (verb === null)
+        throw new Error(`${entry.name} has no CLI verb, so the CLI cannot run it`);
+    const { positionals, options } = splitArguments(entry, args);
+    const argv = [verb, ...positionals, '--json'];
+    for (const [key, value] of options)
+        argv.push('--option', `${key}=${value}`);
+    return argv;
+}
+/**
+ * Parse the CLI's stdout into a canonical value.
+ *
+ * The CLI writes exactly one JSON value to stdout under `--json` and keeps every
+ * diagnostic on stderr, so a parse failure means the command did not behave as
+ * documented rather than that output needs cleaning.
+ * @param entry - the model, for error messages.
+ * @param outcome - the completed command.
+ * @returns the parsed value.
+ * @throws when the exit code is non-zero or stdout is not a single JSON value.
+ */
+export function parseCliOutcome(entry, outcome) {
+    if (outcome.code === CLI_EXIT_USAGE_ERROR) {
+        throw new Error(`${entry.name}: the CLI rejected the call (exit 64). ${outcome.stderr.trim() || 'usage error'}`);
+    }
+    if (outcome.code === CLI_EXIT_RUNTIME_ERROR) {
+        throw new Error(`${entry.name} failed (exit 1). ${outcome.stderr.trim() || 'runtime error'}`);
+    }
+    if (outcome.code !== 0) {
+        throw new Error(`${entry.name}: the CLI exited ${outcome.code}. ${outcome.stderr.trim() || 'unknown failure'}`);
+    }
+    const text = outcome.stdout.trim();
+    if (text.length === 0) {
+        throw new Error(`${entry.name}: the CLI produced no JSON on stdout`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${entry.name}: the CLI stdout was not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return asRecord(entry, parsed);
+}
+/**
+ * Wrap a JSON value as the object a tool output schema requires.
+ * @param entry - the model, for error messages.
+ * @param value - the parsed value.
+ * @returns the value as a record; a non-object is wrapped under `result`.
+ */
+function asRecord(entry, value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    if (Array.isArray(value))
+        return { result: value };
+    // A scalar result is still a result; naming it keeps the output contract
+    // stable instead of failing a call that actually succeeded.
+    void entry;
+    return { result: value };
+}
+/** Spawn a command and capture its output. */
+export const spawnRunner = (command, argv, signal) => new Promise((resolve, reject) => {
+    // `shell: false` keeps argv elements from being re-interpreted by a shell,
+    // so a model input containing quotes or `&` cannot become a second command.
+    const child = spawn(command, [...argv], { shell: false, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const onAbort = () => {
+        if (settled)
+            return;
+        settled = true;
+        child.kill();
+        reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+    };
+    if (signal.aborted) {
+        onAbort();
+        return;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => {
+        if (settled)
+            return;
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        reject(new Error(`cannot run "${command}": ${error.message}`));
+    });
+    child.on('close', (code) => {
+        if (settled)
+            return;
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        resolve({ code: code ?? -1, stdout, stderr });
+    });
+});
+/** POST JSON with the global fetch and read the response as text. */
+export const fetchPost = async (url, body, headers, signal) => {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+        signal,
+    });
+    return { status: response.status, body: await response.text() };
+};
+/**
+ * Build the CLI transport for one model.
+ * @param entry - the catalog entry, which must declare a CLI verb.
+ * @param options - command name and injected runner.
+ * @returns the transport.
+ */
+export function createCliTransport(entry, options = {}) {
+    const command = options.cliCommand ?? DEFAULT_CLI_COMMAND;
+    const run = options.run ?? spawnRunner;
+    return {
+        kind: 'cli',
+        async invoke({ args, signal }) {
+            throwIfAborted(signal);
+            const argv = buildArgv(entry, args);
+            const outcome = await run(command, argv, signal);
+            throwIfAborted(signal);
+            return parseCliOutcome(entry, outcome);
+        },
+    };
+}
+/**
+ * Build the remote transport for one model.
+ *
+ * The bridge contract is deliberately small so a user can implement it in a few
+ * lines on a machine that can run the model:
+ *
+ * ```
+ * POST <endpoint>/invoke
+ *   { "model": "title", "verb": "title", "input": "<primary>", "options": { "max-tokens": "96" } }
+ *   → 200 { "ok": true,  "result": <the model's JSON> }
+ *   → 4xx { "ok": false, "error": "<message>" }
+ * ```
+ * @param entry - the catalog entry to reach.
+ * @param options - endpoint, optional token, injected poster.
+ * @returns the transport.
+ */
+export function createRemoteTransport(entry, options = {}) {
+    const endpoint = options.endpoint;
+    if (endpoint === undefined || endpoint.length === 0) {
+        throw new Error('the remote transport requires an endpoint');
+    }
+    const post = options.post ?? fetchPost;
+    const url = `${endpoint.replace(/\/+$/, '')}${BRIDGE_PATH}`;
+    const headers = options.token === undefined
+        ? {}
+        : { authorization: `Bearer ${options.token}` };
+    return {
+        kind: 'remote',
+        async invoke({ args, signal }) {
+            throwIfAborted(signal);
+            const verb = entry.cliVerb;
+            if (verb === null)
+                throw new Error(`${entry.name} declares no verb for the bridge to run`);
+            const { positionals, options: flags } = splitArguments(entry, args);
+            const response = await post(url, {
+                model: entry.id,
+                verb,
+                // A file model may pass several paths; `input` carries them all so the
+                // bridge does not have to know which models take more than one.
+                input: positionals.length === 1 ? positionals[0] : positionals,
+                options: Object.fromEntries(flags),
+            }, headers, signal);
+            throwIfAborted(signal);
+            return parseBridgeResponse(entry, response);
+        },
+    };
+}
+/**
+ * Interpret one bridge response.
+ * @param entry - the model, for error messages.
+ * @param response - the HTTP status and body.
+ * @returns the model's result as a canonical value.
+ * @throws when the bridge reports a failure or an unreadable body.
+ */
+export function parseBridgeResponse(entry, response) {
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        throw new Error(`${entry.name}: the bridge returned a non-JSON body (HTTP ${response.status})`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${entry.name}: the bridge returned an unexpected body shape`);
+    }
+    const envelope = parsed;
+    if (envelope.ok !== true) {
+        const detail = typeof envelope.error === 'string' ? envelope.error : `HTTP ${response.status}`;
+        throw new Error(`${entry.name}: the bridge could not run the model. ${detail}`);
+    }
+    return asRecord(entry, envelope.result);
+}
+//# sourceMappingURL=transport.js.map

package/lib/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Data model for the Desert Ant Labs model catalog and the capability layer
+ * that decides whether a model can actually run in the current DSH process.
+ *
+ * @module @try-works/dsh-model-as-tool/types
+ */
+/** The kind of value a model consumes. */
+export type ModelInput = 'text' | 'audio' | 'image' | 'video' | 'stroke' | 'transcript';
+/**
+ * How the model's weights are reachable from a Node process on each platform.
+ * This is the field the capability resolver keys off, because it encodes the
+ * upstream packaging reality rather than an aspiration.
+ */
+export type WindowsSupport = 
+/** Ships a prebuilt native core for this platform and works in plain Node. */
+'native-node'
+/** Needs a caller-supplied ONNX Runtime module (e.g. `onnxruntime-node`). */
+ | 'onnxruntime-node'
+/** No Node runtime anywhere: Apple platforms only, through the Swift SDK. */
+ | 'apple-only'
+/** Prebuilt native core exists, but not for this platform/arch. */
+ | 'browser-only'
+/** Weights exist but no SDK ships them at all. */
+ | 'no-sdk';
+/** The JSON-level type of one tool parameter. */
+export type ModelParamType = 'string' | 'number' | 'integer' | 'boolean' | 'string[]';
+/**
+ * One declared tool parameter.
+ *
+ * A bare string is shorthand for `{ type: 'string', description }`, which is
+ * what most of the catalog's parameters are; the object form exists for the
+ * parameters that are genuinely numbers, booleans or string lists.
+ */
+export interface ModelParam {
+    /** Model-facing description of the parameter. */
+    readonly description: string;
+    /** Declared type; defaults to `string`. */
+    readonly type?: ModelParamType;
+}
+/** One parameter as written in the catalog document. */
+export type ModelParamSpec = string | ModelParam;
+/** The model-facing tool a catalog entry installs. */
+export interface ModelToolSpec {
+    /** DSH tool name (lower snake_case). */
+    readonly name: string;
+    /** Model-facing description of the tool. */
+    readonly description: string;
+    /** Parameter name -> declaration, in documentation order; the first is the primary input. */
+    readonly params: Readonly<Record<string, ModelParam>>;
+    /** What the tool returns. */
+    readonly returns: string;
+}
+/** The skill a catalog entry publishes alongside its tool. */
+export interface ModelSkillSpec {
+    /** Kebab-case skill name. */
+    readonly name: string;
+    /** Short routing description for the skill catalog. */
+    readonly description: string;
+    /** Optional extra routing guidance. */
+    readonly whenToUse?: string;
+}
+/** One model in the Desert Ant Labs catalog. */
+export interface ModelCatalogEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly summary: string;
+    readonly capability: string;
+    readonly input: ModelInput;
+    readonly output: string;
+    readonly languages: number | null;
+    readonly modelSizeMB: number | null;
+    readonly appleOnly: boolean;
+    readonly closedBeta: boolean;
+    /** True only where this repository verified a real inference on Windows x64. */
+    readonly verifiedRunnableOnWindows: boolean;
+    readonly windowsSupport: WindowsSupport;
+    readonly npmPackage: string | null;
+    readonly npmSubpath: string | null;
+    readonly requiresRuntime: readonly string[];
+    readonly cliVerb: string | null;
+    readonly license: string;
+    readonly docsUrl: string;
+    readonly hfRepo: string;
+    readonly tool: ModelToolSpec;
+    readonly skill: ModelSkillSpec;
+}
+/** How an adapter reaches a model at run time. */
+export type ModelRoute = 
+/** An npm package loaded in this process. */
+'npm-native'
+/** An npm package plus a caller-supplied ONNX Runtime module. */
+ | 'npm-onnxruntime'
+/** The Desert Ant CLI, run as a child process (macOS and Linux). */
+ | 'cli'
+/** A user-hosted bridge, reached over HTTP. */
+ | 'remote'
+/** No route available in this process. */
+ | 'unavailable';
+/** The capability resolver's verdict for one model in the current process. */
+export interface CapabilityVerdict {
+    /** Whether an adapter can actually produce a working tool for this model. */
+    readonly runnable: boolean;
+    readonly route: ModelRoute;
+    /** Why the model is or is not runnable, always populated for a negative verdict. */
+    readonly reason: string;
+    /** Resolved package specifiers this verdict depended on, for diagnostics. */
+    readonly resolved?: readonly string[];
+    /** Resolved package specifiers that were required but missing. */
+    readonly missing?: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAA;AAEvF;;;;GAIG;AACH,MAAM,MAAM,cAAc;AACxB,8EAA8E;AAC5E,aAAa;AACf,6EAA6E;GAC3E,kBAAkB;AACpB,6EAA6E;GAC3E,YAAY;AACd,mEAAmE;GACjE,cAAc;AAChB,kDAAkD;GAChD,QAAQ,CAAA;AAEZ,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;AAErF;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,CAAA;AAEhD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IACrD,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAA;IAC3C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAC/B;AAED,kDAAkD;AAClD,MAAM,MAAM,UAAU;AACpB,6CAA6C;AAC3C,YAAY;AACd,iEAAiE;GAC/D,iBAAiB;AACnB,oEAAoE;GAClE,KAAK;AACP,+CAA+C;GAC7C,QAAQ;AACV,0CAA0C;GACxC,aAAa,CAAA;AAEjB,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC"}

package/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * Data model for the Desert Ant Labs model catalog and the capability layer
+ * that decides whether a model can actually run in the current DSH process.
+ *
+ * @module @try-works/dsh-model-as-tool/types
+ */
+export {};
+//# sourceMappingURL=types.js.map