Pivot to text-first column-stack workspace + merge-with-review across AI artifacts
Workspace - Pivot from "set of open panes" to a Finder-style miller column stack: TopBar / LeftSidebar / [section → entity → entity ...] / pinned text editor. openPanesStore is now an ordered Column[] with pushFrom / closeFrom / setStack; only one top-level section is rooted at a time. - New entity column panes: Term, Block, Association, Constraint, Requirement, Finding. Click-through navigation truncates deeper columns automatically. - LeftSidebar surfaces a pending-count chip per section (single-glance navigation cue) and spins its analyze ↻ via SVG Spinner whenever the LLM is working — including server-initiated runs caught by the runs poll, not just user-triggered ones. Analyze pipeline + persistence - Unified `concepts` pass (taxonomy + glossary in one LLM call) replaces the two-pass setup. Server still accepts ?section=taxonomy|glossary and normalizes them for back-compat. - model / requirements / detection (assumptions, risks, inconsistencies) + cross-layer validation rules (X1–X4: stale term link, unlinked formalism, undefined linked term, prose-only term). - Persistence: NarrativeDocument, ModelSnapshot, ChangelogEntry, TaxonomyTerm, RequirementEntry, Finding, AnalysisRun. Re-runs MERGE instead of replace: gentle update on existing items, suggested on new, deprecated on missing — same idiom for every artifact kind. User pins preserve "kept" decisions across re-analyses. - Migrations: pivot_text_first, add_requirement_linked_term, term_review_state, review_state_for_reqs_and_findings, add_term_definition_pinned. Concept ↔ ontology integration - linkedTermId on Block / Association / Constraint / Requirement. PromoteToolbar lets the user formalize a concept inline: + Block / + Association / + Constraint / + Requirement, all routed through applyOps so undo/redo and SSE work for free. - decideElement op for in-canvas keep/discard on review-pending model elements. User-authored definitions - TermColumn definition is click-to-edit. Save (Cmd-Enter / blur), Cancel (Esc), Reset to AI suggestion when pinned. - definitionPinned flag on TaxonomyTerm: future Analyze runs leave the user's text alone. setTermDefinition repo function + POST /api/projects/[id]/terms/[termId]/definition endpoint. - mergeTaxonomySuggestion + applyGlossaryDefinitions both pin-aware. UX/UI - StatusChip: single component for all state idioms (suggested, deprecated, accepted, dismissed, resolved, severity, validation code, confidence, warn). Replaces 5+ ad-hoc badge classes. - PaneControls (PaneViewTabs + PaneFilterChip): separates view-mode toggles from filter chips so toggling Pending no longer flips you off the current view. - PaneEmpty: unified empty-state with title + hint + action. - PaneDrawer: collapsible groups for Pending / Discarded review; cards group as Kept (top) → Pending (bottom drawer) → Discarded (Findings only, hidden when empty). Restore action recovers dismissed/resolved findings. - ConceptCard unifies Tree and A–Z views in Concepts; only Tree parents carry the chevron (no empty placeholder offset). - Type + spacing tokens (--text-xs..xl, --space-1..6, --lh-tight/ui/ prose, --radius-*) replace every ad-hoc value. - Buttons standardized to body sans 500 (was a mishmash of mono / display). - Card shells unified across Concepts / Requirements / Findings. Cleanup - Removed: LeftRail, FindingsPanel, IssuesPanel, SocratesDock, ProposalCard, SlashMenu, SlashExtension, slashSuggestion, CanvasHeader, TaxonomyPane, GlossaryPane, TermDetail (popover; now TermColumn). - Section ids in openPanesStore: dropped taxonomy/glossary, added concepts. localStorage migration runs on hydrate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
95
apps/web/lib/llm/analyze/concepts.ts
Normal file
95
apps/web/lib/llm/analyze/concepts.ts
Normal file
@@ -0,0 +1,95 @@
|
||||
// Single-pass "concepts" analyzer — replaces the legacy taxonomy + glossary
|
||||
// pair (T3 of the integration plan). One LLM call emits both the term list
|
||||
// (with hierarchy + synonyms) and definitions, so the two layers can never
|
||||
// drift out of sync.
|
||||
//
|
||||
// The legacy `taxonomy` / `glossary` analyzers (analyze/taxonomy.ts and
|
||||
// analyze/glossary.ts) are still in the tree as deprecated fallbacks for one
|
||||
// release; nothing in the runtime path imports them anymore.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "../gateway";
|
||||
import { loadPrompt } from "../prompts";
|
||||
import type { DetectedTerm } from "../../db/repo";
|
||||
|
||||
interface RawTerm {
|
||||
label?: string;
|
||||
parentLabel?: string | null;
|
||||
synonyms?: string[];
|
||||
definition?: string;
|
||||
}
|
||||
|
||||
const conceptsJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["terms"],
|
||||
properties: {
|
||||
terms: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["label"],
|
||||
properties: {
|
||||
label: { type: "string", minLength: 1 },
|
||||
parentLabel: { type: ["string", "null"] },
|
||||
synonyms: { type: "array", items: { type: "string" } },
|
||||
definition: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
} as const;
|
||||
|
||||
export interface ConceptsResult {
|
||||
terms: DetectedTerm[];
|
||||
definitions: Array<{ label: string; definition: string }>;
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model: string;
|
||||
}
|
||||
|
||||
export async function analyzeConcepts(documentText: string): Promise<ConceptsResult> {
|
||||
const prompt = loadPrompt("socrates/analyze-concepts.md");
|
||||
const gateway = defaultGateway();
|
||||
const messages: Message[] = [
|
||||
{ role: "system", content: prompt },
|
||||
{ role: "user", content: `Document:\n\n${documentText}` },
|
||||
];
|
||||
|
||||
const { value, result } = await chatJSON<{ terms?: RawTerm[] }>(gateway, messages, {
|
||||
temperature: 0.2,
|
||||
maxTokens: 2400,
|
||||
jsonSchema: { name: "concepts", schema: conceptsJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
});
|
||||
|
||||
const seen = new Set<string>();
|
||||
const terms: DetectedTerm[] = [];
|
||||
const definitions: Array<{ label: string; definition: string }> = [];
|
||||
for (const t of value?.terms ?? []) {
|
||||
const label = (t.label ?? "").trim();
|
||||
if (!label) continue;
|
||||
const key = label.toLowerCase();
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
terms.push({
|
||||
label,
|
||||
parentLabel: t.parentLabel?.trim() || null,
|
||||
synonyms: Array.isArray(t.synonyms) ? t.synonyms.filter(s => typeof s === "string") : [],
|
||||
});
|
||||
const def = (t.definition ?? "").trim();
|
||||
if (def) definitions.push({ label, definition: def });
|
||||
}
|
||||
|
||||
return {
|
||||
terms,
|
||||
definitions,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model: gateway.model,
|
||||
};
|
||||
}
|
||||
81
apps/web/lib/llm/analyze/glossary.ts
Normal file
81
apps/web/lib/llm/analyze/glossary.ts
Normal file
@@ -0,0 +1,81 @@
|
||||
// Analyze pass: write definitions for taxonomy terms grounded in the prose.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "../gateway";
|
||||
import { loadPrompt } from "../prompts";
|
||||
|
||||
const glossaryJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["definitions"],
|
||||
properties: {
|
||||
definitions: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["label", "definition"],
|
||||
properties: {
|
||||
label: { type: "string", minLength: 1 },
|
||||
definition: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
} as const;
|
||||
|
||||
export interface GlossaryResult {
|
||||
defs: Array<{ label: string; definition: string }>;
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model: string;
|
||||
}
|
||||
|
||||
export async function analyzeGlossary(
|
||||
documentText: string,
|
||||
terms: Array<{ label: string; parentLabel?: string | null; synonyms?: string[] }>
|
||||
): Promise<GlossaryResult> {
|
||||
if (terms.length === 0) {
|
||||
return { defs: [], inputTokens: 0, outputTokens: 0, provider: "n/a", model: "n/a" };
|
||||
}
|
||||
|
||||
const prompt = loadPrompt("socrates/analyze-glossary.md");
|
||||
const gateway = defaultGateway();
|
||||
const userPayload =
|
||||
`Document:\n\n${documentText}\n\n---\n\n` +
|
||||
`Terms:\n\`\`\`json\n${JSON.stringify(terms, null, 2)}\n\`\`\``;
|
||||
|
||||
const messages: Message[] = [
|
||||
{ role: "system", content: prompt },
|
||||
{ role: "user", content: userPayload },
|
||||
];
|
||||
|
||||
const { value, result } = await chatJSON<{ definitions?: Array<{ label?: string; definition?: string }> }>(
|
||||
gateway,
|
||||
messages,
|
||||
{
|
||||
temperature: 0.2,
|
||||
maxTokens: 1800,
|
||||
jsonSchema: { name: "glossary", schema: glossaryJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
}
|
||||
);
|
||||
|
||||
const defs: Array<{ label: string; definition: string }> = [];
|
||||
for (const d of value?.definitions ?? []) {
|
||||
const label = (d.label ?? "").trim();
|
||||
const def = (d.definition ?? "").trim();
|
||||
if (!label || !def) continue;
|
||||
defs.push({ label, definition: def });
|
||||
}
|
||||
|
||||
return {
|
||||
defs,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model: gateway.model,
|
||||
};
|
||||
}
|
||||
496
apps/web/lib/llm/analyze/model.ts
Normal file
496
apps/web/lib/llm/analyze/model.ts
Normal file
@@ -0,0 +1,496 @@
|
||||
// Analyze pass: derive (or refresh) the SysML model from prose + taxonomy.
|
||||
//
|
||||
// Differs from generateModel.ts (the seed-time generator) in two ways:
|
||||
// 1. Inputs are prose + the current taxonomy term list, not a SeedDraft.
|
||||
// 2. Re-runs *merge* with the existing model: blocks already linked to a
|
||||
// taxonomy term are preserved (id, position, properties) so the user's
|
||||
// manual canvas work isn't blown away on every Analyze.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "../gateway";
|
||||
import { loadPrompt } from "../prompts";
|
||||
import type {
|
||||
SysMLModel,
|
||||
Block,
|
||||
Association,
|
||||
Constraint,
|
||||
Requirement,
|
||||
PropertyType,
|
||||
ReviewStatus,
|
||||
} from "../../sysml/model";
|
||||
|
||||
interface LeanProperty {
|
||||
name: string;
|
||||
type: { kind: "string" | "number" | "boolean" | "enum"; values?: string[] };
|
||||
}
|
||||
interface LeanBlock {
|
||||
id: string;
|
||||
label: string;
|
||||
kind: "system" | "actor" | "block";
|
||||
linkedTermLabel?: string;
|
||||
properties?: LeanProperty[];
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanAssoc {
|
||||
id: string;
|
||||
fromBlockId: string;
|
||||
toBlockId: string;
|
||||
label?: string;
|
||||
kind: "association" | "composition" | "aggregation" | "generalization" | "constraintApplies";
|
||||
/** Optional concept-name for the relationship itself (T2 integration). */
|
||||
linkedTermLabel?: string;
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanConstraint {
|
||||
id: string;
|
||||
label: string;
|
||||
expression?: string;
|
||||
appliesTo?: string[];
|
||||
/** Optional concept-name the constraint enforces. */
|
||||
linkedTermLabel?: string;
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanRequirement {
|
||||
id: string;
|
||||
tag: string;
|
||||
text: string;
|
||||
satisfiedBy?: string[];
|
||||
/** Optional concept this requirement is "about." */
|
||||
linkedTermLabel?: string;
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanModel {
|
||||
systemOfInterestId?: string;
|
||||
blocks: LeanBlock[];
|
||||
associations?: LeanAssoc[];
|
||||
constraints?: LeanConstraint[];
|
||||
requirements?: LeanRequirement[];
|
||||
overallConfidence?: number;
|
||||
}
|
||||
|
||||
const modelJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["blocks"],
|
||||
properties: {
|
||||
systemOfInterestId: { type: "string" },
|
||||
blocks: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "label", "kind", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
label: { type: "string", minLength: 1 },
|
||||
kind: { type: "string", enum: ["system", "actor", "block"] },
|
||||
linkedTermLabel: { type: "string" },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
properties: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["name", "type"],
|
||||
properties: {
|
||||
name: { type: "string", minLength: 1 },
|
||||
type: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["kind"],
|
||||
properties: {
|
||||
kind: { type: "string", enum: ["string", "number", "boolean", "enum"] },
|
||||
values: { type: "array", items: { type: "string" } },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
associations: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "fromBlockId", "toBlockId", "kind", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
fromBlockId: { type: "string", minLength: 1 },
|
||||
toBlockId: { type: "string", minLength: 1 },
|
||||
label: { type: "string" },
|
||||
kind: {
|
||||
type: "string",
|
||||
enum: ["association", "composition", "aggregation", "generalization", "constraintApplies"],
|
||||
},
|
||||
linkedTermLabel: { type: "string" },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
},
|
||||
},
|
||||
constraints: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "label", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
label: { type: "string", minLength: 1 },
|
||||
expression: { type: "string" },
|
||||
appliesTo: { type: "array", items: { type: "string" } },
|
||||
linkedTermLabel: { type: "string" },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
},
|
||||
},
|
||||
requirements: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "tag", "text", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
tag: { type: "string", minLength: 1 },
|
||||
text: { type: "string", minLength: 1 },
|
||||
satisfiedBy: { type: "array", items: { type: "string" } },
|
||||
linkedTermLabel: { type: "string" },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
},
|
||||
},
|
||||
overallConfidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
} as const;
|
||||
|
||||
export interface AnalyzeModelResult {
|
||||
model: SysMLModel;
|
||||
termIdToBlockId: Map<string, string>;
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model_name: string;
|
||||
}
|
||||
|
||||
export async function analyzeModelFromProse(
|
||||
documentText: string,
|
||||
terms: Array<{ id: string; label: string; linkedBlockId: string | null }>,
|
||||
current: SysMLModel
|
||||
): Promise<AnalyzeModelResult> {
|
||||
const character = loadPrompt("socrates/character.md");
|
||||
const generate = loadPrompt("socrates/analyze-model.md");
|
||||
|
||||
const userPayload =
|
||||
`Document:\n\n${documentText}\n\n---\n\n` +
|
||||
`Taxonomy:\n\`\`\`json\n${JSON.stringify(terms.map(t => t.label), null, 2)}\n\`\`\`\n` +
|
||||
`Return only the JSON object conforming to the schema.`;
|
||||
|
||||
const messages: Message[] = [
|
||||
{ role: "system", content: `${character}\n\n---\n\n${generate}` },
|
||||
{ role: "user", content: userPayload },
|
||||
];
|
||||
|
||||
const gateway = defaultGateway();
|
||||
const { value, result } = await chatJSON<LeanModel>(gateway, messages, {
|
||||
temperature: 0.3,
|
||||
maxTokens: 2400,
|
||||
jsonSchema: { name: "sysml_model", schema: modelJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
});
|
||||
|
||||
const merged = mergeIntoCurrent(value, current, terms);
|
||||
|
||||
return {
|
||||
...merged,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model_name: gateway.model,
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Lean → canonical, merged with current model (review-aware) ─────────
|
||||
//
|
||||
// Re-running the analyzer is non-destructive. For each element kind we
|
||||
// match against current by a stable key:
|
||||
// block — id (preserved via linkedTermId chain) OR linkedTermId
|
||||
// association — `${kind}|${fromBlockId}|${toBlockId}`
|
||||
// constraint — `${linkedTermId ?? "label:"+normalize(label)}`
|
||||
// requirement — `${linkedTermId ?? "text:"+normalize(text)}`
|
||||
//
|
||||
// New incoming → reviewStatus = "suggested".
|
||||
// Matched + currently deprecated → flips back to "suggested".
|
||||
// Existing not in incoming + not pinned + not currently suggested → "deprecated".
|
||||
// Existing not in incoming + status was "suggested" → quietly dropped.
|
||||
// Pinned elements left alone regardless.
|
||||
|
||||
function mergeIntoCurrent(
|
||||
lean: LeanModel | null | undefined,
|
||||
current: SysMLModel,
|
||||
terms: Array<{ id: string; label: string; linkedBlockId: string | null }>
|
||||
): { model: SysMLModel; termIdToBlockId: Map<string, string> } {
|
||||
if (!lean || !Array.isArray(lean.blocks)) {
|
||||
return { model: current, termIdToBlockId: new Map() };
|
||||
}
|
||||
|
||||
const termByLabel = new Map<string, { id: string; linkedBlockId: string | null }>();
|
||||
for (const t of terms) termByLabel.set(t.label.toLowerCase(), { id: t.id, linkedBlockId: t.linkedBlockId });
|
||||
const resolveTermId = (label: string | undefined): string | undefined => {
|
||||
if (!label) return undefined;
|
||||
return termByLabel.get(label.toLowerCase())?.id;
|
||||
};
|
||||
|
||||
// ─── Blocks ────────────────────────────────────────────────────────────
|
||||
|
||||
const existingByLinkedTerm = new Map<string, Block>();
|
||||
const existingById = new Map<string, Block>();
|
||||
for (const b of current.blocks) {
|
||||
existingById.set(b.id, b);
|
||||
if (b.linkedTermId) existingByLinkedTerm.set(b.linkedTermId, b);
|
||||
}
|
||||
|
||||
const blocks: Block[] = [];
|
||||
const leanIdToCanonical = new Map<string, string>();
|
||||
const termIdToBlockId = new Map<string, string>();
|
||||
const matchedBlockIds = new Set<string>();
|
||||
|
||||
for (const b of lean.blocks) {
|
||||
const linkedTerm = b.linkedTermLabel ? termByLabel.get(b.linkedTermLabel.toLowerCase()) : undefined;
|
||||
|
||||
let existing: Block | undefined;
|
||||
if (linkedTerm) existing = existingByLinkedTerm.get(linkedTerm.id);
|
||||
if (!existing && existingById.has(b.id)) existing = existingById.get(b.id);
|
||||
|
||||
let canonicalId = b.id;
|
||||
let stereotypes: string[] = [b.kind];
|
||||
let propertiesSource = b.properties ?? [];
|
||||
let nextStatus: ReviewStatus = "suggested";
|
||||
let pinned = false;
|
||||
|
||||
if (existing) {
|
||||
canonicalId = existing.id;
|
||||
stereotypes = existing.stereotypes;
|
||||
propertiesSource = mergeProperties(existing.properties, b.properties ?? []);
|
||||
pinned = !!existing.reviewPinned;
|
||||
// Existing accepted stays accepted; existing deprecated flips back to
|
||||
// suggested (analyzer changed its mind); existing suggested stays
|
||||
// suggested.
|
||||
const cur: ReviewStatus = (existing.reviewStatus ?? "accepted") as ReviewStatus;
|
||||
nextStatus = cur === "deprecated" ? "suggested" : cur;
|
||||
matchedBlockIds.add(existing.id);
|
||||
}
|
||||
|
||||
if (linkedTerm) termIdToBlockId.set(linkedTerm.id, canonicalId);
|
||||
leanIdToCanonical.set(b.id, canonicalId);
|
||||
|
||||
blocks.push({
|
||||
id: canonicalId,
|
||||
label: b.label,
|
||||
kind: b.kind,
|
||||
stereotypes,
|
||||
properties: propertiesSource.map((p, i) => ({
|
||||
id: `${canonicalId}_p${i + 1}`,
|
||||
name: p.name,
|
||||
type: expandPropertyType(p.type),
|
||||
multiplicity: "0..1" as const,
|
||||
})),
|
||||
linkedTermId: linkedTerm?.id,
|
||||
reviewStatus: nextStatus,
|
||||
reviewPinned: pinned,
|
||||
});
|
||||
}
|
||||
|
||||
// Existing blocks the analyzer didn't mention.
|
||||
for (const b of current.blocks) {
|
||||
if (matchedBlockIds.has(b.id)) continue;
|
||||
const cur: ReviewStatus = (b.reviewStatus ?? "accepted") as ReviewStatus;
|
||||
if (cur === "suggested") continue; // never reviewed + dropped → drop.
|
||||
if (b.reviewPinned) {
|
||||
blocks.push(b);
|
||||
continue;
|
||||
}
|
||||
blocks.push({ ...b, reviewStatus: "deprecated" });
|
||||
}
|
||||
|
||||
// ─── Associations ─────────────────────────────────────────────────────
|
||||
|
||||
const associations = mergeListByKey<Association, LeanAssoc>({
|
||||
existing: current.associations,
|
||||
incoming: lean.associations ?? [],
|
||||
keyExisting: a => `${a.kind}|${a.fromBlockId}|${a.toBlockId}`,
|
||||
keyIncoming: a =>
|
||||
`${a.kind}|${leanIdToCanonical.get(a.fromBlockId) ?? a.fromBlockId}|${
|
||||
leanIdToCanonical.get(a.toBlockId) ?? a.toBlockId
|
||||
}`,
|
||||
fromIncoming: a => ({
|
||||
id: a.id,
|
||||
fromBlockId: leanIdToCanonical.get(a.fromBlockId) ?? a.fromBlockId,
|
||||
toBlockId: leanIdToCanonical.get(a.toBlockId) ?? a.toBlockId,
|
||||
label: a.label ?? "",
|
||||
kind: a.kind,
|
||||
linkedTermId: resolveTermId(a.linkedTermLabel),
|
||||
}),
|
||||
mergeFields: (existing, incoming) => ({
|
||||
...existing,
|
||||
label: incoming.label ?? existing.label,
|
||||
// linkedTermId: prefer fresh suggestion, fall back to existing.
|
||||
linkedTermId:
|
||||
resolveTermId(incoming.linkedTermLabel) ?? existing.linkedTermId,
|
||||
}),
|
||||
});
|
||||
|
||||
// ─── Constraints ──────────────────────────────────────────────────────
|
||||
|
||||
const constraints = mergeListByKey<Constraint, LeanConstraint>({
|
||||
existing: current.constraints,
|
||||
incoming: lean.constraints ?? [],
|
||||
keyExisting: c => c.linkedTermId ? `term:${c.linkedTermId}` : `label:${normalizeText(c.label)}`,
|
||||
keyIncoming: c => {
|
||||
const tid = resolveTermId(c.linkedTermLabel);
|
||||
return tid ? `term:${tid}` : `label:${normalizeText(c.label)}`;
|
||||
},
|
||||
fromIncoming: c => ({
|
||||
id: c.id,
|
||||
label: c.label,
|
||||
expression: c.expression ?? "",
|
||||
appliesTo: (c.appliesTo ?? []).map(x => leanIdToCanonical.get(x) ?? x),
|
||||
linkedTermId: resolveTermId(c.linkedTermLabel),
|
||||
}),
|
||||
mergeFields: (existing, incoming) => ({
|
||||
...existing,
|
||||
label: incoming.label,
|
||||
expression: incoming.expression ?? existing.expression,
|
||||
appliesTo: (incoming.appliesTo ?? []).map(x => leanIdToCanonical.get(x) ?? x),
|
||||
linkedTermId: resolveTermId(incoming.linkedTermLabel) ?? existing.linkedTermId,
|
||||
}),
|
||||
});
|
||||
|
||||
// ─── Requirements ─────────────────────────────────────────────────────
|
||||
|
||||
const requirements = mergeListByKey<Requirement, LeanRequirement>({
|
||||
existing: current.requirements,
|
||||
incoming: lean.requirements ?? [],
|
||||
keyExisting: r => r.linkedTermId ? `term:${r.linkedTermId}` : `text:${normalizeText(r.text)}`,
|
||||
keyIncoming: r => {
|
||||
const tid = resolveTermId(r.linkedTermLabel);
|
||||
return tid ? `term:${tid}` : `text:${normalizeText(r.text)}`;
|
||||
},
|
||||
fromIncoming: r => ({
|
||||
id: r.id,
|
||||
tag: r.tag,
|
||||
text: r.text,
|
||||
relations: (r.satisfiedBy ?? []).map(blockId => ({
|
||||
kind: "satisfy" as const,
|
||||
blockId: leanIdToCanonical.get(blockId) ?? blockId,
|
||||
})),
|
||||
linkedTermId: resolveTermId(r.linkedTermLabel),
|
||||
}),
|
||||
mergeFields: (existing, incoming) => ({
|
||||
...existing,
|
||||
tag: incoming.tag || existing.tag,
|
||||
text: incoming.text || existing.text,
|
||||
relations: (incoming.satisfiedBy ?? []).map(blockId => ({
|
||||
kind: "satisfy" as const,
|
||||
blockId: leanIdToCanonical.get(blockId) ?? blockId,
|
||||
})),
|
||||
linkedTermId: resolveTermId(incoming.linkedTermLabel) ?? existing.linkedTermId,
|
||||
}),
|
||||
});
|
||||
|
||||
let soiId = lean.systemOfInterestId ? leanIdToCanonical.get(lean.systemOfInterestId) ?? lean.systemOfInterestId : undefined;
|
||||
if (!soiId) {
|
||||
const systems = blocks.filter(b => b.kind === "system");
|
||||
if (systems.length === 1) soiId = systems[0]!.id;
|
||||
}
|
||||
|
||||
return { model: { systemOfInterestId: soiId, blocks, associations, constraints, requirements }, termIdToBlockId };
|
||||
}
|
||||
|
||||
// ─── Generic merge-with-review helper ──────────────────────────────────
|
||||
|
||||
interface ReviewableElement {
|
||||
reviewStatus?: ReviewStatus;
|
||||
reviewPinned?: boolean;
|
||||
}
|
||||
|
||||
interface MergeArgs<E extends ReviewableElement, I> {
|
||||
existing: E[];
|
||||
incoming: I[];
|
||||
keyExisting: (e: E) => string;
|
||||
keyIncoming: (i: I) => string;
|
||||
fromIncoming: (i: I) => E;
|
||||
mergeFields: (existing: E, incoming: I) => E;
|
||||
}
|
||||
|
||||
function mergeListByKey<E extends ReviewableElement, I>(args: MergeArgs<E, I>): E[] {
|
||||
const existingByKey = new Map<string, E>();
|
||||
for (const e of args.existing) existingByKey.set(args.keyExisting(e), e);
|
||||
|
||||
const incomingByKey = new Map<string, I>();
|
||||
for (const i of args.incoming) {
|
||||
const k = args.keyIncoming(i);
|
||||
if (!incomingByKey.has(k)) incomingByKey.set(k, i);
|
||||
}
|
||||
|
||||
const out: E[] = [];
|
||||
const matched = new Set<string>();
|
||||
|
||||
// Phase 1 — incoming.
|
||||
for (const [key, inc] of incomingByKey.entries()) {
|
||||
const prior = existingByKey.get(key);
|
||||
if (!prior) {
|
||||
const created = args.fromIncoming(inc);
|
||||
out.push({ ...created, reviewStatus: "suggested", reviewPinned: false });
|
||||
} else {
|
||||
const merged = args.mergeFields(prior, inc);
|
||||
const cur: ReviewStatus = (prior.reviewStatus ?? "accepted") as ReviewStatus;
|
||||
const nextStatus: ReviewStatus = cur === "deprecated" ? "suggested" : cur;
|
||||
out.push({ ...merged, reviewStatus: nextStatus, reviewPinned: !!prior.reviewPinned });
|
||||
matched.add(key);
|
||||
}
|
||||
}
|
||||
|
||||
// Phase 2 — existing not in incoming.
|
||||
for (const e of args.existing) {
|
||||
const k = args.keyExisting(e);
|
||||
if (matched.has(k)) continue;
|
||||
const cur: ReviewStatus = (e.reviewStatus ?? "accepted") as ReviewStatus;
|
||||
if (cur === "suggested") continue; // unreviewed + dropped → drop.
|
||||
if (e.reviewPinned) {
|
||||
out.push(e);
|
||||
continue;
|
||||
}
|
||||
out.push({ ...e, reviewStatus: "deprecated" });
|
||||
}
|
||||
|
||||
return out;
|
||||
}
|
||||
|
||||
function normalizeText(s: string): string {
|
||||
return (s ?? "").trim().toLowerCase().replace(/\s+/g, " ");
|
||||
}
|
||||
|
||||
function mergeProperties(
|
||||
current: { name: string }[],
|
||||
incoming: LeanProperty[]
|
||||
): LeanProperty[] {
|
||||
const have = new Set(current.map(p => p.name.toLowerCase()));
|
||||
const merged: LeanProperty[] = current.map(p => ({
|
||||
name: p.name,
|
||||
type: { kind: "string" }, // type re-expanded in caller
|
||||
}));
|
||||
for (const p of incoming) {
|
||||
if (!have.has(p.name.toLowerCase())) merged.push(p);
|
||||
}
|
||||
return merged;
|
||||
}
|
||||
|
||||
function expandPropertyType(type: { kind: string; values?: string[] }): PropertyType {
|
||||
if (type.kind === "enum") return { kind: "enum", values: type.values ?? [] };
|
||||
if (type.kind === "number") return { kind: "number" };
|
||||
if (type.kind === "boolean") return { kind: "boolean" };
|
||||
return { kind: "string" };
|
||||
}
|
||||
52
apps/web/lib/llm/analyze/proseText.ts
Normal file
52
apps/web/lib/llm/analyze/proseText.ts
Normal file
@@ -0,0 +1,52 @@
|
||||
// Convert a ProseMirror JSON document into a plain-text string for LLM input.
|
||||
// Headings get markdown-style "##"; chip nodes render as their label so the
|
||||
// analyzer sees the same surface forms a human would.
|
||||
|
||||
import "server-only";
|
||||
|
||||
interface PMNode {
|
||||
type: string;
|
||||
text?: string;
|
||||
attrs?: Record<string, unknown>;
|
||||
content?: PMNode[];
|
||||
}
|
||||
|
||||
export function proseDocToPlainText(doc: unknown): string {
|
||||
if (!doc || typeof doc !== "object") return "";
|
||||
const root = doc as PMNode;
|
||||
return walk(root, 0).trim();
|
||||
}
|
||||
|
||||
function walk(node: PMNode, depth: number): string {
|
||||
if (!node) return "";
|
||||
if (node.type === "text") return node.text ?? "";
|
||||
if (node.type === "chip") {
|
||||
const label = (node.attrs?.label as string | undefined) ?? "";
|
||||
return label;
|
||||
}
|
||||
|
||||
const children = (node.content ?? []).map(c => walk(c, depth + 1)).join("");
|
||||
|
||||
switch (node.type) {
|
||||
case "heading": {
|
||||
const level = typeof node.attrs?.level === "number" ? (node.attrs.level as number) : 1;
|
||||
const hash = "#".repeat(Math.max(1, Math.min(level, 6)));
|
||||
return `\n\n${hash} ${children}\n\n`;
|
||||
}
|
||||
case "paragraph":
|
||||
return `${children}\n\n`;
|
||||
case "bulletList":
|
||||
case "bullet_list":
|
||||
case "orderedList":
|
||||
case "ordered_list":
|
||||
return `${children}\n`;
|
||||
case "listItem":
|
||||
case "list_item":
|
||||
return `- ${children.trim()}\n`;
|
||||
case "hardBreak":
|
||||
case "hard_break":
|
||||
return "\n";
|
||||
default:
|
||||
return children;
|
||||
}
|
||||
}
|
||||
104
apps/web/lib/llm/analyze/requirements.ts
Normal file
104
apps/web/lib/llm/analyze/requirements.ts
Normal file
@@ -0,0 +1,104 @@
|
||||
// Analyze pass: extract requirements from prose with traceability hints.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "../gateway";
|
||||
import { loadPrompt } from "../prompts";
|
||||
import type { DetectedRequirement } from "../../db/repo";
|
||||
|
||||
const reqsJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["requirements"],
|
||||
properties: {
|
||||
requirements: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["tag", "text"],
|
||||
properties: {
|
||||
tag: { type: "string", minLength: 1 },
|
||||
text: { type: "string", minLength: 1 },
|
||||
tracedToLabels: { type: "array", items: { type: "string" } },
|
||||
/// Optional concept the requirement is conceptually "about." Lets the
|
||||
/// requirement render a back-link to the term in TermDetail even when
|
||||
/// the term has no formalized block yet.
|
||||
linkedTermLabel: { type: "string" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
} as const;
|
||||
|
||||
export interface RequirementsResult {
|
||||
reqs: DetectedRequirement[];
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model: string;
|
||||
}
|
||||
|
||||
export async function analyzeRequirements(
|
||||
documentText: string,
|
||||
terms: Array<{ id: string; label: string; linkedBlockId: string | null }>
|
||||
): Promise<RequirementsResult> {
|
||||
const prompt = loadPrompt("socrates/analyze-requirements.md");
|
||||
const gateway = defaultGateway();
|
||||
const userPayload =
|
||||
`Document:\n\n${documentText}\n\n---\n\n` +
|
||||
`Available term labels:\n${JSON.stringify(terms.map(t => t.label))}`;
|
||||
|
||||
const messages: Message[] = [
|
||||
{ role: "system", content: prompt },
|
||||
{ role: "user", content: userPayload },
|
||||
];
|
||||
|
||||
const { value, result } = await chatJSON<{
|
||||
requirements?: Array<{
|
||||
tag?: string;
|
||||
text?: string;
|
||||
tracedToLabels?: string[];
|
||||
linkedTermLabel?: string;
|
||||
}>;
|
||||
}>(gateway, messages, {
|
||||
temperature: 0.2,
|
||||
maxTokens: 1500,
|
||||
jsonSchema: { name: "requirements", schema: reqsJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
});
|
||||
|
||||
// Map term labels → block ids via the term-to-block links + label → termId.
|
||||
const labelToBlock = new Map<string, string>();
|
||||
const labelToTermId = new Map<string, string>();
|
||||
for (const t of terms) {
|
||||
if (t.linkedBlockId) labelToBlock.set(t.label.toLowerCase(), t.linkedBlockId);
|
||||
labelToTermId.set(t.label.toLowerCase(), t.id);
|
||||
}
|
||||
|
||||
const reqs: DetectedRequirement[] = [];
|
||||
for (const r of value?.requirements ?? []) {
|
||||
const tag = (r.tag ?? "").trim();
|
||||
const text = (r.text ?? "").trim();
|
||||
if (!tag || !text) continue;
|
||||
const blockIds = (r.tracedToLabels ?? [])
|
||||
.map(l => labelToBlock.get(l.toLowerCase()))
|
||||
.filter((id): id is string => Boolean(id));
|
||||
const linkedTermId = r.linkedTermLabel ? labelToTermId.get(r.linkedTermLabel.toLowerCase()) : undefined;
|
||||
reqs.push({
|
||||
tag,
|
||||
text,
|
||||
tracedToIds: blockIds,
|
||||
unsupported: blockIds.length === 0,
|
||||
linkedTermId: linkedTermId ?? null,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
reqs,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model: gateway.model,
|
||||
};
|
||||
}
|
||||
206
apps/web/lib/llm/analyze/runAll.ts
Normal file
206
apps/web/lib/llm/analyze/runAll.ts
Normal file
@@ -0,0 +1,206 @@
|
||||
// Analyze orchestrator. Runs the requested sections sequentially. Sections
|
||||
// are independent: a partial failure in one doesn't abort the rest. Each
|
||||
// section writes an AnalysisRun row for telemetry / "last-run" timestamps.
|
||||
//
|
||||
// Order matters when "all" is selected:
|
||||
// 1. concepts (taxonomy + glossary in one pass — others depend on its output)
|
||||
// 2. model (uses the term list, can populate Block/Assoc/Constraint/Req
|
||||
// linkedTermIds)
|
||||
// 3. requirements (uses term-to-block links from model)
|
||||
// 4. assumptions, risks, inconsistencies (run on the refreshed model)
|
||||
//
|
||||
// Per-section runs skip the dependency steps and use whatever's already in
|
||||
// the DB. That keeps "I just want to refresh concepts" cheap.
|
||||
|
||||
import "server-only";
|
||||
import {
|
||||
loadDocument,
|
||||
loadProject,
|
||||
replaceModel,
|
||||
startAnalysisRun,
|
||||
finishAnalysisRun,
|
||||
mergeTaxonomySuggestion,
|
||||
applyGlossaryDefinitions,
|
||||
listTerms,
|
||||
mergeRequirementsSuggestion,
|
||||
mergeFindingsSuggestion,
|
||||
linkTermToBlock,
|
||||
type AnalysisSection,
|
||||
} from "../../db/repo";
|
||||
import { proseDocToPlainText } from "./proseText";
|
||||
import { analyzeConcepts } from "./concepts";
|
||||
import { analyzeRequirements } from "./requirements";
|
||||
import { analyzeModelFromProse } from "./model";
|
||||
import { detectFindings, type Finding } from "../detect";
|
||||
import { crossValidate } from "../../sysml/crossValidate";
|
||||
|
||||
export type RunSection = AnalysisSection;
|
||||
|
||||
export interface SectionOutcome {
|
||||
section: RunSection;
|
||||
status: "succeeded" | "failed" | "skipped";
|
||||
message?: string;
|
||||
inputTokens?: number;
|
||||
outputTokens?: number;
|
||||
}
|
||||
|
||||
export interface AnalyzeRunResult {
|
||||
outcomes: SectionOutcome[];
|
||||
modelVersion: number;
|
||||
}
|
||||
|
||||
const ALL: RunSection[] = [
|
||||
"concepts",
|
||||
"model",
|
||||
"requirements",
|
||||
"assumptions",
|
||||
"risks",
|
||||
"inconsistencies",
|
||||
];
|
||||
|
||||
export async function runAnalyze(projectId: string, requested: RunSection): Promise<AnalyzeRunResult> {
|
||||
const sections: RunSection[] = requested === "all" ? ALL : [requested];
|
||||
|
||||
const docRow = await loadDocument(projectId);
|
||||
const documentText = docRow ? proseDocToPlainText(docRow.doc) : "";
|
||||
if (!documentText.trim()) {
|
||||
return {
|
||||
outcomes: sections.map(s => ({ section: s, status: "skipped", message: "Empty document" })),
|
||||
modelVersion: (await loadProject(projectId)).version,
|
||||
};
|
||||
}
|
||||
|
||||
const outcomes: SectionOutcome[] = [];
|
||||
|
||||
for (const section of sections) {
|
||||
const { version: modelVersion } = await loadProject(projectId);
|
||||
const runId = await startAnalysisRun(projectId, section, modelVersion);
|
||||
try {
|
||||
const out = await runSection(projectId, section, documentText);
|
||||
await finishAnalysisRun(runId, {
|
||||
status: "succeeded",
|
||||
inputTokens: out.inputTokens,
|
||||
outputTokens: out.outputTokens,
|
||||
});
|
||||
outcomes.push({ section, status: "succeeded", inputTokens: out.inputTokens, outputTokens: out.outputTokens });
|
||||
} catch (err) {
|
||||
const message = (err as Error).message;
|
||||
console.error(`[analyze] ${section} failed:`, message);
|
||||
await finishAnalysisRun(runId, { status: "failed", errorMessage: message });
|
||||
outcomes.push({ section, status: "failed", message });
|
||||
}
|
||||
}
|
||||
|
||||
const finalVersion = (await loadProject(projectId)).version;
|
||||
return { outcomes, modelVersion: finalVersion };
|
||||
}
|
||||
|
||||
// ─── Per-section runners ─────────────────────────────────────────────────
|
||||
|
||||
interface RunOut {
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
}
|
||||
|
||||
async function runSection(projectId: string, section: RunSection, documentText: string): Promise<RunOut> {
|
||||
switch (section) {
|
||||
case "concepts":
|
||||
return runConcepts(projectId, documentText);
|
||||
case "model":
|
||||
return runModel(projectId, documentText);
|
||||
case "requirements":
|
||||
return runRequirements(projectId, documentText);
|
||||
case "assumptions":
|
||||
case "risks":
|
||||
case "inconsistencies":
|
||||
return runFindings(projectId);
|
||||
case "all":
|
||||
throw new Error("'all' must be expanded by the caller");
|
||||
}
|
||||
}
|
||||
|
||||
async function runConcepts(projectId: string, documentText: string): Promise<RunOut> {
|
||||
const { version } = await loadProject(projectId);
|
||||
const { terms, definitions, inputTokens, outputTokens } = await analyzeConcepts(documentText);
|
||||
// Merge instead of replace — analyzer suggestions surface as a *review*.
|
||||
// The user keeps or discards each pending change; accepted state survives.
|
||||
await mergeTaxonomySuggestion(projectId, terms, version);
|
||||
if (definitions.length > 0) {
|
||||
// Definitions still apply only to "accepted" terms whose definition is
|
||||
// empty; mergeTaxonomySuggestion's gentle-update path keeps user-edited
|
||||
// definitions, but the dedicated patch is harmless for new terms.
|
||||
await applyGlossaryDefinitions(projectId, definitions);
|
||||
}
|
||||
return { inputTokens, outputTokens };
|
||||
}
|
||||
|
||||
async function runModel(projectId: string, documentText: string): Promise<RunOut> {
|
||||
const { model: current } = await loadProject(projectId);
|
||||
const terms = await listTerms(projectId);
|
||||
const { model, termIdToBlockId, inputTokens, outputTokens } = await analyzeModelFromProse(
|
||||
documentText,
|
||||
terms.map(t => ({ id: t.id, label: t.label, linkedBlockId: t.linkedBlockId })),
|
||||
current
|
||||
);
|
||||
|
||||
await replaceModel(projectId, model, "Analyze: model refresh");
|
||||
|
||||
// Update term → block linkage based on what the analyzer linked.
|
||||
for (const [termId, blockId] of termIdToBlockId.entries()) {
|
||||
await linkTermToBlock(termId, blockId);
|
||||
}
|
||||
|
||||
return { inputTokens, outputTokens };
|
||||
}
|
||||
|
||||
async function runRequirements(projectId: string, documentText: string): Promise<RunOut> {
|
||||
const { version } = await loadProject(projectId);
|
||||
const terms = await listTerms(projectId);
|
||||
const { reqs, inputTokens, outputTokens } = await analyzeRequirements(
|
||||
documentText,
|
||||
terms.map(t => ({ id: t.id, label: t.label, linkedBlockId: t.linkedBlockId }))
|
||||
);
|
||||
await mergeRequirementsSuggestion(projectId, reqs, version);
|
||||
return { inputTokens, outputTokens };
|
||||
}
|
||||
|
||||
async function runFindings(projectId: string): Promise<RunOut> {
|
||||
const { model, version } = await loadProject(projectId);
|
||||
const result = await detectFindings(model);
|
||||
|
||||
// Cross-layer validation (T2): glue rules between terms and ontology.
|
||||
// Surfaced as inconsistency-kind findings keyed by validationCode = X*.
|
||||
const terms = await listTerms(projectId);
|
||||
const cross = crossValidate({
|
||||
model,
|
||||
terms: terms.map(t => ({ id: t.id, label: t.label, linkedBlockId: t.linkedBlockId })),
|
||||
// X4 needs prose-occurrence counts; left undefined here so it stays
|
||||
// off until we wire prose extraction. X1–X3 still fire.
|
||||
});
|
||||
const crossFindings: Finding[] = cross.map(issue => ({
|
||||
kind: "inconsistency",
|
||||
text: issue.message,
|
||||
linkedElementIds: anchorIds(issue.anchor),
|
||||
confidence: 1.0,
|
||||
severity: issue.severity === "warning" ? "medium" : "low",
|
||||
validationCode: issue.code,
|
||||
}));
|
||||
|
||||
await mergeFindingsSuggestion(
|
||||
projectId,
|
||||
[...result.findings, ...crossFindings],
|
||||
version,
|
||||
result.provider,
|
||||
result.model
|
||||
);
|
||||
return { inputTokens: result.inputTokens, outputTokens: result.outputTokens };
|
||||
}
|
||||
|
||||
function anchorIds(a: import("../../sysml/validate").IssueAnchor): string[] {
|
||||
if (a.kind === "model") return [];
|
||||
if (a.kind === "property") return [a.blockId];
|
||||
// T3: prefix term anchors with `term:` so consumers (FindingsPane,
|
||||
// TermDetail) can route them to the concept popover instead of the model.
|
||||
if (a.kind === "term") return [`term:${a.id}`];
|
||||
return [a.id];
|
||||
}
|
||||
81
apps/web/lib/llm/analyze/taxonomy.ts
Normal file
81
apps/web/lib/llm/analyze/taxonomy.ts
Normal file
@@ -0,0 +1,81 @@
|
||||
// Analyze pass: extract taxonomy terms from prose.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "../gateway";
|
||||
import { loadPrompt } from "../prompts";
|
||||
import type { DetectedTerm } from "../../db/repo";
|
||||
|
||||
interface RawTerm {
|
||||
label?: string;
|
||||
parentLabel?: string | null;
|
||||
synonyms?: string[];
|
||||
}
|
||||
|
||||
const taxonomyJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["terms"],
|
||||
properties: {
|
||||
terms: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["label"],
|
||||
properties: {
|
||||
label: { type: "string", minLength: 1 },
|
||||
parentLabel: { type: ["string", "null"] },
|
||||
synonyms: { type: "array", items: { type: "string" } },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
} as const;
|
||||
|
||||
export interface TaxonomyResult {
|
||||
terms: DetectedTerm[];
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model: string;
|
||||
}
|
||||
|
||||
export async function analyzeTaxonomy(documentText: string): Promise<TaxonomyResult> {
|
||||
const prompt = loadPrompt("socrates/analyze-taxonomy.md");
|
||||
const gateway = defaultGateway();
|
||||
const messages: Message[] = [
|
||||
{ role: "system", content: prompt },
|
||||
{ role: "user", content: `Document:\n\n${documentText}` },
|
||||
];
|
||||
|
||||
const { value, result } = await chatJSON<{ terms?: RawTerm[] }>(gateway, messages, {
|
||||
temperature: 0.2,
|
||||
maxTokens: 1500,
|
||||
jsonSchema: { name: "taxonomy", schema: taxonomyJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
});
|
||||
|
||||
const seen = new Set<string>();
|
||||
const terms: DetectedTerm[] = [];
|
||||
for (const t of value?.terms ?? []) {
|
||||
const label = (t.label ?? "").trim();
|
||||
if (!label) continue;
|
||||
const key = label.toLowerCase();
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
terms.push({
|
||||
label,
|
||||
parentLabel: t.parentLabel?.trim() || null,
|
||||
synonyms: Array.isArray(t.synonyms) ? t.synonyms.filter(s => typeof s === "string") : [],
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
terms,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model: gateway.model,
|
||||
};
|
||||
}
|
||||
275
apps/web/lib/llm/generateModel.ts
Normal file
275
apps/web/lib/llm/generateModel.ts
Normal file
@@ -0,0 +1,275 @@
|
||||
// Seed → SysMLModel via the Phase-0-validated generate prompt.
|
||||
//
|
||||
// Returns a validated, expanded SysMLModel with property ids, multiplicities,
|
||||
// stereotypes filled in. The LLM emits a "lean" shape; we expand it to match
|
||||
// the canonical lib/sysml/model.ts types.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "./gateway";
|
||||
import { loadPrompt } from "./prompts";
|
||||
import type {
|
||||
SysMLModel,
|
||||
Block,
|
||||
Association,
|
||||
Constraint,
|
||||
Requirement,
|
||||
Property,
|
||||
PropertyType,
|
||||
} from "../sysml/model";
|
||||
import type { SeedDraft } from "./seedInterview";
|
||||
|
||||
// ─── LLM-facing lean shape (matches Phase 0's generate.md output) ───────
|
||||
|
||||
interface LeanProperty {
|
||||
name: string;
|
||||
type: { kind: "string" | "number" | "boolean" | "enum"; values?: string[] };
|
||||
}
|
||||
interface LeanBlock {
|
||||
id: string;
|
||||
label: string;
|
||||
kind: "system" | "actor" | "block";
|
||||
properties?: LeanProperty[];
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanAssociation {
|
||||
id: string;
|
||||
fromBlockId: string;
|
||||
toBlockId: string;
|
||||
label?: string;
|
||||
kind: "association" | "composition" | "aggregation" | "generalization" | "constraintApplies";
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanConstraint {
|
||||
id: string;
|
||||
label: string;
|
||||
expression?: string;
|
||||
appliesTo?: string[];
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanRequirement {
|
||||
id: string;
|
||||
tag: string;
|
||||
text: string;
|
||||
satisfiedBy?: string[];
|
||||
confidence: number;
|
||||
}
|
||||
interface LeanModel {
|
||||
systemOfInterestId?: string;
|
||||
blocks: LeanBlock[];
|
||||
associations?: LeanAssociation[];
|
||||
constraints?: LeanConstraint[];
|
||||
requirements?: LeanRequirement[];
|
||||
overallConfidence?: number;
|
||||
notes?: string;
|
||||
}
|
||||
|
||||
// ─── JSON Schema for response_format ─────────────────────────────────────
|
||||
|
||||
const generateJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
systemOfInterestId: { type: "string" },
|
||||
blocks: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "label", "kind", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
label: { type: "string", minLength: 1 },
|
||||
kind: { type: "string", enum: ["system", "actor", "block"] },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
properties: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["name", "type"],
|
||||
properties: {
|
||||
name: { type: "string", minLength: 1 },
|
||||
type: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["kind"],
|
||||
properties: {
|
||||
kind: { type: "string", enum: ["string", "number", "boolean", "enum"] },
|
||||
values: { type: "array", items: { type: "string" } },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
associations: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "fromBlockId", "toBlockId", "kind", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
fromBlockId: { type: "string", minLength: 1 },
|
||||
toBlockId: { type: "string", minLength: 1 },
|
||||
label: { type: "string" },
|
||||
kind: { type: "string", enum: ["association", "composition", "aggregation", "generalization", "constraintApplies"] },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
},
|
||||
},
|
||||
constraints: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "label", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
label: { type: "string", minLength: 1 },
|
||||
expression: { type: "string" },
|
||||
appliesTo: { type: "array", items: { type: "string" } },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
},
|
||||
},
|
||||
requirements: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["id", "tag", "text", "confidence"],
|
||||
properties: {
|
||||
id: { type: "string", minLength: 1 },
|
||||
tag: { type: "string", minLength: 1 },
|
||||
text: { type: "string", minLength: 1 },
|
||||
satisfiedBy: { type: "array", items: { type: "string" } },
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
},
|
||||
},
|
||||
},
|
||||
overallConfidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
notes: { type: "string" },
|
||||
},
|
||||
required: ["blocks"],
|
||||
} as const;
|
||||
|
||||
// ─── Public API ──────────────────────────────────────────────────────────
|
||||
|
||||
export interface GenerateModelResult {
|
||||
model: SysMLModel;
|
||||
overallConfidence: number;
|
||||
notes?: string;
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model_name: string;
|
||||
}
|
||||
|
||||
export async function generateModelFromSeed(seed: SeedDraft): Promise<GenerateModelResult> {
|
||||
const character = loadPrompt("socrates/character.md");
|
||||
const generate = loadPrompt("socrates/generate.md");
|
||||
|
||||
const userPayload =
|
||||
`Seed payload to model:\n\`\`\`json\n${JSON.stringify(seed, null, 2)}\n\`\`\`\n` +
|
||||
`Return only the JSON object conforming to the schema. No prose preamble, no code fences.`;
|
||||
|
||||
const messages: Message[] = [
|
||||
{ role: "system", content: `${character}\n\n---\n\n${generate}` },
|
||||
{ role: "user", content: userPayload },
|
||||
];
|
||||
|
||||
const gateway = defaultGateway();
|
||||
const { value, result } = await chatJSON<LeanModel>(gateway, messages, {
|
||||
temperature: 0.3,
|
||||
maxTokens: 2048,
|
||||
jsonSchema: { name: "sysml_model", schema: generateJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
});
|
||||
|
||||
const model = expand(value);
|
||||
|
||||
return {
|
||||
model,
|
||||
overallConfidence: clamp01(value?.overallConfidence ?? 0.5),
|
||||
notes: value?.notes,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model_name: gateway.model,
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Lean → canonical SysMLModel ────────────────────────────────────────
|
||||
|
||||
function expand(lean: LeanModel | null | undefined): SysMLModel {
|
||||
if (!lean || !Array.isArray(lean.blocks)) {
|
||||
return { blocks: [], associations: [], constraints: [], requirements: [] };
|
||||
}
|
||||
|
||||
const blocks: Block[] = lean.blocks.map(b => ({
|
||||
id: b.id,
|
||||
label: b.label,
|
||||
kind: b.kind,
|
||||
stereotypes: [b.kind],
|
||||
properties: (b.properties ?? []).map((p, i) => ({
|
||||
id: `${b.id}_p${i + 1}`,
|
||||
name: p.name,
|
||||
type: expandPropertyType(p.type),
|
||||
multiplicity: "0..1" as const,
|
||||
})),
|
||||
}));
|
||||
|
||||
const associations: Association[] = (lean.associations ?? []).map(a => ({
|
||||
id: a.id,
|
||||
fromBlockId: a.fromBlockId,
|
||||
toBlockId: a.toBlockId,
|
||||
label: a.label ?? "",
|
||||
kind: a.kind,
|
||||
}));
|
||||
|
||||
const constraints: Constraint[] = (lean.constraints ?? []).map(c => ({
|
||||
id: c.id,
|
||||
label: c.label,
|
||||
expression: c.expression ?? "",
|
||||
appliesTo: c.appliesTo ?? [],
|
||||
}));
|
||||
|
||||
const requirements: Requirement[] = (lean.requirements ?? []).map(r => ({
|
||||
id: r.id,
|
||||
tag: r.tag,
|
||||
text: r.text,
|
||||
relations: (r.satisfiedBy ?? []).map(blockId => ({ kind: "satisfy" as const, blockId })),
|
||||
}));
|
||||
|
||||
// Resolve SoI: prefer the LLM-supplied id if it exists; otherwise the unique kind:'system' block.
|
||||
let soiId = lean.systemOfInterestId;
|
||||
if (!soiId) {
|
||||
const systems = blocks.filter(b => b.kind === "system");
|
||||
if (systems.length === 1) soiId = systems[0]!.id;
|
||||
}
|
||||
|
||||
return {
|
||||
systemOfInterestId: soiId,
|
||||
blocks,
|
||||
associations,
|
||||
constraints,
|
||||
requirements,
|
||||
};
|
||||
}
|
||||
|
||||
function expandPropertyType(type: { kind: string; values?: string[] }): PropertyType {
|
||||
if (type.kind === "enum") return { kind: "enum", values: type.values ?? [] };
|
||||
if (type.kind === "number") return { kind: "number" };
|
||||
if (type.kind === "boolean") return { kind: "boolean" };
|
||||
return { kind: "string" };
|
||||
}
|
||||
function clamp01(n: number): number {
|
||||
if (Number.isNaN(n)) return 0;
|
||||
return Math.max(0, Math.min(1, n));
|
||||
}
|
||||
// Suppress unused-import warning in some TS configs.
|
||||
type _Property = Property;
|
||||
56
apps/web/lib/llm/prompts/socrates/analyze-concepts.md
Normal file
56
apps/web/lib/llm/prompts/socrates/analyze-concepts.md
Normal file
@@ -0,0 +1,56 @@
|
||||
You are extracting **concepts** from a product-thinking document — a piece of structured prose written by a product manager describing an idea. The output combines what we used to call "taxonomy" (terms + hierarchy) and "glossary" (definitions) into one pass: a single emit keeps definitions in lockstep with the hierarchy.
|
||||
|
||||
## Goal
|
||||
|
||||
Identify the **distinct concepts** the document refers to — entities, actors, artifacts, processes, attributes — arrange them into a parent/child hierarchy when one is clearly implied, and write a short definition for each.
|
||||
|
||||
## What counts as a term
|
||||
|
||||
- A noun phrase that names a recurring concept ("Tutor", "Lesson Plan", "Skill Tree").
|
||||
- An actor or stakeholder ("Student", "Parent", "Curriculum Designer").
|
||||
- A domain artifact ("Quiz", "Progress Report").
|
||||
- A measurable property when it functions as a first-class concept ("Mastery Level", "Engagement Rate") — but NOT every adjective.
|
||||
|
||||
## What does NOT count
|
||||
|
||||
- Generic English words ("user", "system", "thing") unless the document uses them with a specific meaning.
|
||||
- Adjectives, adverbs, verbs, or transient phrases.
|
||||
- Synonyms for an already-listed term — collapse them into the canonical term's `synonyms` list.
|
||||
|
||||
## Hierarchy rules
|
||||
|
||||
- Use `parentLabel` only when the document explicitly says or strongly implies the child is-a-kind-of the parent (subset, specialization), or part-of-and-defining-feature-of.
|
||||
- Do NOT invent hierarchies that aren't in the document.
|
||||
- A term may have no parent. Most should.
|
||||
|
||||
## Definition rules
|
||||
|
||||
- 1–2 sentences, ≤ 35 words.
|
||||
- Phrased as a noun-phrase definition, not a sentence about the term ("A student-facing agent that …", not "The Tutor is …").
|
||||
- Use only what the document actually says or strongly implies. Do not import outside knowledge.
|
||||
- If the document does not give enough to define the term, return an empty string for that term — do not guess.
|
||||
|
||||
## Output
|
||||
|
||||
Return a single JSON object with this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"terms": [
|
||||
{
|
||||
"label": "Tutor",
|
||||
"parentLabel": null,
|
||||
"synonyms": ["AI tutor", "tutor agent"],
|
||||
"definition": "A student-facing agent that guides a learner through Socratic questioning toward a curriculum goal."
|
||||
},
|
||||
{
|
||||
"label": "Socratic Tutor",
|
||||
"parentLabel": "Tutor",
|
||||
"synonyms": [],
|
||||
"definition": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Return ONLY the JSON object. No prose. No code fences.
|
||||
28
apps/web/lib/llm/prompts/socrates/analyze-glossary.md
Normal file
28
apps/web/lib/llm/prompts/socrates/analyze-glossary.md
Normal file
@@ -0,0 +1,28 @@
|
||||
You are writing **glossary definitions** for a list of terms extracted from a product-thinking document. The user will read these definitions in a sidebar and click to jump to the first occurrence in the document.
|
||||
|
||||
## Inputs
|
||||
|
||||
- The full prose document.
|
||||
- A list of taxonomy terms (each with an optional parent and synonyms).
|
||||
|
||||
## Output
|
||||
|
||||
For each term, write a **short, document-grounded** definition:
|
||||
|
||||
- 1–2 sentences, ≤ 35 words.
|
||||
- Phrased as a noun-phrase definition, not a sentence about the term ("A student-facing agent that …", not "The Tutor is …").
|
||||
- Use only what the document actually says or strongly implies. Do not import outside knowledge.
|
||||
- If the document does not give enough to define the term, return an empty string for that term — do not guess.
|
||||
|
||||
Return a single JSON object:
|
||||
|
||||
```json
|
||||
{
|
||||
"definitions": [
|
||||
{ "label": "Tutor", "definition": "A student-facing agent that guides a learner through Socratic questioning toward a curriculum goal." },
|
||||
{ "label": "Skill Tree", "definition": "" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Return ONLY the JSON object. No prose. No code fences.
|
||||
70
apps/web/lib/llm/prompts/socrates/analyze-model.md
Normal file
70
apps/web/lib/llm/prompts/socrates/analyze-model.md
Normal file
@@ -0,0 +1,70 @@
|
||||
You are deriving a **SysML model** from a product-thinking document and a known taxonomy of terms. The output backs a visual ontology canvas the user will edit.
|
||||
|
||||
## Inputs
|
||||
|
||||
- The prose document.
|
||||
- The taxonomy term list — each label is a candidate block.
|
||||
|
||||
## What to produce
|
||||
|
||||
A lean SysML model with **blocks** (and optionally associations, constraints, requirements). Prefer a small, accurate model over a large, speculative one.
|
||||
|
||||
### Blocks
|
||||
|
||||
- Use the taxonomy as the *primary* source of block candidates. Most blocks should correspond to a taxonomy term.
|
||||
- `kind`: `"system"` for the overall thing being designed, `"actor"` for human/external roles, `"block"` for everything else.
|
||||
- Reuse the term's exact `label` as the block label.
|
||||
- Set `linkedTermLabel` to the matching term so we can mark it as linked in the sidebar. Use the same spelling as the term list.
|
||||
- A block is allowed without a taxonomy term only when the document clearly implies it but no term was extracted (rare).
|
||||
|
||||
### Associations
|
||||
|
||||
- Only include associations the document actually describes. No speculation.
|
||||
- Verb phrase labels: `"guides"`, `"contains"`, `"reports_to"`.
|
||||
- Optional `linkedTermLabel`: when the relationship itself is named in the
|
||||
taxonomy as a concept (e.g. there's a term "Mentorship" and the association
|
||||
is "Tutor mentors Student"), set it. Most associations don't have one.
|
||||
|
||||
### Constraints
|
||||
|
||||
- Optional `linkedTermLabel`: when the constraint is a concept on its own (e.g.
|
||||
the term "Daily Cap" and the constraint is `sessions_per_day <= 3`), set it.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Optional `linkedTermLabel`: when the requirement is fundamentally *about* a
|
||||
single taxonomy term (e.g. REQ-001 is about Personalization), set it. This
|
||||
is distinct from `satisfiedBy` (which links to blocks the requirement
|
||||
formalizes against).
|
||||
|
||||
### Confidence
|
||||
|
||||
Score `confidence` ∈ [0, 1] honestly. Things straight from the prose: 0.8+. Reasonable inferences: 0.5–0.7. Speculation: leave it out.
|
||||
|
||||
## Output
|
||||
|
||||
```json
|
||||
{
|
||||
"systemOfInterestId": "tutor",
|
||||
"blocks": [
|
||||
{
|
||||
"id": "tutor",
|
||||
"label": "Tutor",
|
||||
"kind": "system",
|
||||
"linkedTermLabel": "Tutor",
|
||||
"confidence": 0.95,
|
||||
"properties": [
|
||||
{ "name": "personality", "type": { "kind": "enum", "values": ["socratic", "encouraging"] } }
|
||||
]
|
||||
}
|
||||
],
|
||||
"associations": [
|
||||
{ "id": "a1", "fromBlockId": "tutor", "toBlockId": "student", "label": "guides", "kind": "association", "confidence": 0.9 }
|
||||
],
|
||||
"constraints": [],
|
||||
"requirements": [],
|
||||
"overallConfidence": 0.8
|
||||
}
|
||||
```
|
||||
|
||||
Return ONLY the JSON object. No prose. No code fences.
|
||||
37
apps/web/lib/llm/prompts/socrates/analyze-requirements.md
Normal file
37
apps/web/lib/llm/prompts/socrates/analyze-requirements.md
Normal file
@@ -0,0 +1,37 @@
|
||||
You are extracting **requirements** from a product-thinking document. The document was written by a product manager describing what they want to build.
|
||||
|
||||
## What counts as a requirement
|
||||
|
||||
- A statement that says the system *must*, *should*, *needs to*, or otherwise commits to a behavior or property.
|
||||
- A success criterion the document explicitly names (e.g. "the user must be able to …").
|
||||
- A hard constraint phrased as a property of the system ("response time under 500ms", "free for students").
|
||||
|
||||
## What does NOT count
|
||||
|
||||
- General descriptions of the idea or domain context.
|
||||
- Aspirational vision statements without an actionable bar ("we want to change education").
|
||||
- Open questions, hypotheses, or assumptions.
|
||||
|
||||
## Output
|
||||
|
||||
Return a single JSON object:
|
||||
|
||||
```json
|
||||
{
|
||||
"requirements": [
|
||||
{
|
||||
"tag": "REQ-001",
|
||||
"text": "The tutor must adapt difficulty to the learner's measured mastery within 3 turns.",
|
||||
"tracedToLabels": ["Tutor", "Mastery Level"],
|
||||
"linkedTermLabel": "Tutor"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- Tags are sequential `REQ-NNN` starting at `REQ-001`.
|
||||
- `tracedToLabels` lists the **taxonomy term labels** (provided in the user payload) this requirement is about. Use exactly the spellings from the term list. Empty array is allowed if no term clearly applies — those will be flagged as unsupported.
|
||||
- `linkedTermLabel` (optional) names the **single concept the requirement is fundamentally about** — pick one from the term list when one clearly stands out. Use this for the requirement's primary anchor (the others belong in `tracedToLabels`). Omit when no single concept dominates.
|
||||
- Keep the `text` short and imperative; quote/paraphrase the document, do not invent.
|
||||
|
||||
Return ONLY the JSON object. No prose. No code fences.
|
||||
47
apps/web/lib/llm/prompts/socrates/analyze-taxonomy.md
Normal file
47
apps/web/lib/llm/prompts/socrates/analyze-taxonomy.md
Normal file
@@ -0,0 +1,47 @@
|
||||
You are extracting a **taxonomy** from a product-thinking document. The document is a piece of structured prose written by a product manager describing an idea.
|
||||
|
||||
## Goal
|
||||
|
||||
Identify the **distinct concepts** the document refers to — entities, actors, artifacts, processes, attributes — and arrange them into a parent/child hierarchy when one is clearly implied by the prose.
|
||||
|
||||
## What counts as a term
|
||||
|
||||
- A noun phrase that names a recurring concept ("Tutor", "Lesson Plan", "Skill Tree").
|
||||
- An actor or stakeholder ("Student", "Parent", "Curriculum Designer").
|
||||
- A domain artifact ("Quiz", "Progress Report").
|
||||
- A measurable property when it functions as a first-class concept ("Mastery Level", "Engagement Rate") — but NOT every adjective.
|
||||
|
||||
## What does NOT count
|
||||
|
||||
- Generic English words ("user", "system", "thing") unless the document uses them with a specific meaning.
|
||||
- Adjectives, adverbs, verbs, or transient phrases.
|
||||
- Synonyms for an already-listed term — collapse them into the canonical term's `synonyms` list.
|
||||
|
||||
## Hierarchy rules
|
||||
|
||||
- Use `parentLabel` only when the document explicitly says or strongly implies the child is-a-kind-of the parent (subset, specialization), or part-of-and-defining-feature-of.
|
||||
- Do NOT invent hierarchies that aren't in the document.
|
||||
- A term may have no parent. Most should.
|
||||
|
||||
## Output
|
||||
|
||||
Return a single JSON object with this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"terms": [
|
||||
{
|
||||
"label": "Tutor",
|
||||
"parentLabel": null,
|
||||
"synonyms": ["AI tutor", "tutor agent"]
|
||||
},
|
||||
{
|
||||
"label": "Socratic Tutor",
|
||||
"parentLabel": "Tutor",
|
||||
"synonyms": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Return ONLY the JSON object, no prose, no code fences.
|
||||
120
apps/web/lib/llm/prompts/socrates/generate.md
Normal file
120
apps/web/lib/llm/prompts/socrates/generate.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# Generate a SysML-shaped product model from a seed idea
|
||||
|
||||
You are an analyst who turns a product manager's seed idea into a structured systems-engineering model.
|
||||
|
||||
## Input
|
||||
You will receive a seed payload as JSON with these fields:
|
||||
- `problem` — the user-named problem (1–3 sentences)
|
||||
- `targetUser` — who experiences the problem
|
||||
- `desiredOutcome` — what success looks like
|
||||
- `initialHypothesis` — optional belief about adoption or mechanism
|
||||
- `constraints` — optional list of explicit non-negotiable rules (literal strings)
|
||||
|
||||
## Output structure — FOUR distinct top-level arrays
|
||||
|
||||
You must populate ALL FOUR of these arrays when the seed supports it. Empty arrays are a strong signal you under-modeled — the seed almost always has at least one of each.
|
||||
|
||||
1. **`blocks`** — entities (kinds: `system`, `actor`, `block`). The thing being built and the things it interacts with or reasons about.
|
||||
2. **`associations`** — labeled relationships between blocks. Verb phrases like `consults`, `enrolled_in`, `scoped_to`.
|
||||
3. **`constraints`** — non-negotiable invariants the system must obey. Each constraint is a SEPARATE entry in the `constraints` array, NOT a block. Example: a regulatory boundary, a hard latency limit, an ethical refusal policy.
|
||||
4. **`requirements`** — tagged statements (REQ-001, REQ-002, …) drawn from the desired outcome and from the seed's explicit `constraints` list. Each requirement lists which block(s) satisfy it.
|
||||
|
||||
## Rules
|
||||
|
||||
**System of Interest (SoI):** Exactly one block has `kind: "system"`. Name it after the *thing being built*, not the problem. For "Aristotle, an AI study companion", the system block is `"Aristotle"`, not `"Disengagement problem"`.
|
||||
|
||||
**Actors:** People or external systems that interact with the SoI. `kind: "actor"`.
|
||||
|
||||
**Blocks:** Things the system reasons about that aren't actors. `kind: "block"`.
|
||||
|
||||
**Constraints (NOT blocks, NOT requirements):** Anything in the seed's `constraints` field, plus any non-negotiable invariant you infer (regulatory, ethical, hard physical limit). Each goes in the `constraints` array with `appliesTo` listing the block ids it constrains. Often `appliesTo` is just the SoI.
|
||||
|
||||
**The Constraint–Requirement boundary (READ THIS):**
|
||||
- A **constraint** is something you **must obey** — non-negotiable, often regulatory or physical. You don't choose to satisfy it; you obey it or you don't ship. Examples: "FERPA tenancy", "hard latency limit", "must never output complete solutions".
|
||||
- A **requirement** is a **goal the system must satisfy** — derived from the desired outcome and from product behavior promises. Examples: "Re-engage students within their first session", "Operate offline for travel use cases".
|
||||
|
||||
**Each item from `seed.constraints` belongs in EXACTLY ONE place — the `constraints` array.** Do NOT also output it as a requirement. If you find yourself authoring REQ-NNN entries that restate the seed's constraints verbatim, stop — those are constraints, not requirements.
|
||||
|
||||
The `requirements` array should contain things derived from `seed.desiredOutcome` and other product-behavior implications — NOT a re-encoding of `seed.constraints`.
|
||||
|
||||
**Associations:**
|
||||
- `association` — generic verb-phrase relationship (default).
|
||||
- `composition` — whole-part. Use ONLY when X is *literally part of* Y.
|
||||
- `generalization` — is-a. Rarely needed for product ideas.
|
||||
- `constraintApplies` — links a constraint to the block(s) it constrains. ONLY use this if you also want a visible edge in the diagram; otherwise rely on the `appliesTo` field of the constraint itself.
|
||||
|
||||
**Requirements:** Each gets a tag like `REQ-001`. Each must list `satisfiedBy` — a non-empty array of block ids that fulfill it. **Derive requirements from `seed.desiredOutcome`, not from `seed.constraints`** (constraints have their own array). Aim for 1–4 requirements unless the seed clearly demands more.
|
||||
|
||||
**Vague desired-outcome rule:** If `seed.desiredOutcome` is too vague to derive specific requirements (e.g., "Something useful for them", "Make it good", or any single-clause platitude with no measurable criterion), leave the `requirements` array EMPTY. Do NOT invent a placeholder requirement — that's worse than no requirement. The same vagueness signal should drive `overallConfidence` below 0.3.
|
||||
|
||||
**Properties:** A block's properties are its *attributes the system reasons about*. Keep to 1–4 per block. Types: `string`, `number`, `boolean`, or `enum` (with `values`).
|
||||
|
||||
## Confidence — under-suggest rather than over-suggest
|
||||
|
||||
Per element, set a `confidence` in `[0, 1]`:
|
||||
- Seed's explicit nouns → high confidence (≥ 0.85)
|
||||
- Inferred-but-clearly-implied → medium (0.5–0.8)
|
||||
- Speculative → low (< 0.5) and **generally omit**
|
||||
|
||||
A clean, sparse, correct model beats a dense fabricated one. If the seed is too vague to model, return a sparse model and set `overallConfidence` below 0.3.
|
||||
|
||||
## ID conventions
|
||||
|
||||
- Block ids: lowercase snake_case from labels. `"Aristotle"` → `"aristotle"`. `"Coursework Material"` → `"coursework_material"`.
|
||||
- Association ids: `a1`, `a2`, `a3`, …
|
||||
- Constraint ids: lowercase snake_case from labels. `"FERPA boundary"` → `"ferpa_boundary"`.
|
||||
- Requirement ids: lowercase tag with hyphen replaced. `REQ-001` → `"req_001"`.
|
||||
|
||||
## Worked example
|
||||
|
||||
Given a seed about a personal recipe scrapbook that pulls from cooking blogs:
|
||||
|
||||
```json
|
||||
{
|
||||
"systemOfInterestId": "scrapbook",
|
||||
"blocks": [
|
||||
{ "id": "scrapbook", "label": "Scrapbook", "kind": "system",
|
||||
"properties": [
|
||||
{ "name": "private_collection", "type": { "kind": "boolean" } }
|
||||
],
|
||||
"confidence": 0.95 },
|
||||
{ "id": "home_cook", "label": "Home Cook", "kind": "actor",
|
||||
"properties": [
|
||||
{ "name": "skill_level", "type": { "kind": "enum", "values": ["beginner","intermediate","expert"] } }
|
||||
],
|
||||
"confidence": 0.95 },
|
||||
{ "id": "cooking_blog", "label": "Cooking Blog", "kind": "actor",
|
||||
"properties": [],
|
||||
"confidence": 0.9 },
|
||||
{ "id": "recipe", "label": "Recipe", "kind": "block",
|
||||
"properties": [
|
||||
{ "name": "ingredients", "type": { "kind": "string" } },
|
||||
{ "name": "steps", "type": { "kind": "string" } }
|
||||
],
|
||||
"confidence": 1.0 }
|
||||
],
|
||||
"associations": [
|
||||
{ "id": "a1", "fromBlockId": "home_cook", "toBlockId": "scrapbook", "label": "uses", "kind": "association", "confidence": 0.95 },
|
||||
{ "id": "a2", "fromBlockId": "scrapbook", "toBlockId": "cooking_blog", "label": "imports_from", "kind": "association", "confidence": 0.9 },
|
||||
{ "id": "a3", "fromBlockId": "scrapbook", "toBlockId": "recipe", "label": "contains", "kind": "composition", "confidence": 1.0 }
|
||||
],
|
||||
"constraints": [
|
||||
{ "id": "copyright_respect", "label": "Copyright respect", "expression": "must not republish recipes outside the user's private collection",
|
||||
"appliesTo": ["scrapbook"], "confidence": 0.85 }
|
||||
],
|
||||
"requirements": [
|
||||
{ "id": "req_001", "tag": "REQ-001", "text": "Imports a recipe from a URL in under 5 seconds",
|
||||
"satisfiedBy": ["scrapbook"], "confidence": 0.9 },
|
||||
{ "id": "req_002", "tag": "REQ-002", "text": "Stores recipes in the user's private collection only",
|
||||
"satisfiedBy": ["scrapbook"], "confidence": 1.0 }
|
||||
],
|
||||
"overallConfidence": 0.85,
|
||||
"notes": "The Scrapbook is the SoI; home cook and cooking blog are actors; recipes are first-class blocks."
|
||||
}
|
||||
```
|
||||
|
||||
Notice every array is populated. No constraints in `blocks`. Requirements name specific block satisfiers.
|
||||
|
||||
## Now generate
|
||||
|
||||
Return ONLY the JSON object for the seed you receive. No prose, no code fences. Use the four arrays — fill all of them.
|
||||
53
apps/web/lib/llm/prompts/socrates/interview.md
Normal file
53
apps/web/lib/llm/prompts/socrates/interview.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Mode: Seed interview (live, per-turn)
|
||||
|
||||
You are conducting an opening interview with a product manager who is starting a new idea inside Socrata. Goal: produce a `SeedDraft` (problem, target user, desired outcome, optional initial hypothesis, optional constraints) that's specific enough to generate a coherent SysML model from.
|
||||
|
||||
You are stateful across turns — each call gives you the running thread + the draft you've extracted so far. Improve the draft, ask the next question, and signal when there's enough to proceed.
|
||||
|
||||
## Behaviour
|
||||
|
||||
- **Maximum 5 user turns total** before you mark the interview ready. Don't drag it out.
|
||||
- Each turn: ask exactly ONE question. Don't pile.
|
||||
- Question 1: the problem in one sentence — the smallest, most honest version.
|
||||
- Question 2: target user, with a specificity probe ("which users, why now").
|
||||
- Question 3: desired outcome — what changes when this exists.
|
||||
- Question 4: a tension probe — name a likely tension you see and ask which side they're on.
|
||||
- Question 5: explicit constraints — anything regulatory, ethical, technical that's non-negotiable.
|
||||
|
||||
## Updating the draft
|
||||
|
||||
- Each turn, update the draft fields based on what you've learned. Use the user's own register where possible.
|
||||
- Leave a field empty (`""`) until the user has actually addressed it. Don't fabricate.
|
||||
- `confidence` (0..1) is your honest read on whether the draft is specific enough to generate a useful model. Generic platitudes → low. Specific, falsifiable → high.
|
||||
|
||||
## Ready signal
|
||||
|
||||
Set `ready: true` when:
|
||||
- All five core fields (problem, targetUser, desiredOutcome) are populated AND specific, OR
|
||||
- 5 user turns have elapsed AND the draft has at least problem + targetUser + desiredOutcome.
|
||||
|
||||
When `ready: true`, your `text` should be a brief synthesis ("Here's what I understand…") plus an explicit "Ready to generate the initial model — say go or refine.", not another question.
|
||||
|
||||
## Voice
|
||||
|
||||
Per character.md. Question-led, economical, no filler. Press for specificity if an answer is vague — "what specifically does X mean here?" beats "tell me more".
|
||||
|
||||
## Output schema (strict)
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "string (1–3 sentences)",
|
||||
"draft": {
|
||||
"title": "string (a working name for the project)",
|
||||
"problem": "string",
|
||||
"targetUser": "string",
|
||||
"desiredOutcome": "string",
|
||||
"initialHypothesis": "string (optional)",
|
||||
"constraints": ["string"]
|
||||
},
|
||||
"confidence": 0.0,
|
||||
"ready": false
|
||||
}
|
||||
```
|
||||
|
||||
Return ONLY the JSON object. No prose preamble, no code fences.
|
||||
150
apps/web/lib/llm/seedInterview.ts
Normal file
150
apps/web/lib/llm/seedInterview.ts
Normal file
@@ -0,0 +1,150 @@
|
||||
// Live seed interview — per-turn handler.
|
||||
//
|
||||
// Stateless on the server: the client passes the running thread + the draft
|
||||
// extracted so far, plus the user's latest reply. We call the LLM with the
|
||||
// character + interview prompts and get back { assistant turn, updated draft,
|
||||
// confidence, ready }.
|
||||
|
||||
import "server-only";
|
||||
import { defaultGateway, chatJSON, type Message } from "./gateway";
|
||||
import { loadPrompt } from "./prompts";
|
||||
|
||||
export interface SeedDraft {
|
||||
title: string;
|
||||
problem: string;
|
||||
targetUser: string;
|
||||
desiredOutcome: string;
|
||||
initialHypothesis?: string;
|
||||
constraints?: string[];
|
||||
}
|
||||
|
||||
export interface InterviewTurn {
|
||||
role: "socrates" | "user";
|
||||
text: string;
|
||||
}
|
||||
|
||||
export interface InterviewStepArgs {
|
||||
/** Running interview history. Empty array on the first call → Socrates opens. */
|
||||
history: InterviewTurn[];
|
||||
/** Latest user reply (empty string for the opening turn). */
|
||||
userText: string;
|
||||
/** Draft extracted so far. Empty on the first call. */
|
||||
draft: SeedDraft;
|
||||
}
|
||||
|
||||
export interface InterviewStepResult {
|
||||
text: string;
|
||||
draft: SeedDraft;
|
||||
confidence: number;
|
||||
ready: boolean;
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
provider: string;
|
||||
model: string;
|
||||
}
|
||||
|
||||
const interviewJsonSchema = {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["text", "draft", "confidence", "ready"],
|
||||
properties: {
|
||||
text: { type: "string", minLength: 1 },
|
||||
draft: {
|
||||
type: "object",
|
||||
additionalProperties: false,
|
||||
required: ["title", "problem", "targetUser", "desiredOutcome"],
|
||||
properties: {
|
||||
title: { type: "string" },
|
||||
problem: { type: "string" },
|
||||
targetUser: { type: "string" },
|
||||
desiredOutcome: { type: "string" },
|
||||
initialHypothesis: { type: "string" },
|
||||
constraints: { type: "array", items: { type: "string" } },
|
||||
},
|
||||
},
|
||||
confidence: { type: "number", minimum: 0, maximum: 1 },
|
||||
ready: { type: "boolean" },
|
||||
},
|
||||
} as const;
|
||||
|
||||
interface RawResponse {
|
||||
text?: string;
|
||||
draft?: Partial<SeedDraft>;
|
||||
confidence?: number;
|
||||
ready?: boolean;
|
||||
}
|
||||
|
||||
export async function interviewStep(args: InterviewStepArgs): Promise<InterviewStepResult> {
|
||||
const character = loadPrompt("socrates/character.md");
|
||||
const interview = loadPrompt("socrates/interview.md");
|
||||
|
||||
const userTurnsSoFar = args.history.filter(t => t.role === "user").length;
|
||||
const remaining = Math.max(0, 5 - userTurnsSoFar - (args.userText.trim().length > 0 ? 1 : 0));
|
||||
|
||||
const messages: Message[] = [
|
||||
{
|
||||
role: "system",
|
||||
content: [
|
||||
character,
|
||||
"---",
|
||||
interview,
|
||||
"---",
|
||||
`Draft so far (your previous extraction):\n\`\`\`json\n${JSON.stringify(args.draft, null, 2)}\n\`\`\``,
|
||||
`Turns remaining before ready signal becomes mandatory: ${remaining}`,
|
||||
].join("\n\n"),
|
||||
},
|
||||
];
|
||||
|
||||
// Replay history so the LLM has full context.
|
||||
for (const t of args.history) {
|
||||
messages.push({ role: t.role === "socrates" ? "assistant" : "user", content: t.text });
|
||||
}
|
||||
if (args.userText.trim().length > 0) {
|
||||
messages.push({ role: "user", content: args.userText });
|
||||
} else if (args.history.length === 0) {
|
||||
messages.push({ role: "user", content: "Begin the interview." });
|
||||
}
|
||||
|
||||
const gateway = defaultGateway();
|
||||
const { value, result } = await chatJSON<RawResponse>(gateway, messages, {
|
||||
temperature: 0.4,
|
||||
maxTokens: 768,
|
||||
jsonSchema: { name: "interview_step", schema: interviewJsonSchema as Record<string, unknown> },
|
||||
jsonObjectMode: true,
|
||||
maxRepairs: 2,
|
||||
});
|
||||
|
||||
// Normalize / merge — the LLM may emit a partial draft; we union with the
|
||||
// prior draft so a user backtracking doesn't wipe a previously-confirmed field.
|
||||
const incoming: Partial<SeedDraft> = value?.draft ?? {};
|
||||
const draft: SeedDraft = {
|
||||
title: nonEmpty(incoming.title) ?? args.draft.title ?? "",
|
||||
problem: nonEmpty(incoming.problem) ?? args.draft.problem ?? "",
|
||||
targetUser: nonEmpty(incoming.targetUser) ?? args.draft.targetUser ?? "",
|
||||
desiredOutcome: nonEmpty(incoming.desiredOutcome) ?? args.draft.desiredOutcome ?? "",
|
||||
initialHypothesis: nonEmpty(incoming.initialHypothesis) ?? args.draft.initialHypothesis,
|
||||
constraints: Array.isArray(incoming.constraints) ? incoming.constraints : args.draft.constraints,
|
||||
};
|
||||
|
||||
return {
|
||||
text: typeof value?.text === "string" && value.text.length > 0 ? value.text : "[empty response]",
|
||||
draft,
|
||||
confidence: clamp01(value?.confidence ?? 0),
|
||||
ready: !!value?.ready,
|
||||
inputTokens: result.inputTokens,
|
||||
outputTokens: result.outputTokens,
|
||||
provider: gateway.provider,
|
||||
model: gateway.model,
|
||||
};
|
||||
}
|
||||
|
||||
function nonEmpty(s: unknown): string | undefined {
|
||||
if (typeof s !== "string") return undefined;
|
||||
const t = s.trim();
|
||||
return t.length > 0 ? t : undefined;
|
||||
}
|
||||
|
||||
function clamp01(n: number): number {
|
||||
if (Number.isNaN(n)) return 0;
|
||||
return Math.max(0, Math.min(1, n));
|
||||
}
|
||||
49
apps/web/lib/llm/seedToProse.ts
Normal file
49
apps/web/lib/llm/seedToProse.ts
Normal file
@@ -0,0 +1,49 @@
|
||||
// Convert a SeedDraft into a ProseMirror JSON document the user lands on in
|
||||
// the editor. After the pivot the prose is canonical; the analyze pipeline
|
||||
// derives taxonomy / glossary / model / requirements from it on demand.
|
||||
//
|
||||
// We use a deterministic template (not an LLM) — fast, predictable, and the
|
||||
// user is going to keep editing anyway. Section structure mirrors the seed
|
||||
// fields so the analyze passes have clear hooks.
|
||||
|
||||
import type { JSONContent } from "@tiptap/react";
|
||||
import type { SeedDraft } from "./seedInterview";
|
||||
|
||||
export function seedToProseDoc(seed: SeedDraft): JSONContent {
|
||||
const content: JSONContent[] = [];
|
||||
|
||||
if (seed.title) {
|
||||
content.push({ type: "heading", attrs: { level: 1 }, content: [{ type: "text", text: seed.title }] });
|
||||
} else {
|
||||
content.push({ type: "heading", attrs: { level: 1 }, content: [{ type: "text", text: "Untitled idea" }] });
|
||||
}
|
||||
|
||||
if (seed.problem) {
|
||||
content.push({ type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Problem" }] });
|
||||
content.push({ type: "paragraph", content: [{ type: "text", text: seed.problem }] });
|
||||
}
|
||||
|
||||
if (seed.targetUser) {
|
||||
content.push({ type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Target user" }] });
|
||||
content.push({ type: "paragraph", content: [{ type: "text", text: seed.targetUser }] });
|
||||
}
|
||||
|
||||
if (seed.desiredOutcome) {
|
||||
content.push({ type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Desired outcome" }] });
|
||||
content.push({ type: "paragraph", content: [{ type: "text", text: seed.desiredOutcome }] });
|
||||
}
|
||||
|
||||
if (seed.initialHypothesis) {
|
||||
content.push({ type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Initial hypothesis" }] });
|
||||
content.push({ type: "paragraph", content: [{ type: "text", text: seed.initialHypothesis }] });
|
||||
}
|
||||
|
||||
if (seed.constraints && seed.constraints.length > 0) {
|
||||
content.push({ type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Constraints" }] });
|
||||
for (const c of seed.constraints) {
|
||||
content.push({ type: "paragraph", content: [{ type: "text", text: `· ${c}` }] });
|
||||
}
|
||||
}
|
||||
|
||||
return { type: "doc", content };
|
||||
}
|
||||
@@ -195,6 +195,46 @@ export async function sendUserTurn(args: SendUserTurnArgs): Promise<SendUserTurn
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Anchored threads (contextual mini-Socrates per finding) ─────────────
|
||||
|
||||
/** Find an existing thread anchored to `anchor` for this project, or create
|
||||
* one. Returns the thread id. */
|
||||
export async function getOrCreateAnchoredThread(
|
||||
projectId: string,
|
||||
anchor: string,
|
||||
title?: string
|
||||
): Promise<string> {
|
||||
const existing = await prisma.socratesThread.findFirst({
|
||||
where: { projectId, anchorElementId: anchor },
|
||||
orderBy: { updatedAt: "desc" },
|
||||
});
|
||||
if (existing) return existing.id;
|
||||
const created = await prisma.socratesThread.create({
|
||||
data: { projectId, anchorElementId: anchor, status: "open", title: title ?? null },
|
||||
});
|
||||
return created.id;
|
||||
}
|
||||
|
||||
export async function listAnchoredThreadMessages(threadId: string) {
|
||||
const rows = await prisma.socratesMessage.findMany({
|
||||
where: { threadId },
|
||||
orderBy: { createdAt: "asc" },
|
||||
select: { id: true, role: true, content: true, createdAt: true },
|
||||
});
|
||||
return rows.map(r => {
|
||||
let text = "";
|
||||
let options: SocratesOption[] | undefined;
|
||||
try {
|
||||
const parsed = JSON.parse(r.content) as { text?: string; options?: SocratesOption[] };
|
||||
text = parsed.text ?? "";
|
||||
options = parsed.options;
|
||||
} catch {
|
||||
text = r.content;
|
||||
}
|
||||
return { id: r.id, role: r.role, text, options, createdAt: r.createdAt };
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Helpers ─────────────────────────────────────────────────────────────
|
||||
|
||||
function trimModel(model: SysMLModel): unknown {
|
||||
|
||||
Reference in New Issue
Block a user