@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/capabilities/model3d.specs.js

@@ -0,0 +1,305 @@
+/**
+ * The `model3d` module's specs — data only, no implementation.
+ *
+ * Split out for the same reason every other module splits: the registry's
+ * eager spec table imports this file and never the implementation, so nothing
+ * `model3d.ts` pulls in reaches the entry graph.
+ */
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+/** Operations one `edit_model3d` call may apply. */
+export const MAX_OPS = 60;
+const MODEL_ID_PROPERTY = {
+    type: "string",
+    description: "The 3D model's asset id, from list_model3ds or create_model3d. An " +
+        "`asset://<id>.glb` URI is accepted too."
+};
+const TARGET_PROPERTY = {
+    type: "string",
+    description: "The object's uuid or its name (case-insensitive)."
+};
+const VEC3_PROPERTY = {
+    type: "array",
+    items: { type: "number" },
+    minItems: 3,
+    maxItems: 3,
+    description: "An [x, y, z] triple."
+};
+export const LIST_MODEL3DS_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Only models whose name contains this text (case-insensitive)."
+        },
+        limit: {
+            type: "number",
+            description: `Max models to return (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}).`
+        }
+    }
+};
+export const listModel3dsSpec = {
+    name: "list_model3ds",
+    description: "List the 3D models (.glb/.gltf assets) in the library, newest first, " +
+        "with each one's asset id, name, content type and size. The starting " +
+        "point for every other 3D capability, which address a model by asset id.",
+    inputSchema: LIST_MODEL3DS_SCHEMA,
+    category: "read",
+    userMessage: () => "Listing 3D models"
+};
+export const CREATE_MODEL3D_SCHEMA = {
+    type: "object",
+    properties: {
+        name: {
+            type: "string",
+            description: "File name for the new model, e.g. \"studio.gltf\"."
+        },
+        ops: {
+            type: "array",
+            items: { type: "object" },
+            description: "Optional scene operations to apply to the new document, in the same " +
+                "form edit_model3d takes. A scene built in one call."
+        }
+    },
+    required: ["name"]
+};
+export const createModel3dSpec = {
+    name: "create_model3d",
+    description: "Create a 3D model asset holding an empty glTF scene, optionally " +
+        "applying scene operations to it in the same call. Returns the asset id " +
+        "to pass to get_model3d and edit_model3d. Use this when there is nothing " +
+        "to start from; to change an existing model, edit it in place instead.",
+    inputSchema: CREATE_MODEL3D_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Creating 3D model ${String(params["name"])}`
+};
+export const GET_MODEL3D_SCHEMA = {
+    type: "object",
+    properties: {
+        model_id: MODEL_ID_PROPERTY
+    },
+    required: ["model_id"]
+};
+export const getModel3dSpec = {
+    name: "get_model3d",
+    description: "List every object in a 3D model's scene with its uuid, name, type, " +
+        "visibility, transform (position, rotation in degrees, scale) and " +
+        "material color, plus the scene's world-space bounds. Call this first to " +
+        "see what is in a model and to get the uuids the edit operations take. " +
+        "This is the headless twin of ui_3d_list_scene, and needs no open editor.",
+    inputSchema: GET_MODEL3D_SCHEMA,
+    category: "read",
+    userMessage: (params) => `Reading 3D model ${String(params["model_id"])}`
+};
+export const EDIT_MODEL3D_SCHEMA = {
+    type: "object",
+    properties: {
+        model_id: MODEL_ID_PROPERTY,
+        ops: {
+            type: "array",
+            description: `Operations to apply in order (at most ${MAX_OPS}).`,
+            items: {
+                type: "object",
+                properties: {
+                    op: {
+                        type: "string",
+                        enum: [
+                            "add_object",
+                            "delete_object",
+                            "set_transform",
+                            "set_visibility",
+                            "rename_object",
+                            "set_material_color",
+                            "select_object"
+                        ],
+                        description: "Which operation this entry applies."
+                    },
+                    kind: {
+                        type: "string",
+                        enum: [
+                            "box",
+                            "sphere",
+                            "plane",
+                            "cylinder",
+                            "torus",
+                            "directionalLight",
+                            "pointLight"
+                        ],
+                        description: "add_object: the primitive to add."
+                    },
+                    name: {
+                        type: "string",
+                        description: "add_object: an optional name (a unique default is assigned " +
+                            "otherwise). rename_object: the new name."
+                    },
+                    target: {
+                        ...TARGET_PROPERTY,
+                        description: TARGET_PROPERTY.description +
+                            " Pass null on select_object to clear the selection."
+                    },
+                    position: { ...VEC3_PROPERTY, description: "set_transform: [x, y, z] position." },
+                    rotation: {
+                        ...VEC3_PROPERTY,
+                        description: "set_transform: [x, y, z] Euler rotation in degrees."
+                    },
+                    scale: { ...VEC3_PROPERTY, description: "set_transform: [x, y, z] scale." },
+                    visible: {
+                        type: "boolean",
+                        description: "set_visibility: whether the object renders."
+                    },
+                    color: {
+                        type: "string",
+                        description: "set_material_color: a CSS hex string like \"#ff8800\". Meshes only."
+                    }
+                },
+                required: ["op"]
+            }
+        }
+    },
+    required: ["model_id", "ops"]
+};
+export const editModel3dSpec = {
+    name: "edit_model3d",
+    description: "Edit a 3D model's scene headlessly: add and delete primitives and " +
+        "lights, set transforms (rotation in degrees), rename, show and hide, " +
+        "recolor a mesh's material, and set the selected object. Operations run " +
+        "in order against the stored glTF and the result is saved back to the " +
+        "same asset, so the id stays valid and an open editor reloads it. These " +
+        "are the ui_3d_* verbs with no editor open. Anything the operations do " +
+        "not name — meshes, textures, animations — is kept as it was. Call " +
+        "get_model3d for the uuids and validate_model3d afterwards.",
+    inputSchema: EDIT_MODEL3D_SCHEMA,
+    category: "write",
+    userMessage: (params) => {
+        const count = Array.isArray(params["ops"]) ? params["ops"].length : 0;
+        return `Editing 3D model ${String(params["model_id"])} (${count} ops)`;
+    }
+};
+export const VALIDATE_MODEL3D_SCHEMA = {
+    type: "object",
+    properties: {
+        model_id: MODEL_ID_PROPERTY,
+        document: {
+            type: "object",
+            description: "An inline glTF 2.0 JSON document to check instead of a stored one."
+        }
+    }
+};
+export const RENDER_MODEL3D_SCHEMA = {
+    type: "object",
+    properties: {
+        background: {
+            type: "boolean",
+            description: "Return at once with a generation_id while Blender renders; collect the result with await_generation. At most 16 open per run.",
+            default: false
+        },
+        model_id: MODEL_ID_PROPERTY,
+        camera_mode: {
+            type: "string",
+            enum: ["auto", "scene", "orbit"],
+            description: "Whose camera renders: auto (the scene's first camera when the " +
+                "model has one, else an orbit camera), scene (the scene's first " +
+                "camera; an error when the model has none), or orbit (always an " +
+                "orbit camera from the props below)."
+        },
+        width: {
+            type: "number",
+            description: "Output image width in pixels (default 1024)."
+        },
+        height: {
+            type: "number",
+            description: "Output image height in pixels (default 1024)."
+        },
+        azimuth: {
+            type: "number",
+            description: "Horizontal camera orbit angle in degrees (default 45; orbit cameras only)."
+        },
+        elevation: {
+            type: "number",
+            description: "Camera angle above the horizon in degrees (default 25; orbit cameras only)."
+        },
+        fov: {
+            type: "number",
+            description: "Vertical field of view in degrees (default 35; orbit cameras only)."
+        },
+        zoom: {
+            type: "number",
+            description: "Distance multiplier on the auto-framed camera (default 1; orbit cameras only)."
+        },
+        lighting: {
+            type: "string",
+            enum: ["studio", "soft", "flat"],
+            description: "Lighting preset used when the scene carries no lights of its own (default studio)."
+        },
+        light_intensity: {
+            type: "number",
+            description: "Multiplier applied to all lights in the preset (default 1)."
+        },
+        background_color: {
+            type: "string",
+            description: "Background hex color, ignored when transparent (default #808080)."
+        },
+        transparent: {
+            type: "boolean",
+            description: "Render on a transparent background (default false)."
+        },
+        engine: {
+            type: "string",
+            enum: ["eevee", "cycles"],
+            description: "Render engine: eevee (fast) or cycles (slower, higher quality; default eevee)."
+        },
+        samples: {
+            type: "number",
+            description: "Render samples per pixel (default 16)."
+        },
+        denoise: {
+            type: "boolean",
+            description: "Denoise the render (default true; Cycles only)."
+        },
+        resolution_percentage: {
+            type: "number",
+            description: "Render scale in percent of width x height (default 100)."
+        },
+        timeout: {
+            type: "number",
+            description: "Maximum render time in seconds (default 600)."
+        }
+    },
+    required: ["model_id"]
+};
+export const renderModel3dSpec = {
+    name: "render_model3d",
+    description: "Render a 3D model to a PNG image with headless Blender (EEVEE or " +
+        "Cycles) — higher quality than the preview renderer, with scene cameras " +
+        "and lights honored. Takes the render_image node params and stores the " +
+        "PNG as an image asset. Needs Blender on the server.",
+    inputSchema: RENDER_MODEL3D_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Rendering 3D model ${String(params["model_id"])}`
+};
+export const validateModel3dSpec = {
+    name: "validate_model3d",
+    description: "Statically validate a 3D model WITHOUT rendering it: the glTF version, " +
+        "node/mesh/accessor/material/buffer references that resolve to nothing, " +
+        "a cycle in the node hierarchy, a node carrying both a matrix and TRS " +
+        "fields, a buffer view reading past its buffer, a light the document does " +
+        "not declare, and an extension this build cannot honor. Warns about an " +
+        "empty scene, geometry with no light, and duplicate names that make " +
+        "addressing by name ambiguous. Pass `model_id` for a stored model or " +
+        "`document` for one you are building.",
+    inputSchema: VALIDATE_MODEL3D_SCHEMA,
+    category: "read",
+    userMessage: (params) => params["model_id"]
+        ? `Validating 3D model ${String(params["model_id"])}`
+        : "Validating glTF document"
+};
+/** Every spec this module declares, in declaration order. */
+export const model3dSpecs = [
+    listModel3dsSpec,
+    createModel3dSpec,
+    getModel3dSpec,
+    editModel3dSpec,
+    validateModel3dSpec,
+    renderModel3dSpec
+];
+//# sourceMappingURL=model3d.specs.js.map

