feat: define graph update proposal contract

2026-08-02 08:00:37 +01:00
parent 02a6ecd0da
commit b38a6a9f2e
4 changed files with 477 additions and 0 deletions
@@ -0,0 +1,114 @@
+import {
+  ConfidenceLevel,
+  SituationKind,
+  SituationRelationship,
+  SituationStatus,
+} from "./schema.js";
+
+const DEFAULT_PROMPT_VERSION = "v0.4";
+
+function formatEnumValues(values) {
+  return Object.values(values).join(" | ");
+}
+
+function formatGraph(graph) {
+  return JSON.stringify(graph, null, 2);
+}
+
+function formatExampleAnswerBlock() {
+  return [
+    "Example answer the model must be able to handle without hard-coding output:",
+    '"The complaint rate fell from 2.0 complaints per 100 units to 1.9 complaints per 100 units."',
+    "This may justify resolving a rate-related unknown or updating a metric node, but only if the current graph and answer support that proposal.",
+  ].join("\n");
+}
+
+export function buildGraphUpdatePrompt({
+  situationGraph,
+  previousQuestion,
+  answer,
+  promptVersion = DEFAULT_PROMPT_VERSION,
+}) {
+  const nodeKinds = formatEnumValues(SituationKind);
+  const nodeStatuses = formatEnumValues(SituationStatus);
+  const edgeRelationships = formatEnumValues(SituationRelationship);
+  const confidenceLevels = formatEnumValues(ConfidenceLevel);
+
+  return `You are proposing a graph update for Confidence Engine ${promptVersion}.
+
+Return exactly one JSON object matching the GraphUpdate contract.
+Return JSON only. Do not include markdown, explanation, or any text before or after the JSON object.
+
+## Current Situation Graph
+${formatGraph(situationGraph)}
+
+## Previous Selected Question
+${previousQuestion}
+
+## User Answer
+${answer}
+
+## Allowed Node Kinds
+${nodeKinds}
+
+## Allowed Node Statuses
+${nodeStatuses}
+
+## Allowed Edge Relationships
+${edgeRelationships}
+
+## Allowed Confidence Values
+${confidenceLevels}
+
+## Required JSON Field Names
+The JSON object must contain exactly these top-level fields:
+- addedNodes
+- updatedNodes
+- addedEdges
+- removedEdgeIds
+- resolvedUnknownNodeIds
+- affectedNodeIds
+
+## Required Shapes
+- addedNodes: array of nodes using these exact keys:
+  id, label, description, kind, status, confidence, value, unit, evidenceIds, dependsOn, affects, parentId, childIds
+- updatedNodes: array of node updates using these exact keys:
+  nodeId, previousStatus, newStatus, previousValue, newValue, reason
+- addedEdges: array of edges using these exact keys:
+  id, fromNodeId, toNodeId, relationship, confidence, description
+- removedEdgeIds: array of strings
+- resolvedUnknownNodeIds: array of strings
+- affectedNodeIds: array of strings
+
+## Proposal Rules
+1. Propose changes only. Never return a replacement graph.
+2. Preserve unrelated nodes and edges by omitting them from the proposal.
+3. Reference existing node IDs when updating an existing concept.
+4. Use addedNodes only for genuinely new concepts.
+5. Resolve the active unknown when the answer supports it.
+6. Propagate only through explicit dependencies or relationships already present in the graph.
+7. Do not invent evidence.
+8. Do not create unsupported causal edges.
+9. Do not ask more than one next question. In this contract you are not returning any next-question field at all.
+10. Use empty arrays when there are no changes in a category.
+11. Never return null array entries.
+12. Never use unknown enum values.
+13. Do not change existing IDs.
+14. Do not replace the whole graph, and do not restate unchanged graph content inside the proposal.
+
+## Additional Guidance
+- If the answer only clarifies an existing unknown, prefer updatedNodes and resolvedUnknownNodeIds over creating duplicate nodes.
+- If a new metric or observation is necessary, add the smallest set of nodes and edges needed.
+- If the answer does not justify a change, return empty arrays for every category.
+
+## Example Constraint Reminder
+${formatExampleAnswerBlock()}
+
+## Output Contract Reminder
+Return one JSON object only, with exact field names and exact enum values.
+Never include a full graph.
+Never include a nextQuestion field.
+`;
+}
+
+export const buildUpdatePrompt = buildGraphUpdatePrompt;