@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/research/clients/semantic-scholar.js

@@ -0,0 +1,126 @@
+/**
+ * Semantic Scholar API client
+ *
+ * @module research/clients/semantic-scholar
+ */
+import { BaseClient } from './base.js';
+/**
+ * Semantic Scholar API client
+ */
+export class SemanticScholarClient extends BaseClient {
+    constructor(config) {
+        super({
+            baseUrl: 'https://api.semanticscholar.org/graph/v1',
+            timeout: 30000,
+            rateLimit: {
+                maxTokens: 100,
+                refillRate: 1, // 1 request per second
+                currentTokens: 100,
+                lastRefill: Date.now(),
+            },
+            retry: {
+                maxRetries: 3,
+                initialDelay: 1000,
+                maxDelay: 10000,
+                backoffMultiplier: 2,
+            },
+            ...config,
+        });
+    }
+    /**
+     * Get paper by DOI
+     */
+    async getPaperByDoi(doi) {
+        const fields = [
+            'paperId',
+            'title',
+            'abstract',
+            'year',
+            'authors',
+            'citationCount',
+            'venue',
+            'externalIds',
+            'openAccessPdf',
+        ];
+        const url = this.buildUrl(`/paper/DOI:${encodeURIComponent(doi)}`, {
+            fields: fields.join(','),
+        });
+        const response = await this.request(url);
+        return this.transformResponse(response);
+    }
+    /**
+     * Get paper by arXiv ID
+     */
+    async getPaperByArxivId(arxivId) {
+        const fields = [
+            'paperId',
+            'title',
+            'abstract',
+            'year',
+            'authors',
+            'citationCount',
+            'venue',
+            'externalIds',
+            'openAccessPdf',
+        ];
+        const url = this.buildUrl(`/paper/ARXIV:${encodeURIComponent(arxivId)}`, {
+            fields: fields.join(','),
+        });
+        const response = await this.request(url);
+        return this.transformResponse(response);
+    }
+    /**
+     * Search papers by query
+     */
+    async search(query, options = {}) {
+        const { limit = 10, offset = 0, fields = [
+            'paperId',
+            'title',
+            'abstract',
+            'year',
+            'authors',
+            'citationCount',
+            'venue',
+            'externalIds',
+            'openAccessPdf',
+        ], } = options;
+        const url = this.buildUrl('/paper/search', {
+            query,
+            limit,
+            offset,
+            fields: fields.join(','),
+        });
+        const response = await this.request(url);
+        return {
+            total: response.total,
+            papers: response.data.map((paper) => this.transformResponse(paper)),
+            offset: response.offset,
+            limit,
+            hasMore: response.offset + limit < response.total,
+        };
+    }
+    /**
+     * Transform Semantic Scholar response to ResearchPaper
+     */
+    transformResponse(response) {
+        const authors = (response.authors || []).map((author) => ({
+            name: author.name,
+            id: author.authorId,
+        }));
+        return {
+            id: response.paperId,
+            title: response.title,
+            authors,
+            year: response.year || 0,
+            abstract: response.abstract,
+            doi: response.externalIds?.DOI,
+            arxivId: response.externalIds?.ArXiv,
+            venue: response.venue,
+            citationCount: response.citationCount,
+            pdfUrl: response.openAccessPdf?.url,
+            source: 'semantic-scholar',
+            retrievedAt: new Date().toISOString(),
+        };
+    }
+}
+//# sourceMappingURL=semantic-scholar.js.map

package/dist/src/research/clients/unpaywall.js

