@oscharko-dev/keiko-model-gateway 0.2.0

package/dist/promptEnhancer/candidates.js

@@ -0,0 +1,109 @@
+// Prompt Enhancer candidate generation (Epic #1307, Issue #1312; ADR-0044 §1/§5/§6).
+//
+// Produces a bounded, ordered set of distinct, safety-preserving Enhanced Prompt candidates for one
+// analysis by varying the generation profile across a deterministic slate. Each profile yields a
+// structurally different prompt (reasoning strategy/depth, token budget, structural caps — see
+// `profiles.ts`), giving the critic genuinely different candidates to rank.
+//
+// Safety floor (AC5 — candidate generation never relaxes safety, grounding, or output schema): the
+// baseline plan's safety posture is the floor. A candidate is admitted only if its derived posture is
+// at least as strict (a candidate that would drop the safety-critical disclaimer or the human-approval
+// gate is rejected before it is ever scored). Output schema and grounding need are bound to the
+// analysis by `generateEnhancedPrompt`, so they cannot drift across candidates.
+//
+// Because the planner escalates a critical-criticality task to the `safety-critical` profile regardless
+// of preference, such tasks deterministically collapse to a single candidate — relaxing the profile to
+// manufacture variety would relax safety, which AC5 forbids. The "at least three candidates" capability
+// (AC1) therefore applies to tasks whose safety floor admits variation, which is the common case.
+//
+// Determinism: pure. No IO, clock, or randomness.
+import { asEnhancedPromptId, PROMPT_ENHANCEMENT_PROFILE_IDS, } from "@oscharko-dev/keiko-contracts";
+import { canonicalise, sha256Hex } from "@oscharko-dev/keiko-security";
+import { generateEnhancedPrompt } from "./generator.js";
+import { planPromptEnhancement } from "./planner.js";
+function candidateId(analysis, profile) {
+    const digest = sha256Hex(canonicalise({ profile, requestId: analysis.requestId }));
+    return `pe-candidate-${profile}-${digest}`;
+}
+// The candidate-preference slate: the baseline profile first, then every other catalog profile in its
+// canonical order. Planning each preference yields the actual selected profile (which may be escalated).
+function preferenceSlate(baseline) {
+    const rest = PROMPT_ENHANCEMENT_PROFILE_IDS.filter((id) => id !== baseline);
+    return [baseline, ...rest];
+}
+// A candidate preserves the safety floor when its posture is at least as strict as the baseline on both
+// safety-critical handling and the human-approval gate. (Output schema and grounding need are bound to
+// the analysis by the generator, so they never drift.)
+function preservesSafetyFloor(candidate, floor) {
+    const safetyCriticalOk = candidate.safetyPosture.safetyCritical || !floor.safetyPosture.safetyCritical;
+    const humanApprovalOk = candidate.safetyPosture.requiresHumanApproval || !floor.safetyPosture.requiresHumanApproval;
+    return safetyCriticalOk && humanApprovalOk && candidate.safetyPosture.restrictsAuthority;
+}
+// A wording-independent structural signature of the prompt, used to drop a candidate that is identical
+// to a higher-priority one even though its nominal profile differs.
+function structuralSignature(prompt) {
+    return JSON.stringify([
+        prompt.role,
+        prompt.goal,
+        prompt.context,
+        prompt.taskDecomposition,
+        prompt.constraints,
+        prompt.groundingRules,
+        prompt.qualityCriteria,
+        prompt.uncertaintyHandling,
+        prompt.safetyRules,
+        prompt.outputSchema,
+        prompt.groundingPlan,
+    ]);
+}
+/**
+ * Generate a bounded, ordered set of distinct, safety-preserving Enhanced Prompt candidates. Pure.
+ *
+ * Candidates are produced by planning the analysis under each profile in the slate, deduplicating by
+ * the actual selected profile (so a forced escalation does not produce repeats), rejecting any candidate
+ * that would relax the baseline safety floor, and capping the result at `candidateCount`.
+ */
+export function generatePromptCandidates(args) {
+    const { analysis, input } = args;
+    const count = Number.isInteger(args.candidateCount) && args.candidateCount > 0 ? args.candidateCount : 1;
+    const floor = planPromptEnhancement(analysis, { profilePreference: args.profilePreference });
+    const baselineProfile = floor.selectedProfile;
+    const candidates = [];
+    const rejected = [];
+    const seenProfiles = new Set();
+    const seenSignatures = new Set();
+    for (const preference of preferenceSlate(baselineProfile)) {
+        if (candidates.length >= count)
+            break;
+        const plan = planPromptEnhancement(analysis, { profilePreference: preference });
+        const actualProfile = plan.selectedProfile;
+        // Deduplicate by the actual selected profile: a forced escalation (e.g. every preference escalating
+        // to `safety-critical` for a critical task) is the same candidate, generated once.
+        if (seenProfiles.has(actualProfile))
+            continue;
+        seenProfiles.add(actualProfile);
+        const id = candidateId(analysis, actualProfile);
+        if (!preservesSafetyFloor(plan, floor)) {
+            rejected.push({
+                candidateId: id,
+                profile: actualProfile,
+                reason: "safety-floor-not-preserved",
+            });
+            continue;
+        }
+        const prompt = generateEnhancedPrompt({
+            promptId: asEnhancedPromptId(id),
+            analysis,
+            plan,
+            input,
+        });
+        const signature = structuralSignature(prompt);
+        if (seenSignatures.has(signature)) {
+            rejected.push({ candidateId: id, profile: actualProfile, reason: "duplicate-candidate" });
+            continue;
+        }
+        seenSignatures.add(signature);
+        candidates.push({ candidateId: id, profile: actualProfile, plan, prompt });
+    }
+    return { candidates, rejected };
+}

