@google-cloud/kcmd 0.0.0-stage → 0.1.0

package/build/ts/kcmd/semantic/runtime/agent_tools.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Deriving action tools and schema metadata for a bound semantic model.
+ *
+ * An action declares a name, a description of what it does, its typed
+ * parameters, the guidance an AI caller should follow
+ * (`ai_context.instructions`), and the rules that gate it (`guards`). This
+ * module resolves those declarations against the active binding profile so
+ * `kcmd skills-generate` can render the model as an Agent Skill.
+ */
+import { Entity } from '../ir';
+import { SqlDialect } from './dialect';
+import { SemanticRuntime } from './runtime';
+/** The JSON types a tool parameter can take. */
+export type ToolParameterType = 'string' | 'number' | 'integer' | 'boolean';
+/** One argument a tool accepts, derived from an action parameter. */
+export interface ToolParameter {
+    name: string;
+    type: ToolParameterType;
+    /** What to pass, in the words the model's own types justify. */
+    description: string;
+    /**
+     * Whether the caller must supply this argument. An action parameter is
+     * required unless declared `required: false` or given a `default`.
+     */
+    required: boolean;
+    /**
+     * The default value substituted when the caller omits the argument, if any.
+     */
+    default?: unknown;
+}
+/** One tool, derived from one action. */
+export interface ActionTool {
+    /** The action name in snake_case, which is what tool APIs expect. */
+    name: string;
+    /** The action this tool calls, by its authored name. */
+    actionName: string;
+    parameters: ToolParameter[];
+    /**
+     * Whether this action can run under the active binding profile. False when
+     * the profile supplies no executor, when a `sql` executor has no operational
+     * store, or when the action names a guard that is undeclared or states no
+     * rule text.
+     */
+    runnable: boolean;
+    /** Why `runnable` is false, in words a caller can report. */
+    unavailable?: string;
+}
+export interface ActionToolOptions {
+    /** The model to derive tools from, and the store they would run against. */
+    runtime: SemanticRuntime;
+}
+/**
+ * One tool per action the model declares, in declaration order.
+ *
+ * A model with no actions yields no tools, which is the honest answer: an
+ * agent over a read-only model has nothing to call.
+ */
+export declare function actionTools(opts: ActionToolOptions): ActionTool[];
+/** Everything a model offers an agent, in one name space. */
+export interface ModelTools {
+    /** One write per action. */
+    actions: ActionTool[];
+    /**
+     * What to tell an agent holding these tools: the model's own
+     * `ai_context.instructions` followed by how the tools are meant to be used.
+     */
+    instruction: string;
+}
+/**
+ * Every tool a model offers, with the names guaranteed distinct.
+ */
+export declare function modelTools(opts: ActionToolOptions): ModelTools;
+interface BoundField {
+    name: string;
+    type: string;
+    column: string;
+    /** What the model says this field holds, if it says anything. */
+    description?: string;
+}
+/**
+ * An entity a statement can name: one table, and the columns behind it.
+ */
+export interface ReadableEntity {
+    entity: Entity;
+    table: string;
+    fields: BoundField[];
+}
+/**
+ * What there is to read under this runtime: one entry per entity the model
+ * declares, the profile binds to a table, and a statement can name.
+ */
+export declare function readableEntities(runtime: SemanticRuntime, dialect: SqlDialect): ReadableEntity[];
+export {};

