🤖 Navam - Standalone AI Investment Assistant

🎯 What is Navam?

Navam is a standalone AI investment assistant that combines Claude's intelligence with real-time market data. No Claude Desktop required - just install and start researching stocks.

Key Features

• 🚀 Standalone Package - Works immediately after pip install navam
• 🤖 18 Specialized AI Agents - Expert analysis for every investment scenario
• ⚡ Smart Caching - 70% reduction in API calls for faster, cheaper queries
• 📊 3 High-Performance MCP Servers - Real-time stock, company, and news data
• 🎯 8 Investment Workflows - Pre-built slash commands for common tasks
• 💬 Interactive Chat - Natural language investment research

What's New in v1.7.2

• 🎯 Fixed Agent Selection - All 7 investment commands now use specialized agents correctly
• ⚡ 5x Faster Streaming Reports - Progressive display of agent results as they complete
• 💰 75% Cost Reduction - Workflows now $0.30-0.40 (was $1.50-1.80)
• 🚀 2-3 Minute Execution - Down from 10-13 minutes for complex workflows
• ✅ Domain Expertise Applied - Each agent brings specialized knowledge to analysis

✨ Features

💬 Interactive Chat

• Natural Language Financial Analysis - Ask questions, get intelligent insights
• Real-time Progress Indicators - See thinking tokens, tool execution, and agent activity
• Multi-Agent Coordination - Multiple AI agents working in parallel with progress tracking
• Smart Caching System - 70% reduction in API calls, 70% cost savings
• Performance Monitoring - /perf command shows cache hits, cost tracking, parallel execution
• Persistent Chat History - Context-aware conversations with turn tracking
• Custom Slash Commands - Pre-built investment workflows
• Built-in Commands - /agents, /api, /tools, /help, /perf, /cache and more

📊 Financial Intelligence

• Live Market Data - Real-time quotes, volume, price movements
• Technical Analysis - RSI, MACD, moving averages, trend indicators
• Company Research - Fundamentals, SEC filings, analyst ratings
• News & Sentiment - Multi-source aggregation with AI sentiment analysis
• Portfolio Management - Value tracking, allocation analysis, performance metrics

🤖 AI Agents

• 18 Specialized Financial Agents - Expert AI for every investment scenario
• Strategy & Planning - Atlas (investment strategy), Compass (goal planning), Macro Lens (market analysis)
• Research & Analysis - Quill (equity research), Earnings Whisperer, News Sentry, Screen Forge
• Portfolio Management - Ledger (performance), Quant Optimizer, Risk Shield, Rebalance Bot
• Trading & Execution - Trader Jane, Compliance Sentinel
• Tax & Treasury - Tax Scout, Cash Treasury Steward
• Advanced Strategies - Hedge Smith (options), Factor Scout
• Knowledge Management - Notionist Librarian

Use /agents command in chat to see all agents with detailed descriptions!

🔧 Integration Ready

• Claude Desktop Compatible - Works seamlessly with Claude Desktop
• MCP Protocol - Industry-standard Model Context Protocol
• API-First Design - Easy integration with other tools
• Standalone or Integrated - Use independently or with Claude Desktop

🚀 Quick Start

Installation

# Install from PyPI
pip install navam

# Verify installation
navam --version

Setup

# Required: Set your Anthropic API key
export ANTHROPIC_API_KEY="your_anthropic_api_key"

# Optional: Add API keys for enhanced data (see Configuration section)
export ALPHA_VANTAGE_KEY="your_alpha_vantage_key"

Start Chatting

# Launch interactive AI chat
navam chat

# Once in chat, try these commands:
/agents      # See all 18 specialized AI agents
/api         # Check which APIs are active
/help        # Get complete command reference

# Or use direct CLI commands
navam analyze AAPL
navam compare AAPL MSFT GOOGL
navam news "Federal Reserve"

First time using Navam? Start with navam chat and type /help to see all features!

💡 Usage Examples

Interactive Chat Commands

# Launch interactive chat
navam chat

# Built-in commands (use within chat):
/agents      # List all 18 specialized AI agents
/api         # Show API status and configuration
/perf        # Performance metrics: cache hits, costs, parallel execution
/cache       # Cache statistics and savings
/help        # Show all available commands
/tools       # List available MCP tools
/commands    # List all slash commands

# Investment workflow commands (NEW in v1.7.2 - now with specialized agents!):
/invest:research-stock NVDA          # 3 specialized agents analyze fundamentals, news, and risks
/invest:review-portfolio              # 6 specialized agents provide comprehensive portfolio analysis
/invest:screen-opportunities          # 4 specialized agents screen and analyze top candidates
/invest:plan-goals                    # 3 specialized agents map goals and create investment strategy
/invest:optimize-taxes                # 6 specialized agents optimize tax efficiency
/invest:monitor-holdings              # 6 specialized agents provide continuous monitoring
/invest:execute-rebalance             # 6 specialized agents handle systematic rebalancing

