navam-invest 0.1.31

AI agents and tools for the retail investor

🧠 Navam Invest

AI-Powered Investment Advisory for Retail Investors

Features • Quick Start • AI Agents • Examples • Documentation • Roadmap

---

📖 Overview

Navam Invest brings institutional-grade portfolio intelligence to individual retail investors managing $50K-$1M portfolios. Built on LangGraph and powered by Anthropic's Claude, it replaces traditional wealth management fees (1% AUM) with a team of specialized AI agents that collaborate through multi-agent workflows for equity research, systematic screening, macro analysis, earnings tracking, and portfolio management—all accessible through an interactive terminal interface.

Why Navam Invest?

🤖 Multi-Agent Intelligence 7 specialized AI agents orchestrated by LangGraph for coordinated analysis	📊 Institutional Data Yahoo Finance + SEC EDGAR + 7 premium APIs (all free tiers)	🔒 Privacy-First Runs locally with your API keys—your data stays yours
💡 Explainable AI Full audit trails and transparent reasoning with real-time streaming	🆓 Zero Lock-In Yahoo Finance + EDGAR require no API keys, core tools always free	🔧 Extensible Modular architecture for custom agents and workflows

Architecture at a Glance

graph LR
    A[You] -->|Natural Language| B[Textual TUI]
    B --> C{LangGraph Orchestrator}
    C --> D[Quill<br/>Equity Research]
    C --> E[Earnings Whisperer<br/>Earnings Analysis]
    C --> F[Screen Forge<br/>Stock Screening]
    C --> G[Macro Lens<br/>Market Strategist]
    C --> H[Atlas<br/>Asset Allocation]
    D --> I[Yahoo Finance]
    D --> J[SEC EDGAR]
    D --> K[Tiingo]
    E --> I
    F --> I
    F --> L[Finnhub]
    G --> M[FRED]
    G --> N[U.S. Treasury]
    style C fill:#f9f,stroke:#333,stroke-width:4px
    style I fill:#9f9,stroke:#333,stroke-width:2px
    style J fill:#9f9,stroke:#333,stroke-width:2px

Stack: LangGraph (orchestration) → LangChain (tools) → Claude (reasoning) → Textual (TUI) → yfinance/httpx (data)

---

✨ Features

🤖 Specialized AI Agents

Each agent is purpose-built with 10-36 specialized tools and expert system prompts

⭐ Quill - Equity Research Analyst

Deep fundamental analysis & investment thesis building

Core Capabilities:

• 📊 Valuation Models: DCF, comparable company analysis, P/E/P/B/P/S ratios
• 📈 Financial Analysis: 5-year trends (revenue, margins, ROIC, FCF, debt ratios)
• 💰 Earnings Tracking: Historical earnings, analyst estimates, surprise analysis
• 🎯 Analyst Coverage: Consensus ratings, price targets, upgrades/downgrades
• 🏢 Ownership Tracking: Institutional holders, insider transactions (Form 4)
• 📋 SEC Filings: 10-K, 10-Q, 8-K material events, XBRL structured data
• 💵 Dividends: Yield, payout ratios, dividend history, sustainability
• 📰 News Validation: Company-specific news with sentiment analysis

Tools: 36 specialized tools across Yahoo Finance, SEC EDGAR, Tiingo, Finnhub, NewsAPI

Command: /quill

Example Query:

"Analyze AAPL with focus on recent earnings trends, institutional ownership, and material events from 8-K filings"

📊 Earnings Whisperer - Earnings Specialist

Earnings surprise analysis & post-earnings drift detection

Core Capabilities:

• 🎯 Historical Analysis: 4-8 quarter earnings surprise tracking
• 📈 Drift Detection: 1-3 day post-earnings momentum patterns
• 🔄 Analyst Revisions: Estimate changes and rating updates post-earnings
• ✅ Quality Assessment: Revenue vs. EPS beats, non-recurring items
• 📅 Calendar Monitoring: Upcoming earnings with probability scoring
• 🏆 Pattern Recognition: Consistent beaters, accelerating beats, quality issues
• 💹 Trading Signals: BUY (drift play), HOLD (wait), SELL (negative momentum)

Tools: 14 specialized tools across Yahoo Finance, SEC, Finnhub

Command: /earnings

