navam 1.3.0

Personal AI agents for investing, shopping, health, and learning

🤖 Navam - Personal AI Agents Platform

Personal AI agents for investing, shopping, health, and learning

🚀 Quick Start • 📖 Documentation • 💬 Chat Interface • 🔧 Integration • 🤝 Contributing

---

🎯 What is Navam?

Navam is a comprehensive AI agents platform that brings specialized artificial intelligence to key areas of your life. Starting with financial intelligence, Navam provides:

• 🤖 Interactive AI Chat Interface powered by Claude
• 📊 19 Specialized Financial Agents for investment research and analysis
• ⚡ 3 High-Performance MCP Servers for real-time data
• 🎯 Custom Investment Workflows with slash commands
• 🔌 Claude Desktop Integration for seamless experience

Currently focused on investing with plans to expand into shopping, health, and learning domains.

✨ Features

💬 Interactive Chat

• Natural Language Financial Analysis - Ask questions, get intelligent insights
• Real-time Progress Indicators - See what's happening behind the scenes
• Multi-Agent Coordination - Multiple AI agents working in parallel
• Persistent Chat History - Context-aware conversations
• Custom Slash Commands - Pre-built investment workflows

📊 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

🔧 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

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

💡 Usage Examples

Interactive Chat Commands

# In navam chat interface:
/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
# Then use: /api    # Shows which APIs are active

🔌 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)
├── 📊 Stock Analysis MCP Server (Grade A- 90%)
├── 🏢 Company Research MCP Server (Grade C+ 75%)
├── 📰 News Analysis MCP Server (Grade B 80%)
├── 🎯 19 Specialized AI Agents
├── ⚡ 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

🔒 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.2.0 (Latest)

• ✨ Enhanced API Status Monitoring - Real-time API health dashboard
• 🔧 Improved Configuration - Comprehensive API key documentation
• 📊 Better Error Handling - Graceful fallbacks when APIs unavailable
• 🚀 Performance Optimizations - Faster response times

Version 1.1.3

• 🤖 19 Specialized Financial Agents - Expert AI for every investment need
• 💬 Interactive Chat Interface - Natural language financial analysis
• 📊 Production MCP Servers - High-performance data integration
• ⚡ Custom Investment Commands - Pre-built workflows
• 🔐 Enterprise Security - Read-only, secure operations

🆘 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