@inflexa-ai/harness 0.45.0 → 0.45.1

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;

package/dist/tools/knowledge/situation.js

@@ -0,0 +1,164 @@
+/**
+ * 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";
+export const SituationFieldsSchema = z.object({
+    question: z
+        .enum([
+        "differential_expression",
+        "enrichment",
+        "qc",
+        "full_plan",
+        "tf_activity",
+        "deconvolution",
+        "coexpression",
+        "clustering",
+        "survival",
+        "signature_scoring",
+    ])
+        .describe("What the plan needs a procedure for. `full_plan` returns QC, filtering, the model, the test, shrinkage, multiple testing, enrichment, and the report in one answer. " +
+        "Use `differential_expression` when the research question does not ask for pathways or gene sets; an enrichment step the user did not ask for is unasked scope. " +
+        "Use `enrichment` when a results table is the input and no new test is fitted, and `qc` when the question stops at the sample structure. " +
+        "Use `tf_activity` for regulator or pathway activity, `deconvolution` for cell type proportions, `coexpression` for modules, `clustering` for sample subgroups, `survival` for an outcome association, " +
+        "and `signature_scoring` for a per-sample score, or with `classifier: true` for a classifier of the samples."),
+    modality: z.literal("bulk_rna_seq").describe("The assay. Phase 0 serves bulk RNA-seq only."),
+    data_state: z
+        .enum(["fastq", "counts", "tpm_or_fpkm", "log_normalized"])
+        .describe("The state of the expression data in the inputs: raw reads, a raw integer count matrix, TPM/FPKM/RPKM abundances, or log-scale normalized values (log-CPM, microarray)."),
+    count_source: z
+        .enum(["salmon", "kallisto", "star_featurecounts", "rsem", "unknown"])
+        .optional()
+        .describe("The quantifier that produced the counts, when the profile names one. The quantifier does not establish the length correction; `import_state` does."),
+    import_state: z
+        .enum(["quantifications", "estimated_counts_with_lengths", "corrected_counts", "integer_counts", "unknown"])
+        .optional()
+        .describe("The import state of a count table from a transcript quantifier (Salmon, kallisto, RSEM): whether the length correction occurred. Read it from the profile. " +
+        "`quantifications`: per-sample quantification files (quant.sf or abundance.h5) or a quantification directory, plus a transcript-to-gene map. " +
+        "`estimated_counts_with_lengths`: a fractional gene-by-sample matrix plus a table of average transcript lengths per gene and sample. " +
+        "`corrected_counts`: a table described as lengthScaledTPM or scaledTPM counts. " +
+        "`integer_counts`: integer counts from an aligner and a counter (STAR, featureCounts) or from a 3' protocol, with no length data. " +
+        "`unknown`: a count table from a quantifier with no statement of the correction. Omit when `data_state` is not `counts`."),
+    organism: z.enum(["human", "mouse", "other"]).describe("The organism of the samples."),
+    n_groups: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The number of levels of the condition of interest (2 for a two-group comparison; 4 for a 2x2 design; 1 when `continuous_predictor` names the variable of interest)."),
+    n_per_group_min: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The smallest number of biological samples in any group, after technical replicates are summed. 1 means a group has no replication. In a time course, the smallest number in one group at one time point. With a nested block, the smallest number of blocks (for example animals) in one group. With a continuous predictor, the number of samples."),
+    n_per_group_max: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The largest number of biological samples in any group. In a time course, the largest number in one group at one time point. With a nested block, the largest number of blocks in one group. With a continuous predictor, the number of samples."),
+    n_samples: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("The total number of biological samples in the analysis, after technical replicates are summed. Give it whenever the profile states it: the per-group extrema do not give the total for three or more groups, and the rules on a small cohort read it."),
+    n_events: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("For a survival question, the number of samples with an observed event (event indicator 1) in the outcome column. Omit when the question is not survival or the count is not in the profile."),
+    paired: z.boolean().describe("True when each subject contributes a sample to more than one condition (paired or repeated measures)."),
+    blocking_factor: z
+        .enum(["individual", "cell_line", "litter", "site", "pair", "other"])
+        .nullable()
+        .optional()
+        .describe("The role of the blocking factor that is not the condition, never its column name: `individual` when the same subject, donor, or animal gives more than one sample; `cell_line`; `litter`; `site` for a center or a lab of a multi-site study; `pair` for matched pairs of different individuals; `other`. Omit when there is none. The column name stays in the step."),
+    block_structure: z
+        .enum(["crossed", "nested"])
+        .optional()
+        .describe("How the blocking factor relates to the condition: `crossed` when each block holds samples of more than one condition (a donor with a treated and a control sample); `nested` when each block lies inside one condition (several samples from one animal of one genotype), thus the block is the unit of replication. Omit when there is no blocking factor."),
+    batch: z
+        .enum(["none", "known_balanced", "known_confounded", "known_unbalanced", "suspected"])
+        .describe("The batch structure: none; a known batch whose levels each hold every condition; a known batch whose levels coincide with the conditions; a known batch whose levels do not each hold every condition but at least one level holds two conditions (estimable, unbalanced); or a suspected structure (dates, lanes, plates) the metadata does not name."),
+    covariates: z
+        .array(z.enum(["sex", "age", "clinical", "technical", "other"]))
+        .optional()
+        .describe('The role of each other sample covariate the design must hold, one entry per covariate and never a column name, for example ["sex", "age"]: `clinical` for a stage, a grade, or a diagnosis; `technical` for a variable that is not the batch, for example the RNA integrity. Omit when there are none. The column names stay in the step.'),
+    n_timepoints: z.number().int().min(1).nullable().optional().describe("The number of time points when the design is a time course. Omit otherwise."),
+    continuous_predictor: z
+        .enum(["dose", "time", "age", "score", "other"])
+        .nullable()
+        .optional()
+        .describe("The role of the numeric variable of interest, never its column name, when the research question is a trend over that value and not a comparison of groups: `dose`, `time`, `age`, `score`, or `other`. Then set `n_groups` to 1 and the per-group counts to the number of samples. Omit when the variable of interest is a factor. The column name stays in the step."),
+    technical_replicates: z
+        .boolean()
+        .optional()
+        .describe("Set true when some columns of the count table are technical replicates of one biological sample, for example one library sequenced on two lanes or two runs. Omit when each column is one biological sample."),
+    sample_exclusions: z
+        .boolean()
+        .optional()
+        .describe("Set true when the plan drops some delivered samples before the analysis, for example an on-treatment biopsy in a pre-treatment cohort or a failed library. The service then adds a cohort assembly step that counts the units per group after the drop, so the plan states no count before that step. Omit when every delivered sample enters the analysis."),
+    feature_level: z
+        .enum(["gene", "exon", "transcript"])
+        .optional()
+        .describe("The row unit of the count table: `gene` for one row per gene; `exon` for one row per exon or counting bin with the gene of each row, as featureCounts at the feature level writes it; `transcript` for one row per transcript, as tximport writes with txOut or a quantifier table delivers. Omit for a gene-level table or when `data_state` is not counts."),
+    library_type: z.enum(["polyA", "total", "three_prime", "unknown"]).optional().describe("The library preparation, when known."),
+    strandedness: z
+        .enum(["verified", "declared_unverified", "unknown"])
+        .optional()
+        .describe("Whether the strandedness was verified against the quantification, declared but not verified, or unknown."),
+    interaction: z.boolean().optional().describe("True when the question is the interaction of two factors (for example genotype by treatment)."),
+    classifier: z
+        .boolean()
+        .optional()
+        .describe("Set true when the question is a classifier of the samples into classes (a model that predicts the class of a sample from its expression, with cross-validation). Omit for a per-sample score."),
+    extra_analyses: z
+        .array(z.enum([
+        "variance_partition",
+        "tf_activity",
+        "pathway_activity",
+        "signature_scoring",
+        "deconvolution",
+        "coexpression",
+        "clustering",
+        "survival",
+        "transcript_level",
+        "annotation",
+    ]))
+        .optional()
+        .describe("Analyses the research question asks for beside the question kind, for example a regulator activity beside a differential expression. Each joins the procedure at its place. " +
+        "Add `annotation` when the rows of the count table are not gene symbols (Ensembl or Entrez identifiers) and a later step needs symbols: the identifier map is then a vetted step with its own template, and no other step rebuilds it. Omit when none."),
+    preferred_language: z
+        .enum(["R", "python"])
+        .optional()
+        .describe("The script language the user asked for, when the user constraints name one. The answer then names the template in that language when the method has one. Omit otherwise."),
+    enrichment_input: z
+        .enum(["ranked_list", "gene_list", "sample_scores"])
+        .optional()
+        .describe("What the enrichment step takes: `ranked_list` for every tested gene ranked by a statistic (the default), `gene_list` for a discrete list such as the significant genes, `sample_scores` for a pathway score per sample. Omit when the question has no enrichment."),
+    quality_flags: z
+        .array(z.enum(["low_depth_sample", "outlier_sample", "sample_identity_doubt", "high_duplication", "degraded_rna"]))
+        .optional()
+        .describe("The quality concerns of the profile as typed flags: a sample with a library size far below the median; a sample that does not cluster with its group; a doubt about the identity of a sample; high duplication; degraded RNA (a low RNA integrity number, a 3' coverage bias, or formalin-fixed material)."),
+});
+/** The situation as the client sends it: the fields as given, with an absent optional field omitted. */
+export function toSituation(fields) {
+    const situation = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (key === "preferred_language")
+            continue;
+        if (value !== undefined)
+            situation[key] = value;
+    }
+    // The schema above validated every field, thus the record has the shape of the client type.
+    return situation;
+}
+/** The preferences of the caller, beside the situation: the language of the template. */
+export function toPreferences(fields) {
+    return fields.preferred_language ? { language: fields.preferred_language } : undefined;
+}
+/** One worked example, in the descriptions of the two planner tools. Examples raise complex-parameter accuracy. */
+export const SITUATION_EXAMPLE = '{"question":"differential_expression","modality":"bulk_rna_seq","data_state":"counts","count_source":"salmon","import_state":"unknown","organism":"human",' +
+    '"n_groups":2,"n_per_group_min":6,"n_per_group_max":6,"paired":false,"batch":"none","quality_flags":["low_depth_sample"]}';

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

