A sophisticated AI assistant that combines Ollama LLMs with RAG (Retrieval-Augmented Generation) capabilities, featuring web scraping, vector search, and intelligent context injection.

• 🧠 RAG Pipeline: FAISS vector search with BERT embeddings for intelligent context retrieval
• 🔄 Dynamic Model Switching: Hot-swap between different Ollama models
• 🌐 Web Scraping: Automatically scrape and index web content with BeautifulSoup
• 🔌 MCP Integration: Both MCP Server (be a tool for others) AND Client (use external tools)
• 📅 Smart Calendar: ASCII calendar view with natural language event creation
• 🎨 Beautiful CLI: Customizable themes (Matrix, Cyberpunk, Minimal) with Rich terminal UI
• 💾 Persistent Memory: Conversation history and document storage in SQLite
• ⚡ Performance Optimized: Lazy loading, caching, and async operations
• 🛡️ Robust: Timeout handling, circuit breakers, and graceful error recovery
• 📊 Smart Analytics: Usage statistics and system health monitoring

1. Python 3.8+ - Download Python
2. Ollama - Install Ollama
3. Node.js (optional, for MCP servers and web UI) - Download Node.js

Use the platform-specific setup scripts to automatically install dependencies:

setup_windows.bat

chmod +x setup_mac.sh
./setup_mac.sh

1. Clone or download the project:

cd jarvis_ai_agent

2. Install dependencies:

pip install -r requirements.txt

3. Start Ollama (in another terminal):

ollama serve

4. Pull some models (choose what you prefer):

ollama pull llama3.1
ollama pull codellama
ollama pull mistral

5. Run Jarvis:

python main.py

1. Python 3.8+

   • Download from python.org
   • Important: Check "Add Python to PATH" during installation
   • Verify installation: python --version

2. Ollama

   • Download from ollama.ai/download
   • Run the installer and follow the prompts
   • Verify installation: ollama --version

3. Node.js (optional, for MCP and web UI)

   • Download from nodejs.org
   • Choose the LTS version
   • Verify installation: node --version

4. Git (optional, for cloning)

   • Download from git-scm.com

Run the automated setup script:

setup_windows.bat

Or manually:

pip install -r requirements.txt
ollama serve
ollama pull llama3.1
python main.py

• PowerShell vs Command Prompt: Both work, but PowerShell offers better features
• Virtual Environment (recommended):

  python -m venv venv
  venv\Scripts\activate
  pip install -r requirements.txt

• Firewall: Allow Ollama through Windows Firewall if prompted
• Long Path Names: Enable long paths in Windows if you encounter path length issues:

  reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

1. Homebrew (recommended)

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Python 3.8+

   • macOS comes with Python, but you may need a newer version:

   brew install [email protected]

   • Verify: python3 --version

3. Ollama

   brew install ollama

   • Or download from ollama.ai/download

4. Node.js (optional, for MCP and web UI)

   brew install node

Run the automated setup script:

chmod +x setup_mac.sh
./setup_mac.sh

Or manually:

pip3 install -r requirements.txt
ollama serve
ollama pull llama3.1
python3 main.py

• Apple Silicon (M1/M2/M3): All dependencies are compatible with ARM architecture
• Virtual Environment (recommended):

  python3 -m venv venv
  source venv/bin/activate
  pip install -r requirements.txt

• Permissions: If you see "permission denied" errors:

  chmod +x start_jrvs.sh start-api.sh setup_mac.sh

• Gatekeeper: If macOS blocks Ollama, go to System Preferences > Security & Privacy and allow it
• Memory: For larger models (70B+), ensure you have sufficient RAM (32GB+ recommended)

Just type your questions and Jarvis will respond with enhanced context from its knowledge base:

jarvis❯ What is machine learning?

Scrape a website:

jarvis❯ /scrape https://python.org/dev/pep/pep-8/

Switch AI model:

jarvis❯ /switch codellama

Search your knowledge base:

jarvis❯ /search python best practices

Change theme:

jarvis❯ /theme cyberpunk

1. Document Ingestion: Web pages are scraped and chunked into manageable pieces
2. Embedding Generation: BERT creates vector embeddings for semantic search
3. Vector Storage: FAISS provides fast similarity search across document chunks
4. Context Injection: Relevant chunks are automatically added to your prompts
5. Enhanced Responses: Ollama generates responses with enriched context

Jarvis gets smarter over time:

• Conversation Memory: Learns from your chat history
• Document Growth: More scraped content = better context
• Usage Patterns: Optimizes based on your preferences

JRVS can now act as an MCP Client, connecting to MCP servers to access external tools like filesystems, databases, APIs, and more!

1. Configure servers in mcp/client_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/xmanz"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

2. Start JRVS - it will auto-connect to configured servers

3. Use MCP commands:

/mcp-servers              # List connected servers
/mcp-tools                # List all available tools
/mcp-tools filesystem     # Tools from specific server

• filesystem - File operations (read, write, search)
• github - GitHub API (issues, PRs, repos)
• postgres - PostgreSQL database access
• brave-search - Web search
• memory - Persistent notes/memory
• slack - Slack messaging
• And many more! See MCP_CLIENT_GUIDE.md

