navam-invest


Namenavam-invest JSON
Version 0.1.26 PyPI version JSON
download
home_pageNone
SummaryAI agents and tools for the retail investor
upload_time2025-10-07 14:38:17
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseMIT
keywords ai-agents finance investment retail-investor trading
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            <div align="center">

# 🤖 Navam Invest

**AI-Powered Investment Advisor for Retail Investors**

[![PyPI version](https://badge.fury.io/py/navam-invest.svg)](https://badge.fury.io/py/navam-invest)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/navam-invest)](https://pepy.tech/project/navam-invest)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

[Features](#-features) •
[Quick Start](#-quick-start) •
[Agents](#-specialized-ai-agents) •
[API Sources](#-data-sources) •
[Examples](#-example-interactions) •
[Documentation](#-documentation)

</div>

---

## 🆕 What's New in v0.1.26

**Yahoo Finance + Enhanced SEC EDGAR Integration** - Institutional-grade data at zero cost:

- ✨ **Yahoo Finance Integration**: 11 new tools for real-time quotes, earnings analysis, analyst ratings, institutional holders (FREE, no API key)
- ✨ **Enhanced SEC EDGAR**: 4 new tools for 8-K material events, XBRL company facts, insider transactions (Form 4), flexible filing search
- ✨ **Quill Agent Enhanced**: 22 → 36 tools (+64% capabilities) - Now includes earnings trends, analyst sentiment, ownership tracking
- ✨ **Zero Cost Expansion**: All new tools free & unlimited ($2,400-$10,800/year savings vs. paid alternatives)
- ✨ **Full Backward Compatibility**: Existing agents and workflows unchanged

**New Capabilities**:
- **Earnings Analysis**: Historical EPS surprises, upcoming earnings calendar, analyst estimates
- **Analyst Coverage**: Consensus ratings, price targets, recent upgrades/downgrades
- **Material Events**: 8-K filings for M&A, earnings, management changes, bankruptcy
- **Ownership Intelligence**: Institutional holders, Form 4 insider transactions, 13F filings
- **Market Indices**: S&P 500, Dow Jones, Nasdaq, Russell 2000, VIX (for macro analysis)

See [Integration Docs](backlog/edgar-yahoo-integration.md) for details | Previous: [v0.1.25](backlog/release-0.1.25.md)

---

## 📖 Overview

`navam-invest` brings **institutional-grade portfolio intelligence** to individual retail investors. Built with [LangGraph](https://langchain-ai.github.io/langgraph/) and powered by [Anthropic's Claude](https://www.anthropic.com/claude), it provides **specialized AI agents** that collaborate through **multi-agent workflows** for equity research, systematic screening, macro analysis, and portfolio management—all accessible through an interactive terminal interface.

### Why Navam Invest?

- **🎯 Multi-Agent Workflows**: Coordinated agent collaboration for comprehensive analysis
- **🤖 Specialized Agents**: 6 purpose-built agents (Quill, Screen Forge, Macro Lens, Atlas, Portfolio, Research)
- **📊 Institutional Data**: Yahoo Finance + Enhanced EDGAR + 8 premium APIs (all free tiers)
- **🔒 Privacy-First**: Run locally with your own API keys—your data stays yours
- **💡 Transparent**: Full audit trails and explainable AI reasoning with real-time streaming
- **🆓 Zero Additional Cost**: New Yahoo Finance + EDGAR tools require no API keys
- **🔧 Extensible**: Modular architecture makes it easy to add new agents and workflows

---

## ✨ Features

### 🤖 **Specialized AI Agents** (Powered by LangGraph)

<table>
<tr>
<td width="50%">

#### **Quill - Equity Research** ⭐ *Enhanced v0.1.26*
*Deep fundamental analysis & thesis building*

**NEW Capabilities**:
- ✨ Real-time earnings trends & surprises (Yahoo Finance)
- ✨ Analyst consensus & price targets (Yahoo Finance)
- ✨ Institutional ownership tracking (Yahoo Finance)
- ✨ Material event detection (8-K filings)
- ✨ XBRL structured data extraction
- ✨ Insider transaction patterns (Form 4)

**Core Capabilities**:
- Investment thesis development
- DCF & comparable company valuation
- 5-year historical fundamentals (Tiingo)
- Quarterly earnings tracking
- SEC filings analysis (10-K, 10-Q, 8-K)
- Company-specific news validation
- Dividend history & yield analysis
- **36 specialized tools** (up from 22)

**Command**: `/quill`

**Use Case**: "Analyze AAPL with focus on recent earnings trends and analyst sentiment"

</td>
<td width="50%">

#### **Screen Forge - Equity Screening**
*Systematic stock discovery & idea generation*

**Enhanced Capabilities** (v0.1.26):
- ✨ Earnings momentum screening (consistent beats)
- ✨ Analyst upgrade activity filtering

**Core Capabilities**:
- Multi-factor screening (value, growth, quality)
- Systematic candidate identification
- Weekly watchlist generation
- Factor-based ranking systems
- Sentiment validation (Finnhub + Yahoo)
- Integration with Quill for deep-dives
- **15 specialized tools** (up from 10)

**Command**: `/screen`

**Use Case**: "Screen for stocks with consistent earnings beats and analyst upgrades"

</td>
</tr>
<tr>
<td width="50%">

#### **Macro Lens - Market Strategist**
*Top-down macro analysis & regime identification*

**Enhanced Capabilities** (v0.1.26):
- ✨ Market indices tracking (S&P 500, Nasdaq, VIX)
- ✨ Historical index data for regime analysis

**Core Capabilities**:
- Economic cycle regime analysis (4 phases)
- Yield curve interpretation & recession signals
- Sector allocation guidance based on macro
- Factor recommendations (value/growth, size)
- Inflation, growth, employment tracking
- Fed policy and interest rate analysis
- **13 specialized tools** (up from 11)

**Command**: `/macro`

**Use Case**: "What's the current macro regime and which sectors should I overweight?"

</td>
<td width="50%">

#### **Atlas - Investment Strategist**
*Strategic asset allocation & portfolio construction*

**Core Capabilities**:
- Investment Policy Statement (IPS) development
- Strategic asset allocation frameworks
- Risk tolerance profiling (Conservative/Moderate/Aggressive)
- Macro-driven tactical tilts
- Rebalancing strategies (threshold, calendar, tax-aware)
- Portfolio construction guidance
- **12 specialized tools**

**Command**: `/atlas`

**Use Case**: "Create an IPS for moderate risk tolerance with $100k portfolio"

</td>
</tr>
<tr>
<td width="50%">

#### **Portfolio Analysis** (Legacy)
*Comprehensive portfolio tools*

- Real-time stock quotes & metrics
- Company fundamentals & financial ratios
- News & social sentiment analysis
- SEC filings & institutional holdings
- Multi-criteria stock screening
- Local file reading (CSV, JSON, Excel)
- **24 tools** (backward compatible)

**Command**: `/portfolio`

**Use Case**: "What's the current price and fundamentals of MSFT?"

</td>
<td width="50%">

#### **Market Research** (Legacy)
*Top-down macro analysis*

- Macroeconomic indicators (GDP, CPI, unemployment)
- Treasury yield curves & spreads
- Federal Reserve data (FRED)
- Economic regime detection
- Debt-to-GDP analysis
- Market news & sentiment
- **10 tools**

**Command**: `/research`

**Use Case**: "Show me the Treasury yield curve and economic indicators"

*Note: Will be phased out in favor of Macro Lens agent in v0.2.0*

</td>
</tr>
</table>

### 🔀 **Multi-Agent Workflows**

Coordinated agent collaboration combining specialized expertise:

#### **Investment Analysis Workflow**

**Sequential Orchestration**: Quill → Macro Lens → Synthesis

**How it works**:
1. **Quill** performs bottom-up fundamental analysis
   - Business overview & competitive position
   - Financial health (5-year trends)
   - Valuation (P/E, P/B, DCF fair value)
   - **NEW**: Earnings trends, analyst sentiment
   - Investment thesis with catalysts

2. **Macro Lens** validates timing with top-down analysis
   - Receives Quill's thesis via shared state
   - Assesses current macro regime
   - Evaluates sector positioning
   - Validates entry point timing
   - **NEW**: Market indices regime correlation

3. **Synthesis** combines both perspectives
   - Overall rating: BUY/HOLD/SELL
   - Confidence level: High/Medium/Low
   - Key reasoning from both agents
   - Risk warning & suggested action

**Command**: `/analyze <SYMBOL>`

**Example**:
```
/analyze AAPL

📊 Quill analyzing fundamentals...
  → get_quote: $227.45, P/E 36x, Market Cap $3.5T
  → get_earnings_history: Beat by $0.15 last 3 quarters
  → get_analyst_recommendations: 42 Buy, 8 Hold, 2 Sell
  → get_institutional_holders: BlackRock 6.8%, Vanguard 8.2%

🌍 Macro Lens validating timing...
  → get_market_indices: S&P 500 +12% YTD, VIX 14.2
  → get_treasury_yield_curve: 10Y-2Y inverted -0.54%

🎯 Final Recommendation: HOLD - Medium Confidence
Apple shows strong fundamentals (earnings beats, analyst
support) but late-cycle macro timing suggests cautious
positioning. Dollar-cost average on dips below $210.
```

### 📊 **Data Sources** (36 Tools Across 10+ APIs)

| Data Source | Tools | Purpose | Cost | New in v0.1.26 |
|-------------|-------|---------|------|----------------|
| **Yahoo Finance** 🆕 | 11 | Real-time quotes, earnings, analyst ratings, ownership | **FREE** | ✅ |
| **SEC EDGAR** 🔄 | 9 | Corporate filings (10-K, 10-Q, 8-K), XBRL, insider transactions | **FREE** | ✅ 4 new |
| **Financial Modeling Prep** | 4 | Financial statements, ratios, screening | 250 calls/day | |
| **Tiingo** | 4 | Historical fundamentals (5yr), quarterly data | 50 symbols/hr | |
| **Finnhub** | 5 | News/social/insider sentiment, analyst ratings | 60 calls/min | |
| **Alpha Vantage** | 2 | Stock prices, company overviews | 25-500 calls/day | |
| **FRED (St. Louis Fed)** | 2 | Economic indicators, macro data | Unlimited | |
| **U.S. Treasury** | 4 | Yield curves, treasury rates | Unlimited | |
| **NewsAPI.org** | 3 | Market news, headlines | 100 calls/day | |
| **Anthropic Claude** | - | AI reasoning (Sonnet 4.5) | Pay-as-you-go | |

**Total Free Data**: 7 out of 10 sources require no API key! (Yahoo Finance, SEC, Treasury)

### 💬 **Interactive Terminal UI**

- **Chat Interface**: Natural language interaction with specialized agents
- **Real-time Streaming**: Watch agents think and reason live
- **Multi-Agent Progress**: See workflow transitions and agent collaboration
- **Granular Tool Tracking**: Watch which tools are called with what arguments
- **Markdown Rendering**: Beautiful formatted output with tables
- **Agent Switching**: `/quill`, `/screen`, `/macro`, `/atlas`, `/portfolio`, `/research`
- **Workflow Commands**: `/analyze <SYMBOL>` for multi-agent analysis
- **Command Palette**: Quick access to common actions
- **File Reading**: Analyze local portfolio files

### 🏗️ **Built on Modern Tech**

```
LangGraph (Multi-Agent Orchestration) → LangChain (Tools) → Anthropic Claude (Reasoning)
     ↓
Textual (Terminal UI) + Typer (CLI) + httpx (Async HTTP) + yfinance (Market Data)
```

**Architecture Highlights**:
- **Multi-Agent Workflows**: Sequential orchestration with shared state
- **Specialized Agents**: Purpose-built agents with focused tool sets
- **Tools Registry**: Agent-specific tool mappings for optimal performance
- **ReAct Pattern**: Reasoning + Acting for transparent decision-making
- **Async/Await**: Non-blocking I/O for responsive UI
- **Type Safety**: Full type hints with MyPy strict mode

---

## 🚀 Quick Start

### Prerequisites

- **Python 3.9+** (3.13 recommended)
- **pip** package manager
- API keys (see [Configuration](#configuration))

### Installation

#### Option 1: Install from PyPI (Recommended)

```bash
pip install navam-invest
```

#### Option 2: Install from Source

```bash
git clone https://github.com/navam-io/navam-invest.git
cd navam-invest
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

### Configuration

1. **Copy environment template:**
   ```bash
   cp .env.example .env
   ```

2. **Add your API keys** to `.env`:
   ```bash
   # Required
   ANTHROPIC_API_KEY=sk-ant-...

   # Optional (but recommended for full functionality)
   ALPHA_VANTAGE_API_KEY=your_key_here
   FMP_API_KEY=your_key_here
   TIINGO_API_KEY=your_key_here
   FINNHUB_API_KEY=your_key_here
   FRED_API_KEY=your_key_here
   NEWSAPI_API_KEY=your_key_here

   # No keys needed for Yahoo Finance, SEC EDGAR, U.S. Treasury!
   ```

3. **Get API Keys** (all have free tiers):

   | Service | Link | Free Tier | Required? |
   |---------|------|-----------|-----------|
   | **Anthropic** ⭐ | [console.anthropic.com](https://console.anthropic.com/) | Pay-as-you-go ($3-15/M tokens) | ✅ Required |
   | **Yahoo Finance** 🆕 | - | Unlimited, no key needed | ✅ Built-in |
   | **SEC EDGAR** | - | Unlimited, no key needed | ✅ Built-in |
   | **U.S. Treasury** | - | Unlimited, no key needed | ✅ Built-in |
   | **Alpha Vantage** | [alphavantage.co/support/#api-key](https://www.alphavantage.co/support/#api-key) | 25 calls/day | Optional |
   | **FMP** | [financialmodelingprep.com/developer](https://financialmodelingprep.com/developer) | 250 calls/day | Optional |
   | **Tiingo** | [tiingo.com](https://www.tiingo.com/) | 50 symbols/hr, 5yr history | Optional |
   | **Finnhub** | [finnhub.io/register](https://finnhub.io/register) | 60 calls/min | Optional |
   | **FRED** | [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) | Unlimited | Optional |
   | **NewsAPI** | [newsapi.org/register](https://newsapi.org/register) | 100 calls/day | Optional |

### Usage

#### Launch the Interactive Interface

```bash
navam invest
```

This opens an interactive chat interface with 6 specialized AI agents and multi-agent workflows.

#### Quick Command Reference

| Command | Agent/Workflow | Description |
|---------|----------------|-------------|
| `/analyze <SYMBOL>` | Investment Analysis Workflow | Multi-agent fundamental + macro analysis |
| `/quill` | Quill (Equity Research) | Deep fundamental analysis & thesis building ⭐ *36 tools* |
| `/screen` | Screen Forge | Systematic stock screening & idea generation |
| `/macro` | Macro Lens | Top-down macro analysis & regime identification |
| `/atlas` | Atlas (Investment Strategist) | Strategic asset allocation & IPS development |
| `/portfolio` | Portfolio Analysis | Comprehensive stock & portfolio tools (legacy) |
| `/research` | Market Research | Macroeconomic analysis & treasury data (legacy) |
| `/examples` | - | Show example queries for current agent/workflow |
| `/help` | - | Show all commands |
| `/clear` | - | Clear chat history |
| `/quit` | - | Exit application |

---

## 💡 Example Interactions

### Quill - Equity Research (with Yahoo Finance) 🆕

<details>
<summary><b>📈 Earnings & Analyst Sentiment Analysis</b></summary>

```
You: /quill
You: Analyze AAPL with focus on recent earnings trends and analyst sentiment

Quill (Equity Research):
  → get_quote(symbol=AAPL)
  ✓ AAPL: $227.45, +1.2% (+$2.70), P/E 36x, Market Cap $3.5T

  → get_earnings_history(symbol=AAPL)
  ✓ Earnings history retrieved

  → get_analyst_recommendations(symbol=AAPL)
  ✓ Analyst ratings retrieved

  → get_institutional_holders(symbol=AAPL)
  ✓ Institutional ownership retrieved

**Apple Inc. (AAPL) - Earnings & Sentiment Analysis**

**Earnings Trends** (Last 4 Quarters):

| Quarter | EPS Actual | EPS Estimate | Surprise | Surprise % |
|---------|------------|--------------|----------|------------|
| Q4 2024 | $1.64 | $1.60 | $0.04 | +2.5% |
| Q3 2024 | $1.40 | $1.35 | $0.05 | +3.7% |
| Q2 2024 | $1.53 | $1.50 | $0.03 | +2.0% |
| Q1 2024 | $2.18 | $2.10 | $0.08 | +3.8% |

**Key Observation**: Apple has beaten analyst estimates for 4 consecutive
quarters with an average surprise of +3.0%. This demonstrates consistent
execution and conservative guidance from management.

**Upcoming Earnings**:
- **Date**: January 30, 2025 (estimated)
- **EPS Estimate**: $2.23 (range: $2.18 - $2.28)
- **Revenue Estimate**: $124.5B

**Analyst Sentiment**:

**Ratings Distribution** (52 analysts):
- **Buy/Overweight**: 42 (81%)
- **Hold/Neutral**: 8 (15%)
- **Sell/Underweight**: 2 (4%)

**Price Targets**:
- **Mean Target**: $248 (+9% upside)
- **Median Target**: $245 (+7.7% upside)
- **High Target**: $275 (+21% upside)
- **Low Target**: $180 (-21% downside)

**Recent Rating Changes** (Last 30 days):
- **Wedbush**: Maintained Outperform, raised target $260 → $275
- **Morgan Stanley**: Upgraded Neutral → Overweight, target $240 → $260
- **JPMorgan**: Maintained Overweight, raised target $245 → $265

**Institutional Ownership**:

**Top 5 Holders** (Total: 58.2% institutional ownership):
1. **Vanguard Group**: 8.2% ($287B) - Increased 2.1M shares Q3
2. **BlackRock**: 6.8% ($238B) - Increased 1.5M shares Q3
3. **Berkshire Hathaway**: 5.8% ($203B) - Maintained position
4. **State Street**: 4.1% ($144B) - Increased 850K shares Q3
5. **Fidelity**: 2.3% ($81B) - Decreased 300K shares Q3

**Sentiment Analysis**:

**Bullish Indicators**:
- ✅ 4 consecutive earnings beats (avg +3% surprise)
- ✅ 81% analyst buy ratings (strong consensus)
- ✅ Recent analyst upgrades (3 in last month)
- ✅ Institutional accumulation (+4.4M shares Q3 from top holders)
- ✅ Mean price target implies +9% upside

**Cautionary Signals**:
- ⚠️ High valuation (36x P/E vs. 28x 5-year avg)
- ⚠️ Fidelity reduced position (-300K shares)
- ⚠️ Wide price target range ($180-$275, $95 spread)

**Investment Recommendation**: **BUY on Dips**

Apple demonstrates strong fundamental momentum with consistent earnings
beats and positive analyst sentiment. However, current valuation (36x P/E)
is elevated. Recommend accumulating on any pullback to $210-215 range
(30-31x P/E) for better risk/reward.

**Upcoming Catalysts**:
1. **Q1 FY25 Earnings** (Jan 30, 2025) - iPhone 16 holiday sales reveal
2. **Vision Pro Expansion** (International launch scheduled Q1 2025)
3. **AI Features Rollout** (iOS 18.2+ with enhanced Siri capabilities)

**Risk Factors**:
- China demand softness (18% of revenue)
- DOJ antitrust case (App Store at risk)
- Valuation multiple compression if growth disappoints

**Data Sources**:
- Real-time quote: Yahoo Finance
- Earnings history: Yahoo Finance (4 quarters)
- Analyst ratings: Yahoo Finance (52 analysts)
- Institutional ownership: Yahoo Finance (13F filings)
```
</details>

### Multi-Agent Workflow: Investment Analysis

<details>
<summary><b>📊 Complete Investment Analysis (Fundamental + Macro)</b></summary>

```
You: /analyze MSFT

Investment Analysis Workflow: Starting multi-agent analysis...

📊 Quill analyzing fundamentals...
  → get_quote
  → get_financials
  → get_earnings_history
  → get_analyst_recommendations
  ✓ Fundamental analysis complete

🌍 Macro Lens validating timing...
  → get_key_macro_indicators
  → get_treasury_yield_curve
  → get_market_indices
  ✓ Macro validation complete

🎯 Synthesizing recommendation...

Final Recommendation:

**Overall Rating: BUY - Medium Confidence**

**Key Reasoning**:
Microsoft demonstrates exceptional fundamental quality with 42% ROE,
$87B annual free cash flow, and strong competitive moats in cloud
(Azure) and enterprise software. Recent earnings show consistent beats
(+4.2% avg surprise last 4 quarters) with 89% analyst buy ratings.
Current valuation of 31x P/E is reasonable given 15% revenue growth.

However, macro timing presents headwinds—we're in late expansion phase
with inverted yield curve (-0.54%) signaling recession risk within 12
months. Tech sector (Nasdaq -8% from highs) showing vulnerability.

**Suggested Action**:
Consider accumulating MSFT on dips rather than full position immediately.
Dollar-cost average over 3-6 months to capture potential volatility from
macro headwinds. Microsoft's defensive characteristics (enterprise
subscriptions, cloud infrastructure) should outperform cyclical tech
peers in downturn.

**Risk Warning**:
Monitor enterprise cloud spending trends and Microsoft Azure growth rates.
If Azure growth decelerates below 25% YoY, fundamental thesis weakens.
Macro risk: Recession could compress P/E multiple to 24-26x (historical
trough), implying 15-20% downside risk from current levels.

**Data Sources**:
- Fundamentals: Yahoo Finance (earnings, analysts, quotes), FMP (ratios)
- Macro: FRED (GDP, CPI, unemployment), U.S. Treasury (yield curve)
- Market: Yahoo Finance (indices), NewsAPI (sentiment)
```
</details>

### Screen Forge - Earnings Momentum Screening 🆕

<details>
<summary><b>🔍 Screen for Earnings Beat Momentum</b></summary>

```
You: /screen
You: Screen for stocks with consistent earnings beats over last 3 quarters

Screen Forge (Equity Screening):
  → screen_stocks(market_cap_min=1000000000)
  ✓ 347 stocks retrieved

  → get_earnings_history (batch for 347 stocks)
  ✓ Earnings data retrieved for 298 stocks

  → Filtering for 3+ consecutive beats
  ✓ 42 stocks match criteria

**Earnings Beat Momentum Screen Results**

**Criteria**:
- Market Cap: > $1B
- Earnings Beats: 3+ consecutive quarters
- Average Surprise: > 2%

**Top 10 Candidates** (Ranked by avg surprise %):

| Rank | Ticker | Company | Mkt Cap | Avg Surprise | Streak | Latest Beat |
|------|--------|---------|---------|--------------|--------|-------------|
| 1 | **NVDA** | NVIDIA | $3.2T | +18.4% | 8 qtrs | +21.2% |
| 2 | **META** | Meta Platforms | $1.4T | +12.6% | 5 qtrs | +15.8% |
| 3 | **GOOGL** | Alphabet | $2.1T | +8.9% | 6 qtrs | +9.4% |
| 4 | **MSFT** | Microsoft | $3.1T | +4.2% | 4 qtrs | +3.8% |
| 5 | **AAPL** | Apple | $3.5T | +3.0% | 4 qtrs | +2.5% |
| 6 | **AMZN** | Amazon | $1.9T | +7.5% | 5 qtrs | +8.2% |
| 7 | **V** | Visa | $592B | +5.1% | 7 qtrs | +4.8% |
| 8 | **MA** | Mastercard | $453B | +4.9% | 6 qtrs | +5.2% |
| 9 | **HD** | Home Depot | $381B | +3.8% | 4 qtrs | +4.1% |
| 10 | **CRM** | Salesforce | $308B | +6.2% | 5 qtrs | +7.8% |

**Sector Breakdown**:
- Technology: 28 stocks (67%)
- Financials: 6 stocks (14%)
- Consumer Discretionary: 5 stocks (12%)
- Healthcare: 3 stocks (7%)

**Key Insights**:

1. **Tech Dominance**: Technology sector shows strongest earnings momentum,
   driven by AI tailwinds (NVDA, META, GOOGL) and cloud growth (MSFT, AMZN).

2. **Consistency Matters**: Stocks with 5+ quarter streaks (NVDA, META, GOOGL,
   AMZN, V, MA) show stronger post-earnings drift (+2.1% avg vs. market).

3. **Valuation Check**: Despite earnings beats, many trade at premium multiples:
   - NVDA: 65x P/E (highest risk)
   - META: 28x P/E (reasonable)
   - GOOGL: 26x P/E (attractive)

**Recommended Next Steps**:

1. **Deep Dive Top 3** (use Quill):
   - GOOGL: Best risk/reward (26x P/E, 8.9% avg surprise, cloud recovery)
   - META: Strong momentum (12.6% surprise, AI monetization)
   - V: Defensive quality (5.1% surprise, recession resilient)

2. **Analyst Validation**:
   - Run `get_analyst_recommendations` for top candidates
   - Check for recent upgrades/downgrades

3. **Timing Check** (use Macro Lens):
   - Validate entry timing with current macro regime
   - Consider dollar-cost averaging if late-cycle concerns persist

**Use with Quill**:
Type `/quill` then "Analyze GOOGL with earnings momentum focus" for
deep-dive analysis on top value candidate.
```
</details>

---

## 📚 Documentation

### Project Resources

- **[Integration Docs](backlog/edgar-yahoo-integration.md)**: Yahoo Finance + EDGAR integration guide (NEW)
- **[Backlog](backlog/active.md)**: Current development roadmap
- **[Release Notes](backlog/)**: Detailed changelog for each version
- **[Architecture Specs](refer/specs/)**: Technical design documents
- **[LangGraph Guide](refer/langgraph/)**: Multi-agent patterns & best practices

### API Reference

- **[Anthropic Claude](https://docs.anthropic.com/)**: AI reasoning engine
- **[LangGraph](https://langchain-ai.github.io/langgraph/)**: Agent orchestration framework
- **[Yahoo Finance (yfinance)](https://github.com/ranaroussi/yfinance)**: Free market data library 🆕
- **[Alpha Vantage](https://www.alphavantage.co/documentation/)**: Stock market data
- **[FMP](https://site.financialmodelingprep.com/developer/docs)**: Financial statements & screening
- **[Tiingo](https://www.tiingo.com/documentation/)**: Historical fundamentals
- **[Finnhub](https://finnhub.io/docs/api)**: Alternative data & sentiment
- **[FRED](https://fred.stlouisfed.org/docs/api/fred/)**: Economic indicators
- **[SEC EDGAR](https://www.sec.gov/edgar/sec-api-documentation)**: Corporate filings 🔄 *Enhanced*

### Development

#### Running Tests

```bash
pytest                    # Run all tests
pytest -v                # Verbose output
pytest tests/test_*.py   # Specific test file
```

#### Code Quality

```bash
black src/ tests/        # Format code
ruff check src/ tests/   # Lint code
mypy src/                # Type check
```

#### Building from Source

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Build package
python -m build

# Check distribution
twine check dist/*
```

---

## 🗺️ Roadmap

### Current Release: v0.1.26
- ✅ Yahoo Finance integration (11 tools, FREE)
- ✅ Enhanced SEC EDGAR (4 new tools: 8-K, company facts, insider transactions)
- ✅ Quill agent enhanced with earnings & analyst coverage
- ✅ Zero cost expansion ($2.4K-$10.8K/year savings)

### Next: v0.1.27-0.1.30
- [ ] Earnings Whisperer agent (leverages Yahoo earnings tools)
- [ ] News Sentry agent (leverages 8-K material events)
- [ ] Options analysis tools for Hedge Smith agent (Yahoo options chain)
- [ ] Enhanced multi-agent workflows (parallel execution)
- [ ] Caching layer (DuckDB) for API efficiency

### Future: v0.2.0+
- [ ] Portfolio tracking & performance attribution
- [ ] Backtesting engine for investment strategies
- [ ] Risk management workflows (VaR, stress testing)
- [ ] Web UI (in addition to TUI)
- [ ] Cloud deployment options

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Ways to Contribute**:
- 🐛 Report bugs via [GitHub Issues](https://github.com/navam-io/navam-invest/issues)
- 💡 Suggest features or improvements
- 📝 Improve documentation
- 🔧 Submit pull requests

---

## 📄 License

This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **[Anthropic](https://www.anthropic.com/)** - Claude AI reasoning engine
- **[LangChain](https://www.langchain.com/)** - Agent framework ecosystem
- **[Textual](https://textual.textualize.io/)** - Modern terminal UI framework
- **[yfinance](https://github.com/ranaroussi/yfinance)** - Free Yahoo Finance API wrapper 🆕
- **Data Providers** - Yahoo Finance, SEC, Treasury, Alpha Vantage, FMP, Tiingo, Finnhub, FRED, NewsAPI

---

<div align="center">

**Built with ❤️ for retail investors**

[⬆ Back to Top](#-navam-invest)

</div>

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "navam-invest",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "ai-agents, finance, investment, retail-investor, trading",
    "author": null,
    "author_email": "navam-io <contact@navam.io>",
    "download_url": "https://files.pythonhosted.org/packages/f4/7f/edcdde54327dff7eceebffedc255ccf01e49b4be1aeb97c2a283a0119052/navam_invest-0.1.26.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n\n# \ud83e\udd16 Navam Invest\n\n**AI-Powered Investment Advisor for Retail Investors**\n\n[![PyPI version](https://badge.fury.io/py/navam-invest.svg)](https://badge.fury.io/py/navam-invest)\n[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://static.pepy.tech/badge/navam-invest)](https://pepy.tech/project/navam-invest)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n[Features](#-features) \u2022\n[Quick Start](#-quick-start) \u2022\n[Agents](#-specialized-ai-agents) \u2022\n[API Sources](#-data-sources) \u2022\n[Examples](#-example-interactions) \u2022\n[Documentation](#-documentation)\n\n</div>\n\n---\n\n## \ud83c\udd95 What's New in v0.1.26\n\n**Yahoo Finance + Enhanced SEC EDGAR Integration** - Institutional-grade data at zero cost:\n\n- \u2728 **Yahoo Finance Integration**: 11 new tools for real-time quotes, earnings analysis, analyst ratings, institutional holders (FREE, no API key)\n- \u2728 **Enhanced SEC EDGAR**: 4 new tools for 8-K material events, XBRL company facts, insider transactions (Form 4), flexible filing search\n- \u2728 **Quill Agent Enhanced**: 22 \u2192 36 tools (+64% capabilities) - Now includes earnings trends, analyst sentiment, ownership tracking\n- \u2728 **Zero Cost Expansion**: All new tools free & unlimited ($2,400-$10,800/year savings vs. paid alternatives)\n- \u2728 **Full Backward Compatibility**: Existing agents and workflows unchanged\n\n**New Capabilities**:\n- **Earnings Analysis**: Historical EPS surprises, upcoming earnings calendar, analyst estimates\n- **Analyst Coverage**: Consensus ratings, price targets, recent upgrades/downgrades\n- **Material Events**: 8-K filings for M&A, earnings, management changes, bankruptcy\n- **Ownership Intelligence**: Institutional holders, Form 4 insider transactions, 13F filings\n- **Market Indices**: S&P 500, Dow Jones, Nasdaq, Russell 2000, VIX (for macro analysis)\n\nSee [Integration Docs](backlog/edgar-yahoo-integration.md) for details | Previous: [v0.1.25](backlog/release-0.1.25.md)\n\n---\n\n## \ud83d\udcd6 Overview\n\n`navam-invest` brings **institutional-grade portfolio intelligence** to individual retail investors. Built with [LangGraph](https://langchain-ai.github.io/langgraph/) and powered by [Anthropic's Claude](https://www.anthropic.com/claude), it provides **specialized AI agents** that collaborate through **multi-agent workflows** for equity research, systematic screening, macro analysis, and portfolio management\u2014all accessible through an interactive terminal interface.\n\n### Why Navam Invest?\n\n- **\ud83c\udfaf Multi-Agent Workflows**: Coordinated agent collaboration for comprehensive analysis\n- **\ud83e\udd16 Specialized Agents**: 6 purpose-built agents (Quill, Screen Forge, Macro Lens, Atlas, Portfolio, Research)\n- **\ud83d\udcca Institutional Data**: Yahoo Finance + Enhanced EDGAR + 8 premium APIs (all free tiers)\n- **\ud83d\udd12 Privacy-First**: Run locally with your own API keys\u2014your data stays yours\n- **\ud83d\udca1 Transparent**: Full audit trails and explainable AI reasoning with real-time streaming\n- **\ud83c\udd93 Zero Additional Cost**: New Yahoo Finance + EDGAR tools require no API keys\n- **\ud83d\udd27 Extensible**: Modular architecture makes it easy to add new agents and workflows\n\n---\n\n## \u2728 Features\n\n### \ud83e\udd16 **Specialized AI Agents** (Powered by LangGraph)\n\n<table>\n<tr>\n<td width=\"50%\">\n\n#### **Quill - Equity Research** \u2b50 *Enhanced v0.1.26*\n*Deep fundamental analysis & thesis building*\n\n**NEW Capabilities**:\n- \u2728 Real-time earnings trends & surprises (Yahoo Finance)\n- \u2728 Analyst consensus & price targets (Yahoo Finance)\n- \u2728 Institutional ownership tracking (Yahoo Finance)\n- \u2728 Material event detection (8-K filings)\n- \u2728 XBRL structured data extraction\n- \u2728 Insider transaction patterns (Form 4)\n\n**Core Capabilities**:\n- Investment thesis development\n- DCF & comparable company valuation\n- 5-year historical fundamentals (Tiingo)\n- Quarterly earnings tracking\n- SEC filings analysis (10-K, 10-Q, 8-K)\n- Company-specific news validation\n- Dividend history & yield analysis\n- **36 specialized tools** (up from 22)\n\n**Command**: `/quill`\n\n**Use Case**: \"Analyze AAPL with focus on recent earnings trends and analyst sentiment\"\n\n</td>\n<td width=\"50%\">\n\n#### **Screen Forge - Equity Screening**\n*Systematic stock discovery & idea generation*\n\n**Enhanced Capabilities** (v0.1.26):\n- \u2728 Earnings momentum screening (consistent beats)\n- \u2728 Analyst upgrade activity filtering\n\n**Core Capabilities**:\n- Multi-factor screening (value, growth, quality)\n- Systematic candidate identification\n- Weekly watchlist generation\n- Factor-based ranking systems\n- Sentiment validation (Finnhub + Yahoo)\n- Integration with Quill for deep-dives\n- **15 specialized tools** (up from 10)\n\n**Command**: `/screen`\n\n**Use Case**: \"Screen for stocks with consistent earnings beats and analyst upgrades\"\n\n</td>\n</tr>\n<tr>\n<td width=\"50%\">\n\n#### **Macro Lens - Market Strategist**\n*Top-down macro analysis & regime identification*\n\n**Enhanced Capabilities** (v0.1.26):\n- \u2728 Market indices tracking (S&P 500, Nasdaq, VIX)\n- \u2728 Historical index data for regime analysis\n\n**Core Capabilities**:\n- Economic cycle regime analysis (4 phases)\n- Yield curve interpretation & recession signals\n- Sector allocation guidance based on macro\n- Factor recommendations (value/growth, size)\n- Inflation, growth, employment tracking\n- Fed policy and interest rate analysis\n- **13 specialized tools** (up from 11)\n\n**Command**: `/macro`\n\n**Use Case**: \"What's the current macro regime and which sectors should I overweight?\"\n\n</td>\n<td width=\"50%\">\n\n#### **Atlas - Investment Strategist**\n*Strategic asset allocation & portfolio construction*\n\n**Core Capabilities**:\n- Investment Policy Statement (IPS) development\n- Strategic asset allocation frameworks\n- Risk tolerance profiling (Conservative/Moderate/Aggressive)\n- Macro-driven tactical tilts\n- Rebalancing strategies (threshold, calendar, tax-aware)\n- Portfolio construction guidance\n- **12 specialized tools**\n\n**Command**: `/atlas`\n\n**Use Case**: \"Create an IPS for moderate risk tolerance with $100k portfolio\"\n\n</td>\n</tr>\n<tr>\n<td width=\"50%\">\n\n#### **Portfolio Analysis** (Legacy)\n*Comprehensive portfolio tools*\n\n- Real-time stock quotes & metrics\n- Company fundamentals & financial ratios\n- News & social sentiment analysis\n- SEC filings & institutional holdings\n- Multi-criteria stock screening\n- Local file reading (CSV, JSON, Excel)\n- **24 tools** (backward compatible)\n\n**Command**: `/portfolio`\n\n**Use Case**: \"What's the current price and fundamentals of MSFT?\"\n\n</td>\n<td width=\"50%\">\n\n#### **Market Research** (Legacy)\n*Top-down macro analysis*\n\n- Macroeconomic indicators (GDP, CPI, unemployment)\n- Treasury yield curves & spreads\n- Federal Reserve data (FRED)\n- Economic regime detection\n- Debt-to-GDP analysis\n- Market news & sentiment\n- **10 tools**\n\n**Command**: `/research`\n\n**Use Case**: \"Show me the Treasury yield curve and economic indicators\"\n\n*Note: Will be phased out in favor of Macro Lens agent in v0.2.0*\n\n</td>\n</tr>\n</table>\n\n### \ud83d\udd00 **Multi-Agent Workflows**\n\nCoordinated agent collaboration combining specialized expertise:\n\n#### **Investment Analysis Workflow**\n\n**Sequential Orchestration**: Quill \u2192 Macro Lens \u2192 Synthesis\n\n**How it works**:\n1. **Quill** performs bottom-up fundamental analysis\n   - Business overview & competitive position\n   - Financial health (5-year trends)\n   - Valuation (P/E, P/B, DCF fair value)\n   - **NEW**: Earnings trends, analyst sentiment\n   - Investment thesis with catalysts\n\n2. **Macro Lens** validates timing with top-down analysis\n   - Receives Quill's thesis via shared state\n   - Assesses current macro regime\n   - Evaluates sector positioning\n   - Validates entry point timing\n   - **NEW**: Market indices regime correlation\n\n3. **Synthesis** combines both perspectives\n   - Overall rating: BUY/HOLD/SELL\n   - Confidence level: High/Medium/Low\n   - Key reasoning from both agents\n   - Risk warning & suggested action\n\n**Command**: `/analyze <SYMBOL>`\n\n**Example**:\n```\n/analyze AAPL\n\n\ud83d\udcca Quill analyzing fundamentals...\n  \u2192 get_quote: $227.45, P/E 36x, Market Cap $3.5T\n  \u2192 get_earnings_history: Beat by $0.15 last 3 quarters\n  \u2192 get_analyst_recommendations: 42 Buy, 8 Hold, 2 Sell\n  \u2192 get_institutional_holders: BlackRock 6.8%, Vanguard 8.2%\n\n\ud83c\udf0d Macro Lens validating timing...\n  \u2192 get_market_indices: S&P 500 +12% YTD, VIX 14.2\n  \u2192 get_treasury_yield_curve: 10Y-2Y inverted -0.54%\n\n\ud83c\udfaf Final Recommendation: HOLD - Medium Confidence\nApple shows strong fundamentals (earnings beats, analyst\nsupport) but late-cycle macro timing suggests cautious\npositioning. Dollar-cost average on dips below $210.\n```\n\n### \ud83d\udcca **Data Sources** (36 Tools Across 10+ APIs)\n\n| Data Source | Tools | Purpose | Cost | New in v0.1.26 |\n|-------------|-------|---------|------|----------------|\n| **Yahoo Finance** \ud83c\udd95 | 11 | Real-time quotes, earnings, analyst ratings, ownership | **FREE** | \u2705 |\n| **SEC EDGAR** \ud83d\udd04 | 9 | Corporate filings (10-K, 10-Q, 8-K), XBRL, insider transactions | **FREE** | \u2705 4 new |\n| **Financial Modeling Prep** | 4 | Financial statements, ratios, screening | 250 calls/day | |\n| **Tiingo** | 4 | Historical fundamentals (5yr), quarterly data | 50 symbols/hr | |\n| **Finnhub** | 5 | News/social/insider sentiment, analyst ratings | 60 calls/min | |\n| **Alpha Vantage** | 2 | Stock prices, company overviews | 25-500 calls/day | |\n| **FRED (St. Louis Fed)** | 2 | Economic indicators, macro data | Unlimited | |\n| **U.S. Treasury** | 4 | Yield curves, treasury rates | Unlimited | |\n| **NewsAPI.org** | 3 | Market news, headlines | 100 calls/day | |\n| **Anthropic Claude** | - | AI reasoning (Sonnet 4.5) | Pay-as-you-go | |\n\n**Total Free Data**: 7 out of 10 sources require no API key! (Yahoo Finance, SEC, Treasury)\n\n### \ud83d\udcac **Interactive Terminal UI**\n\n- **Chat Interface**: Natural language interaction with specialized agents\n- **Real-time Streaming**: Watch agents think and reason live\n- **Multi-Agent Progress**: See workflow transitions and agent collaboration\n- **Granular Tool Tracking**: Watch which tools are called with what arguments\n- **Markdown Rendering**: Beautiful formatted output with tables\n- **Agent Switching**: `/quill`, `/screen`, `/macro`, `/atlas`, `/portfolio`, `/research`\n- **Workflow Commands**: `/analyze <SYMBOL>` for multi-agent analysis\n- **Command Palette**: Quick access to common actions\n- **File Reading**: Analyze local portfolio files\n\n### \ud83c\udfd7\ufe0f **Built on Modern Tech**\n\n```\nLangGraph (Multi-Agent Orchestration) \u2192 LangChain (Tools) \u2192 Anthropic Claude (Reasoning)\n     \u2193\nTextual (Terminal UI) + Typer (CLI) + httpx (Async HTTP) + yfinance (Market Data)\n```\n\n**Architecture Highlights**:\n- **Multi-Agent Workflows**: Sequential orchestration with shared state\n- **Specialized Agents**: Purpose-built agents with focused tool sets\n- **Tools Registry**: Agent-specific tool mappings for optimal performance\n- **ReAct Pattern**: Reasoning + Acting for transparent decision-making\n- **Async/Await**: Non-blocking I/O for responsive UI\n- **Type Safety**: Full type hints with MyPy strict mode\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n- **Python 3.9+** (3.13 recommended)\n- **pip** package manager\n- API keys (see [Configuration](#configuration))\n\n### Installation\n\n#### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install navam-invest\n```\n\n#### Option 2: Install from Source\n\n```bash\ngit clone https://github.com/navam-io/navam-invest.git\ncd navam-invest\npython3 -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Configuration\n\n1. **Copy environment template:**\n   ```bash\n   cp .env.example .env\n   ```\n\n2. **Add your API keys** to `.env`:\n   ```bash\n   # Required\n   ANTHROPIC_API_KEY=sk-ant-...\n\n   # Optional (but recommended for full functionality)\n   ALPHA_VANTAGE_API_KEY=your_key_here\n   FMP_API_KEY=your_key_here\n   TIINGO_API_KEY=your_key_here\n   FINNHUB_API_KEY=your_key_here\n   FRED_API_KEY=your_key_here\n   NEWSAPI_API_KEY=your_key_here\n\n   # No keys needed for Yahoo Finance, SEC EDGAR, U.S. Treasury!\n   ```\n\n3. **Get API Keys** (all have free tiers):\n\n   | Service | Link | Free Tier | Required? |\n   |---------|------|-----------|-----------|\n   | **Anthropic** \u2b50 | [console.anthropic.com](https://console.anthropic.com/) | Pay-as-you-go ($3-15/M tokens) | \u2705 Required |\n   | **Yahoo Finance** \ud83c\udd95 | - | Unlimited, no key needed | \u2705 Built-in |\n   | **SEC EDGAR** | - | Unlimited, no key needed | \u2705 Built-in |\n   | **U.S. Treasury** | - | Unlimited, no key needed | \u2705 Built-in |\n   | **Alpha Vantage** | [alphavantage.co/support/#api-key](https://www.alphavantage.co/support/#api-key) | 25 calls/day | Optional |\n   | **FMP** | [financialmodelingprep.com/developer](https://financialmodelingprep.com/developer) | 250 calls/day | Optional |\n   | **Tiingo** | [tiingo.com](https://www.tiingo.com/) | 50 symbols/hr, 5yr history | Optional |\n   | **Finnhub** | [finnhub.io/register](https://finnhub.io/register) | 60 calls/min | Optional |\n   | **FRED** | [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) | Unlimited | Optional |\n   | **NewsAPI** | [newsapi.org/register](https://newsapi.org/register) | 100 calls/day | Optional |\n\n### Usage\n\n#### Launch the Interactive Interface\n\n```bash\nnavam invest\n```\n\nThis opens an interactive chat interface with 6 specialized AI agents and multi-agent workflows.\n\n#### Quick Command Reference\n\n| Command | Agent/Workflow | Description |\n|---------|----------------|-------------|\n| `/analyze <SYMBOL>` | Investment Analysis Workflow | Multi-agent fundamental + macro analysis |\n| `/quill` | Quill (Equity Research) | Deep fundamental analysis & thesis building \u2b50 *36 tools* |\n| `/screen` | Screen Forge | Systematic stock screening & idea generation |\n| `/macro` | Macro Lens | Top-down macro analysis & regime identification |\n| `/atlas` | Atlas (Investment Strategist) | Strategic asset allocation & IPS development |\n| `/portfolio` | Portfolio Analysis | Comprehensive stock & portfolio tools (legacy) |\n| `/research` | Market Research | Macroeconomic analysis & treasury data (legacy) |\n| `/examples` | - | Show example queries for current agent/workflow |\n| `/help` | - | Show all commands |\n| `/clear` | - | Clear chat history |\n| `/quit` | - | Exit application |\n\n---\n\n## \ud83d\udca1 Example Interactions\n\n### Quill - Equity Research (with Yahoo Finance) \ud83c\udd95\n\n<details>\n<summary><b>\ud83d\udcc8 Earnings & Analyst Sentiment Analysis</b></summary>\n\n```\nYou: /quill\nYou: Analyze AAPL with focus on recent earnings trends and analyst sentiment\n\nQuill (Equity Research):\n  \u2192 get_quote(symbol=AAPL)\n  \u2713 AAPL: $227.45, +1.2% (+$2.70), P/E 36x, Market Cap $3.5T\n\n  \u2192 get_earnings_history(symbol=AAPL)\n  \u2713 Earnings history retrieved\n\n  \u2192 get_analyst_recommendations(symbol=AAPL)\n  \u2713 Analyst ratings retrieved\n\n  \u2192 get_institutional_holders(symbol=AAPL)\n  \u2713 Institutional ownership retrieved\n\n**Apple Inc. (AAPL) - Earnings & Sentiment Analysis**\n\n**Earnings Trends** (Last 4 Quarters):\n\n| Quarter | EPS Actual | EPS Estimate | Surprise | Surprise % |\n|---------|------------|--------------|----------|------------|\n| Q4 2024 | $1.64 | $1.60 | $0.04 | +2.5% |\n| Q3 2024 | $1.40 | $1.35 | $0.05 | +3.7% |\n| Q2 2024 | $1.53 | $1.50 | $0.03 | +2.0% |\n| Q1 2024 | $2.18 | $2.10 | $0.08 | +3.8% |\n\n**Key Observation**: Apple has beaten analyst estimates for 4 consecutive\nquarters with an average surprise of +3.0%. This demonstrates consistent\nexecution and conservative guidance from management.\n\n**Upcoming Earnings**:\n- **Date**: January 30, 2025 (estimated)\n- **EPS Estimate**: $2.23 (range: $2.18 - $2.28)\n- **Revenue Estimate**: $124.5B\n\n**Analyst Sentiment**:\n\n**Ratings Distribution** (52 analysts):\n- **Buy/Overweight**: 42 (81%)\n- **Hold/Neutral**: 8 (15%)\n- **Sell/Underweight**: 2 (4%)\n\n**Price Targets**:\n- **Mean Target**: $248 (+9% upside)\n- **Median Target**: $245 (+7.7% upside)\n- **High Target**: $275 (+21% upside)\n- **Low Target**: $180 (-21% downside)\n\n**Recent Rating Changes** (Last 30 days):\n- **Wedbush**: Maintained Outperform, raised target $260 \u2192 $275\n- **Morgan Stanley**: Upgraded Neutral \u2192 Overweight, target $240 \u2192 $260\n- **JPMorgan**: Maintained Overweight, raised target $245 \u2192 $265\n\n**Institutional Ownership**:\n\n**Top 5 Holders** (Total: 58.2% institutional ownership):\n1. **Vanguard Group**: 8.2% ($287B) - Increased 2.1M shares Q3\n2. **BlackRock**: 6.8% ($238B) - Increased 1.5M shares Q3\n3. **Berkshire Hathaway**: 5.8% ($203B) - Maintained position\n4. **State Street**: 4.1% ($144B) - Increased 850K shares Q3\n5. **Fidelity**: 2.3% ($81B) - Decreased 300K shares Q3\n\n**Sentiment Analysis**:\n\n**Bullish Indicators**:\n- \u2705 4 consecutive earnings beats (avg +3% surprise)\n- \u2705 81% analyst buy ratings (strong consensus)\n- \u2705 Recent analyst upgrades (3 in last month)\n- \u2705 Institutional accumulation (+4.4M shares Q3 from top holders)\n- \u2705 Mean price target implies +9% upside\n\n**Cautionary Signals**:\n- \u26a0\ufe0f High valuation (36x P/E vs. 28x 5-year avg)\n- \u26a0\ufe0f Fidelity reduced position (-300K shares)\n- \u26a0\ufe0f Wide price target range ($180-$275, $95 spread)\n\n**Investment Recommendation**: **BUY on Dips**\n\nApple demonstrates strong fundamental momentum with consistent earnings\nbeats and positive analyst sentiment. However, current valuation (36x P/E)\nis elevated. Recommend accumulating on any pullback to $210-215 range\n(30-31x P/E) for better risk/reward.\n\n**Upcoming Catalysts**:\n1. **Q1 FY25 Earnings** (Jan 30, 2025) - iPhone 16 holiday sales reveal\n2. **Vision Pro Expansion** (International launch scheduled Q1 2025)\n3. **AI Features Rollout** (iOS 18.2+ with enhanced Siri capabilities)\n\n**Risk Factors**:\n- China demand softness (18% of revenue)\n- DOJ antitrust case (App Store at risk)\n- Valuation multiple compression if growth disappoints\n\n**Data Sources**:\n- Real-time quote: Yahoo Finance\n- Earnings history: Yahoo Finance (4 quarters)\n- Analyst ratings: Yahoo Finance (52 analysts)\n- Institutional ownership: Yahoo Finance (13F filings)\n```\n</details>\n\n### Multi-Agent Workflow: Investment Analysis\n\n<details>\n<summary><b>\ud83d\udcca Complete Investment Analysis (Fundamental + Macro)</b></summary>\n\n```\nYou: /analyze MSFT\n\nInvestment Analysis Workflow: Starting multi-agent analysis...\n\n\ud83d\udcca Quill analyzing fundamentals...\n  \u2192 get_quote\n  \u2192 get_financials\n  \u2192 get_earnings_history\n  \u2192 get_analyst_recommendations\n  \u2713 Fundamental analysis complete\n\n\ud83c\udf0d Macro Lens validating timing...\n  \u2192 get_key_macro_indicators\n  \u2192 get_treasury_yield_curve\n  \u2192 get_market_indices\n  \u2713 Macro validation complete\n\n\ud83c\udfaf Synthesizing recommendation...\n\nFinal Recommendation:\n\n**Overall Rating: BUY - Medium Confidence**\n\n**Key Reasoning**:\nMicrosoft demonstrates exceptional fundamental quality with 42% ROE,\n$87B annual free cash flow, and strong competitive moats in cloud\n(Azure) and enterprise software. Recent earnings show consistent beats\n(+4.2% avg surprise last 4 quarters) with 89% analyst buy ratings.\nCurrent valuation of 31x P/E is reasonable given 15% revenue growth.\n\nHowever, macro timing presents headwinds\u2014we're in late expansion phase\nwith inverted yield curve (-0.54%) signaling recession risk within 12\nmonths. Tech sector (Nasdaq -8% from highs) showing vulnerability.\n\n**Suggested Action**:\nConsider accumulating MSFT on dips rather than full position immediately.\nDollar-cost average over 3-6 months to capture potential volatility from\nmacro headwinds. Microsoft's defensive characteristics (enterprise\nsubscriptions, cloud infrastructure) should outperform cyclical tech\npeers in downturn.\n\n**Risk Warning**:\nMonitor enterprise cloud spending trends and Microsoft Azure growth rates.\nIf Azure growth decelerates below 25% YoY, fundamental thesis weakens.\nMacro risk: Recession could compress P/E multiple to 24-26x (historical\ntrough), implying 15-20% downside risk from current levels.\n\n**Data Sources**:\n- Fundamentals: Yahoo Finance (earnings, analysts, quotes), FMP (ratios)\n- Macro: FRED (GDP, CPI, unemployment), U.S. Treasury (yield curve)\n- Market: Yahoo Finance (indices), NewsAPI (sentiment)\n```\n</details>\n\n### Screen Forge - Earnings Momentum Screening \ud83c\udd95\n\n<details>\n<summary><b>\ud83d\udd0d Screen for Earnings Beat Momentum</b></summary>\n\n```\nYou: /screen\nYou: Screen for stocks with consistent earnings beats over last 3 quarters\n\nScreen Forge (Equity Screening):\n  \u2192 screen_stocks(market_cap_min=1000000000)\n  \u2713 347 stocks retrieved\n\n  \u2192 get_earnings_history (batch for 347 stocks)\n  \u2713 Earnings data retrieved for 298 stocks\n\n  \u2192 Filtering for 3+ consecutive beats\n  \u2713 42 stocks match criteria\n\n**Earnings Beat Momentum Screen Results**\n\n**Criteria**:\n- Market Cap: > $1B\n- Earnings Beats: 3+ consecutive quarters\n- Average Surprise: > 2%\n\n**Top 10 Candidates** (Ranked by avg surprise %):\n\n| Rank | Ticker | Company | Mkt Cap | Avg Surprise | Streak | Latest Beat |\n|------|--------|---------|---------|--------------|--------|-------------|\n| 1 | **NVDA** | NVIDIA | $3.2T | +18.4% | 8 qtrs | +21.2% |\n| 2 | **META** | Meta Platforms | $1.4T | +12.6% | 5 qtrs | +15.8% |\n| 3 | **GOOGL** | Alphabet | $2.1T | +8.9% | 6 qtrs | +9.4% |\n| 4 | **MSFT** | Microsoft | $3.1T | +4.2% | 4 qtrs | +3.8% |\n| 5 | **AAPL** | Apple | $3.5T | +3.0% | 4 qtrs | +2.5% |\n| 6 | **AMZN** | Amazon | $1.9T | +7.5% | 5 qtrs | +8.2% |\n| 7 | **V** | Visa | $592B | +5.1% | 7 qtrs | +4.8% |\n| 8 | **MA** | Mastercard | $453B | +4.9% | 6 qtrs | +5.2% |\n| 9 | **HD** | Home Depot | $381B | +3.8% | 4 qtrs | +4.1% |\n| 10 | **CRM** | Salesforce | $308B | +6.2% | 5 qtrs | +7.8% |\n\n**Sector Breakdown**:\n- Technology: 28 stocks (67%)\n- Financials: 6 stocks (14%)\n- Consumer Discretionary: 5 stocks (12%)\n- Healthcare: 3 stocks (7%)\n\n**Key Insights**:\n\n1. **Tech Dominance**: Technology sector shows strongest earnings momentum,\n   driven by AI tailwinds (NVDA, META, GOOGL) and cloud growth (MSFT, AMZN).\n\n2. **Consistency Matters**: Stocks with 5+ quarter streaks (NVDA, META, GOOGL,\n   AMZN, V, MA) show stronger post-earnings drift (+2.1% avg vs. market).\n\n3. **Valuation Check**: Despite earnings beats, many trade at premium multiples:\n   - NVDA: 65x P/E (highest risk)\n   - META: 28x P/E (reasonable)\n   - GOOGL: 26x P/E (attractive)\n\n**Recommended Next Steps**:\n\n1. **Deep Dive Top 3** (use Quill):\n   - GOOGL: Best risk/reward (26x P/E, 8.9% avg surprise, cloud recovery)\n   - META: Strong momentum (12.6% surprise, AI monetization)\n   - V: Defensive quality (5.1% surprise, recession resilient)\n\n2. **Analyst Validation**:\n   - Run `get_analyst_recommendations` for top candidates\n   - Check for recent upgrades/downgrades\n\n3. **Timing Check** (use Macro Lens):\n   - Validate entry timing with current macro regime\n   - Consider dollar-cost averaging if late-cycle concerns persist\n\n**Use with Quill**:\nType `/quill` then \"Analyze GOOGL with earnings momentum focus\" for\ndeep-dive analysis on top value candidate.\n```\n</details>\n\n---\n\n## \ud83d\udcda Documentation\n\n### Project Resources\n\n- **[Integration Docs](backlog/edgar-yahoo-integration.md)**: Yahoo Finance + EDGAR integration guide (NEW)\n- **[Backlog](backlog/active.md)**: Current development roadmap\n- **[Release Notes](backlog/)**: Detailed changelog for each version\n- **[Architecture Specs](refer/specs/)**: Technical design documents\n- **[LangGraph Guide](refer/langgraph/)**: Multi-agent patterns & best practices\n\n### API Reference\n\n- **[Anthropic Claude](https://docs.anthropic.com/)**: AI reasoning engine\n- **[LangGraph](https://langchain-ai.github.io/langgraph/)**: Agent orchestration framework\n- **[Yahoo Finance (yfinance)](https://github.com/ranaroussi/yfinance)**: Free market data library \ud83c\udd95\n- **[Alpha Vantage](https://www.alphavantage.co/documentation/)**: Stock market data\n- **[FMP](https://site.financialmodelingprep.com/developer/docs)**: Financial statements & screening\n- **[Tiingo](https://www.tiingo.com/documentation/)**: Historical fundamentals\n- **[Finnhub](https://finnhub.io/docs/api)**: Alternative data & sentiment\n- **[FRED](https://fred.stlouisfed.org/docs/api/fred/)**: Economic indicators\n- **[SEC EDGAR](https://www.sec.gov/edgar/sec-api-documentation)**: Corporate filings \ud83d\udd04 *Enhanced*\n\n### Development\n\n#### Running Tests\n\n```bash\npytest                    # Run all tests\npytest -v                # Verbose output\npytest tests/test_*.py   # Specific test file\n```\n\n#### Code Quality\n\n```bash\nblack src/ tests/        # Format code\nruff check src/ tests/   # Lint code\nmypy src/                # Type check\n```\n\n#### Building from Source\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Build package\npython -m build\n\n# Check distribution\ntwine check dist/*\n```\n\n---\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n### Current Release: v0.1.26\n- \u2705 Yahoo Finance integration (11 tools, FREE)\n- \u2705 Enhanced SEC EDGAR (4 new tools: 8-K, company facts, insider transactions)\n- \u2705 Quill agent enhanced with earnings & analyst coverage\n- \u2705 Zero cost expansion ($2.4K-$10.8K/year savings)\n\n### Next: v0.1.27-0.1.30\n- [ ] Earnings Whisperer agent (leverages Yahoo earnings tools)\n- [ ] News Sentry agent (leverages 8-K material events)\n- [ ] Options analysis tools for Hedge Smith agent (Yahoo options chain)\n- [ ] Enhanced multi-agent workflows (parallel execution)\n- [ ] Caching layer (DuckDB) for API efficiency\n\n### Future: v0.2.0+\n- [ ] Portfolio tracking & performance attribution\n- [ ] Backtesting engine for investment strategies\n- [ ] Risk management workflows (VaR, stress testing)\n- [ ] Web UI (in addition to TUI)\n- [ ] Cloud deployment options\n\n---\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Ways to Contribute**:\n- \ud83d\udc1b Report bugs via [GitHub Issues](https://github.com/navam-io/navam-invest/issues)\n- \ud83d\udca1 Suggest features or improvements\n- \ud83d\udcdd Improve documentation\n- \ud83d\udd27 Submit pull requests\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\n- **[Anthropic](https://www.anthropic.com/)** - Claude AI reasoning engine\n- **[LangChain](https://www.langchain.com/)** - Agent framework ecosystem\n- **[Textual](https://textual.textualize.io/)** - Modern terminal UI framework\n- **[yfinance](https://github.com/ranaroussi/yfinance)** - Free Yahoo Finance API wrapper \ud83c\udd95\n- **Data Providers** - Yahoo Finance, SEC, Treasury, Alpha Vantage, FMP, Tiingo, Finnhub, FRED, NewsAPI\n\n---\n\n<div align=\"center\">\n\n**Built with \u2764\ufe0f for retail investors**\n\n[\u2b06 Back to Top](#-navam-invest)\n\n</div>\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "AI agents and tools for the retail investor",
    "version": "0.1.26",
    "project_urls": {
        "Homepage": "https://github.com/navam-io/navam-invest",
        "Issues": "https://github.com/navam-io/navam-invest/issues",
        "Repository": "https://github.com/navam-io/navam-invest"
    },
    "split_keywords": [
        "ai-agents",
        " finance",
        " investment",
        " retail-investor",
        " trading"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "e681a883d418c613b06b1aa64bbb7b835de7ce2ec0894f6fb96ef8c977e4fdfb",
                "md5": "f3f2d03a47d5724cfd57af231a549876",
                "sha256": "adf5ab4a225d0e958cc19f4847958676274211b6b536f815ac4dbaae0c8c9aad"
            },
            "downloads": -1,
            "filename": "navam_invest-0.1.26-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f3f2d03a47d5724cfd57af231a549876",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 79586,
            "upload_time": "2025-10-07T14:38:15",
            "upload_time_iso_8601": "2025-10-07T14:38:15.634563Z",
            "url": "https://files.pythonhosted.org/packages/e6/81/a883d418c613b06b1aa64bbb7b835de7ce2ec0894f6fb96ef8c977e4fdfb/navam_invest-0.1.26-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "f47fedcdde54327dff7eceebffedc255ccf01e49b4be1aeb97c2a283a0119052",
                "md5": "0322d34e0ba07aa281664b1ce48d8c23",
                "sha256": "8e3d8c8faefea418b0cb3275cf63ec46e4eb49dc938abda9d142782a4ded8ba6"
            },
            "downloads": -1,
            "filename": "navam_invest-0.1.26.tar.gz",
            "has_sig": false,
            "md5_digest": "0322d34e0ba07aa281664b1ce48d8c23",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 60078,
            "upload_time": "2025-10-07T14:38:17",
            "upload_time_iso_8601": "2025-10-07T14:38:17.226706Z",
            "url": "https://files.pythonhosted.org/packages/f4/7f/edcdde54327dff7eceebffedc255ccf01e49b4be1aeb97c2a283a0119052/navam_invest-0.1.26.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-07 14:38:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "navam-io",
    "github_project": "navam-invest",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "navam-invest"
}
None
Elapsed time: 1.17987s