navam-invest 0.1.42

AI agents and tools for the retail investor

🧠 Navam Invest

AI-Powered Investment Intelligence for Retail Investors

Replace $1,000-$10,000/year wealth management fees with institutional-grade AI

Built on LangGraph • Powered by Anthropic Claude

Quick Start • Features • AI Agents • Workflows • Documentation

---

🎯 What is Navam Invest?

An open-source AI investment advisory platform for retail investors managing $50K-$1M portfolios. Get 10 specialized AI agents with automatic intent-based routing—all running locally with your API keys, using free public data.

Just ask naturally. No commands to memorize.

# Install and run
pip install navam-invest
navam invest

# Ask anything - AI routes to the right expert agents automatically
> Should I invest in Apple stock right now?
> Find undervalued tech stocks with strong earnings momentum
> How can I reduce my tax bill before year-end?
> Protect my NVDA position with options strategies

---

💡 What You Get

🏦 Institutional Intelligence 10 specialized AI agents working together: Equity Research - Deep fundamental analysis Earnings Analysis - Post-earnings drift detection Stock Screening - Systematic idea generation Macro Strategy - Top-down economic context Risk Management - Portfolio exposure analysis Tax Optimization - Tax-loss harvesting Options Strategies - Portfolio hedging Event Monitoring - Real-time alerts Asset Allocation - Strategic planning + Automatic routing - Just ask naturally, no commands needed

💰 Zero Lock-In, Maximum Value Free to run with public data: ✅ Yahoo Finance (unlimited, no key) ✅ SEC EDGAR (unlimited, no key) ✅ U.S. Treasury (unlimited, no key) ✅ 6 optional APIs (generous free tiers) Your data stays yours: Runs 100% locally on your machine No subscription fees, no recurring costs Open source MIT license

🔍 Transparent & Explainable Watch AI agents think in real-time: Progressive streaming of reasoning Full audit trails of data sources Educational explanations, not black boxes Tool execution tracking Production-ready features: ESC to cancel long operations Auto-save all reports Smart API caching (instant responses) Non-blocking terminal UI

⚡ Rich Data Access 32 tools across 9 APIs: Real-time quotes & earnings SEC filings (10-K, 10-Q, 8-K) Insider transactions (Form 4) Economic indicators (GDP, CPI) Yield curves & interest rates News & sentiment analysis Options chains & Greeks Analyst ratings & estimates 80% of features work with zero API keys!

---

🆚 Why Navam Invest?

Solution	Cost	Intelligence	Transparency
Wealth Manager	$1K-$10K/year (1% AUM)	✅ Expert analysis	❌ Black box decisions
Robo-Advisor	$250-$1K/year (0.25% AUM)	⚠️ Basic rebalancing	⚠️ Limited transparency
DIY Research	Free	⚠️ Time-consuming	✅ Full control
Navam Invest	$3-15/month (AI API costs)	✅ 10 AI experts	✅ Full audit trails

---

🚀 Quick Start

Installation (2 minutes)

Requirements: Python 3.9+ and an Anthropic API key

# Install from PyPI
pip install navam-invest

# Start the interactive terminal
navam invest

Setup (3 minutes)

1. Get your Anthropic API key (required):

Visit console.anthropic.com and create a free account. 💰 Cost: ~$3-15/month for typical usage (pay-as-you-go, no subscription)

2. Create environment file:

# Copy example file
cp .env.example .env

# Add your key
echo "ANTHROPIC_API_KEY=sk-ant-your-key-here" >> .env

3. Optional: Add free-tier API keys (recommended):

# All have generous free tiers - get keys at their websites
FRED_API_KEY=your_key_here          # Unlimited economic data
TIINGO_API_KEY=your_key_here        # 50 symbols/hr historical data
FINNHUB_API_KEY=your_key_here       # 60 calls/min sentiment
NEWSAPI_API_KEY=your_key_here       # 1,000 calls/day news
ALPHA_VANTAGE_API_KEY=your_key_here # 25-500 calls/day quotes

