@kolmo/scout 0.1.0

package/dist/summarizers/repoSummary.js

@@ -0,0 +1,101 @@
+const PROJECT_TYPE_LABELS = {
+    data_folder_project: 'data folder',
+    fastapi_backend_project: 'FastAPI backend',
+    frontend_project: 'frontend application',
+    generic_project: 'general analytics project',
+    notebook_research_project: 'notebook research project',
+    python_analytics_project: 'Python analytics project',
+    supabase_project: 'Supabase-backed project',
+};
+const WORKFLOW_LABELS = {
+    carbon_emissions_analysis: 'carbon emissions analysis',
+    crude_oil_price_analysis: 'crude oil price analysis',
+    data_quality_check: 'data quality checks',
+    general_energy_analysis: 'general energy analysis',
+    lng_market_analysis: 'LNG market analysis',
+    natural_gas_analysis: 'natural gas analysis',
+    notebook_review: 'notebook review',
+    power_market_analysis: 'power market analysis',
+    python_model_review: 'Python model review',
+};
+export function buildRepoSummary(input) {
+    const fileCount = input.detectedFiles.length;
+    const fileTypeCounts = countBy(input.detectedFiles.map((file) => file.detected_type));
+    const topFileTypes = topEntries(fileTypeCounts, 3).filter(([type]) => type !== 'unknown');
+    const dataFileCount = input.detectedFiles.filter((file) => ['.csv', '.xls', '.xlsx'].includes(file.extension.toLowerCase())).length;
+    const pythonFileCount = input.detectedFiles.filter((file) => file.extension === '.py').length;
+    const notebookCount = input.detectedFiles.filter((file) => file.extension === '.ipynb').length;
+    const signals = unique(input.detectedFiles.flatMap((file) => file.signals));
+    const packages = unique([
+        ...input.detectedPackages.python.slice(0, 4),
+        ...input.detectedPackages.node.slice(0, 4),
+    ]);
+    const projectLabel = PROJECT_TYPE_LABELS[input.projectType] ?? input.projectType.replace(/_/g, ' ');
+    const assetsText = input.detectedAssets.length
+        ? `focused on ${formatAssetList(input.detailedAssets ?? [], input.detectedAssets)}`
+        : 'with no specific energy asset detected yet';
+    const workflowText = input.suggestedWorkflows.length
+        ? formatList(input.suggestedWorkflows.map((workflow) => WORKFLOW_LABELS[workflow] ?? workflow))
+        : 'general energy analysis';
+    const details = [];
+    if (dataFileCount > 0)
+        details.push(`${dataFileCount} structured data ${plural(dataFileCount, 'file')}`);
+    if (pythonFileCount > 0)
+        details.push(`${pythonFileCount} Python ${plural(pythonFileCount, 'file')}`);
+    if (notebookCount > 0)
+        details.push(`${notebookCount} notebook${notebookCount === 1 ? '' : 's'}`);
+    if (topFileTypes.length > 0) {
+        details.push(`detected content such as ${formatList(topFileTypes.map(([type]) => type.replace(/_/g, ' ')))}`);
+    }
+    if (signals.length > 0) {
+        details.push(`signals around ${formatList(signals.slice(0, 5))}`);
+    }
+    if (packages.length > 0) {
+        details.push(`a stack using ${formatList(packages)}`);
+    }
+    const detailText = details.length
+        ? ` The scan reviewed ${fileCount} ${plural(fileCount, 'file')} and found ${details.join(', ')}.`
+        : ` The scan reviewed ${fileCount} ${plural(fileCount, 'file')}, but not enough domain structure to classify the strategy deeply yet.`;
+    return (`Kolmo understands "${input.projectName}" as a ${projectLabel} ${assetsText}.` +
+        detailText +
+        ` Recommended next workflows are ${workflowText}.` +
+        buildEvidenceSentence(input.evidenceCitations ?? []));
+}
+function countBy(values) {
+    const counts = new Map();
+    for (const value of values) {
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return counts;
+}
+function topEntries(counts, limit) {
+    return Array.from(counts.entries())
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, limit);
+}
+function unique(values) {
+    return Array.from(new Set(values.filter(Boolean))).sort();
+}
+function formatList(values) {
+    if (values.length === 0)
+        return '';
+    if (values.length === 1)
+        return values[0];
+    if (values.length === 2)
+        return `${values[0]} and ${values[1]}`;
+    return `${values.slice(0, -1).join(', ')}, and ${values[values.length - 1]}`;
+}
+function plural(count, noun) {
+    return count === 1 ? noun : `${noun}s`;
+}
+function formatAssetList(detailedAssets, symbols) {
+    if (detailedAssets.length === 0)
+        return formatList(symbols);
+    const labels = detailedAssets.map((asset) => asset.inferred ? `${asset.symbol} (inferred from "crude")` : asset.symbol);
+    return formatList(labels);
+}
+function buildEvidenceSentence(citations) {
+    if (citations.length === 0)
+        return '';
+    return ` Evidence: ${citations.slice(0, 3).join('; ')}.`;
+}

