_         _         ____       _           _
    / \  _   _| |_ ___  / ___|  ___| |__   ___ | | __ _ _ __
   / _ \| | | | __/ _ \ \___ \ / __| '_ \ / _ \| |/ _` | '__|
  / ___ \ |_| | || (_) | ___) | (__| | | | (_) | | (_| | |
 /_/   \_\__,_|\__\___/ |____/ \___|_| |_|\___/|_|\__,_|_|

Autonomous Scientific Research Agent

Generate publication-ready academic papers — entirely from your terminal.

Install  •  Quick Start  •  How It Works  •  Data Sources  •  API Keys

 ╭──────────────────────────────────────────────╮
 │  Welcome to AutoScholar                      │
 │  A quant researcher + economist + data       │
 │  scientist living inside your terminal.      │
 ╰──────────────────────────────────────────────╯

  ◆ Pre-flight Checks
  ──────────────────────────────────────────────

  ✔ Python (python3) — 9 packages ready
  ✔ API keys — 5 configured

  ████████░░░░░░░░░░░░  29%  Gauss — Literature
  ████████████████░░░░  71%  Fisher — Analysis
  ████████████████████ 100%  Finalizing

 ╔═══════════  Research Complete  ════════════╗
 ║ ✔ Paper generated successfully             ║
 ║                                            ║
 ║ Title     Volatility Spillovers Between    ║
 ║           Crypto and Commodities           ║
 ║ Pages     72                               ║
 ║ Figures   24                               ║
 ║ Duration  18m 42s                          ║
 ╚════════════════════════════════════════════╝

Why AutoScholar?

Most research tools help with one step — search papers, fetch data, or run a model. AutoScholar handles the entire pipeline autonomously:

| | Traditional Workflow | With AutoScholar | |---|---|---| | Literature Review | Hours of manual searching | 250M+ papers searched in minutes | | Data Collection | Writing API scripts by hand | Auto-fetched from 12+ sources | | Analysis | Manually coding models | GARCH, OLS, Panel — auto-generated | | Paper Writing | Weeks of drafting | 8 sections written in LaTeX | | Figures | One-by-one in matplotlib | 20+ publication-quality figures | | PDF | Manual LaTeX compilation | Compiled automatically |

One command. One paper. Fully reproducible.

📦 Install

npm install -g autoscholar-cli

Then install the Python scientific stack:

pip3 install pandas numpy scipy matplotlib seaborn scikit-learn statsmodels arch linearmodels

Install TeX Live or MacTeX to compile papers to PDF. Without it, AutoScholar saves .tex source files that you can compile yourself.

# macOS
brew install --cask mactex-no-gui

# Ubuntu / Debian
sudo apt install texlive-full

🚀 Quick Start

# Interactive mode — guided menu
autoscholar

# Direct execution
autoscholar run --topic "Volatility spillovers between crypto and commodities 2015-2025"

# With all options
autoscholar run \
  --topic "Factor momentum in US equities" \
  --assets "AAPL,MSFT,GOOG,AMZN" \
  --method "DCC-GARCH" \
  --hf      # high-frequency data

# Dry run — preview the plan without executing
autoscholar run --topic "..." --dry

On first launch, a setup wizard walks you through API key configuration.

🧠 How It Works

AutoScholar orchestrates five specialized AI agents through a 7-stage pipeline, supervised by a rule-based Governor Engine that handles errors, retries, and quality control.

  ┌─────────────────────────────────────────────────────────────┐
  │                                                             │
  │   📋 Plan  →  📚 Gauss  →  📊 Turing  →  🔧 Newton       │
  │                                                             │
  │         →  🔬 Fisher  →  ✍️  Write  →  📄 Compile          │
  │                                                             │
  │   ┌───────────────────────────────────────────────────┐     │
  │   │  Governor Engine — profiles, retries, confidence  │     │
  │   └───────────────────────────────────────────────────┘     │
  └─────────────────────────────────────────────────────────────┘

The Five Agents

Governor Engine

A zero-LLM decision engine monitors every step:

| Feature | Description | |---------|-------------| | Profile switching | Auto-switches to academic_figures during Fisher, jf_rewrite during writing, debug_recovery on Python errors, latex_fallback on compilation errors | | Retry budgets | 5 Python retries, 3 data retries, 3 LaTeX retries — then graceful finalization | | Confidence scoring | Starts at 0.8, adjusts on every success (+0.02) and failure (-0.05 to -0.25) | | Error pattern matching | Detects ModuleNotFoundError, SingularMatrix, MemoryError, etc. and injects targeted recovery directives |

🖥️ Commands

| Command | Description | |:--------|:------------| | autoscholar | Launch interactive mode with guided menu | | autoscholar run | Execute the full research pipeline | | autoscholar config | Add, edit, or validate API keys | | autoscholar outputs | Browse all generated papers and figures | | autoscholar resume <id> | Resume an interrupted project |

Run Flags

| Flag | Description | Example | |:-----|:------------|:--------| | --topic | Research topic (required) | "Crypto volatility spillovers" | | --assets | Comma-separated tickers | "BTC,ETH,WTI,GOLD" | | --method | Econometric method | "DCC-GARCH", "OLS", "VAR" | | --hf | Use high-frequency intraday data | — | | --dry | Show execution plan only | — |

🌐 Data Sources

✅ = No API key needed    🔑 = API key required

🔐 API Keys

Keys are stored locally in ~/.autoscholar/.env. Manage them anytime:

autoscholar config

| Key | Status | What it unlocks | |:----|:------:|:----------------| | ANTHROPIC_API_KEY | Required | Powers all 5 AI agents (Claude) | | FMP_API_KEY | Recommended | Stocks, fundamentals, ratios, SEC filings, ESG | | EODHD_API_KEY | Recommended | Deep historical prices, intraday, options Greeks | | FRED_API_KEY | Recommended | GDP, CPI, unemployment, rates — 840K+ series | | SERPER_API_KEY | Optional | Web search for broader research context | | SERPAPI_API_KEY | Optional | Google Scholar for academic paper discovery | | FIRECRAWL_API_KEY | Optional | Scrape web pages, extract datasets from PDFs | | TAVILY_API_KEY | Optional | AI-powered search with summarization | | EXA_API_KEY | Optional | Semantic similarity search for papers & data |

📁 Output Structure

Every project is fully self-contained and reproducible:

~/.autoscholar/projects/AS-20250410-x8k2m1/
│
├── data/                          ← Raw & processed datasets
│   ├── fmp_prices.csv
│   ├── fred_macro.csv
│   └── final_dataset.csv
│
├── code/                          ← All generated Python scripts
│   ├── newton_build_dataset.py
│   └── fisher_analysis.py
│
├── output/                        ← Publication artifacts
│   ├── paper.tex
│   ├── paper.pdf
│   ├── references.bib
│   └── figures/
│       ├── correlation_matrix.png
│       ├── time_series.png
│       ├── garch_volatility.png
│       ├── ols_diagnostics.png
│       ├── scatter_matrix.png
│       └── ...  (20+ figures)
│
├── logs/                          ← Full execution logs
│   └── run_2025-04-10T14-30-00.log
│
└── meta.json                      ← Project metadata & state

🔬 Supported Methods

| Method | Description | |--------|-------------| | OLS / Robust SE | Ordinary least squares with HC1-HC3 standard errors | | IV / 2SLS | Instrumental variables estimation | | GMM | Generalized method of moments | | Panel FE / RE | Fixed and random effects with Hausman test | | Fama-MacBeth | Two-pass cross-sectional regression | | GARCH / DCC-GARCH | Volatility modeling and dynamic correlations | | VAR / VECM | Vector autoregression and error correction | | Granger Causality | Temporal precedence testing | | Local Projections | Impulse response estimation |

| Method | Description | |--------|-------------| | t-tests | One-sample, two-sample, paired | | ANOVA | One-way and two-way analysis of variance | | Chi-square | Independence and goodness-of-fit | | Mann-Whitney | Non-parametric rank test | | Kruskal-Wallis | Non-parametric ANOVA | | Bootstrap CI | Confidence intervals via resampling |

| Method | Description | |--------|-------------| | Random Forest | Ensemble tree-based classification/regression | | XGBoost | Gradient boosting with regularization | | LightGBM | Fast gradient boosting for large datasets | | SVM / SVR | Support vector machines | | ElasticNet | L1 + L2 regularized regression | | PCA | Dimensionality reduction | | k-means | Unsupervised clustering | | SHAP | Model interpretability and feature importance |

⚙️ Requirements

| Dependency | Version | Required | |:-----------|:--------|:--------:| | Node.js | >= 18 | Yes | | Python | >= 3.9 | Yes | | Anthropic API key | — | Yes | | LaTeX (TeX Live / MacTeX) | 2024+ | Optional |

💡 Philosophy

A quant researcher + economist + data scientist living inside your terminal.

| | | |:---:|:---| | Autonomous | End-to-end paper generation — no manual steps | | Reproducible | All code, data, and logs saved per project | | Modular | Five specialized agents with clean interfaces | | Local-first | Runs on your machine — no cloud dependency | | Premium | Beautiful terminal UX inspired by Vercel & Stripe |

Built with   Claude  ·  OpenAlex  ·  arXiv  ·  FRED

MIT License