4. Verify setup:

navam invest
> /api
# Shows: ✅ working / ⚪ not configured / ❌ failed

First Query (1 minute)

navam invest

# Optional: Pre-warm cache for faster queries
> /cache warm
# Loads 23 common queries (FAANG+ stocks, indices, GDP/CPI)
# Takes 60 seconds, but future queries are instant!

# Just ask naturally - automatic routing!
> Should I invest in Apple stock right now?
# → Router selects Quill (fundamentals), Macro Lens (timing), Risk Shield (exposure)
# → Comprehensive BUY/HOLD/SELL recommendation in 30 seconds

> Find undervalued tech stocks with strong earnings momentum
# → Router selects Screen Forge (screening) + Earnings Whisperer (earnings)
# → Ranked list of 10-15 candidates with analysis

# Or use workflows for systematic analysis
> /analyze MSFT
# 5-agent comprehensive investment analysis

> /optimize-tax I hold GOOGL at $150, now $120
# Tax-loss harvesting with replacement strategies

> /protect I hold 1000 NVDA shares, worried about correction
# Portfolio hedging with protective options

# Cache management (NEW in v0.1.41)
> /cache
# View hit rates, cached tools, API savings

> /cache clear
# Invalidate all cached entries

🎓 New to Navam Invest? See the Getting Started Guide for detailed walkthroughs.

---

✨ Key Features

🔀 Automatic Intent-Based Routing (v0.1.36+)

No more manual agent switching! Just ask your question naturally:

# Simply ask - the router automatically selects the right agent(s)
> Should I invest in AAPL?
# → Routes to Quill (fundamentals) + Macro Lens (timing) + Risk Shield (exposure)

> Find undervalued tech stocks with strong earnings momentum
# → Routes to Screen Forge + Earnings Whisperer

> Protect my NVDA position with options
# → Routes to Hedge Smith for options strategies

Power users can still use manual commands (/quill, /hedge, /risk) for direct agent control.

⚡ Smart API Caching (v0.1.41+)

DuckDB-powered caching that dramatically reduces API calls:

• ✅ 42 cached tools across 9 data sources
• ✅ Intelligent TTL: Real-time (60s), fundamentals (1h), economic data (24h)
• ✅ Cache warming: Pre-populate with /cache warm (23 common queries)
• ✅ Performance stats: /cache shows hit rates and API savings
• ✅ Zero config: Works out-of-the-box

Expected Performance:

• 20-40% hit rates on economic indicators
• 40-70% hit rates on treasury data
• 10-30% hit rates on equity data
• Higher over time as you query the same stocks repeatedly

💬 Modern Terminal UI

Built with Textual framework for responsive CLI:

• ✅ Progressive streaming: Watch tool calls appear in real-time
• ✅ ESC cancellation: Cancel long operations anytime (v0.1.38+)
• ✅ Non-blocking: Scroll and interact while agents work
• ✅ Markdown rendering: Tables, code blocks, syntax highlighting
• ✅ Auto-save reports: All responses >200 chars saved to reports/
• ✅ Keyboard shortcuts: ESC (cancel), Ctrl+C (clear), Ctrl+Q (quit)

---

🤖 10 Specialized AI Agents

Each agent is purpose-built with curated tools and expert system prompts:

Agent	Purpose	Tools	Example Query
Quill	Deep fundamental research	36	"Analyze AAPL with DCF valuation and insider activity"
Earnings Whisperer	Earnings surprise analysis	14	"Find post-earnings drift opportunities in NVDA"
Screen Forge	Systematic stock screening	15	"Screen for stocks with 3+ consecutive earnings beats"
Macro Lens	Top-down macro analysis	13	"What's the current economic regime for tech stocks?"
News Sentry	Real-time event detection	13	"Alert me to material 8-K filings and insider trades"
Risk Shield	Portfolio risk management	18	"Calculate VAR and analyze concentration risks"
Tax Scout	Tax-loss harvesting	12	"Identify tax-loss harvesting opportunities"
Hedge Smith	Options strategies	13	"Design a protective collar for my AAPL position"
Atlas	Strategic asset allocation	12	"Create an IPS for $200K portfolio"
Portfolio/Research	Legacy general-purpose	24/10	Backward compatibility

