autoscholar-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AutoScholar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+<p align="center">
+  <br/>
+  <strong>
+    <code>&nbsp;A u t o S c h o l a r&nbsp;&nbsp;C L I&nbsp;</code>
+  </strong>
+  <br/><br/>
+  <em>A quant researcher + economist + data scientist living inside your terminal.</em>
+  <br/><br/>
+  <a href="https://www.npmjs.com/package/autoscholar-cli"><img src="https://img.shields.io/npm/v/autoscholar-cli?color=0EA5E9&label=npm&style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/autoscholar-cli"><img src="https://img.shields.io/npm/dm/autoscholar-cli?color=06B6D4&style=flat-square" alt="downloads"></a>
+  <a href="https://github.com/autoscholar/autoscholar-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/autoscholar-cli?color=14B8A6&style=flat-square" alt="license"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-0EA5E9?style=flat-square" alt="node version">
+  <img src="https://img.shields.io/badge/python-%3E%3D3.9-0EA5E9?style=flat-square" alt="python version">
+</p>
+
+---
+
+**AutoScholar CLI** is an autonomous scientific research agent that generates **publication-ready academic papers** entirely from the command line. It orchestrates five AI agents to search literature, collect data, build datasets, run econometric analysis, and compile LaTeX PDFs — all without a browser or GUI.
+
+```
+     _         _         ____       _           _
+    / \  _   _| |_ ___  / ___|  ___| |__   ___ | | __ _ _ __
+   / _ \| | | | __/ _ \ \___ \ / __| '_ \ / _ \| |/ _` | '__|
+  / ___ \ |_| | || (_) | ___) | (__| | | | (_) | | (_| | |
+ /_/   \_\__,_|\__\___/ |____/ \___|_| |_|\___/|_|\__,_|_|
+
+ Autonomous Scientific Research Agent v1.0.0
+```
+
+## Install
+
+```bash
+npm install -g autoscholar-cli
+```
+
+### Python Dependencies
+
+AutoScholar requires Python 3.9+ with the following packages:
+
+```bash
+pip3 install pandas numpy scipy matplotlib seaborn scikit-learn statsmodels arch linearmodels
+```
+
+### LaTeX (optional, for PDF compilation)
+
+Install [TeX Live](https://www.tug.org/texlive/) or [MacTeX](https://www.tug.org/mactex/) for PDF generation. Without LaTeX, papers are saved as `.tex` source files.
+
+## Quick Start
+
+```bash
+# Launch interactive mode
+autoscholar
+
+# Or run directly with flags
+autoscholar run --topic "Volatility spillovers between crypto and commodities 2015-2025"
+```
+
+On first launch, AutoScholar will walk you through an interactive **setup wizard** to configure your API keys.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `autoscholar` | Interactive mode (default) |
+| `autoscholar run` | Run the full research pipeline |
+| `autoscholar config` | Manage API keys |
+| `autoscholar outputs` | Browse generated papers |
+| `autoscholar resume <id>` | Resume an incomplete project |
+
+### Run Options
+
+```bash
+autoscholar run \
+  --topic "Factor momentum in US equities"  \
+  --assets "AAPL,MSFT,GOOG,AMZN"           \
+  --method "DCC-GARCH"                       \
+  --hf                                       \  # high-frequency data
+  --dry                                         # show plan only
+```
+
+## How It Works
+
+AutoScholar orchestrates **five specialized AI agents** through a 7-stage pipeline:
+
+```
+ Plan -> Gauss -> Turing -> Newton -> Fisher -> Write -> Compile
+  |        |        |         |         |         |        |
+  |     Search    Fetch    Clean &    Run      Write    LaTeX
+  |    250M+     FMP,     merge     GARCH,    8 paper   to
+  |    papers    EODHD,   sources   OLS,      sections  PDF
+  |              FRED               Panel
+  |
+  Euler (orchestrator)
+```
+
+### The Five Agents
+
+| Agent | Role | What it does |
+|-------|------|-------------|
+| **Euler** | Orchestrator | Plans the study, coordinates agents, writes the paper |
+| **Gauss** | Literature | Searches 250M+ papers via OpenAlex, arXiv, CrossRef. Identifies research gaps. |
+| **Turing** | Data Collection | Fetches data from FMP, EODHD, FRED, World Bank, IMF |
+| **Newton** | Dataset Builder | Cleans, merges, and constructs analysis-ready datasets |
+| **Fisher** | Analysis Engine | Runs econometric models, generates figures & tables |
+
+### Governor Engine
+
+A rule-based decision engine monitors the pipeline in real-time:
+
+- Automatic **profile switching** (academic figures, debug recovery, LaTeX fallback)
+- **Retry budgets** (5 Python, 3 data, 3 LaTeX retries)
+- **Confidence scoring** that adapts to errors and successes
+
+## Data Sources
+
+| Source | Coverage | Key Required |
+|--------|----------|-------------|
+| **OpenAlex** | 250M+ academic papers | No |
+| **arXiv** | Preprints (finance, econ, stat) | No |
+| **CrossRef** | 140M+ articles, DOI resolution | No |
+| **FMP** | 230+ financial data endpoints | Yes |
+| **EODHD** | Historical prices, intraday, options | Yes |
+| **FRED** | 840,000+ macroeconomic series | Yes |
+| **World Bank** | 16,000+ development indicators | No |
+| **IMF** | Global Financial Stability data | No |
+| **Firecrawl** | Web scraping & extraction | Yes |
+| **Serper / SerpAPI** | Web & Google Scholar search | Yes |
+| **Tavily** | AI-powered search | Yes |
+| **Exa** | Semantic neural search | Yes |
+
+## API Keys
+
+API keys are stored securely in `~/.autoscholar/.env`. Configure them interactively:
+
+```bash
+autoscholar config
+```
+
+| Key | Required | Purpose |
+|-----|----------|---------|
+| `ANTHROPIC_API_KEY` | **Yes** | Powers all AI agents |
+| `FMP_API_KEY` | Recommended | Financial data (stocks, fundamentals) |
+| `EODHD_API_KEY` | Recommended | Historical prices, options chains |
+| `FRED_API_KEY` | Recommended | Macroeconomic data |
+| `SERPER_API_KEY` | Optional | Web search |
+| `SERPAPI_API_KEY` | Optional | Google Scholar |
+| `FIRECRAWL_API_KEY` | Optional | Web scraping |
+| `TAVILY_API_KEY` | Optional | AI search |
+| `EXA_API_KEY` | Optional | Semantic search |
+
+## Output Structure
+
+All outputs are stored locally:
+
+```
+~/.autoscholar/projects/{project-id}/
+  data/
+    fmp_prices.csv
+    fred_macro.csv
+    final_dataset.csv
+  code/
+    fisher_analysis.py
+    newton_build_dataset.py
+  output/
+    paper.tex
+    paper.pdf
+    references.bib
+    figures/
+      correlation_matrix.png
+      time_series.png
+      ols_diagnostics.png
+      ...
+  logs/
+    run_2025-01-15T10-30-00.log
+  meta.json
+```
+
+## Supported Methods
+
+### Econometrics
+OLS, Robust SE, IV/2SLS, GMM, Panel Fixed Effects, Panel Random Effects, Hausman Test, Fama-MacBeth, GARCH, DCC-GARCH, VAR, VECM, Granger Causality, Local Projections
+
+### Statistics
+t-tests, ANOVA, Chi-square, Mann-Whitney, Kruskal-Wallis, Bootstrap Confidence Intervals
+
+### Machine Learning
+Random Forest, XGBoost, LightGBM, SVM/SVR, ElasticNet, PCA, k-means, SHAP
+
+## Requirements
+
+- **Node.js** >= 18
+- **Python** >= 3.9
+- **Anthropic API key** (required)
+- **LaTeX** (optional, for PDF output)
+
+## Philosophy
+
+AutoScholar CLI should feel like:
+
+> *"A quant researcher + economist + data scientist living inside your terminal"*
+
+It is:
+
+- **Autonomous** — end-to-end paper generation with no manual steps
+- **Reproducible** — all code, data, and logs saved per project
+- **Modular** — five specialized agents with clean interfaces
+- **Local-first** — everything runs on your machine, no cloud dependency
+- **Premium** — beautiful terminal UX inspired by Vercel and Stripe CLIs
+
+## License
+
+MIT

package/dist/agents/euler.js

@@ -0,0 +1,261 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEulerPipeline = runEulerPipeline;
+const chalk_1 = __importDefault(require("chalk"));
+const llm_1 = require("../utils/llm");
+const banner_1 = require("../cli/banner");
+const governor_1 = require("./governor");
+const gauss_1 = require("./gauss");
+const turing_1 = require("./turing");
+const newton_1 = require("./newton");
+const fisher_1 = require("./fisher");
+const generator_1 = require("../latex/generator");
+const project_1 = require("../utils/project");
+const logger_1 = require("../utils/logger");
+async function runEulerPipeline(topic, projectId, config, logger, options) {
+    const startTime = Date.now();
+    const governor = new governor_1.GovernorEngine();
+    const stages = {};
+    (0, banner_1.printStageHeader)('Euler: Research Pipeline', '\u25B6');
+    console.log();
+    (0, banner_1.printKV)('Topic', topic);
+    if (options.assets)
+        (0, banner_1.printKV)('Assets', options.assets);
+    if (options.method)
+        (0, banner_1.printKV)('Method', options.method);
+    console.log();
+    (0, banner_1.printStep)(1, 7, 'Planning research strategy...');
+    const plan = await planResearch(topic, options, config);
+    logger.info(`[EULER] Plan: ${JSON.stringify(plan)}`);
+    console.log();
+    (0, banner_1.printKV)('Title', plan.title);
+    (0, banner_1.printKV)('Methodology', plan.methodology);
+    (0, banner_1.printKV)('Type', plan.methodType);
+    (0, banner_1.printKV)('Steps', plan.analysisSteps.join(chalk_1.default.hex('#0EA5E9')(' \u2192 ')));
+    console.log();
+    (0, project_1.updateProject)(projectId, { method: plan.methodology });
+    if (options.dryRun) {
+        (0, banner_1.printSuccess)('Dry run complete. Plan generated without execution.');
+        return {
+            success: true, projectId, title: plan.title,
+            figureCount: 0, duration: Date.now() - startTime, stages,
+        };
+    }
+    (0, banner_1.printStep)(2, 7, 'Gauss \u2014 Literature Gap Analysis');
+    (0, project_1.updateProject)(projectId, { status: 'gauss', lastStage: 'gauss' });
+    const gaussStart = Date.now();
+    let gapAnalysis;
+    try {
+        gapAnalysis = await (0, gauss_1.runGauss)(topic, config, logger);
+        governor.evaluate({ stage: 'gauss', success: gapAnalysis.success });
+        stages.gauss = { success: gapAnalysis.success, duration: Date.now() - gaussStart };
+        if (gapAnalysis.success) {
+            (0, project_1.updateProject)(projectId, { gapAnalysis: { title: gapAnalysis.suggestedTitle, gaps: gapAnalysis.gaps.length, papers: gapAnalysis.totalPapersAnalyzed } });
+        }
+    }
+    catch (err) {
+        logger.error(`[EULER] Gauss failed: ${err.message}`);
+        governor.evaluate({ stage: 'gauss', success: false, output: err.message });
+        gapAnalysis = { success: false, topic, totalPapersAnalyzed: 0, sourcesUsed: [], sourcesFailed: [], gaps: [], recommendedGap: null, suggestedTitle: topic, suggestedAbstract: '', suggestedContributions: [], literatureSynthesis: '', thematicClusters: [], scientificLandscape: { dominantMethods: [], commonDatasets: [], sharedLimitations: [], futureDirections: [] }, bibtexBlock: '', papers: [] };
+        stages.gauss = { success: false, duration: Date.now() - gaussStart };
+    }
+    console.log();
+    (0, banner_1.printStep)(3, 7, 'Turing \u2014 Data Collection');
+    (0, project_1.updateProject)(projectId, { status: 'turing', lastStage: 'turing' });
+    const turingStart = Date.now();
+    let dataResult;
+    try {
+        dataResult = await (0, turing_1.runTuring)(topic, options.assets, plan.methodology, !!options.hf, projectId, config, logger, gapAnalysis);
+        governor.evaluate({ stage: 'turing', success: dataResult.success });
+        stages.turing = { success: dataResult.success, duration: Date.now() - turingStart };
+    }
+    catch (err) {
+        logger.error(`[EULER] Turing failed: ${err.message}`);
+        governor.evaluate({ stage: 'turing', success: false, output: err.message });
+        dataResult = { success: false, datasets: [], totalRows: 0, sources: [], errors: [err.message] };
+        stages.turing = { success: false, duration: Date.now() - turingStart };
+    }
+    console.log();
+    if (!dataResult.success || dataResult.datasets.length === 0) {
+        (0, banner_1.printSection)('Pipeline Halted');
+        console.log(chalk_1.default.red('  No data collected. Cannot proceed with analysis.'));
+        (0, project_1.updateProject)(projectId, { status: 'failed' });
+        return {
+            success: false, projectId, title: plan.title,
+            figureCount: 0, duration: Date.now() - startTime, stages,
+        };
+    }
+    (0, banner_1.printStep)(4, 7, 'Newton \u2014 Dataset Construction');
+    (0, project_1.updateProject)(projectId, { status: 'newton', lastStage: 'newton' });
+    const newtonStart = Date.now();
+    let datasetResult;
+    try {
+        datasetResult = await (0, newton_1.runNewton)(topic, projectId, config, logger, {
+            datasets: dataResult.datasets.map((d) => ({
+                filename: d.filename, filePath: d.filePath,
+                columns: d.columns, rows: d.rows,
+            })),
+        });
+        governor.evaluate({ stage: 'newton', success: datasetResult.success });
+        stages.newton = { success: datasetResult.success, duration: Date.now() - newtonStart };
+    }
+    catch (err) {
+        logger.error(`[EULER] Newton failed: ${err.message}`);
+        governor.evaluate({ stage: 'newton', success: false, output: err.message });
+        const fallbackDs = dataResult.datasets[0];
+        datasetResult = {
+            success: true,
+            finalDatasetPath: fallbackDs.filePath,
+            rows: fallbackDs.rows,
+            columns: fallbackDs.columns,
+            description: 'Raw dataset (Newton fallback)',
+            transformations: [],
+            dataDictionary: {},
+        };
+        stages.newton = { success: false, duration: Date.now() - newtonStart };
+    }
+    console.log();
+    (0, banner_1.printStep)(5, 7, 'Fisher \u2014 Empirical Analysis');
+    (0, project_1.updateProject)(projectId, { status: 'fisher', lastStage: 'fisher' });
+    const fisherStart = Date.now();
+    let analysisResult;
+    try {
+        analysisResult = await (0, fisher_1.runFisher)(topic, plan.methodology, projectId, config, logger, {
+            finalDatasetPath: datasetResult.finalDatasetPath,
+            columns: datasetResult.columns,
+            rows: datasetResult.rows,
+            dataDictionary: datasetResult.dataDictionary,
+        }, gapAnalysis);
+        governor.evaluate({
+            stage: 'fisher', success: analysisResult.success,
+            figuresGenerated: analysisResult.figures.length,
+        });
+        stages.fisher = { success: analysisResult.success, duration: Date.now() - fisherStart };
+    }
+    catch (err) {
+        logger.error(`[EULER] Fisher failed: ${err.message}`);
+        governor.evaluate({ stage: 'fisher', success: false, output: err.message });
+        analysisResult = { success: false, models: [], figures: [], tables: [], summary: '', diagnostics: [] };
+        stages.fisher = { success: false, duration: Date.now() - fisherStart };
+    }
+    console.log();
+    (0, banner_1.printStep)(6, 7, 'Euler \u2014 Writing Research Paper');
+    (0, project_1.updateProject)(projectId, { status: 'writing', lastStage: 'euler_write' });
+    const writeStart = Date.now();
+    let paperResult;
+    try {
+        paperResult = await (0, generator_1.generatePaper)({
+            topic,
+            title: gapAnalysis.suggestedTitle || plan.title,
+            abstract: gapAnalysis.suggestedAbstract || '',
+            contributions: gapAnalysis.suggestedContributions || [],
+            methodology: plan.methodology,
+            methodType: plan.methodType,
+            literatureSynthesis: gapAnalysis.literatureSynthesis || '',
+            bibtexBlock: gapAnalysis.bibtexBlock || '',
+            dataDescription: {
+                sources: dataResult.sources,
+                totalRows: dataResult.totalRows,
+                datasets: dataResult.datasets,
+                transformations: datasetResult.transformations,
+            },
+            analysisResults: analysisResult,
+            gapAnalysis,
+        }, projectId, config, logger);
+        governor.evaluate({ stage: 'euler_write', success: paperResult.success });
+        stages.euler_write = { success: paperResult.success, duration: Date.now() - writeStart };
+    }
+    catch (err) {
+        logger.error(`[EULER] Paper generation failed: ${err.message}`);
+        governor.evaluate({ stage: 'euler_write', success: false, output: err.message });
+        paperResult = { success: false, pdfPath: '', pageCount: 0, compilationLog: err.message };
+        stages.euler_write = { success: false, duration: Date.now() - writeStart };
+    }
+    console.log();
+    (0, banner_1.printStep)(7, 7, 'Finalizing');
+    const totalDuration = Date.now() - startTime;
+    (0, project_1.updateProject)(projectId, {
+        status: paperResult.success ? 'complete' : 'failed',
+        pdfPath: paperResult.pdfPath,
+        figureCount: analysisResult.figures.length,
+        pageCount: paperResult.pageCount,
+        lastStage: 'complete',
+    });
+    const govState = governor.getState();
+    logger.info(`[EULER] Governor final state: confidence=${govState.confidence.toFixed(2)}, profile=${govState.profile}`);
+    if (paperResult.success) {
+        const summaryLines = [
+            `${chalk_1.default.hex('#94A3B8')('Paper')}       ${chalk_1.default.white(gapAnalysis.suggestedTitle || plan.title)}`,
+            paperResult.pdfPath ? `${chalk_1.default.hex('#94A3B8')('PDF')}         ${chalk_1.default.white(paperResult.pdfPath)}` : '',
+            `${chalk_1.default.hex('#94A3B8')('Pages')}       ${chalk_1.default.white(String(paperResult.pageCount))}`,
+            `${chalk_1.default.hex('#94A3B8')('Figures')}     ${chalk_1.default.white(String(analysisResult.figures.length))}`,
+            `${chalk_1.default.hex('#94A3B8')('Models')}      ${chalk_1.default.white(String(analysisResult.models.length))}`,
+            `${chalk_1.default.hex('#94A3B8')('Duration')}    ${chalk_1.default.white((0, logger_1.formatDuration)(totalDuration))}`,
+            `${chalk_1.default.hex('#94A3B8')('Confidence')}  ${chalk_1.default.white(`${(govState.confidence * 100).toFixed(0)}%`)}`,
+            '',
+            ...Object.entries(stages).map(([stage, info]) => {
+                const icon = info.success ? chalk_1.default.hex('#22C55E')('\u2714') : chalk_1.default.hex('#EF4444')('\u2718');
+                return `  ${icon} ${chalk_1.default.hex('#94A3B8')(stage.padEnd(14))} ${chalk_1.default.hex('#64748B')((0, logger_1.formatDuration)(info.duration))}`;
+            }),
+        ].filter(Boolean);
+        (0, banner_1.printSummaryBox)(summaryLines, true);
+    }
+    else {
+        const summaryLines = [
+            chalk_1.default.hex('#F59E0B')('Paper generation failed'),
+            `${chalk_1.default.hex('#94A3B8')('Duration')}  ${chalk_1.default.white((0, logger_1.formatDuration)(totalDuration))}`,
+            '',
+            ...Object.entries(stages).map(([stage, info]) => {
+                const icon = info.success ? chalk_1.default.hex('#22C55E')('\u2714') : chalk_1.default.hex('#EF4444')('\u2718');
+                return `  ${icon} ${chalk_1.default.hex('#94A3B8')(stage.padEnd(14))} ${chalk_1.default.hex('#64748B')((0, logger_1.formatDuration)(info.duration))}`;
+            }),
+        ];
+        (0, banner_1.printSummaryBox)(summaryLines, false);
+    }
+    return {
+        success: paperResult.success,
+        projectId,
+        title: gapAnalysis.suggestedTitle || plan.title,
+        pdfPath: paperResult.pdfPath,
+        figureCount: analysisResult.figures.length,
+        pageCount: paperResult.pageCount,
+        duration: totalDuration,
+        stages,
+    };
+}
+async function planResearch(topic, options, config) {
+    const response = await (0, llm_1.callLLM)(config, `You are Euler, the master research orchestrator of AutoScholar.
+Plan a comprehensive research study for the given topic.
+
+Classify the methodology type:
+- econometrics: OLS, IV, GMM, panel data, GARCH, VAR
+- statistics: hypothesis testing, ANOVA, chi-square
+- ml: random forest, XGBoost, neural networks
+- ai: deep learning, NLP, computer vision
+
+Respond as JSON:
+{
+  "title": "Full paper title",
+  "methodology": "Specific method name (e.g., DCC-GARCH, Panel Fixed Effects)",
+  "methodType": "econometrics|statistics|ml|ai",
+  "dataRequirements": ["Type of data needed"],
+  "analysisSteps": ["Step 1", "Step 2"],
+  "expectedSections": ["introduction", "literature_review", "methodology", "data", "results", "discussion", "conclusion"],
+  "estimatedTime": "20-30 minutes"
+}`, `Topic: ${topic}\nAssets: ${options.assets || 'auto'}\nPreferred method: ${options.method || 'auto'}\nHigh-frequency: ${options.hf || false}`, { maxTokens: 2048 });
+    const parsed = (0, llm_1.parseJsonResponse)(response);
+    if (parsed)
+        return parsed;
+    return {
+        title: topic,
+        methodology: options.method || 'OLS',
+        methodType: 'econometrics',
+        dataRequirements: ['Financial data', 'Macroeconomic data'],
+        analysisSteps: ['Data collection', 'Data preparation', 'Model estimation', 'Robustness checks'],
+        expectedSections: ['introduction', 'literature_review', 'methodology', 'data', 'results', 'discussion', 'conclusion'],
+        estimatedTime: '20-30 minutes',
+    };
+}