v2 #4: LLM inference from a deal description (v0.8.0)

New \`--from-deal PATH\` flag reads a free-form deal description and
asks the configured T5 LLM provider to extract values for the
schema's declared placeholders. The inverse of T5 detection: instead
of inferring WHERE placeholders are, infer WHAT values they should
take from prose deal notes.

Resolution precedence updated:
  CLI > --params > --from-deal (LLM) > --interactive > default > error

CLI / --params always win, so the user can fix or override anything
the LLM got wrong without re-running inference.

Locked decisions (V2_BRIEFS_REMAINING Q4.1–Q4.3):
- Q4.1: same T5 provider (Anthropic / OpenAI / DRAFT_LLM_*). One
  network surface, one env-var set.
- Q4.2: extra keys (LLM emits keys not in the placeholder list)
  warn to stderr; the LLM gets the allowed-key list in the prompt
  so this is rare in practice.
- Q4.3: --from-deal does NOT require explicit --llm; inference is
  implicit when the flag is set. --no-llm still disables.

Implementation:
- New --from-deal PATH CLI flag.
- inferFromDeal(dealText, placeholders, providerCfg, { fetcher }):
  builds a prompt with deal text + allowed keys, calls callLlm
  (existing helper), parses JSON response, splits values vs
  extraKeys vs warnings. Empty placeholder list short-circuits
  without an LLM call.
- resolveValues gains an \`inferred\` option used between --params
  and --interactive precedence levels.
- main() loads dealText from opts.fromDeal and threads it through
  the IO options bag to cmdDraft + cmdValidate.
- cmdDraft + cmdValidate call inferFromDeal before resolveValues
  when dealText is present and --no-llm not set.

Constraints documented:
- --from-deal errors are fatal (EXIT.LLM) — users see bad provider
  configs immediately, not silently with no inferred values.
- Bundle mode doesn't yet thread --from-deal per-template (deferred);
  shared --params JSON is the bundle-friendly structured-data path.

Tests: 282 passing (269 baseline + 13 new). Coverage: inferFromDeal
unit (happy path, extra keys, numeric coercion, non-string warning,
missing provider, malformed LLM response, empty-placeholders short-
circuit); end-to-end via main() with fakeFetcher for happy path,
CLI > inferred precedence, extra-keys warning, --no-llm disables,
missing file errors, missing provider errors.

CHANGELOG + PARAM_SCHEMA.md §5 updated. v0.8.0. This completes the
v2-remaining feature surface from V2_BRIEFS_REMAINING.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DrBaher

CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project will be documented in this file. The
 format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
 and the project adheres to semantic versioning once it leaves 0.x.
 
+## 0.8.0 — 2026-05-17
+
+### Added
+
+- **LLM inference from a deal description** (last v2 item). New
+  `--from-deal PATH` flag reads a free-form deal description and
+  asks the configured T5 LLM provider to extract values for the
+  schema's declared placeholders:
+  ```sh
+  draft nda.md --from-deal deal-notes.txt --output draft.md
+  ```
+  Where `deal-notes.txt` is unstructured prose:
+  ```
+  Mutual NDA between Acme Corporation (DE) and Globex (UK), effective
+  June 1, 2026, for a 2-year term.
+  ```
+  The LLM is asked to fill `party_a`, `party_a_state`, `party_b`,
+  `effective_date`, etc. — only the keys already detected as
+  placeholders are extracted.
+- **Value-resolution precedence updated:**
+  `CLI flag > --params JSON > --from-deal (LLM) > --interactive > schema default > error`.
+  CLI / --params always win, so users can fix or override anything
+  the LLM got wrong.
+- **New public API:** `inferFromDeal(dealText, placeholders, providerCfg, { fetcher })`.
+
+### Decisions locked (V2_BRIEFS_REMAINING Q4.1–Q4.3)
+
+- **Q4.1 Provider:** same T5 provider config — `ANTHROPIC_API_KEY`,
+  `OPENAI_API_KEY`, or explicit `DRAFT_LLM_*`. No separate inference
+  provider; one network surface, one set of env vars.
+- **Q4.2 Extra keys:** keys the LLM emits that aren't in the
+  detected placeholders are **warned** to stderr (not dropped
+  silently). The LLM gets a fresh list of allowed keys in the
+  prompt so this is rare in practice.
+- **Q4.3 Auto-LLM:** `--from-deal` does **not** require an
+  explicit `--llm` flag — the inference is implicit. `--no-llm`
+  still disables it (the user can opt out of the network call).
+
+### Notes
+
+- `--from-deal` errors are fatal (`EXIT.LLM` for provider /
+  network / parse failures). Users with bad provider configs see
+  the issue immediately rather than silently running with no
+  inferred values.
+- Bundle mode (v0.7.0) does not yet thread `--from-deal` through
+  per-template inference. Deferred to a follow-up; the shared
+  parameter resolution makes the single-doc API already useful
+  for bundles via `--params`.
+
 ## 0.7.0 — 2026-05-17
 
 ### Added

PARAM_SCHEMA.md

@@ -515,6 +515,71 @@ keys and their sources.
 Programmatic API: `loadBundle(path)` parses + validates; `cmdBundle`
 runs the orchestration with the same IO contract as `cmdDraft`.
 
+### LLM inference from a deal description (v0.8.0, opt-in)
+
+`--from-deal PATH` reads a free-form deal description and asks the
+configured T5 LLM provider to extract values for the schema's
+declared placeholders. The inverse of T5 detection — instead of
+inferring *where* placeholders are in a template, infer *what
+values* they should take from the deal prose:
+
+```sh
+draft nda.md --from-deal deal-notes.txt --output draft.md
+```
+
+```
+# deal-notes.txt
+Mutual NDA between Acme Corporation (DE) and Globex (UK),
+effective June 1, 2026, for a 2-year term.
+```
+
+Then `[Party A]` → `Acme Corporation`, `[Effective Date]` →
+`June 1, 2026`, etc., without any `--party-a` / `--effective-date`
+flags.
+
+**Value-resolution precedence** with `--from-deal`:
+
+```
+CLI flag  >  --params JSON  >  --from-deal (LLM)  >  --interactive  >  schema default  >  error
+```
+
+CLI / --params always win, so users can fix or override anything the
+LLM got wrong without re-running inference.
+
+**Q4.1 locked:** same T5 provider config (`ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, or explicit `DRAFT_LLM_*`). One network surface,
+one set of env vars.
+
+**Q4.2 locked:** extra keys (LLM emits keys not in the detected
+placeholder list) are **warned** to stderr, not silently dropped.
+The LLM gets the allowed-key list in the prompt so this is rare in
+practice.
+
+**Q4.3 locked:** `--from-deal` does **not** require explicit
+`--llm` — the inference is implicit when the flag is present.
+`--no-llm` still disables the inference call (the user can opt
+out of the network).
+
+**Provider missing:** if no LLM provider is configured (no
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `DRAFT_LLM_*` in env),
+`--from-deal` errors immediately with `EXIT.LLM` (exit 5) and a
+clear message. Same for network / HTTP errors / non-JSON LLM
+responses.
+
+**Resolution interaction with typed parameters:** inferred values
+go through the same typed-normalization step as user-supplied
+values. So an LLM that returns `"June 1, 2026"` for a `type: date`
+parameter with `format: yyyy-MM-d` gets normalized to `2026-06-1`
+before substitution.
+
+**Bundle mode (v0.7.0) interaction:** bundles do not currently
+thread `--from-deal` through per-template inference. The shared
+parameter resolution already accepts `--params` JSON, which is the
+simpler structured-data path for bundle workflows. Deferred to a
+future release.
+
+Programmatic API: `inferFromDeal(dealText, placeholders, providerCfg, { fetcher })`.
+
 ### Orphan handling (Q4 locked)
 
 Schema declares a key whose alias list matches no detected phrase →