📖 View detailed agent capabilities

⭐ Quill - Equity Research Analyst

Deep fundamental analysis & investment thesis development

What Quill Does:

• 📊 DCF Valuation: Discounted cash flow models with sensitivity analysis
• 📈 5-Year Trends: Revenue growth, margins, ROIC, FCF, debt ratios
• 💰 Earnings Analysis: Historical beats, estimates, surprise patterns
• 🎯 Analyst Coverage: Consensus ratings, price targets, upgrades/downgrades
• 🏢 Ownership Tracking: Institutional holders, insider transactions (Form 4)
• 📋 SEC Filings: 10-K/10-Q deep-dives, 8-K material events, XBRL data
• 💵 Dividend Analysis: Yield, payout sustainability, history
• 📰 News Validation: Company-specific news with sentiment

Example Output: 5-section investment thesis with BUY/HOLD/SELL recommendation, fair value range, key catalysts, and risk factors.

📊 Earnings Whisperer - Earnings Specialist

Earnings surprise analysis & post-earnings drift detection

What Earnings Whisperer Does:

• 🎯 Historical Tracking: 4-8 quarter earnings surprise analysis
• 📈 Drift Detection: 1-3 day post-earnings momentum patterns
• 🔄 Analyst Revisions: Estimate changes post-earnings
• ✅ Quality Assessment: Revenue vs EPS beats, non-recurring items
• 📅 Calendar Monitoring: Upcoming earnings with probability scoring
• 🏆 Pattern Recognition: Consistent beaters, accelerating growth
• 💹 Trading Signals: BUY/HOLD/SELL based on drift probability

Example Output: Earnings momentum scorecard with drift probability, pattern analysis, and trading recommendation.

🔍 Screen Forge - Equity Screener

Systematic stock discovery & idea generation

What Screen Forge Does:

• 📐 Multi-Factor Screening: Value, growth, quality, momentum factors
• 🎯 Systematic Discovery: Weekly watchlist generation with ranking
• 📈 Earnings Momentum: Filter for consistent earnings beaters
• ⬆️ Analyst Activity: Upgrade/downgrade-based screening
• 💬 Sentiment Validation: News and social sentiment checks
• 🔗 Seamless Handoff: Passes top candidates to Quill for deep-dive

Example Output: Ranked table of 10-20 candidates with screening criteria, key metrics, and suggested next steps.

🌍 Macro Lens - Market Strategist

Top-down economic analysis & regime identification

What Macro Lens Does:

• 🔄 Economic Cycles: 4-phase regime analysis (early/mid/late expansion, recession)
• 📈 Yield Curve: Interpretation and recession signal detection
• 🏭 Sector Allocation: Macro-driven positioning guidance
• 📊 Factor Recommendations: Value vs growth, size, volatility tilts
• 📉 Macro Tracking: Inflation, GDP, employment, Fed policy
• 💹 Interest Rates: Fed funds, treasury rates, credit spreads

Example Output: Regime assessment with sector allocation matrix, factor positioning, and macro risk scenarios.

🗞️ News Sentry - Real-Time Event Monitor

Material event detection & breaking news alerts

What News Sentry Does:

• 📋 8-K Monitoring: Material corporate events (M&A, management changes)
• 📝 Form 4 Tracking: Insider buying/selling by officers
• 📰 Breaking News: Real-time company-specific news with sentiment
• 📊 Analyst Actions: Rating changes, price target updates
• 🎯 Event Prioritization: CRITICAL/HIGH/MEDIUM/LOW urgency scoring
• ⚡ Rapid Response: Detect market-moving events as they happen

