222 feat enhance ai analyzer providers power user prompt versioning and swapping

[MatiasOS]

Description

Enhance the AI Analyzer with new provider support (Perplexity and Gemini), a prompt versioning system with power/regular user modes, and improved contract analysis context with smarter ABI summarization.

Related Issue

Closes #222

Type of Change

• New feature
• Bug fix
• Documentation update
• Refactoring
• Performance improvement
• Other (please describe):

Changes Made

AI Providers

• Replaced Together AI with Perplexity and Gemini as new AI providers
• Added Gemini API integration (callGemini) with its native REST API format
• Updated provider priority order: Groq > Gemini > Perplexity > OpenAI > Anthropic (free-tier providers first)
• Increased MAX_TOKENS from 1024 to 4096

Prompt Versioning & User Modes

• Added PromptVersion type ("stable" | "latest") to support prompt experimentation
• Introduced power vs regular user modes with distinct prompt configs:
  • Power user: Detailed analysis (8-10 sentences), audience = senior blockchain developer, includes security-focused analysis
  • Regular user: Simplified analysis (3-7 sentences), audience = general user, beginner-friendly language
• Created a PROMPT_REGISTRY for O(1) lookup by version → mode → type
• Added prompt version selector in Settings UI (Stable/Latest)
• Cache keys now incorporate prompt version and user mode to avoid stale results

Smarter Contract Context (aiContext.ts)

• Replaced raw ABI dump with structured contract intelligence:
  • Interface detection: Automatically identifies ERC-20, ERC-721, ERC-1155, Uniswap V4 Hook, Ownable, AccessControl, Pausable, ERC-2612, UUPS/Transparent Proxy
  • Protocol hints: Detects OpenZeppelin, Uniswap, Solady, Chainlink, Aave, Compound, Safe, EigenLayer, LayerZero from source file paths
  • Function categorization: Groups functions into admin, hooks, core, and view categories
  • Function summary: Counts total, view, state-changing, and payable functions
• Significantly reduces token usage by sending structured summaries instead of full ABI arrays

Transaction Context

• Event summaries now include up to 4 decoded parameter name/value pairs for richer AI context

i18n

• Added translations (en/es) for Perplexity, Gemini provider labels, and prompt version settings

Screenshots (if applicable)

Checklist

• I have run npm run format:fix and npm run lint:fix
• I have run npm run typecheck with no errors
• I have run tests with npm run test:run
• I have tested my changes locally
• I have updated documentation if needed
• My code follows the project's architecture patterns

Additional Notes

• The latest prompt configs are initially clones of stable — they serve as an experimentation sandbox for prompt iteration without risking regression on the stable path.
• Gemini uses its native REST API (not OpenAI-compatible), so a dedicated callGemini method was added.
• The contract context refactor should noticeably reduce AI token consumption while providing better analytical signals (detected interfaces, protocol hints, categorized functions).

[github-actions]

🚀 Preview: https://pr-225--openscan.netlify.app
📝 Commit: 70214aef105b6b51118c2f28d346954c61791c8e

[AugustoL]

PR #225 Review — AI Analyzer Enhancement

Overall: Well-structured PR with solid architecture decisions. The PROMPT_REGISTRY, aiContext.ts refactor, and cache key versioning are particularly good. A few things worth addressing before merging.

---

Issues

1. Naming inconsistency: superUserMode vs isSuperUser

UserSettings defines superUserMode?: boolean but the hook reportedly passes it as isSuperUser. These need to be consistent — either rename the type field or the hook variable. Small but can cause silent bugs if someone reads directly from settings expecting isSuperUser.

---

2. primaryAIProviderId hardcoded to "groq" in settings UI

const primaryAIProviderId = "groq"; // hardcoded

This should be AI_PROVIDER_ORDER[0] so that if the priority order ever changes, the Settings UI reflects it automatically. Hardcoding creates a maintenance footgun.

---

3. Anthropic model ID is outdated

In aiProviders.ts:

defaultModel: "claude-sonnet-4-5-20250929",

The current model is claude-sonnet-4-6. This is minor since users can override, but the default matters for first-time usage.

---

4. Protocol detection false positives

extractProtocolHints() matches against source file paths using regex. A contract with a file named something like my-uniswap-fork/MyContract.sol would be detected as Uniswap. Consider requiring the match to be at a directory boundary (e.g. node_modules/ or a known import path prefix) to reduce noise.

---

5. AIAnalysisResult.cached — appears unused

The type includes cached: boolean but the hook's analyze() (cache-first) method doesn't seem to surface this to the UI. Either wire it up to show a "cached" indicator, or remove it from the type to avoid dead fields.

---

6. AIService.ts — retry/timeout behavior

A few things worth verifying in the service:

• Is there a hard timeout per request (not just retries)? A slow provider shouldn't hang the UI indefinitely.
• Is the Anthropic anthropic-version header using a hardcoded date? That can cause issues when the API deprecates old versions.
• Are API keys ever interpolated into URLs? They should only appear in headers.

---

Summary

Architecture	✅ PROMPT_REGISTRY, cache key versioning, aiContext.ts refactor are solid
Should fix	superUserMode/isSuperUser inconsistency, hardcoded primaryAIProviderId
Should verify	AIService.ts timeout handling, Anthropic version header
Minor	Outdated Anthropic model default, protocol detection false positives, dead cached field