InvestorMate 🤖📈

AI-Powered Stock Analysis in Python — Terminal CLI + Student Edition (v0.6.0)

InvestorMate is the only Python package you need for comprehensive stock analysis - from a keyless terminal CLI to data fetching, AI-powered insights, portfolio diversification, news sentiment, strategy backtesting, and custom screening.

Just want to run it: pip install investormate then investormate quote AAPL

✨ Features

• Terminal CLI (v0.6.0) - Keyless investormate quote / investormate analyze with human and --json output
• AI-Powered Analysis - Ask natural language questions about any stock using OpenAI, Claude, Gemini, or OpenRouter (optional [ai] extra)
• Comprehensive Stock Data - Real-time prices, financials, news, and SEC filings via yfinance
• 20+ Technical Indicators - SMA, EMA, RSI, MACD, Bollinger Bands, ATR, ADX, Ichimoku, and more (native, no extra deps)
• Advanced Financial Ratios - 40+ ratios including ROIC, WACC, Equity Multiplier, and TTM metrics
• Valuation - DCF (Discounted Cash Flow), comparable companies (P/E, EV/EBITDA, P/S), fair value summary & sensitivity table
• Earnings Call Transcripts - Access earnings dates and transcript infrastructure (expandable)
• Stock Screening - Value, growth, dividend, custom filters, Magic Formula, CAN SLIM-style screen, dividend growth (Aristocrat-style streak)
• Portfolio Analysis - Value-weighted performance, Sharpe/Sortino, Calmar, max drawdown, beta, VaR (historical/parametric), Monte Carlo terminal value
• Fetch cache - In-memory TTL cache + rate limiting for yfinance; stock.refresh() busts cache per ticker
• Earnings API - stock.earnings for calendar, estimates, EPS surprise history, trends
• Beneish M-Score - Full eight-variable model when multi-period statements are available (manipulation risk)
• Batch & peers - Stock.batch([...]) for many tickers; stock.peers and stock.compare_with() for peer tables
• Strategy templates - MomentumStrategy, MeanReversionStrategy, SMACrossoverStrategy for the built-in backtest runner
• Market Summaries - Real-time data for US, Asian, European, crypto, and commodity markets
• Pretty Formatting - Beautiful CLI output for financial statements and ratios
• Student Edition - TVM calculator, bond pricing & duration, Black-Scholes & Greeks, financial statement analysis, CAPM regression, educational layer (explain(), show_work(), CFA tags), practice problems, Markdown/Excel export

🚀 Quick Start

Just want to run it:

pip install investormate
investormate quote AAPL          # live price snapshot — no API key
investormate analyze MSFT        # fundamentals + key ratios
investormate analyze AAPL --json # machine-readable output for scripts

Or use the Python API (same package, no extra install for stock data):

from investormate import Stock

stock = Stock("AAPL")
print(f"Price: ${stock.price}")
print(f"P/E Ratio: {stock.ratios.pe}")
print(f"ROIC: {stock.ratios.roic}")  # Advanced ratios
print(f"TTM EPS: {stock.ratios.ttm_eps}")  # Trailing metrics
print(f"RSI: {stock.indicators.rsi()}")

# Batch load tickers (skips bad symbols with a warning)
stocks = Stock.batch(["AAPL", "MSFT", "GOOGL"], skip_invalid=True)

# Beneish detail (8 indices when statements allow)
detail = stock.scores.beneish_m_score_detail()
print(detail.get("indices"), detail.get("score"))

📦 Installation

# Basic installation (CLI + stock data — no API key required)
pip install investormate

# With AI providers (OpenAI / Anthropic / Gemini / OpenRouter SDKs)
pip install investormate[ai]

# With Excel export support
pip install investormate[export]

# Everything
pip install investormate[all]

# With development dependencies
pip install investormate[dev]

🔑 API Keys

Stock quotes and analysis work without any API keys. AI features need one provider key and the [ai] extra:

pip install investormate[ai]

• OpenAI: Get your API key at https://platform.openai.com/api-keys
• Anthropic Claude: Get your API key at https://console.anthropic.com/
• Google Gemini: Get your API key at https://ai.google.dev/
• OpenRouter: Get your API key at https://openrouter.ai/keys (one key → hundreds of models)

You only need one API key to use the AI features.

from investormate import Investor

# OpenRouter gives access to many models via a single key
investor = Investor(
    openrouter_api_key="sk-or-...",
    openrouter_model="anthropic/claude-3.5-sonnet",  # optional; defaults to openai/gpt-4o
)
result = investor.ask("AAPL", "Is Apple undervalued compared to its peers?")

📚 Documentation

• Quickstart Guide - Get started in 5 minutes
• API Reference - Complete API documentation
• Data Policy - Price adjustment, NaN handling, and data provenance
• AI Providers Guide - OpenAI, Claude, and Gemini setup
• Caching - TTL cache and rate limiting
• Data Providers - Swap yfinance for a custom data source
• Earnings - Estimates and surprise history
• Risk - VaR and Monte Carlo
• Strategy templates - Built-in backtest strategies
• Examples - Working code examples

🗺️ Roadmap & Contributing

• ROADMAP.md — Our vision to build a Bloomberg Terminal–grade package. See planned features, phases, and priorities.
• CONTRIBUTING.md — Want to contribute? Start here for development setup, your first PR, and guidelines.

New to open source? Check CONTRIBUTING.md for step-by-step guidance on making your first contribution.

🎯 Why InvestorMate?

💡 Examples

Stock Analysis

from investormate import Stock
from investormate.utils import print_ratios_table

stock = Stock("TSLA")

# Basic info
print(stock.price)
print(stock.market_cap)
print(stock.sector)

# Financial statements
income_stmt = stock.income_statement
balance_sheet = stock.balance_sheet
cash_flow = stock.cash_flow

# Advanced ratios and TTM metrics
print(f"ROIC: {stock.ratios.roic}")
print(f"WACC: {stock.ratios.wacc}")
print(f"TTM Revenue: {stock.ratios.ttm_revenue}")
print(f"TTM EPS: {stock.ratios.ttm_eps}")

# Valuation (DCF, comps, fair value summary)
dcf = stock.valuation.dcf(growth_rate=0.05)
comps = stock.valuation.comps(peers=["MSFT", "GOOGL"])
summary = stock.valuation.summary(peers=["MSFT", "GOOGL"])
print(f"DCF fair value: ${dcf.get('fair_value_per_share')}")
print(f"Summary: {summary.get('recommendation')}")

# Pretty print all ratios
print_ratios_table(stock.ratios.all())

# DuPont ROE Analysis
dupont = stock.ratios.dupont_roe
print(dupont)

# Earnings transcripts (infrastructure ready)
transcripts_list = stock.earnings_transcripts.get_transcripts_list()

# Earnings calendar, estimates, surprise history (v0.3.0)
print(stock.earnings.calendar())
print(stock.earnings.surprise_history()[-3:])

# Historical data
df = stock.history(period="1y", interval="1d")

# Bust fetch cache for this ticker (v0.3.0)
stock.refresh()

AI-Powered Insights

from investormate import Investor

investor = Investor(openai_api_key="sk-...")

# Ask questions
result = investor.ask("NVDA", "What are the key revenue drivers?")

# Compare stocks
comparison = investor.compare(
    ["AAPL", "GOOGL", "MSFT"],
    "Which has the best growth prospects?"
)

# Analyze documents
result = investor.analyze_document(
    ticker="TSLA",
    url="https://example.com/earnings-report.pdf",
    question="Summarize Q4 earnings highlights"
)

Technical Analysis

from investormate import Stock

stock = Stock("AAPL")
df = stock.history(period="6mo")