Example Output: Prioritized event list with urgency levels, event details, and recommended actions.

🛡️ Risk Shield - Portfolio Risk Manager

Comprehensive risk analysis & exposure monitoring

What Risk Shield Does:

• 📊 Concentration Analysis: Sector, geographic, single-stock exposures
• 📉 Drawdown Metrics: Historical drawdowns, peak-to-trough, recovery
• 💹 VAR Calculations: Value at Risk (95%, 99% confidence levels)
• 🎲 Scenario Testing: Stress tests against historical crises (2008, 2020)
• 🔗 Correlation Analysis: Diversification quality, correlation matrices
• 📈 Volatility Metrics: Portfolio vol, beta, Sharpe, Sortino ratios
• ⚠️ Limit Breach Detection: Position size, sector concentration thresholds
• 🛠️ Risk Mitigation: Hedging strategies, rebalancing recommendations

Example Output: Risk scorecard (1-10 scale), concentration analysis, VAR metrics, stress test results, and mitigation recommendations.

💰 Tax Scout - Tax Optimization Specialist

Tax-loss harvesting & wash-sale compliance

What Tax Scout Does:

• 💸 Tax-Loss Harvesting: Identify positions with unrealized losses
• ⏰ Wash-Sale Compliance: 30-day rule monitoring (IRS Section 1091)
• 🔄 Replacement Candidates: Find substantially different securities
• 📊 Capital Gains Analysis: Short-term vs long-term tracking
• 📅 Year-End Planning: Strategic positioning before Dec 31
• ⚖️ Tax-Efficient Rebalancing: Minimize gains during portfolio adjustments
• 📋 Lot-Level Analysis: FIFO, LIFO, specific lot identification

Example Output: TLH opportunities table with tax savings estimates, wash-sale violations, replacement candidates, and year-end action plan.

🎯 Hedge Smith - Options Strategist

Options strategies for portfolio protection & yield enhancement

What Hedge Smith Does:

• 🛡️ Protective Collars: Simultaneous put purchase + call sale for downside protection
• 💰 Covered Calls: Sell calls against holdings for premium income
• 📉 Protective Puts: Portfolio insurance with cost/benefit optimization
• 💵 Cash-Secured Puts: Generate income while waiting to acquire stock
• 🎯 Strike Selection: Optimal strike selection (5-10% OTM protection, 10-20% income)
• 📅 Expiration Optimization: 30-45 days for theta decay, 60-90 days for protection
• 📊 Options Greeks: Delta, gamma, theta, vega, IV percentile analysis
• ⚖️ Risk/Reward Profiling: Max profit, max loss, breakeven, probability estimates

Example Output: Complete strategy specification with specific strikes, premiums, Greeks, risk/reward analysis, and exit strategy.

---

🔀 Multi-Agent Workflows

Agents collaborate in sophisticated workflows for institutional-quality analysis:

/analyze - Comprehensive Investment Analysis (5 Agents)

/analyze MSFT

# 1. Quill performs bottom-up fundamental analysis
#    → Financial health, valuation, earnings trends
# 2. News Sentry checks for material events
#    → 8-K filings, insider trading, breaking news
# 3. Macro Lens validates with top-down regime analysis
#    → Economic cycles, sector positioning, yield curve
# 4. Risk Shield assesses portfolio fit
#    → Concentration risk, VAR, correlation analysis
# 5. Tax Scout evaluates tax implications
#    → Wash-sale checks, holding period optimization
# 6. Final synthesis combines all perspectives
#    → BUY/HOLD/SELL with confidence level and reasoning

/discover - Systematic Idea Generation (3 Agents)

/discover quality growth stocks with strong margins