CLI Commands

# Stock analysis
navam analyze AAPL

# Multi-stock comparison
navam compare AAPL MSFT GOOGL

# Market screening
navam screen --sector technology --min-price 100

# News analysis
navam news "Tesla earnings"

# Check API status
navam chat
# Then use: /api

Python API

from navam import StockAnalyzer, CompanyResearch

# Analyze stocks programmatically
stock = StockAnalyzer()
analysis = await stock.analyze_stock("AAPL")
print(f"Price: ${analysis.price}")

# Research companies
company = CompanyResearch()
profile = await company.get_company_profile("AAPL")
print(f"Sector: {profile.sector}")

⚙️ Configuration

API Key Setup

Navam uses a tiered API approach - basic functionality works with free APIs, premium features unlock with paid keys:

Required

export ANTHROPIC_API_KEY="your_anthropic_key"  # For AI chat functionality

Optional (Enhanced Features)

# Financial data enhancement
export ALPHA_VANTAGE_KEY="your_key"     # Company data, technical indicators
export POLYGON_API_KEY="your_key"       # Professional market data
export MARKETAUX_API_KEY="your_key"     # Financial news aggregation
export NEWSAPI_KEY="your_key"           # Global news coverage
export FINNHUB_API_KEY="your_key"       # Real-time financial news

Configuration Methods

Method 1: Environment Variables (Production)

echo 'export ANTHROPIC_API_KEY="your_key"' >> ~/.bashrc
source ~/.bashrc

Method 2: .env File (Development)

# Create .env file in project directory
echo "ANTHROPIC_API_KEY=your_key" > .env
echo "ALPHA_VANTAGE_KEY=your_key" >> .env

Method 3: Session Variables (Temporary)

export ANTHROPIC_API_KEY="your_key"
navam chat

Check Configuration Status

navam chat

# Inside chat, use these commands:
/api         # Shows detailed API status - which are active, which need keys
/agents      # List all 18 specialized AI agents available
/tools       # Show all available MCP tools
/help        # Complete command reference

🔌 Integrations

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "navam-stock": {
      "command": "python",
      "args": ["-m", "stock_mcp.server", "stdio"],
      "env": {
        "ALPHA_VANTAGE_KEY": "your_key"
      }
    },
    "navam-company": {
      "command": "python",
      "args": ["-m", "company_mcp.server", "stdio"]
    },
    "navam-news": {
      "command": "python",
      "args": ["-m", "news_mcp.server", "stdio"]
    }
  }
}

Standalone MCP Servers

# Run individual MCP servers
python -m stock_mcp.server stdio
python -m company_mcp.server streamable-http --port 8080
python -m news_mcp.server stdio

🏗️ Architecture

Component Overview

📦 Navam Platform
├── 💬 Interactive Chat (navam chat)
│   ├── Real-time thinking token display
│   ├── Live tool execution tracking
│   ├── Multi-agent parallel execution monitoring
│   └── Built-in commands (/agents, /api, /tools, /help)
├── 📊 Stock Analysis MCP Server (Grade A- 90%)
├── 🏢 Company Research MCP Server (Grade C+ 75%)
├── 📰 News Analysis MCP Server (Grade B 80%)
├── 🤖 18 Specialized AI Agents
│   ├── Strategy & Planning (3 agents)
│   ├── Research & Analysis (4 agents)
│   ├── Portfolio Management (4 agents)
│   ├── Trading & Execution (2 agents)
│   ├── Tax & Treasury (2 agents)
│   ├── Advanced Strategies (2 agents)
│   └── Knowledge Management (1 agent)
├── ⚡ Custom Investment Commands
└── 🔧 Claude Desktop Integration

Data Sources

📊 Performance

Performance Metrics (v1.7.2):

• 70% Cache Hit Rate - Eliminates duplicate API calls
• 75% Cost Reduction - $1.77 → $0.30-0.40 per workflow
• 70% Faster Execution - 13 min → 2-3 min for complex workflows
• Parallel Execution - Multiple specialized agents working simultaneously
• Streaming Reports - 5x faster perceived speed with progressive results

Architecture:

• Async/Await - Concurrent operations
• Hook-Based Caching - Intelligent API call interception
• Graceful Degradation - Works with or without premium APIs
• Rate Limiting - Respects API quotas

🧪 Development

Local Development

# Clone repository
git clone https://github.com/navam-ai/navam.git
cd navam

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Code formatting
black .
ruff check .
mypy .

Testing MCP Servers

# Test with MCP inspector
mcp dev stock_mcp/server.py
mcp dev company_mcp/server.py
mcp dev news_mcp/server.py