package/dist/promptEnhancer/critic.d.ts

@@ -0,0 +1,22 @@
+import { type EnhancedPrompt, type PromptCandidateScorecard, type PromptCriticDimension, type PromptEnhancementProfileId, type PromptTaskAnalysis } from "@oscharko-dev/keiko-contracts";
+import type { PromptEnhancementPlan } from "./planner.js";
+export declare const PROMPT_CRITIC_DIMENSION_WEIGHTS: Readonly<Record<PromptCriticDimension, number>>;
+export interface PromptCandidateScoringContext {
+    readonly candidateId: string;
+    readonly profile: PromptEnhancementProfileId;
+    readonly prompt: EnhancedPrompt;
+    readonly plan: PromptEnhancementPlan;
+    readonly analysis: PromptTaskAnalysis;
+}
+/**
+ * Deterministic token estimate for the full rendered prompt (instructions + input). Heuristic, not a
+ * provider tokenizer. This is the candidate's real dispatch-cost estimate and feeds the budget.
+ */
+export declare function estimatePromptTokens(prompt: EnhancedPrompt): number;
+/**
+ * Deterministically score one Enhanced Prompt candidate across all six critic dimensions and fold them
+ * into a weighted aggregate. Pure. The result is a fully populated, auditable `PromptCandidateScorecard`
+ * with one score-plus-rationale per dimension in canonical order.
+ */
+export declare function scorePromptCandidate(context: PromptCandidateScoringContext): PromptCandidateScorecard;
+//# sourceMappingURL=critic.d.ts.map

package/dist/promptEnhancer/critic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"critic.d.ts","sourceRoot":"","sources":["../../src/promptEnhancer/critic.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAE1B,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAuB1D,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAQxF,CAAC;AAIL,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC;AA4BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEnE;AAqKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,6BAA6B,GACrC,wBAAwB,CAmB1B"}

package/dist/promptEnhancer/critic.js