package/dist/capabilities/model3d.specs.js.map

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

package/dist/capabilities/models.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The `models` capability module — model discovery over the configured
+ * providers.
+ *
+ * Three capabilities that used to be three `Tool` subclasses, one per file.
+ * Wire names, descriptions and schemas are unchanged: a belt builds them
+ * from `models.specs.ts` by name.
+ *
+ * The providers map was a constructor argument and is now `run.providers`. It
+ * is read at call time, so a host that fills the map lazily — the MCP mount
+ * does — still serves the models it resolved after construction.
+ *
+ * `find_model` is where an agent's default model choice is made: with no hint
+ * from the caller it answers with the model that tops the quality leaderboard
+ * for the task (see {@link SCORE_TIERS}), so an agent that just asks for a
+ * capability gets the best model for the job rather than the first one a
+ * provider happens to list.
+ *
+ * Design: docs/tool-class-retirement-design.md § Migration.
+ */
+import type { ModelRankingsArtifact, RankedModelEntry, TaskRank } from "@nodetool-ai/model-pricing/model-rankings";
+import type { CapabilityExport, CapabilityModule } from "./types.js";
+interface AnyModel {
+    id: string;
+    name: string;
+    provider: string;
+    supportedTasks?: string[];
+}
+/**
+ * The score ladder. Each tier outranks the sum of every tier below it, so the
+ * order between two candidates is a decision rather than an arithmetic
+ * accident:
+ *
+ * | tier | addend | when |
+ * |---|---:|---|
+ * | model hint | 2000 | the caller named this model |
+ * | provider hint | 1000 | the caller named this provider |
+ * | prefer_local | 500 | the caller asked for local and this runs locally |
+ * | leaderboard | 200 + 0…80 | the artifact ranks this model for the task |
+ * | recommended | 100 | `RECOMMENDED_MODELS` pins it and nothing ranks it |
+ * | downloaded | 30 | a local provider serves it |
+ *
+ * What the ladder decides: with no hint from the caller, the default pick is
+ * the model that tops the leaderboard for the task — `find_model`, and so
+ * `nodetool.models.pick`, answer with the best model for the job rather than
+ * with whichever one the static `RECOMMENDED_MODELS` list happens to pin.
+ * The pinned list still orders what the artifact says nothing about: language,
+ * embedding and ASR models, local models, and any model the rankings have
+ * never heard of.
+ *
+ * A caller's own preference still wins: naming a provider or a model, or
+ * asking for local, outranks any leaderboard position. Rankings order the
+ * field; they never overrule the caller.
+ */
+export declare const SCORE_TIERS: {
+    readonly modelHint: 2000;
+    readonly providerHint: 1000;
+    readonly preferLocal: 500;
+    readonly ranked: 200;
+    readonly recommended: 100;
+    readonly downloaded: 30;
+    /** Nudge against a hosted model when the caller asked for local. */
+    readonly remote: -5;
+};
+/** The most a leaderboard *position* adds, on top of {@link SCORE_TIERS}.ranked. */
+export declare const RANK_BONUS_MAX = 80;
+/** One alternate provider route to the same canonical model. */
+interface RouteRef {
+    provider: string;
+    model_id: string;
+}
+/**
+ * What the rankings artifact adds to a candidate. Every field is omitted when
+ * the artifact says nothing, so an unranked model's result is the same shape
+ * `find_model` returned before rankings existed.
+ */
+export interface CandidateRankingFields {
+    /** The leaderboard's own slug — the id grouping this route with its siblings. */
+    canonical?: string;
+    /** The task whose leaderboard `rank`/`of` refer to. */
+    ranked_task?: string;
+    rank?: number;
+    of?: number;
+    /** Other providers serving the same canonical model. */
+    alternate_routes?: RouteRef[];
+}
+/** A candidate's ranking: the score addend and the fields to attach. */
+export interface CandidateRanking {
+    bonus: number;
+    fields: CandidateRankingFields;
+}
+/**
+ * The leaderboard row to report for a candidate: the requested task's, or —
+ * when the caller named no task and the capability is one rankings cover —
+ * the task where the model's `score` is highest.
+ */
+export declare function pickTaskRank(entry: RankedModelEntry, task: string | undefined, allowBestTask: boolean): {
+    task: string;
+    rank: TaskRank;
+} | null;
+/**
+ * Score addend and answer fields for one candidate route. Pure in the
+ * artifact so tests drive it with a fixture instead of mocking the module.
+ */
+export declare function rankCandidate(provider: string, modelId: string, task: string | undefined, allowBestTask: boolean, artifact?: ModelRankingsArtifact): CandidateRanking;
+/** Everything the ranking of one candidate depends on. */
+export interface CandidateScoreInput {
+    providerId: string;
+    model: AnyModel;
+    /** Whether the model is in `RECOMMENDED_MODELS` for this capability. */
+    recommended: boolean;
+    /** The requested task, or undefined when the caller named none. */
+    task?: string;
+    providerHint?: string;
+    modelHints: Set<string>;
+    preferLocal: boolean;
+    /** Whether rankings cover this capability — see {@link RANKED_CAPABILITIES}. */
+    rankedCapability: boolean;
+}
+/**
+ * One candidate's score and the ranking fields to attach to it. Additive and
+ * pure in the artifact, so the ordering between an explicit hint and a
+ * leaderboard position is pinned by a unit test with a fixture rather than by
+ * reading the constants.
+ */
+export declare function scoreCandidate(input: CandidateScoreInput, artifact?: ModelRankingsArtifact): {
+    score: number;
+    downloaded: boolean;
+    fields: CandidateRankingFields;
+};
+declare const findModel: CapabilityExport;
+declare const listModels: CapabilityExport;
+declare const listProviderModels: CapabilityExport;
+/** Every model capability, in the order `getAllMcpTools` offered them. */
+export declare const MODEL_CAPABILITIES: readonly CapabilityExport[];
+export declare const module: CapabilityModule;
+export { findModel, listModels, listProviderModels };
+//# sourceMappingURL=models.d.ts.map

package/dist/capabilities/models.d.ts.map

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