scorpion-cli 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# Scorpion CLI 🦂
+
+An end-to-end **agentic AI assistant** for your terminal, refined for **speed**, **aesthetics**, and **intelligence**.
+
+Powered by [Ollama](https://ollama.com) and **qwen3.5:0.8b**, Scorpion doesn't just chat—it takes action, manages your system, and researches the web for you **(for free, without API keys)**.
+
+```
+  ███████╗ ██████╗ ██████╗ ██████╗ ██████╗ ██╗ ██████╗ ███╗   ██╗
+  ██╔════╝██╔════╝██╔═══██╗██╔══██╗██╔══██╗██║██╔═══██╗████╗  ██║
+  ███████╗██║     ██║   ██║██████╔╝██████╔╝██║██║   ██║██╔██╗ ██║
+  ╚════██║██║     ██║   ██║██╔══██╗██╔═══╝ ██║██║   ██║██║╚██╗██║
+  ███████║╚██████╗╚██████╔╝██║  ██║██║     ██║╚██████╔╝██║ ╚████║
+  ╚══════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═══╝
+```
+
+## ✨ Key Features
+
+- **🌐 Free & Private Web Search**: Builit-in scraping engine uses **DuckDuckGo**, **Bing**, and **Google News** to find real-time information without requiring any paid API keys.
+- **🧠 Smart Agent Core**: Automatically detects when it needs to search the web (for events after 2023) vs. using internal knowledge.
+- **🔬 Deep Research Mode**: A dedicated tool that scans **arXiv** (papers), **Hacker News** (tech discussions), and **Wikipedia** to generate comprehensive, cited reports.
+- **⚡ Local & Fast**: Runs entirely on your machine using Ollama. No data leaves your system except for anonymous search queries.
+- **🎨 Beautiful UI**: Rich ASCII tables, interactive spinners, live progress updates, and structured markdown rendering.
+- **🔧 System Control**: Execute commands, manage files, check system performance (CPU/RAM), and write code directly to files.
+
+## What It Can Do
+
+- **"Research the latest developments in quantum computing"** (Triggers Deep Research)
+- **"What's the current stock price of NVIDIA?"** (Triggers Web Search)
+- **"Check my system CPU usage"** (Triggers System Tools)
+- **"Create a Python script for a discord bot"** (Triggers File Tools)
+
+## Requirements
+
+- **Node.js** 22.12+
+- [Ollama](https://ollama.com/download) running locally
+- **qwen3.5:0.8b** model (recommended):
+  ```bash
+  ollama pull qwen3.5:0.8b
+  ```
+
+## Quick Start
+
+1. **Clone & Install**
+   ```bash
+   git clone <repo-url>
+   cd scorpion-cli-2
+   npm install
+   ```
+
+2. **Run Scorpion**
+   ```bash
+   npm start
+   ```
+   *No API keys required! It works straight out of the box.*
+
+### Install from npm
+
+After the `0.1.0` release, Scorpion can be installed on Windows, macOS, and Linux:
+
+```bash
+# Global npm install
+npm install --global scorpion-cli
+scorpion
+
+# Run without installing globally
+npx scorpion-cli
+```
+
+PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/amaansyed27/scorpion-cli-agent/v0.1.0/install.ps1 | iex
+scorpion
+```
+
+macOS/Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/amaansyed27/scorpion-cli-agent/v0.1.0/install.sh | sh
+scorpion
+```
+
+The current `https://aish.dawnlightlabs.com/install.ps1` endpoint belongs to AiSH and should not be used for Scorpion. Configure a separate Scorpion subdomain, such as `https://scorpion.dawnlightlabs.com/install.ps1`, to serve these installer files if you want a branded short URL.
+
+Scorpion is distributed as one Node.js package rather than separate native binaries, so the same release works across all three platforms. Ollama must still be installed and running locally.
+
+## 🎯 Usage & Power Commands
+
+Scorpion uses a natural language interface, but also supports powerful triggers for specific workflows:
+
+Inside the interactive session, slash commands control the session:
+
+```text
+/list                 List installed Ollama models
+/model                Interactively select an installed model
+/model <name>         Switch directly to a model
+/settings             Show the active model and settings
+/think on|off|toggle  Enable or disable visible thinking output
+/help                 Show all commands
+/clear                Clear conversation history
+/stats, /reports      Show session statistics or saved reports
+/export [md|json]     Export the last report
+/demo                 Show UI features
+/exit                 Quit Scorpion
+```
+
+### **1. Deep Research Mode** (`@deep`)
+Triggers an in-depth analysis session. It searches multiple sources, reads simplified content, and compiles a structured report with citations.
+
+```bash
+> @deep The impact of AI agents on software engineering jobs
+```
+*Also triggered by asking to "research", "analyze", or "explain in detail".*
+
+### **2. Quick Response** (`@quick`)
+Forces a fast answer without searching the web, using only the model's internal knowledge.
+
+```bash
+> @quick Explain the concept of recursion
+```
+
+### **3. System & Files**
+Directly interact with your OS.
+
+```bash
+> show my memory usage
+> list files in the current directory
+> create a README.md file for a react project
+```
+
+## 🛠️ Configuration
+
+Scorpion works with default settings, but you can configure it via environment variables if needed:
+
+- `OLLAMA_HOST`: Set if your Ollama instance is not on `localhost:11434`.
+- `OLLAMA_MODEL`: Override the default `qwen3.5:0.8b` model.
+
+## Troubleshooting
+
+- **"Model not found"**: Run `ollama pull qwen3.5:0.8b` (or your preferred model) first.
+- **"Connection failed"**: Ensure Ollama is running (`ollama serve`).
+
+## Built With
+
+- **Ollama** - Local AI inference
+- **Cheerio** - specialized web scraping & parsing
+- **Node.js** - Runtime & System Interaction
+- **Ora/Chalk** - Terminal styling & Animations
+
+## License
+
+MIT

package/install.ps1

@@ -0,0 +1,22 @@
+$ErrorActionPreference = 'Stop'
+
+$requiredNode = [version]'22.12.0'
+$nodeCommand = Get-Command node -ErrorAction SilentlyContinue
+$npmCommand = Get-Command npm -ErrorAction SilentlyContinue
+
+if (-not $nodeCommand -or -not $npmCommand) {
+    throw 'Node.js 22.12 or newer is required. Install it from https://nodejs.org/ and run this installer again.'
+}
+
+$nodeVersion = [version]((& node --version).TrimStart('v'))
+if ($nodeVersion -lt $requiredNode) {
+    throw "Node.js $requiredNode or newer is required. Detected $nodeVersion."
+}
+
+& npm install --global scorpion-cli@latest
+if ($LASTEXITCODE -ne 0) {
+    throw 'Scorpion installation failed.'
+}
+
+Write-Host 'Scorpion CLI installed successfully.' -ForegroundColor Green
+Write-Host 'Run: scorpion'

package/install.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+set -eu
+
+required_node='22.12.0'
+
+if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+  echo 'Node.js 22.12 or newer is required. Install it from https://nodejs.org/ and run this installer again.' >&2
+  exit 1
+fi
+
+node_version="$(node --version | sed 's/^v//')"
+node -e "const [a,b,c] = process.argv[1].split('.').map(Number); const [x,y,z] = process.argv[2].split('.').map(Number); process.exit(a > x || (a === x && (b > y || (b === y && c >= z))) ? 0 : 1)" "$node_version" "$required_node" || {
+  echo "Node.js $required_node or newer is required. Detected $node_version." >&2
+  exit 1
+}
+
+npm install --global scorpion-cli@latest
+echo 'Scorpion CLI installed successfully.'
+echo 'Run: scorpion'

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "scorpion-cli",
+    "version": "0.1.0",
+    "description": "Agentic AI CLI assistant powered by Ollama",
+    "type": "module",
+    "main": "src/index.js",
+    "bin": {
+        "scorpion": "src/index.js"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "install.ps1",
+        "install.sh"
+    ],
+    "scripts": {
+        "start": "node src/index.js",
+        "dev": "node --watch src/index.js"
+    },
+    "keywords": [
+        "ai",
+        "cli",
+        "ollama",
+        "agent",
+        "assistant"
+    ],
+    "author": "Amaan",
+    "license": "MIT",
+    "engines": {
+        "node": ">=22.12.0"
+    },
+    "dependencies": {
+        "boxen": "^8.0.1",
+        "chalk": "^6.0.0",
+        "cheerio": "^1.2.0",
+        "commander": "^15.0.0",
+        "figlet": "^1.11.3",
+        "gradient-string": "^3.0.0",
+        "node-fetch": "^3.3.2",
+        "ollama": "^0.6.3",
+        "ora": "^9.4.1",
+        "systeminformation": "^5.33.1"
+    }
+}

package/src/agent.js

@@ -0,0 +1,226 @@
+/**
+ * Agent Core
+ * Implements the agentic loop with tool calling and streaming
+ */
+
+import { chat, DEFAULT_MODEL } from './ollama.js';
+import { getAllToolSchemas, executeTool } from './registry.js';
+
+/**
+ * Get current date/time for system prompt
+ */
+function getCurrentDateTime() {
+    const now = new Date();
+    return {
+        date: now.toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }),
+        time: now.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: true }),
+        year: now.getFullYear(),
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+    };
+}
+
+/**
+ * Build system prompt with real-time context
+ */
+function buildSystemPrompt() {
+    const dt = getCurrentDateTime();
+    const currentYear = new Date().getFullYear();
+
+    return `You are Scorpion, a helpful AI assistant. Current date: ${dt.date}
+
+CRITICAL RULES:
+1. Your knowledge is outdated (cutoff: mid-2023). For ANY current events, news, sports, or facts about people/companies/products, you MUST use web_search() first.
+2. Search for anything mentioning ${currentYear - 1} or ${currentYear}, or keywords: "latest", "recent", "today", "current"
+3. Answer from memory ONLY for: basic math, greetings, timeless concepts
+
+MANDATORY: When answering sports/news, ALWAYS call web_search() before responding.
+
+---
+
+RESPONSE FORMAT - use this structure for EVERY answer:
+
+## Main Topic
+
+> Key Insight: One sentence summary
+
+Your detailed explanation with **important terms** in bold and \`code\` for technical items.
+
+- Key point 1
+- Key point 2
+- Key point 3
+
+---
+
+### Additional Context (if needed)
+
+More details here.
+
+---
+
+FORMATTING RULES:
+- ## for main sections
+- ### for subsections  
+- **bold** for names, key terms, numbers
+- \`code\` for technical terms
+- > for key insights/summaries
+- Short paragraphs (2-3 sentences)
+- Cite sources clearly
+
+Be concise, organized, and always cite your sources.`;
+}
+
+/**
+ * Run the agent loop
+ * @param {string} userMessage - User's input message
+ * @param {Object} options - Agent options
+ * @param {Array} options.history - Conversation history
+ * @param {Function} options.onThinking - Callback for thinking output
+ * @param {Function} options.onContent - Callback for content output
+ * @param {Function} options.onToolCall - Callback when tool is called
+ * @param {Function} options.onToolResult - Callback with tool result
+ * @param {string} options.model - Model to use
+ * @returns {Object} - Final response and updated history
+ */
+export async function runAgent(userMessage, options = {}) {
+    const {
+        history = [],
+        onThinking = () => { },
+        onContent = () => { },
+        onToolCall = () => { },
+        onToolResult = () => { },
+        model = DEFAULT_MODEL,
+    } = options;
+
+    // Build messages with dynamic system prompt (includes current date/time)
+    const messages = [
+        { role: 'system', content: buildSystemPrompt() },
+        ...history,
+        { role: 'user', content: userMessage }
+    ];
+
+    // Get all available tools
+    const tools = getAllToolSchemas();
+
+    let iterations = 0;
+    const maxIterations = 10; // Safety limit
+
+    while (iterations < maxIterations) {
+        iterations++;
+
+        // Call the model with streaming
+        const stream = await chat({
+            model,
+            messages,
+            tools,
+            think: true,
+            stream: true,
+        });
+
+        // Accumulate the response
+        let thinking = '';
+        let content = '';
+        let toolCalls = [];
+        let inThinking = false;
+
+        for await (const chunk of stream) {
+            // Handle thinking
+            if (chunk.message?.thinking) {
+                if (!inThinking) {
+                    inThinking = true;
+                }
+                thinking += chunk.message.thinking;
+                onThinking(chunk.message.thinking);
+            }
+
+            // Handle content
+            if (chunk.message?.content) {
+                if (inThinking) {
+                    inThinking = false;
+                }
+                content += chunk.message.content;
+                onContent(chunk.message.content);
+            }
+
+            // Handle tool calls
+            if (chunk.message?.tool_calls) {
+                toolCalls = chunk.message.tool_calls;
+            }
+        }
+
+        // Add assistant message to history
+        const assistantMessage = {
+            role: 'assistant',
+            content: content || undefined,
+            thinking: thinking || undefined,
+            tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+        };
+        messages.push(assistantMessage);
+
+        // If there are tool calls, execute them
+        if (toolCalls.length > 0) {
+            for (const call of toolCalls) {
+                const toolName = call.function?.name;
+                const toolArgs = call.function?.arguments || {};
+
+                onToolCall({ name: toolName, args: toolArgs });
+
+                // Execute the tool
+                const result = await executeTool(toolName, toolArgs);
+
+                onToolResult({ name: toolName, result });
+
+                // Add tool result to messages
+                messages.push({
+                    role: 'tool',
+                    tool_name: toolName,
+                    content: result,
+                });
+            }
+            // Continue the loop to let model process tool results
+        } else {
+            // No tool calls - agent is done
+            break;
+        }
+    }
+
+    // Extract final response
+    const finalMessage = messages[messages.length - 1];
+
+    // Update history (exclude system prompt)
+    const newHistory = messages.slice(1);
+
+    return {
+        content: finalMessage.content || '',
+        thinking: finalMessage.thinking,
+        history: newHistory,
+        iterations,
+    };
+}
+
+/**
+ * Run a single query without streaming (simpler interface)
+ * @param {string} query - User query
+ * @param {Array} history - Conversation history
+ * @returns {Promise<Object>} - Response object
+ */
+export async function query(query, history = []) {
+    let fullContent = '';
+    let fullThinking = '';
+    const toolsUsed = [];
+
+    const result = await runAgent(query, {
+        history,
+        onThinking: (text) => { fullThinking += text; },
+        onContent: (text) => { fullContent += text; },
+        onToolCall: (tool) => { toolsUsed.push(tool.name); },
+    });
+
+    return {
+        content: fullContent || result.content,
+        thinking: fullThinking,
+        toolsUsed,
+        history: result.history,
+    };
+}
+
+export { buildSystemPrompt };

