navam 1.7.4

Standalone AI investment assistant with 18 specialized agents and real-time market data

🤖 Navam - Standalone AI Investment Assistant

AI-powered investment research with 18 specialized agents and real-time market data

🚀 Quick Start • 📖 Features • 💬 Chat Interface • 🤖 Agents • 🤝 Contributing

---

🎯 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

Source	Type	Features
Yahoo Finance	Free	Stock quotes, company data, news
SEC EDGAR	Free	Official company filings
Alpha Vantage	Premium	Technical indicators, fundamentals
Polygon.io	Premium	Real-time professional data
MarketAux	Premium	Curated financial news
NewsAPI	Premium	Global news coverage
Finnhub	Premium	Real-time market news

📊 Performance

MCP Server	Grade	Response Time	Production Ready
Stock Analysis	A- (90%)	2-4s	✅
Company Research	C+ (75%)	2-4s	✅
News Analysis	B (80%)	<2s	✅

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:

Command	Description
/agents	List all 18 specialized AI agents with descriptions and categories
/api	Show detailed API status - which are active, which need configuration
/perf	Performance metrics: cache hit rate, API costs, parallel execution stats
/cache	Cache statistics: hits/misses, cost savings, efficiency metrics
/help	Display complete help with all features and commands
/commands	List all available slash commands (built-in + investment workflows)
/tools	Show all MCP tools available for financial analysis
/servers	Display loaded MCP servers status
/status	Show conversation metrics (turns, tools used, agents invoked)
/new	Start a fresh conversation (clear context)
/clear	Clear the screen
/exit	Exit the chat interface

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

---

🚀 Ready to supercharge your financial intelligence?

Start your journey with AI-powered investing today!

pip install navam && navam chat

Built with ❤️ for the global financial community