Example Query:

"Analyze NVDA earnings history - is there a post-earnings drift opportunity?"

🔍 Screen Forge - Equity Screener

Systematic stock discovery & idea generation

Core Capabilities:

• 📐 Multi-Factor Screening: Value, growth, quality, momentum factors
• 🎯 Systematic Discovery: Weekly watchlist generation with factor-based ranking
• 📈 Earnings Momentum: Consistent earnings beat screening
• ⬆️ Analyst Activity: Upgrade/downgrade filtering
• 💬 Sentiment Validation: News and social sentiment checks
• 🔗 Integration: Seamless handoff to Quill for deep-dive analysis

Tools: 15 specialized tools across Yahoo Finance, Finnhub, Alpha Vantage

Command: /screen

Example Query:

"Screen for stocks with consistent earnings beats over last 3 quarters and analyst upgrades"

🌍 Macro Lens - Market Strategist

Top-down macro analysis & regime identification

Core Capabilities:

• 🔄 Economic Cycles: 4-phase regime analysis (early/mid/late expansion, recession)
• 📈 Yield Curve: Interpretation and recession signal detection (inversions)
• 🏭 Sector Allocation: Macro-driven sector positioning guidance
• 📊 Factor Recommendations: Value vs. growth, size, low-volatility tilts
• 📉 Macro Tracking: Inflation, GDP growth, employment, Fed policy
• 📊 Market Indices: S&P 500, Nasdaq, VIX for regime correlation
• 💹 Interest Rates: Fed funds, treasury rates, spreads

Tools: 13 specialized tools across FRED, U.S. Treasury, Yahoo Finance, NewsAPI

Command: /macro

Example Query:

"What's the current macro regime and which sectors should I overweight?"

🗺️ Atlas - Investment Strategist

Strategic asset allocation & portfolio construction

Core Capabilities:

• 📋 IPS Development: Investment Policy Statement creation
• 🎯 Asset Allocation: Strategic allocation frameworks (stocks/bonds/alternatives)
• 📊 Risk Profiling: Conservative/Moderate/Aggressive tolerance assessment
• 🔄 Tactical Tilts: Macro-driven portfolio adjustments
• ⚖️ Rebalancing: Threshold-based, calendar-based, tax-aware strategies
• 🏗️ Construction: Portfolio building with constraint optimization

Tools: 12 specialized tools across all data sources

Command: /atlas

Example Query:

"Create an IPS for moderate risk tolerance with $100k portfolio"

📁 Portfolio & Research (Legacy)

Backward-compatible general-purpose agents

• Portfolio (/portfolio): 24 tools for quotes, fundamentals, news, SEC filings
• Research (/research): 10 tools for macro indicators, yield curves, FRED data

Note: Will be phased out in v0.2.0 in favor of specialized agents

🔀 Multi-Agent Workflows

Coordinated agent collaboration combining specialized expertise

Investment Analysis Workflow

Command: /analyze <SYMBOL>

Sequential Orchestration: Quill (bottom-up) → Macro Lens (top-down) → Synthesis

Step 1: Fundamental Analysis Quill performs bottom-up analysis: Business overview Financial health (5-year trends) Valuation (P/E, DCF) Earnings trends Analyst sentiment Investment thesis

Step 2: Macro Validation Macro Lens validates timing: Receives Quill's thesis Assesses macro regime Evaluates sector positioning Validates entry point Market indices correlation

Step 3: Synthesis Combined recommendation: Overall rating (BUY/HOLD/SELL) Confidence level Key reasoning from both agents Risk warnings Suggested action

Example Output:

/analyze AAPL

📊 Quill analyzing fundamentals...
  ✓ Strong earnings momentum (+3% avg beat, 4 qtrs)
  ✓ 81% analyst buy ratings, $248 mean target (+9% upside)

🌍 Macro Lens validating timing...
  ✓ Late expansion phase, inverted yield curve (-0.54%)
  ⚠️ Tech sector vulnerability (Nasdaq -8% from highs)

🎯 Final Recommendation: HOLD - Medium Confidence
Apple shows strong fundamentals but late-cycle macro timing
suggests cautious positioning. Dollar-cost average on dips below $210.

📊 Data Sources

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

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