# Add indicators
df = stock.add_indicators(df, [
    "sma_20", "sma_50", "rsi_14", "macd", "bbands"
])

# Or use individual methods
sma_20 = stock.indicators.sma(20)
rsi = stock.indicators.rsi(14)
macd = stock.indicators.macd()

Stock Screening

from investormate import Screener

screener = Screener()

# Pre-built screens
value_stocks = screener.value_stocks(pe_max=15, pb_max=1.5)
growth_stocks = screener.growth_stocks(revenue_growth_min=20)
dividend_stocks = screener.dividend_stocks(yield_min=3.0)

# Custom screening
results = screener.filter(
    market_cap_min=1_000_000_000,
    pe_ratio=(10, 25),
    roe_min=15,
    sector="Technology"
)

# Magic Formula (ROIC + earnings yield ranks) — set your own universe
magic = screener.magic_formula(top_n=20, min_market_cap=300_000_000)
print(magic)

# CAN SLIM-style and dividend growth screens (v0.3.0)
can_slim = screener.can_slim(top_n=10, min_score=3)
aristocrats = screener.dividend_aristocrats(min_years=15, min_yield=2.0, top_n=10)
print(can_slim, aristocrats)

Portfolio Analysis

from investormate import Portfolio

portfolio = Portfolio({
    "AAPL": 10,
    "GOOGL": 5,
    "MSFT": 15,
    "TSLA": 8
})

print(f"Total Value: ${portfolio.value:,.2f}")
print(f"Sharpe Ratio: {portfolio.sharpe_ratio:.2f}")
print(f"Sortino: {portfolio.sortino_ratio}, Calmar: {portfolio.calmar_ratio}")
print(f"Max drawdown %: {portfolio.max_drawdown}, Beta vs SPY: {portfolio.beta()}")
print(f"Allocation: {portfolio.allocation}")

# VaR and Monte Carlo (v0.3.0)
print(portfolio.var(confidence=0.95, method="historical"))
print(portfolio.monte_carlo_simulation(n=500, horizon=126, seed=1))

Strategy templates (backtest)

from investormate import Backtest, SMACrossoverStrategy

bt = Backtest(
    strategy=SMACrossoverStrategy,
    ticker="MSFT",
    start_date="2020-01-01",
    end_date="2023-01-01",
    initial_capital=10_000,
)
print(bt.run().summary())

Peer comparison

from investormate import Stock

stock = Stock("AAPL")
print(stock.peers[:5])
table = stock.compare_with(peers=["MSFT", "GOOGL", "META"])
print(table["metrics"])

Valuation (DCF & Comps)

from investormate import Stock

stock = Stock("AAPL")

# DCF with terminal value
dcf = stock.valuation.dcf(growth_rate=0.05, terminal_growth=0.02, years=5)
print(f"DCF fair value: ${dcf.get('fair_value_per_share')}")

# Comparable companies (peer multiples)
comps = stock.valuation.comps(peers=["MSFT", "GOOGL", "META"])
print(f"Median P/E: {comps.get('median_pe')}")
print(f"Implied value (P/E): ${comps.get('implied_value_pe')}")

# Combined fair value summary
summary = stock.valuation.summary(peers=["MSFT", "GOOGL"])
print(f"Range: ${summary['fair_value_low']} - ${summary['fair_value_high']}")
print(f"Verdict: {summary['recommendation']}")

# Sensitivity table (growth vs WACC)
sens = stock.valuation.sensitivity()
print(sens["table"])

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for:

• Development setup and first-time contributor guide
• How to find work (roadmap, good first issues)
• Code style, testing, and PR process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

InvestorMate is for educational and research purposes only. It is not financial advice. AI-generated insights may contain errors or hallucinations. Always verify information and consult with a qualified financial advisor before making investment decisions.

🌟 Support

If you find InvestorMate useful, please give it a star on GitHub!

Made with ❤️ by the InvestorMate community