# 1. Screen Forge identifies 10-15 candidates
#    → Factor-based screening, momentum analysis
# 2. Quill analyzes top 3-5 picks
#    → Deep fundamental analysis, valuation
# 3. Risk Shield assesses portfolio fit
#    → Position sizing, concentration analysis
# 4. Final synthesis ranks candidates
#    → Actionable recommendations with entry points

/optimize-tax - Tax-Loss Harvesting (2 Agents)

/optimize-tax I hold GOOGL at $150, now $120 and ETHUSD at $2500, now $1800

# 1. Tax Scout identifies tax-loss harvesting opportunities
#    → Unrealized losses >5%, wash-sale compliance, tax savings
# 2. Hedge Smith designs replacement strategies
#    → Sector ETF substitutes, synthetic long options
# 3. Final synthesis provides actionable tax plan
#    → Immediate actions, year-end optimization, compliance checklist

/protect - Portfolio Hedging (2 Agents)

/protect I hold 1000 NVDA shares at $120 average cost, currently $500

# 1. Risk Shield analyzes portfolio exposures
#    → Concentration risk, drawdown analysis, VAR, correlation
# 2. Hedge Smith designs protective strategies
#    → Protective puts, collars, index hedges, tail risk protection
# 3. Final synthesis provides hedging plan
#    → Strategy selection, cost-benefit analysis, implementation steps

---

💡 Example Workflows

📊 Comprehensive MSFT Analysis (click to expand)

You: Should I invest in Microsoft?

🔀 Router analyzing your query to select appropriate agent(s)...

Router (Analyzing Intent):
→ Detected investment decision query
→ Routing to Quill (fundamental analysis)
→ Routing to News Sentry (event monitoring)
→ Routing to Macro Lens (market timing validation)
→ Routing to Risk Shield (exposure assessment)
→ Routing to Tax Scout (tax implications)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
QUILL: FUNDAMENTAL ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quill (Equity Research):
  → Calling route_to_quill
     Quill analyzing: Should I invest in Microsoft...
     Running specialist tools (fundamental analysis, valuation, investment thesis)...
      → get_quote({'symbol': 'MSFT'})
      → get_earnings_history({'symbol': 'MSFT'})
      → get_analyst_recommendations({'symbol': 'MSFT'})
      → get_financials({'symbol': 'MSFT'})
  ✓ Quill (Fundamental Analysis) completed

**Fundamental Assessment**: STRONG
- Price: $420.45 (+0.8%), P/E 31x, Market Cap $3.1T
- 4 consecutive earnings beats, avg +4.2% surprise
- 89% buy ratings, mean target $475 (+13% upside)
- Revenue +15% YoY, 42% gross margin, $87B FCF
- Exceptional profitability (42% ROE)

[... similar sections for News Sentry, Macro Lens, Risk Shield, Tax Scout ...]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FINAL SYNTHESIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 RECOMMENDATION: BUY (Dollar-Cost Average)
📊 Confidence Level: MEDIUM

**Key Reasoning**:

Microsoft shows exceptional fundamental quality:
- 42% ROE, $87B annual FCF (best-in-class capital efficiency)
- Strong competitive moats (Azure cloud, enterprise software lock-in)
- Consistent earnings beats (+4.2% avg surprise, 4 quarters)
- 89% analyst buy ratings, $475 mean target (+13% upside)

However, macro timing suggests staged entry:
- Late expansion phase (GDP slowing from 2.8% to 2.4%)
- Inverted yield curve (-0.54%) signals 70% recession probability
- Tech sector vulnerable (Nasdaq -8% from highs)

**Suggested Action**:

Dollar-cost average over 3-6 months:
- Tranche 1: 40% now (defensive exposure to quality)
- Tranche 2: 30% if MSFT dips below $390 (-7% from current)
- Tranche 3: 30% if macro deteriorates (recession confirmed)

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

📄 Report saved to: reports/MSFT_analysis_20251012_143022.md

💰 Tax Optimization for GOOGL + ETHUSD (click to expand)