package/build/ts/kcmd/semantic/runtime/agent_tools.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Deriving action tools and schema metadata for a bound semantic model.
+ *
+ * An action declares a name, a description of what it does, its typed
+ * parameters, the guidance an AI caller should follow
+ * (`ai_context.instructions`), and the rules that gate it (`guards`). This
+ * module resolves those declarations against the active binding profile so
+ * `kcmd skills-generate` can render the model as an Agent Skill.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actionTools = actionTools;
+exports.modelTools = modelTools;
+exports.readableEntities = readableEntities;
+const binding_1 = require("../binding");
+const ir_1 = require("../ir");
+const sql_expr_utils_1 = require("../sql_expr_utils");
+const runtime_1 = require("./runtime");
+/**
+ * One tool per action the model declares, in declaration order.
+ *
+ * A model with no actions yields no tools, which is the honest answer: an
+ * agent over a read-only model has nothing to call.
+ */
+function actionTools(opts) {
+    return (opts.runtime.model.actions ?? [])
+        .map(action => toolFor(action, opts));
+}
+function toolFor(action, opts) {
+    const blocked = whyRefusedWithoutRunning(opts.runtime, action) ?? undefined;
+    const tool = {
+        name: snakeCase(action.name),
+        actionName: action.name,
+        parameters: action.parameters.map(toolParameter),
+        runnable: !blocked,
+    };
+    if (blocked)
+        tool.unavailable = blocked;
+    return tool;
+}
+function whyRefusedWithoutRunning(runtime, action) {
+    const model = runtime.model;
+    const executor = action.executor;
+    if (!executor) {
+        return `Action '${action.name}' has no executor under this binding, so ` +
+            `there is nothing to run. An executor is a physical binding: a ` +
+            `profile supplies one, and a profile that writes 'executor: null' ` +
+            `withdraws it. The action is still declared and still published; it ` +
+            `is only not performable here, and is performed somewhere else.`;
+    }
+    const advisory = new Set((model.constraints ?? [])
+        .filter(c => c.onViolation === 'warn')
+        .map(c => c.name));
+    const guards = (action.guards ?? []).filter(g => !advisory.has(g));
+    const blank = (model.constraints ?? [])
+        .filter(c => guards.includes(c.name) && !(c.judgment ?? '').trim())
+        .map(c => c.name);
+    if (blank.length) {
+        const says = blank.length === 1 ? 'states no rule to put to a judge' :
+            'state no rule to put to a judge';
+        return `Action '${action.name}' is guarded by ${quoteList(blank)}, ` +
+            `which ${says}. There is nothing to put to a judge, so the action ` +
+            `is refused rather than run unchecked.`;
+    }
+    const declared = new Set((model.constraints ?? []).map(c => c.name));
+    const undeclared = guards.filter(g => !declared.has(g));
+    if (undeclared.length) {
+        return `Action '${action.name}' is guarded by ${quoteList(undeclared)}, ` +
+            `which ${undeclared.length === 1 ? 'is' : 'are'} not declared by ` +
+            `model '${model.name}'. Running it would apply a write the model says ` +
+            `must be checked first, so it is refused rather than run unchecked.`;
+    }
+    if (executor.kind === 'sql') {
+        return (0, runtime_1.runtimeStoreError)(runtime);
+    }
+    return null;
+}
+function quoteList(names) {
+    const quoted = names.map(n => `'${n}'`);
+    if (quoted.length === 1)
+        return quoted[0];
+    return `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}`;
+}
+function isParameterRequired(param) {
+    if (param.default !== undefined)
+        return false;
+    return param.required !== false;
+}
+function sentence(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return '';
+    return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+function toolParameter(param) {
+    const said = param.description?.trim();
+    const guidance = scalarFormatGuidance(param.type);
+    const out = {
+        name: param.name,
+        type: jsonType(param.type),
+        description: said ?
+            (guidance ? `${sentence(said)} ${guidance}` : sentence(said)) :
+            `The ${param.name}, as ${article(param.type)}.`,
+        required: isParameterRequired(param),
+    };
+    if (param.default !== undefined)
+        out.default = param.default;
+    return out;
+}
+function scalarFormatGuidance(dataType) {
+    switch (dataType) {
+        case 'Date':
+        case 'Time':
+        case 'DateTime':
+        case 'DateTimeTz':
+            return `As ${article(dataType)}.`;
+        default:
+            return undefined;
+    }
+}
+function jsonType(dataType) {
+    switch (dataType) {
+        case 'Integer':
+            return 'integer';
+        case 'Decimal':
+        case 'Float':
+            return 'number';
+        case 'Boolean':
+            return 'boolean';
+        default:
+            return 'string';
+    }
+}
+function article(dataType) {
+    switch (dataType) {
+        case 'Integer':
+            return 'a whole number';
+        case 'Decimal':
+            return 'a decimal number';
+        case 'Float':
+            return 'a number';
+        case 'Boolean':
+            return 'true or false';
+        case 'Date':
+            return 'a date, YYYY-MM-DD';
+        case 'Time':
+            return 'a time, HH:MM:SS';
+        case 'DateTime':
+        case 'DateTimeTz':
+            return 'a timestamp in RFC 3339 form';
+        default:
+            return 'text';
+    }
+}
+function snakeCase(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/[\s-]+/g, '_')
+        .toLowerCase();
+}
+/**
+ * Every tool a model offers, with the names guaranteed distinct.
+ */
+function modelTools(opts) {
+    const actions = actionTools(opts);
+    const taken = new Set();
+    for (const tool of actions) {
+        tool.name = distinct(tool.name, taken);
+    }
+    return {
+        actions,
+        instruction: instructionFor(opts.runtime.model),
+    };
+}
+function instructionFor(model) {
+    const parts = [];
+    const stated = model.aiContext?.instructions?.trim();
+    if (stated)
+        parts.push(stated);
+    parts.push('Never invent an identifier. When you are given a name or a ' +
+        'description where an action wants a key, ask the caller or read the ' +
+        'store directly. Check every rule that gates an action before running ' +
+        'it: when a rule says a write must not happen, refuse and explain why; ' +
+        'when it says a person has to decide, say so and stop, because you ' +
+        'cannot approve it yourself; when an advisory rule goes unmet, report ' +
+        'both the change and the warning. Finish by saying what you changed.');
+    return parts.join('\n\n');
+}
+function distinct(base, taken) {
+    let name = base;
+    for (let n = 2; taken.has(name); n++)
+        name = `${base}_${n}`;
+    taken.add(name);
+    return name;
+}
+// The fields of `entity` bound to one column each. A binding is read without
+// its comments, as the graph generators read it, so `order_id -- the key`
+// names the column `order_id` on the entity and on every entity that inherits
+// it. On a PostgreSQL store the binding is the text the database runs, the
+// field's ALLOYDB or ANSI_SQL entry, read as PostgreSQL, where `#` starts no
+// comment. A field with neither keeps its binding as fieldBinding gives it,
+// read the same way.
+function boundFields(entity, dialect) {
+    const postgres = dialect.name === 'PostgreSQL';
+    const bound = [];
+    for (const field of entity.fields) {
+        const runs = postgres ? (0, ir_1.expressionForDialect)(field, 'ALLOYDB') : undefined;
+        const read = runs !== undefined ?
+            (0, sql_expr_utils_1.sqlWithoutComments)(runs, 'POSTGRES') :
+            (0, sql_expr_utils_1.fieldBindingWithoutComments)(field, postgres ? 'POSTGRES' : undefined);
+        const expr = read?.trim() ?? '';
+        if (!expr || !/^[A-Za-z_]\w*$/.test(expr))
+            continue;
+        const said = field.description?.trim();
+        bound.push({
+            name: field.name,
+            type: field.type ?? 'String',
+            column: expr,
+            ...(said ? { description: said } : {}),
+        });
+    }
+    return bound;
+}
+/**
+ * What there is to read under this runtime: one entry per entity the model
+ * declares, the profile binds to a table, and a statement can name.
+ */
+function readableEntities(runtime, dialect) {
+    const readable = [];
+    for (const entity of runtime.model.entities ?? []) {
+        if (entity.abstract)
+            continue;
+        const fields = boundFields(entity, dialect);
+        if (!fields.length)
+            continue;
+        const warnings = [];
+        const table = (0, binding_1.boundTable)(entity.dataSource, warnings, entity.name, dialect.quote);
+        if (warnings.length)
+            continue;
+        readable.push({ entity, table, fields });
+    }
+    return readable;
+}

