@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/tools/knowledge/local-slots.js

@@ -0,0 +1,177 @@
+/**
+ * The local slots of a template: the slots whose value is a fact of the
+ * machine (a path, a column name, a level label, a design formula). The
+ * service renders such a slot as its marker `{{name}}` and never sees its
+ * value; the host binds the value here, after the render and before the
+ * write, thus the value never leaves the machine.
+ *
+ * `bindLocalSlots` is a copy of the reference implementation the knowledge
+ * service exports (`src/render/render.ts` of the service). The two must give
+ * the same bytes: a marked render bound here equals a full render of the
+ * service for the same values. Keep the literal rules in step with the
+ * service when a slot type is added.
+ */
+/** The local slots of a contract, in the order the template declares them. */
+export function localParameters(parameters) {
+    return parameters.filter((parameter) => parameter.local === true);
+}
+const FORMULA_PATTERN = /^~\s*[A-Za-z0-9_.+*:()\s-]+$/;
+/** Check one caller value against the contract of its slot, as the renderer of the service does. */
+export function validateLocalSlot(parameter, value) {
+    const slot = parameter.name;
+    const permitted = parameter.enum;
+    switch (parameter.type) {
+        case "string":
+        case "formula": {
+            if (typeof value !== "string" || value.length === 0)
+                return { slot, reason: "a non-empty string is required" };
+            if (parameter.type === "formula" && !FORMULA_PATTERN.test(value))
+                return { slot, reason: "a formula must start with ~ and hold only names, +, :, *, and parentheses" };
+            if (permitted && !permitted.includes(value))
+                return { slot, reason: `the value "${value}" is not permitted`, permitted };
+            if (parameter.pattern && !new RegExp(parameter.pattern).test(value))
+                return { slot, reason: `the value must match ${parameter.pattern}` };
+            return undefined;
+        }
+        case "number":
+        case "integer": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                return { slot, reason: "a number is required" };
+            if (parameter.type === "integer" && !Number.isInteger(value))
+                return { slot, reason: "an integer is required" };
+            if (parameter.minimum !== undefined && value < parameter.minimum)
+                return { slot, reason: `the value must be at least ${parameter.minimum}` };
+            if (parameter.maximum !== undefined && value > parameter.maximum)
+                return { slot, reason: `the value must be at most ${parameter.maximum}` };
+            return undefined;
+        }
+        case "boolean":
+            return typeof value === "boolean" ? undefined : { slot, reason: "a boolean is required" };
+        case "string_list": {
+            if (!Array.isArray(value) || !value.every((item) => typeof item === "string"))
+                return { slot, reason: "a list of strings is required" };
+            if (permitted) {
+                const bad = value.find((item) => !permitted.includes(item));
+                if (bad !== undefined)
+                    return { slot, reason: `the value "${bad}" is not permitted`, permitted };
+            }
+            return undefined;
+        }
+        default:
+            // The contract is a loose object of the wire, thus a type this host does not know is possible. It is
+            // refused, never rendered as text, because a wrong literal is a wrong script.
+            return { slot, reason: `the slot type ${parameter.type} is not one this host renders` };
+    }
+}
+/** A slot value as a literal of the language: R gives `TRUE` and `c(...)`, Python gives `True` and `[...]`. */
+function literal(language, parameter, value) {
+    const python = language === "python";
+    switch (parameter.type) {
+        case "string":
+            return JSON.stringify(String(value));
+        case "formula":
+            return String(value);
+        case "number":
+        case "integer":
+            return String(value);
+        case "boolean":
+            return python ? (value ? "True" : "False") : value ? "TRUE" : "FALSE";
+        case "string_list": {
+            const items = Array.isArray(value) ? value : [String(value)];
+            const rendered = items.map((item) => JSON.stringify(String(item))).join(", ");
+            return python ? `[${rendered}]` : `c(${rendered})`;
+        }
+        default:
+            throw new Error(`unhandled slot type: ${parameter.type}`);
+    }
+}
+/** The literal of an optional slot that has no value: R keeps the type of the slot, Python has one absent scalar and an empty list. */
+function absentLiteral(language, type) {
+    if (language === "python")
+        return type === "string_list" ? "[]" : "None";
+    switch (type) {
+        case "string":
+            return "NA_character_";
+        case "integer":
+            return "NA_integer_";
+        case "number":
+            return "NA_real_";
+        case "boolean":
+            return "NA";
+        case "string_list":
+            return "character(0)";
+        default:
+            return "NULL";
+    }
+}
+/** The marker of a slot as the service leaves it in a marked render. */
+export function slotMarker(name) {
+    return `{{${name}}}`;
+}
+/**
+ * Bind the local values into a marked script. Each local marker takes the
+ * literal of its value, else of the default of the slot, else the absent
+ * literal when the slot is optional. A required local slot with no value
+ * and no default is an issue, and so is a value the contract refuses. The
+ * report names the source of each bound slot and keeps the `read` flag of
+ * the marked report of the service.
+ */
+export function bindLocalSlots(template, script, localValues, marked = []) {
+    const issues = [];
+    const locals = localParameters(template.parameters);
+    const byName = new Map(locals.map((parameter) => [parameter.name, parameter]));
+    for (const name of Object.keys(localValues)) {
+        if (!byName.has(name))
+            issues.push({ slot: name, reason: "the template has no such local slot", permitted: [...byName.keys()] });
+    }
+    const values = new Map();
+    const slots = [];
+    for (const parameter of locals) {
+        const given = localValues[parameter.name];
+        if (given !== undefined) {
+            const issue = validateLocalSlot(parameter, given);
+            if (issue) {
+                issues.push(issue);
+                continue;
+            }
+            // Validated above: a string, a finite number, a boolean, or a list of strings.
+            const value = given;
+            values.set(parameter.name, value);
+            slots.push({ name: parameter.name, value, source: "caller", adaptable: true, lines: [] });
+        }
+        else if (parameter.default !== undefined) {
+            // The contract is loose on the wire; a default is a scalar or a list of strings by the contract of the service,
+            // and the service renders whatever it holds, thus only an absent default is absent here too.
+            const value = parameter.default;
+            values.set(parameter.name, value);
+            slots.push({
+                name: parameter.name,
+                value,
+                source: "default",
+                adaptable: true,
+                ...(parameter.default_source ? { default_source: parameter.default_source } : {}),
+                lines: [],
+            });
+        }
+        else if (parameter.required !== false) {
+            issues.push({ slot: parameter.name, reason: "the local slot is required and has no value" });
+        }
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    const bound = script.replace(/\{\{([a-z][a-z0-9_]*)\}\}/g, (whole, name) => {
+        const parameter = byName.get(name);
+        if (!parameter)
+            return whole;
+        const value = values.get(name);
+        return value === undefined ? absentLiteral(template.language, parameter.type) : literal(template.language, parameter, value);
+    });
+    const lines = bound.split("\n");
+    const readByName = new Map(marked.flatMap((entry) => (entry.read === undefined ? [] : [[entry.name, entry.read]])));
+    const located = slots.map((entry) => ({
+        ...entry,
+        lines: script.split("\n").flatMap((line, index) => (line.includes(slotMarker(entry.name)) && index < lines.length ? [index + 1] : [])),
+        ...(readByName.has(entry.name) ? { read: readByName.get(entry.name) } : {}),
+    }));
+    return { ok: true, script: bound, slots: located };
+}

package/dist/tools/knowledge/pin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The release a plan pins. The planner tools of one plan generation share
+ * one pin: the first recommend answer sets it, and every later call of the
+ * service inside that plan carries it as `expected_snapshot`. A service that
+ * moved to another release between two calls then refuses the call, and the
+ * plan never mixes two releases in silence.
+ */
+export interface SnapshotPin {
+    /** The pinned release digest, or `undefined` before the first answer. */
+    get(): string | undefined;
+    /** Pin the release of the first answer. A later call with another digest changes nothing: the first release is the plan's. */
+    set(digest: string): void;
+}
+export declare function createSnapshotPin(): SnapshotPin;

package/dist/tools/knowledge/pin.js

@@ -0,0 +1,17 @@
+/**
+ * The release a plan pins. The planner tools of one plan generation share
+ * one pin: the first recommend answer sets it, and every later call of the
+ * service inside that plan carries it as `expected_snapshot`. A service that
+ * moved to another release between two calls then refuses the call, and the
+ * plan never mixes two releases in silence.
+ */
+export function createSnapshotPin() {
+    let pinned;
+    return {
+        get: () => pinned,
+        set: (digest) => {
+            if (pinned === undefined)
+                pinned = digest;
+        },
+    };
+}

package/dist/tools/knowledge/recommend.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `knowledge_recommend` — one typed situation in, one plan skeleton out.
+ *
+ * The description is the whole contract with the planner: when to call, what
+ * to send, and where the answer goes (the `grounding` field of each method
+ * step). No prompt names this tool. Whether a model calls it from the
+ * description alone is a Phase 0 measurement.
+ *
+ * The model receives one representation. The procedure of the service is
+ * folded into `plan_skeleton` (the shape `submit_plan` accepts), and the
+ * claims ride beside it, cited by id from the steps. The procedure itself
+ * stays out of the tool result: the same fact would otherwise reach the
+ * model three times, as a procedure step, as a claim view, and as a skeleton
+ * step.
+ */
+import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import type { KnowledgeClient, KnowledgeRejected, KnowledgeSnapshotMismatch, KnowledgeUnavailable, RecommendResponse } from "./client.js";
+import type { SnapshotPin } from "./pin.js";
+import { type EnvironmentPaths, type RecommendWithEnvironment } from "./environment.js";
+import { type SkeletonStep } from "./skeleton.js";
+export interface KnowledgeRecommendDeps extends Omit<EnvironmentPaths, "farmLockFile"> {
+    readonly client: KnowledgeClient;
+    /** Host path of the farm `inflexa.lock`, or its resolver for each analysis. Absent, the packages read as unknown. */
+    readonly farmLockFile?: EnvironmentStorePaths["farmLockFile"];
+    /**
+     * Receives each answer the planner sees. The planner keeps the skeleton of
+     * the invocation, thus `submit_plan` can restore a grounding field that the
+     * model dropped when it copied a skeleton step.
+     */
+    readonly onAnswer?: (answer: KnowledgeRecommendAnswer) => void;
+    /**
+     * The release of the plan. The first answer sets it, and each later call
+     * of this tool and of `knowledge_check` sends it, thus a service that moved
+     * to another release between two calls refuses instead of mixing releases.
+     */
+    readonly pin?: SnapshotPin;
+}
+/**
+ * The model-facing answer of the tool: the skeleton and the claims, with the
+ * envelope of the service and the environment source. Never the procedure.
+ */
+export interface KnowledgeRecommendAnswer {
+    readonly match: RecommendResponse["match"];
+    readonly snapshot: RecommendResponse["snapshot"];
+    /** The situation as the service normalized it. */
+    readonly situation?: Readonly<Record<string, unknown>>;
+    readonly flags: RecommendResponse["flags"];
+    /** The step types a flag removed. Absent when none. */
+    readonly dropped?: readonly string[];
+    readonly uncovered: readonly string[];
+    /** The step types whose method has no eligible template: covered by the knowledge, not by a vetted script. Absent when none. */
+    readonly unrealized?: readonly string[];
+    readonly environment_source?: RecommendWithEnvironment["environment_source"];
+    readonly plan_skeleton: readonly SkeletonStep[];
+    readonly claims: RecommendResponse["claims"];
+    readonly nearest?: RecommendResponse["nearest"];
+    readonly reason?: string;
+}
+export type KnowledgeRecommendOutput = KnowledgeRecommendAnswer | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch;
+/** The one representation: the envelope, the skeleton, and the claims. The procedure stays host-side. */
+export declare function toPlannerAnswer(joined: RecommendWithEnvironment): KnowledgeRecommendAnswer;
+export declare function createKnowledgeRecommendTool(deps: KnowledgeRecommendDeps): import("../define-tool.js").Tool<{
+    question: "enrichment" | "differential_expression" | "qc" | "full_plan" | "tf_activity" | "deconvolution" | "coexpression" | "clustering" | "survival" | "signature_scoring";
+    modality: "bulk_rna_seq";
+    data_state: "fastq" | "counts" | "tpm_or_fpkm" | "log_normalized";
+    organism: "other" | "human" | "mouse";
+    n_groups: number;
+    n_per_group_min: number;
+    n_per_group_max: number;
+    paired: boolean;
+    batch: "none" | "known_balanced" | "known_confounded" | "known_unbalanced" | "suspected";
+    count_source?: "unknown" | "salmon" | "kallisto" | "star_featurecounts" | "rsem" | undefined;
+    import_state?: "unknown" | "quantifications" | "estimated_counts_with_lengths" | "corrected_counts" | "integer_counts" | undefined;
+    n_samples?: number | undefined;
+    n_events?: number | undefined;
+    blocking_factor?: "other" | "individual" | "cell_line" | "litter" | "site" | "pair" | null | undefined;
+    block_structure?: "crossed" | "nested" | undefined;
+    covariates?: ("other" | "technical" | "sex" | "age" | "clinical")[] | undefined;
+    n_timepoints?: number | null | undefined;
+    continuous_predictor?: "other" | "score" | "time" | "age" | "dose" | null | undefined;
+    technical_replicates?: boolean | undefined;
+    sample_exclusions?: boolean | undefined;
+    feature_level?: "gene" | "exon" | "transcript" | undefined;
+    library_type?: "unknown" | "total" | "polyA" | "three_prime" | undefined;
+    strandedness?: "unknown" | "verified" | "declared_unverified" | undefined;
+    interaction?: boolean | undefined;
+    classifier?: boolean | undefined;
+    extra_analyses?: ("tf_activity" | "deconvolution" | "coexpression" | "clustering" | "survival" | "signature_scoring" | "variance_partition" | "pathway_activity" | "transcript_level" | "annotation")[] | undefined;
+    preferred_language?: "R" | "python" | undefined;
+    enrichment_input?: "ranked_list" | "gene_list" | "sample_scores" | undefined;
+    quality_flags?: ("low_depth_sample" | "outlier_sample" | "sample_identity_doubt" | "high_duplication" | "degraded_rna")[] | undefined;
+}, KnowledgeRecommendOutput>;

package/dist/tools/knowledge/recommend.js

@@ -0,0 +1,98 @@
+/**
+ * `knowledge_recommend` — one typed situation in, one plan skeleton out.
+ *
+ * The description is the whole contract with the planner: when to call, what
+ * to send, and where the answer goes (the `grounding` field of each method
+ * step). No prompt names this tool. Whether a model calls it from the
+ * description alone is a Phase 0 measurement.
+ *
+ * The model receives one representation. The procedure of the service is
+ * folded into `plan_skeleton` (the shape `submit_plan` accepts), and the
+ * claims ride beside it, cited by id from the steps. The procedure itself
+ * stays out of the tool result: the same fact would otherwise reach the
+ * model three times, as a procedure step, as a claim view, and as a skeleton
+ * step.
+ */
+import { ok } from "neverthrow";
+import { defineTool } from "../define-tool.js";
+import { joinEnvironment } from "./environment.js";
+import { SITUATION_EXAMPLE, SituationFieldsSchema, toPreferences, toSituation } from "./situation.js";
+import { buildPlanSkeleton } from "./skeleton.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
+}
+/** The one representation: the envelope, the skeleton, and the claims. The procedure stays host-side. */
+export function toPlannerAnswer(joined) {
+    const dropped = stringList(joined.dropped);
+    const unrealized = stringList(joined.unrealized);
+    return {
+        match: joined.match,
+        snapshot: joined.snapshot,
+        ...(isRecord(joined.situation) ? { situation: joined.situation } : {}),
+        flags: joined.flags,
+        ...(dropped ? { dropped } : {}),
+        uncovered: joined.uncovered,
+        ...(unrealized && unrealized.length > 0 ? { unrealized } : {}),
+        ...(joined.environment_source ? { environment_source: joined.environment_source } : {}),
+        plan_skeleton: buildPlanSkeleton(joined),
+        claims: joined.claims,
+        ...(joined.nearest ? { nearest: joined.nearest } : {}),
+        ...(joined.reason !== undefined ? { reason: joined.reason } : {}),
+    };
+}
+export function createKnowledgeRecommendTool(deps) {
+    return defineTool({
+        id: "knowledge_recommend",
+        description: "Get the cited, versioned procedure for a bulk RNA-seq analysis situation from the Inflexa knowledge service, folded into plan steps: " +
+            "which method for each step (QC, filter, normalize, model, test, shrinkage, multiple testing, enrichment, report), " +
+            "its settings with their sources, a tested script template per step, the rules that select them, and the evidence. " +
+            "Call it BEFORE you draft a method step for bulk RNA-seq differential expression, enrichment, or QC. " +
+            "Fill the situation from the Data Context (the design, the replicate counts, the batch structure, the data state, the quality concerns); never send a sample name or a file path. " +
+            `Example input: ${SITUATION_EXAMPLE}. ` +
+            "The answer holds one representation: `plan_skeleton`, the plan steps with the id, the name, the track, the agent, the packages, the dependencies, " +
+            "the caveats, the `alternatives`, the `forbids`, the `disputed` sides, the `environment`, and the `grounding` " +
+            "(the status, the snapshot, the claim ids, the template, the `settings`, and the reason) filled. " +
+            "`claims` holds one view per claim id the steps cite; cite a claim by its id, and never copy its text into the plan. " +
+            "Read the answer this way. `match: applicable`: copy each skeleton step into `submit_plan` as it is, including `grounding.settings`, " +
+            "then add the question, the acceptance criteria, the resources, and the step budget from the data profile. " +
+            "A skeleton step is the vetted default, not the only permitted method. When the design or the question does not fit its method, plan the step with your method: " +
+            "set `grounding.status: ungrounded`, keep the snapshot digest, cite no claim, and give the reason for the departure in `grounding.reason`. A departure the plan states is not a fault; a silent one is. " +
+            "`match: flag`: a rule changes the outcome (for example no replication, or a batch confounded with the condition); " +
+            "the skeleton step carries `status: flagged`, the rule id in its reason, and the flag message as its first caveat; obey the flag `outcome`. " +
+            "`dropped` lists the steps the procedure removed, because a flag removed inference or because the script of the test runs no such step (the shrinkage of limma and edgeR); do not plan them. " +
+            "`unrealized` lists the steps whose method has no vetted script template for this design; the skeleton step keeps the method and the claims, its caveat names the gap, " +
+            "and the plan states that the step runs without a vetted template instead of an invented one. " +
+            "`match: none`: no rule covers the central step; plan that step from your own knowledge with `status: ungrounded` and the reason, and keep the skeleton steps the answer holds. " +
+            "`match: unavailable`: the service did not answer; plan as usual and set `status: ungrounded`. " +
+            "`match: rejected`: a field was invalid; the answer names the field and the permitted values, so correct the call once. " +
+            "A step with `disputed` sides: choose one side and state the choice in the step. " +
+            "The `alternatives` of a step are also vetted methods; `forbids` names the method ids the rules forbid for the step, and a forbidden method stays forbidden. " +
+            "A caveat is one of: a warn flag; a parameter conflict between two rules (the step omits that parameter, so state the value you choose and both rule ids); " +
+            "a substitution (the template runs a substitute of the method of record, and the step method, package, and template are the substitute; the plan states it); " +
+            "a language limit (the requested language has no template that realizes the method for this design, or its template refuses a value of the rules; the step keeps the named template, and the plan states the limit). " +
+            "A step carries `environment` when the host bound the stores: `package.present` and its version from the packages installed in the sandbox, and `collection.present` with its path in the reference store. " +
+            "That is the environment answer; do not call the listing tools for a package or a collection the answer already reports. " +
+            "Call it once per situation; a second call with the same situation gives the same answer.",
+        inputSchema: SituationFieldsSchema,
+        describeCall: ({ question, n_per_group_min, n_per_group_max, batch }) => `${question}: ${n_per_group_min}-${n_per_group_max} per group, batch ${batch}`,
+        describeResult: (_input, result) => result.match === "applicable" ? `${result.plan_skeleton.length} steps, ${result.claims.length} claims` : result.match,
+        execute: async (input, ctx) => {
+            const answer = await deps.client.recommend(toSituation(input), "concise", toPreferences(input), deps.pin?.get());
+            if (answer.match === "unavailable" || answer.match === "rejected" || answer.match === "snapshot_mismatch")
+                return ok(answer);
+            deps.pin?.set(answer.snapshot.digest);
+            const farmLockFile = typeof deps.farmLockFile === "function" ? deps.farmLockFile(ctx.session.scope.analysisId) : deps.farmLockFile;
+            const joined = await joinEnvironment(answer, {
+                ...(farmLockFile ? { farmLockFile } : {}),
+                ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+                ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
+            });
+            const planner = toPlannerAnswer(joined);
+            deps.onAnswer?.(planner);
+            return ok(planner);
+        },
+    });
+}

