Metadata-Version: 2.4
Name: navam-invest
Version: 0.1.14
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
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 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)
[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)

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

</div>

---

## 🆕 What's New in v0.1.14

**Specialized Agents & Tools Registry** - Professional equity research and systematic screening:

- ✨ **Screen Forge Agent**: Systematic stock screening with multi-factor analysis (value, growth, quality, momentum)
- ✨ **Tools Registry Enhancement**: Agent-specific tool mappings for optimal specialization
- ✨ **Phase 2A Complete**: Quill (v0.1.13) + Screen Forge (v0.1.14) specialized agents

**Agent Count**: 2 → **4 specialized agents** | **Tool Registry**: Agent-optimized tool sets

See [Release Notes](backlog/release-0.1.14.md) for details | Previous: [v0.1.13 - Quill Agent](backlog/release-0.1.13.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** for equity research, systematic screening, portfolio analysis, and market research—all accessible through an interactive terminal interface.

### Why Navam Invest?

- **🎯 Specialized Agents**: Purpose-built agents for equity research, screening, portfolio analysis, and macro research
- **🔒 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
- **🆓 Free Data Sources**: Leverages high-quality public APIs (free tiers available)
- **🔧 Extensible**: Modular architecture makes it easy to add new agents and data sources

---

## ✨ Features

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

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

#### **Quill - Equity Research** 🆕
*Deep fundamental analysis & thesis building*

- Investment thesis development
- DCF & comparable company valuation
- 5-year historical fundamentals (Tiingo)
- Quarterly earnings tracking
- SEC filings analysis (10-K, 10-Q)
- Insider trading pattern analysis
- Company-specific news validation
- **16 specialized tools**

**Use Case**: "Analyze AAPL and provide an investment thesis with fair value"

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

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

- Multi-factor screening (value, growth, quality)
- Systematic candidate identification
- Weekly watchlist generation
- Factor-based ranking systems
- Sentiment validation (Finnhub)
- Integration with Quill for deep-dives
- **9 specialized tools**

**Use Case**: "Screen for value stocks with P/E < 15 and market cap > $1B"

</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)

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

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

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

### 📊 **Real API Integrations** (27 Tools Across 8 Data Sources)

| API | Tools | Purpose | Free Tier |
|-----|-------|---------|-----------|
| **Alpha Vantage** | 2 | Stock prices, company overviews | 25-500 calls/day |
| **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 |
| **FRED (St. Louis Fed)** | 2 | Economic indicators, macro data | Unlimited |
| **U.S. Treasury** | 4 | Yield curves, treasury rates | Unlimited |
| **SEC EDGAR** | 5 | Corporate filings (10-K, 10-Q, 13F) | 10 req/sec |
| **NewsAPI.org** | 3 | Market news, headlines | 100 calls/day |
| **Anthropic Claude** | - | AI reasoning (Sonnet 4.5) | Pay-as-you-go |

### 💬 **Interactive Terminal UI**

- **Chat Interface**: Natural language interaction with specialized agents
- **Real-time Streaming**: Watch agents think and reason live
- **Granular Progress**: See which tools are called with what arguments
- **Markdown Rendering**: Beautiful formatted output with tables
- **Agent Switching**: `/quill`, `/screen`, `/portfolio`, `/research`
- **Command Palette**: Quick access to common actions
- **File Reading**: Analyze local portfolio files

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

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

**Architecture Highlights**:
- **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
   ```

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

   | Service | Link | Free Tier |
   |---------|------|-----------|
   | **Anthropic** ⭐ | [console.anthropic.com](https://console.anthropic.com/) | Pay-as-you-go ($3-15/M tokens) |
   | **Alpha Vantage** | [alphavantage.co/support/#api-key](https://www.alphavantage.co/support/#api-key) | 25 calls/day |
   | **FMP** | [financialmodelingprep.com/developer](https://financialmodelingprep.com/developer) | 250 calls/day |
   | **Tiingo** | [tiingo.com](https://www.tiingo.com/) | 50 symbols/hr, 5yr history |
   | **Finnhub** | [finnhub.io/register](https://finnhub.io/register) | 60 calls/min |
   | **FRED** | [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) | Unlimited |
   | **NewsAPI** | [newsapi.org/register](https://newsapi.org/register) | 100 calls/day |
   | **Treasury & SEC** | - | No keys required! |

### Usage

#### Launch the Interactive Interface

```bash
navam invest
```

This opens an interactive chat interface with 4 specialized AI agents.

#### Quick Command Reference

| Command | Agent | Description |
|---------|-------|-------------|
| `/quill` 🆕 | Quill (Equity Research) | Deep fundamental analysis & thesis building |
| `/screen` 🆕 | Screen Forge | Systematic stock screening & idea generation |
| `/portfolio` | Portfolio Analysis | Comprehensive stock & portfolio tools |
| `/research` | Market Research | Macroeconomic analysis & treasury data |
| `/examples` | - | Show example queries for current agent |
| `/help` | - | Show all commands |
| `/clear` | - | Clear chat history |
| `/quit` | - | Exit application |

---

## 💡 Example Interactions

### Quill - Equity Research Agent 🆕

<details>
<summary><b>📊 Investment Thesis & Valuation</b></summary>

```
You: /quill
You: Analyze AAPL and provide an investment thesis with fair value