💡 Total Free Data: 3 out of 9 sources require no API key! (Yahoo Finance, SEC, Treasury)

💬 Interactive Terminal UI

Built with Textual - Modern Python TUI Framework

Real-Time Processing Indicators 🆕:

• ✅ Smart Input Disabling: Input grayed out during agent processing
• ✅ Live Status Updates: "⏳ Processing your request..." placeholder
• ✅ Footer Progress: Current agent + processing state in footer bar
• ✅ Error Recovery: Auto-enables input even on errors
• ✅ Auto-Focus: Returns cursor to input when ready

Core Features:

• ✅ Chat Interface: Natural language interaction with specialized agents
• ✅ Real-time Streaming: Watch agents think and reason live
• ✅ Multi-Agent Progress: See workflow transitions and agent collaboration
• ✅ Tool Tracking: Granular visibility into which tools are called with what arguments
• ✅ Markdown Rendering: Beautiful formatted output with tables, code blocks, lists
• ✅ Agent Switching: Quick commands to switch between agents
• ✅ Workflow Commands: Multi-agent orchestration with single commands
• ✅ Auto-Save Reports: All agent responses saved to reports/ directory with timestamps

Keyboard Shortcuts:

• Ctrl+C: Clear chat history
• Ctrl+Q: Quit application
• Mouse scroll for history navigation

📄 Automatic Report Saving

All agent-generated reports are automatically saved to the reports/ directory:

• Investment Analysis (/analyze): Complete multi-section reports with fundamentals, macro validation, and final recommendation
• Agent Responses: All substantial responses (>200 chars) automatically saved as markdown files
• Organized Naming: {symbol}_{report_type}_{timestamp}.md
• Full Context: Metadata (date, symbol, query) and formatted markdown content

Supported Report Types:

• analysis - Multi-agent investment analysis workflow
• equity_research - Quill equity research reports
• earnings - Earnings surprise analysis
• screening - Stock screening results
• macro_analysis - Macro regime analysis
• portfolio - Portfolio analysis reports

---

🚀 Quick Start

Prerequisites

• Python 3.9+ (3.13 recommended)
• pip package manager
• Anthropic API key (required) - Get it at console.anthropic.com

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  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Configuration

1. Create Environment File

cp .env.example .env

2. Add Your API Keys

Edit .env with your API keys:

# Required - AI reasoning engine
ANTHROPIC_API_KEY=sk-ant-...

# Optional - Enhanced data coverage (all have free tiers)
ALPHA_VANTAGE_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

# No keys needed for Yahoo Finance, SEC EDGAR, U.S. Treasury!

3. Get Free API Keys

Service	Link	Free Tier	Required?
Anthropic ⭐	console.anthropic.com	Pay-as-you-go ($3-15/M tokens)	✅ Required
Yahoo Finance 🆓	-	Unlimited, no key needed	✅ Built-in
SEC EDGAR 🆓	-	Unlimited, no key needed	✅ Built-in
U.S. Treasury 🆓	-	Unlimited, no key needed	✅ Built-in
Alpha Vantage	alphavantage.co/support/#api-key	25 calls/day	Optional
Tiingo	tiingo.com	50 symbols/hr, 5yr history	Optional
Finnhub	finnhub.io/register	60 calls/min	Optional
FRED	fredaccount.stlouisfed.org/apikeys	Unlimited	Optional
NewsAPI.org	newsapi.org/register	1,000 calls/day	Optional

4. Verify Setup

navam invest
> /api
# Shows status table with ✅ working / ❌ failed / ⚪ not configured

Usage

Launch the Interactive Interface

navam invest

This opens an interactive chat interface with 7 specialized AI agents and multi-agent workflows.

Available Commands

System Commands:

• /api - Check API connectivity and status of all data providers
• /help - Show all available commands
• /examples - Show example prompts for current agent
• /clear - Clear chat history
• /quit - Exit the application

Agent Selection:

• /analyze <SYMBOL> - Multi-agent investment analysis workflow (Quill + Macro Lens)
• /quill - Switch to Quill (Equity Research) agent
• /earnings - Switch to Earnings Whisperer agent
• /screen - Switch to Screen Forge agent
• /macro - Switch to Macro Lens agent
• /atlas - Switch to Atlas (Investment Strategist) agent
• /portfolio - Switch to Portfolio (legacy) agent
• /research - Switch to Research (legacy) agent

