@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/research/services/documentation.js

@@ -0,0 +1,269 @@
+/**
+ * Documentation service for generating structured paper summaries
+ *
+ * @module research/services/documentation
+ */
+/**
+ * Documentation service for generating summaries and notes
+ */
+export class DocumentationService {
+    constructor(_config = {}) {
+        // Config values will be used when stub methods are fully implemented
+    }
+    /**
+     * Generate structured summary from paper
+     * Note: Full implementation would use LLM or PDF parsing
+     */
+    async summarize(_paperPath) {
+        // Stub implementation - full version would parse PDF
+        return {
+            refId: 'REF-XXX',
+            oneSentence: 'Paper summary to be generated from PDF content',
+            contributions: [
+                'Contribution 1 (extracted from paper)',
+                'Contribution 2 (extracted from paper)',
+                'Contribution 3 (extracted from paper)',
+            ],
+            methodology: 'Methodology description extracted from paper',
+            findings: [
+                'Finding 1 with metrics',
+                'Finding 2 with metrics',
+                'Finding 3 with metrics',
+            ],
+            limitations: [
+                'Limitation 1 acknowledged by authors',
+                'Limitation 2 identified',
+            ],
+            aiwgRelevance: {
+                applicability: 'direct',
+                componentsAffected: ['agents', 'workflows'],
+                implementationPriority: 'round-2',
+            },
+        };
+    }
+    /**
+     * Extract claims from paper
+     * Note: Full implementation would use NLP/LLM
+     */
+    async extractClaims(_paperPath) {
+        // Stub implementation - full version would use NLP
+        return [
+            {
+                id: 'claim-001',
+                statement: 'Example claim extracted from paper',
+                type: 'empirical',
+                evidence: [
+                    {
+                        sourceRefId: 'REF-XXX',
+                        pageNumbers: '5-6',
+                        quote: 'Direct quote supporting claim',
+                        context: 'Context around the claim',
+                    },
+                ],
+                confidence: 'high',
+                tags: ['tag1', 'tag2'],
+            },
+        ];
+    }
+    /**
+     * Generate Zettelkasten literature note
+     */
+    async generateNote(paper, summary) {
+        const authors = paper.authors.map((a) => a.name).join(', ');
+        const note = `# ${summary.refId}: ${paper.title}
+
+**Authors:** ${authors}
+**Year:** ${paper.year}
+**Source:** ${paper.venue || 'Unknown'}
+**DOI:** ${paper.doi || 'N/A'}
+**arXiv:** ${paper.arxivId || 'N/A'}
+
+## Summary
+
+${summary.oneSentence}
+
+## Key Contributions
+
+${summary.contributions.map((c) => `- ${c}`).join('\n')}
+
+## Methodology
+
+${summary.methodology}
+
+## Main Findings
+
+${summary.findings.map((f) => `- ${f}`).join('\n')}
+
+## Limitations
+
+${summary.limitations.map((l) => `- ${l}`).join('\n')}
+
+## AIWG Relevance
+
+**Applicability:** ${summary.aiwgRelevance.applicability}
+
+**Components Affected:**
+${summary.aiwgRelevance.componentsAffected.map((c) => `- ${c}`).join('\n')}
+
+**Implementation Priority:** ${summary.aiwgRelevance.implementationPriority}
+
+## References
+
+- Source: ${paper.source}
+- Retrieved: ${paper.retrievedAt}
+${paper.pdfUrl ? `- PDF: ${paper.pdfUrl}` : ''}
+
+## Citations
+
+To cite this paper:
+
+\`\`\`
+${this.generateCitation(paper)}
+\`\`\`
+
+## Notes
+
+[Add personal notes and connections here]
+
+## Tags
+
+#research #${summary.refId.toLowerCase()} ${summary.aiwgRelevance.componentsAffected.map((c) => `#${c}`).join(' ')}
+`;
+        return note;
+    }
+    /**
+     * Assess GRADE quality level
+     */
+    async assessGRADE(source) {
+        const paper = source.paper;
+        // Determine starting quality based on study type
+        const startingQuality = this.determineStartingQuality(paper);
+        const ratingUp = [];
+        const ratingDown = [];
+        // Factors that could increase quality
+        if (paper.citationCount && paper.citationCount > 100) {
+            ratingUp.push({
+                factor: 'Large citation count',
+                description: `Highly cited (${paper.citationCount} citations) indicates impact`,
+            });
+        }
+        // Factors that could decrease quality
+        if (paper.type === 'preprint') {
+            ratingDown.push({
+                factor: 'Non-peer-reviewed',
+                description: 'Preprint not yet peer reviewed',
+            });
+        }
+        if (!paper.abstract) {
+            ratingDown.push({
+                factor: 'Missing abstract',
+                description: 'Incomplete metadata reduces confidence',
+            });
+        }
+        // Calculate final level
+        let level = startingQuality;
+        // Adjust based on factors (simplified)
+        if (ratingDown.length > ratingUp.length) {
+            level = this.downgradeLevel(level);
+        }
+        else if (ratingUp.length > 0 && ratingDown.length === 0) {
+            level = this.upgradeLevel(level);
+        }
+        const justification = this.buildJustification(startingQuality, level, ratingUp, ratingDown);
+        return {
+            level,
+            startingQuality,
+            ratingUp,
+            ratingDown,
+            justification,
+        };
+    }
+    /**
+     * Determine starting GRADE quality based on publication type
+     */
+    determineStartingQuality(paper) {
+        if (paper.type === 'journal') {
+            return 'HIGH';
+        }
+        if (paper.type === 'conference') {
+            return 'HIGH';
+        }
+        if (paper.type === 'preprint') {
+            return 'MODERATE';
+        }
+        if (paper.type === 'thesis') {
+            return 'MODERATE';
+        }
+        return 'LOW';
+    }
+    /**
+     * Downgrade GRADE level
+     */
+    downgradeLevel(level) {
+        const levels = ['HIGH', 'MODERATE', 'LOW', 'VERY_LOW'];
+        const index = levels.indexOf(level);
+        if (index < levels.length - 1) {
+            return levels[index + 1];
+        }
+        return level;
+    }
+    /**
+     * Upgrade GRADE level
+     */
+    upgradeLevel(level) {
+        const levels = ['HIGH', 'MODERATE', 'LOW', 'VERY_LOW'];
+        const index = levels.indexOf(level);
+        if (index > 0) {
+            return levels[index - 1];
+        }
+        return level;
+    }
+    /**
+     * Build GRADE justification text
+     */
+    buildJustification(startingQuality, finalLevel, ratingUp, ratingDown) {
+        let text = `Starting quality: ${startingQuality} (based on publication type). `;
+        if (ratingUp.length > 0) {
+            text += `Quality increased due to: ${ratingUp.map((r) => r.factor).join(', ')}. `;
+        }
+        if (ratingDown.length > 0) {
+            text += `Quality decreased due to: ${ratingDown.map((r) => r.factor).join(', ')}. `;
+        }
+        text += `Final assessment: ${finalLevel}.`;
+        return text;
+    }
+    /**
+     * Generate citation in APA format
+     */
+    generateCitation(paper) {
+        const authors = this.formatAuthorsAPA(paper.authors.map((a) => a.name));
+        const year = paper.year || 'n.d.';
+        const title = paper.title;
+        const venue = paper.venue || '';
+        const doi = paper.doi ? `https://doi.org/${paper.doi}` : '';
+        let citation = `${authors} (${year}). ${title}.`;
+        if (venue) {
+            citation += ` ${venue}.`;
+        }
+        if (doi) {
+            citation += ` ${doi}`;
+        }
+        return citation;
+    }
+    /**
+     * Format authors in APA style
+     */
+    formatAuthorsAPA(authors) {
+        if (authors.length === 0)
+            return 'Unknown';
+        if (authors.length === 1)
+            return authors[0];
+        if (authors.length === 2)
+            return `${authors[0]} & ${authors[1]}`;
+        // More than 2 authors
+        const lastAuthor = authors[authors.length - 1];
+        const otherAuthors = authors.slice(0, -1).join(', ');
+        return `${otherAuthors}, & ${lastAuthor}`;
+    }
+}
+//# sourceMappingURL=documentation.js.map

