navam-invest 0.1.12

AI agents and tools for the retail investor

🤖 Navam Invest

AI-Powered Investment Advisor for Retail Investors

Features • Quick Start • Examples • Documentation • Contributing

---

🆕 What's New in v0.1.12 (In Development)

Tiingo Integration & Real-Time Streaming - Historical fundamentals and transparent AI execution:

• ✨ Historical Fundamentals: 5-year trend analysis, quarterly statements, CAGR calculations (Tiingo)
• ✨ Granular Progress Streaming: Real-time visibility into agent reasoning and tool execution
• ✨ Enhanced Transparency: See which APIs are called, what arguments are used, live tool status

Tool Count: 23 → 27 tools (+17% growth) | Full release notes: v0.1.12

---

📖 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 portfolio analysis, market research, and investment insights—all accessible through an interactive terminal interface.

Why Navam Invest?

• 🎯 Institutional Intelligence: Access the same analytical depth once reserved for institutional portfolios
• 🔒 Privacy-First: Run locally with your own API keys—your data stays yours
• 💡 Transparent: Full audit trails and explainable AI reasoning
• 🆓 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

🤖 AI Agents Powered by LangGraph

Portfolio Analysis Agent Real-time stock quotes and metrics Company fundamentals & financial ratios 5-year historical fundamentals 🆕 Quarterly statement tracking 🆕 News & social sentiment analysis Insider sentiment tracking (MSPR) Analyst recommendation trends SEC filings (10-K, 10-Q, 13F) Multi-criteria stock screening Local file reading (CSV, JSON, Excel)

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

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

API	Tools	Purpose	Free Tier
Alpha Vantage	2	Stock prices, company overviews, technical indicators	25-500 calls/day
Financial Modeling Prep	4	Financial statements, ratios, insider trades, screening	250 calls/day
Tiingo 🆕	4	Historical fundamentals (5yr), quarterly statements, daily metrics	50 symbols/hr
Finnhub	5	News sentiment, social sentiment, 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, debt metrics	Unlimited
SEC EDGAR	5	Corporate filings (10-K, 10-Q, 13F)	10 req/sec
NewsAPI.org	3	Market news, headlines, company news	100 calls/day
Anthropic Claude	-	AI reasoning and tool orchestration	Pay-as-you-go

💬 Interactive Terminal UI

• Chat Interface: Natural language interaction with AI agents
• Real-time Streaming: Watch agents think and reason in real-time
• Granular Progress 🆕: See which tools are called, with what arguments, and live execution status
• Markdown Rendering: Beautiful formatted output with tables and lists
• Agent Switching: Seamlessly switch between specialized agents (/portfolio, /research)
• Command Palette: Quick access to common actions
• File Reading: Analyze local portfolio files (CSV, JSON, Excel)

🏗️ Built on Modern Tech

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

---

🚀 Quick Start

Prerequisites

• Python 3.9+ (3.13 recommended)
• pip or uv 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	Notes
   Anthropic	console.anthropic.com	Required - Pay-as-you-go ($3-15/M tokens)
   Alpha Vantage	alphavantage.co/support/#api-key	Free tier: 25 calls/day
   FMP	financialmodelingprep.com/developer	Free tier: 250 calls/day
   Tiingo	tiingo.com	Free tier: 50 symbols/hr, 5yr history
   Finnhub	finnhub.io/register	Free tier: 60 calls/min
   FRED	fredaccount.stlouisfed.org/apikeys	Free - Unlimited
   NewsAPI	newsapi.org/register	Free tier: 100 calls/day
   Treasury & SEC	-	No API keys required!

Usage

Launch the Interactive Interface

navam invest

This opens an interactive chat interface where you can talk to AI agents in natural language.

---

💡 Example Interactions

Portfolio Analysis Examples

📈 Stock Price & Overview

You: What's the current price of AAPL?

Portfolio Agent:
**AAPL - Stock Price**
Symbol: AAPL
Price: $178.25
Change: +2.45 (+1.39%)
Volume: 45,234,567
Market Cap: $2.81T

💰 Financial Fundamentals

You: Show me Apple's financial ratios

Portfolio Agent:
**AAPL - Financial Ratios**

**Liquidity:**
Current Ratio: 0.98
Quick Ratio: 0.83

**Profitability:**
Gross Margin: 0.44
Operating Margin: 0.30
Net Margin: 0.25

**Returns:**
ROE: 1.47
ROA: 0.28