---

💡 Example Workflows

1. Multi-Agent Investment Analysis

Complete fundamental + macro analysis for MSFT

You: /analyze MSFT

Investment Analysis Workflow: Starting multi-agent analysis...

📊 Quill analyzing fundamentals...
  → get_quote(symbol=MSFT)
  ✓ MSFT: $420.45, +0.8%, P/E 31x, Market Cap $3.1T

  → get_earnings_history(symbol=MSFT)
  ✓ 4 consecutive earnings beats, avg +4.2% surprise

  → get_analyst_recommendations(symbol=MSFT)
  ✓ 89% buy ratings, mean target $475 (+13% upside)

  → get_financials(symbol=MSFT)
  ✓ Revenue +15% YoY, 42% gross margin, $87B FCF

  ✓ Fundamental analysis complete

🌍 Macro Lens validating timing...
  → get_key_macro_indicators()
  ✓ GDP +2.4%, CPI +3.1%, Unemployment 3.7%

  → get_treasury_yield_curve()
  ✓ 10Y-2Y inverted -0.54% (recession warning)

  → get_market_indices()
  ✓ S&P 500 +12% YTD, Nasdaq -8% from highs, VIX 14.2

  ✓ Macro validation complete

🎯 Synthesizing recommendation...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final Recommendation: BUY - Medium Confidence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Key Reasoning**:

Microsoft demonstrates exceptional fundamental quality:
- 42% ROE, $87B annual free cash flow
- Strong competitive moats (Azure cloud, enterprise software)
- Consistent earnings beats (+4.2% avg surprise, 4 quarters)
- 89% analyst buy ratings, $475 mean target (+13% upside)
- Current valuation 31x P/E reasonable given 15% revenue growth

However, macro timing presents headwinds:
- Late expansion phase (GDP +2.4%, but slowing)
- Inverted yield curve (-0.54%) signals recession risk within 12 months
- Tech sector vulnerability (Nasdaq -8% from highs)

**Suggested Action**:

Consider accumulating MSFT on dips rather than full position immediately.
Dollar-cost average over 3-6 months to capture potential volatility from
macro headwinds. Microsoft's defensive characteristics (enterprise
subscriptions, cloud infrastructure) should outperform cyclical tech
peers in downturn.

**Risk Warning**:

Monitor enterprise cloud spending trends and Azure growth rates. If Azure
growth decelerates below 25% YoY, fundamental thesis weakens. Macro risk:
Recession could compress P/E multiple to 24-26x (historical trough),
implying 15-20% downside risk from current levels.

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

📄 Report saved to: reports/MSFT_analysis_20251008_143022.md

2. Earnings Momentum Screening

Screen for stocks with consistent earnings beats

You: /screen
You: Screen for stocks with consistent earnings beats over last 3 quarters

Screen Forge (Equity Screening):
  → screen_stocks(market_cap_min=1000000000)
  ✓ 347 stocks retrieved

  → get_earnings_history (batch for 347 stocks)
  ✓ Earnings data retrieved for 298 stocks

  → Filtering for 3+ consecutive beats
  ✓ 42 stocks match criteria

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Earnings Beat Momentum Screen Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Criteria**:
- Market Cap: > $1B
- Earnings Beats: 3+ consecutive quarters
- Average Surprise: > 2%

**Top 10 Candidates** (Ranked by avg surprise %):

┏━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Rank┃ Ticker ┃ Company        ┃ Mkt Cap┃ Avg Surprise ┃ Streak ┃ Latest Beat ┃
┡━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━┩
│  1  │ NVDA   │ NVIDIA         │ $3.2T  │ +18.4%       │ 8 qtrs │ +21.2%      │
│  2  │ META   │ Meta Platforms │ $1.4T  │ +12.6%       │ 5 qtrs │ +15.8%      │
│  3  │ GOOGL  │ Alphabet       │ $2.1T  │ +8.9%        │ 6 qtrs │ +9.4%       │
│  4  │ MSFT   │ Microsoft      │ $3.1T  │ +4.2%        │ 4 qtrs │ +3.8%       │
│  5  │ AAPL   │ Apple          │ $3.5T  │ +3.0%        │ 4 qtrs │ +2.5%       │
│  6  │ AMZN   │ Amazon         │ $1.9T  │ +7.5%        │ 5 qtrs │ +8.2%       │
│  7  │ V      │ Visa           │ $592B  │ +5.1%        │ 7 qtrs │ +4.8%       │
│  8  │ MA     │ Mastercard     │ $453B  │ +4.9%        │ 6 qtrs │ +5.2%       │
│  9  │ HD     │ Home Depot     │ $381B  │ +3.8%        │ 4 qtrs │ +4.1%       │
│ 10  │ CRM    │ Salesforce     │ $308B  │ +6.2%        │ 5 qtrs │ +7.8%       │
└─────┴────────┴────────────────┴────────┴──────────────┴────────┴─────────────┘