package/dist/tools/knowledge/situation.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The situation fields as a flat tool input. Each `.describe()` is the whole
+ * of what the model knows about a field, thus the descriptions carry the
+ * definitions of the terms, and they tell the planner where in the Data
+ * Context each value comes from.
+ */
+import { z } from "zod";
+import type { KnowledgeSituation, KnowledgePreferences } from "./client.js";
+export declare const SituationFieldsSchema: z.ZodObject<{
+    question: z.ZodEnum<{
+        enrichment: "enrichment";
+        differential_expression: "differential_expression";
+        qc: "qc";
+        full_plan: "full_plan";
+        tf_activity: "tf_activity";
+        deconvolution: "deconvolution";
+        coexpression: "coexpression";
+        clustering: "clustering";
+        survival: "survival";
+        signature_scoring: "signature_scoring";
+    }>;
+    modality: z.ZodLiteral<"bulk_rna_seq">;
+    data_state: z.ZodEnum<{
+        fastq: "fastq";
+        counts: "counts";
+        tpm_or_fpkm: "tpm_or_fpkm";
+        log_normalized: "log_normalized";
+    }>;
+    count_source: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        salmon: "salmon";
+        kallisto: "kallisto";
+        star_featurecounts: "star_featurecounts";
+        rsem: "rsem";
+    }>>;
+    import_state: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        quantifications: "quantifications";
+        estimated_counts_with_lengths: "estimated_counts_with_lengths";
+        corrected_counts: "corrected_counts";
+        integer_counts: "integer_counts";
+    }>>;
+    organism: z.ZodEnum<{
+        other: "other";
+        human: "human";
+        mouse: "mouse";
+    }>;
+    n_groups: z.ZodNumber;
+    n_per_group_min: z.ZodNumber;
+    n_per_group_max: z.ZodNumber;
+    n_samples: z.ZodOptional<z.ZodNumber>;
+    n_events: z.ZodOptional<z.ZodNumber>;
+    paired: z.ZodBoolean;
+    blocking_factor: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        other: "other";
+        individual: "individual";
+        cell_line: "cell_line";
+        litter: "litter";
+        site: "site";
+        pair: "pair";
+    }>>>;
+    block_structure: z.ZodOptional<z.ZodEnum<{
+        crossed: "crossed";
+        nested: "nested";
+    }>>;
+    batch: z.ZodEnum<{
+        none: "none";
+        known_balanced: "known_balanced";
+        known_confounded: "known_confounded";
+        known_unbalanced: "known_unbalanced";
+        suspected: "suspected";
+    }>;
+    covariates: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        other: "other";
+        technical: "technical";
+        sex: "sex";
+        age: "age";
+        clinical: "clinical";
+    }>>>;
+    n_timepoints: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    continuous_predictor: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        other: "other";
+        score: "score";
+        time: "time";
+        age: "age";
+        dose: "dose";
+    }>>>;
+    technical_replicates: z.ZodOptional<z.ZodBoolean>;
+    sample_exclusions: z.ZodOptional<z.ZodBoolean>;
+    feature_level: z.ZodOptional<z.ZodEnum<{
+        gene: "gene";
+        exon: "exon";
+        transcript: "transcript";
+    }>>;
+    library_type: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        total: "total";
+        polyA: "polyA";
+        three_prime: "three_prime";
+    }>>;
+    strandedness: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        verified: "verified";
+        declared_unverified: "declared_unverified";
+    }>>;
+    interaction: z.ZodOptional<z.ZodBoolean>;
+    classifier: z.ZodOptional<z.ZodBoolean>;
+    extra_analyses: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        tf_activity: "tf_activity";
+        deconvolution: "deconvolution";
+        coexpression: "coexpression";
+        clustering: "clustering";
+        survival: "survival";
+        signature_scoring: "signature_scoring";
+        variance_partition: "variance_partition";
+        pathway_activity: "pathway_activity";
+        transcript_level: "transcript_level";
+        annotation: "annotation";
+    }>>>;
+    preferred_language: z.ZodOptional<z.ZodEnum<{
+        R: "R";
+        python: "python";
+    }>>;
+    enrichment_input: z.ZodOptional<z.ZodEnum<{
+        ranked_list: "ranked_list";
+        gene_list: "gene_list";
+        sample_scores: "sample_scores";
+    }>>;
+    quality_flags: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        low_depth_sample: "low_depth_sample";
+        outlier_sample: "outlier_sample";
+        sample_identity_doubt: "sample_identity_doubt";
+        high_duplication: "high_duplication";
+        degraded_rna: "degraded_rna";
+    }>>>;
+}, z.core.$strip>;
+export type SituationFields = z.infer<typeof SituationFieldsSchema>;
+/** The situation as the client sends it: the fields as given, with an absent optional field omitted. */
+export declare function toSituation(fields: SituationFields): KnowledgeSituation;
+/** The preferences of the caller, beside the situation: the language of the template. */
+export declare function toPreferences(fields: SituationFields): KnowledgePreferences | undefined;
+/** One worked example, in the descriptions of the two planner tools. Examples raise complex-parameter accuracy. */
+export declare const SITUATION_EXAMPLE: string;