draft-cli.mjs

@@ -70,7 +70,7 @@ import { fileURLToPath } from "node:url";
  */
 
 /** @type {string} */
-export const VERSION = "0.7.0";
+export const VERSION = "0.8.0";
 
 // ─── EXIT CODES ─────────────────────────────────────────────────────────────
 /**
@@ -279,6 +279,7 @@ export function parseArgs(argv) {
     if (a === "--params") { opts.params = argv[++i]; continue; }
     if (a === "--parties") { opts.parties = argv[++i]; continue; }
     if (a === "--bundle") { opts.bundle = argv[++i]; continue; }
+    if (a === "--from-deal") { opts.fromDeal = argv[++i]; continue; }
     if (a === "--output" || a === "-o") { opts.output = argv[++i]; continue; }
     if (a === "--syntax") {
       const v = argv[++i];
@@ -808,6 +809,95 @@ ${body.slice(0, 12000)}`;
   return out;
 }
 
+/**
+ * v2 #4: LLM inference from a free-form deal description.
+ *
+ * Takes the prose deal description (the user's notes about parties, dates,
+ * amounts, etc.) and asks the configured T5 LLM provider to extract values
+ * for the placeholders the cascade has already detected. Returns
+ * `{values, extraKeys, warnings}`:
+ *
+ *   - values: `{key: string}` for every placeholder key the LLM filled
+ *   - extraKeys: any keys the LLM emitted that aren't in the placeholders list (Q4.2 → warn)
+ *   - warnings: human-readable messages for malformed entries
+ *
+ * Throws on missing provider config, missing `fetch`, network/HTTP error, or
+ * non-JSON LLM response — same failure boundaries as `detectLlm`.
+ *
+ * @param {string} dealText — free-form deal description
+ * @param {Placeholder[]} placeholders — the post-detection placeholder list
+ * @param {ReturnType<llmProviderFromEnv>} providerCfg
+ * @param {{ fetcher?: typeof fetch | null }} [opts]
+ * @returns {Promise<{ values: Object<string,string>, extraKeys: string[], warnings: string[] }>}
+ */
+export async function inferFromDeal(dealText, placeholders, providerCfg, { fetcher = (typeof fetch !== "undefined" ? fetch : null) } = {}) {
+  if (!fetcher) {
+    const e = new Error("fetch is not available; Node 18+ is required for --from-deal");
+    e.exitCode = EXIT.LLM;
+    throw e;
+  }
+  if (!providerCfg) {
+    const e = new Error("--from-deal requires an LLM provider; set ANTHROPIC_API_KEY / OPENAI_API_KEY / DRAFT_LLM_* in .env");
+    e.exitCode = EXIT.LLM;
+    throw e;
+  }
+  const wantedKeys = placeholders.map((p) => ({
+    key: p.key,
+    aliases: (p.aliases || []).slice(0, 4),
+    first_seen_as: p.first_seen_as,
+  }));
+  if (wantedKeys.length === 0) {
+    return { values: {}, extraKeys: [], warnings: [] };
+  }
+  const fieldList = wantedKeys.map((w) =>
+    `  - ${w.key} (template placeholder: "${w.first_seen_as}"${w.aliases.length > 1 ? `; aliases: ${w.aliases.join(", ")}` : ""})`
+  ).join("\n");
+  const prompt = `You are filling parameters for a legal-document drafting tool.
+A user has written prose describing a deal. Extract values for the following
+fields from the deal description. Output JSON ONLY in this exact shape, with
+no commentary:
+
+{"values":{"<key>":"<extracted_value>",...}}
+
+If a field can't be confidently extracted from the description, omit it (do
+NOT guess). Do not invent additional fields not in the list. Match the deal's
+language verbatim — don't reformat dates, currencies, or names.
+
+FIELDS:
+${fieldList}
+
+DEAL DESCRIPTION:
+${dealText.slice(0, 12000)}`;
+  const raw = await callLlm(providerCfg, prompt, fetcher);
+  let parsed;
+  try {
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    parsed = JSON.parse(jsonMatch ? jsonMatch[0] : raw);
+  } catch {
+    const e = new Error(`LLM returned non-JSON response for --from-deal`);
+    e.exitCode = EXIT.LLM;
+    throw e;
+  }
+  const rawValues = (parsed && typeof parsed.values === "object" && parsed.values) ? parsed.values : {};
+  const knownKeys = new Set(placeholders.map((p) => p.key));
+  const values = {};
+  const extraKeys = [];
+  const warnings = [];
+  for (const [k, v] of Object.entries(rawValues)) {
+    if (!knownKeys.has(k)) {
+      extraKeys.push(k);
+      continue;
+    }
+    if (v === null || v === undefined) continue;
+    if (typeof v !== "string" && typeof v !== "number") {
+      warnings.push(`--from-deal: value for "${k}" was ${typeof v}, expected string; skipped`);
+      continue;
+    }
+    values[k] = String(v);
+  }
+  return { values, extraKeys, warnings };
+}
+
 async function callLlm(cfg, prompt, fetcher) {
   if (cfg.provider === "anthropic") {
     const r = await fetcher("https://api.anthropic.com/v1/messages", {
@@ -1460,7 +1550,7 @@ export function loadBundle(path) {
  * @param {{ prompter?: (p: Placeholder) => Promise<string|null> }} [io]
  * @returns {Promise<ResolvedValues>}
  */
-export async function resolveValues(placeholders, opts, paramsObj, { prompter = nodePrompter } = {}) {
+export async function resolveValues(placeholders, opts, paramsObj, { prompter = nodePrompter, inferred = null } = {}) {
   const resolved = {};
   const missing = [];
   const sources = {};
@@ -1475,6 +1565,12 @@ export async function resolveValues(placeholders, opts, paramsObj, { prompter =
       sources[p.key] = "params";
       continue;
     }
+    // v2 #4: --from-deal LLM-inferred values, between --params and --interactive.
+    if (inferred && Object.prototype.hasOwnProperty.call(inferred, p.key)) {
+      resolved[p.key] = String(inferred[p.key]);
+      sources[p.key] = "deal-llm";
+      continue;
+    }
     if (opts.interactive) {
       const v = await prompter(p);
       if (v !== null && v !== undefined && v !== "") {
@@ -2089,7 +2185,7 @@ export async function cmdListPlaceholders(opts, input, schema, envObj, { fetcher
   return EXIT.OK;
 }
 
-export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null } = {}) {
+export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null, dealText = null } = {}) {
   const result = await runCascade(input, opts, schema, envObj, { fetcher });
   if (result.tier === "none") {
     err.write(paint("error: no placeholders detected by any tier\n", "red", err));
@@ -2109,7 +2205,24 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
     }
     return EXIT.VALIDATION;
   }
-  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj);
+  // v2 #4: --from-deal LLM inference (when dealText is present and
+  // --no-llm not set). Provider config comes from env. Errors are fatal
+  // to keep the user from running with partial inferred values.
+  let inferred = null;
+  if (dealText && !opts.noLlm) {
+    try {
+      const r = await inferFromDeal(dealText, result.placeholders, llmProviderFromEnv(envObj), { fetcher });
+      inferred = r.values;
+      for (const k of r.extraKeys) {
+        err.write(paint(`warning: --from-deal LLM emitted unknown key "${k}" (not in template/schema)\n`, "yellow", err));
+      }
+      for (const w of r.warnings) err.write(paint(`warning: ${w}\n`, "yellow", err));
+    } catch (e) {
+      err.write(paint(`error: ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.LLM;
+    }
+  }
+  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj, { inferred });
   if (missing.length > 0) {
     printMissing(missing, err);
     if (opts.json) {
@@ -2170,7 +2283,7 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
   return EXIT.OK;
 }
 
-export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null } = {}) {
+export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null, dealText = null } = {}) {
   const result = await runCascade(input, opts, schema, envObj, { fetcher });
   if (result.tier === "none") {
     const hasProvider = Boolean(llmProviderFromEnv(envObj));
@@ -2221,7 +2334,25 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     return EXIT.VALIDATION;
   }
 
-  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj);
+  // v2 #4: --from-deal LLM inference (when dealText is present and
+  // --no-llm not set). Provider config comes from env. Errors are fatal
+  // to keep the user from running with partial inferred values.
+  let inferred = null;
+  if (dealText && !opts.noLlm) {
+    try {
+      const r = await inferFromDeal(dealText, result.placeholders, llmProviderFromEnv(envObj), { fetcher });
+      inferred = r.values;
+      for (const k of r.extraKeys) {
+        err.write(paint(`warning: --from-deal LLM emitted unknown key "${k}" (not in template/schema)\n`, "yellow", err));
+      }
+      for (const w of r.warnings) err.write(paint(`warning: ${w}\n`, "yellow", err));
+    } catch (e) {
+      err.write(paint(`error: ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.LLM;
+    }
+  }
+
+  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj, { inferred });
   // Footgun guard: flag --typo'd-key VALUE that didn't match any detected
   // placeholder. Without this warning, a typo'd flag is silently dropped and
   // the user sees only a "missing required" error without the connection.
@@ -2839,13 +2970,22 @@ export async function main(argv, io = {}) {
     return EXIT.IO;
   }
 
-  let input, schema, paramsObj, envObj, parties;
+  let input, schema, paramsObj, envObj, parties, dealText;
   try {
     input = await resolveInput(opts.positional[0], { spawner, stdinReader });
     schema = loadSchema(input.path);
     paramsObj = loadParamsFile(opts.params);
     envObj = effectiveEnv(cwd, processEnv);
     parties = loadParties(opts.parties || null);
+    // v2 #4: --from-deal PATH reads a free-form deal description.
+    if (opts.fromDeal) {
+      if (!existsSync(opts.fromDeal)) {
+        const e = new Error(`deal description file not found: ${opts.fromDeal}`);
+        e.exitCode = EXIT.IO;
+        throw e;
+      }
+      dealText = readFileSync(opts.fromDeal, "utf8");
+    }
   } catch (e) {
     err.write(paint(`error: ${e.message}\n`, "red", err));
     return e.exitCode || EXIT.IO;
@@ -2856,9 +2996,9 @@ export async function main(argv, io = {}) {
       return await cmdListPlaceholders(opts, input, schema, envObj, { fetcher, out, err });
     }
     if (opts.validate) {
-      return await cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties });
+      return await cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties, dealText });
     }
-    return await cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties });
+    return await cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties, dealText });
   } catch (e) {
     err.write(paint(`error: ${e.message}\n`, "red", err));
     return e.exitCode || EXIT.IO;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drbaher/draft-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Fill placeholders in a legal-document template with parameter values. Part of the contract-operations suite.",
   "type": "module",
   "bin": {