@maintainabilityai/research-runner 0.1.1

package/dist/search/tavily-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * tavily-client — minimal `fetch`-based wrapper around Tavily's `/search`
+ * endpoint. Returns normalized results the dedupe_and_rank node can score.
+ */
+export interface TavilySearchOpts {
+    apiKey: string;
+    query: string;
+    /** 1..20. Tavily default is 5. */
+    maxResults?: number;
+    /** "basic" (cheap, fast) or "advanced" (better quality, slower). */
+    searchDepth?: 'basic' | 'advanced';
+    /** Whether to include domains-only filter etc. — pass through to Tavily. */
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    /** Test injection point; defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** Abort timeout (ms). Default 30s. */
+    timeoutMs?: number;
+}
+export interface TavilyResult {
+    title: string;
+    url: string;
+    /** Snippet/excerpt that matched the query. */
+    content: string;
+    /** Tavily relevance score 0..1. */
+    score: number;
+    /** Publication date if Tavily resolved one (ISO). */
+    publishedDate?: string;
+}
+export interface TavilySearchResult {
+    query: string;
+    results: TavilyResult[];
+    /** Total response bytes (for audit). */
+    responseBytes: number;
+    /** HTTP status. */
+    httpStatus: number;
+}
+export declare function tavilySearch(opts: TavilySearchOpts): Promise<TavilySearchResult>;