@@ -0,0 +1,87 @@
+/**
+ * Unpaywall API client
+ *
+ * @module research/clients/unpaywall
+ */
+import { BaseClient } from './base.js';
+import { ResearchError, ResearchErrorCode, } from '../types.js';
+/**
+ * Unpaywall API client
+ */
+export class UnpaywallClient extends BaseClient {
+    email;
+    constructor(config) {
+        const email = config?.email || 'research@example.com';
+        super({
+            baseUrl: 'https://api.unpaywall.org/v2',
+            timeout: 30000,
+            rateLimit: {
+                maxTokens: 100,
+                refillRate: 10, // 10 requests per second
+                currentTokens: 100,
+                lastRefill: Date.now(),
+            },
+            retry: {
+                maxRetries: 3,
+                initialDelay: 1000,
+                maxDelay: 10000,
+                backoffMultiplier: 2,
+            },
+            ...config,
+        });
+        this.email = email;
+    }
+    /**
+     * Get paper by DOI
+     */
+    async getPaperByDoi(doi) {
+        if (!this.email || this.email === 'research@example.com') {
+            throw new ResearchError(ResearchErrorCode.RF_101, 'Email is required for Unpaywall API');
+        }
+        const url = this.buildUrl(`/${encodeURIComponent(doi)}`, {
+            email: this.email,
+        });
+        const response = await this.request(url);
+        return this.transformResponse(response);
+    }
+    /**
+     * Check if open access PDF is available for DOI
+     */
+    async checkOpenAccess(doi) {
+        try {
+            const paper = await this.getPaperByDoi(doi);
+            return paper.pdfUrl || null;
+        }
+        catch (error) {
+            if (error instanceof ResearchError &&
+                error.code === ResearchErrorCode.RF_300) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Transform Unpaywall response to ResearchPaper
+     */
+    transformResponse(response) {
+        const authors = response.authors?.map((author) => {
+            const name = [author.given, author.family]
+                .filter(Boolean)
+                .join(' ');
+            return { name };
+        }) || [];
+        return {
+            id: response.doi,
+            title: response.title || '',
+            authors,
+            year: response.year || 0,
+            doi: response.doi,
+            venue: response.journal_name,
+            pdfUrl: response.best_oa_location?.url_for_pdf ||
+                response.best_oa_location?.url,
+            source: 'unpaywall',
+            retrievedAt: new Date().toISOString(),
+        };
+    }
+}
+//# sourceMappingURL=unpaywall.js.map

package/dist/src/research/index.js

@@ -0,0 +1,14 @@
+/**
+ * Research Framework - API clients for academic paper retrieval
+ *
+ * @module research
+ */
+export * from './types.js';
+export * from './clients/base.js';
+export * from './clients/semantic-scholar.js';
+export * from './clients/crossref.js';
+export * from './clients/arxiv.js';
+export * from './clients/unpaywall.js';
+export * from './cache/manager.js';
+export * from './services/index.js';
+//# sourceMappingURL=index.js.map

package/dist/src/research/query-cli.js

@@ -0,0 +1,336 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../artifacts/index-builder.js";
+import { loadGraphIndexFile } from "../artifacts/index-reader.js";
+const RESEARCH_TYPES = new Set([
+    "research-ref",
+    "research-profile",
+    "research-view",
+    "research-synthesis",
+    "aiwg.research.ref",
+    "aiwg.research.profile",
+    "aiwg.research.view",
+    "aiwg.research.synthesis",
+    "kb-page",
+    "aiwg.kb.page",
+]);
+const STOPWORDS = new Set([
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "of",
+    "for",
+    "to",
+    "in",
+    "on",
+    "with",
+    "what",
+    "does",
+    "do",
+    "is",
+    "are",
+    "about",
+    "research",
+    "say",
+    "evidence",
+]);
+function usage() {
+    return [
+        "Usage: aiwg research-query <question> [--backend fortemi-core|local] [--graph <name>]",
+        "                           [--depth quick|thorough] [--sources-only] [--max-sources N]",
+        "                           [--json] [--save]",
+    ].join("\n");
+}
+function flagValue(args, flag, errorMessage) {
+    const index = args.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(errorMessage);
+    }
+    return value;
+}
+function positiveIntegerFlag(args, flag, defaultValue, errorMessage) {
+    const value = flagValue(args, flag, errorMessage);
+    if (value === undefined)
+        return defaultValue;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || String(parsed) !== value) {
+        throw new Error(errorMessage);
+    }
+    return parsed;
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function stripFlags(args) {
+    const valueFlags = new Set([
+        "--backend",
+        "--graph",
+        "--depth",
+        "--max-sources",
+    ]);
+    const bareFlags = new Set(["--sources-only", "--json", "--save"]);
+    const question = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (valueFlags.has(arg)) {
+            index++;
+            continue;
+        }
+        if (bareFlags.has(arg))
+            continue;
+        question.push(arg);
+    }
+    return question;
+}
+function parseArgs(args) {
+    if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+        console.log(usage());
+        process.exit(0);
+    }
+    const backend = flagValue(args, "--backend", "--backend must be local or fortemi-core");
+    if (backend && backend !== "local" && backend !== "fortemi-core") {
+        throw new Error("--backend must be local or fortemi-core");
+    }
+    const depth = (flagValue(args, "--depth", "--depth must be quick or thorough") ??
+        "thorough");
+    if (depth !== "quick" && depth !== "thorough") {
+        throw new Error("--depth must be quick or thorough");
+    }
+    const maxSources = positiveIntegerFlag(args, "--max-sources", 10, "--max-sources must be a positive integer");
+    const question = stripFlags(args).join(" ").trim();
+    if (!question)
+        throw new Error("question is required");
+    return {
+        question,
+        backend: backend ?? "fortemi-core",
+        graph: (flagValue(args, "--graph", "--graph requires a graph name") ??
+            "project"),
+        depth,
+        maxSources,
+        sourcesOnly: hasFlag(args, "--sources-only"),
+        json: hasFlag(args, "--json"),
+        save: hasFlag(args, "--save"),
+    };
+}
+function tokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter((token) => token.length > 1 && !STOPWORDS.has(token));
+}
+function readEntryBody(cwd, entryPath) {
+    const resolved = path.isAbsolute(entryPath)
+        ? entryPath
+        : path.resolve(cwd, entryPath);
+    try {
+        return parseFrontmatter(fs.readFileSync(resolved, "utf-8")).body;
+    }
+    catch {
+        return "";
+    }
+}
+function entryId(entry) {
+    const text = [entry.name, entry.title, entry.path].filter(Boolean).join(" ");
+    return (text.match(/\bREF-\d+\b/i)?.[0]?.toUpperCase() ??
+        text.match(/\bPROF-[A-Z0-9-]+/i)?.[0]?.toUpperCase() ??
+        path.basename(entry.path).replace(/\.[^.]+$/, ""));
+}
+function gradeFromText(text) {
+    const normalized = text.toUpperCase();
+    if (/\bVERY\s+LOW\b/.test(normalized))
+        return "VERY LOW";
+    if (/\bHIGH\b/.test(normalized))
+        return "HIGH";
+    if (/\bMODERATE\b/.test(normalized))
+        return "MODERATE";
+    if (/\bLOW\b/.test(normalized))
+        return "LOW";
+    return "UNKNOWN";
+}
+function relevance(score) {
+    if (score >= 0.55)
+        return "direct";
+    if (score >= 0.25)
+        return "supporting";
+    return "tangential";
+}
+function scoreEntry(entry, question, body, depth) {
+    const queryTokens = tokens(question);
+    if (queryTokens.length === 0)
+        return 0;
+    const fields = [
+        { text: entry.title, weight: 3 },
+        { text: entry.name ?? "", weight: 3 },
+        { text: entry.tags.join(" "), weight: 2 },
+        { text: entry.summary, weight: 2 },
+        { text: entry.path, weight: 0.75 },
+        ...(depth === "thorough" ? [{ text: body, weight: 1.5 }] : []),
+    ];
+    let weightedHits = 0;
+    let maxWeight = 0;
+    for (const token of queryTokens) {
+        const best = fields.reduce((score, field) => {
+            if (!field.text.toLowerCase().includes(token))
+                return score;
+            return Math.max(score, field.weight);
+        }, 0);
+        weightedHits += best;
+        maxWeight += 3;
+    }
+    return Math.min(weightedHits / Math.max(maxWeight, 1), 1);
+}
+function isResearchEntry(entry) {
+    const type = entry.type.toLowerCase();
+    const entryPath = entry.path.toLowerCase();
+    return (RESEARCH_TYPES.has(type) ||
+        entryPath.includes("/research/") ||
+        entryPath.includes("/kb/"));
+}
+function localEntries(cwd, graph) {
+    const index = loadGraphIndexFile(cwd, "metadata.json", graph);
+    return index ? Object.values(index.entries) : [];
+}
+async function backendEntries(cwd, graph, backend) {
+    if (backend === "fortemi-core") {
+        const { loadFortemiCoreMetadataEntries } = await import("../artifacts/fortemi-core-query-adapter.js");
+        const loaded = loadFortemiCoreMetadataEntries(cwd, graph);
+        return { entries: loaded.entries, hint: loaded.reason };
+    }
+    return { entries: localEntries(cwd, graph) };
+}
+function sourceForEntry(cwd, entry, question, depth) {
+    const body = depth === "thorough" ? readEntryBody(cwd, entry.path) : "";
+    const sourceText = [
+        entry.title,
+        entry.summary,
+        entry.tags.join(" "),
+        body,
+    ].join("\n");
+    const score = scoreEntry(entry, question, body, depth);
+    if (score <= 0)
+        return null;
+    return {
+        id: entryId(entry),
+        path: entry.path,
+        title: entry.title,
+        type: entry.type,
+        grade: gradeFromText(sourceText),
+        relevance: relevance(score),
+        score: Math.round(score * 1000) / 1000,
+        summary: entry.summary,
+        tags: entry.tags,
+    };
+}
+export async function runResearchQuery(cwd, options) {
+    const graph = options.graph ?? "project";
+    const backend = options.backend ?? "fortemi-core";
+    const depth = options.depth ?? "thorough";
+    const maxSources = options.maxSources ?? 10;
+    const loaded = await backendEntries(cwd, graph, backend);
+    if (backend === "fortemi-core" && loaded.hint) {
+        throw new Error(loaded.hint);
+    }
+    const sources = loaded.entries
+        .filter(isResearchEntry)
+        .map((entry) => sourceForEntry(cwd, entry, options.question, depth))
+        .filter((source) => source !== null)
+        .sort((left, right) => {
+        const scoreCmp = right.score - left.score;
+        if (scoreCmp !== 0)
+            return scoreCmp;
+        return left.path.localeCompare(right.path);
+    })
+        .slice(0, maxSources);
+    const result = {
+        query: {
+            question: options.question,
+            backend,
+            graph,
+            depth,
+        },
+        sources,
+        total: sources.length,
+        hint: loaded.hint,
+    };
+    if (options.save) {
+        result.savedPath = saveSourceSelection(cwd, result, options.generatedAt);
+    }
+    return result;
+}
+function saveSourceSelection(cwd, result, generatedAt = new Date().toISOString()) {
+    const date = generatedAt.slice(0, 10);
+    const slug = result.query.question
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48) || "query";
+    const relativePath = path.join(".aiwg", "research", "synthesis", `query-${slug}-${date}.md`);
+    const outPath = path.resolve(cwd, relativePath);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, renderMarkdown(result, true), "utf-8");
+    return relativePath;
+}
+function renderSourcesTable(sources) {
+    const rows = [
+        "| REF | Title | GRADE | Relevance | Score | Path |",
+        "|-----|-------|-------|-----------|-------|------|",
+        ...sources.map((source) => `| ${source.id} | ${source.title} | ${source.grade} | ${source.relevance} | ${source.score.toFixed(3)} | ${source.path} |`),
+    ];
+    return rows.join("\n");
+}
+function renderMarkdown(result, saved = false) {
+    const frontmatter = saved
+        ? [
+            "---",
+            "type: query-source-selection",
+            `question: ${JSON.stringify(result.query.question)}`,
+            `backend: ${result.query.backend}`,
+            `graph: ${result.query.graph}`,
+            `depth: ${result.query.depth}`,
+            `sources: [${result.sources.map((source) => source.id).join(", ")}]`,
+            "---",
+            "",
+        ].join("\n")
+        : "";
+    const sections = [
+        `${frontmatter}## Research Sources`,
+        "",
+        `Question: ${result.query.question}`,
+        `Backend: ${result.query.backend}`,
+        "",
+        result.sources.length > 0
+            ? renderSourcesTable(result.sources)
+            : "No matching research sources found.",
+    ];
+    if (result.query.backend === "local") {
+        sections.push("", "Use the research-query skill to synthesize an answer from these sources with GRADE-aware hedging and inline REF citations.");
+    }
+    if (result.hint)
+        sections.push("", `Hint: ${result.hint}`);
+    return sections.join("\n") + "\n";
+}
+export async function main(args, cwd = process.cwd()) {
+    try {
+        const options = parseArgs(args);
+        const result = await runResearchQuery(cwd, options);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(renderMarkdown(result));
+        if (result.savedPath) {
+            console.log(`Saved source selection: ${result.savedPath}`);
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        console.error(usage());
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=query-cli.js.map