@darksol/terminal 0.13.0 → 0.13.1

package/README.md

@@ -57,7 +57,7 @@ darksol bridge status 0xTxHash...
 darksol bridge chains
 
 # Cross-DEX arbitrage
-darksol arb scan --chain base                       # one-shot price comparison
+darksol arb scan --chain base                       # AI-scored DEX price comparison
 darksol arb monitor --chain base --execute          # real-time block-by-block scanning
 darksol arb config                                   # set thresholds, dry-run, DEXes
 darksol arb add-endpoint base wss://your-quicknode   # faster with WSS endpoints
@@ -65,6 +65,12 @@ darksol arb add-pair WETH AERO                       # add pairs to scan
 darksol arb stats --days 7                           # PnL history
 darksol arb info                                     # setup guide + risk warnings
 
+# AI arbitrage intelligence
+darksol arb ai                                       # strategy briefing + recommendations
+darksol arb discover --chain base                    # AI pair discovery
+darksol arb tune --chain base                        # AI threshold optimization
+darksol arb learn --chain base                       # learn from history patterns
+
 # Set up your agent identity
 darksol soul
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -17,6 +17,7 @@ import { executeSwap } from './trading/swap.js';
 import { snipeToken, watchSnipe } from './trading/snipe.js';
 import { createDCA, listDCA, cancelDCA, runDCA } from './trading/dca.js';
 import { arbScan, arbMonitor, arbExecute, arbStats, arbConfig, arbAddEndpoint, arbAddPair, arbRemovePair, arbInfo } from './trading/arb.js';
+import { aiDiscoverPairs, aiTuneThresholds, aiStrategyBriefing, aiLearn } from './trading/arb-ai.js';
 import { executeLifiSwap, executeLifiBridge, checkBridgeStatus, showSupportedChains } from './services/lifi.js';
 import { topMovers, tokenDetail, compareTokens } from './services/market.js';
 import { oracleFlip, oracleDice, oracleNumber, oracleShuffle, oracleHealth } from './services/oracle.js';
@@ -400,6 +401,30 @@ export function cli(argv) {
     .description('How arbitrage works, setup guide, and risk warnings')
     .action(() => arbInfo());
 
+  arb
+    .command('ai')
+    .description('AI strategy briefing — assessment, recommendations, next actions')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiStrategyBriefing({ chain: opts.chain }));
+
+  arb
+    .command('discover')
+    .description('AI-powered pair discovery — find new opportunities, drop dead pairs')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiDiscoverPairs({ chain: opts.chain }));
+
+  arb
+    .command('tune')
+    .description('AI threshold tuning — optimize min profit, trade size, gas ceiling')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiTuneThresholds({ chain: opts.chain }));
+
+  arb
+    .command('learn')
+    .description('Run AI learning cycle — analyze history and update patterns')
+    .option('-c, --chain <chain>', 'Target chain', 'base')
+    .action((opts) => aiLearn({ chain: opts.chain }));
+
   const auto = program
     .command('auto')
     .description('Autonomous trader mode - goal-based automated execution');

package/src/trading/arb-ai.js

