@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/tools/knowledge/check.js

@@ -0,0 +1,92 @@
+/**
+ * `knowledge_check` — the drafted steps against the rules, once, before
+ * `submit_plan`. A violation names the rule and the permitted alternatives.
+ * The planner revises once. There is no loop: the host counts the calls of
+ * one plan generation, and past `CHECK_CALL_LIMIT` the tool answers with a
+ * typed refusal and never reaches the service. A small model that cannot
+ * satisfy a finding otherwise rephrases the step until the plan times out.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { SituationFieldsSchema, toSituation } from "./situation.js";
+/** The checks one plan generation may run. Two is a draft and one revision; the third is slack. */
+export const CHECK_CALL_LIMIT = 3;
+const DraftedStepSchema = z.object({
+    step_type: z
+        .enum([
+        "cohort_assembly",
+        "qc_sample_structure",
+        "filter_low_counts",
+        "normalize",
+        "model_design",
+        "differential_expression",
+        "shrink_lfc",
+        "multiple_testing",
+        "enrichment",
+        "variance_partition",
+        "tf_activity",
+        "pathway_activity",
+        "signature_scoring",
+        "deconvolution",
+        "coexpression",
+        "clustering",
+        "survival",
+        "transcript_level",
+        "annotation",
+        "report",
+    ])
+        .describe("The kind of work the drafted step does."),
+    method: z.string().min(1).describe("The method as the step names it, for example `DESeq2 Wald test` or `edgeR quasi-likelihood`."),
+    method_id: z
+        .string()
+        .regex(/^M-\d{4}$/)
+        .optional()
+        .describe("The `method.id` of the step in the `knowledge_recommend` answer (for example `M-0001`), copied when the step uses that method. With it the check matches the method exactly and ignores the wording."),
+    package: z.string().optional().describe("The main package of the step, for example `DESeq2`."),
+    parameters: z
+        .array(z.object({ name: z.string().min(1), value: z.union([z.string(), z.number(), z.boolean()]) }))
+        .optional()
+        .describe("The key parameters of the step, for example `alpha`, `min_count`, `lfc_shrink`, `rank_metric`."),
+    outcome: z
+        .string()
+        .optional()
+        .describe("The outcome the step states when a flag of `knowledge_recommend` removes inference, copied from the flag, for example `descriptive_only`."),
+});
+/** `ok`, or the counts of the findings, plus the steps the check did not assess when there are any. */
+function describeFindings(result) {
+    const findings = result.ok ? "ok" : `${result.violations.length} violation(s), ${result.warnings.length} warning(s)`;
+    const notAssessed = result.not_assessed?.length ?? 0;
+    return notAssessed > 0 ? `${findings}, ${notAssessed} not assessed` : findings;
+}
+export function createKnowledgeCheckTool(deps) {
+    let calls = 0;
+    return defineTool({
+        id: "knowledge_check",
+        description: "Check the method steps you drafted for a bulk RNA-seq analysis against the rules of the Inflexa knowledge service, once, after the draft and before `submit_plan`. " +
+            "Send the same situation you sent to `knowledge_recommend` and the drafted steps: the step type, the method as the step names it, its package, and its key parameters. " +
+            "The answer lists `violations` (a forbidden method, or an inferential test on a design that a flag limits) and `warnings` (a method outside the set the rules name, a parameter that differs from a sourced default, or a required parameter that the step does not state), each with the rule id and the permitted alternatives. " +
+            "Revise a violated step once, then submit. A warning is advice: keep the step when the data gives a reason, and state the reason in the step. `ok: true` means no finding on the assessed steps. " +
+            "`not_assessed` lists the steps that no rule covers; the check neither passed nor failed them, so submit them as drafted. " +
+            "`match: unavailable` means the service did not answer, and `match: snapshot_mismatch` means the service moved to another release than the one your recommend answer came from; in both cases submit the draft as it is. " +
+            `The host accepts ${CHECK_CALL_LIMIT} checks per plan; after that the tool refuses and you submit with the findings you have.`,
+        inputSchema: SituationFieldsSchema.extend({
+            steps: z.array(DraftedStepSchema).min(1).describe("The drafted method steps, one entry per step type."),
+        }),
+        describeCall: ({ steps }) => `${steps.length} drafted step(s)`,
+        describeResult: (_input, result) => ("ok" in result ? describeFindings(result) : result.match),
+        execute: async (input) => {
+            calls += 1;
+            if (calls > CHECK_CALL_LIMIT) {
+                return ok({
+                    match: "rejected",
+                    message: `The host accepts ${CHECK_CALL_LIMIT} checks per plan, and this is call ${calls}. Submit the plan with the findings of the last check.`,
+                    issues: [],
+                });
+            }
+            const { steps, ...fields } = input;
+            const answer = await deps.client.check(toSituation(fields), steps, deps.pin?.get());
+            return ok(answer);
+        },
+    });
+}

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