You: /optimize-tax I hold GOOGL at $150, now $120 and ETHUSD at $2500, now $1800

Tax Optimization Workflow: Starting tax-loss harvesting analysis...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TAX SCOUT: TAX-LOSS IDENTIFICATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Tax Scout (Tax Optimization):
  💰 Tax Scout identifying loss harvesting opportunities...
    → get_quote
    → check_wash_sale_window

**TAX-LOSS HARVESTING OPPORTUNITIES**:

1. GOOGL - Alphabet Inc.
   Current Price: $120.00 | Cost Basis: $150.00 | Unrealized Loss: -$30.00 (-20%)
   Holding Period: 180 days (Long-term capital loss)
   Wash-Sale Risk: None (no recent purchases)
   Tax Savings Estimate: $6,000 (assuming 20% LTCG bracket)
   Maintain Exposure? YES (core tech holding)

2. ETHUSD - Ethereum
   Current Price: $1,800 | Cost Basis: $2,500 | Unrealized Loss: -$700 (-28%)
   Holding Period: 45 days (Short-term capital loss)
   Wash-Sale Risk: None
   Tax Savings Estimate: $259 (assuming 37% ordinary income bracket)
   Maintain Exposure? YES (crypto allocation)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HEDGE SMITH: REPLACEMENT STRATEGIES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Hedge Smith (Options Strategist):
  🛡️ Hedge Smith designing replacement strategies...
    → get_options_chain
    → get_sector_etf_alternatives

**REPLACEMENT STRATEGY: GOOGL**

Option 1: Sector ETF Substitute (RECOMMENDED)
- Ticker: XLK - Technology Select Sector SPDR ETF
- Correlation: 0.75 (wash-sale compliant)
- Investment: $120 × shares (match original position size)
- Hold for: 31+ days, then repurchase GOOGL if desired

Option 2: Synthetic Long (Options)
- Buy 1 call @ $120 strike, 60-day expiration
- Sell 1 put @ $120 strike, 60-day expiration
- Net cost: ~$2.50 per share ($250 per contract)
- Delta: ~1.0 (matches stock exposure)

**REPLACEMENT STRATEGY: ETHUSD**

Option 1: Execute sell + immediate rebuy (RECOMMENDED)
- Crypto exempt from wash-sale rules (IRS Notice 2014-21)
- Harvest loss: -$700 tax deduction
- Rebuy immediately: Maintain same exposure with zero gap

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FINAL TAX OPTIMIZATION PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 **IMMEDIATE ACTIONS** (Execute today):

1. Sell GOOGL @ market
   → Replace with XLK (Tech ETF) for 31+ days
   → Tax savings: $6,000 | Hold ETF 31+ days

2. Sell ETHUSD @ market
   → Rebuy immediately (crypto exempt from wash-sale)
   → Tax savings: $259 | Maintain same exposure

**TOTAL TAX IMPACT**:
- Total harvestable losses: -$6,259
- Estimated tax savings: $6,259
- Net tax benefit: $6,259

**COMPLIANCE CHECKLIST**:
- [ ] Confirm no GOOGL purchases in last 30 days
- [ ] Select replacement security (XLK or 31-day cash hold)
- [ ] Document cost basis and trade dates for tax reporting
- [ ] Set 31-day calendar reminder

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

📄 Report saved to: reports/report_tax_optimization_20251014_123710.md

---

📊 Data Sources

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

Data Source	Coverage	Free Tier	Cost
Yahoo Finance 🆓	Real-time quotes, earnings, analyst ratings, ownership	Unlimited	FREE
SEC EDGAR 🆓	Corporate filings (10-K, 10-Q, 8-K), insider transactions	Unlimited	FREE
U.S. Treasury 🆓	Yield curves, treasury rates	Unlimited	FREE
Tiingo	5-year historical fundamentals	50 symbols/hr	Optional
Finnhub	News/social sentiment, insider trades	60 calls/min	Optional
Alpha Vantage	Stock prices, company overviews	25-500 calls/day	Optional
FRED	Economic indicators (GDP, CPI, unemployment)	Unlimited	Optional
NewsAPI.org	Market news, headlines	1,000 calls/day	Optional
Anthropic Claude	AI reasoning engine (Sonnet 4.5)	Pay-as-you-go	Required

