# DefeatBeta-API Tutorial Notebook

An interactive Jupyter notebook comparing **DefeatBeta-API** vs **Yahoo Finance** for financial data analysis.

## 📚 What's Included

### `defeatbeta_tutorial.ipynb`
A comprehensive 12-section interactive notebook covering:

1. **Quick Performance Test** - Compare query speeds
2. **Price Data Comparison** - OHLCV data structures
3. **Valuation Metrics** - TTM EPS, P/E ratios, Market Cap (historical!)
4. **Financial Statements** - Income statements, balance sheets, cash flows
5. **Financial Ratios** - ROE, ROIC, WACC with full time-series
6. **Growth & Margin Metrics** - YoY growth and margin analysis
7. **Earnings Transcripts** - Unique feature! Full transcript access
8. **Revenue Breakdown** - Unique feature! By segment and geography
9. **DCF Valuation** - Unique feature! Automated Excel output
10. **Interactive Stock Analysis** - Explore any stock symbol
11. **Stock Comparison** - Compare multiple stocks side-by-side
12. **Complete Method Reference** - All available API methods

## 🚀 How to Use

### Option 1: Run the notebook directly
```bash
./run_notebook.sh
```

### Option 2: Run with uv
```bash
uv run jupyter notebook defeatbeta_tutorial.ipynb
```

### Option 3: Convert to Python script
```bash
uv run jupyter nbconvert --to script defeatbeta_tutorial.ipynb
uv run python defeatbeta_tutorial.py
```

## 📦 Requirements

```bash
uv add defeatbeta-api jupyter
```

## 🎯 Key Features Demonstrated

### DefeatBeta-API Unique Features:
- ✅ **Earnings Call Transcripts** - Access full transcripts by quarter
- ✅ **Revenue Segmentation** - Breakdown by product/segment/geography
- ✅ **Automated DCF** - Professional Excel valuation models
- ✅ **Historical Financial Ratios** - Time-series for ROE, ROIC, WACC
- ✅ **AI-Powered Analysis** - LLM analysis of transcripts
- ✅ **No Rate Limits** - Hugging Face hosted data

### Comparison with Yahoo Finance:
- DefeatBeta: Historical analysis, financial modeling, no rate limits
- Yahoo Finance: Real-time data, analyst consensus, larger ecosystem

## 📊 Example Output

```python
# Stock Comparison
Symbol   Price    P/E    Market Cap    ROE     Rev Growth
AAPL     $270.23  31.2   $4.1T        10.2%   16.7%
MSFT     $420.00  35.1   $3.1T        31.1%   20.2%
GOOGL    $341.68  31.6   $4.1T        8.6%    22.3%
NVDA     $201.68  41.2   $4.9T        31.1%   73.2%
```

## 🧪 Exercises

Try these challenges in the notebook:

1. **Find Undervalued Stocks** - P/E < 20 but ROE > 15%
2. **Growth Analysis** - Compare NVDA vs AMD
3. **DCF Valuation** - Compare fair value estimates
4. **Revenue Mix** - Track Apple's services growth
5. **Transcript Mining** - Extract sentiment from earnings calls

## 📖 Documentation

- [DefeatBeta-API GitHub](https://github.com/defeat-beta/defeatbeta-api)
- [DuckDB Documentation](https://duckdb.org/docs)
- [Financial Analysis Examples](doc/api/Value_Examples.md)

## ⚠️ Notes

- Data is updated daily (batch on HuggingFace)
- Real-time data requires Yahoo Finance
- AI features need `OPENAI_API_KEY` set
- Some features require Windows WSL/Docker (DuckDB dependency)

## 🎓 Learning Path

1. Start with **Section 1-2** to understand data structures
2. Move to **Section 3-5** for valuation and ratios
3. Explore **Section 7-9** for unique features
4. Complete **Section 10-11** for practical analysis
5. Reference **Section 12** for complete API

---

**Created:** 2026-04-25
**Version:** 0.0.45
**Author:** Interactive Tutorial