@@ -0,0 +1,382 @@
+/**
+ * The knowledge service interface of the harness.
+ *
+ * `KnowledgeClient` is the one contract between the harness and the remote
+ * knowledge service: four typed operations and the snapshot they answer
+ * from. The harness never knows about a license. It sees a client, or it sees
+ * nothing, and an absent client is a normal state in which no knowledge tool
+ * attaches. `createHttpKnowledgeClient` is the shipped realization over plain
+ * HTTPS with the retry and timeout policy of the other external tools.
+ *
+ * Every operation answers a data variant. A service that is configured but
+ * unreachable gives `{ match: "unavailable" }` after the retry policy, and the
+ * caller continues from the prose skills. A 400 names the field and the
+ * permitted values, thus a model corrects itself in one turn. A 404 on the
+ * contract lookup names the `template` field the same way. The response
+ * shapes below are the harness copy of the wire contract of the service, kept
+ * lenient with `looseObject`, thus a richer answer of a later snapshot still
+ * parses.
+ */
+import { z } from "zod";
+/** The role of the blocking factor. A role and never a column name, because the situation leaves the machine. */
+export type BlockingRole = "individual" | "cell_line" | "litter" | "site" | "pair" | "other";
+/** The role of a covariate of the design. A role and never a column name. */
+export type CovariateRole = "sex" | "age" | "clinical" | "technical" | "other";
+/** The role of the numeric variable of interest when the question is a trend, not a comparison of groups. */
+export type PredictorRole = "dose" | "time" | "age" | "score" | "other";
+/** The typed description of one analysis situation. Never a sample row, never an identifier, and never a column name. */
+export interface KnowledgeSituation {
+    readonly question: "differential_expression" | "enrichment" | "qc" | "full_plan";
+    readonly modality: "bulk_rna_seq";
+    readonly data_state: "fastq" | "counts" | "tpm_or_fpkm" | "log_normalized";
+    readonly count_source?: "salmon" | "kallisto" | "star_featurecounts" | "rsem" | "unknown";
+    /** Whether the length correction of a quantifier occurred. Never required: the service sets `unknown` on counts. */
+    readonly import_state?: "quantifications" | "estimated_counts_with_lengths" | "corrected_counts" | "integer_counts" | "unknown";
+    readonly organism: "human" | "mouse" | "other";
+    readonly n_groups: number;
+    readonly n_per_group_min: number;
+    readonly n_per_group_max: number;
+    /** The total number of biological samples. Never required. */
+    readonly n_samples?: number;
+    /** The number of samples with an observed event, for a survival question. Never required. */
+    readonly n_events?: number;
+    readonly paired: boolean;
+    /** The role of the blocking factor, or null. The column name stays on the machine. */
+    readonly blocking_factor?: BlockingRole | null;
+    /** How the blocking factor relates to the condition: crossed, or nested inside one condition. */
+    readonly block_structure?: "crossed" | "nested";
+    readonly batch: "none" | "known_balanced" | "known_confounded" | "known_unbalanced" | "suspected";
+    /** The role of each covariate of the design, one entry per covariate. The column names stay on the machine. */
+    readonly covariates?: readonly CovariateRole[];
+    readonly n_timepoints?: number | null;
+    /** The role of the numeric variable of interest when the question is a trend over it; then `n_groups` is 1. The column name stays on the machine. */
+    readonly continuous_predictor?: PredictorRole | null;
+    /** True when some columns of the count table are technical replicates of one biological sample. */
+    readonly technical_replicates?: boolean;
+    /** The row unit of the count table. Absent for a gene-level table. */
+    readonly feature_level?: "gene" | "exon" | "transcript";
+    readonly library_type?: "polyA" | "total" | "three_prime" | "unknown";
+    readonly strandedness?: "verified" | "declared_unverified" | "unknown";
+    readonly interaction?: boolean;
+    /** True for a classifier of the samples into classes; absent for a per-sample score. */
+    readonly classifier?: boolean;
+    readonly quality_flags?: readonly ("low_depth_sample" | "outlier_sample" | "sample_identity_doubt" | "high_duplication" | "degraded_rna")[];
+}
+export declare const RecommendResponseSchema: z.ZodObject<{
+    match: z.ZodEnum<{
+        none: "none";
+        applicable: "applicable";
+        flag: "flag";
+    }>;
+    snapshot: z.ZodObject<{
+        date: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strip>;
+    procedure: z.ZodArray<z.ZodObject<{
+        step: z.ZodString;
+        method: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$loose>>;
+        template: z.ZodOptional<z.ZodString>;
+        rules: z.ZodArray<z.ZodString>;
+        flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            rule: z.ZodString;
+            severity: z.ZodString;
+            message: z.ZodString;
+            outcome: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        alternatives: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            method: z.ZodString;
+            label: z.ZodString;
+            when: z.ZodString;
+            rules: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>>>;
+        disputed: z.ZodOptional<z.ZodObject<{
+            rule: z.ZodString;
+            sides: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>>;
+        parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodUnknown;
+            default_source: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        conflicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            parameter: z.ZodString;
+            entries: z.ZodArray<z.ZodObject<{
+                rule: z.ZodString;
+                value: z.ZodUnknown;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>>;
+        substitution: z.ZodOptional<z.ZodObject<{
+            for: z.ZodString;
+            label: z.ZodString;
+            template: z.ZodString;
+        }, z.core.$loose>>;
+        limit: z.ZodOptional<z.ZodObject<{
+            requested_language: z.ZodEnum<{
+                R: "R";
+                python: "python";
+            }>;
+            reason: z.ZodString;
+            skipped: z.ZodArray<z.ZodObject<{
+                template: z.ZodString;
+                missing: z.ZodArray<z.ZodString>;
+                refused: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        unrealized: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodString;
+            templates: z.ZodArray<z.ZodObject<{
+                template: z.ZodString;
+                why: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    uncovered: z.ZodArray<z.ZodString>;
+    unrealized: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    flags: z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        severity: z.ZodString;
+        message: z.ZodString;
+        outcome: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    claims: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        strength: z.ZodString;
+        evidence: z.ZodArray<z.ZodObject<{
+            doi: z.ZodOptional<z.ZodString>;
+            pmid: z.ZodOptional<z.ZodString>;
+            title: z.ZodString;
+            year: z.ZodNumber;
+            direction: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    nearest: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        title: z.ZodString;
+        failed: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type RecommendResponse = z.infer<typeof RecommendResponseSchema>;
+export declare const CheckResponseSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    snapshot: z.ZodObject<{
+        date: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strip>;
+    violations: z.ZodArray<z.ZodObject<{
+        step_type: z.ZodString;
+        severity: z.ZodString;
+        rule: z.ZodString;
+        message: z.ZodString;
+        permitted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    warnings: z.ZodArray<z.ZodObject<{
+        step_type: z.ZodString;
+        severity: z.ZodString;
+        rule: z.ZodString;
+        message: z.ZodString;
+        permitted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    not_assessed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        step_type: z.ZodString;
+        reason: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type CheckResponse = z.infer<typeof CheckResponseSchema>;
+export declare const RenderResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    snapshot: z.ZodObject<{
+        date: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strip>;
+    template: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        label: z.ZodString;
+        method: z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$loose>;
+        substitute_for: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$loose>>;
+        language: z.ZodString;
+    }, z.core.$loose>;
+    script: z.ZodString;
+    slots: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodOptional<z.ZodUnknown>;
+        source: z.ZodString;
+        adaptable: z.ZodBoolean;
+        lines: z.ZodArray<z.ZodNumber>;
+        read: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    local_slots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    environment: z.ZodObject<{
+        match: z.ZodString;
+    }, z.core.$loose>;
+    syntax: z.ZodObject<{
+        status: z.ZodString;
+    }, z.core.$loose>;
+    outputs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    decision_record: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$loose>;
+export type RenderResponse = z.infer<typeof RenderResponseSchema>;
+/**
+ * One slot of a template with the constraint a caller value must obey.
+ * `adaptable: false` marks a pinned slot: the render refuses a caller value
+ * for it. An adaptable slot without a default is required unless `required`
+ * is false.
+ */
+declare const TemplateParameterSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+    description: z.ZodString;
+    adaptable: z.ZodBoolean;
+    local: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+    default_source: z.ZodOptional<z.ZodString>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pattern: z.ZodOptional<z.ZodString>;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type TemplateParameter = z.infer<typeof TemplateParameterSchema>;
+/**
+ * The contract of one template as `GET /v1/templates/{id}` serves it: every
+ * slot, pinned ones included, the inputs, and the outputs. The service adds
+ * fields such as `step_types` and `environment`; they pass through the loose
+ * remainder.
+ */
+export declare const TemplateContractSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    label: z.ZodString;
+    method: z.ZodString;
+    substitute_for: z.ZodOptional<z.ZodString>;
+    language: z.ZodString;
+    honors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    parameters: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        description: z.ZodString;
+        adaptable: z.ZodBoolean;
+        local: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+        default_source: z.ZodOptional<z.ZodString>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pattern: z.ZodOptional<z.ZodString>;
+        minimum: z.ZodOptional<z.ZodNumber>;
+        maximum: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    outputs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type TemplateContract = z.infer<typeof TemplateContractSchema>;
+/** The preferences of the caller: the language of the template the answer names. */
+export interface KnowledgePreferences {
+    readonly language?: "R" | "python";
+}
+/** What a drafted step carries into the check. */
+export interface DraftedStep {
+    readonly step_type: string;
+    readonly method: string;
+    /** The catalog id of the method (`M-dddd`), copied from the recommendation. An exact match wins over the wording. */
+    readonly method_id?: string;
+    readonly package?: string;
+    readonly parameters?: readonly {
+        readonly name: string;
+        readonly value: string | number | boolean;
+    }[];
+    /** The outcome the step states when the design forbids inference, for example `descriptive_only`. */
+    readonly outcome?: string;
+}
+export interface FarmPackage {
+    readonly name: string;
+    readonly version: string;
+}
+/** The service could not answer after the retry policy. The run continues from the prose skills. */
+export interface KnowledgeUnavailable {
+    readonly match: "unavailable";
+    readonly reason: string;
+}
+/**
+ * The service serves another release than the one the plan pinned, and it
+ * did no work. A plan is not moved to a new release in silence: the caller
+ * proceeds as with an unavailable service, and it states the two digests.
+ */
+export interface KnowledgeSnapshotMismatch {
+    readonly match: "snapshot_mismatch";
+    readonly message: string;
+    readonly expected: string;
+    readonly served: {
+        readonly date: string;
+        readonly digest: string;
+    };
+}
+/** The service refused the request and named the field or the slot and the permitted values. */
+export interface KnowledgeRejected {
+    readonly match: "rejected";
+    readonly message: string;
+    readonly issues: readonly {
+        readonly field?: string;
+        readonly slot?: string;
+        readonly message?: string;
+        readonly reason?: string;
+        readonly permitted?: readonly string[];
+    }[];
+}
+/** What a render call carries beside the template and the slots. */
+export interface RenderCallOptions {
+    /** The id of the plan step that runs the script. */
+    readonly step?: string;
+    /** The claims of the plan step that selected the template. Each must resolve in the served snapshot. */
+    readonly claims?: readonly string[];
+    /** The release digest the plan pinned. The service refuses another release with `snapshot_mismatch`. */
+    readonly expectedSnapshot?: string;
+}
+export interface KnowledgeClient {
+    /** `expectedSnapshot` pins the release of an earlier answer of the same plan; the first call of a plan has none. */
+    recommend(situation: KnowledgeSituation, responseFormat?: "concise" | "detailed", preferences?: KnowledgePreferences, expectedSnapshot?: string): Promise<RecommendResponse | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch>;
+    check(situation: KnowledgeSituation, steps: readonly DraftedStep[], expectedSnapshot?: string): Promise<CheckResponse | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch>;
+    /** `slots` never holds a local slot: the host binds those after the render, on the machine. */
+    render(template: string, slots: Readonly<Record<string, unknown>>, farm?: readonly FarmPackage[], options?: RenderCallOptions): Promise<RenderResponse | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch>;
+    /**
+     * The slot contract of a template, by reference (`tpl-x@1.0.0`) or by id.
+     * The service serves one version per snapshot, thus the answer carries the
+     * version it serves and the caller compares it with the reference. An
+     * unknown template is `rejected` with the field `template`.
+     */
+    contract(template: string): Promise<TemplateContract | KnowledgeUnavailable | KnowledgeRejected>;
+}
+export interface HttpKnowledgeClientConfig {
+    /** The service origin, for example `https://knowledge.inflexa.ai`. */
+    readonly baseUrl: string;
+    /** The bearer key. The license of the service. */
+    readonly apiKey: string;
+    readonly timeoutMs?: number;
+    readonly maxRetries?: number;
+}
+export declare function createHttpKnowledgeClient(config: HttpKnowledgeClientConfig): KnowledgeClient;
+export {};