package/build/ts/kcmd/semantic/runtime/dialect.d.ts

@@ -0,0 +1,13 @@
+import { Store } from './store';
+export interface SqlDialect {
+    /** Which dialect this is, for a message that needs to name it. */
+    readonly name: 'GoogleSQL' | 'PostgreSQL';
+    /** An identifier, quoted as this dialect requires. */
+    quote(identifier: string): string;
+}
+/** Spanner and BigQuery. */
+export declare const GOOGLE_SQL: SqlDialect;
+/** AlloyDB (PostgreSQL). */
+export declare const POSTGRESQL: SqlDialect;
+/** The dialect `store` speaks; defaults to GoogleSQL when no store is bound. */
+export declare function dialectFor(store: Store | undefined): SqlDialect;

package/build/ts/kcmd/semantic/runtime/dialect.js

@@ -0,0 +1,39 @@
+"use strict";
+// The SQL dialect a bound store speaks (`GoogleSQL` for Spanner and BigQuery,
+// `PostgreSQL` for AlloyDB).
+//
+// `kcmd skills-generate` uses this surface when emitting the physical table
+// and column map in `SKILL.md` (`readableEntities` in `agent_tools.ts` and
+// `readableSchema` in `skills.ts`):
+// - `name`: names the dialect the store expects (`GoogleSQL` or `PostgreSQL`).
+// - `quote`: quotes table and column identifiers according to that dialect's
+//   rules (backticks only when needed in GoogleSQL; double quotes in
+//   PostgreSQL so mixed-case physical names survive folding).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POSTGRESQL = exports.GOOGLE_SQL = void 0;
+exports.dialectFor = dialectFor;
+const sql_identifiers_1 = require("../sql_identifiers");
+/** Spanner and BigQuery. */
+exports.GOOGLE_SQL = {
+    name: 'GoogleSQL',
+    // Quote only what would otherwise be misread -- a reserved word, or a name
+    // that is not a bare identifier. GoogleSQL is case-preserving and
+    // case-insensitive, so an ordinary name reaches the column it names without
+    // help, and backticking every one of them would churn the table map for no
+    // gain.
+    quote: sql_identifiers_1.quoteIdentifier,
+};
+/** AlloyDB (PostgreSQL). */
+exports.POSTGRESQL = {
+    name: 'PostgreSQL',
+    // PostgreSQL folds an unquoted identifier to lowercase before looking it up,
+    // so `OrderId` unquoted asks for a column named `orderid` and misses one
+    // created as `"OrderId"`. Quoting unconditionally is the one rule that
+    // reaches the column however the schema was written, and escapes an embedded
+    // quote by doubling it.
+    quote: id => `"${id.replace(/"/g, '""')}"`,
+};
+/** The dialect `store` speaks; defaults to GoogleSQL when no store is bound. */
+function dialectFor(store) {
+    return store?.kind === 'alloydb' ? exports.POSTGRESQL : exports.GOOGLE_SQL;
+}