**Leverage:**
Debt Ratio: 0.32

📊 Historical Fundamentals Analysis (NEW!)

You: Analyze AAPL's historical fundamentals over the past 5 years

Portfolio Agent:
  → Calling get_historical_fundamentals(symbol=AAPL, years=5)
  ✓ get_historical_fundamentals completed

**AAPL - 5-Year Fundamental Trends**

**Revenue Growth:**
2020: $274.5B → 2024: $383.9B
CAGR: 8.7% (Steady growth)

**Profitability Trends:**
Net Margin: 21.2% → 25.3% (+4.1pp improvement)
ROE: 73.7% → 147.4% (Exceptional capital efficiency)

**Balance Sheet Strength:**
Total Assets: $323.9B → $365.7B (+12.9%)
Debt-to-Equity: 1.57 → 1.69 (Slight increase)

**Free Cash Flow:**
2020: $73.4B → 2024: $99.6B
5-Year Total: $452.8B (Strong cash generation)

**Valuation Trends:**
P/E Ratio: 28.5 → 30.2 (Premium valuation maintained)
P/B Ratio: 21.0 → 44.5 (Significant multiple expansion)

**Investment Thesis:**
Apple shows consistent revenue growth with improving profitability.
ROE expansion indicates exceptional capital allocation. Strong FCF
supports buybacks and dividends. Premium valuation reflects market
confidence in services transition.

🔍 Sentiment Analysis

You: What's the sentiment around TSLA?

Portfolio Agent:
**TSLA - News Sentiment Analysis**

**Sentiment Scores:**
Company News Score: 0.75
Sector Average: 0.62
Bullish: 68% | Bearish: 32%

**News Buzz:**
Articles Last Week: 45
Weekly Average: 32
Buzz Score: 1.4

**Social Media Sentiment:**
Reddit Mentions: 2,500 | Score: 0.65 (Positive)
Twitter Mentions: 5,200 | Score: 0.58 (Positive)

**Insider Sentiment:**
MSPR: 0.15 (Net buying)
Sentiment: 🟢 Bullish

**Analyst Recommendations:**
Strong Buy: 12 | Buy: 8 | Hold: 5 | Sell: 1
Consensus: 🟢 Bullish

📋 SEC Filings

You: Find me the latest 10-K for Apple

Portfolio Agent:
**AAPL - Latest 10-K Filing**

Filing Date: 2024-11-01
Period: FY 2024
Form: 10-K (Annual Report)

Document: https://www.sec.gov/cgi-bin/viewer?action=view&cik=0000320193&accession_number=...

Key Sections:
- Business Overview
- Risk Factors
- Financial Statements
- Management Discussion & Analysis

🎯 Stock Screening

You: Screen for tech stocks with market cap > $10B and P/E < 20

Portfolio Agent:
**Stock Screener Results**

**GOOGL** - Alphabet Inc
Sector: Technology | Price: $141.50
Market Cap: $1,750,234,567,890 | P/E: 18.2

**MSFT** - Microsoft Corporation
Sector: Technology | Price: $378.25
Market Cap: $2,801,456,789,012 | P/E: 19.5

**META** - Meta Platforms Inc
Sector: Technology | Price: $485.30
Market Cap: $1,234,567,890,123 | P/E: 16.8

Market Research Examples

📊 Economic Indicators

You: /research
You: Show me key economic indicators

Research Agent:
**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)

Economic Regime: Late Cycle Expansion

📈 Treasury Yield Curve

You: Show me the Treasury yield curve

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

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

**2Y-10Y Spread:** -0.54% (Inverted - Recession signal)
**Curve Shape:** Inverted (Short rates > Long rates)

📰 Market News

You: What's the latest market news?

Research Agent:
**Top Financial Headlines**

1. **Fed Signals Pause on Rate Hikes**
   Source: Reuters | 2 hours ago
   Summary: Federal Reserve officials indicate they may hold rates steady...

2. **Tech Stocks Rally on AI Optimism**
   Source: Bloomberg | 4 hours ago
   Summary: Major tech companies surge as investors bet on AI growth...

3. **Oil Prices Fall on Demand Concerns**
   Source: CNBC | 6 hours ago
   Summary: Crude oil drops 3% amid worries about global economic slowdown...

File Analysis Example

📁 Local Portfolio Analysis

You: Analyze my portfolio in portfolio.csv

Portfolio Agent:
**Portfolio Analysis**