**Recommended Next Steps**:
Type `/quill` then "Analyze GOOGL with earnings momentum focus"

📄 Report saved to: reports/SCREENER_earnings_beats_20251008_144530.md

3. Real-Time Processing Feedback

Watch the improved UX during agent processing

Before Query:

Footer: Agent: Quill | Ready
Input: [Ask about stocks or economic indicators...]

During Processing (input automatically disabled):

Footer: Processing...
Input: [⏳ Processing your request...] (grayed out, uneditable)

During Long Operations (no more confusion!):

Quill (Equity Research):
  → Calling get_financials(symbol=AAPL)
  ✓ get_financials completed
  → Calling get_earnings_history(symbol=AAPL)
  ✓ get_earnings_history completed

Footer: Processing...
Input: [⏳ Processing your request...] (still disabled)

[Even during pauses, you know the system is working!]

After Completion (input automatically re-enabled):

Footer: Agent: Quill | Ready
Input: [Ask about stocks or economic indicators...] (cursor auto-focused)

Benefits:

• ✅ No confusion about whether system is frozen or working
• ✅ Can't accidentally submit duplicate requests
• ✅ Clear visual feedback at multiple levels
• ✅ Auto-recovers even on errors

---

📚 Documentation

Official Resources

• GitHub Repository - Source code, issues, PRs
• PyPI Package - Latest releases
• Release Notes - Detailed changelog for each version
• Integration Guide - Yahoo Finance + EDGAR integration
• Architecture Specs - Technical design documents
• LangGraph Guide - Multi-agent patterns & best practices

API Documentation

• Anthropic Claude - AI reasoning engine
• LangGraph - Agent orchestration framework
• Yahoo Finance (yfinance) - Free market data library
• SEC EDGAR - Corporate filings
• Alpha Vantage - Stock market data
• Tiingo - Historical fundamentals
• Finnhub - Alternative data & sentiment
• FRED - Economic indicators

Development

Running Tests

pytest                    # Run all tests
pytest -v                # Verbose output
pytest tests/test_*.py   # Specific test file
pytest --cov             # With coverage report

Code Quality

black src/ tests/        # Format code (88 char line length)
ruff check src/ tests/   # Lint code
mypy src/                # Type check (strict mode)

Building from Source

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

# Build distribution
python -m build