package/dist/src/research/services/index.js

@@ -0,0 +1,14 @@
+/**
+ * Research Framework Services
+ *
+ * @module research/services
+ */
+export * from './types.js';
+export * from './discovery.js';
+export * from './acquisition.js';
+export * from './documentation.js';
+export * from './citation.js';
+export * from './quality.js';
+export * from './archival.js';
+export * from './provenance.js';
+//# sourceMappingURL=index.js.map

package/dist/src/research/services/provenance.js

@@ -0,0 +1,279 @@
+/**
+ * Provenance service for W3C PROV tracking
+ *
+ * @module research/services/provenance
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+/**
+ * Provenance service for W3C PROV-compliant tracking
+ */
+export class ProvenanceService {
+    recordsDir;
+    autoPersist;
+    records;
+    constructor(config = {}) {
+        this.recordsDir = config.recordsDir || '.aiwg/research/provenance/records';
+        this.autoPersist = config.autoPersist !== false;
+        this.records = new Map();
+    }
+    /**
+     * Record a provenance activity
+     */
+    async recordActivity(activity) {
+        const recordId = this.generateRecordId();
+        const timestamp = new Date().toISOString();
+        // Create entity for each output
+        const entities = activity.outputs.map((outputId) => ({
+            id: outputId,
+            type: 'artifact',
+            attributes: {},
+        }));
+        // For simplicity, use first output as primary entity
+        const primaryEntity = entities[0] || {
+            id: 'unknown',
+            type: 'artifact',
+            attributes: {},
+        };
+        const record = {
+            id: recordId,
+            timestamp,
+            entity: primaryEntity,
+            activity: {
+                id: this.generateActivityId(activity.type),
+                type: activity.type,
+                startedAt: timestamp,
+                endedAt: timestamp,
+                attributes: {
+                    description: activity.description,
+                    ...activity.metadata,
+                },
+            },
+            agent: {
+                id: activity.agentId,
+                type: 'software_agent',
+                attributes: {},
+            },
+            relationships: {
+                wasGeneratedBy: this.generateActivityId(activity.type),
+                wasDerivedFrom: activity.inputs,
+                wasAttributedTo: activity.agentId,
+                wasAssociatedWith: activity.agentId,
+            },
+        };
+        // Store in memory
+        this.records.set(recordId, record);
+        // Persist if enabled
+        if (this.autoPersist) {
+            await this.persistRecord(record);
+        }
+        return record;
+    }
+    /**
+     * Query lineage (provenance chain) for an entity
+     */
+    async queryLineage(entityId) {
+        const activities = [];
+        const sources = [];
+        const derived = [];
+        // Search through records
+        for (const record of this.records.values()) {
+            // Check if this record involves the entity
+            if (record.entity.id === entityId ||
+                record.relationships.wasDerivedFrom?.includes(entityId)) {
+                // Reconstruct activity
+                const activity = {
+                    type: record.activity.type,
+                    description: String(record.activity.attributes.description || ''),
+                    agentId: record.agent.id,
+                    inputs: record.relationships.wasDerivedFrom || [],
+                    outputs: [record.entity.id],
+                    metadata: record.activity.attributes,
+                };
+                activities.push({
+                    activity,
+                    timestamp: record.timestamp,
+                    agent: record.agent.id,
+                });
+                // Track sources and derived
+                if (record.relationships.wasDerivedFrom &&
+                    record.relationships.wasDerivedFrom.length === 0) {
+                    sources.push(record.entity.id);
+                }
+                if (record.relationships.wasDerivedFrom?.includes(entityId)) {
+                    derived.push(record.entity.id);
+                }
+            }
+        }
+        return {
+            entityId,
+            activities,
+            sources,
+            derived,
+        };
+    }
+    /**
+     * Validate provenance chain integrity
+     */
+    async validateChain(chainId) {
+        // Load chain
+        const chain = await this.queryLineage(chainId);
+        // Check that all activities are connected
+        const allInputs = new Set();
+        const allOutputs = new Set();
+        for (const { activity } of chain.activities) {
+            activity.inputs.forEach((input) => allInputs.add(input));
+            activity.outputs.forEach((output) => allOutputs.add(output));
+        }
+        // All inputs (except sources) should be outputs of other activities
+        for (const input of allInputs) {
+            if (!chain.sources.includes(input) && !allOutputs.has(input)) {
+                return false; // Broken chain
+            }
+        }
+        return true;
+    }
+    /**
+     * Export provenance in specified format
+     */
+    async exportPROV(format) {
+        if (format === 'json') {
+            return this.exportJSON();
+        }
+        else if (format === 'turtle') {
+            return this.exportTurtle();
+        }
+        throw new Error(`Unsupported format: ${format}`);
+    }
+    /**
+     * Export as PROV-JSON
+     */
+    exportJSON() {
+        const provDoc = {
+            prefix: {
+                prov: 'http://www.w3.org/ns/prov#',
+                aiwg: 'urn:aiwg:',
+            },
+            entity: {},
+            activity: {},
+            agent: {},
+            wasGeneratedBy: {},
+            wasDerivedFrom: {},
+            wasAttributedTo: {},
+            wasAssociatedWith: {},
+        };
+        for (const record of this.records.values()) {
+            // Add entity
+            provDoc.entity[record.entity.id] = record.entity.attributes;
+            // Add activity
+            provDoc.activity[record.activity.id] = {
+                'prov:startedAtTime': record.activity.startedAt,
+                'prov:endedAtTime': record.activity.endedAt,
+                ...record.activity.attributes,
+            };
+            // Add agent
+            provDoc.agent[record.agent.id] = record.agent.attributes;
+            // Add relationships
+            if (record.relationships.wasGeneratedBy) {
+                provDoc.wasGeneratedBy[record.entity.id] = {
+                    'prov:entity': record.entity.id,
+                    'prov:activity': record.relationships.wasGeneratedBy,
+                };
+            }
+            if (record.relationships.wasDerivedFrom) {
+                for (const source of record.relationships.wasDerivedFrom) {
+                    provDoc.wasDerivedFrom[`${record.entity.id}-${source}`] = {
+                        'prov:generatedEntity': record.entity.id,
+                        'prov:usedEntity': source,
+                    };
+                }
+            }
+            if (record.relationships.wasAttributedTo) {
+                provDoc.wasAttributedTo[record.entity.id] = {
+                    'prov:entity': record.entity.id,
+                    'prov:agent': record.relationships.wasAttributedTo,
+                };
+            }
+            if (record.relationships.wasAssociatedWith) {
+                provDoc.wasAssociatedWith[record.activity.id] = {
+                    'prov:activity': record.activity.id,
+                    'prov:agent': record.relationships.wasAssociatedWith,
+                };
+            }
+        }
+        return JSON.stringify(provDoc, null, 2);
+    }
+    /**
+     * Export as PROV-Turtle (simplified)
+     */
+    exportTurtle() {
+        const lines = [
+            '@prefix prov: <http://www.w3.org/ns/prov#> .',
+            '@prefix aiwg: <urn:aiwg:> .',
+            '',
+        ];
+        for (const record of this.records.values()) {
+            // Entity
+            lines.push(`aiwg:${record.entity.id} a prov:Entity .`);
+            // Activity
+            lines.push(`aiwg:${record.activity.id} a prov:Activity ;`);
+            lines.push(`  prov:startedAtTime "${record.activity.startedAt}"^^xsd:dateTime ;`);
+            lines.push(`  prov:endedAtTime "${record.activity.endedAt}"^^xsd:dateTime .`);
+            // Agent
+            lines.push(`aiwg:${record.agent.id} a prov:Agent .`);
+            // Relationships
+            if (record.relationships.wasGeneratedBy) {
+                lines.push(`aiwg:${record.entity.id} prov:wasGeneratedBy aiwg:${record.relationships.wasGeneratedBy} .`);
+            }
+            if (record.relationships.wasDerivedFrom) {
+                for (const source of record.relationships.wasDerivedFrom) {
+                    lines.push(`aiwg:${record.entity.id} prov:wasDerivedFrom aiwg:${source} .`);
+                }
+            }
+            if (record.relationships.wasAttributedTo) {
+                lines.push(`aiwg:${record.entity.id} prov:wasAttributedTo aiwg:${record.relationships.wasAttributedTo} .`);
+            }
+            if (record.relationships.wasAssociatedWith) {
+                lines.push(`aiwg:${record.activity.id} prov:wasAssociatedWith aiwg:${record.relationships.wasAssociatedWith} .`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Persist record to disk
+     */
+    async persistRecord(record) {
+        const filename = `${record.id}.json`;
+        const filepath = join(this.recordsDir, filename);
+        // Ensure directory exists
+        await this.ensureDir(this.recordsDir);
+        await fs.writeFile(filepath, JSON.stringify(record, null, 2), 'utf-8');
+    }
+    /**
+     * Generate record ID
+     */
+    generateRecordId() {
+        return `prov-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    }
+    /**
+     * Generate activity ID
+     */
+    generateActivityId(type) {
+        return `activity-${type}-${Date.now()}`;
+    }
+    /**
+     * Ensure directory exists
+     */
+    async ensureDir(dir) {
+        try {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+        }
+    }
+}
+//# sourceMappingURL=provenance.js.map