package/src/commands.js

@@ -0,0 +1,193 @@
+/**
+ * CLI Commands
+ * Export, stats, and utility commands
+ */
+
+import { saveResearchReport, listReports } from './ui/export.js';
+import { renderTable } from './ui/table.js';
+import { barChart } from './ui/charts.js';
+import { colors } from './ui/formatter.js';
+import { listModels } from './ollama.js';
+
+/**
+ * List models installed in the local Ollama instance.
+ * @param {string} currentModel - Currently selected model
+ * @returns {Promise<Array>} Installed models
+ */
+export async function handleListModels(currentModel) {
+    try {
+        const models = await listModels();
+
+        if (models.length === 0) {
+            console.log(colors.info('  No Ollama models are installed.'));
+            console.log(colors.dim('  Pull one with: ollama pull <model>'));
+            return models;
+        }
+
+        console.log();
+        console.log(colors.bold.white('  Ollama Models'));
+        console.log(colors.dim('  ' + '─'.repeat(50)));
+        renderTable(models.map((model) => ({
+            Model: model.name === currentModel ? `${model.name} *` : model.name,
+            Size: formatBytes(model.size),
+            Modified: model.modified_at ? new Date(model.modified_at).toLocaleString() : '—',
+        })), { compact: true });
+        console.log(colors.dim('  * active model'));
+        console.log();
+        return models;
+    } catch (error) {
+        console.log(colors.error('  Could not list Ollama models.'));
+        console.log(colors.dim('  Make sure Ollama is running: ollama serve'));
+        return [];
+    }
+}
+
+/**
+ * Select an installed Ollama model using the REPL's existing input stream.
+ * @param {string} currentModel - Currently selected model
+ * @param {Function} ask - Function that prompts for one line of input
+ * @param {string} requestedModel - Optional model supplied with `/model <name>`
+ * @returns {Promise<string|null>} Selected model, or null when cancelled/unavailable
+ */
+export async function handleModelSelect(currentModel, ask, requestedModel = '') {
+    let models;
+    try {
+        models = await listModels();
+    } catch (error) {
+        console.log(colors.error('  Could not connect to Ollama.'));
+        console.log(colors.dim('  Make sure Ollama is running: ollama serve'));
+        return null;
+    }
+    if (models.length === 0) {
+        console.log(colors.info('  No Ollama models are installed. Pull one with: ollama pull <model>'));
+        return null;
+    }
+
+    const requested = requestedModel.trim();
+    if (requested) {
+        const exactMatch = models.find((model) => model.name === requested);
+        if (exactMatch) return exactMatch.name;
+        console.log(colors.error(`  Model '${requested}' is not installed. Use /list to see available models.`));
+        return null;
+    }
+
+    console.log();
+    console.log(colors.bold.white('  Select an Ollama Model'));
+    models.forEach((model, index) => {
+        const active = model.name === currentModel ? colors.success(' (active)') : '';
+        console.log(`  ${colors.dim(`${index + 1}.`)} ${model.name}${active}`);
+    });
+    console.log(colors.dim('  Enter a number, model name, or press Enter to cancel.'));
+
+    const answer = (await ask(colors.accent('  Select model: '))).trim();
+    if (!answer) return null;
+
+    const selectedIndex = Number.parseInt(answer, 10);
+    if (Number.isInteger(selectedIndex) && String(selectedIndex) === answer && models[selectedIndex - 1]) {
+        return models[selectedIndex - 1].name;
+    }
+
+    const exactMatch = models.find((model) => model.name === answer);
+    if (exactMatch) return exactMatch.name;
+
+    console.log(colors.error(`  '${answer}' is not a valid installed model.`));
+    return null;
+}
+
+function formatBytes(bytes = 0) {
+    if (!bytes) return '—';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const index = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+    return `${(bytes / (1024 ** index)).toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+}
+
+/**
+ * Handle export command
+ * @param {string} format - Export format (md, json)
+ */
+export async function handleExport(format = 'md') {
+    console.log();
+    console.log(colors.accent('  💾 Export Report'));
+    console.log(colors.dim('  ─'.repeat(30)));
+    console.log();
+    console.log(colors.dim('  Exporting last research report...'));
+    console.log();
+
+    // TODO: Implement export of last report
+    console.log(colors.info('  ℹ Export functionality available via Deep Research'));
+    console.log(colors.dim('  Reports are auto-saved to reports/ directory'));
+    console.log();
+}
+
+/**
+ * Handle list reports command
+ */
+export async function handleListReports() {
+    await listReports();
+}
+
+/**
+ * Handle stats command
+ */
+export async function handleStats() {
+    console.log();
+    console.log(colors.bold.white('  📊 Session Statistics'));
+    console.log(colors.dim('  ─'.repeat(50)));
+    console.log();
+
+    // Example stats (would be tracked in real implementation)
+    const stats = [
+        { label: 'Queries', value: 12 },
+        { label: 'Tool Calls', value: 45 },
+        { label: 'Deep Research', value: 3 },
+        { label: 'Quick Response', value: 9 }
+    ];
+
+    barChart(stats, { maxWidth: 30, color: 'cyan' });
+}
+
+/**
+ * Handle demo command (show all UI features)
+ */
+export async function handleDemo() {
+    console.log();
+    console.log(colors.bold.white('  🎨 UI Feature Demo'));
+    console.log(colors.dim('  ─'.repeat(50)));
+    console.log();
+
+    // Demo table
+    console.log(colors.accent('  📋 Table Example:'));
+    console.log();
+    renderTable([
+        { Feature: 'Deep Research', Status: '✓ Available', Type: 'Core' },
+        { Feature: 'Quick Mode', Status: '✓ Available', Type: 'Core' },
+        { Feature: 'Export', Status: '✓ Available', Type: 'Utility' }
+    ], { compact: true });
+
+    console.log();
+    console.log(colors.accent('  📊 Chart Example:'));
+    console.log();
+    barChart([
+        { label: 'arXiv', value: 85 },
+        { label: 'HN', value: 65 },
+        { label: 'Wikipedia', value: 92 }
+    ], { title: 'Source Reliability (%)', maxWidth: 40 });
+
+    console.log(colors.accent('  💡 Available Commands:'));
+    console.log();
+    console.log(colors.dim('    help') + colors.white(' - Show @ trigger help'));
+    console.log(colors.dim('    stats') + colors.white(' - Show session stats'));
+    console.log(colors.dim('    reports') + colors.white(' - List saved reports'));
+    console.log(colors.dim('    demo') + colors.white(' - Show UI features'));
+    console.log(colors.dim('    clear') + colors.white(' - Clear conversation'));
+    console.log();
+}
+
+export default {
+    handleExport,
+    handleListReports,
+    handleListModels,
+    handleModelSelect,
+    handleStats,
+    handleDemo
+};