navam-invest 0.1.10

AI agents and tools for the retail investor

🤖 Navam Invest

AI-Powered Investment Advisor for Retail Investors

Features • Quick Start • Documentation • Contributing

---

🆕 What's New in v0.1.5

Tier 1 API Tools Expansion - Added 13 new tools across 3 major APIs:

• ✨ Financial Modeling Prep: Comprehensive fundamentals, ratios, insider trades, stock screening
• ✨ U.S. Treasury Data: Full yield curves (1M-30Y), spreads, debt metrics - no API key needed!
• ✨ SEC EDGAR: Corporate filings (10-K, 10-Q, 13F) with direct links

Tool Count: 4 → 17 tools (+325% growth) | Full release notes: v0.1.5

---

📖 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 (FRED, Alpha Vantage)
• 🔧 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 Insider trading activity tracking SEC filings (10-K, 10-Q, 13F) Multi-criteria stock screening

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

📊 Real API Integrations (17 Tools Across 5 Data Sources)

API	Tools	Purpose	Cost
Alpha Vantage	2	Stock prices, company fundamentals, technical indicators	Free tier: 25 calls/day
Financial Modeling Prep	4	Financial statements, ratios, insider trades, screening	Free tier: 250 calls/day
FRED (St. Louis Fed)	2	Economic indicators, macro data	Free (unlimited)
U.S. Treasury	4	Yield curves, treasury rates, debt data	Free (unlimited)
SEC EDGAR	5	Corporate filings (10-K, 10-Q, 13F)	Free (10 req/sec)
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
• Markdown Rendering: Beautiful formatted output with tables and lists
• Agent Switching: Seamlessly switch between specialized agents
• Command Palette: Quick access to common actions

🏗️ 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

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
   FRED_API_KEY=your_key_here
   FMP_API_KEY=your_key_here
   

3. Get API Keys (all free tiers available):

   • Anthropic: console.anthropic.com (pay-as-you-go)
   • Alpha Vantage: alphavantage.co/support/#api-key (free)
   • FRED: fredaccount.stlouisfed.org/apikeys (free)
   • FMP: financialmodelingprep.com/developer (free)
   • Treasury & SEC: No API keys required!

Usage

Launch the Interactive Interface

navam invest

Example Interactions

Portfolio Analysis:

You: What's the current price of AAPL?
Portfolio Agent: [Fetches real-time data and provides formatted response]

You: Show me Apple's financial ratios
Portfolio Agent: [Displays liquidity, profitability, leverage ratios]

You: Any recent insider trading at AAPL?
Portfolio Agent: [Shows latest insider buy/sell activity with dates and volumes]

You: Find me the latest 10-K for Apple
Portfolio Agent: [Retrieves SEC filing with direct link to document]

Market Research:

You: /research
You: What's the current GDP?
Research Agent: [Fetches latest GDP data from FRED with date and trend]

You: Show me the Treasury yield curve
Research Agent: [Displays full curve from 1M to 30Y with current rates]

You: What's the 2Y-10Y spread telling us?
Research Agent: [Calculates spread with economic interpretation (normal/inverted/flat)]

You: Give me key economic indicators
Research Agent: [Shows dashboard of GDP, unemployment, CPI, fed funds rate]

TUI Commands

Command	Action
/portfolio	Switch to Portfolio Analysis Agent
/research	Switch to Market Research Agent
/help	Show help message
Ctrl+C	Clear chat history
Ctrl+Q	Quit application

CLI Commands

navam invest    # Launch interactive chat interface
navam version   # Show version information
navam --help    # Show help

---

📚 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 (17 tools total)
│   │   ├── alpha_vantage.py #    Stock price & fundamentals
│   │   ├── fred.py          #    Economic indicators & macro data
│   │   ├── fmp.py           #    Financial statements & ratios
│   │   ├── treasury.py      #    Yield curves & treasury data
│   │   ├── sec_edgar.py     #    Corporate filings (10-K, 10-Q, 13F)
│   │   └── __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
├── 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:

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

Portfolio Analysis Agent (17 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)
• Filings: search_company_by_ticker, get_latest_10k, get_latest_10q, get_institutional_holdings, get_company_filings (SEC)
• Use cases: Stock analysis, fundamental screening, insider tracking, regulatory research

Market Research Agent (6 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)
• Use cases: Macro analysis, yield curve interpretation, regime detection, economic trends

---

🛠️ 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_tools.py -v

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

Current Coverage: 7/7 tests passing ✅

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
• 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.5 (Released 2025-10-05)

• Financial Modeling Prep integration (fundamentals, ratios, insider trades, screening)
• U.S. Treasury data integration (yield curves, spreads, debt metrics)
• SEC EDGAR integration (10-K, 10-Q, 13F filings)
• Unified tools registry (17 tools across 5 categories)

v0.2.0 (Planned)

• Tier 2 macro APIs (World Bank, OECD)
• Alternative data (CoinGecko crypto, NewsAPI sentiment)
• Portfolio optimization agent (MPT, Black-Litterman)
• Tax-loss harvesting agent
• Conversation persistence with LangGraph checkpointers
• Enhanced TUI with portfolio display panels

v0.3.0 (Planned)

• Multi-agent supervisor for coordinated analysis
• Backtesting framework with historical data
• Risk metrics dashboard (VaR, beta, Sharpe)
• Custom screening agents
• Export capabilities (CSV/JSON/PDF)

Future

• Web UI (Streamlit or FastAPI + HTMX)
• Mobile app (React Native)
• LangGraph Cloud deployment
• Social trading features

---

📄 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
• FRED - Economic data from St. Louis Fed
• U.S. Treasury - Treasury yields & debt data
• SEC EDGAR - Corporate filings

---

🔗 Links

• Homepage: github.com/navam-io/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