@@ -0,0 +1,827 @@
+/**
+ * arb-ai.js — AI-Powered Arbitrage Intelligence
+ *
+ * Layers AI decision-making on top of the mechanical arb scanner.
+ * Uses the configured LLM provider to:
+ *   1. Discover promising pairs to scan
+ *   2. Score opportunities beyond raw math
+ *   3. Tune thresholds dynamically based on history
+ *   4. Learn from past results (what worked, what didn't)
+ *   5. Provide natural-language strategy briefings
+ */
+
+import { LLMEngine } from '../llm/engine.js';
+import { getConfig } from '../config/store.js';
+import { theme } from '../ui/theme.js';
+import { spinner, kvDisplay, success, error, warn, info, card } from '../ui/components.js';
+import { showSection } from '../ui/banner.js';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// ═══════════════════════════════════════════════════════════════
+// PATHS & CONSTANTS
+// ═══════════════════════════════════════════════════════════════
+
+const DARKSOL_DIR = join(homedir(), '.darksol');
+const ARB_HISTORY_PATH = join(DARKSOL_DIR, 'arb-history.json');
+const ARB_LEARNINGS_PATH = join(DARKSOL_DIR, 'arb-learnings.json');
+const ARB_AI_LOG_PATH = join(DARKSOL_DIR, 'arb-ai-log.json');
+
+function ensureDir() {
+  if (!existsSync(DARKSOL_DIR)) mkdirSync(DARKSOL_DIR, { recursive: true });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// LEARNING STORE — persistent cross-session intelligence
+// ═══════════════════════════════════════════════════════════════
+
+function loadLearnings() {
+  ensureDir();
+  if (!existsSync(ARB_LEARNINGS_PATH)) return getDefaultLearnings();
+  try {
+    return JSON.parse(readFileSync(ARB_LEARNINGS_PATH, 'utf-8'));
+  } catch {
+    return getDefaultLearnings();
+  }
+}
+
+function saveLearnings(learnings) {
+  ensureDir();
+  writeFileSync(ARB_LEARNINGS_PATH, JSON.stringify(learnings, null, 2));
+}
+
+function getDefaultLearnings() {
+  return {
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    // Which pairs have historically produced profitable opportunities
+    profitablePairs: [],
+    // Which pairs consistently waste gas with no real spread
+    deadPairs: [],
+    // Best performing DEX combos (e.g. "uniswapV3→aerodrome on base")
+    bestDexCombos: [],
+    // Time-of-day patterns (hour → avg opportunity count)
+    hourlyPatterns: {},
+    // Chain performance ranking
+    chainRanking: [],
+    // Threshold recommendations from AI analysis
+    recommendedThresholds: {
+      minProfitUsd: 0.50,
+      maxTradeSize: 1.0,
+      gasCeiling: 0.01,
+    },
+    // AI-generated strategy notes (natural language)
+    strategyNotes: [],
+    // Total sessions analyzed
+    sessionsAnalyzed: 0,
+  };
+}
+
+function loadHistory() {
+  if (!existsSync(ARB_HISTORY_PATH)) return [];
+  try {
+    return JSON.parse(readFileSync(ARB_HISTORY_PATH, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+function logAiAction(action) {
+  ensureDir();
+  let log = [];
+  if (existsSync(ARB_AI_LOG_PATH)) {
+    try { log = JSON.parse(readFileSync(ARB_AI_LOG_PATH, 'utf-8')); } catch {}
+  }
+  log.push({ ts: new Date().toISOString(), ...action });
+  if (log.length > 500) log.splice(0, log.length - 500);
+  writeFileSync(ARB_AI_LOG_PATH, JSON.stringify(log, null, 2));
+}
+
+// ═══════════════════════════════════════════════════════════════
+// LLM INITIALIZATION
+// ═══════════════════════════════════════════════════════════════
+
+async function getEngine() {
+  const engine = new LLMEngine({
+    temperature: 0.3, // low temp for analytical work
+  });
+  await engine.init();
+  return engine;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SYSTEM PROMPTS
+// ═══════════════════════════════════════════════════════════════
+
+const ARB_AI_SYSTEM = `You are DARKSOL Terminal's arbitrage intelligence engine. You analyze cross-DEX arbitrage data and provide actionable insights.
+
+You have access to:
+- Historical arb scan results (opportunities found, spreads, gas costs, net profit/loss)
+- Learning data (which pairs/DEXs/times perform best)
+- Current market conditions
+
+Your job is to:
+1. Identify patterns in arb performance data
+2. Recommend which pairs to focus on and which to drop
+3. Suggest optimal thresholds (min profit, trade size, gas ceiling)
+4. Score individual opportunities beyond raw math (consider liquidity depth, token risk, MEV likelihood)
+5. Provide clear, actionable strategy briefings
+
+IMPORTANT CONSTRAINTS:
+- Be honest about limitations — DEX arb is competitive and most simple arb is front-run
+- Never hallucinate token addresses or contract details
+- Base recommendations on actual data, not speculation
+- Always factor in gas costs and MEV risk
+- Flag honeypot tokens or suspicious liquidity patterns
+
+RESPONSE FORMAT:
+Always respond with valid JSON. No markdown, no prose outside the JSON structure.`;
+
+// ═══════════════════════════════════════════════════════════════
+// AI PAIR DISCOVERY
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Use AI to analyze history and suggest new pairs to scan.
+ * Also identifies dead pairs that waste gas.
+ */
+export async function aiDiscoverPairs(opts = {}) {
+  showSection('AI PAIR DISCOVERY');
+
+  const spin = spinner('Analyzing arb history for patterns...').start();
+
+  try {
+    const history = loadHistory();
+    const learnings = loadLearnings();
+    const chain = opts.chain || getConfig('chain') || 'base';
+
+    if (history.length < 5) {
+      spin.fail('Not enough history');
+      info('Run at least 5 arb scans first: darksol arb scan');
+      info('The AI needs data to find patterns.');
+      return null;
+    }
+
+    // Summarize history for the LLM (don't send raw data — too large)
+    const summary = summarizeHistory(history, chain);
+
+    const engine = await getEngine();
+    engine.setSystemPrompt(ARB_AI_SYSTEM);
+
+    const prompt = `Analyze this arb scan history summary and recommend pair strategy.
+
+CHAIN: ${chain}
+HISTORY SUMMARY:
+${JSON.stringify(summary, null, 2)}
+
+CURRENT LEARNINGS:
+${JSON.stringify({
+  profitablePairs: learnings.profitablePairs.slice(0, 10),
+  deadPairs: learnings.deadPairs.slice(0, 10),
+  bestDexCombos: learnings.bestDexCombos.slice(0, 5),
+}, null, 2)}
+
+Respond with JSON:
+{
+  "addPairs": [{"tokenA": "SYMBOL", "tokenB": "SYMBOL", "reason": "why this pair"}],
+  "removePairs": [{"tokenA": "SYMBOL", "tokenB": "SYMBOL", "reason": "why drop it"}],
+  "focusPairs": [{"tokenA": "SYMBOL", "tokenB": "SYMBOL", "priority": 1-5, "reason": "why focus"}],
+  "insights": ["insight 1", "insight 2"],
+  "confidence": 0.0-1.0
+}`;
+
+    spin.text = 'AI analyzing patterns...';
+    const response = await engine.chat(prompt, { skipContext: true });
+
+    let analysis;
+    try {
+      // Extract JSON from response (handle markdown wrapping)
+      const jsonStr = response.replace(/```json?\n?/g, '').replace(/```/g, '').trim();
+      analysis = JSON.parse(jsonStr);
+    } catch {
+      spin.fail('AI returned invalid JSON');
+      error('Could not parse AI response. Try again.');
+      return null;
+    }
+
+    spin.succeed('AI analysis complete');
+    console.log('');
+
+    // Display results
+    if (analysis.addPairs?.length > 0) {
+      console.log(theme.gold('  📈 Suggested New Pairs:'));
+      for (const p of analysis.addPairs) {
+        console.log(`    ${theme.success('+')} ${theme.bright(p.tokenA + '/' + p.tokenB)} — ${theme.dim(p.reason)}`);
+      }
+      console.log('');
+    }
+
+    if (analysis.removePairs?.length > 0) {
+      console.log(theme.gold('  📉 Suggested Removals:'));
+      for (const p of analysis.removePairs) {
+        console.log(`    ${theme.error('−')} ${theme.bright(p.tokenA + '/' + p.tokenB)} — ${theme.dim(p.reason)}`);
+      }
+      console.log('');
+    }
+
+    if (analysis.focusPairs?.length > 0) {
+      console.log(theme.gold('  🎯 Focus Priority:'));
+      for (const p of analysis.focusPairs) {
+        const stars = '★'.repeat(p.priority) + '☆'.repeat(5 - p.priority);
+        console.log(`    ${theme.gold(stars)} ${theme.bright(p.tokenA + '/' + p.tokenB)} — ${theme.dim(p.reason)}`);
+      }
+      console.log('');
+    }
+
+    if (analysis.insights?.length > 0) {
+      console.log(theme.gold('  💡 Insights:'));
+      for (const insight of analysis.insights) {
+        console.log(`    ${theme.dim('•')} ${insight}`);
+      }
+      console.log('');
+    }
+
+    console.log(theme.dim(`  AI confidence: ${((analysis.confidence || 0) * 100).toFixed(0)}%`));
+    console.log('');
+
+    // Update learnings
+    if (analysis.focusPairs) {
+      learnings.profitablePairs = analysis.focusPairs.map(p => `${p.tokenA}/${p.tokenB}`);
+    }
+    if (analysis.removePairs) {
+      learnings.deadPairs = [
+        ...new Set([...learnings.deadPairs, ...analysis.removePairs.map(p => `${p.tokenA}/${p.tokenB}`)]),
+      ].slice(0, 50);
+    }
+    learnings.updatedAt = new Date().toISOString();
+    learnings.sessionsAnalyzed++;
+    saveLearnings(learnings);
+
+    logAiAction({ type: 'discover_pairs', chain, result: analysis });
+
+    return analysis;
+
+  } catch (err) {
+    spin.fail('AI analysis failed');
+    error(err.message);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI OPPORTUNITY SCORING
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Score an array of raw arb opportunities using AI.
+ * Adds risk assessment, MEV likelihood, and go/no-go recommendation.
+ */
+export async function aiScoreOpportunities(opportunities, opts = {}) {
+  if (!opportunities || opportunities.length === 0) return [];
+
+  const engine = await getEngine();
+  engine.setSystemPrompt(ARB_AI_SYSTEM);
+
+  const learnings = loadLearnings();
+
+  // Only send top opportunities to save tokens
+  const top = opportunities
+    .sort((a, b) => b.netProfitUsd - a.netProfitUsd)
+    .slice(0, 10);
+
+  const oppData = top.map(o => ({
+    pair: o.pair,
+    buyDex: o.buyDexName,
+    sellDex: o.sellDexName,
+    spread: o.spread,
+    netProfitUsd: o.netProfitUsd,
+    gasCostUsd: o.gasCostUsd,
+    chain: o.chain,
+    amountInEth: o.amountInEth,
+  }));
+
+  const prompt = `Score these arb opportunities. Consider MEV risk, liquidity depth, token legitimacy, and historical patterns.
+
+OPPORTUNITIES:
+${JSON.stringify(oppData, null, 2)}
+
+LEARNED PATTERNS:
+- Profitable pairs: ${learnings.profitablePairs.join(', ') || 'none yet'}
+- Dead pairs: ${learnings.deadPairs.join(', ') || 'none yet'}
+- Best DEX combos: ${learnings.bestDexCombos.join(', ') || 'none yet'}
+
+Respond with JSON:
+{
+  "scored": [
+    {
+      "pair": "TOKEN/TOKEN",
+      "riskScore": 1-10,
+      "mevLikelihood": "low|medium|high",
+      "recommendation": "execute|skip|watch",
+      "reason": "why",
+      "adjustedProfitUsd": 0.00
+    }
+  ],
+  "summary": "one-line overall assessment"
+}`;
+
+  try {
+    const response = await engine.chat(prompt, { skipContext: true });
+    const jsonStr = response.replace(/```json?\n?/g, '').replace(/```/g, '').trim();
+    const scoring = JSON.parse(jsonStr);
+
+    logAiAction({ type: 'score', count: top.length, result: scoring });
+    return scoring;
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI THRESHOLD TUNING
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Analyze history and recommend optimal thresholds.
+ */
+export async function aiTuneThresholds(opts = {}) {
+  showSection('AI THRESHOLD TUNING');
+
+  const spin = spinner('Analyzing performance data...').start();
+
+  try {
+    const history = loadHistory();
+    const learnings = loadLearnings();
+    const chain = opts.chain || getConfig('chain') || 'base';
+
+    if (history.length < 10) {
+      spin.fail('Need more data');
+      info('Run at least 10 arb scans before tuning. Current: ' + history.length);
+      return null;
+    }
+
+    const summary = summarizeHistory(history, chain);
+    const engine = await getEngine();
+    engine.setSystemPrompt(ARB_AI_SYSTEM);
+
+    const prompt = `Analyze this arb performance data and recommend optimal thresholds.
+
+CHAIN: ${chain}
+PERFORMANCE SUMMARY:
+${JSON.stringify(summary, null, 2)}
+
+CURRENT THRESHOLDS:
+${JSON.stringify(learnings.recommendedThresholds, null, 2)}
+
+Consider:
+- What minimum profit threshold filters noise without missing real opportunities?
+- What trade size balances risk vs reward?
+- What gas ceiling is appropriate for ${chain}?
+- What cooldown prevents overtrading?
+
+Respond with JSON:
+{
+  "recommended": {
+    "minProfitUsd": 0.00,
+    "maxTradeSize": 0.00,
+    "gasCeiling": 0.00,
+    "cooldownMs": 0
+  },
+  "changes": [
+    {"field": "minProfitUsd", "from": 0.00, "to": 0.00, "reason": "why"}
+  ],
+  "reasoning": "overall explanation",
+  "confidence": 0.0-1.0
+}`;
+
+    spin.text = 'AI evaluating thresholds...';
+    const response = await engine.chat(prompt, { skipContext: true });
+
+    let tuning;
+    try {
+      const jsonStr = response.replace(/```json?\n?/g, '').replace(/```/g, '').trim();
+      tuning = JSON.parse(jsonStr);
+    } catch {
+      spin.fail('AI returned invalid response');
+      return null;
+    }
+
+    spin.succeed('Threshold analysis complete');
+    console.log('');
+
+    // Display recommendations
+    if (tuning.changes?.length > 0) {
+      console.log(theme.gold('  🔧 Recommended Changes:'));
+      for (const c of tuning.changes) {
+        const arrow = c.to > c.from ? theme.success('↑') : theme.error('↓');
+        console.log(`    ${arrow} ${theme.bright(c.field)}: ${c.from} → ${theme.gold(String(c.to))}`);
+        console.log(`      ${theme.dim(c.reason)}`);
+      }
+      console.log('');
+    }
+
+    if (tuning.reasoning) {
+      console.log(theme.gold('  📝 Reasoning:'));
+      console.log(`    ${theme.dim(tuning.reasoning)}`);
+      console.log('');
+    }
+
+    console.log(theme.dim(`  AI confidence: ${((tuning.confidence || 0) * 100).toFixed(0)}%`));
+    console.log('');
+
+    // Save recommended thresholds to learnings
+    if (tuning.recommended) {
+      learnings.recommendedThresholds = tuning.recommended;
+      learnings.updatedAt = new Date().toISOString();
+      saveLearnings(learnings);
+    }
+
+    logAiAction({ type: 'tune_thresholds', chain, result: tuning });
+
+    return tuning;
+
+  } catch (err) {
+    spin.fail('Threshold analysis failed');
+    error(err.message);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI STRATEGY BRIEFING
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Generate a natural-language strategy briefing based on all available data.
+ */
+export async function aiStrategyBriefing(opts = {}) {
+  showSection('AI STRATEGY BRIEFING');
+
+  const spin = spinner('Generating strategy briefing...').start();
+
+  try {
+    const history = loadHistory();
+    const learnings = loadLearnings();
+    const chain = opts.chain || getConfig('chain') || 'base';
+    const summary = summarizeHistory(history, chain);
+
+    const engine = await getEngine();
+    engine.setSystemPrompt(ARB_AI_SYSTEM);
+
+    const prompt = `Generate a strategy briefing for DEX arbitrage on ${chain}.
+
+PERFORMANCE DATA:
+${JSON.stringify(summary, null, 2)}
+
+LEARNED PATTERNS:
+${JSON.stringify({
+  profitablePairs: learnings.profitablePairs,
+  deadPairs: learnings.deadPairs,
+  bestDexCombos: learnings.bestDexCombos,
+  hourlyPatterns: learnings.hourlyPatterns,
+  chainRanking: learnings.chainRanking,
+  recommendedThresholds: learnings.recommendedThresholds,
+  sessionsAnalyzed: learnings.sessionsAnalyzed,
+  strategyNotes: learnings.strategyNotes.slice(-5),
+}, null, 2)}
+
+Write a concise strategy briefing. Include:
+1. Current state assessment (how are we doing?)
+2. Top recommendations (what should we change?)
+3. Risk warnings (what could go wrong?)
+4. Next actions (what should the user do right now?)
+
+Respond with JSON:
+{
+  "assessment": "current state in 1-2 sentences",
+  "performance": {"totalScans": 0, "profitableOpps": 0, "executedTrades": 0, "estimatedPnl": 0},
+  "recommendations": ["rec 1", "rec 2", "rec 3"],
+  "risks": ["risk 1", "risk 2"],
+  "nextActions": ["action 1", "action 2"],
+  "confidence": 0.0-1.0
+}`;
+
+    spin.text = 'AI drafting briefing...';
+    const response = await engine.chat(prompt, { skipContext: true });
+
+    let briefing;
+    try {
+      const jsonStr = response.replace(/```json?\n?/g, '').replace(/```/g, '').trim();
+      briefing = JSON.parse(jsonStr);
+    } catch {
+      spin.fail('AI returned invalid response');
+      return null;
+    }
+
+    spin.succeed('Briefing ready');
+    console.log('');
+
+    // Display briefing
+    console.log(theme.gold('  📋 Assessment:'));
+    console.log(`    ${briefing.assessment}`);
+    console.log('');
+
+    if (briefing.performance) {
+      kvDisplay([
+        ['Scans',           String(briefing.performance.totalScans || 0)],
+        ['Profitable Opps', String(briefing.performance.profitableOpps || 0)],
+        ['Executed',        String(briefing.performance.executedTrades || 0)],
+        ['Est. PnL',        `$${(briefing.performance.estimatedPnl || 0).toFixed(4)}`],
+      ], { title: 'Performance' });
+      console.log('');
+    }
+
+    if (briefing.recommendations?.length > 0) {
+      console.log(theme.gold('  💡 Recommendations:'));
+      briefing.recommendations.forEach((r, i) => {
+        console.log(`    ${theme.gold(String(i + 1) + '.')} ${r}`);
+      });
+      console.log('');
+    }
+
+    if (briefing.risks?.length > 0) {
+      console.log(theme.warning('  ⚠ Risks:'));
+      briefing.risks.forEach(r => {
+        console.log(`    ${theme.error('•')} ${r}`);
+      });
+      console.log('');
+    }
+
+    if (briefing.nextActions?.length > 0) {
+      console.log(theme.success('  ▶ Next Actions:'));
+      briefing.nextActions.forEach(a => {
+        console.log(`    ${theme.info('→')} ${a}`);
+      });
+      console.log('');
+    }
+
+    // Save briefing to learnings
+    learnings.strategyNotes.push({
+      ts: new Date().toISOString(),
+      chain,
+      assessment: briefing.assessment,
+      recommendations: briefing.recommendations,
+    });
+    // Keep last 20 briefings
+    if (learnings.strategyNotes.length > 20) {
+      learnings.strategyNotes = learnings.strategyNotes.slice(-20);
+    }
+    learnings.updatedAt = new Date().toISOString();
+    saveLearnings(learnings);
+
+    logAiAction({ type: 'briefing', chain, result: briefing });
+
+    return briefing;
+
+  } catch (err) {
+    spin.fail('Briefing failed');
+    error(err.message);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI LEARN — analyze history and update patterns
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Run a learning cycle — analyze recent history and update persistent learnings.
+ * Should be run periodically (after a batch of scans or daily).
+ */
+export async function aiLearn(opts = {}) {
+  showSection('AI LEARNING CYCLE');
+
+  const spin = spinner('Analyzing recent arb data...').start();
+
+  try {
+    const history = loadHistory();
+    const learnings = loadLearnings();
+    const chain = opts.chain || getConfig('chain') || 'base';
+
+    if (history.length < 3) {
+      spin.fail('Not enough data to learn from');
+      info('Run more scans first.');
+      return null;
+    }
+
+    // Extract patterns from raw data (no LLM needed for this)
+    const chainHistory = history.filter(h => h.chain === chain);
+
+    // Hourly pattern analysis
+    const hourBuckets = {};
+    for (const h of chainHistory) {
+      const hour = new Date(h.ts).getHours();
+      if (!hourBuckets[hour]) hourBuckets[hour] = { count: 0, profitable: 0 };
+      hourBuckets[hour].count++;
+      if (h.netProfitUsd > 0) hourBuckets[hour].profitable++;
+    }
+    learnings.hourlyPatterns = hourBuckets;
+
+    // Best DEX combos
+    const comboCounts = {};
+    for (const h of chainHistory.filter(h => h.netProfitUsd > 0)) {
+      const combo = `${h.buyDex}→${h.sellDex}`;
+      comboCounts[combo] = (comboCounts[combo] || 0) + 1;
+    }
+    learnings.bestDexCombos = Object.entries(comboCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([combo, count]) => `${combo} (${count}x)`);
+
+    // Pair profitability
+    const pairProfits = {};
+    for (const h of chainHistory) {
+      const pair = h.pair;
+      if (!pair) continue;
+      if (!pairProfits[pair]) pairProfits[pair] = { total: 0, profitable: 0, totalProfit: 0 };
+      pairProfits[pair].total++;
+      if (h.netProfitUsd > 0) {
+        pairProfits[pair].profitable++;
+        pairProfits[pair].totalProfit += h.netProfitUsd;
+      }
+    }
+
+    learnings.profitablePairs = Object.entries(pairProfits)
+      .filter(([, data]) => data.profitable / data.total > 0.1) // >10% success rate
+      .sort((a, b) => b[1].totalProfit - a[1].totalProfit)
+      .slice(0, 20)
+      .map(([pair]) => pair);
+
+    learnings.deadPairs = Object.entries(pairProfits)
+      .filter(([, data]) => data.total >= 5 && data.profitable === 0) // 5+ scans, never profitable
+      .map(([pair]) => pair);
+
+    // Chain ranking
+    const chainCounts = {};
+    for (const h of history.filter(h => h.netProfitUsd > 0)) {
+      chainCounts[h.chain] = (chainCounts[h.chain] || 0) + 1;
+    }
+    learnings.chainRanking = Object.entries(chainCounts)
+      .sort((a, b) => b[1] - a[1])
+      .map(([c, count]) => `${c} (${count} opps)`);
+
+    learnings.updatedAt = new Date().toISOString();
+    learnings.sessionsAnalyzed++;
+    saveLearnings(learnings);
+
+    spin.succeed('Learning cycle complete');
+    console.log('');
+
+    // Display what was learned
+    kvDisplay([
+      ['Data Points',     chainHistory.length.toString()],
+      ['Profitable Pairs', learnings.profitablePairs.length.toString()],
+      ['Dead Pairs',       learnings.deadPairs.length.toString()],
+      ['Best DEX Combos',  learnings.bestDexCombos.slice(0, 3).join(', ') || 'none yet'],
+      ['Chain Ranking',    learnings.chainRanking.join(', ') || 'none yet'],
+      ['Sessions',         learnings.sessionsAnalyzed.toString()],
+    ], { title: 'Learned Patterns' });
+    console.log('');
+
+    // Show hourly heatmap
+    if (Object.keys(hourBuckets).length > 0) {
+      console.log(theme.gold('  🕐 Hourly Opportunity Heatmap:'));
+      const maxCount = Math.max(...Object.values(hourBuckets).map(b => b.profitable));
+      for (let h = 0; h < 24; h++) {
+        const bucket = hourBuckets[h] || { count: 0, profitable: 0 };
+        const bar = maxCount > 0 ? '█'.repeat(Math.ceil((bucket.profitable / maxCount) * 20)) : '';
+        const hour = String(h).padStart(2, '0') + ':00';
+        const color = bucket.profitable > 0 ? theme.success : theme.dim;
+        console.log(`    ${theme.dim(hour)} ${color(bar)} ${theme.dim(String(bucket.profitable) + '/' + String(bucket.count))}`);
+      }
+      console.log('');
+    }
+
+    logAiAction({ type: 'learn', chain, patternsFound: learnings.profitablePairs.length });
+
+    return learnings;
+
+  } catch (err) {
+    spin.fail('Learning cycle failed');
+    error(err.message);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI-ENHANCED MONITOR FILTER
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Quick AI filter for the monitor loop.
+ * Uses learnings (no LLM call) to filter opportunities in real-time.
+ * This is the fast path — no API calls, pure pattern matching.
+ */
+export function aiFilterOpportunity(opportunity) {
+  const learnings = loadLearnings();
+
+  let score = 50; // base score out of 100
+
+  // Boost if pair is in profitable list
+  if (learnings.profitablePairs.includes(opportunity.pair)) {
+    score += 20;
+  }
+
+  // Penalize if pair is in dead list
+  if (learnings.deadPairs.includes(opportunity.pair)) {
+    score -= 40;
+  }
+
+  // Boost if DEX combo is known good
+  const combo = `${opportunity.buyDex}→${opportunity.sellDex}`;
+  if (learnings.bestDexCombos.some(c => c.startsWith(combo))) {
+    score += 15;
+  }
+
+  // Time-of-day boost
+  const currentHour = new Date().getHours();
+  const hourData = learnings.hourlyPatterns[currentHour];
+  if (hourData && hourData.profitable > 0) {
+    score += Math.min(10, hourData.profitable * 2);
+  }
+
+  // Apply learned thresholds
+  const thresholds = learnings.recommendedThresholds;
+  if (thresholds.minProfitUsd && opportunity.netProfitUsd < thresholds.minProfitUsd) {
+    score -= 20;
+  }
+
+  // Clamp score
+  score = Math.max(0, Math.min(100, score));
+
+  return {
+    score,
+    pass: score >= 40,
+    reason: score >= 70 ? 'strong pattern match'
+          : score >= 40 ? 'acceptable'
+          : 'below AI threshold',
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// HISTORY SUMMARIZER (for LLM context)
+// ═══════════════════════════════════════════════════════════════
+
+function summarizeHistory(history, chain) {
+  const chainHistory = history.filter(h => h.chain === chain);
+  const last7d = chainHistory.filter(h => Date.now() - new Date(h.ts).getTime() < 7 * 86400 * 1000);
+
+  // Pair frequency
+  const pairCounts = {};
+  const pairProfits = {};
+  for (const h of last7d) {
+    const pair = h.pair || 'unknown';
+    pairCounts[pair] = (pairCounts[pair] || 0) + 1;
+    if (!pairProfits[pair]) pairProfits[pair] = { sum: 0, count: 0 };
+    pairProfits[pair].sum += (h.netProfitUsd || 0);
+    pairProfits[pair].count++;
+  }
+
+  // DEX frequency
+  const dexCounts = {};
+  for (const h of last7d) {
+    if (h.buyDex) dexCounts[h.buyDex] = (dexCounts[h.buyDex] || 0) + 1;
+    if (h.sellDex) dexCounts[h.sellDex] = (dexCounts[h.sellDex] || 0) + 1;
+  }
+
+  // Spread statistics
+  const spreads = last7d.map(h => h.spread || 0).filter(s => s > 0);
+  const avgSpread = spreads.length > 0 ? spreads.reduce((a, b) => a + b, 0) / spreads.length : 0;
+  const maxSpread = Math.max(0, ...spreads);
+
+  // Profit statistics
+  const profits = last7d.map(h => h.netProfitUsd || 0);
+  const totalProfit = profits.reduce((a, b) => a + b, 0);
+  const profitableCount = profits.filter(p => p > 0).length;
+
+  // Gas statistics
+  const gasCosts = last7d.map(h => h.gasCostUsd || 0);
+  const avgGas = gasCosts.length > 0 ? gasCosts.reduce((a, b) => a + b, 0) / gasCosts.length : 0;
+
+  return {
+    chain,
+    totalEntries: chainHistory.length,
+    last7dEntries: last7d.length,
+    pairBreakdown: Object.entries(pairCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([pair, count]) => ({
+        pair,
+        count,
+        avgProfit: pairProfits[pair] ? (pairProfits[pair].sum / pairProfits[pair].count).toFixed(4) : '0',
+      })),
+    dexUsage: dexCounts,
+    avgSpread: avgSpread.toFixed(4),
+    maxSpread: maxSpread.toFixed(4),
+    totalProfitUsd: totalProfit.toFixed(4),
+    profitableOppCount: profitableCount,
+    avgGasCostUsd: avgGas.toFixed(4),
+    types: {
+      scans: last7d.filter(h => h.type === 'scan').length,
+      executed: last7d.filter(h => h.type === 'executed').length,
+      dryRuns: last7d.filter(h => h.type === 'dry_run').length,
+      errors: last7d.filter(h => h.type === 'error').length,
+    },
+  };
+}

package/src/trading/arb.js

@@ -22,6 +22,7 @@ import { spinner, kvDisplay, success, error, warn, info, table } from '../ui/com
 import { showSection } from '../ui/banner.js';
 import { resolveToken, getTokenInfo } from './swap.js';
 import { getDexesForChain, DEX_ADAPTERS } from './arb-dexes.js';
+import { aiFilterOpportunity, aiScoreOpportunities } from './arb-ai.js';
 
 // ═══════════════════════════════════════════════════════════════
 // CONSTANTS & PATHS
@@ -346,21 +347,63 @@ export async function arbScan(opts = {}) {
     console.log('');
 
     const profitable = allOpps.filter(o => o.netProfitUsd >= minProfit);
-    displayOpportunities(profitable);
+
+    // Apply AI pattern filter (fast, no API call)
+    const aiFiltered = profitable.map(o => {
+      const aiResult = aiFilterOpportunity(o);
+      return { ...o, aiScore: aiResult.score, aiPass: aiResult.pass, aiReason: aiResult.reason };
+    });
+    const aiPassed = aiFiltered.filter(o => o.aiPass);
+    const aiSkipped = aiFiltered.length - aiPassed.length;
+
+    displayOpportunities(aiPassed);
+
+    if (aiSkipped > 0) {
+      info(`AI filter skipped ${aiSkipped} low-confidence opportunity(s) — run 'darksol arb learn' to improve accuracy`);
+      console.log('');
+    }
+
+    // AI deep scoring for top opportunities (uses LLM)
+    if (aiPassed.length > 0 && !opts.skipAi) {
+      const scoreSpin = spinner('AI scoring opportunities...').start();
+      try {
+        const scoring = await aiScoreOpportunities(aiPassed);
+        if (scoring?.scored?.length > 0) {
+          scoreSpin.succeed('AI risk scoring complete');
+          console.log('');
+          console.log(theme.gold('  🧠 AI Risk Assessment:'));
+          for (const s of scoring.scored) {
+            const riskColor = s.riskScore <= 3 ? theme.success : s.riskScore <= 6 ? theme.warning : theme.error;
+            const recColor = s.recommendation === 'execute' ? theme.success : s.recommendation === 'watch' ? theme.warning : theme.error;
+            console.log(`    ${theme.bright(s.pair)} — risk: ${riskColor(String(s.riskScore) + '/10')} | MEV: ${theme.dim(s.mevLikelihood)} | ${recColor(s.recommendation.toUpperCase())}`);
+            console.log(`      ${theme.dim(s.reason)}`);
+          }
+          if (scoring.summary) {
+            console.log('');
+            console.log(`    ${theme.dim('Summary: ' + scoring.summary)}`);
+          }
+          console.log('');
+        } else {
+          scoreSpin.succeed('AI scoring returned no results');
+        }
+      } catch {
+        scoreSpin.warn('AI scoring unavailable — showing raw results');
+      }
+    }
 
     // Log everything (including unprofitable) to history
     for (const o of allOpps) {
       recordArb({ type: 'scan', ...o });
     }
 
-    if (profitable.length > 0) {
+    if (aiPassed.length > 0) {
       console.log('');
       console.log(theme.warning('  ⚠ MEV Warning: ') + theme.dim('simple two-tx arb is likely to be front-run.'));
       console.log(theme.dim('  Use WSS endpoints + Flashbots bundles for reliable execution.'));
       console.log('');
     }
 
-    return profitable;
+    return aiPassed;
   } catch (err) {
     spin.fail('Scan failed');
     error(err.message);
@@ -427,15 +470,20 @@ export async function arbMonitor(opts = {}) {
       }
 
       const profitable = allOpps.filter(o => o.netProfitUsd >= minProfit);
-      oppsFound += profitable.length;
 
-      if (profitable.length > 0) {
-        blockSpin.succeed(`[Block ${blockNumber}] ${profitable.length} opportunity(s) found`);
-        displayOpportunities(profitable.slice(0, 5));
+      // AI pattern filter (fast, no API call)
+      const aiPassed = profitable.filter(o => aiFilterOpportunity(o).pass);
+      oppsFound += aiPassed.length;
+
+      if (aiPassed.length > 0) {
+        const skipped = profitable.length - aiPassed.length;
+        const skipNote = skipped > 0 ? ` (${skipped} AI-filtered)` : '';
+        blockSpin.succeed(`[Block ${blockNumber}] ${aiPassed.length} opportunity(s) found${skipNote}`);
+        displayOpportunities(aiPassed.slice(0, 5));
 
         // Auto-execute if requested and cooldown satisfied
         if (execute && !dryRun && Date.now() - lastExecute > (arbCfg.cooldownMs || 5000)) {
-          const best = profitable.sort((a, b) => b.netProfitUsd - a.netProfitUsd)[0];
+          const best = aiPassed.sort((a, b) => b.netProfitUsd - a.netProfitUsd)[0];
           if (best.netProfitUsd >= minProfit) {
             await arbExecute({ opportunity: best, dryRun: false, skipConfirm: true });
             lastExecute = Date.now();
@@ -443,7 +491,7 @@ export async function arbMonitor(opts = {}) {
           }
         }
       } else {
-        blockSpin.text = `[Block ${blockNumber}] No profitable arb found (${allOpps.length} pairs scanned)`;
+        blockSpin.text = `[Block ${blockNumber}] No profitable arb found (${allOpps.length} scanned, ${profitable.length} pre-filter)`;
         blockSpin.succeed();
       }
 

package/src/web/commands.js

@@ -1390,14 +1390,58 @@ async function cmdArb(args, ws) {
     return {};
   }
 
+  if (sub === 'ai') {
+    try {
+      const { aiStrategyBriefing } = await import('../trading/arb-ai.js');
+      await aiStrategyBriefing({ chain: args[1] || getConfig('chain') || 'base' });
+    } catch (e) {
+      ws.sendLine(`  ${ANSI.red}AI briefing failed: ${e.message}${ANSI.reset}`);
+    }
+    return {};
+  }
+
+  if (sub === 'discover') {
+    try {
+      const { aiDiscoverPairs } = await import('../trading/arb-ai.js');
+      await aiDiscoverPairs({ chain: args[1] || getConfig('chain') || 'base' });
+    } catch (e) {
+      ws.sendLine(`  ${ANSI.red}Discovery failed: ${e.message}${ANSI.reset}`);
+    }
+    return {};
+  }
+
+  if (sub === 'tune') {
+    try {
+      const { aiTuneThresholds } = await import('../trading/arb-ai.js');
+      await aiTuneThresholds({ chain: args[1] || getConfig('chain') || 'base' });
+    } catch (e) {
+      ws.sendLine(`  ${ANSI.red}Tuning failed: ${e.message}${ANSI.reset}`);
+    }
+    return {};
+  }
+
+  if (sub === 'learn') {
+    try {
+      const { aiLearn } = await import('../trading/arb-ai.js');
+      await aiLearn({ chain: args[1] || getConfig('chain') || 'base' });
+    } catch (e) {
+      ws.sendLine(`  ${ANSI.red}Learning failed: ${e.message}${ANSI.reset}`);
+    }
+    return {};
+  }
+
   // Default: show arb menu
   ws.sendLine(`${ANSI.gold}  ◆ ARBITRAGE${ANSI.reset}`);
   ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
-  ws.sendLine(`  ${ANSI.white}Cross-DEX arbitrage scanner${ANSI.reset}`);
+  ws.sendLine(`  ${ANSI.white}AI-powered cross-DEX arbitrage${ANSI.reset}`);
   ws.sendLine('');
 
   ws.sendMenu('arb_action', '◆ Arb Actions', [
-    { value: 'arb scan', label: '🔍 Scan', desc: 'One-shot DEX price comparison' },
+    { value: 'arb scan', label: '🔍 Scan', desc: 'AI-scored DEX price comparison' },
+    { value: 'arb ai', label: '🧠 AI Briefing', desc: 'Strategy assessment + recommendations' },
+    { value: 'arb discover', label: '📈 Discover', desc: 'AI pair discovery — find new opportunities' },
+    { value: 'arb tune', label: '🔧 Tune', desc: 'AI threshold optimization' },
+    { value: 'arb learn', label: '📚 Learn', desc: 'Run learning cycle on history' },
     { value: 'arb stats', label: '📊 Stats', desc: 'View arb history & PnL' },
     { value: 'arb info', label: '📖 Guide', desc: 'How arb works, setup tips, risks' },
     { value: 'back', label: '← Back', desc: '' },