@trazum/core 1.60.3 → 1.61.0

package/dist/write.js

@@ -0,0 +1,243 @@
+import { optimize } from './optimize.js';
+import { BUNDLED_CATALOGUE } from './pricing.js';
+/**
+ * The interview behind `trazum write`.
+ *
+ * Every other command in this product reads a prompt somebody already wrote.
+ * This one starts from nothing and asks. What it asks is the product: a
+ * question whose answer cannot change the output is waste, and waste is this
+ * tool's entire subject.
+ *
+ * **Deterministic, and deliberately so.** No model decides what to ask. The
+ * catalogue below is fixed, the gates are predicates over the answers so far,
+ * and the same answers produce the same interview on any machine — which is
+ * what lets the offline rule hold without a footnote.
+ *
+ * **Ids here, words in the CLI.** Same split as the rules catalogue: this file
+ * knows a slot exists and what opens it; `packages/cli/src/i18n` knows how to
+ * ask it in a locale. A locale changes the question, never which questions.
+ */
+/**
+ * The sections of an assembled prompt, in the order they are written.
+ *
+ * The order is fixed, and for a reason this tool can price: prompt caching is
+ * a byte-for-byte prefix match, so everything stable goes first and everything
+ * that varies per call goes last, which makes the cacheable prefix as long as
+ * the prompt allows.
+ */
+export const SECTIONS = [
+    'role',
+    'task',
+    'inputs',
+    'output',
+    'constraints',
+    'examples',
+    'failure-modes',
+];
+/**
+ * The closed vocabulary `output-shape` accepts.
+ *
+ * Named `OutputFormat` rather than `OutputShape` because that name is already
+ * taken by the usage report's finding about where output spend concentrates,
+ * and two unrelated things under one name in one package is how a consumer
+ * imports the wrong one.
+ */
+export const OUTPUT_FORMATS = ['prose', 'json', 'list', 'table'];
+const answered = (answers, id) => Object.prototype.hasOwnProperty.call(answers, id) && answers[id] !== null;
+const shapeIs = (...formats) => (answers) => {
+    const shape = answers['output-shape'];
+    return typeof shape === 'string' && formats.includes(shape);
+};
+/**
+ * The catalogue, in the order the interview walks it.
+ *
+ * Required first is not an accident: somebody who abandons the interview
+ * halfway should have answered the things without which there is no prompt at
+ * all, rather than having spent their attention on the optional half.
+ */
+export const SLOTS = [
+    { id: 'task', section: 'task', required: true },
+    { id: 'role', section: 'role', required: true },
+    { id: 'inputs', section: 'inputs', required: true },
+    { id: 'output-shape', section: 'output', required: true },
+    { id: 'output-schema', section: 'output', required: true, opensWhen: shapeIs('json', 'table') },
+    { id: 'output-length', section: 'output', required: false, opensWhen: shapeIs('prose', 'list') },
+    { id: 'audience', section: 'role', required: false },
+    { id: 'constraints', section: 'constraints', required: false },
+    { id: 'refusal', section: 'constraints', required: false },
+    { id: 'examples', section: 'examples', required: false },
+    {
+        id: 'example-inputs',
+        section: 'examples',
+        required: false,
+        opensWhen: (answers) => answered(answers, 'examples'),
+    },
+    { id: 'failure-modes', section: 'failure-modes', required: false },
+    { id: 'model', section: null, required: false },
+    { id: 'budget', section: null, required: false },
+];
+export const SLOT_IDS = SLOTS.map((entry) => entry.id);
+export function slot(id) {
+    return SLOTS.find((entry) => entry.id === id);
+}
+/** Whether a slot is worth asking, given what is known so far. */
+export function isOpen(entry, answers) {
+    return entry.opensWhen === undefined || entry.opensWhen(answers);
+}
+export function interview(answers) {
+    const open = SLOTS.filter((entry) => isOpen(entry, answers));
+    const has = (entry) => Object.prototype.hasOwnProperty.call(answers, entry.id);
+    const unasked = open.filter((entry) => !has(entry));
+    return {
+        next: unasked[0]?.id ?? null,
+        done: unasked.length === 0,
+        open: open.map((entry) => entry.id),
+        answered: open.filter((entry) => answered(answers, entry.id)).map((entry) => entry.id),
+        declined: open
+            .filter((entry) => has(entry) && answers[entry.id] === null)
+            .map((entry) => entry.id),
+        missing: unasked.filter((entry) => entry.required).map((entry) => entry.id),
+    };
+}
+/**
+ * How each slot appears in the assembled prompt.
+ *
+ * A slot either supplies the section's opening line on its own, or arrives
+ * under a label. Nothing here paraphrases an answer: the words are the
+ * author's, and a writer that rewrote them would be answering a question
+ * nobody asked it.
+ */
+const LABEL = {
+    role: null,
+    audience: 'Audience:',
+    task: null,
+    inputs: null,
+    'output-shape': 'Format:',
+    'output-schema': 'Fields:',
+    'output-length': 'At most:',
+    constraints: null,
+    refusal: 'When you cannot answer:',
+    examples: null,
+    'example-inputs': 'Input:',
+    'failure-modes': null,
+};
+/**
+ * The heading each section is written under.
+ *
+ * **English, in every locale, on purpose.** These are structure rather than
+ * prose — a contract with the model, not words for a human reader — and the
+ * arc promises the same answers produce the same prompt byte for byte on any
+ * machine *and in any locale*. A heading that moved with `TRAZUM_LOCALE` would
+ * make the assembled prompt a function of the machine that ran the interview,
+ * which is the one thing [the locale rule](../../../ROADMAP.md) forbids.
+ */
+const HEADING = {
+    role: 'Role',
+    task: 'Task',
+    inputs: 'Inputs',
+    output: 'Output',
+    constraints: 'Constraints',
+    examples: 'Examples',
+    'failure-modes': 'Failure modes',
+};
+const line = (id, answer) => {
+    const label = LABEL[id] ?? null;
+    return label === null ? answer.trim() : `${label} ${answer.trim()}`;
+};
+/**
+ * Assemble the prompt, or refuse and say what is missing.
+ *
+ * Deterministic in both senses that matter: the same answers produce the same
+ * bytes, and nothing here consults the network, the clock or the locale.
+ */
+export function assemble(answers, options = {}) {
+    const state = interview(answers);
+    const sections = [];
+    for (const section of SECTIONS) {
+        const filled = SLOTS.filter((entry) => entry.section === section &&
+            isOpen(entry, answers) &&
+            typeof answers[entry.id] === 'string' &&
+            answers[entry.id].trim().length > 0);
+        if (filled.length === 0)
+            continue;
+        const body = filled.map((entry) => line(entry.id, answers[entry.id])).join('\n');
+        sections.push({
+            section,
+            text: `${HEADING[section]}\n${body}`,
+            from: filled.map((entry) => entry.id),
+        });
+    }
+    const prompt = state.missing.length > 0 ? null : sections.map((entry) => entry.text).join('\n\n');
+    return {
+        schemaVersion: 1,
+        prompt,
+        sections,
+        answered: state.answered,
+        declined: state.declined,
+        missing: state.missing,
+        measured: prompt === null ? null : measure(prompt, answers, state, options),
+    };
+}
+const measure = (prompt, answers, state, options) => {
+    const model = typeof answers['model'] === 'string' ? answers['model'].trim() : null;
+    const budgetAnswer = typeof answers['budget'] === 'string' ? Number(answers['budget']) : NaN;
+    const budgetUsd = Number.isFinite(budgetAnswer) ? budgetAnswer : null;
+    /*
+      Priced only when the catalogue knows the model.
+  
+      `optimize` throws on a model it cannot price, which is right for a command
+      somebody typed a model into and wrong here: an unpriced model is one of the
+      three answers this measurement gives, not a crash. So the tokens and the
+      rules — neither of which needs a price — are measured first, and the money
+      is asked for separately and only when there is something to ask.
+    */
+    const known = model !== null && (options.pricing ?? BUNDLED_CATALOGUE).byId.has(model);
+    const usage = {};
+    if (known)
+        usage.model = model;
+    if (options.callsPerMonth !== undefined)
+        usage.callsPerMonth = options.callsPerMonth;
+    if (options.avgOutputTokens !== undefined)
+        usage.avgOutputTokens = options.avgOutputTokens;
+    const report = optimize(prompt, {
+        level: options.level ?? 'safe',
+        pricing: options.pricing,
+        usage,
+    });
+    const monthlyUsd = known && report.savings !== null ? report.savings.perMonth.before.totalUsd : null;
+    let verdict = 'cannot-tell';
+    let reason = null;
+    if (budgetUsd === null)
+        reason = 'no-budget';
+    else if (model === null)
+        reason = 'no-model';
+    else if (monthlyUsd === null)
+        reason = 'model-unpriced';
+    else
+        verdict = monthlyUsd > budgetUsd ? 'over' : 'within';
+    return {
+        complete: {
+            required: SLOTS.filter((entry) => entry.required && isOpen(entry, answers)).length,
+            answered: state.answered.length,
+            declined: state.declined,
+            missing: state.missing,
+        },
+        cheap: {
+            tokens: report.tokensBefore,
+            tokenSource: report.tokenSource,
+            model,
+            monthlyUsd,
+            provenance: 'estimated',
+            budgetUsd,
+            verdict,
+            reason,
+        },
+        clean: {
+            rules: report.rules
+                .filter((entry) => entry.hits > 0)
+                .map((entry) => ({ id: entry.id, hits: entry.hits })),
+            tokensRecoverable: report.tokensSaved,
+        },
+    };
+};
+//# sourceMappingURL=write.js.map

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.60.3",
+  "version": "1.61.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/conform.ts

