textopt 0.0.0

package/dist/types-CWv4IQFF.d.mts

@@ -0,0 +1,129 @@
+//#region src/types.d.ts
+/**
+ * A candidate is a map of named text components to their current text. This is
+ * the unit of optimization — prompts, instructions, code, tool descriptions,
+ * anything expressible as a named string.
+ *
+ * `K` is the union of component names, inferred from the seed candidate, so a
+ * misspelled component is a compile error rather than a silent no-op.
+ */
+type Candidate<K extends string = string> = Record<K, string>;
+/**
+ * What one rollout consumed. Every field is optional because providers report
+ * different subsets, and a partial reading is still worth more than none.
+ */
+interface RolloutUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Defaults to the sum of the two token counts when they are reported. */
+  totalTokens?: number;
+  costUsd?: number;
+}
+/** Usage summed over a run, alongside the rollouts that produced it. */
+interface UsageTotals {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  costUsd: number;
+  /** Fresh rollouts counted here. Cached instances buy nothing. */
+  rollouts: number;
+}
+/**
+ * Result of running a candidate over a batch of data instances.
+ *
+ * `scores` is the load-bearing field: one number per instance, higher is
+ * better. `feedback` is a per-instance textual diagnosis of what went wrong,
+ * which a reflective optimizer reads to write a better candidate.
+ */
+interface EvaluationBatch<Trajectory = unknown, Output = unknown> {
+  outputs: Output[];
+  scores: number[];
+  /**
+   * What each rollout consumed. Rollout counts are the budget, but they are a
+   * poor proxy for spend: reflective search grows the text it optimizes, so
+   * the same rollout costs more late in a run than early in it.
+   */
+  usage?: RolloutUsage[];
+  feedback?: string[];
+  trajectories?: Trajectory[];
+  objectiveScores?: Record<string, number>[];
+  /**
+   * Per-instance: true when the score reflects an infrastructure failure
+   * rather than the candidate's behaviour. Transient scores are never written
+   * to the evaluation cache.
+   */
+  transient?: boolean[];
+}
+/**
+ * What a per-instance scorer returns. Shared by every adapter so scorers are
+ * portable between them — a Braintrust scorer works in a LangChain run.
+ */
+interface ScoreResult {
+  score: number;
+  feedback?: string;
+  objectiveScores?: Record<string, number>;
+  /** What this rollout consumed, when the caller can see it. */
+  usage?: RolloutUsage;
+  /**
+   * Marks a score produced by an infrastructure failure — a rate limit, a
+   * network blip, a provider 5xx — rather than by the candidate. Without this
+   * the engine cannot tell such a zero from a genuine one, and would cache it
+   * permanently against the candidate.
+   */
+  transient?: boolean;
+}
+interface EvaluateArgs<Datum, K extends string = string> {
+  batch: readonly Datum[];
+  candidate: Candidate<K>;
+  captureTraces: boolean;
+  /**
+   * Where this batch sits in the run. Forward it to whatever tracing the
+   * system under optimization already has — without it a run is thousands of
+   * indistinguishable rollouts, and no trace can be tied back to the iteration
+   * whose score moved.
+   */
+  run: EvaluationContext;
+  signal?: AbortSignal;
+}
+/**
+ * Identifies one evaluation within a run. `candidateId` is null while the
+ * candidate is still a proposal being screened on a minibatch: it has no
+ * record, and inventing an id for it would collide with the one it gets if it
+ * is accepted.
+ */
+interface EvaluationContext {
+  iteration: number;
+  phase: EvaluationPhase;
+  split: EvaluationSplit;
+  candidateId: number | null;
+}
+type EvaluationPhase = "seed" | "minibatch" | "validation" | "test";
+/**
+ * Which dataset an instance id was drawn from. Each split numbers its ids
+ * independently, so the same id can name three different instances; the cache
+ * key has to keep them apart.
+ */
+type EvaluationSplit = "train" | "val" | "test";
+/**
+ * The single integration seam between an optimizer and a system under
+ * optimization. Everything framework-specific — LangChain, the AI SDK,
+ * Braintrust — lives in an implementation of this interface.
+ */
+interface Adapter<Datum, Trajectory = unknown, Output = unknown, K extends string = string> {
+  evaluate(args: EvaluateArgs<Datum, K>): Promise<EvaluationBatch<Trajectory, Output>> | EvaluationBatch<Trajectory, Output>;
+}
+/** Provider-agnostic text model: text in, text out. */
+type TextModel = (args: {
+  prompt: string;
+  signal?: AbortSignal;
+}) => Promise<string>;
+/**
+ * The component names of a candidate, as the union they were inferred from.
+ *
+ * `Object.keys` widens a closed key union back to `string`. This is the one
+ * place that narrowing happens, so every other caller stays assertion-free.
+ * Accepts a partial so it also names the components of a component patch.
+ */
+declare function componentNames<K extends string>(candidate: Partial<Candidate<K>>): K[];
+//#endregion
+export { EvaluationContext as a, RolloutUsage as c, UsageTotals as d, componentNames as f, EvaluationBatch as i, ScoreResult as l, Candidate as n, EvaluationPhase as o, EvaluateArgs as r, EvaluationSplit as s, Adapter as t, TextModel as u };

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "textopt",
+  "version": "0.0.0",
+  "description": "Prompt optimization for TypeScript, with GEPA, OPRO, MIPRO, and random search behind a shared interface",
+  "keywords": [
+    "prompt-optimization",
+    "gepa",
+    "mipro",
+    "opro",
+    "llm",
+    "prompt-engineering",
+    "dspy",
+    "evaluation"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/ctdio/textopt#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctdio/textopt.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/ctdio/textopt/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./file-cache": {
+      "import": {
+        "types": "./dist/file-cache.d.mts",
+        "default": "./dist/file-cache.mjs"
+      },
+      "require": {
+        "types": "./dist/file-cache.d.cts",
+        "default": "./dist/file-cache.cjs"
+      }
+    },
+    "./gepa": {
+      "import": {
+        "types": "./dist/gepa/index.d.mts",
+        "default": "./dist/gepa/index.mjs"
+      },
+      "require": {
+        "types": "./dist/gepa/index.d.cts",
+        "default": "./dist/gepa/index.cjs"
+      }
+    },
+    "./simba": {
+      "import": {
+        "types": "./dist/simba/index.d.mts",
+        "default": "./dist/simba/index.mjs"
+      },
+      "require": {
+        "types": "./dist/simba/index.d.cts",
+        "default": "./dist/simba/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing.d.mts",
+        "default": "./dist/testing.mjs"
+      },
+      "require": {
+        "types": "./dist/testing.d.cts",
+        "default": "./dist/testing.cjs"
+      }
+    },
+    "./random-search": {
+      "import": {
+        "types": "./dist/random-search/index.d.mts",
+        "default": "./dist/random-search/index.mjs"
+      },
+      "require": {
+        "types": "./dist/random-search/index.d.cts",
+        "default": "./dist/random-search/index.cjs"
+      }
+    },
+    "./opro": {
+      "import": {
+        "types": "./dist/opro/index.d.mts",
+        "default": "./dist/opro/index.mjs"
+      },
+      "require": {
+        "types": "./dist/opro/index.d.cts",
+        "default": "./dist/opro/index.cjs"
+      }
+    },
+    "./bootstrap-search": {
+      "import": {
+        "types": "./dist/bootstrap-search/index.d.mts",
+        "default": "./dist/bootstrap-search/index.mjs"
+      },
+      "require": {
+        "types": "./dist/bootstrap-search/index.d.cts",
+        "default": "./dist/bootstrap-search/index.cjs"
+      }
+    },
+    "./mipro": {
+      "import": {
+        "types": "./dist/mipro/index.d.mts",
+        "default": "./dist/mipro/index.mjs"
+      },
+      "require": {
+        "types": "./dist/mipro/index.d.cts",
+        "default": "./dist/mipro/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}