💡 80% of functionality works with just Yahoo Finance + SEC EDGAR (no API keys needed!)

---

🗺️ Roadmap

Current Release: v0.1.42 (October 2025)

Latest in v0.1.41:

• ✅ API Caching Layer: DuckDB-based caching with 42 cached tools
• ✅ Cache Warming: /cache warm (23 common queries)
• ✅ Performance Boost: Up to 75% hit rates on repeated queries

v0.1.40:

• ✅ /protect Workflow: Portfolio hedging (Risk Shield + Hedge Smith)

v0.1.39:

• ✅ /optimize-tax Workflow: Tax-loss harvesting with replacement strategies

v0.1.38:

• ✅ ESC Cancellation: Cancel long operations anytime
• ✅ Non-blocking TUI: Scroll while agents work

v0.1.37:

• ✅ Extended /analyze: 5-agent comprehensive analysis
• ✅ /discover Workflow: Systematic idea generation

v0.1.36:

• ✅ Automatic Intent Routing: No more manual agent switching

Planned Features

v0.1.43+ (Q4 2025):

• Workflow Progress Visualization: Enhanced TUI with status indicators
• Async Tool Execution: Parallel tool calls for faster responses
• Cache Analytics: Hit rate optimization and size management

v0.2.0+ (Q1 2026):

• Backtesting Engine: Test strategies on historical data
• Web UI: Browser-based interface (in addition to TUI)
• State Persistence: PostgreSQL checkpointer for cross-session memory
• Cloud Deployment: LangGraph Cloud integration
• Custom Agents: User-defined agent templates
• Python SDK: Programmatic API for integrations

---

📚 Documentation

User Guides

• 🚀 Getting Started - Installation, setup, first queries
• ❓ FAQ - 100+ answered questions
• 🤖 Agents Guide - Complete agent reference
• 🔀 Multi-Agent Workflows - Collaboration patterns
• 🛠️ API Tools - Data sources and capabilities

Developer Resources

• 📦 PyPI Package - Releases and changelog
• 🔧 GitHub Repository - Source code, issues
• 🏗️ Architecture - System design overview
• 📖 LangGraph Guide - Multi-agent patterns

---

🤝 Contributing

We welcome contributions! Built by retail investors, for retail investors.

Ways to Contribute

• 🐛 Report Bugs
• 💡 Suggest Features
• 📝 Improve Docs
• 🔧 Submit PRs

Development Workflow

# Fork and clone
git clone https://github.com/your-username/navam-invest.git
cd navam-invest

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

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

# Make changes and run quality checks
black src/ tests/        # Format
ruff check src/ tests/   # Lint
mypy src/                # Type check
pytest                   # Test

# Commit and push
git checkout -b feature/amazing-feature
git commit -m "feat: Add amazing feature"
git push origin feature/amazing-feature

See CONTRIBUTING.md for detailed guidelines.

---

📄 License

MIT License - Free for personal and commercial use. See LICENSE for details.

---

🙏 Acknowledgments

Core Technologies

• Anthropic - Claude AI (Sonnet 4.5)
• LangChain - LangGraph agent framework
• Textual - Modern terminal UI

Data Providers

• Yahoo Finance - Real-time market data
• SEC EDGAR - Corporate filings
• U.S. Treasury - Yield curves, rates
• Alpha Vantage - Stock data
• Tiingo - Historical fundamentals
• Finnhub - Alternative data
• FRED - Economic indicators
• NewsAPI - Market news

---

Built with ❤️ for retail investors

⬆ Back to Top