@compilr-dev/factory 0.1.13 → 0.1.14

package/dist/research-model/tools.js

@@ -0,0 +1,586 @@
+/**
+ * Research Model Tools
+ *
+ * research_model_get — scoped reads of the Research Model
+ * research_model_update — semantic operations on the model
+ * research_model_validate — check model health
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { ResearchModelStore } from './persistence.js';
+import { applyResearchOperation } from './operations.js';
+import { validateResearchModel } from './schema.js';
+import { createDefaultResearchModel } from './defaults.js';
+// =============================================================================
+// Helpers
+// =============================================================================
+function getProjectId(config, inputProjectId) {
+    const projectId = inputProjectId ?? config.context.currentProjectId;
+    if (!projectId) {
+        throw new Error('No active project. Use project_create or project_get first.');
+    }
+    return projectId;
+}
+function createStore(config, projectId) {
+    return new ResearchModelStore({
+        documents: config.context.documents,
+        projectId,
+    });
+}
+function createSummary(model) {
+    return {
+        title: model.title,
+        citationStyle: model.citationStyle,
+        sectionCount: model.sections.length,
+        sourceCount: model.sources.length,
+        questionCount: model.researchQuestions.length,
+        sections: model.sections.map((s) => ({
+            id: s.id,
+            title: s.title,
+            status: s.status,
+            claimCount: s.claims.length,
+            parentId: s.parentId,
+        })),
+        sources: model.sources.map((s) => ({
+            id: s.id,
+            citeKey: s.citeKey,
+            title: s.citation.title,
+            analyzed: s.analyzed,
+        })),
+        questions: model.researchQuestions.map((q) => ({
+            id: q.id,
+            question: q.question,
+            status: q.status,
+            sectionCount: q.sectionRefs.length,
+        })),
+        revision: model.meta.revision,
+    };
+}
+function createResearchModelGetTool(config) {
+    return defineTool({
+        name: 'research_model_get',
+        description: 'Read the Research Model. Supports scoped reads by section or overview.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    enum: ['overview', 'sections', 'sources', 'claims', 'questions', 'full'],
+                    description: 'Which part to return. "overview" for summary, "sections" for all sections, "sources" for source registry, "claims" for all claims across sections, "questions" for research questions, omit or "full" for everything.',
+                },
+                sectionId: {
+                    type: 'string',
+                    description: 'Return only this section (by ID). Overrides scope.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID. Uses active project if omitted.',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = getProjectId(config, input.project_id);
+                const store = createStore(config, projectId);
+                const model = await store.get();
+                if (!model) {
+                    return createSuccessResult({
+                        exists: false,
+                        message: 'No Research Model found. Use research_model_update with an operation to start building one (e.g., set_title, section_add, question_add).',
+                    });
+                }
+                // Section-scoped read
+                if (input.sectionId) {
+                    const section = model.sections.find((s) => s.id === input.sectionId);
+                    if (!section) {
+                        return createErrorResult(`Section "${input.sectionId}" not found`);
+                    }
+                    return createSuccessResult({ section, meta: model.meta });
+                }
+                // Scope-based read
+                switch (input.scope) {
+                    case 'overview':
+                        return createSuccessResult(createSummary(model));
+                    case 'sections':
+                        return createSuccessResult({ sections: model.sections, meta: model.meta });
+                    case 'sources':
+                        return createSuccessResult({ sources: model.sources, meta: model.meta });
+                    case 'claims': {
+                        const allClaims = model.sections.flatMap((s) => s.claims.map((c) => ({ ...c, sectionId: s.id, sectionTitle: s.title })));
+                        return createSuccessResult({ claims: allClaims, meta: model.meta });
+                    }
+                    case 'questions':
+                        return createSuccessResult({
+                            researchQuestions: model.researchQuestions,
+                            meta: model.meta,
+                        });
+                    default:
+                        return createSuccessResult(model);
+                }
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+        readonly: true,
+    });
+}
+const ALL_OPS = [
+    // Section
+    'section_add',
+    'section_update',
+    'section_remove',
+    'section_reorder',
+    'section_move',
+    // Claim
+    'claim_add',
+    'claim_update',
+    'claim_remove',
+    'claim_link_source',
+    'claim_unlink_source',
+    // Source
+    'source_add',
+    'source_update',
+    'source_remove',
+    // Question
+    'question_add',
+    'question_update',
+    'question_remove',
+    'question_link_section',
+    // Metadata
+    'set_title',
+    'set_abstract',
+    'set_citation_style',
+    'set_keywords',
+    'set_methodology',
+    'set_authors',
+    'set_target_journal',
+];
+function createResearchModelUpdateTool(config) {
+    return defineTool({
+        name: 'research_model_update',
+        description: 'Apply a semantic operation to the Research Model. Auto-creates if none exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                op: {
+                    type: 'string',
+                    enum: [...ALL_OPS],
+                    description: 'The operation to perform.',
+                },
+                revision: {
+                    type: 'number',
+                    description: 'Expected current revision for optimistic locking. Optional.',
+                },
+                sectionId: {
+                    type: 'string',
+                    description: 'Section ID (for section_update, section_remove, section_move, claim ops).',
+                },
+                section: {
+                    oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }],
+                    description: 'Section object for section_add. Must include "title". Optional: purpose, order, parentId, status, targetWordCount.',
+                },
+                newParentId: {
+                    type: 'string',
+                    description: 'New parent section ID for section_move. Omit for top-level.',
+                },
+                order: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Section ID order for section_reorder.',
+                },
+                force: {
+                    type: 'boolean',
+                    description: 'Force removal with cascading cleanup.',
+                },
+                claimId: {
+                    type: 'string',
+                    description: 'Claim ID (for claim_update, claim_remove, claim_link/unlink_source).',
+                },
+                claim: {
+                    oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }],
+                    description: 'Claim object for claim_add. Must include "statement". Optional: evidenceStrength, type.',
+                },
+                sourceRef: {
+                    type: 'object',
+                    additionalProperties: true,
+                    description: 'Source reference for claim_link_source. Must include "sourceId". Optional: location, relevance.',
+                },
+                relation: {
+                    type: 'string',
+                    enum: ['supporting', 'contradicting'],
+                    description: 'Relation type for claim_link_source.',
+                },
+                sourceId: {
+                    type: 'string',
+                    description: 'Source ID (for source_update, source_remove, claim_unlink_source).',
+                },
+                source: {
+                    type: 'object',
+                    additionalProperties: true,
+                    description: 'Source object for source_add. Must include "citeKey" and "citation" (with title, authors, year, type).',
+                },
+                questionId: {
+                    type: 'string',
+                    description: 'Question ID (for question_update, question_remove, question_link_section).',
+                },
+                question: {
+                    oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }],
+                    description: 'Question object for question_add. Must include "question" text.',
+                },
+                unlink: {
+                    type: 'boolean',
+                    description: 'If true, question_link_section removes the link instead of adding it.',
+                },
+                updates: {
+                    oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }],
+                    description: 'Partial updates for section_update, claim_update, source_update, question_update.',
+                },
+                // Metadata shortcuts
+                title: { type: 'string', description: 'Paper title for set_title.' },
+                abstract: { type: 'string', description: 'Abstract text for set_abstract.' },
+                citationStyle: {
+                    type: 'string',
+                    enum: ['apa', 'mla', 'chicago', 'ieee', 'harvard'],
+                    description: 'Citation style for set_citation_style.',
+                },
+                keywords: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Keywords for set_keywords.',
+                },
+                methodology: { type: 'string', description: 'Methodology for set_methodology.' },
+                authors: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Authors for set_authors.',
+                },
+                targetJournal: { type: 'string', description: 'Target journal for set_target_journal.' },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID. Uses active project if omitted.',
+                },
+            },
+            required: ['op'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = getProjectId(config, input.project_id);
+                const store = createStore(config, projectId);
+                let model = await store.get();
+                if (!model) {
+                    model = createDefaultResearchModel();
+                }
+                // Optimistic locking
+                if (input.revision !== undefined && input.revision !== model.meta.revision) {
+                    return createErrorResult(`Revision conflict: expected ${String(input.revision)}, current is ${String(model.meta.revision)}. Re-read the model and retry.`);
+                }
+                const operation = buildOperation(input);
+                const updated = applyResearchOperation(model, operation);
+                // Validate (only block on errors, not warnings)
+                const validation = validateResearchModel(updated);
+                if (!validation.valid) {
+                    const msgs = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+                    return createErrorResult(`Operation would produce invalid model: ${msgs}`);
+                }
+                await store.save(updated);
+                return createSuccessResult({
+                    op: input.op,
+                    revision: updated.meta.revision,
+                    message: `Operation "${input.op}" applied successfully.`,
+                    warnings: validation.warnings.length > 0
+                        ? validation.warnings.map((w) => `${w.path}: ${w.message}`)
+                        : undefined,
+                });
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}
+// =============================================================================
+// Build Operation from flat input
+// =============================================================================
+function coerceToObject(value) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not valid JSON
+        }
+    }
+    return null;
+}
+function buildOperation(input) {
+    switch (input.op) {
+        // ── Section ops ────────────────────────────────────────────────────────
+        case 'section_add': {
+            const section = coerceToObject(input.section);
+            if (!section) {
+                throw new Error('section_add requires "section" object with at least "title".');
+            }
+            return {
+                op: 'section_add',
+                section: section,
+            };
+        }
+        case 'section_update': {
+            if (!input.sectionId)
+                throw new Error('section_update requires "sectionId".');
+            const updates = coerceToObject(input.updates);
+            if (!updates)
+                throw new Error('section_update requires "updates" object.');
+            return {
+                op: 'section_update',
+                sectionId: input.sectionId,
+                updates,
+            };
+        }
+        case 'section_remove':
+            if (!input.sectionId)
+                throw new Error('section_remove requires "sectionId".');
+            return {
+                op: 'section_remove',
+                sectionId: input.sectionId,
+                force: input.force,
+            };
+        case 'section_reorder':
+            if (!input.order)
+                throw new Error('section_reorder requires "order" array.');
+            return { op: 'section_reorder', order: input.order };
+        case 'section_move':
+            if (!input.sectionId)
+                throw new Error('section_move requires "sectionId".');
+            return {
+                op: 'section_move',
+                sectionId: input.sectionId,
+                newParentId: input.newParentId,
+            };
+        // ── Claim ops ──────────────────────────────────────────────────────────
+        case 'claim_add': {
+            if (!input.sectionId)
+                throw new Error('claim_add requires "sectionId".');
+            const claim = coerceToObject(input.claim);
+            if (!claim)
+                throw new Error('claim_add requires "claim" object with at least "statement".');
+            return { op: 'claim_add', sectionId: input.sectionId, claim };
+        }
+        case 'claim_update': {
+            if (!input.sectionId)
+                throw new Error('claim_update requires "sectionId".');
+            if (!input.claimId)
+                throw new Error('claim_update requires "claimId".');
+            const updates = coerceToObject(input.updates);
+            if (!updates)
+                throw new Error('claim_update requires "updates" object.');
+            return {
+                op: 'claim_update',
+                sectionId: input.sectionId,
+                claimId: input.claimId,
+                updates,
+            };
+        }
+        case 'claim_remove':
+            if (!input.sectionId)
+                throw new Error('claim_remove requires "sectionId".');
+            if (!input.claimId)
+                throw new Error('claim_remove requires "claimId".');
+            return {
+                op: 'claim_remove',
+                sectionId: input.sectionId,
+                claimId: input.claimId,
+            };
+        case 'claim_link_source': {
+            if (!input.sectionId)
+                throw new Error('claim_link_source requires "sectionId".');
+            if (!input.claimId)
+                throw new Error('claim_link_source requires "claimId".');
+            const sourceRef = coerceToObject(input.sourceRef);
+            if (!sourceRef)
+                throw new Error('claim_link_source requires "sourceRef" object with "sourceId".');
+            if (!sourceRef.sourceId)
+                throw new Error('claim_link_source sourceRef must include "sourceId".');
+            if (!input.relation)
+                throw new Error('claim_link_source requires "relation" ("supporting" or "contradicting").');
+            return {
+                op: 'claim_link_source',
+                sectionId: input.sectionId,
+                claimId: input.claimId,
+                sourceRef: sourceRef,
+                relation: input.relation,
+            };
+        }
+        case 'claim_unlink_source':
+            if (!input.sectionId)
+                throw new Error('claim_unlink_source requires "sectionId".');
+            if (!input.claimId)
+                throw new Error('claim_unlink_source requires "claimId".');
+            if (!input.sourceId)
+                throw new Error('claim_unlink_source requires "sourceId".');
+            return {
+                op: 'claim_unlink_source',
+                sectionId: input.sectionId,
+                claimId: input.claimId,
+                sourceId: input.sourceId,
+            };
+        // ── Source ops ─────────────────────────────────────────────────────────
+        case 'source_add': {
+            const source = coerceToObject(input.source);
+            if (!source) {
+                throw new Error('source_add requires "source" object with "citeKey" and "citation".');
+            }
+            return { op: 'source_add', source };
+        }
+        case 'source_update': {
+            if (!input.sourceId)
+                throw new Error('source_update requires "sourceId".');
+            const updates = coerceToObject(input.updates);
+            if (!updates)
+                throw new Error('source_update requires "updates" object.');
+            return { op: 'source_update', sourceId: input.sourceId, updates };
+        }
+        case 'source_remove':
+            if (!input.sourceId)
+                throw new Error('source_remove requires "sourceId".');
+            return {
+                op: 'source_remove',
+                sourceId: input.sourceId,
+                force: input.force,
+            };
+        // ── Question ops ───────────────────────────────────────────────────────
+        case 'question_add': {
+            const question = coerceToObject(input.question);
+            if (!question) {
+                // Allow string shorthand: { op: "question_add", question: "What is...?" }
+                if (typeof input.question === 'string') {
+                    return {
+                        op: 'question_add',
+                        question: { question: input.question },
+                    };
+                }
+                throw new Error('question_add requires "question" object with "question" text.');
+            }
+            return { op: 'question_add', question };
+        }
+        case 'question_update': {
+            if (!input.questionId)
+                throw new Error('question_update requires "questionId".');
+            const updates = coerceToObject(input.updates);
+            if (!updates)
+                throw new Error('question_update requires "updates" object.');
+            return {
+                op: 'question_update',
+                questionId: input.questionId,
+                updates,
+            };
+        }
+        case 'question_remove':
+            if (!input.questionId)
+                throw new Error('question_remove requires "questionId".');
+            return { op: 'question_remove', questionId: input.questionId };
+        case 'question_link_section':
+            if (!input.questionId)
+                throw new Error('question_link_section requires "questionId".');
+            if (!input.sectionId)
+                throw new Error('question_link_section requires "sectionId".');
+            return {
+                op: 'question_link_section',
+                questionId: input.questionId,
+                sectionId: input.sectionId,
+                unlink: input.unlink,
+            };
+        // ── Metadata ops ───────────────────────────────────────────────────────
+        case 'set_title':
+            if (!input.title)
+                throw new Error('set_title requires "title".');
+            return { op: 'set_title', title: input.title };
+        case 'set_abstract':
+            return { op: 'set_abstract', abstract: input.abstract ?? '' };
+        case 'set_citation_style':
+            if (!input.citationStyle)
+                throw new Error('set_citation_style requires "citationStyle".');
+            return {
+                op: 'set_citation_style',
+                citationStyle: input.citationStyle,
+            };
+        case 'set_keywords':
+            if (!input.keywords)
+                throw new Error('set_keywords requires "keywords" array.');
+            return { op: 'set_keywords', keywords: input.keywords };
+        case 'set_methodology':
+            return {
+                op: 'set_methodology',
+                methodology: input.methodology ?? '',
+            };
+        case 'set_authors':
+            if (!input.authors)
+                throw new Error('set_authors requires "authors" array.');
+            return { op: 'set_authors', authors: input.authors };
+        case 'set_target_journal':
+            return {
+                op: 'set_target_journal',
+                targetJournal: input.targetJournal ?? '',
+            };
+        default:
+            throw new Error(`Unknown operation: ${input.op}`);
+    }
+}
+function createResearchModelValidateTool(config) {
+    return defineTool({
+        name: 'research_model_validate',
+        description: 'Validate the Research Model. Returns structural errors and research-quality warnings (unsupported claims, orphan sources, etc.).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID. Uses active project if omitted.',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = getProjectId(config, input.project_id);
+                const store = createStore(config, projectId);
+                const model = await store.get();
+                if (!model) {
+                    return createSuccessResult({
+                        valid: false,
+                        errors: [{ path: '', message: 'No Research Model found' }],
+                        warnings: [],
+                    });
+                }
+                const result = validateResearchModel(model);
+                return createSuccessResult({
+                    valid: result.valid,
+                    errors: result.errors,
+                    warnings: result.warnings,
+                    revision: model.meta.revision,
+                });
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+        readonly: true,
+    });
+}
+// =============================================================================
+// Public API
+// =============================================================================
+export function createResearchModelTools(config) {
+    return [
+        createResearchModelGetTool(config),
+        createResearchModelUpdateTool(config),
+        createResearchModelValidateTool(config),
+    ];
+}