Reading file: portfolio.csv

**Holdings:**
AAPL: 100 shares @ $178.25 = $17,825
MSFT: 50 shares @ $378.25 = $18,912.50
GOOGL: 75 shares @ $141.50 = $10,612.50

**Total Value:** $47,350
**Sector Allocation:**
- Technology: 100%

**Recommendations:**
- Portfolio is highly concentrated in tech sector
- Consider diversification into other sectors
- Current tech sentiment is bullish based on recent news

TUI Commands Reference

Command	Action
/portfolio	Switch to Portfolio Analysis Agent
/research	Switch to Market Research Agent
/examples	Show example queries
/help	Show help message
/quit or /exit	Exit application
/clear	Clear chat history
Ctrl+C	Clear input or chat
Ctrl+Q	Quit application

---

📚 Documentation

Project Structure

navam-invest/
├── src/navam_invest/
│   ├── agents/              # 🤖 LangGraph agent implementations
│   │   ├── portfolio.py     #    Portfolio analysis with ReAct pattern
│   │   └── research.py      #    Market research with macro tools
│   ├── tools/               # 🔧 API integration tools (23 tools total)
│   │   ├── alpha_vantage.py #    Stock price & fundamentals
│   │   ├── fmp.py           #    Financial statements & ratios
│   │   ├── tiingo.py        #    🆕 Historical fundamentals (5yr)
│   │   ├── finnhub.py       #    Sentiment & alternative data
│   │   ├── fred.py          #    Economic indicators & macro data
│   │   ├── treasury.py      #    Yield curves & treasury data
│   │   ├── sec_edgar.py     #    Corporate filings (10-K, 10-Q, 13F)
│   │   ├── newsapi.py       #    Market news & headlines
│   │   ├── file_reader.py   #    Local file reading
│   │   └── __init__.py      #    Unified tools registry
│   ├── tui/                 # 💬 Textual-based user interface
│   │   └── app.py           #    Chat interface with streaming
│   ├── config/              # ⚙️ Configuration management
│   │   └── settings.py      #    Pydantic settings with .env
│   └── cli.py               # 🖥️ Typer CLI entry point
├── tests/                   # ✅ Test suite (pytest + async)
│   ├── test_config.py
│   ├── test_tools.py
│   ├── test_tiingo.py       # 🆕 Tiingo tests (12 tests, 86% coverage)
│   ├── test_finnhub.py      # Finnhub tests
│   ├── test_newsapi.py
│   └── test_file_reader.py
├── refer/                   # 📖 Reference documentation
│   ├── langgraph/           #    LangGraph docs & examples
│   └── specs/               #    Project specifications
├── backlog/                 # 📋 Development backlog
│   ├── active.md            #    Current features
│   └── release-*.md         #    Release notes
├── .env.example             # 🔑 Environment template
├── pyproject.toml           # 📦 Package configuration
├── CLAUDE.md                # 🤖 AI assistant guide
└── README.md                # 📄 This file

Architecture

Technology Stack

AI & Agents	LangGraph 0.2+ - Agent orchestration, stateful workflows LangChain Core 0.3+ - Tool framework, message handling Anthropic Claude - Sonnet 4.5 for reasoning & analysis
User Interface	Textual 1.0+ - Modern terminal UI framework Typer 0.15+ - CLI framework with type hints Rich 13+ - Terminal formatting & markdown
Data & HTTP	httpx 0.28+ - Async HTTP client Pydantic 2.0+ - Data validation & settings python-dotenv - Environment management

Agent Design Pattern

Both agents implement the ReAct (Reasoning + Acting) pattern with tool calling:

User Query → Agent Reasoning → Tool Selection → Tool Execution → Response Formatting
     ↑                                                                    ↓
     └──────────────────── Streaming Updates ←──────────────────────────┘

Portfolio Analysis Agent (23 tools available):

• Market Data: get_stock_price, get_stock_overview (Alpha Vantage)
• Fundamentals: get_company_fundamentals, get_financial_ratios, get_insider_trades, screen_stocks (FMP)
• Historical Fundamentals 🆕: get_fundamentals_daily, get_fundamentals_statements, get_fundamentals_definitions, get_historical_fundamentals (Tiingo)
• Sentiment: get_company_news_sentiment, get_social_sentiment, get_insider_sentiment, get_recommendation_trends, get_finnhub_company_news (Finnhub)
• Filings: search_company_by_ticker, get_latest_10k, get_latest_10q, get_institutional_holdings, get_company_filings (SEC)
• News: search_market_news, get_company_news, get_top_financial_headlines (NewsAPI)
• Files: read_local_file, list_local_files (Local)