Quill (Equity Research):
  → Calling get_stock_price(symbol=AAPL)
  ✓ get_stock_price completed
  → Calling get_company_fundamentals(symbol=AAPL)
  ✓ get_company_fundamentals completed
  → Calling get_historical_fundamentals(symbol=AAPL, years=5)
  ✓ get_historical_fundamentals completed

**AAPL - Investment Thesis**

**Recommendation**: BUY
**Fair Value Range**: $185 - $205 (Current: $178)

**Investment Thesis**:
Apple demonstrates exceptional business quality with a durable competitive moat
in hardware/software integration. The services transition is accelerating with
28% annual growth, improving margins and reducing cyclicality. 5-year revenue
CAGR of 8.7% with expanding net margins (21% → 25%) shows pricing power.

**Key Catalysts**:
1. Vision Pro spatial computing platform opening new TAM
2. Services growth (Apple One, advertising) driving margin expansion
3. India manufacturing diversification reducing supply chain risk

**Key Risks**:
1. iPhone dependency (52% of revenue) creates cyclical exposure
2. Regulatory pressure on App Store (EU DMA compliance)
3. Premium valuation (P/E 30x) limits margin of safety

**Valuation**:
- DCF (10% WACC, 3% terminal growth): $195
- P/E multiple (25x normalized earnings): $185
- Fair value: $190 (7% upside from current)

**Financial Metrics**:
- ROE: 147% (exceptional capital efficiency)
- Free Cash Flow: $100B annually (supports $15B dividends + buybacks)
- Debt/Equity: 1.69 (manageable with strong cash generation)
```
</details>

### Screen Forge - Equity Screening Agent 🆕

<details>
<summary><b>🔍 Multi-Factor Stock Screening</b></summary>

```
You: /screen
You: Screen for value stocks: P/E under 15, P/B under 2, market cap over $1B

Screen Forge (Equity Screening):
  → Calling screen_stocks(peRatioLowerThan=15, pbRatioLowerThan=2...)
  ✓ screen_stocks completed
  → Calling get_financial_ratios(symbol=BAC)
  ✓ get_financial_ratios completed

**Stock Screening Results - Value Screen**

**Methodology**: Value stocks with P/E < 15, P/B < 2, Market Cap > $1B
**Candidates Found**: 12 stocks | **Top 5 Shown**

**1. BAC - Bank of America Corp**
   Price: $34.50 | Market Cap: $271.2B
   P/E: 11.2 | P/B: 1.1 | ROE: 9.8%
   **Standout**: Trading below book value with solid profitability

**2. WFC - Wells Fargo & Company**
   Price: $48.20 | Market Cap: $168.5B
   P/E: 10.5 | P/B: 1.3 | ROE: 12.4%
   **Standout**: Highest ROE in banking peers, P/E at 5-year low

**3. VZ - Verizon Communications**
   Price: $41.30 | Market Cap: $173.4B
   P/E: 8.9 | P/B: 1.8 | Dividend Yield: 6.2%
   **Standout**: Defensive telecom with strong dividend yield

**4. PFE - Pfizer Inc**
   Price: $28.70 | Market Cap: $161.8B
   P/E: 9.4 | P/B: 1.5 | Net Margin: 18.3%
   **Standout**: Beaten down pharma with strong pipeline

**5. CVX - Chevron Corporation**
   Price: $156.80 | Market Cap: $289.3B
   P/E: 10.8 | P/B: 1.7 | FCF Yield: 8.1%
   **Standout**: Energy major with exceptional free cash flow

**Next Steps**:
→ Deep dive with Quill on top 3 picks (BAC, WFC, VZ)
→ Consider sector diversification (3 financials, 1 telecom, 1 pharma, 1 energy)
→ Validate thesis with macro environment (interest rate sensitivity for financials)