@@ -45,6 +45,7 @@ export const CONTRACT_NAMES = [
   'outcome-report',
   'annual-record',
   'roll-up',
+  'prompt-draft',
 ] as const;
 
 export type ContractName = (typeof CONTRACT_NAMES)[number];
@@ -326,6 +327,35 @@ const DOCUMENT_RULES: Record<Exclude<ContractName, 'usage-log'>, FieldRule[]> =
     rule('call', 'an object, or null when nothing was described', (v) => v === null || isObject(v)),
     rule('budget', 'an object, or null when there is no budget', (v) => v === null || isObject(v)),
   ],
+  /**
+   * A prompt somebody was interviewed into, and what the interview could not
+   * get out of them.
+   *
+   * `prompt` is **null and never an empty string** when required answers are
+   * missing: an empty string reads as a prompt that came out blank, and the
+   * difference between "not built" and "built and empty" is the one this
+   * format refuses to lose everywhere else.
+   *
+   * `declined` and `missing` are separate arrays for the same reason. Somebody
+   * who was asked and said no is not somebody who was never asked, and folding
+   * the two would turn a decision into a gap.
+   */
+  'prompt-draft': [
+    rule(
+      'prompt',
+      'the assembled prompt, or **null** when required answers are missing — never an empty string',
+      (v) => v === null || typeof v === 'string',
+    ),
+    rule('sections', 'an array of the sections that got words, in the order they are written', isArray),
+    rule('answered', 'an array of the slots that were answered', isArray),
+    rule('declined', 'an array of the slots somebody was asked and declined — never folded into missing', isArray),
+    rule('missing', 'an array of required slots still unanswered; empty exactly when prompt is a string', isArray),
+    rule(
+      'measured',
+      'an object of the three claims, or **null** when there is no prompt to measure — never an object of zeros',
+      (v) => v === null || isObject(v),
+    ),
+  ],
 };
 
 /**

package/src/index.ts

@@ -547,3 +547,27 @@ export {
 } from './config-schema.js';
 export type { ResolvedBudget, SpendConfig, TrazumConfig, WaiveEntry } from './config-schema.js';
 export { WAIVABLE_GATES } from './config-schema.js';
+
+export { RULE_LEVELS } from './types.js';
+export {
+  assemble,
+  interview,
+  isOpen,
+  OUTPUT_FORMATS,
+  SECTIONS,
+  slot,
+  SLOT_IDS,
+  SLOTS,
+} from './write.js';
+export type {
+  Answer,
+  Answers,
+  AssembleOptions,
+  DraftMeasurement,
+  DraftSection,
+  Interview,
+  OutputFormat,
+  PromptDraft,
+  Section,
+  Slot,
+} from './write.js';

package/src/optimize.ts

@@ -9,6 +9,7 @@ import { computeSavings } from './savings.js';
 import { join, segment } from './segment.js';
 import { estimateTokens } from './tokenizer.js';
 import type { AsyncTokenCounter } from './tokenizer.js';
+import { RULE_LEVELS } from './types.js';
 import type {
   OptimizationResult,
   OptimizeOptions,
@@ -92,6 +93,22 @@ function distinctProtected(segments: Segment[]): string[] {
  */
 export function optimize(prompt: string, options: OptimizeOptions = {}): OptimizationResult {
   const level = options.level ?? 'safe';
+  /*
+    An unknown level used to run `safe` and say nothing.
+
+    The rule loop skips aggressive rules unless the level *is* `aggressive`, so
+    every other string — a typo, a plausible-sounding `balanced` — silently
+    produced safe-level results. The CLI has always refused `--level balanced`
+    by name; a library caller got the quiet downgrade instead, and a report
+    that says `safe` work was done at the level somebody asked for is the
+    swallowed-flag defect one layer down. Nothing correct depends on the old
+    behaviour: no program means `safe` by writing something else.
+  */
+  if (!RULE_LEVELS.includes(level)) {
+    throw new Error(
+      `level must be one of ${RULE_LEVELS.join(', ')} (received: ${JSON.stringify(level)})`,
+    );
+  }
   const locale: Locale = options.locale ?? DEFAULT_LOCALE;
   const t = getMessages(locale);
   const disabled = new Set<RuleId>(options.disableRules ?? []);

package/src/types.ts

@@ -5,7 +5,17 @@ import type { Locale, RuleId } from './i18n/types.js';
 import type { PricingCatalogue } from './pricing.js';
 
 /** How aggressive the deterministic rules are allowed to be. */
-export type RuleLevel = 'safe' | 'aggressive';
+/**
+ * The levels an optimisation runs at, from the one place that defines them.
+ *
+ * Exported as a value, not only as a type. `@trazum/core` had the union and no
+ * list, so the valid set was not discoverable from the package and a caller
+ * reaching for a plausible third name — `balanced` — got no answer from the
+ * types at runtime and no error either.
+ */
+export const RULE_LEVELS = ['safe', 'aggressive'] as const;
+
+export type RuleLevel = (typeof RULE_LEVELS)[number];
 
 /**
  * A deterministic rule applied to the mutable text of a prompt.