# Check package before upload
twine check dist/*

# Upload to PyPI (maintainers only)
twine upload dist/*

---

🗺️ Roadmap

Current Release: v0.1.31 (In Development)

Status: Active development

Latest Updates:

• ✅ Enhanced UX: Smart input disabling during processing
• ✅ Live Status: Real-time footer updates ("Processing..." → "Ready")
• ✅ Full Responses: Increased max_tokens to 8192 (no more truncation)
• ✅ Error Recovery: Input always re-enables, even on errors

Planned Features:

• News Sentry agent (real-time event detection, 8-K material event monitoring)
• Enhanced multi-agent workflows (extend /analyze with additional agents)
• API caching layer (DuckDB-based caching to reduce API calls)
• Options analysis tools (Yahoo Finance options chain integration)
• Risk management enhancements (drawdown analysis, VAR calculations)

Recent Releases

v0.1.30 (Jan 8, 2025) - API Reliability Improvements

Removed: Financial Modeling Prep (FMP) API due to free tier access errors

Benefits:

• ✅ 100% reliable APIs (Yahoo + SEC have no rate limits)
• ✅ Better data quality (Yahoo has real-time data)
• ✅ Simpler setup (one less API key required)
• ✅ No more "Access denied" errors

Updates: 32 tools across 9 APIs (down from 36 tools, 10 APIs)

Full Release Notes

v0.1.28 (Jan 5, 2025) - Self-Service API Status

New: /api command for interactive API connectivity testing

Features:

• ✅ Real-time validation of all 9 data providers
• ✅ Rich table formatting with color-coded status (✅/❌/⚪)
• ✅ Troubleshooting tips and error diagnosis
• ✅ Documentation clarifying NewsAPI.org vs NewsAPI.ai

Full Release Notes

v0.1.27 (Dec 29, 2024) - Earnings Whisperer Agent

New Agent: Earnings Whisperer for earnings surprise analysis and post-earnings drift detection

Features:

• ✅ 14 specialized tools (Yahoo Finance + SEC + Finnhub)
• ✅ 5-step earnings analysis framework
• ✅ Pattern recognition (consistent beaters, accelerating beats, drift opportunities)
• ✅ Trading signals (BUY/HOLD/SELL on earnings)
• ✅ TUI command: /earnings

Full Release Notes

v0.1.26 (Dec 22, 2024) - Yahoo Finance + Enhanced EDGAR

Major Update: Yahoo Finance integration (11 FREE tools) + Enhanced SEC EDGAR (4 new tools)

Features:

• ✅ Real-time earnings trends & surprises (Yahoo Finance)
• ✅ Analyst consensus & price targets (Yahoo Finance)
• ✅ Institutional ownership tracking (Yahoo Finance)
• ✅ Material event detection (8-K filings)
• ✅ XBRL structured data extraction
• ✅ Insider transaction patterns (Form 4)
• ✅ Zero cost expansion ($2.4K-$10.8K/year savings)

Agent Enhancements: Quill (36 tools, up from 22), Screen Forge (15 tools), Macro Lens (13 tools)

Full Release Notes

Future Releases

v0.1.32-0.1.35 (Q1 2025):

• Additional specialized agents (Risk Shield, Tax Scout, Hedge Smith)
• Enhanced multi-agent workflows (parallel execution, conditional branching)
• Portfolio tracking & performance attribution
• State persistence (PostgreSQL checkpointer for LangGraph)

v0.2.0+ (Q2 2025):

• Backtesting engine for investment strategies
• Risk management workflows (VaR, stress testing)
• Web UI (in addition to TUI)
• Cloud deployment options (LangGraph Cloud)
• API for third-party integrations

---

🤝 Contributing

Contributions are welcome! We're building the future of retail investment intelligence together.

Ways to Contribute

• 🐛 Report Bugs - Submit detailed bug reports via GitHub Issues
• 💡 Suggest Features - Share ideas for new agents, workflows, or data sources
• 📝 Improve Documentation - Help make docs clearer and more comprehensive
• 🔧 Submit PRs - Code contributions for bug fixes, features, or tests

Development Workflow

1. Fork the repository and clone locally
2. Create a feature branch: git checkout -b feature/amazing-agent
3. Make your changes with tests and documentation
4. Run quality checks: black src/ tests/, ruff check, mypy src/, pytest
5. Commit with semantic messages: feat: Add News Sentry agent
6. Push and create a PR with detailed description

See CONTRIBUTING.md for detailed guidelines.

---

📄 License

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

Key Points:

• ✅ Free for personal and commercial use
• ✅ Modify and distribute as you wish
• ✅ No warranty provided

---

🙏 Acknowledgments

Core Technologies

• Anthropic - Claude AI reasoning engine (Sonnet 4.5)
• LangChain - Agent framework ecosystem (LangGraph orchestration)
• Textual - Modern terminal UI framework

Data Providers

• Yahoo Finance - Free real-time quotes, earnings, analyst ratings (via yfinance)
• SEC EDGAR - Corporate filings (10-K, 10-Q, 8-K, Form 4)
• U.S. Treasury - Yield curves, treasury rates
• Alpha Vantage - Stock market data
• Tiingo - Historical fundamentals
• Finnhub - Alternative data & sentiment
• FRED - Federal Reserve economic data
• NewsAPI.org - Market news & headlines

Community

Special thanks to all contributors, users, and the open-source community for making this project possible.

---

Built with ❤️ for retail investors

⬆ Back to Top