**Screening Limitations**:
- Excludes companies with negative earnings
- Does not account for cyclical earnings adjustments
- Static snapshot; fundamentals may change
```
</details>

### Portfolio Analysis Examples

<details>
<summary><b>📈 Stock Fundamentals & Ratios</b></summary>

```
You: /portfolio
You: Show me MSFT's financial ratios

Portfolio Analyst:
**MSFT - Financial Ratios**

**Profitability:**
Gross Margin: 0.68
Operating Margin: 0.42
Net Margin: 0.36
ROE: 0.43
ROA: 0.19

**Liquidity:**
Current Ratio: 1.31
Quick Ratio: 1.27

**Leverage:**
Debt/Equity: 0.39
Interest Coverage: 28.5x

**Valuation:**
P/E Ratio: 34.2
P/B Ratio: 12.8
EV/EBITDA: 22.1
```
</details>

<details>
<summary><b>📰 Sentiment Analysis</b></summary>

```
You: What's the sentiment around NVDA?

Portfolio Analyst:
**NVDA - Sentiment Analysis**

**News Sentiment** (Finnhub):
Company Score: 0.82 (Very Bullish)
Sector Average: 0.58
Articles (7 days): 67 | Buzz: 2.1x

**Social Sentiment**:
Reddit: 4,500 mentions | Score: 0.73 (Positive)
Twitter: 12,300 mentions | Score: 0.68 (Positive)

**Insider Sentiment**:
MSPR: 0.45 (Strong net buying)
Recent Insider Buys: 3 executives ($2.1M)

**Analyst Recommendations**:
Strong Buy: 25 | Buy: 8 | Hold: 2 | Sell: 0
Consensus: 🟢 Very Bullish (AI accelerator dominance)
```
</details>

### Market Research Examples

<details>
<summary><b>📊 Macro Indicators & Yield Curve</b></summary>

```
You: /research
You: Show me key economic indicators and the yield curve

Market Researcher:
**Key Macroeconomic Indicators**

**GDP Growth (Real):** 2.4% (Q3 2024)
**Unemployment Rate:** 3.9% (October 2024)
**CPI Inflation:** 3.2% (YoY, October 2024)
**Fed Funds Rate:** 5.25-5.50% (Current)

**U.S. Treasury Yield Curve** (2025-10-06)

1 Month:   5.42%  |  1 Year:    5.15%
3 Month:   5.38%  |  2 Year:    4.82%
6 Month:   5.32%  |  5 Year:    4.35%
                  | 10 Year:    4.28%
                  | 30 Year:    4.42%

**2Y-10Y Spread:** -0.54% (Inverted)
**Curve Shape:** 🔴 Inverted (Recession signal)

**Economic Regime:** Late Cycle Expansion
**Investment Implications:** Defensive positioning, monitor credit spreads
```
</details>

---

## 📚 Documentation

### Agent Tool Mappings

Each specialized agent has curated tools for optimal performance:

| Agent | Tool Count | Categories | Focus |
|-------|------------|------------|-------|
| **Quill** 🆕 | 16 | Market, Fundamentals, SEC, News | Deep fundamental analysis, thesis building |
| **Screen Forge** 🆕 | 9 | Market, Fundamentals, Sentiment | Systematic screening, idea generation |
| **Portfolio** | 24 | All categories | Comprehensive backward compatibility |
| **Research** | 10 | Macro, Treasury, News | Top-down economic analysis |

### Project Structure

```
navam-invest/
├── src/navam_invest/
│   ├── agents/                 # 🤖 LangGraph specialized agents
│   │   ├── quill.py           #    🆕 Equity research analyst
│   │   ├── screen_forge.py    #    🆕 Systematic screener
│   │   ├── portfolio.py       #    Portfolio analysis (legacy)
│   │   └── research.py        #    Market research (legacy)
│   ├── tools/                  # 🔧 API integration (27 tools)
│   │   ├── __init__.py        #    Tools registry with agent mappings
│   │   ├── alpha_vantage.py   #    Stock prices & overviews
│   │   ├── fmp.py             #    Fundamentals & screening
│   │   ├── tiingo.py          #    Historical fundamentals
│   │   ├── finnhub.py         #    Sentiment & alternative data
│   │   ├── fred.py            #    Economic indicators
│   │   ├── treasury.py        #    Yield curves & treasury data
│   │   ├── sec_edgar.py       #    Corporate filings
│   │   ├── newsapi.py         #    Market news
│   │   └── file_reader.py     #    Local file reading
│   ├── tui/                    # 💬 Textual terminal UI
│   │   └── app.py             #    Chat interface with streaming
│   ├── config/                 # ⚙️ Configuration
│   │   └── settings.py        #    Pydantic settings with .env
│   └── cli.py                  # 🖥️ Typer CLI entry point
├── tests/                      # ✅ Test suite (48 tests, 39% coverage)
├── backlog/                    # 📋 Development roadmap
│   ├── active.md              #    Current tasks
│   └── release-*.md           #    Release notes
└── pyproject.toml             # 📦 Package configuration
```

### Technology Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| **AI & Agents** | LangGraph 0.2+, LangChain Core 0.3+, Anthropic Claude Sonnet 4.5 | Agent orchestration, tool framework, AI reasoning |
| **User Interface** | Textual 1.0+, Typer 0.15+, Rich 13+ | Terminal UI, CLI framework, markdown rendering |
| **Data & HTTP** | httpx 0.28+, Pydantic 2.0+, python-dotenv | Async HTTP, data validation, config management |

---

## 🛠️ Development

### Setup Development Environment

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

### Running Tests

```bash
# All tests with coverage
pytest

