@styx-api/core 0.5.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@styx-api/core",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Styx compiler core: parses CLI tool descriptors (e.g. Boutiques), optimizes an IR, solves typed parameter bindings, and generates type-safe wrappers (TypeScript, Python, JSON Schema). Part of the Styx/NiWrap ecosystem.",
   "keywords": [
     "styx",

package/src/backend/python/python.ts

@@ -165,6 +165,28 @@ export function computePublicNames(appId: string | undefined): PublicNames {
   };
 }
 
+/**
+ * A kwarg `_params` builder for one nested (non-root) struct - a union variant
+ * or a plain nested sub-struct. Lets callers write
+ * `output=tool_corrected_output_params(...)` instead of hand-authoring a
+ * `{"@type": ...}` dict. The root struct's factory is `names.paramsFn`; this
+ * covers everything below it.
+ */
+export interface NestedFactory {
+  /** The struct's TypedDict name (factory return + `params` annotation type). */
+  typeName: string;
+  /** Structural identity key of the struct - used by the snippet renderer to
+   * route a nested struct value to its factory. */
+  structKey: string;
+  /** Registered factory function name (e.g. `tool_corrected_output_params`). */
+  funcName: string;
+  /** The struct's `@type` discriminator, injected by the factory; undefined for
+   * a plain sub-struct that carries no discriminator. */
+  typeTag: string | undefined;
+  /** Per-field signature entries (shared with the snippet renderer). */
+  sigEntries: SigEntry[];
+}
+
 /**
  * The fully-derived naming/typing model for one tool's Python emission. Computed
  * once by `buildEmitModel` so the file emitter and the call-site snippet renderer
@@ -192,6 +214,7 @@ export interface PyEmitModel {
   rootTypeTag: string | undefined;
   paramsType: string;
   sigEntries: SigEntry[];
+  nestedFactories: NestedFactory[];
 }
 
 /**
@@ -257,23 +280,88 @@ export function buildEmitModel(
       ? names.params
       : mapType(rootType, resolveTypeName(namedTypes));
 
+  // Host kwarg names are snake_cased so a tool's signature reads idiomatically
+  // (`corrected_output_file_name=`) regardless of how the descriptor authored
+  // the wire id (camelCase Boutiques sub-ids, etc.); the dict key keeps the
+  // original wire name, so this divergence is the same one as `float` ->
+  // `float_`. Scrubbed for validity / reserved words, then deduped through the
+  // function scope. Shared by the root wrapper and every nested factory so they
+  // stay in lockstep.
+  const hostName = (childScope: Scope, wireKey: string): string =>
+    childScope.add(pyScrubIdent(snakeCase(wireKey), PY_RESERVED));
+
   // Build the per-field SigEntry list once - the factory and kwarg wrapper
   // both consume it, so the host names registered here must satisfy both
   // function scopes. Pre-reserve `params` (factory + wrapper body) and
   // `runner` (wrapper signature) so a wire key matching either gets
   // suffix-bumped. `rootType` is narrowed by `rootIsStruct` for the `Extract`
   // constraint.
+  const resolve = resolveTypeName(namedTypes);
   const sigScope = scope.child(["params", "runner"]);
   const sigEntries =
     rootIsStruct && rootType.kind === "struct"
       ? buildSigEntries(
           rootType,
           collectFieldInfo(ctx, rootType),
-          (wireKey) => sigScope.add(pyScrubIdent(wireKey, PY_RESERVED)),
-          pySigOptions(resolveTypeName(namedTypes)),
+          (wireKey) => hostName(sigScope, wireKey),
+          pySigOptions(resolve),
         )
       : [];
 
+  // Nested-struct factories: every non-root struct (union variants and plain
+  // nested sub-structs, all already collected into `typeDecls`) gets a kwarg
+  // `_params` builder so callers don't have to hand-author `{"@type": ...}`
+  // dicts. Unions are bare type aliases (the caller picks a variant), so only
+  // struct decls get a factory. The factory name is derived from the
+  // (already tool-prefixed, unique) TypedDict name and registered in the shared
+  // scope so it stays unique across the suite's flat `from .x import *`.
+  //
+  // Why this is Python-only (the TypeScript backend keeps nested objects as
+  // inline literals): a nested object literal is idiomatic, well-typed API
+  // design in TypeScript, but in Python it reads as an untyped dict blob.
+  // niwrap's Python audience has used the factory-builder pattern since v1
+  // (`tool_sub_params(...)`), so emitting these factories restores the
+  // convention downstream users expect rather than forcing raw tagged dicts.
+  // The two backends deliberately diverge here; see `structConstructor` in
+  // snippet-core for the matching seam on the snippet side.
+  const rootStructKey =
+    rootIsStruct && rootType.kind === "struct" ? structKey(rootType) : undefined;
+  const nestedFactories: NestedFactory[] = [];
+  for (const decl of typeDecls) {
+    if (decl.type.kind !== "struct") continue;
+    const sKey = structKey(decl.type);
+    if (sKey === rootStructKey) continue; // root already has its `_params` factory
+    const funcName = scope.add(pyScrubIdent(snakeCase(decl.name) + "_params", PY_RESERVED));
+    // Union variants carry their discriminator as a required `@type` literal
+    // field; the factory injects it. A plain nested sub-struct has none.
+    //
+    // The `string` narrowing is total in practice, not a silent drop: the
+    // solver always builds `@type` from a variant's string `name`, so the
+    // literal value is invariably a string. (If a numeric `@type` ever slipped
+    // through, `emitStructTypedDict` would still emit it as a required
+    // `Literal[<n>]` field, so the un-injected dict would fail the mypy --strict
+    // codegen gate rather than miscompile silently.)
+    const atType = decl.type.fields["@type"];
+    const typeTag =
+      atType && atType.kind === "literal" && typeof atType.value === "string"
+        ? atType.value
+        : undefined;
+    const factoryScope = scope.child(["params"]);
+    const factorySig = buildSigEntries(
+      decl.type,
+      collectFieldInfo(ctx, decl.type),
+      (wireKey) => hostName(factoryScope, wireKey),
+      pySigOptions(resolve),
+    );
+    nestedFactories.push({
+      typeName: decl.name,
+      structKey: sKey,
+      funcName,
+      typeTag,
+      sigEntries: factorySig,
+    });
+  }
+
   return {
     appId,
     pkg,
@@ -285,6 +373,7 @@ export function buildEmitModel(
     rootTypeTag,
     paramsType,
     sigEntries,
+    nestedFactories,
   };
 }
 
@@ -303,6 +392,7 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
     rootTypeTag,
     paramsType,
     sigEntries,
+    nestedFactories,
   } = buildEmitModel(ctx, scope);
 
   // Auto-generated header.
@@ -341,6 +431,15 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
     cb.blank();
   }
 
+  // Nested-struct factories: one kwarg `_params` builder per union variant /
+  // nested sub-struct, so callers can write `output=tool_x_params(...)` instead
+  // of a hand-authored `{"@type": ...}` dict. Their TypedDicts are already
+  // declared above (emitTypeDeclarations), so the eager annotations resolve.
+  for (const nf of nestedFactories) {
+    emitParamsFactory(nf.sigEntries, nf.funcName, nf.typeName, nf.typeTag, cb);
+    cb.blank();
+  }
+
   // Validation: walks the root binding and raises StyxValidationError on bad
   // input. Called first thing in the dict-style execute (below).
   emitValidate(
@@ -403,6 +502,7 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
     names.cargs,
     ...(emitOutputs ? [names.outputsFn] : []),
     ...(rootIsStruct ? [names.paramsFn, names.execute] : []),
+    ...nestedFactories.map((nf) => nf.funcName),
     names.validate,
     names.wrapper,
   ];

package/src/backend/python/snippet.ts

@@ -3,6 +3,8 @@ import type { CodegenContext } from "../../manifest/index.js";
 import type { SigEntry } from "../sig-entries.js";
 import type { SnippetDialect, SnippetOptions } from "../snippet-core.js";
 import { renderValue } from "../snippet-core.js";
+import { structKey } from "../type-keys.js";
+import type { PyEmitModel } from "./python.js";
 import { buildEmitModel } from "./python.js";
 import { pyStr } from "./typemap.js";
 
@@ -16,6 +18,49 @@ const pyDialect: SnippetDialect = {
   objKey: (k) => pyStr(k),
 };
 
+/**
+ * Build a Python dialect that renders nested structs as `_params` factory calls
+ * (matching the generated code's per-struct builders) rather than plain dicts.
+ * Each factory is looked up by the struct's structural key; field values use the
+ * factory's scrubbed host kwarg names (from the same `buildSigEntries` the
+ * generated factory is built from), and the function name is package-qualified
+ * so the call resolves through `from <root> import <pkg>`. A struct with no
+ * registered factory (shouldn't happen for well-formed nested types) falls back
+ * to the plain dict literal.
+ */
+function pyDialectWithFactories(model: PyEmitModel, pkg: string | undefined): SnippetDialect {
+  // Keyed only by the NESTED factories - the root struct is intentionally
+  // absent (it has no entry in `model.nestedFactories`), so a struct that is
+  // structurally identical to the root falls through to the plain dict literal
+  // rather than a factory call. That case is rare (requires no `@type`
+  // injection) and harmless; this is not a missed registration.
+  const byKey = new Map<string, { call: string; nameByWire: Map<string, string> }>();
+  for (const f of model.nestedFactories) {
+    byKey.set(f.structKey, {
+      call: pkg ? `${pkg}.${f.funcName}` : f.funcName,
+      nameByWire: new Map(f.sigEntries.map((e) => [e.wireKey, e.name])),
+    });
+  }
+  return {
+    ...pyDialect,
+    structConstructor(type, value, indent, d) {
+      const entry = byKey.get(structKey(type));
+      if (!entry) return undefined;
+      const inner = indent + d.indentUnit;
+      const lines: string[] = [];
+      for (const [wireKey, fieldType] of Object.entries(type.fields)) {
+        if (wireKey === "@type") continue; // injected by the factory
+        if (fieldType.kind === "literal") continue; // no runtime representation
+        if (!(wireKey in value)) continue; // omitted optional / absent field
+        const name = entry.nameByWire.get(wireKey) ?? wireKey;
+        lines.push(`${inner}${name}=${renderValue(value[wireKey], fieldType, inner, d)},`);
+      }
+      if (lines.length === 0) return `${entry.call}()`;
+      return `${entry.call}(\n${lines.join("\n")}\n${indent})`;
+    },
+  };
+}
+
 /**
  * Render a Python call snippet for one tool from a config object (the params
  * dict the form produces, keyed by Boutiques wire names).
@@ -25,8 +70,9 @@ const pyDialect: SnippetDialect = {
  * *scrubbed host* identifiers (`float` -> `float_`), not the wire keys; the
  * per-field mapping comes from the same `buildSigEntries` the generated wrapper
  * is built from, so the snippet matches the real signature. Nested structs /
- * union variants / lists-of-structs have no constructor in the generated code,
- * so they render as plain dict literals keyed by wire names.
+ * union variants / lists-of-structs render as calls to their generated
+ * `_params` factory (`fsl.bet_x_params(...)`), matching the per-struct builders
+ * the Python backend emits.
  *
  * Union- (or otherwise non-struct-) rooted tools have no kwarg wrapper; the
  * single dict-style `<tool>` entry is called with one object-literal argument.
@@ -51,11 +97,12 @@ export function renderPythonCall(
   const model = buildEmitModel(ctx);
   const pkg = ctx.package?.name;
   const callee = pkg ? `${pkg}.${model.names.wrapper}` : model.names.wrapper;
+  const dialect = pyDialectWithFactories(model, pkg);
 
   const call =
     model.rootIsStruct && model.rootType.kind === "struct"
-      ? renderKwargCall(callee, model.sigEntries, model.rootType, config)
-      : `${callee}(${renderValue(config, model.rootType, "", pyDialect)})`;
+      ? renderKwargCall(callee, model.sigEntries, model.rootType, config, dialect)
+      : `${callee}(${renderValue(config, model.rootType, "", dialect)})`;
 
   if (opts.includeImport === false || !pkg) return call;
   const root = opts.packageRoot ?? ctx.project?.name;
@@ -69,15 +116,16 @@ function renderKwargCall(
   sigEntries: readonly SigEntry[],
   rootType: Extract<BoundType, { kind: "struct" }>,
   config: Record<string, unknown>,
+  dialect: SnippetDialect,
 ): string {
   const nameFor = new Map(sigEntries.map((e) => [e.wireKey, e.name]));
-  const indent = pyDialect.indentUnit;
+  const indent = dialect.indentUnit;
   const lines: string[] = [];
   for (const [wireKey, fieldType] of Object.entries(rootType.fields)) {
     if (fieldType.kind === "literal") continue; // @type / consts injected by the wrapper
     if (!(wireKey in config)) continue;
     const name = nameFor.get(wireKey) ?? wireKey;
-    lines.push(`${indent}${name}=${renderValue(config[wireKey], fieldType, indent, pyDialect)},`);
+    lines.push(`${indent}${name}=${renderValue(config[wireKey], fieldType, indent, dialect)},`);
   }
   if (lines.length === 0) return `${callee}()`;
   return `${callee}(\n${lines.join("\n")}\n)`;

package/src/backend/snippet-core.ts

@@ -19,6 +19,24 @@ export interface SnippetDialect {
   null: string;
   /** Render an object-literal key from a wire key, quoting when not a bare identifier. */
   objKey(wireKey: string): string;