@@ -0,0 +1,237 @@
+// Prompt Enhancer deterministic PromptCritic (Epic #1307, Issue #1312; ADR-0044 §1/§6).
+//
+// Scores an `EnhancedPrompt` candidate on the six Issue #1312 quality dimensions — clarity,
+// completeness, grounding readiness, safety, output controllability, and token efficiency — each on a
+// continuous [0, 1] scale with an inspectable rationale, then folds them into a single weighted
+// aggregate used for ranking. The MVP critic is fully deterministic so it provides reproducible CI
+// coverage (Engineering Notes: "MVP scoring must have deterministic coverage for CI"); a model-assisted
+// LLM-as-judge stage is an explicit later option and is intentionally not built here.
+//
+// The score is computed from observable structural evidence of the artefact (section population,
+// decomposition depth, grounding apparatus, safety-rule coverage, output-schema shape, token estimate),
+// never from the raw user input, so a rationale can never echo untrusted content (ADR-0044 §5).
+//
+// Determinism: pure. No IO, clock, or randomness. Identical inputs always yield an identical scorecard.
+import { PROMPT_CRITIC_DIMENSIONS, PROMPT_ENHANCER_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { renderEnhancedPromptText } from "./rendering.js";
+// Heuristic characters-per-token ratio for the deterministic token estimate. This is a coarse, model
+// independent approximation (not a provider tokenizer); it is used consistently for every candidate so
+// the comparison between candidates is fair, and it feeds the optimization-loop token budget.
+const CHARS_PER_TOKEN = 4;
+// Global normalization references for the absolute-thoroughness dimensions. Chosen as the largest cap
+// any execution profile applies (see `profiles.ts`), so a maximally thorough prompt approaches 1.0.
+const REFERENCE_DECOMPOSITION_STEPS = 6;
+const REFERENCE_QUALITY_CRITERIA = 5;
+const REFERENCE_CONSTRAINTS = 6;
+const REFERENCE_UNCERTAINTY_RULES = 3;
+// A generous instruction-token reference: a lean prompt sits well under this and scores high token
+// efficiency; a rich one approaches it and scores lower, expressing the genuine breadth/cost trade-off.
+const REFERENCE_INSTRUCTION_TOKENS = 600;
+// Token-efficiency never collapses fully to zero for a well-formed prompt; this floor keeps the
+// dimension a graded signal rather than a cliff for the most verbose profile.
+const TOKEN_EFFICIENCY_FLOOR = 0.2;
+// Weighted aggregate. Safety carries the most weight (it is the floor candidate generation must never
+// relax, AC5); completeness is next; the remaining quality dimensions are balanced. Sums to 1.0.
+export const PROMPT_CRITIC_DIMENSION_WEIGHTS = Object.freeze({
+    clarity: 0.15,
+    completeness: 0.2,
+    "grounding-readiness": 0.15,
+    safety: 0.25,
+    "output-controllability": 0.15,
+    "token-efficiency": 0.1,
+});
+// ─── Deterministic numeric helpers ─────────────────────────────────────────────────
+function clampUnit(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    if (value >= 1)
+        return 1;
+    return value;
+}
+// Round to 4 decimals so scores are stable, readable values rather than IEEE-754 tails. Deterministic.
+function round4(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+ * Deterministic token estimate for the full rendered prompt (instructions + input). Heuristic, not a
+ * provider tokenizer. This is the candidate's real dispatch-cost estimate and feeds the budget.
+ */
+export function estimatePromptTokens(prompt) {
+    return estimateTokens(renderEnhancedPromptText(prompt));
+}
+// The instruction overhead the candidate controls: every trusted section except the constant user
+// input. Token efficiency is scored on this so a candidate is not penalised for the input's size, which
+// is identical across all candidates for the same request.
+function instructionTokens(prompt) {
+    const sections = [
+        prompt.role,
+        prompt.goal,
+        ...prompt.context,
+        ...prompt.taskDecomposition,
+        ...prompt.constraints,
+        ...prompt.groundingRules,
+        ...prompt.qualityCriteria,
+        ...prompt.uncertaintyHandling,
+        ...prompt.safetyRules,
+    ];
+    return estimateTokens(sections.join("\n"));
+}
+// ─── Dimension scorers ─────────────────────────────────────────────────────────────
+// Clarity: the prompt is unambiguous and well organised — every structural slot is populated and the
+// task is expressed as an ordered, multi-step plan. Well-formed prompts score uniformly high here;
+// clarity is a stable base rather than the primary differentiator.
+function scoreClarity(prompt) {
+    const checks = [
+        prompt.role.trim().length > 0,
+        prompt.goal.trim().length > 0,
+        prompt.context.length > 0,
+        prompt.taskDecomposition.length >= 2,
+        prompt.constraints.length > 0,
+        prompt.qualityCriteria.length > 0,
+        prompt.uncertaintyHandling.length > 0,
+    ];
+    const satisfied = checks.filter(Boolean).length;
+    return {
+        score: clampUnit(satisfied / checks.length),
+        rationale: `${String(satisfied)}/${String(checks.length)} structural clarity checks met (role, goal, context, ${String(prompt.taskDecomposition.length)} ordered steps, constraints, criteria, uncertainty rule).`,
+    };
+}
+// Completeness: absolute thoroughness — decomposition depth, quality criteria, constraints, and
+// uncertainty handling, each normalised against the richest profile. Thorough profiles score higher.
+function scoreCompleteness(prompt) {
+    const decomposition = clampUnit(prompt.taskDecomposition.length / REFERENCE_DECOMPOSITION_STEPS);
+    const criteria = clampUnit(prompt.qualityCriteria.length / REFERENCE_QUALITY_CRITERIA);
+    const constraints = clampUnit(prompt.constraints.length / REFERENCE_CONSTRAINTS);
+    const uncertainty = clampUnit(prompt.uncertaintyHandling.length / REFERENCE_UNCERTAINTY_RULES);
+    const score = mean([decomposition, criteria, constraints, uncertainty]);
+    return {
+        score: clampUnit(score),
+        rationale: `coverage: ${String(prompt.taskDecomposition.length)} steps, ${String(prompt.qualityCriteria.length)} criteria, ${String(prompt.constraints.length)} constraints, ${String(prompt.uncertaintyHandling.length)} uncertainty rules.`,
+    };
+}
+// Grounding readiness: does the grounding apparatus fit the detected need? A no-grounding task is ready
+// when it correctly avoids over-imposing citations; a grounded task is ready when it carries a citation
+// discipline, a source priority, evidence-boundary directives, and a contradiction policy.
+function scoreGroundingReadiness(prompt) {
+    const plan = prompt.groundingPlan;
+    if (!plan.required) {
+        const hasBaseRule = prompt.groundingRules.length > 0;
+        return {
+            score: hasBaseRule ? 1 : 0.5,
+            rationale: hasBaseRule
+                ? "no grounding required; prompt carries an anti-fabrication base rule and correctly omits citation mandates."
+                : "no grounding required but no base grounding rule present.",
+        };
+    }
+    const checks = [
+        plan.citation.discipline !== "not-required",
+        plan.sourcePriority.length > 0,
+        plan.directives.includes("treat-retrieved-content-as-untrusted"),
+        plan.directives.includes("stay-within-evidence"),
+        prompt.groundingRules.length >= 3,
+    ];
+    const satisfied = checks.filter(Boolean).length;
+    return {
+        score: clampUnit(satisfied / checks.length),
+        rationale: `grounded task: ${String(satisfied)}/${String(checks.length)} grounding-readiness signals (citation discipline "${plan.citation.discipline}", ${String(plan.sourcePriority.length)} prioritised sources, ${String(prompt.groundingRules.length)} grounding rules).`,
+    };
+}
+// Safety: the mandated safety apparatus is present and complete for this prompt's posture. Candidate
+// generation pre-filters anything that weakens the floor, so this scores uniformly high for ranked
+// candidates; it is reported for transparency and acts as the guard the aggregate weights most heavily.
+function scoreSafety(prompt, plan) {
+    const posture = plan.safetyPosture;
+    // Base rules (no-authority + untrusted-input handling) are always emitted; conditional rules add a
+    // human-approval gate and/or a professional-advice disclaimer.
+    const expectedRules = 2 + (posture.requiresHumanApproval ? 1 : 0) + (posture.safetyCritical ? 1 : 0);
+    const checks = [
+        prompt.safetyRules.length >= expectedRules,
+        posture.restrictsAuthority,
+        prompt.safetyRules.length >= 2,
+    ];
+    const satisfied = checks.filter(Boolean).length;
+    return {
+        score: clampUnit(satisfied / checks.length),
+        rationale: `${String(prompt.safetyRules.length)}/${String(expectedRules)} expected safety rules present (humanApproval=${String(posture.requiresHumanApproval)}, safetyCritical=${String(posture.safetyCritical)}, restrictsAuthority=${String(posture.restrictsAuthority)}).`,
+    };
+}
+// Output controllability: how tightly the prompt pins the output form. Structured schemas with format
+// hints and an explicit controllability criterion are highly controllable; inherently freeform tasks
+// score low by nature (an honest reflection, constant across that task's candidates).
+function scoreOutputControllability(prompt) {
+    const schema = prompt.outputSchema;
+    const hasControllabilityCriterion = prompt.qualityCriteria.some((criterion) => criterion.startsWith("Output controllability"));
+    const checks = [
+        schema.structured,
+        schema.hints.length > 0,
+        hasControllabilityCriterion,
+    ];
+    const satisfied = checks.filter(Boolean).length;
+    return {
+        score: clampUnit(satisfied / checks.length),
+        rationale: `output ${schema.structured ? "structured" : "unstructured"} (${schema.format}), ${String(schema.hints.length)} hints, controllability criterion ${hasControllabilityCriterion ? "present" : "absent"}.`,
+    };
+}
+// Token efficiency: instruction leanness. Scored on instruction overhead only (the input is constant
+// across candidates), normalised against a generous reference and floored so the richest profile still
+// grades rather than collapsing. Lean profiles score high; this trades off against completeness.
+function scoreTokenEfficiency(prompt) {
+    const tokens = instructionTokens(prompt);
+    const raw = 1 - tokens / REFERENCE_INSTRUCTION_TOKENS;
+    const score = TOKEN_EFFICIENCY_FLOOR + (1 - TOKEN_EFFICIENCY_FLOOR) * clampUnit(raw);
+    return {
+        score: clampUnit(score),
+        rationale: `~${String(tokens)} instruction tokens (reference ${String(REFERENCE_INSTRUCTION_TOKENS)}); leaner instructions score higher.`,
+    };
+}
+function assess(dimension, context) {
+    switch (dimension) {
+        case "clarity":
+            return scoreClarity(context.prompt);
+        case "completeness":
+            return scoreCompleteness(context.prompt);
+        case "grounding-readiness":
+            return scoreGroundingReadiness(context.prompt);
+        case "safety":
+            return scoreSafety(context.prompt, context.plan);
+        case "output-controllability":
+            return scoreOutputControllability(context.prompt);
+        case "token-efficiency":
+            return scoreTokenEfficiency(context.prompt);
+    }
+}
+function aggregate(scores) {
+    const total = scores.reduce((sum, entry) => sum + PROMPT_CRITIC_DIMENSION_WEIGHTS[entry.dimension] * entry.score, 0);
+    return round4(clampUnit(total));
+}
+/**
+ * Deterministically score one Enhanced Prompt candidate across all six critic dimensions and fold them
+ * into a weighted aggregate. Pure. The result is a fully populated, auditable `PromptCandidateScorecard`
+ * with one score-plus-rationale per dimension in canonical order.
+ */
+export function scorePromptCandidate(context) {
+    const dimensionScores = PROMPT_CRITIC_DIMENSIONS.map((dimension) => {
+        const assessment = assess(dimension, context);
+        return {
+            dimension,
+            score: round4(clampUnit(assessment.score)),
+            rationale: assessment.rationale,
+        };
+    });
+    return {
+        schemaVersion: PROMPT_ENHANCER_SCHEMA_VERSION,
+        candidateId: context.candidateId,
+        profile: context.profile,
+        dimensionScores,
+        aggregateScore: aggregate(dimensionScores),
+        estimatedTokens: estimatePromptTokens(context.prompt),
+    };
+}

package/dist/promptEnhancer/generator.d.ts

@@ -0,0 +1,15 @@
+import { type EnhancedPrompt, type EnhancedPromptId, type PromptTaskAnalysis, type RawPromptInput } from "@oscharko-dev/keiko-contracts";
+import type { PromptEnhancementPlan } from "./planner.js";
+export declare const GENERATED_INPUT_MAX_CHARS = 16000;
+export interface GenerateEnhancedPromptArgs {
+    readonly promptId: EnhancedPromptId;
+    readonly analysis: PromptTaskAnalysis;
+    readonly plan: PromptEnhancementPlan;
+    readonly input: RawPromptInput;
+}
+/**
+ * Generate a deterministic, structured `EnhancedPrompt` from an analysis, its plan, and the raw input.
+ * Pure. The result always satisfies `validateEnhancedPrompt` (#1309).
+ */
+export declare function generateEnhancedPrompt(args: GenerateEnhancedPromptArgs): EnhancedPrompt;
+//# sourceMappingURL=generator.d.ts.map

package/dist/promptEnhancer/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/promptEnhancer/generator.ts"],"names":[],"mappings":"AAmBA,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAUrB,KAAK,kBAAkB,EAEvB,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAO1D,eAAO,MAAM,yBAAyB,QAAS,CAAC;AA8chD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,0BAA0B,GAAG,cAAc,CAwBvF"}