Metadata-Version: 2.4
Name: navam-invest
Version: 0.1.31
Summary: AI agents and tools for the retail investor
Project-URL: Homepage, https://github.com/navam-io/navam-invest
Project-URL: Repository, https://github.com/navam-io/navam-invest
Project-URL: Issues, https://github.com/navam-io/navam-invest/issues
Author-email: navam-io <contact@navam.io>
License: MIT
License-File: LICENSE
Keywords: ai-agents,finance,investment,retail-investor,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: langchain-anthropic>=0.3.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=1.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: yfinance>=0.2.49
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: textual-dev>=1.0.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🧠 Navam Invest

**AI-Powered Investment Advisory 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) •
[AI Agents](#-specialized-ai-agents) •
[Examples](#-example-workflows) •
[Documentation](#-documentation) •
[Roadmap](#-roadmap)

</div>

---

## 📖 Overview

**Navam Invest** brings **institutional-grade portfolio intelligence** to individual retail investors managing $50K-$1M portfolios. Built on [LangGraph](https://langchain-ai.github.io/langgraph/) and powered by [Anthropic's Claude](https://www.anthropic.com/claude), it replaces traditional wealth management fees (1% AUM) with a team of **specialized AI agents** that collaborate through **multi-agent workflows** for equity research, systematic screening, macro analysis, earnings tracking, and portfolio management—all accessible through an interactive terminal interface.

### Why Navam Invest?

<table>
<tr>
<td width="33%" align="center">

**🤖 Multi-Agent Intelligence**

7 specialized AI agents orchestrated by LangGraph for coordinated analysis

</td>
<td width="33%" align="center">

**📊 Institutional Data**

Yahoo Finance + SEC EDGAR + 7 premium APIs (all free tiers)

</td>
<td width="33%" align="center">

**🔒 Privacy-First**

Runs locally with your API keys—your data stays yours

</td>
</tr>
<tr>
<td width="33%" align="center">

**💡 Explainable AI**

Full audit trails and transparent reasoning with real-time streaming

</td>
<td width="33%" align="center">

**🆓 Zero Lock-In**

Yahoo Finance + EDGAR require no API keys, core tools always free

</td>
<td width="33%" align="center">

**🔧 Extensible**

Modular architecture for custom agents and workflows

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

### Architecture at a Glance

```mermaid
graph LR
    A[You] -->|Natural Language| B[Textual TUI]
    B --> C{LangGraph Orchestrator}
    C --> D[Quill<br/>Equity Research]
    C --> E[Earnings Whisperer<br/>Earnings Analysis]
    C --> F[Screen Forge<br/>Stock Screening]
    C --> G[Macro Lens<br/>Market Strategist]
    C --> H[Atlas<br/>Asset Allocation]
    D --> I[Yahoo Finance]
    D --> J[SEC EDGAR]
    D --> K[Tiingo]
    E --> I
    F --> I
    F --> L[Finnhub]
    G --> M[FRED]
    G --> N[U.S. Treasury]
    style C fill:#f9f,stroke:#333,stroke-width:4px
    style I fill:#9f9,stroke:#333,stroke-width:2px
    style J fill:#9f9,stroke:#333,stroke-width:2px
```

**Stack**: LangGraph (orchestration) → LangChain (tools) → Claude (reasoning) → Textual (TUI) → yfinance/httpx (data)

---

## ✨ Features

### 🤖 Specialized AI Agents

> **Each agent is purpose-built with 10-36 specialized tools and expert system prompts**

<details open>
<summary><h4>⭐ Quill - Equity Research Analyst</h4></summary>

**Deep fundamental analysis & investment thesis building**

**Core Capabilities**:
- 📊 **Valuation Models**: DCF, comparable company analysis, P/E/P/B/P/S ratios
- 📈 **Financial Analysis**: 5-year trends (revenue, margins, ROIC, FCF, debt ratios)
- 💰 **Earnings Tracking**: Historical earnings, analyst estimates, surprise analysis
- 🎯 **Analyst Coverage**: Consensus ratings, price targets, upgrades/downgrades
- 🏢 **Ownership Tracking**: Institutional holders, insider transactions (Form 4)
- 📋 **SEC Filings**: 10-K, 10-Q, 8-K material events, XBRL structured data
- 💵 **Dividends**: Yield, payout ratios, dividend history, sustainability
- 📰 **News Validation**: Company-specific news with sentiment analysis

**Tools**: 36 specialized tools across Yahoo Finance, SEC EDGAR, Tiingo, Finnhub, NewsAPI

**Command**: `/quill`

**Example Query**:
> "Analyze AAPL with focus on recent earnings trends, institutional ownership, and material events from 8-K filings"

</details>

<details>
<summary><h4>📊 Earnings Whisperer - Earnings Specialist</h4></summary>

**Earnings surprise analysis & post-earnings drift detection**

**Core Capabilities**:
- 🎯 **Historical Analysis**: 4-8 quarter earnings surprise tracking
- 📈 **Drift Detection**: 1-3 day post-earnings momentum patterns
- 🔄 **Analyst Revisions**: Estimate changes and rating updates post-earnings
- ✅ **Quality Assessment**: Revenue vs. EPS beats, non-recurring items
- 📅 **Calendar Monitoring**: Upcoming earnings with probability scoring
- 🏆 **Pattern Recognition**: Consistent beaters, accelerating beats, quality issues
- 💹 **Trading Signals**: BUY (drift play), HOLD (wait), SELL (negative momentum)

**Tools**: 14 specialized tools across Yahoo Finance, SEC, Finnhub

**Command**: `/earnings`

**Example Query**:
> "Analyze NVDA earnings history - is there a post-earnings drift opportunity?"

</details>

<details>
<summary><h4>🔍 Screen Forge - Equity Screener</h4></summary>

**Systematic stock discovery & idea generation**

**Core Capabilities**:
- 📐 **Multi-Factor Screening**: Value, growth, quality, momentum factors
- 🎯 **Systematic Discovery**: Weekly watchlist generation with factor-based ranking
- 📈 **Earnings Momentum**: Consistent earnings beat screening
- ⬆️ **Analyst Activity**: Upgrade/downgrade filtering
- 💬 **Sentiment Validation**: News and social sentiment checks
- 🔗 **Integration**: Seamless handoff to Quill for deep-dive analysis

**Tools**: 15 specialized tools across Yahoo Finance, Finnhub, Alpha Vantage

**Command**: `/screen`

**Example Query**:
> "Screen for stocks with consistent earnings beats over last 3 quarters and analyst upgrades"

</details>

<details>
<summary><h4>🌍 Macro Lens - Market Strategist</h4></summary>

**Top-down macro analysis & regime identification**

**Core Capabilities**:
- 🔄 **Economic Cycles**: 4-phase regime analysis (early/mid/late expansion, recession)
- 📈 **Yield Curve**: Interpretation and recession signal detection (inversions)
- 🏭 **Sector Allocation**: Macro-driven sector positioning guidance
- 📊 **Factor Recommendations**: Value vs. growth, size, low-volatility tilts
- 📉 **Macro Tracking**: Inflation, GDP growth, employment, Fed policy
- 📊 **Market Indices**: S&P 500, Nasdaq, VIX for regime correlation
- 💹 **Interest Rates**: Fed funds, treasury rates, spreads

**Tools**: 13 specialized tools across FRED, U.S. Treasury, Yahoo Finance, NewsAPI

**Command**: `/macro`

**Example Query**:
> "What's the current macro regime and which sectors should I overweight?"

</details>

<details>
<summary><h4>🗺️ Atlas - Investment Strategist</h4></summary>

**Strategic asset allocation & portfolio construction**

**Core Capabilities**:
- 📋 **IPS Development**: Investment Policy Statement creation
- 🎯 **Asset Allocation**: Strategic allocation frameworks (stocks/bonds/alternatives)
- 📊 **Risk Profiling**: Conservative/Moderate/Aggressive tolerance assessment
- 🔄 **Tactical Tilts**: Macro-driven portfolio adjustments
- ⚖️ **Rebalancing**: Threshold-based, calendar-based, tax-aware strategies
- 🏗️ **Construction**: Portfolio building with constraint optimization

**Tools**: 12 specialized tools across all data sources

**Command**: `/atlas`

**Example Query**:
> "Create an IPS for moderate risk tolerance with $100k portfolio"

</details>

<details>
<summary><h4>📁 Portfolio & Research (Legacy)</h4></summary>

**Backward-compatible general-purpose agents**

- **Portfolio** (`/portfolio`): 24 tools for quotes, fundamentals, news, SEC filings
- **Research** (`/research`): 10 tools for macro indicators, yield curves, FRED data

*Note: Will be phased out in v0.2.0 in favor of specialized agents*

</details>

### 🔀 Multi-Agent Workflows

> **Coordinated agent collaboration combining specialized expertise**

#### Investment Analysis Workflow

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

**Sequential Orchestration**: Quill (bottom-up) → Macro Lens (top-down) → Synthesis

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

**Step 1: Fundamental Analysis**

Quill performs bottom-up analysis:
- Business overview
- Financial health (5-year trends)
- Valuation (P/E, DCF)
- Earnings trends
- Analyst sentiment
- Investment thesis

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

**Step 2: Macro Validation**

Macro Lens validates timing:
- Receives Quill's thesis
- Assesses macro regime
- Evaluates sector positioning
- Validates entry point
- Market indices correlation

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

**Step 3: Synthesis**

Combined recommendation:
- Overall rating (BUY/HOLD/SELL)
- Confidence level
- Key reasoning from both agents
- Risk warnings
- Suggested action

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

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

📊 Quill analyzing fundamentals...
  ✓ Strong earnings momentum (+3% avg beat, 4 qtrs)
  ✓ 81% analyst buy ratings, $248 mean target (+9% upside)

🌍 Macro Lens validating timing...
  ✓ Late expansion phase, inverted yield curve (-0.54%)
  ⚠️ Tech sector vulnerability (Nasdaq -8% from highs)

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

### 📊 Data Sources

**32 tools across 9 APIs** (3 completely free, 6 with generous free tiers)

| Data Source | Tools | Purpose | Free Tier | Cost |
|-------------|-------|---------|-----------|------|
| **Yahoo Finance** 🆓 | 11 | Real-time quotes, earnings, analyst ratings, ownership | Unlimited | **FREE** |
| **SEC EDGAR** 🆓 | 9 | Corporate filings (10-K, 10-Q, 8-K), XBRL, insider transactions | Unlimited | **FREE** |
| **U.S. Treasury** 🆓 | 4 | Yield curves, treasury rates | Unlimited | **FREE** |
| **Tiingo** | 4 | Historical fundamentals (5yr), quarterly data | 50 symbols/hr | Optional |
| **Finnhub** | 5 | News/social/insider sentiment, analyst ratings | 60 calls/min | Optional |
| **Alpha Vantage** | 2 | Stock prices, company overviews | 25-500 calls/day | Optional |
| **FRED** | 2 | Economic indicators, macro data | Unlimited | Optional |
| **NewsAPI.org** | 3 | Market news, headlines | 1,000 calls/day | Optional |
| **Anthropic Claude** | - | AI reasoning (Sonnet 4.5) | Pay-as-you-go | Required |

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

### 💬 Interactive Terminal UI

**Built with Textual - Modern Python TUI Framework**

**Real-Time Processing Indicators** 🆕:
- ✅ **Smart Input Disabling**: Input grayed out during agent processing
- ✅ **Live Status Updates**: `"⏳ Processing your request..."` placeholder
- ✅ **Footer Progress**: Current agent + processing state in footer bar
- ✅ **Error Recovery**: Auto-enables input even on errors
- ✅ **Auto-Focus**: Returns cursor to input when ready

**Core Features**:
- ✅ **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
- ✅ **Tool Tracking**: Granular visibility into which tools are called with what arguments
- ✅ **Markdown Rendering**: Beautiful formatted output with tables, code blocks, lists
- ✅ **Agent Switching**: Quick commands to switch between agents
- ✅ **Workflow Commands**: Multi-agent orchestration with single commands
- ✅ **Auto-Save Reports**: All agent responses saved to `reports/` directory with timestamps

**Keyboard Shortcuts**:
- `Ctrl+C`: Clear chat history
- `Ctrl+Q`: Quit application
- Mouse scroll for history navigation

### 📄 Automatic Report Saving

**All agent-generated reports are automatically saved** to the `reports/` directory:

- **Investment Analysis** (`/analyze`): Complete multi-section reports with fundamentals, macro validation, and final recommendation
- **Agent Responses**: All substantial responses (>200 chars) automatically saved as markdown files
- **Organized Naming**: `{symbol}_{report_type}_{timestamp}.md`
- **Full Context**: Metadata (date, symbol, query) and formatted markdown content

**Supported Report Types**:
- `analysis` - Multi-agent investment analysis workflow
- `equity_research` - Quill equity research reports
- `earnings` - Earnings surprise analysis
- `screening` - Stock screening results
- `macro_analysis` - Macro regime analysis
- `portfolio` - Portfolio analysis reports

---

## 🚀 Quick Start

### Prerequisites

- **Python 3.9+** (3.13 recommended)
- **pip** package manager
- **Anthropic API key** (required) - Get it at [console.anthropic.com](https://console.anthropic.com/)

### 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  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

### Configuration

#### 1. Create Environment File

```bash
cp .env.example .env
```

#### 2. Add Your API Keys

Edit `.env` with your API keys:

```bash
# Required - AI reasoning engine
ANTHROPIC_API_KEY=sk-ant-...

# Optional - Enhanced data coverage (all have free tiers)
ALPHA_VANTAGE_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 Free API Keys

| 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 |
| **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.org** | [newsapi.org/register](https://newsapi.org/register) | 1,000 calls/day | Optional |

#### 4. Verify Setup

```bash
navam invest
> /api
# Shows status table with ✅ working / ❌ failed / ⚪ not configured
```

### Usage

#### Launch the Interactive Interface

```bash
navam invest
```

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

#### Available Commands

**System Commands**:
- `/api` - Check API connectivity and status of all data providers
- `/help` - Show all available commands
- `/examples` - Show example prompts for current agent
- `/clear` - Clear chat history
- `/quit` - Exit the application

**Agent Selection**:
- `/analyze <SYMBOL>` - Multi-agent investment analysis workflow (Quill + Macro Lens)
- `/quill` - Switch to Quill (Equity Research) agent
- `/earnings` - Switch to Earnings Whisperer agent
- `/screen` - Switch to Screen Forge agent
- `/macro` - Switch to Macro Lens agent
- `/atlas` - Switch to Atlas (Investment Strategist) agent
- `/portfolio` - Switch to Portfolio (legacy) agent
- `/research` - Switch to Research (legacy) agent

---

## 💡 Example Workflows

### 1. Multi-Agent Investment Analysis

<details>
<summary><b>Complete fundamental + macro analysis for MSFT</b></summary>

```
You: /analyze MSFT

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

📊 Quill analyzing fundamentals...
  → get_quote(symbol=MSFT)
  ✓ MSFT: $420.45, +0.8%, P/E 31x, Market Cap $3.1T

  → get_earnings_history(symbol=MSFT)
  ✓ 4 consecutive earnings beats, avg +4.2% surprise

  → get_analyst_recommendations(symbol=MSFT)
  ✓ 89% buy ratings, mean target $475 (+13% upside)

  → get_financials(symbol=MSFT)
  ✓ Revenue +15% YoY, 42% gross margin, $87B FCF

  ✓ Fundamental analysis complete

🌍 Macro Lens validating timing...
  → get_key_macro_indicators()
  ✓ GDP +2.4%, CPI +3.1%, Unemployment 3.7%

  → get_treasury_yield_curve()
  ✓ 10Y-2Y inverted -0.54% (recession warning)

  → get_market_indices()
  ✓ S&P 500 +12% YTD, Nasdaq -8% from highs, VIX 14.2

  ✓ Macro validation complete

🎯 Synthesizing recommendation...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final Recommendation: BUY - Medium Confidence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Key Reasoning**:

Microsoft demonstrates exceptional fundamental quality:
- 42% ROE, $87B annual free cash flow
- Strong competitive moats (Azure cloud, enterprise software)
- Consistent earnings beats (+4.2% avg surprise, 4 quarters)
- 89% analyst buy ratings, $475 mean target (+13% upside)
- Current valuation 31x P/E reasonable given 15% revenue growth

However, macro timing presents headwinds:
- Late expansion phase (GDP +2.4%, but slowing)
- Inverted yield curve (-0.54%) signals recession risk within 12 months
- Tech sector vulnerability (Nasdaq -8% from highs)

**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 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.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📄 Report saved to: reports/MSFT_analysis_20251008_143022.md
```

</details>

### 2. Earnings Momentum Screening

<details>
<summary><b>Screen for stocks with consistent earnings beats</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%       │
└─────┴────────┴────────────────┴────────┴──────────────┴────────┴─────────────┘

**Recommended Next Steps**:
Type `/quill` then "Analyze GOOGL with earnings momentum focus"

📄 Report saved to: reports/SCREENER_earnings_beats_20251008_144530.md
```

</details>

### 3. Real-Time Processing Feedback

<details>
<summary><b>Watch the improved UX during agent processing</b></summary>

**Before Query**:
```
Footer: Agent: Quill | Ready
Input: [Ask about stocks or economic indicators...]
```

**During Processing** (input automatically disabled):
```
Footer: Processing...
Input: [⏳ Processing your request...] (grayed out, uneditable)
```

**During Long Operations** (no more confusion!):
```
Quill (Equity Research):
  → Calling get_financials(symbol=AAPL)
  ✓ get_financials completed
  → Calling get_earnings_history(symbol=AAPL)
  ✓ get_earnings_history completed

Footer: Processing...
Input: [⏳ Processing your request...] (still disabled)

[Even during pauses, you know the system is working!]
```

**After Completion** (input automatically re-enabled):
```
Footer: Agent: Quill | Ready
Input: [Ask about stocks or economic indicators...] (cursor auto-focused)
```

**Benefits**:
- ✅ No confusion about whether system is frozen or working
- ✅ Can't accidentally submit duplicate requests
- ✅ Clear visual feedback at multiple levels
- ✅ Auto-recovers even on errors

</details>

---

## 📚 Documentation

### Official Resources

- **[GitHub Repository](https://github.com/navam-io/navam-invest)** - Source code, issues, PRs
- **[PyPI Package](https://pypi.org/project/navam-invest/)** - Latest releases
- **[Release Notes](backlog/)** - Detailed changelog for each version
- **[Integration Guide](backlog/edgar-yahoo-integration.md)** - Yahoo Finance + EDGAR integration
- **[Architecture Specs](refer/specs/)** - Technical design documents
- **[LangGraph Guide](refer/langgraph/)** - Multi-agent patterns & best practices

### API Documentation

- **[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
- **[SEC EDGAR](https://www.sec.gov/edgar/sec-api-documentation)** - Corporate filings
- **[Alpha Vantage](https://www.alphavantage.co/documentation/)** - Stock market data
- **[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

### Development

#### Running Tests

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

#### Code Quality

```bash
black src/ tests/        # Format code (88 char line length)
ruff check src/ tests/   # Lint code
mypy src/                # Type check (strict mode)
```

#### Building from Source

```bash
# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Build distribution
python -m build

# Check package before upload
twine check dist/*

# Upload to PyPI (maintainers only)
twine upload dist/*
```

---

## 🗺️ Roadmap

### Current Release: v0.1.31 (In Development)

**Status**: Active development

**Latest Updates**:
- ✅ **Enhanced UX**: Smart input disabling during processing
- ✅ **Live Status**: Real-time footer updates ("Processing..." → "Ready")
- ✅ **Full Responses**: Increased max_tokens to 8192 (no more truncation)
- ✅ **Error Recovery**: Input always re-enables, even on errors

**Planned Features**:
- [ ] News Sentry agent (real-time event detection, 8-K material event monitoring)
- [ ] Enhanced multi-agent workflows (extend `/analyze` with additional agents)
- [ ] API caching layer (DuckDB-based caching to reduce API calls)
- [ ] Options analysis tools (Yahoo Finance options chain integration)
- [ ] Risk management enhancements (drawdown analysis, VAR calculations)

### Recent Releases

<details>
<summary><b>v0.1.30 (Jan 8, 2025) - API Reliability Improvements</b></summary>

**Removed**: Financial Modeling Prep (FMP) API due to free tier access errors

**Benefits**:
- ✅ 100% reliable APIs (Yahoo + SEC have no rate limits)
- ✅ Better data quality (Yahoo has real-time data)
- ✅ Simpler setup (one less API key required)
- ✅ No more "Access denied" errors

**Updates**: 32 tools across 9 APIs (down from 36 tools, 10 APIs)

[Full Release Notes](backlog/release-0.1.30.md)

</details>

<details>
<summary><b>v0.1.28 (Jan 5, 2025) - Self-Service API Status</b></summary>

**New**: `/api` command for interactive API connectivity testing

**Features**:
- ✅ Real-time validation of all 9 data providers
- ✅ Rich table formatting with color-coded status (✅/❌/⚪)
- ✅ Troubleshooting tips and error diagnosis
- ✅ Documentation clarifying NewsAPI.org vs NewsAPI.ai

[Full Release Notes](backlog/release-0.1.28.md)

</details>

<details>
<summary><b>v0.1.27 (Dec 29, 2024) - Earnings Whisperer Agent</b></summary>

**New Agent**: Earnings Whisperer for earnings surprise analysis and post-earnings drift detection

**Features**:
- ✅ 14 specialized tools (Yahoo Finance + SEC + Finnhub)
- ✅ 5-step earnings analysis framework
- ✅ Pattern recognition (consistent beaters, accelerating beats, drift opportunities)
- ✅ Trading signals (BUY/HOLD/SELL on earnings)
- ✅ TUI command: `/earnings`

[Full Release Notes](backlog/release-0.1.27.md)

</details>

<details>
<summary><b>v0.1.26 (Dec 22, 2024) - Yahoo Finance + Enhanced EDGAR</b></summary>

**Major Update**: Yahoo Finance integration (11 FREE tools) + Enhanced SEC EDGAR (4 new tools)

**Features**:
- ✅ 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)
- ✅ Zero cost expansion ($2.4K-$10.8K/year savings)

**Agent Enhancements**: Quill (36 tools, up from 22), Screen Forge (15 tools), Macro Lens (13 tools)

[Full Release Notes](backlog/release-0.1.26.md)

</details>

### Future Releases

**v0.1.32-0.1.35** (Q1 2025):
- [ ] Additional specialized agents (Risk Shield, Tax Scout, Hedge Smith)
- [ ] Enhanced multi-agent workflows (parallel execution, conditional branching)
- [ ] Portfolio tracking & performance attribution
- [ ] State persistence (PostgreSQL checkpointer for LangGraph)

**v0.2.0+** (Q2 2025):
- [ ] Backtesting engine for investment strategies
- [ ] Risk management workflows (VaR, stress testing)
- [ ] Web UI (in addition to TUI)
- [ ] Cloud deployment options (LangGraph Cloud)
- [ ] API for third-party integrations

---

## 🤝 Contributing

Contributions are welcome! We're building the future of retail investment intelligence together.

### Ways to Contribute

- 🐛 **Report Bugs** - Submit detailed bug reports via [GitHub Issues](https://github.com/navam-io/navam-invest/issues)
- 💡 **Suggest Features** - Share ideas for new agents, workflows, or data sources
- 📝 **Improve Documentation** - Help make docs clearer and more comprehensive
- 🔧 **Submit PRs** - Code contributions for bug fixes, features, or tests

### Development Workflow

1. **Fork the repository** and clone locally
2. **Create a feature branch**: `git checkout -b feature/amazing-agent`
3. **Make your changes** with tests and documentation
4. **Run quality checks**: `black src/ tests/`, `ruff check`, `mypy src/`, `pytest`
5. **Commit with semantic messages**: `feat: Add News Sentry agent`
6. **Push and create a PR** with detailed description

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## 📄 License

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

**Key Points**:
- ✅ Free for personal and commercial use
- ✅ Modify and distribute as you wish
- ✅ No warranty provided

---

## 🙏 Acknowledgments

### Core Technologies

- **[Anthropic](https://www.anthropic.com/)** - Claude AI reasoning engine (Sonnet 4.5)
- **[LangChain](https://www.langchain.com/)** - Agent framework ecosystem (LangGraph orchestration)
- **[Textual](https://textual.textualize.io/)** - Modern terminal UI framework

### Data Providers

- **[Yahoo Finance](https://finance.yahoo.com/)** - Free real-time quotes, earnings, analyst ratings (via yfinance)
- **[SEC EDGAR](https://www.sec.gov/edgar)** - Corporate filings (10-K, 10-Q, 8-K, Form 4)
- **[U.S. Treasury](https://home.treasury.gov/)** - Yield curves, treasury rates
- **[Alpha Vantage](https://www.alphavantage.co/)** - Stock market data
- **[Tiingo](https://www.tiingo.com/)** - Historical fundamentals
- **[Finnhub](https://finnhub.io/)** - Alternative data & sentiment
- **[FRED](https://fred.stlouisfed.org/)** - Federal Reserve economic data
- **[NewsAPI.org](https://newsapi.org/)** - Market news & headlines

### Community

Special thanks to all contributors, users, and the open-source community for making this project possible.

---

<div align="center">

**Built with ❤️ for retail investors**

[![Star on GitHub](https://img.shields.io/github/stars/navam-io/navam-invest?style=social)](https://github.com/navam-io/navam-invest)
[![Follow on Twitter](https://img.shields.io/twitter/follow/navam_io?style=social)](https://twitter.com/navam_io)

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

</div>