package/build/ts/kcmd/semantic/runtime/runtime.d.ts

@@ -0,0 +1,94 @@
+import * as context from '../../gcp/context';
+import { CatalogSnapshot } from '../../snapshot';
+import { SemanticModel } from '../ir';
+import { Store } from './store';
+/**
+ * A semantic model made operational: the model as authored under one binding
+ * profile, and the store it runs against.
+ */
+export interface SemanticRuntime {
+    model: SemanticModel;
+    /**
+     * The model file this was authored in -- the `.yaml` basename, not a path.
+     * Carried so a message about this model can point at the author's file.
+     */
+    document: string;
+    /** Where the model's data lives. Absent when this profile binds no store. */
+    store?: Store;
+    /** Why there is no store. Set exactly when `store` is absent. */
+    storeError?: string;
+    /**
+     * Set when the model's deployments name a target and still no store
+     * results. The target of any deployment may be in no accepted form, the
+     * profile's several targets may leave the store ambiguous, the model may
+     * bind a table outside its Spanner or AlloyDB store, or finding how to
+     * connect may fail, such as the lookup of an AlloyDB cluster's primary
+     * instance. Also set when a GOOGLE block's data is not valid JSON, so its
+     * targets cannot be read. `storeError` says why.
+     */
+    storeFailed?: boolean;
+    /**
+     * Set with `storeFailed` when the model's deployments give no store
+     * whatever the model is used for. One such case is a target in
+     * no accepted form in any deployment. Another is a GOOGLE block that is not
+     * valid JSON. A third is several targets for the profile with no single
+     * store. A table bound outside the store and a failed AlloyDB lookup are
+     * not such cases.
+     */
+    deploymentsRejected?: boolean;
+    /** Which binding profile produced this. Provenance, for messages. */
+    profile: string;
+    /** The entry group the model is scoped to. */
+    entryGroup: string;
+}
+/**
+ * Why this runtime cannot execute SQL DML statements, or null when it can.
+ *
+ * Having a store is the whole requirement. Every backend a profile can deploy
+ * to -- Spanner, AlloyDB, BigQuery -- executes DML, so the kind of store is not
+ * a reason to refuse an action.
+ */
+export declare function runtimeStoreError(runtime: SemanticRuntime): string | null;
+/** How to create the runtimes. Every field has the answer `kcmd` would give. */
+export interface CreateRuntimeOptions {
+    /** Directory holding `catalog.yaml`. Defaults to the current directory. */
+    path?: string;
+    /**
+     * Binding profile to apply to each model. Defaults to the model's inline
+     * bindings.
+     */
+    profile?: string;
+    ctx?: context.ApiContext;
+    /**
+     * Where a non-fatal problem goes -- an unbound field, a profile that names
+     * something the model does not. Defaults to `console.warn`. A caller with a
+     * transcript to keep tidy can collect them instead.
+     */
+    onWarning?: (text: string) => void;
+    /**
+     * Set to refuse a scope that holds more than one model. The scope is
+     * refused before any store is looked up. When this is a function, it takes
+     * the number of models and returns the error.
+     */
+    oneModel?: boolean | ((count: number) => string);
+    /** The scope, already loaded. Defaults to a load of `path`. */
+    snapshot?: CatalogSnapshot;
+}
+/**
+ * One runtime per model document in the scope, in discovery order.
+ *
+ * A lighter path than push's: nothing is pruned or validated for
+ * deployment, because running an action needs the model as authored rather
+ * than the subset a deployed graph can answer. Bindings stay optional, so a
+ * purely logical model yields a runtime with no store -- readable and
+ * inspectable, not runnable -- instead of an error that stops the scope.
+ */
+export declare function createSemanticRuntimes(options?: CreateRuntimeOptions): Promise<SemanticRuntime[] | {
+    error: string;
+}>;
+/**
+ * Why `model` cannot be used because a deployment names a binding profile
+ * `declared` does not hold, or undefined when each names `default` or a
+ * declared profile. `document` is the model's document, for the message.
+ */
+export declare function undeclaredProfileError(document: string, model: SemanticModel, declared: string[]): string | undefined;