Market Research Agent (11 tools available):

• Macro: get_economic_indicator, get_key_macro_indicators (FRED)
• Treasury: get_treasury_yield_curve, get_treasury_rate, get_treasury_yield_spread, get_debt_to_gdp (Treasury)
• News: search_market_news, get_company_news, get_top_financial_headlines (NewsAPI)
• Files: read_local_file, list_local_files (Local)

---

🛠️ Development

Setup Development Environment

# Clone and setup
git clone https://github.com/navam-io/navam-invest.git
cd navam-invest
python3 -m venv .venv
source .venv/bin/activate

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

Running Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_finnhub.py -v

# Run with coverage report
pytest --cov=src/navam_invest --cov-report=term-missing

Current Coverage: 48/48 tests passing ✅ (43% overall coverage)

Code Quality

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

# Run all quality checks
black src/ tests/ && ruff check src/ tests/ && mypy src/

Development Tools

• Black - Code formatting (88 char line length)
• Ruff - Fast Python linter
• MyPy - Static type checking (strict mode enabled)
• pytest - Testing framework with async support
• Textual DevTools - TUI hot-reload (textual run --dev)

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🐛 Report Bugs: Open an issue
2. 💡 Suggest Features: Start a discussion
3. 📝 Improve Docs: Submit PR for documentation improvements
4. 🔧 Submit Code: Fork, create branch, submit PR

Development Workflow

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

# 2. Make changes and test
pytest

# 3. Format and lint
black src/ tests/
ruff check src/ tests/

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

# 5. Open Pull Request

Adding New Agents

See CLAUDE.md for comprehensive guide on adding new LangGraph agents and tools.

---

📋 Roadmap

✅ v0.1.12 (In Development)

• Tiingo integration (5-year historical fundamentals, quarterly statements, CAGR analysis)
• Granular progress streaming (real-time tool execution visibility)
• Enhanced TUI with transparent agent reasoning
• Agent refactoring plan and architecture design

🚀 v0.1.13-0.1.15 (Next - Phase 2A)

• Build Quill (Equity Research) agent - Deep fundamental analysis and thesis building
• Build Screen Forge agent - Systematic stock screening and idea generation
• Add agent selection in TUI: /quill, /screen commands
• Update tools registry to map tools to specialized agents

v0.2.0 (Planned - Phase 2B & Phase 3)

• Implement Workflow 1: Comprehensive Investment Analysis (Quill → Macro Lens → Atlas)
• Add workflow command: /analyze <SYMBOL> for end-to-end analysis
• Refactor Portfolio → Atlas (Investment Strategist)
• Refactor Research → Macro Lens (Market Strategist)
• Multi-agent supervisor for coordinated workflows
• Portfolio optimization tools (PyPortfolioOpt integration)
• Conversation persistence with LangGraph checkpointers
• Enhanced TUI with portfolio display panels

v0.3.0 (Planned)

• Tax-loss harvesting agent
• Risk metrics dashboard (VaR, beta, Sharpe)
• Backtesting framework with historical data
• Export capabilities (CSV/JSON/PDF)

Future

• Web UI (Streamlit or FastAPI + HTMX)
• LangGraph Cloud deployment
• Mobile app (React Native)
• Broker integrations (Alpaca, Interactive Brokers)

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with these amazing open-source projects:

• LangGraph - Agent orchestration framework
• LangChain - LLM application framework
• Anthropic Claude - AI reasoning engine
• Textual - Terminal UI framework
• Typer - CLI framework

Data sources:

• Alpha Vantage - Stock market data
• Financial Modeling Prep - Fundamentals & financials
• Tiingo - Historical fundamentals & quarterly tracking
• Finnhub - Alternative data & sentiment analysis
• FRED - Economic data from St. Louis Fed
• U.S. Treasury - Treasury yields & debt data
• SEC EDGAR - Corporate filings
• NewsAPI - Market news & headlines

---

🔗 Links

• Homepage: github.com/navam-io/navam-invest
• PyPI Package: pypi.org/project/navam-invest
• Documentation: View on GitHub
• Issues: Report bugs
• Discussions: Join the conversation

---

⭐ If you find this project useful, please consider giving it a star!

Made with ❤️ by the Navam team