📖 Full guide: See MCP_CLIENT_GUIDE.md

Example for connecting to a remote Ollama instance:

export OLLAMA_BASE_URL="http://192.168.1.100:11434"
export OLLAMA_DEFAULT_MODEL="llama3:8b"
python main.py

python main.py --help

Options:

• --theme {matrix,cyberpunk,minimal} - Set CLI theme
• --model MODEL_NAME - Set default Ollama model
• --ollama-url URL - Custom Ollama API URL
• --no-banner - Skip ASCII banner
• --debug - Enable debug mode

• Matrix: Green-on-black hacker aesthetic
• Cyberpunk: Magenta and cyan futuristic style
• Minimal: Clean black and white interface

jarvis_ai_agent/
├── main.py              # Application entry point
├── config.py            # Configuration settings
├── requirements.txt     # Python dependencies
├── core/
│   ├── database.py      # SQLite database operations
│   └── lazy_loader.py   # Performance optimizations
├── rag/
│   ├── embeddings.py    # BERT embedding generation
│   ├── vector_store.py  # FAISS vector operations
│   └── retriever.py     # RAG pipeline coordinator
├── llm/
│   └── ollama_client.py # Ollama API integration
├── cli/
│   ├── interface.py     # Main CLI interface
│   ├── themes.py        # Theme management
│   └── commands.py      # Command handling
├── scraper/
│   └── web_scraper.py   # Web scraping functionality
└── data/                # Generated data directory
    ├── jarvis.db        # SQLite database
    └── faiss_index.*    # Vector index files

Edit config.py to customize:

• Default models
• Timeout settings
• RAG parameters
• Performance limits

JRVS now includes a full-featured MCP server for Claude Code integration:

# Run MCP server
python mcp/server.py

# Test components
python mcp/test_server.py

17 tools available: RAG search, web scraping, calendar, model switching, and more!

See MCP_SETUP.md for complete integration guide.

The modular design allows easy integration:

from rag.retriever import rag_retriever
from llm.ollama_client import ollama_client

# Add document
doc_id = await rag_retriever.add_document(content, title, url)

# Enhanced chat
context = await rag_retriever.retrieve_context(query)
response = await ollama_client.generate(query, context=context)

"Cannot connect to Ollama"

• Make sure Ollama is running: ollama serve
• Check if port 11434 is free
• Verify Ollama installation

"No models available"

• Pull at least one model: ollama pull llama3.1
• Check model list: ollama list

Import errors

• Install dependencies: pip install -r requirements.txt
• Check Python version: python --version (needs 3.8+)

Performance issues

• Reduce MAX_CONTEXT_LENGTH in config.py
• Use smaller models (e.g., llama3.1:8b instead of llama3.1:70b)
• Clear vector cache: delete data/faiss_index.* files

"python is not recognized"

• Python is not in PATH
• Reinstall Python and check "Add Python to PATH"
• Or use the full path: C:\Python311\python.exe

"pip is not recognized"

• Try: python -m pip install -r requirements.txt

Permission denied errors

• Run Command Prompt as Administrator
• Or use a virtual environment

torch installation fails

• Install Visual C++ Build Tools from Microsoft
• Try: pip install torch --index-url https://download.pytorch.org/whl/cpu

FAISS installation issues

• Try: pip install faiss-cpu --no-cache-dir
• Ensure you have a 64-bit Python installation

"command not found: python"

• Use python3 instead of python
• Or create an alias: alias python=python3

"zsh: permission denied"

• Make script executable: chmod +x script_name.sh

SSL certificate errors

• Install certificates:

  /Applications/Python\ 3.11/Install\ Certificates.command

Apple Silicon (M1/M2/M3) issues

• Ensure you're using ARM-native Python (not Rosetta)
• Check architecture: python3 -c "import platform; print(platform.machine())"
• Should output arm64

Homebrew not found after install (Apple Silicon)

• Add to your shell profile (~/.zshrc):

  eval "$(/opt/homebrew/bin/brew shellenv)"

• Then: source ~/.zshrc

Memory errors with large models

• Close other applications to free RAM
• Use smaller models: ollama pull llama3.1:8b
• Check available memory: top or Activity Monitor

"npx: command not found"

• Install Node.js from nodejs.org
• Verify: node --version and npm --version

MCP servers not connecting

• Check mcp/client_config.json configuration
• Ensure paths are correct for your OS
• Windows paths use backslashes or forward slashes: "C:/Users/name/folder"

Using a virtual environment is recommended to avoid dependency conflicts:

Windows:

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

macOS/Linux:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

To deactivate: deactivate

This is a functional RAG system built for learning and experimentation. Feel free to:

• Add new features
• Improve performance
• Fix bugs
• Add new themes
• Enhance the CLI

This project is for educational and personal use. Respect website terms of service when scraping.

• Ollama for local LLM serving
• FAISS for efficient vector search
• Sentence Transformers for embeddings
• Rich for beautiful terminal UI
• BeautifulSoup for web scraping

Happy chatting with Jarvis! 🚀