# Test individual servers
echo '{"symbol": "AAPL"}' | python -m stock_mcp.server stdio

💡 Chat Command Reference

When you run navam chat, you have access to powerful built-in commands:

Investment Workflow Commands:

• /invest:research-stock [SYMBOL] - Deep dive stock research (3 specialized agents)
• /invest:review-portfolio - Portfolio analysis and recommendations (6 specialized agents)
• /invest:screen-opportunities - Find investment opportunities (4 specialized agents)
• /invest:plan-goals - Financial goal planning (3 specialized agents)
• /invest:optimize-taxes - Tax optimization strategies (6 specialized agents)
• /invest:monitor-holdings - Continuous portfolio monitoring (6 specialized agents)
• /invest:execute-rebalance - Systematic portfolio rebalancing (6 specialized agents)

🔒 Security & Compliance

• ✅ Read-Only Operations - No trading or account modifications
• ✅ API Key Security - Environment variable storage
• ✅ Rate Limiting - Respectful API usage
• ✅ No Data Storage - No personal financial data stored
• ✅ Open Source - Full transparency

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Contribution Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/navam.git
cd navam

# Development setup
pip install -e .[dev]
pre-commit install

# Make changes, test, and submit PR
pytest
black .
git commit -m "feat: your contribution"

Ways to Contribute

• 🐛 Bug Reports - GitHub Issues
• ✨ Feature Requests - GitHub Discussions
• 📖 Documentation - Improve guides and examples
• 🔧 Code - New features, bug fixes, optimizations
• 🧪 Testing - Add test coverage, performance testing

📈 What's New

Version 1.7.2 (Latest) - October 2025

🎯 Critical Fix: Agent Selection & Streaming Reports

• 🎯 Fixed Agent Selection Bug - Specialized agents now work correctly

  • All 7 investment commands updated with explicit Task tool syntax
  • Previously: All workflows used generic "general-purpose" agent
  • Now: Each workflow invokes correct specialized agents by name
  • Format: Task(subagent_type="agent-name", description="...", prompt="...")

• ⚡ Streaming Reports Operational - 5x faster perceived speed

  • Progressive display of agent results as they complete
  • Real-time feedback during long-running workflows
  • Shows agent name, duration, and result preview (first 1000 chars)
  • Rich formatted cyan panels for streaming sections

• 💰 Massive Performance Improvements - Production-validated metrics

  • 75% Cost Reduction: $1.77 → $0.30-0.40 per workflow
  • 70% Faster Execution: 13 min → 2-3 min for complex workflows
  • Domain Expertise Applied: Each agent brings specialized knowledge
  • Parallel Execution: Multiple specialized agents working simultaneously

• 🔧 Commands Fixed (7 total)

  • ✅ /invest:research-stock - 3 specialized agents
  • ✅ /invest:plan-goals - 3 specialized agents
  • ✅ /invest:optimize-taxes - 6 specialized agents
  • ✅ /invest:monitor-holdings - 6 specialized agents
  • ✅ /invest:execute-rebalance - 6 specialized agents
  • ✅ /invest:screen-opportunities - 4 specialized agents
  • ✅ /invest:review-portfolio - 6 specialized agents

Version 1.7.0-1.7.1 - October 2025

📊 Streaming Reports & Command Consistency

• ⚡ Streaming Reports (v1.7.0) - Progressive display of subagent results
• 🎯 Command Consistency (v1.7.1) - All 7 commands use parallel execution

Version 1.6.0-1.6.8 - September-October 2025

🚀 Standalone Package + Performance Optimization Series

• ✅ Zero External Dependencies - No Claude Code or Claude Desktop needed
• 🤖 18 Bundled Agents - All specialized agents included
• ⚡ Hook-Based Caching - 70% API call reduction
• 📊 Cost Tracking - Real-time monitoring of API usage and costs

See CHANGELOG.md for complete version history.

🆘 Support

Getting Help

• 📖 Documentation - Comprehensive guides in /docs
• 💬 Discord Community - Join our Discord
• 🐛 Bug Reports - GitHub Issues
• 💡 Feature Requests - GitHub Discussions

Resources

• 🌐 Website - navam.ai
• 📦 PyPI - pypi.org/project/navam
• 📚 Documentation - docs.navam.ai
• 💼 GitHub - github.com/navam-ai/navam

📄 License

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

⭐ Acknowledgments

Built with amazing open-source technologies:

• 🧠 Anthropic Claude - AI foundation
• ⚡ MCP Protocol - Agent communication
• 🚀 FastMCP - High-performance framework
• 📊 Yahoo Finance - Financial data
• 🔧 Rich - Beautiful terminal interfaces

pip install navam && navam chat