+  /**
+   * Optional: render a nested struct as a constructor/factory call instead of a
+   * plain object literal. A backend that generates per-struct builders (Python's
+   * `tool_x_params(...)`) supplies this; one that doesn't (TypeScript) leaves it
+   * unset and gets the object-literal form. Return `undefined` to fall back to
+   * the object literal for this particular struct (e.g. no matching factory).
+   *
+   * The Python/TypeScript divergence is deliberate: nested object literals are
+   * idiomatic in TypeScript, whereas Python's niwrap audience expects the
+   * factory-builder pattern (`tool_sub_params(...)`) it has used since v1. See
+   * the nested-factory block in `python.ts` for the full rationale.
+   */
+  structConstructor?(
+    type: Extract<BoundType, { kind: "struct" }>,
+    value: Record<string, unknown>,
+    indent: string,
+    d: SnippetDialect,
+  ): string | undefined;
 }
 
 /** Options shared by both language renderers. */
@@ -67,9 +85,13 @@ function structAtType(type: Extract<BoundType, { kind: "struct" }>): string | un
 
 /**
  * Render a struct config as a host object literal (Python dict / TS object).
- * Keys are the Boutiques wire names (the generated TypedDict / interface keys) -
- * nested structs have no constructor function in the generated code, so callers
- * build them as plain object literals.
+ * Keys are the Boutiques wire names (the generated TypedDict / interface keys).
+ *
+ * When the dialect supplies `structConstructor` (Python, which generates a
+ * per-struct `_params` builder), the struct is rendered as that factory call
+ * instead - e.g. `tool_corrected_output_params(file="...")`. Backends without
+ * per-struct builders (TypeScript) leave the hook unset and build the plain
+ * object literal below.
  *
  * `@type` is emitted from the struct's literal discriminator field when present
  * (union variants carry a required, load-bearing `@type`); for the root call the
@@ -85,6 +107,13 @@ export function renderStructLiteral(
   injectAtType?: string,
 ): string {
   const obj = isRecord(value) ? value : {};
+  // A factory call carries its own `@type`, so it's only valid when the struct's
+  // discriminator comes from the struct itself (or none) - not when the tag must
+  // be injected from outside (the root call, which never reaches this path).
+  if (injectAtType === undefined && d.structConstructor) {
+    const call = d.structConstructor(type, obj, indent, d);
+    if (call !== undefined) return call;
+  }
   const inner = indent + d.indentUnit;
   const lines: string[] = [];