@@ -0,0 +1,69 @@
+/**
+ * The plan skeleton: the procedure of the service folded into the steps of a
+ * plan, with the agent, the packages, the dependencies, the caveats, the
+ * alternatives, the disputed sides, the forbidden methods, the environment,
+ * and the grounding of each step filled from the answer. It is
+ * the one representation the planner receives: the procedure itself never
+ * reaches the model, thus nothing the procedure holds may be lost here. A
+ * small model edits a skeleton where it fails to compose a plan from a
+ * procedure; a frontier model pays nothing for it. The skeleton carries only
+ * the fields the answer can fill. The question, the acceptance criteria, the
+ * resources, and the step budget come from the data profile, and the planner
+ * adds them.
+ *
+ * The fold is fixed: one cohort assembly step when the procedure holds one
+ * (the sample exclusions and the sum of technical replicates, before any
+ * other step reads the counts), one QC step, one differential expression
+ * step that holds the filter, the normalization, the design, the test, the
+ * shrinkage, and the multiple testing (the templates cover the same span),
+ * one enrichment step on its own track, and one report step. A group with
+ * no step in the procedure is absent from the skeleton.
+ *
+ * The central step of a group names the method of the skeleton step, and it
+ * gives the alternatives, the template, and the environment: an alternative
+ * of a folded step (a normalization in the differential expression group)
+ * is not a permitted replacement of the step method, and it stays out. The
+ * settings, the caveats, and the forbidden methods come from every step of
+ * the group, each setting with the step it belongs to. A parameter is a
+ * setting of the grounding, never a constraint of the step: the value is the
+ * vetted default, and the agent can state another value with its reason.
+ */
+import type { GroundingSetting } from "../../schemas/workflow-state.js";
+import type { RecommendWithEnvironment, StepEnvironment } from "./environment.js";
+export interface SkeletonAlternative {
+    readonly method: string;
+    readonly label: string;
+    readonly when: string;
+    readonly rules: readonly string[];
+}
+export interface SkeletonStep {
+    readonly id: string;
+    readonly name: string;
+    readonly track: string;
+    readonly step_type: string;
+    readonly agent: string;
+    readonly packages: readonly string[];
+    readonly depends_on: readonly string[];
+    readonly caveats: readonly string[];
+    /** The other permitted methods of the step, from the central procedure step. */
+    readonly alternatives: readonly SkeletonAlternative[];
+    /** A disputed rule of the group with its sides. The planner chooses one side and states the choice. */
+    readonly disputed?: {
+        readonly rule: string;
+        readonly sides: readonly string[];
+    };
+    /** The method ids the rules forbid in the steps of the group. */
+    readonly forbids: readonly string[];
+    /** The environment of the central step, when the host bound the stores: the package in the farm and the collection in the reference store. */
+    readonly environment?: StepEnvironment;
+    readonly grounding: {
+        readonly status: "grounded" | "ungrounded" | "flagged";
+        readonly snapshot: string;
+        readonly claims: readonly string[];
+        readonly template?: string;
+        /** One entry per parameter of the procedure steps of the group, with the step it belongs to. */
+        readonly settings: readonly GroundingSetting[];
+        readonly reason: string;
+    };
+}
+export declare function buildPlanSkeleton(answer: RecommendWithEnvironment): SkeletonStep[];