package/dist/taxonomy/energyTaxonomy.d.ts

@@ -0,0 +1,27 @@
+import type { ScoutAssetInfo } from '../types.js';
+export interface EnergyAssetDefinition {
+    symbol: string;
+    family: string;
+    exchange?: string;
+    region?: string;
+    hub?: string;
+    unit?: string;
+    aliases: string[];
+}
+export interface ParsedTenor {
+    raw: string;
+    kind: 'relative_month' | 'month' | 'quarter' | 'calendar_year';
+    label: string;
+    year?: number;
+    month?: number;
+    quarter?: number;
+    sequence?: number;
+}
+export declare const ENERGY_ASSETS: EnergyAssetDefinition[];
+export declare function detectEnergyAssets(input: {
+    file?: string;
+    filenames?: string[];
+    columnNames?: string[];
+    textValues?: string[];
+}): ScoutAssetInfo[];
+export declare function parseTenor(value: string): ParsedTenor | null;

package/dist/taxonomy/energyTaxonomy.js

@@ -0,0 +1,250 @@
+export const ENERGY_ASSETS = [
+    {
+        symbol: 'BRENT',
+        family: 'crude_oil',
+        exchange: 'ICE',
+        region: 'North Sea',
+        hub: 'BFOE',
+        unit: 'bbl',
+        aliases: ['brent', 'bfoe', 'ice brent', 'brn'],
+    },
+    {
+        symbol: 'WTI',
+        family: 'crude_oil',
+        exchange: 'NYMEX',
+        region: 'United States',
+        hub: 'Cushing',
+        unit: 'bbl',
+        aliases: ['wti', 'west texas', 'nymex crude', 'cl futures', 'cl_'],
+    },
+    {
+        symbol: 'TTF',
+        family: 'natural_gas',
+        exchange: 'ICE',
+        region: 'Netherlands',
+        hub: 'Title Transfer Facility',
+        unit: 'MWh',
+        aliases: ['ttf', 'dutch gas', 'ice endex ttf'],
+    },
+    {
+        symbol: 'NBP',
+        family: 'natural_gas',
+        exchange: 'ICE',
+        region: 'United Kingdom',
+        hub: 'National Balancing Point',
+        unit: 'therm',
+        aliases: ['nbp', 'uk gas', 'national balancing point'],
+    },
+    {
+        symbol: 'JKM',
+        family: 'lng',
+        exchange: 'ICE',
+        region: 'North Asia',
+        hub: 'Japan Korea Marker',
+        unit: 'MMBtu',
+        aliases: ['jkm', 'japan korea marker', 'lng'],
+    },
+    {
+        symbol: 'RBOB',
+        family: 'refined_products',
+        exchange: 'NYMEX',
+        region: 'United States',
+        hub: 'New York Harbor',
+        unit: 'gal',
+        aliases: ['rbob', 'gasoline', 'nymex rbob'],
+    },
+    {
+        symbol: 'ULSD',
+        family: 'refined_products',
+        exchange: 'NYMEX',
+        region: 'United States',
+        hub: 'New York Harbor',
+        unit: 'gal',
+        aliases: ['ulsd', 'diesel', 'heating oil', 'nymex ho'],
+    },
+    {
+        symbol: 'GASOIL',
+        family: 'refined_products',
+        exchange: 'ICE',
+        region: 'Europe',
+        hub: 'ARA',
+        unit: 'tonne',
+        aliases: ['gasoil', 'ice gasoil'],
+    },
+    {
+        symbol: 'NG',
+        family: 'natural_gas',
+        exchange: 'NYMEX',
+        region: 'United States',
+        hub: 'Henry Hub',
+        unit: 'MMBtu',
+        aliases: ['henry hub', 'natural gas', 'natgas', 'ng futures', 'ng_'],
+    },
+    {
+        symbol: 'EUA',
+        family: 'carbon',
+        exchange: 'ICE',
+        region: 'European Union',
+        hub: 'EU ETS',
+        unit: 'tCO2e',
+        aliases: ['eua', 'carbon', 'emissions', 'eu ets'],
+    },
+    {
+        symbol: 'POWER',
+        family: 'power',
+        region: 'Europe',
+        unit: 'MWh',
+        aliases: ['power', 'electricity', 'baseload', 'peakload'],
+    },
+];
+const MONTHS = {
+    jan: 1,
+    feb: 2,
+    mar: 3,
+    apr: 4,
+    may: 5,
+    jun: 6,
+    jul: 7,
+    aug: 8,
+    sep: 9,
+    sept: 9,
+    oct: 10,
+    nov: 11,
+    dec: 12,
+};
+export function detectEnergyAssets(input) {
+    const evidenceBySymbol = new Map();
+    const values = [
+        ...(input.filenames ?? []).map((value) => ({ source: 'filename', value })),
+        ...(input.columnNames ?? []).map((value) => ({ source: 'column', value })),
+        ...(input.textValues ?? []).map((value) => ({ source: 'text', value })),
+    ];
+    for (const asset of ENERGY_ASSETS) {
+        for (const { source, value } of values) {
+            const matchedAlias = asset.aliases.find((alias) => matchesAlias(value, alias));
+            if (!matchedAlias)
+                continue;
+            const evidence = evidenceBySymbol.get(asset.symbol) ?? [];
+            evidence.push({
+                source,
+                value,
+                pattern: matchedAlias,
+                file: input.file,
+            });
+            evidenceBySymbol.set(asset.symbol, evidence);
+        }
+    }
+    // Bare "crude" fallback — if no WTI or BRENT was explicitly matched but the word "crude"
+    // appears without "brent" context, default to WTI (US market convention).
+    const inferredSymbols = new Set();
+    const crudeSignal = values.find(({ value }) => {
+        const norm = normalize(value);
+        return /\bcrude\b/.test(norm) && !/\bbrent\b/.test(norm);
+    });
+    if (crudeSignal && !evidenceBySymbol.has('WTI')) {
+        inferredSymbols.add('WTI');
+        evidenceBySymbol.set('WTI', [{
+                source: crudeSignal.source,
+                value: crudeSignal.value,
+                pattern: 'crude',
+                file: input.file,
+            }]);
+    }
+    return Array.from(evidenceBySymbol.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([symbol, evidence]) => {
+        const asset = ENERGY_ASSETS.find((candidate) => candidate.symbol === symbol);
+        const inferred = inferredSymbols.has(symbol);
+        return {
+            symbol,
+            family: asset?.family ?? 'unknown',
+            exchange: asset?.exchange,
+            region: asset?.region,
+            hub: asset?.hub,
+            unit: asset?.unit,
+            evidence: dedupeEvidence(evidence),
+            inferred: inferred || undefined,
+            inference_note: inferred
+                ? `"crude" detected — defaulting to WTI (US convention). Update to BRENT if this is European crude.`
+                : undefined,
+        };
+    });
+}
+export function parseTenor(value) {
+    const raw = value.trim();
+    if (!raw)
+        return null;
+    const lower = raw.toLowerCase();
+    const relativeMonth = lower.match(/\bm\s*([1-9][0-9]?)\b/);
+    if (relativeMonth) {
+        const sequence = Number(relativeMonth[1]);
+        return { raw, kind: 'relative_month', label: `M${sequence}`, sequence };
+    }
+    const calendarYear = lower.match(/\bcal(?:endar)?[-_\s']?([0-9]{2}|20[0-9]{2})\b/);
+    if (calendarYear) {
+        const year = normalizeYear(calendarYear[1]);
+        return { raw, kind: 'calendar_year', label: `Cal${String(year).slice(-2)}`, year };
+    }
+    const quarter = lower.match(/\bq([1-4])[-_\s']?([0-9]{2}|20[0-9]{2})\b/);
+    if (quarter) {
+        const quarterNumber = Number(quarter[1]);
+        const year = normalizeYear(quarter[2]);
+        return {
+            raw,
+            kind: 'quarter',
+            label: `Q${quarterNumber}-${String(year).slice(-2)}`,
+            quarter: quarterNumber,
+            year,
+        };
+    }
+    const month = lower.match(/\b(jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*[-_\s']?([0-9]{2}|20[0-9]{2})\b/);
+    if (month) {
+        const monthNumber = MONTHS[month[1]];
+        const year = normalizeYear(month[2]);
+        return {
+            raw,
+            kind: 'month',
+            label: `${monthLabel(monthNumber)}${String(year).slice(-2)}`,
+            month: monthNumber,
+            year,
+        };
+    }
+    return null;
+}
+function matchesAlias(value, alias) {
+    const normalizedValue = normalize(value);
+    const normalizedAlias = normalize(alias);
+    if (!normalizedAlias)
+        return false;
+    if (alias.endsWith('_')) {
+        const compactAlias = alias.toLowerCase();
+        const baseAlias = normalize(alias.replace(/_+$/g, ''));
+        return (value.toLowerCase().includes(compactAlias) ||
+            new RegExp(`(^|\\s)${escapeRegex(baseAlias)}(\\s|$)`, 'i').test(normalizedValue));
+    }
+    return new RegExp(`(^|\\s)${escapeRegex(normalizedAlias)}(\\s|$)`, 'i').test(normalizedValue);
+}
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function normalizeYear(value) {
+    const year = Number(value);
+    return year < 100 ? 2000 + year : year;
+}
+function monthLabel(month) {
+    const entry = Object.entries(MONTHS).find(([, value]) => value === month);
+    return entry ? entry[0][0].toUpperCase() + entry[0].slice(1, 3) : 'Mon';
+}
+function dedupeEvidence(evidence) {
+    const seen = new Set();
+    return evidence.filter((item) => {
+        const key = `${item.source}:${item.value}:${item.pattern}:${item.file ?? ''}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export interface ScoutFileInfo {
+    path: string;
+    extension: string;
+    detected_type: string;
+    detected_assets: string[];
+    columns: string[];
+    signals: string[];
+    metadata: Record<string, unknown>;
+}
+export interface ScoutAssetEvidence {
+    source: 'filename' | 'column' | 'text';
+    value: string;
+    pattern: string;
+    file?: string;
+}
+export interface ScoutAssetInfo {
+    symbol: string;
+    family: string;
+    exchange?: string;
+    region?: string;
+    hub?: string;
+    unit?: string;
+    evidence: ScoutAssetEvidence[];
+    inferred?: boolean;
+    inference_note?: string;
+}
+export interface ScoutFileTypeExplanation {
+    path: string;
+    detected_type: string;
+    reason: string;
+    evidence: string[];
+}
+export interface ScoutExplanations {
+    project_type_reasons: string[];
+    asset_evidence: ScoutAssetInfo[];
+    file_type_reasons: ScoutFileTypeExplanation[];
+    workflow_reasons: string[];
+    evidence_citations: string[];
+}
+export interface ScoutFileContent {
+    path: string;
+    content: string;
+    truncated: boolean;
+}
+export interface ScoutManifest {
+    schema_version: string;
+    project_name: string;
+    created_by: string;
+    privacy_mode: string;
+    project_type: string;
+    repo_summary: string;
+    summary_source: 'generated' | 'provided' | 'user_edited';
+    detected_assets: string[];
+    detailed_assets: ScoutAssetInfo[];
+    detected_files: ScoutFileInfo[];
+    detected_packages: {
+        python: string[];
+        node: string[];
+    };
+    suggested_workflows: string[];
+    explanations: ScoutExplanations;
+    file_contents: ScoutFileContent[];
+    portfolio_name?: string;
+}
+export interface ScanOptions {
+    apiUrl: string;
+    dir?: string;
+    noUpload?: boolean;
+    noContent?: boolean;
+    portfolioName?: string;
+    summary?: string;
+    yes?: boolean;
+    verbose?: boolean;
+}
+export interface ExplainOptions {
+    dir?: string;
+    json?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/workflows/workflowSuggestions.d.ts

@@ -0,0 +1,2 @@
+export declare function buildSuggestedWorkflows(projectType: string, assets: string[]): string[];
+export declare function explainWorkflows(workflows: string[], assets: string[], projectType: string): string[];

package/dist/workflows/workflowSuggestions.js

@@ -0,0 +1,61 @@
+export function buildSuggestedWorkflows(projectType, assets) {
+    const workflows = [];
+    if (assets.includes('BRENT') || assets.includes('WTI')) {
+        workflows.push('crude_oil_price_analysis');
+    }
+    if (assets.includes('TTF') || assets.includes('NBP') || assets.includes('NG')) {
+        workflows.push('natural_gas_analysis');
+    }
+    if (assets.includes('EUA')) {
+        workflows.push('carbon_emissions_analysis');
+    }
+    if (assets.includes('POWER')) {
+        workflows.push('power_market_analysis');
+    }
+    if (assets.includes('JKM')) {
+        workflows.push('lng_market_analysis');
+    }
+    if (projectType === 'notebook_research_project') {
+        workflows.push('notebook_review');
+    }
+    if (projectType === 'python_analytics_project') {
+        workflows.push('python_model_review');
+    }
+    if (projectType === 'data_folder_project') {
+        workflows.push('data_quality_check');
+    }
+    if (workflows.length === 0) {
+        workflows.push('general_energy_analysis');
+    }
+    return workflows;
+}
+export function explainWorkflows(workflows, assets, projectType) {
+    return workflows.map((workflow) => {
+        if (workflow === 'crude_oil_price_analysis') {
+            return 'Crude workflow selected because Brent or WTI was detected.';
+        }
+        if (workflow === 'natural_gas_analysis') {
+            return 'Natural gas workflow selected because TTF, NBP, or Henry Hub gas was detected.';
+        }
+        if (workflow === 'carbon_emissions_analysis') {
+            return 'Carbon workflow selected because EUA or emissions data was detected.';
+        }
+        if (workflow === 'power_market_analysis') {
+            return 'Power workflow selected because power-market language was detected.';
+        }
+        if (workflow === 'lng_market_analysis') {
+            return 'LNG workflow selected because JKM or LNG data was detected.';
+        }
+        if (workflow === 'notebook_review') {
+            return 'Notebook review selected because the project contains Jupyter notebooks.';
+        }
+        if (workflow === 'python_model_review') {
+            return 'Python model review selected because the project looks like a Python analytics project.';
+        }
+        if (workflow === 'data_quality_check') {
+            return 'Data quality checks selected because most scanned files are structured data files.';
+        }
+        const assetText = assets.length ? ` for ${assets.join(', ')}` : '';
+        return `General energy analysis selected${assetText} because no more specific workflow matched project type ${projectType}.`;
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kolmo/scout",
+  "version": "0.1.0",
+  "description": "Kolmo Scout — scan local energy projects and connect to Kolmo analytics",
+  "main": "./dist/index.js",
+  "bin": {
+    "kolmo-scout": "dist/index.js",
+    "kolmo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/tests"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test dist/tests/*.test.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.2",
+    "ora": "^8.0.1",
+    "papaparse": "^5.4.1",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/papaparse": "^5.3.14",
+    "typescript": "^5.4.0"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  }
+}