Add detailed local installation guide for beginners

INSTALLATION.md

@@ -0,0 +1,727 @@
+# Amihan 1.2 - Complete Local Installation Guide
+
+**For Complete Beginners - Step by Step**
+
+This guide will help you run Amihan (and optionally Bandila + Amigo) on your own computer.
+
+---
+
+## What You're Installing
+
+**Amihan 1.2** - The intelligent orchestrator that coordinates between specialists.
+
+**Optional Specialists:**
+- **Bandila 1.0** - Reasoning specialist (for architecture, DevOps, strategy)
+- **Amigo 1.0** - Coding specialist (for programming, debugging, algorithms)
+
+**Note:** You can run Amihan alone, or with the full Trio for better results.
+
+---
+
+## System Requirements
+
+### Minimum (Amihan Only):
+- 8GB RAM
+- 10GB free disk space
+- Any CPU (Intel, AMD, Apple Silicon)
+- Internet connection (for initial download)
+
+### Recommended (Full Trio):
+- 16GB RAM (32GB ideal)
+- 30GB free disk space
+- NVIDIA GPU with 8GB+ VRAM (optional, makes it faster)
+- Internet connection
+
+### Operating Systems:
+- Windows 10/11
+- macOS (Intel or Apple Silicon M1/M2/M3)
+- Linux (Ubuntu, Fedora, Debian, etc.)
+
+---
+
+## Installation Steps
+
+### Step 1: Install Python
+
+Python is the programming language needed to run the models.
+
+#### Windows:
+1. Go to: https://www.python.org/downloads/
+2. Click the big yellow "Download Python 3.11" button
+3. Run the downloaded file
+4. **IMPORTANT**: Check the box "Add Python to PATH"
+5. Click "Install Now"
+6. Wait for installation to complete
+7. Click "Close"
+
+#### macOS:
+Open Terminal (Applications → Utilities → Terminal) and paste:
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+brew install python@3.11
+```
+
+#### Linux (Ubuntu/Debian):
+Open Terminal and paste:
+```bash
+sudo apt update
+sudo apt install python3.11 python3.11-venv python3-pip git
+```
+
+#### Linux (Fedora):
+```bash
+sudo dnf install python3.11 python3-pip git
+```
+
+**Verify Python is installed:**
+Open Terminal/Command Prompt and type:
+```bash
+python --version
+```
+You should see: `Python 3.11.x` or similar.
+
+If you see "command not found", try:
+```bash
+python3 --version
+```
+
+---
+
+### Step 2: Create a Project Folder
+
+This is where all the AI models will be stored.
+
+#### Windows:
+1. Open File Explorer
+2. Go to your Documents folder
+3. Right-click in empty space
+4. Click "New" → "Folder"
+5. Name it: `amihan-ai`
+6. Open Command Prompt:
+   - Press `Windows Key + R`
+   - Type: `cmd`
+   - Press Enter
+7. Type this and press Enter:
+```cmd
+cd %USERPROFILE%\Documents\amihan-ai
+```
+
+#### macOS/Linux:
+Open Terminal and paste:
+```bash
+mkdir ~/amihan-ai
+cd ~/amihan-ai
+```
+
+---
+
+### Step 3: Set Up Python Environment
+
+This creates an isolated space for the AI models.
+
+**Copy and paste this entire block** into your Terminal/Command Prompt:
+
+#### Windows:
+```cmd
+python -m venv venv
+venv\Scripts\activate
+```
+
+#### macOS/Linux:
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+You should now see `(venv)` at the start of your command line.
+
+---
+
+### Step 4: Install Required Software
+
+**Copy and paste this** (it will take 5-10 minutes):
+
+```bash
+pip install --upgrade pip
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
+pip install transformers peft accelerate gradio huggingface-hub bitsandbytes
+```
+
+**If you have an NVIDIA GPU** (for faster performance), use this instead:
+```bash
+pip install --upgrade pip
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+pip install transformers peft accelerate gradio huggingface-hub bitsandbytes
+```
+
+**Wait for it to finish.** You'll see lots of text scrolling. This is normal.
+
+---
+
+### Step 5: Download the Models
+
+You have two options: Amihan only, or the full Trio.
+
+#### Option A: Amihan Only (Faster, Smaller)
+
+Create a file called `download_amihan.py`:
+
+**Windows:** Right-click in folder → New → Text Document → Rename to `download_amihan.py`
+
+**macOS/Linux:** In Terminal, type: `nano download_amihan.py`
+
+**Paste this code:**
+
+```python
+from huggingface_hub import snapshot_download
+import os
+
+print("=" * 60)
+print("DOWNLOADING AMIHAN 1.2")
+print("=" * 60)
+print()
+print("This will download about 8GB of data.")
+print("Estimated time: 10-20 minutes (depends on internet speed)")
+print()
+
+# Create models directory
+os.makedirs("models", exist_ok=True)
+
+# Download Amihan orchestrator model
+print("Downloading Amihan 1.2 (Phi-3-mini + LoRA adapter)...")
+snapshot_download(
+    repo_id="swordfish7412/Amihan_1.2",
+    local_dir="models/amihan",
+    local_dir_use_symlinks=False
+)
+
+print()
+print("=" * 60)
+print("AMIHAN 1.2 DOWNLOADED SUCCESSFULLY!")
+print("=" * 60)
+print()
+print("Next step: Run 'python run_amihan.py'")
+```
+
+Save and close. Then run:
+```bash
+python download_amihan.py
+```
+
+#### Option B: Full Trio (Amihan + Bandila + Amigo)
+
+Create a file called `download_trio.py`:
+
+```python
+from huggingface_hub import snapshot_download
+import os
+
+print("=" * 60)
+print("DOWNLOADING SWORDFISH AI TRIO")
+print("=" * 60)
+print()
+print("This will download about 28GB of data.")
+print("Estimated time: 30-60 minutes (depends on internet speed)")
+print()
+
+# Create models directory
+os.makedirs("models", exist_ok=True)
+
+# Download Amihan
+print("1/3 Downloading Amihan 1.2 (Orchestrator)...")
+snapshot_download(
+    repo_id="swordfish7412/Amihan_1.2",
+    local_dir="models/amihan",
+    local_dir_use_symlinks=False
+)
+print("✓ Amihan downloaded!")
+print()
+
+# Download Bandila
+print("2/3 Downloading Bandila 1.0 (Reasoning Specialist)...")
+snapshot_download(
+    repo_id="swordfish7412/Bandila_1.0",
+    local_dir="models/bandila",
+    local_dir_use_symlinks=False
+)
+print("✓ Bandila downloaded!")
+print()
+
+# Download Amigo
+print("3/3 Downloading Amigo 1.0 (Coding Specialist)...")
+snapshot_download(
+    repo_id="swordfish7412/Amigo_1.0",
+    local_dir="models/amigo",
+    local_dir_use_symlinks=False
+)
+print("✓ Amigo downloaded!")
+print()
+
+print("=" * 60)
+print("ALL MODELS DOWNLOADED SUCCESSFULLY!")
+print("=" * 60)
+print()
+print("Next step: Run 'python run_trio.py'")
+```
+
+Save and run:
+```bash
+python download_trio.py
+```
+
+**Go make coffee.** This takes a while.
+
+---
+
+### Step 6: Create the Run Script
+
+#### Option A: Run Amihan Only
+
+Create a file called `run_amihan.py`:
+
+```python
+"""
+Amihan 1.2 - Standalone Mode
+Runs without Bandila and Amigo specialists
+"""
+
+import torch
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+import gradio as gr
+
+print("=" * 60)
+print("LOADING AMIHAN 1.2 - STANDALONE MODE")
+print("=" * 60)
+print()
+
+# Detect device
+device = "cuda" if torch.cuda.is_available() else "cpu"
+print(f"Device: {device}")
+print()
+
+# Load Amihan orchestrator model
+print("Loading Amihan 1.2 (Phi-3-mini + LoRA)...")
+MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True)
+tokenizer.pad_token = tokenizer.eos_token
+
+base_model = AutoModelForCausalLM.from_pretrained(
+    MODEL_NAME,
+    torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+    device_map="auto",
+    trust_remote_code=True,
+    low_cpu_mem_usage=True
+)
+
+model = PeftModel.from_pretrained(base_model, "models/amihan")
+model.eval()
+
+print("✓ Amihan loaded!")
+print()
+print("=" * 60)
+print("AMIHAN 1.2 READY!")
+print("=" * 60)
+print()
+
+def generate_response(message):
+    """Generate response using Amihan's brain"""
+    prompt = f"""You are Amihan, an intelligent AI assistant. Answer this question:
+
+Question: {message}
+
+Provide a helpful, detailed response.
+
+Response:"""
+    
+    inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=1024)
+    inputs = {k: v.to(model.device) for k, v in inputs.items()}
+    
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=512,
+            temperature=0.7,
+            top_p=0.9,
+            do_sample=True,
+            pad_token_id=tokenizer.eos_token_id
+        )
+    
+    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    
+    if "Response:" in response:
+        response = response.split("Response:")[-1].strip()
+    
+    return response
+
+def chat(message, history):
+    """Chat function for Gradio"""
+    if not message.strip():
+        return "Please enter a message."
+    
+    response = generate_response(message)
+    return response
+
+# Create Gradio interface
+with gr.Blocks(theme=gr.themes.Soft(), title="Amihan 1.2 - Standalone") as demo:
+    gr.Markdown("""
+    # Amihan 1.2 - Standalone Mode
+    
+    **Running locally on your computer**
+    
+    Amihan is running in standalone mode without the specialist models.
+    For full Trio capabilities, download and run Bandila + Amigo.
+    
+    Ask any technical question!
+    """)
+    
+    chatbot = gr.Chatbot(height=500, show_label=False)
+    
+    with gr.Row():
+        msg = gr.Textbox(
+            placeholder="Ask me anything...",
+            show_label=False,
+            scale=4
+        )
+        submit = gr.Button("Send", scale=1, variant="primary")
+    
+    gr.Examples(
+        examples=[
+            "What is your name?",
+            "Explain microservices architecture",
+            "Write a Python function to sort a list"
+        ],
+        inputs=msg
+    )
+    
+    def respond(message, chat_history):
+        bot_message = chat(message, chat_history)
+        chat_history.append((message, bot_message))
+        return "", chat_history
+    
+    msg.submit(respond, [msg, chatbot], [msg, chatbot])
+    submit.click(respond, [msg, chatbot], [msg, chatbot])
+
+if __name__ == "__main__":
+    print("Starting Gradio interface...")
+    print("Open your browser and go to: http://localhost:7860")
+    print()
+    demo.launch(server_name="127.0.0.1", server_port=7860, share=False)
+```
+
+#### Option B: Run Full Trio
+
+Create a file called `run_trio.py`:
+
+```python
+"""
+Swordfish AI Trio - Complete Local Installation
+Amihan + Bandila + Amigo working together
+"""
+
+import torch
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+import gradio as gr
+
+print("=" * 60)
+print("LOADING SWORDFISH AI TRIO")
+print("=" * 60)
+print()
+print("This may take 3-5 minutes on first run...")
+print()
+
+# Detect device
+device = "cuda" if torch.cuda.is_available() else "cpu"
+print(f"Device: {device}")
+print()
+
+# Load Amihan (Orchestrator)
+print("1/3 Loading Amihan 1.2 (Orchestrator)...")
+amihan_tokenizer = AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct", trust_remote_code=True)
+amihan_tokenizer.pad_token = amihan_tokenizer.eos_token
+
+amihan_base = AutoModelForCausalLM.from_pretrained(
+    "microsoft/Phi-3-mini-4k-instruct",
+    torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+    device_map="auto",
+    trust_remote_code=True,
+    low_cpu_mem_usage=True
+)
+amihan_model = PeftModel.from_pretrained(amihan_base, "models/amihan")
+amihan_model.eval()
+print("✓ Amihan loaded!")
+print()
+
+# Load Bandila (Reasoning Specialist)
+print("2/3 Loading Bandila 1.0 (Reasoning)...")
+bandila_base = AutoModelForCausalLM.from_pretrained(
+    "mistralai/Mistral-7B-v0.1",
+    torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+    device_map="auto",
+    low_cpu_mem_usage=True
+)
+bandila_model = PeftModel.from_pretrained(bandila_base, "models/bandila")
+bandila_tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")
+bandila_tokenizer.pad_token = bandila_tokenizer.eos_token
+bandila_model.eval()
+print("✓ Bandila loaded!")
+print()
+
+# Load Amigo (Coding Specialist)
+print("3/3 Loading Amigo 1.0 (Coding)...")
+amigo_base = AutoModelForCausalLM.from_pretrained(
+    "codellama/CodeLlama-7b-hf",
+    torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+    device_map="auto",
+    low_cpu_mem_usage=True
+)
+amigo_model = PeftModel.from_pretrained(amigo_base, "models/amigo")
+amigo_tokenizer = AutoTokenizer.from_pretrained("codellama/CodeLlama-7b-hf")
+amigo_tokenizer.pad_token = amigo_tokenizer.eos_token
+amigo_model.eval()
+print("✓ Amigo loaded!")
+print()
+
+print("=" * 60)
+print("SWORDFISH AI TRIO READY!")
+print("=" * 60)
+print()
+
+# Routing logic
+CODING_KEYWORDS = [
+    'code', 'function', 'class', 'method', 'algorithm', 'program', 'script',
+    'debug', 'error', 'bug', 'fix', 'implement', 'write', 'create',
+    'python', 'javascript', 'java', 'c++', 'rust', 'go', 'sql',
+    'api', 'endpoint', 'route', 'controller', 'model', 'view'
+]
+
+def route_request(message):
+    """Use Amihan to decide which specialist to use"""
+    message_lower = message.lower()
+    
+    # Check for coding keywords
+    coding_score = sum(1 for kw in CODING_KEYWORDS if kw in message_lower)
+    
+    if coding_score >= 2:
+        return "amigo"
+    elif any(word in message_lower for word in ['architecture', 'design', 'strategy', 'devops', 'infrastructure']):
+        return "bandila"
+    elif 'write' in message_lower or 'create' in message_lower:
+        return "amigo"
+    else:
+        return "bandila"
+
+def generate_response(model, tokenizer, message):
+    """Generate response from a specialist model"""
+    prompt = f"### Instruction:\n{message}\n\n### Response:\n"
+    
+    inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=2048)
+    inputs = {k: v.to(model.device) for k, v in inputs.items()}
+    
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=512,
+            temperature=0.7,
+            top_p=0.9,
+            do_sample=True,
+            pad_token_id=tokenizer.eos_token_id
+        )
+    
+    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    
+    if "### Response:" in response:
+        response = response.split("### Response:")[-1].strip()
+    
+    return response
+
+def chat(message, history):
+    """Main chat function - routes to appropriate specialist"""
+    if not message.strip():
+        return "Please enter a message."
+    
+    # Route the request
+    specialist = route_request(message)
+    
+    if specialist == "amigo":
+        print(f"→ Routing to Amigo (Coding)")
+        response = generate_response(amigo_model, amigo_tokenizer, message)
+        return f"**[Amigo - Coding Specialist]**\n\n{response}"
+    else:
+        print(f"→ Routing to Bandila (Reasoning)")
+        response = generate_response(bandila_model, bandila_tokenizer, message)
+        return f"**[Bandila - Reasoning Specialist]**\n\n{response}"
+
+# Create Gradio interface
+with gr.Blocks(theme=gr.themes.Soft(), title="Swordfish AI Trio") as demo:
+    gr.Markdown("""
+    # Swordfish AI Trio - Local Installation
+    
+    **Running locally on your computer**
+    
+    **Amihan 1.2:** Intelligent orchestrator  
+    **Bandila 1.0:** Reasoning specialist  
+    **Amigo 1.0:** Coding specialist
+    
+    Ask any technical question - Amihan will route it to the right specialist!
+    """)
+    
+    chatbot = gr.Chatbot(height=500, show_label=False)
+    
+    with gr.Row():
+        msg = gr.Textbox(
+            placeholder="Ask about code, architecture, DevOps...",
+            show_label=False,
+            scale=4
+        )
+        submit = gr.Button("Send", scale=1, variant="primary")
+    
+    gr.Examples(
+        examples=[
+            "What is your name?",
+            "Write a Python function to calculate Fibonacci",
+            "Explain microservices architecture best practices",
+            "Debug this code: def add(a,b) return a+b"
+        ],
+        inputs=msg
+    )
+    
+    def respond(message, chat_history):
+        bot_message = chat(message, chat_history)
+        chat_history.append((message, bot_message))
+        return "", chat_history
+    
+    msg.submit(respond, [msg, chatbot], [msg, chatbot])
+    submit.click(respond, [msg, chatbot], [msg, chatbot])
+
+if __name__ == "__main__":
+    print("Starting Gradio interface...")
+    print("Open your browser and go to: http://localhost:7860")
+    print()
+    demo.launch(server_name="127.0.0.1", server_port=7860, share=False)
+```
+
+---
+
+### Step 7: Run It!
+
+**For Amihan Only:**
+```bash
+python run_amihan.py
+```
+
+**For Full Trio:**
+```bash
+python run_trio.py
+```
+
+**First run takes 2-5 minutes to load models into memory.**
+
+When you see:
+```
+AMIHAN 1.2 READY!
+Running on local URL:  http://127.0.0.1:7860
+```
+
+**Open your browser and go to:** http://localhost:7860
+
+---
+
+## Usage Tips
+
+### Response Times:
+- **With GPU**: 2-5 seconds per response
+- **Without GPU (CPU)**: 30-90 seconds per response
+
+### Best Questions:
+- "Write a Python function to..."
+- "Explain the concept of..."
+- "How do I design a..."
+- "Debug this code: [paste code]"
+
+### Stopping the Server:
+Press `Ctrl + C` in the Terminal/Command Prompt
+
+### Running Again:
+1. Open Terminal/Command Prompt
+2. Navigate to folder: `cd ~/amihan-ai` (or `cd %USERPROFILE%\Documents\amihan-ai` on Windows)
+3. Activate environment: `source venv/bin/activate` (or `venv\Scripts\activate` on Windows)
+4. Run: `python run_amihan.py` or `python run_trio.py`
+
+---
+
+## Troubleshooting
+
+### "Out of memory" error:
+Your system doesn't have enough RAM. Try:
+1. Close other applications
+2. Run Amihan only (not full Trio)
+3. Restart your computer and try again
+
+### "torch not found" error:
+Reinstall PyTorch:
+```bash
+pip uninstall torch
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+```
+
+### Very slow responses:
+This is normal on CPU. To speed up:
+1. Get a computer with NVIDIA GPU
+2. Or use the online version: https://huggingface.co/spaces/swordfish7412/Amihan
+
+### "Python command not found":
+Try using `python3` instead of `python`:
+```bash
+python3 run_amihan.py
+```
+
+---
+
+## Uninstalling
+
+To remove everything:
+
+1. Deactivate environment:
+```bash
+deactivate
+```
+
+2. Delete the folder:
+   - **Windows**: Delete `Documents\amihan-ai` folder
+   - **macOS/Linux**: `rm -rf ~/amihan-ai`
+
+---
+
+## Getting Help
+
+- **Online Demo**: https://huggingface.co/spaces/swordfish7412/Amihan
+- **Model Page**: https://huggingface.co/swordfish7412/Amihan_1.2
+- **Email**: janfrancisisrael@gmail.com
+
+---
+
+## Summary
+
+**Easiest Option:**  
+Just use online: https://huggingface.co/spaces/swordfish7412/Amihan
+
+**Local Installation Steps:**
+1. Install Python 3.11
+2. Create project folder
+3. Set up virtual environment
+4. Install dependencies (5-10 min)
+5. Download models (10-60 min depending on option)
+6. Run the script
+7. Open http://localhost:7860
+
+**Total Time:** 30-90 minutes (mostly downloading)
+
+---
+
+**Created by:** Jan Israel  
+**Part of:** The Swordfish Project  
+**Version:** 1.2 (November 2025)
+