navam 1.6.3

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.6.0

• ✅ Zero Dependencies - No Claude Code or Claude Desktop installation needed
• ⚡ 70% Faster - Hook-based caching dramatically reduces API calls
• 🚀 Production Ready - Clean package, predictable behavior, works anywhere
• 🤖 18 Bundled Agents - All agents included, ready to use immediately

✨ 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
• Persistent Chat History - Context-aware conversations with turn tracking
• Custom Slash Commands - Pre-built investment workflows
• Built-in Commands - /agents, /api, /tools, /help, 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
/help        # Show all available commands
/tools       # List available MCP tools
/commands    # List all slash commands

# Investment workflow commands:
/invest:research-stock NVDA
/invest:review-portfolio
/invest:screen-opportunities
/invest:plan-goals
/invest:optimize-taxes

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	✅

• Async/Await Architecture - Concurrent operations
• Intelligent Caching - Minimizes API calls
• 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
/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
• /invest:review-portfolio - Portfolio analysis and recommendations
• /invest:screen-opportunities - Find investment opportunities
• /invest:plan-goals - Financial goal planning
• /invest:optimize-taxes - Tax optimization strategies

🔒 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.6.0 (Latest) - January 2025

🚀 Major Release: Standalone Package + Performance Boost

• ✅ Zero External Dependencies - No Claude Code or Claude Desktop needed

  • Package bundles all 18 agents and 8 commands
  • Works immediately after pip install navam
  • Production-ready for any environment (containers, CI/CD, cloud)

• ⚡ 70% Performance Improvement - Hook-based intelligent caching

  • Automatic duplicate API call elimination
  • 70% reduction in API costs per query
  • Faster response times (2-3min vs 8min for complex workflows)

• 🏗️ Clean Architecture - Complete package independence

  • Single source of truth (package-bundled resources)
  • Predictable behavior across all environments
  • No file copying to user directories
  • Clear error messages if sync script not run

• 🤖 18 Bundled Agents - All specialized agents included

  • fundamental-analyst, technical-analyst, news-analyst
  • Portfolio managers, risk managers, tax optimizers
  • Ready to use without any configuration

Version 1.5.11 (December 2024)

• 🔧 Stable Release - Markdown-based agents working reliably
• 🎯 8 Investment Commands - Pre-built workflow templates
• 📊 Cache Metrics - Track cache hit rates and performance

Version 1.4.1

• 🐛 Bug Fix - Fixed /agents command not finding agents in installed package
• 📦 Package Fix - All 18 agent files now properly included in PyPI distribution

Version 1.4.0

• 🤖 New /agents Command - List all 18 specialized AI agents with descriptions
• 📊 Enhanced Chat Interface - Real-time thinking tokens and tool execution tracking
• ⚡ Multi-Agent Monitoring - See parallel agent execution in real-time

🆘 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