navam-invest 0.1.14

AI agents and tools for the retail investor

🤖 Navam Invest

AI-Powered Investment Advisor for Retail Investors

Features • Quick Start • Agents • Examples • Documentation

---

🆕 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 for details | Previous: v0.1.13 - Quill Agent

---

📖 Overview

navam-invest brings institutional-grade portfolio intelligence to individual retail investors. Built with LangGraph and powered by Anthropic's 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)

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"	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"
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?"	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"

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

Installation

Option 1: Install from PyPI (Recommended)

pip install navam-invest

Option 2: Install from Source

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:

   cp .env.example .env
   

2. Add your API keys to .env:

   # 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	Pay-as-you-go ($3-15/M tokens)
   Alpha Vantage	alphavantage.co/support/#api-key	25 calls/day
   FMP	financialmodelingprep.com/developer	250 calls/day
   Tiingo	tiingo.com	50 symbols/hr, 5yr history
   Finnhub	finnhub.io/register	60 calls/min
   FRED	fredaccount.stlouisfed.org/apikeys	Unlimited
   NewsAPI	newsapi.org/register	100 calls/day
   Treasury & SEC	-	No keys required!

Usage

Launch the Interactive Interface

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 🆕

📊 Investment Thesis & Valuation

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)

Screen Forge - Equity Screening Agent 🆕

🔍 Multi-Factor Stock Screening

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

Portfolio Analysis Examples

📈 Stock Fundamentals & Ratios

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

📰 Sentiment Analysis

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)

Market Research Examples

📊 Macro Indicators & Yield Curve

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

---

📚 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

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

# 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

# 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
2. 💡 Suggest Features: Start a discussion
3. 📝 Improve Docs: Submit PR for documentation
4. 🔧 Submit Code: Fork, branch, PR

Development Workflow

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

• Screen Forge agent - Systematic stock screening
• Tools registry enhancement - Agent-specific mappings
• 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 file for details.

---

🙏 Acknowledgments

Built with:

• LangGraph - Agent orchestration
• Anthropic Claude - AI reasoning
• Textual - Terminal UI

Data sources:

• Alpha Vantage, FMP, Tiingo
• Finnhub, FRED, U.S. Treasury
• SEC EDGAR, NewsAPI

---

🔗 Links

• PyPI: pypi.org/project/navam-invest
• GitHub: github.com/navam-io/navam-invest
• Issues: Report bugs
• Discussions: Join conversation

---

⭐ Star this project if you find it useful!

Made with ❤️ by the Navam team