# Specific test file
pytest tests/test_finnhub.py -v

# With coverage report
pytest --cov=src/navam_invest --cov-report=term-missing
```

**Current Status**: ✅ 48/48 tests passing (39% coverage)

### Code Quality

```bash
# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

# All quality checks
black src/ tests/ && ruff check src/ tests/ && mypy src/
```

---

## 🤝 Contributing

Contributions are welcome! Here's how:

1. **🐛 Report Bugs**: [Open an issue](https://github.com/navam-io/navam-invest/issues)
2. **💡 Suggest Features**: [Start a discussion](https://github.com/navam-io/navam-invest/discussions)
3. **📝 Improve Docs**: Submit PR for documentation
4. **🔧 Submit Code**: Fork, branch, PR

### Development Workflow

```bash
# 1. Create feature branch
git checkout -b feature/your-feature

# 2. Make changes and test
pytest && black src/ tests/

# 3. Commit and push
git commit -m "feat: add your feature"
git push origin feature/your-feature

# 4. Open Pull Request
```

See `CLAUDE.md` for comprehensive agent development guide.

---

## 📋 Roadmap

### ✅ v0.1.14 (Current)
- [x] Screen Forge agent - Systematic stock screening
- [x] Tools registry enhancement - Agent-specific mappings
- [x] Phase 2A complete - Specialized agents architecture

### 🚀 v0.1.15 (Next - Phase 2B)
- [ ] Multi-agent workflows - Comprehensive investment analysis
- [ ] `/analyze <SYMBOL>` command - End-to-end analysis
- [ ] Refactor Portfolio → Atlas (Investment Strategist)
- [ ] Refactor Research → Macro Lens (Market Strategist)

### v0.2.0 (Planned)
- [ ] Multi-agent supervisor for coordinated workflows
- [ ] Tax-loss harvesting agent
- [ ] Portfolio optimization (PyPortfolioOpt)
- [ ] Conversation persistence (LangGraph checkpointers)
- [ ] Enhanced TUI with portfolio panels

### Future
- [ ] Web UI (Streamlit or FastAPI)
- [ ] LangGraph Cloud deployment
- [ ] Broker integrations (Alpaca, IBKR)

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

**Built with**:
- [LangGraph](https://github.com/langchain-ai/langgraph) - Agent orchestration
- [Anthropic Claude](https://www.anthropic.com/) - AI reasoning
- [Textual](https://github.com/Textualize/textual) - Terminal UI

**Data sources**:
- [Alpha Vantage](https://www.alphavantage.co/), [FMP](https://financialmodelingprep.com/), [Tiingo](https://www.tiingo.com/)
- [Finnhub](https://finnhub.io/), [FRED](https://fred.stlouisfed.org/), [U.S. Treasury](https://fiscaldata.treasury.gov/)
- [SEC EDGAR](https://www.sec.gov/edgar), [NewsAPI](https://newsapi.org/)

---

## 🔗 Links

- **PyPI**: [pypi.org/project/navam-invest](https://pypi.org/project/navam-invest/)
- **GitHub**: [github.com/navam-io/navam-invest](https://github.com/navam-io/navam-invest)
- **Issues**: [Report bugs](https://github.com/navam-io/navam-invest/issues)
- **Discussions**: [Join conversation](https://github.com/navam-io/navam-invest/discussions)

---

<div align="center">

**⭐ Star this project if you find it useful!**

Made with ❤️ by the Navam team

</div>