package/dist/search/tavily-client.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * tavily-client — minimal `fetch`-based wrapper around Tavily's `/search`
+ * endpoint. Returns normalized results the dedupe_and_rank node can score.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tavilySearch = tavilySearch;
+async function tavilySearch(opts) {
+    if (!opts.apiKey) {
+        throw new Error('TAVILY_API_KEY missing — set the env var or pass apiKey directly');
+    }
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30_000);
+    let response;
+    try {
+        response = await fetchImpl('https://api.tavily.com/search', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                api_key: opts.apiKey,
+                query: opts.query,
+                max_results: opts.maxResults ?? 5,
+                search_depth: opts.searchDepth ?? 'basic',
+                ...(opts.includeDomains?.length ? { include_domains: opts.includeDomains } : {}),
+                ...(opts.excludeDomains?.length ? { exclude_domains: opts.excludeDomains } : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpStatus = response.status;
+    const rawText = await response.text();
+    if (!response.ok) {
+        throw new Error(`Tavily returned ${httpStatus}: ${rawText.slice(0, 400)}`);
+    }
+    const data = JSON.parse(rawText);
+    const results = (data.results ?? []).map(r => ({
+        title: r.title ?? '',
+        url: r.url ?? '',
+        content: r.content ?? '',
+        score: typeof r.score === 'number' ? r.score : 0,
+        publishedDate: r.published_date,
+    })).filter(r => r.url.length > 0);
+    return {
+        query: opts.query,
+        results,
+        responseBytes: Buffer.byteLength(rawText, 'utf8'),
+        httpStatus,
+    };
+}

package/dist/search/uspto-client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * uspto-client — query USPTO's Open Data Portal for patents related to the
+ * research topic, then enrich each hit with its abstract by following the
+ * grant / pre-grant publication XML URI.
+ *
+ * Two-stage pipeline (mirrors the NCMS archeologist_agent.py reference at
+ * github.com/AliceNN-ucdenver/ncms/.../archeologist_agent.py#L810):
+ *
+ *   1. GET https://api.uspto.gov/api/v1/patent/applications/search
+ *      ?q=<urlencoded-AND-joined-terms>&limit=<n>&offset=0
+ *      Headers: X-API-Key: <USPTO_API_KEY>, Accept: application/json
+ *      Returns { patentFileWrapperDataBag: [{ applicationMetaData, grantDocumentMetaData, pgpubDocumentMetaData, ... }] }
+ *
+ *   2. For each hit, follow `grantDocumentMetaData.fileLocationURI` (or
+ *      `pgpubDocumentMetaData.fileLocationURI` as fallback) and parse the
+ *      <abstract> element out of the XML. Stage 2 is best-effort —
+ *      a missing/failed abstract just leaves abstract: '' on the result
+ *      and the synthesis prompt falls back on the title alone.
+ *
+ * Migrated from the deprecated PatentsView v1 endpoint
+ * (https://search.patentsview.org/api/v1/patent/) — USPTO has consolidated
+ * onto the Open Data Portal at api.uspto.gov. The PatentsView endpoint may
+ * still respond intermittently but is no longer the recommended path.
+ *
+ * Get a key at https://data.uspto.gov/apis/getting-started (USPTO ODP).
+ */
+export interface UsptoResult {
+    patentNumber: string;
+    title: string;
+    /** Best abstract / first claim summary, fetched in stage 2. Empty when stage 2 fails. */
+    abstract: string;
+    url: string;
+    grantedAt: string;
+    inventors: string[];
+}
+export interface UsptoSearchOpts {
+    apiKey: string;
+    query: string;
+    maxResults?: number;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    endpoint?: string;
+}
+export interface UsptoSearchResult {
+    query: string;
+    results: UsptoResult[];
+    responseBytes: number;
+    httpStatus: number;
+}
+export declare function usptoSearch(opts: UsptoSearchOpts): Promise<UsptoSearchResult>;

package/dist/search/uspto-client.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * uspto-client — query USPTO's Open Data Portal for patents related to the
+ * research topic, then enrich each hit with its abstract by following the
+ * grant / pre-grant publication XML URI.
+ *
+ * Two-stage pipeline (mirrors the NCMS archeologist_agent.py reference at
+ * github.com/AliceNN-ucdenver/ncms/.../archeologist_agent.py#L810):
+ *
+ *   1. GET https://api.uspto.gov/api/v1/patent/applications/search
+ *      ?q=<urlencoded-AND-joined-terms>&limit=<n>&offset=0
+ *      Headers: X-API-Key: <USPTO_API_KEY>, Accept: application/json
+ *      Returns { patentFileWrapperDataBag: [{ applicationMetaData, grantDocumentMetaData, pgpubDocumentMetaData, ... }] }
+ *
+ *   2. For each hit, follow `grantDocumentMetaData.fileLocationURI` (or
+ *      `pgpubDocumentMetaData.fileLocationURI` as fallback) and parse the
+ *      <abstract> element out of the XML. Stage 2 is best-effort —
+ *      a missing/failed abstract just leaves abstract: '' on the result
+ *      and the synthesis prompt falls back on the title alone.
+ *
+ * Migrated from the deprecated PatentsView v1 endpoint
+ * (https://search.patentsview.org/api/v1/patent/) — USPTO has consolidated
+ * onto the Open Data Portal at api.uspto.gov. The PatentsView endpoint may
+ * still respond intermittently but is no longer the recommended path.
+ *
+ * Get a key at https://data.uspto.gov/apis/getting-started (USPTO ODP).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usptoSearch = usptoSearch;
+const DEFAULT_ENDPOINT = 'https://api.uspto.gov/api/v1/patent/applications/search';
+async function usptoSearch(opts) {
+    if (!opts.apiKey) {
+        throw new Error('USPTO_API_KEY missing — request one at https://data.uspto.gov/apis/getting-started');
+    }
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+    const size = Math.min(Math.max(1, opts.maxResults ?? 5), 20);
+    // The api.uspto.gov endpoint takes free-text queries with AND operators
+    // directly in the q= param (URL-encoded). No JSON DSL.
+    const url = `${endpoint}?q=${encodeURIComponent(opts.query)}&limit=${size}&offset=0`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30_000);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+                'X-API-Key': opts.apiKey,
+            },
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpStatus = response.status;
+    const rawText = await response.text();
+    if (!response.ok) {
+        throw new Error(`USPTO ODP returned ${httpStatus}: ${rawText.slice(0, 400)}`);
+    }
+    const data = JSON.parse(rawText);
+    const records = data.patentFileWrapperDataBag ?? [];
+    const stage1 = records.map(r => {
+        const meta = r.applicationMetaData ?? {};
+        const xmlUri = r.grantDocumentMetaData?.fileLocationURI
+            || r.pgpubDocumentMetaData?.fileLocationURI
+            || '';
+        const num = meta.patentNumber || meta.earliestPublicationNumber || '';
+        return {
+            patentNumber: num,
+            title: meta.inventionTitle ?? '',
+            abstract: '',
+            url: num ? `https://patents.google.com/patent/US${num}` : '',
+            grantedAt: meta.grantDate || meta.filingDate || meta.effectiveFilingDate || '',
+            inventors: meta.firstInventorName ? [meta.firstInventorName] : [],
+            _xmlUri: xmlUri,
+        };
+    });
+    // Stage 2: parallel best-effort abstract fetch. The full-text XML carries
+    // the <abstract> element; we regex it out rather than parsing the whole
+    // document (the XML is large and we only want the abstract).
+    await Promise.all(stage1.map(async (r) => {
+        if (!r._xmlUri) {
+            return;
+        }
+        try {
+            const xmlRes = await fetchImpl(r._xmlUri, {
+                method: 'GET',
+                headers: { 'X-API-Key': opts.apiKey, accept: 'application/xml' },
+            });
+            if (!xmlRes.ok) {
+                return;
+            }
+            const xml = await xmlRes.text();
+            const m = xml.match(/<abstract[^>]*>([\s\S]*?)<\/abstract>/i);
+            if (m) {
+                const stripped = m[1].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+                r.abstract = stripped.slice(0, 1000);
+            }
+        }
+        catch { /* ignore — best-effort */ }
+    }));
+    // Drop the internal _xmlUri marker before returning.
+    const results = stage1.map(({ _xmlUri: _ignored, ...rest }) => rest);
+    return {
+        query: opts.query,
+        results,
+        responseBytes: rawText.length,
+        httpStatus,
+    };
+}

package/dist/utils/run-id.d.ts

@@ -0,0 +1,2 @@
+export type RunKind = 'RES' | 'PRD';
+export declare function generateRunId(kind: RunKind, now?: Date): string;

package/dist/utils/run-id.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRunId = generateRunId;
+/**
+ * run-id — generate stable, sortable, low-collision run identifiers.
+ *
+ * Format: `<KIND>-YYYY-MM-DD-<8 hex chars>`
+ *   KIND ∈ {RES, PRD}
+ *
+ * The date is the run's UTC start day; the 8-hex tail is the first 4 bytes
+ * of a crypto.randomBytes call. 32 bits gives birthday-collision probability
+ * around 1 in 65,536 for the same date — more than enough for human-scale
+ * mesh-wide audit.
+ */
+const node_crypto_1 = require("node:crypto");
+function generateRunId(kind, now = new Date()) {
+    const yyyy = now.getUTCFullYear();
+    const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(now.getUTCDate()).padStart(2, '0');
+    const tail = (0, node_crypto_1.randomBytes)(4).toString('hex');
+    return `${kind}-${yyyy}-${mm}-${dd}-${tail}`;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@maintainabilityai/research-runner",
+  "version": "0.1.1",
+  "description": "Research + PRD agent runner — orchestrates the Archeologist and PRD pipelines for the MaintainabilityAI governance mesh",
+  "license": "MIT",
+  "author": "MaintainabilityAI",
+  "homepage": "https://maintainability.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AliceNN-ucdenver/MaintainabilityAI",
+    "directory": "packages/research-runner"
+  },
+  "bugs": {
+    "url": "https://github.com/AliceNN-ucdenver/MaintainabilityAI/issues"
+  },
+  "keywords": [
+    "research",
+    "prd",
+    "governance",
+    "calm",
+    "ai-agents",
+    "tavily",
+    "anthropic"
+  ],
+  "bin": {
+    "research-runner": "./bin/research-runner.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test --import tsx 'src/**/*.test.ts'",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}