@rankcli/agent-runtime 0.0.14 → 0.0.16

package/src/audit/ai/analyzer.ts

@@ -1,347 +0,0 @@
-// AI-Powered SEO Analyzer
-// Uses LLMs to provide contextual, intelligent SEO analysis
-
-import type {
-  AIConfig,
-  AIContentAnalysis,
-  AIMetaAnalysis,
-  AISchemaAnalysis,
-  AIVisibilityAnalysis,
-  AIFixPrioritization,
-  AIAnalysisResult,
-  PageContext,
-} from './types.js';
-
-import {
-  CONTENT_ANALYSIS_SYSTEM,
-  CONTENT_ANALYSIS_USER,
-  META_ANALYSIS_SYSTEM,
-  META_ANALYSIS_USER,
-  SCHEMA_ANALYSIS_SYSTEM,
-  SCHEMA_ANALYSIS_USER,
-  AI_VISIBILITY_SYSTEM,
-  AI_VISIBILITY_USER,
-  FIX_PRIORITIZATION_SYSTEM,
-  FIX_PRIORITIZATION_USER,
-} from './prompts/content-analysis.js';
-
-export class AIAnalyzer {
-  private config: AIConfig;
-  private cache: Map<string, { result: unknown; timestamp: number }> = new Map();
-  private cacheTimeout = 3600000; // 1 hour
-
-  constructor(config: AIConfig) {
-    this.config = {
-      model: 'gpt-4o',
-      maxTokens: 4096,
-      temperature: 0.3,
-      ...config,
-    };
-  }
-
-  /**
-   * Call OpenAI API with structured JSON response
-   */
-  private async callOpenAI<T>(
-    systemPrompt: string,
-    userPrompt: string,
-    cacheKey?: string
-  ): Promise<{ result: T; tokensUsed: number; cached: boolean }> {
-    // Check cache
-    if (cacheKey) {
-      const cached = this.cache.get(cacheKey);
-      if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
-        return { result: cached.result as T, tokensUsed: 0, cached: true };
-      }
-    }
-
-    const response = await fetch('https://api.openai.com/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.openaiApiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.config.model,
-        messages: [
-          { role: 'system', content: systemPrompt },
-          { role: 'user', content: userPrompt },
-        ],
-        max_tokens: this.config.maxTokens,
-        temperature: this.config.temperature,
-        response_format: { type: 'json_object' },
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`OpenAI API error: ${response.status} - ${error}`);
-    }
-
-    const data = await response.json();
-    const content = data.choices?.[0]?.message?.content;
-    const tokensUsed = data.usage?.total_tokens || 0;
-
-    if (!content) {
-      throw new Error('No content in OpenAI response');
-    }
-
-    let result: T;
-    try {
-      result = JSON.parse(content) as T;
-    } catch {
-      throw new Error(`Failed to parse OpenAI JSON response: ${content}`);
-    }
-
-    // Cache result
-    if (cacheKey) {
-      this.cache.set(cacheKey, { result, timestamp: Date.now() });
-    }
-
-    return { result, tokensUsed, cached: false };
-  }
-
-  /**
-   * Analyze content quality using AI
-   */
-  async analyzeContent(context: PageContext): Promise<{
-    analysis: AIContentAnalysis;
-    tokensUsed: number;
-    cached: boolean;
-  }> {
-    const cacheKey = `content:${context.url}:${context.textContent.length}`;
-
-    const { result, tokensUsed, cached } = await this.callOpenAI<AIContentAnalysis>(
-      CONTENT_ANALYSIS_SYSTEM,
-      CONTENT_ANALYSIS_USER({
-        url: context.url,
-        title: context.title,
-        h1: context.h1,
-        metaDescription: context.metaDescription,
-        textContent: context.textContent,
-        wordCount: context.wordCount,
-        headings: context.headings,
-      }),
-      cacheKey
-    );
-
-    return { analysis: result, tokensUsed, cached };
-  }
-
-  /**
-   * Analyze and optimize meta tags using AI
-   */
-  async analyzeMeta(context: PageContext): Promise<{
-    analysis: AIMetaAnalysis;
-    tokensUsed: number;
-    cached: boolean;
-  }> {
-    const cacheKey = `meta:${context.url}:${context.title}:${context.metaDescription}`;
-
-    const { result, tokensUsed, cached } = await this.callOpenAI<AIMetaAnalysis>(
-      META_ANALYSIS_SYSTEM,
-      META_ANALYSIS_USER({
-        url: context.url,
-        title: context.title,
-        metaDescription: context.metaDescription,
-        h1: context.h1,
-        pageType: context.industry,
-        industry: context.industry,
-      }),
-      cacheKey
-    );
-
-    return { analysis: result, tokensUsed, cached };
-  }
-
-  /**
-   * Analyze and generate structured data using AI
-   */
-  async analyzeSchema(context: PageContext): Promise<{
-    analysis: AISchemaAnalysis;
-    tokensUsed: number;
-    cached: boolean;
-  }> {
-    const cacheKey = `schema:${context.url}`;
-
-    // Detect page type from URL and content
-    let pageType = 'other';
-    const urlLower = context.url.toLowerCase();
-    const contentLower = context.textContent.toLowerCase();
-
-    if (urlLower.includes('/blog/') || urlLower.includes('/article/') || urlLower.includes('/post/')) {
-      pageType = 'article';
-    } else if (urlLower.includes('/product/') || contentLower.includes('add to cart') || contentLower.includes('buy now')) {
-      pageType = 'product';
-    } else if (urlLower.includes('/faq') || contentLower.includes('frequently asked')) {
-      pageType = 'faq';
-    } else if (urlLower.includes('/about') || urlLower.includes('/team')) {
-      pageType = 'organization';
-    } else if (urlLower.includes('/contact')) {
-      pageType = 'local-business';
-    }
-
-    const { result, tokensUsed, cached } = await this.callOpenAI<AISchemaAnalysis>(
-      SCHEMA_ANALYSIS_SYSTEM,
-      SCHEMA_ANALYSIS_USER({
-        url: context.url,
-        title: context.title,
-        textContent: context.textContent,
-        existingSchema: context.schema,
-        pageType,
-      }),
-      cacheKey
-    );
-
-    return { analysis: result, tokensUsed, cached };
-  }
-
-  /**
-   * Analyze AI/LLM visibility and optimization
-   */
-  async analyzeAIVisibility(
-    context: PageContext,
-    botAccess: { hasLlmsTxt: boolean; llmsTxtContent?: string; blockedBots: string[] }
-  ): Promise<{
-    analysis: AIVisibilityAnalysis;
-    tokensUsed: number;
-    cached: boolean;
-  }> {
-    const cacheKey = `aivis:${context.url}`;
-
-    const { result, tokensUsed, cached } = await this.callOpenAI<AIVisibilityAnalysis>(
-      AI_VISIBILITY_SYSTEM,
-      AI_VISIBILITY_USER({
-        url: context.url,
-        title: context.title,
-        textContent: context.textContent,
-        headings: context.headings,
-        hasLlmsTxt: botAccess.hasLlmsTxt,
-        llmsTxtContent: botAccess.llmsTxtContent,
-        blockedBots: botAccess.blockedBots,
-      }),
-      cacheKey
-    );
-
-    return { analysis: result, tokensUsed, cached };
-  }
-
-  /**
-   * Prioritize fixes using AI
-   */
-  async prioritizeFixes(
-    issues: { code: string; severity: string; title: string; category: string }[],
-    context: { url: string; framework?: string }
-  ): Promise<{
-    analysis: AIFixPrioritization;
-    tokensUsed: number;
-    cached: boolean;
-  }> {
-    // Don't cache fix prioritization - issues change each audit
-    const { result, tokensUsed, cached } = await this.callOpenAI<AIFixPrioritization>(
-      FIX_PRIORITIZATION_SYSTEM,
-      FIX_PRIORITIZATION_USER({
-        issues,
-        url: context.url,
-        framework: context.framework,
-      })
-    );
-
-    return { analysis: result, tokensUsed, cached };
-  }
-
-  /**
-   * Run full AI analysis on a page
-   */
-  async runFullAnalysis(
-    context: PageContext,
-    options: {
-      analyzeContent?: boolean;
-      analyzeMeta?: boolean;
-      analyzeSchema?: boolean;
-      analyzeAIVisibility?: boolean;
-      prioritizeFixes?: boolean;
-      issues?: { code: string; severity: string; title: string; category: string }[];
-      botAccess?: { hasLlmsTxt: boolean; llmsTxtContent?: string; blockedBots: string[] };
-    } = {}
-  ): Promise<AIAnalysisResult> {
-    const startTime = Date.now();
-    let totalTokens = 0;
-    let anyCached = false;
-
-    const result: AIAnalysisResult = {
-      analysisTime: 0,
-      tokensUsed: 0,
-      modelUsed: this.config.model || 'gpt-4o',
-      cached: false,
-    };
-
-    // Run analyses in parallel where possible
-    const analyses = await Promise.allSettled([
-      options.analyzeContent !== false
-        ? this.analyzeContent(context)
-        : Promise.resolve(null),
-      options.analyzeMeta !== false
-        ? this.analyzeMeta(context)
-        : Promise.resolve(null),
-      options.analyzeSchema !== false
-        ? this.analyzeSchema(context)
-        : Promise.resolve(null),
-      options.analyzeAIVisibility !== false && options.botAccess
-        ? this.analyzeAIVisibility(context, options.botAccess)
-        : Promise.resolve(null),
-      options.prioritizeFixes && options.issues
-        ? this.prioritizeFixes(options.issues, { url: context.url, framework: context.framework })
-        : Promise.resolve(null),
-    ]);
-
-    // Process results
-    if (analyses[0].status === 'fulfilled' && analyses[0].value) {
-      result.content = analyses[0].value.analysis;
-      totalTokens += analyses[0].value.tokensUsed;
-      if (analyses[0].value.cached) anyCached = true;
-    }
-
-    if (analyses[1].status === 'fulfilled' && analyses[1].value) {
-      result.meta = analyses[1].value.analysis;
-      totalTokens += analyses[1].value.tokensUsed;
-      if (analyses[1].value.cached) anyCached = true;
-    }
-
-    if (analyses[2].status === 'fulfilled' && analyses[2].value) {
-      result.schema = analyses[2].value.analysis;
-      totalTokens += analyses[2].value.tokensUsed;
-      if (analyses[2].value.cached) anyCached = true;
-    }
-
-    if (analyses[3].status === 'fulfilled' && analyses[3].value) {
-      result.aiVisibility = analyses[3].value.analysis;
-      totalTokens += analyses[3].value.tokensUsed;
-      if (analyses[3].value.cached) anyCached = true;
-    }
-
-    if (analyses[4].status === 'fulfilled' && analyses[4].value) {
-      result.fixPrioritization = analyses[4].value.analysis;
-      totalTokens += analyses[4].value.tokensUsed;
-      if (analyses[4].value.cached) anyCached = true;
-    }
-
-    result.analysisTime = Date.now() - startTime;
-    result.tokensUsed = totalTokens;
-    result.cached = anyCached;
-
-    return result;
-  }
-
-  /**
-   * Clear the cache
-   */
-  clearCache(): void {
-    this.cache.clear();
-  }
-}
-
-// Export a factory function for creating analyzers
-export function createAIAnalyzer(config: AIConfig): AIAnalyzer {
-  return new AIAnalyzer(config);
-}

package/src/audit/ai/index.ts

@@ -1,29 +0,0 @@
-// AI-Powered SEO Analysis Module
-// Exports for use in audits and Edge Functions
-
-export { AIAnalyzer, createAIAnalyzer } from './analyzer.js';
-
-export type {
-  AIConfig,
-  AIContentAnalysis,
-  AIMetaAnalysis,
-  AISchemaAnalysis,
-  AILinkAnalysis,
-  AIVisibilityAnalysis,
-  AIFixPrioritization,
-  AIAnalysisResult,
-  PageContext,
-} from './types.js';
-
-export {
-  CONTENT_ANALYSIS_SYSTEM,
-  CONTENT_ANALYSIS_USER,
-  META_ANALYSIS_SYSTEM,
-  META_ANALYSIS_USER,
-  SCHEMA_ANALYSIS_SYSTEM,
-  SCHEMA_ANALYSIS_USER,
-  AI_VISIBILITY_SYSTEM,
-  AI_VISIBILITY_USER,
-  FIX_PRIORITIZATION_SYSTEM,
-  FIX_PRIORITIZATION_USER,
-} from './prompts/content-analysis.js';

package/src/audit/ai/prompts/content-analysis.ts

@@ -1,271 +0,0 @@
-// AI Content Analysis Prompts
-
-export const CONTENT_ANALYSIS_SYSTEM = `You are an expert SEO analyst with deep knowledge of search engine algorithms, content quality signals, and Google's E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) guidelines.
-
-Your task is to analyze webpage content and provide actionable SEO insights. Be specific, practical, and data-driven in your analysis.
-
-Always respond with valid JSON matching the specified schema.`;
-
-export const CONTENT_ANALYSIS_USER = (context: {
-  url: string;
-  title?: string;
-  h1?: string;
-  metaDescription?: string;
-  textContent: string;
-  wordCount: number;
-  headings?: { level: number; text: string }[];
-}) => `Analyze this webpage content for SEO quality:
-
-<webpage>
-URL: ${context.url}
-Title: ${context.title || 'Not found'}
-H1: ${context.h1 || 'Not found'}
-Meta Description: ${context.metaDescription || 'Not found'}
-Word Count: ${context.wordCount}
-Headings: ${JSON.stringify(context.headings || [])}
-
-Content (first 5000 chars):
-${context.textContent.substring(0, 5000)}
-</webpage>
-
-Analyze this content and return JSON with this exact structure:
-{
-  "overallScore": <0-100 integer>,
-  "searchIntentMatch": <0-100 integer - how well content satisfies likely search intent>,
-  "contentDepth": "<shallow|moderate|comprehensive>",
-  "keywordNaturalness": <0-100 integer - 100 = perfectly natural, 0 = keyword stuffed>,
-  "eeatSignals": {
-    "experience": [<strings describing first-hand experience indicators found>],
-    "expertise": [<strings describing expertise signals like credentials, depth of knowledge>],
-    "authority": [<strings describing authority signals like citations, references>],
-    "trust": [<strings describing trust signals like contact info, transparency>]
-  },
-  "improvements": [
-    {
-      "priority": <1-5 integer, 1 = highest>,
-      "suggestion": "<specific actionable improvement>",
-      "impact": "<expected SEO impact of this change>"
-    }
-  ],
-  "uniqueValue": "<one sentence describing what unique value this page provides>",
-  "missingTopics": [<topics that comprehensive coverage should include>],
-  "targetKeyword": "<the primary keyword this page appears to target>",
-  "keywordDensity": <percentage as decimal, e.g., 2.5>
-}
-
-Be critical but constructive. Focus on high-impact improvements.`;
-
-export const META_ANALYSIS_SYSTEM = `You are an expert SEO copywriter specializing in meta tags that drive clicks from search results.
-
-You understand:
-- Google's SERP display rules (title ~60 chars, description ~155 chars)
-- Click psychology and emotional triggers
-- Keyword optimization without stuffing
-- Brand positioning in titles
-
-Always respond with valid JSON matching the specified schema.`;
-
-export const META_ANALYSIS_USER = (context: {
-  url: string;
-  title?: string;
-  metaDescription?: string;
-  h1?: string;
-  pageType?: string;
-  industry?: string;
-}) => `Analyze these meta tags and suggest improvements:
-
-<page>
-URL: ${context.url}
-Current Title: ${context.title || 'Missing'}
-Current Description: ${context.metaDescription || 'Missing'}
-H1: ${context.h1 || 'Not found'}
-Page Type: ${context.pageType || 'Unknown'}
-Industry: ${context.industry || 'General'}
-</page>
-
-Return JSON with this exact structure:
-{
-  "titleAnalysis": {
-    "effectiveness": <0-100 integer>,
-    "clickPotential": <0-100 integer>,
-    "keywordPlacement": "<optimal|suboptimal|missing>",
-    "emotionalTriggers": [<power words or emotional triggers found>],
-    "suggestions": [<3-5 alternative title suggestions that would perform better>]
-  },
-  "descriptionAnalysis": {
-    "effectiveness": <0-100 integer>,
-    "hasCallToAction": <boolean>,
-    "hasUniqueSellingProposition": <boolean>,
-    "keywordNaturalness": <0-100 integer>,
-    "suggestions": [<3-5 alternative description suggestions>]
-  },
-  "serpPrediction": {
-    "predictedCTR": <predicted click-through rate as percentage, e.g., 3.5>,
-    "competitiveStrength": "<weak|average|strong>",
-    "improvements": [<specific changes that would improve CTR>]
-  }
-}
-
-Make suggestions compelling, keyword-optimized, and within character limits.`;
-
-export const SCHEMA_ANALYSIS_SYSTEM = `You are an expert in structured data and Schema.org markup for SEO.
-
-You understand:
-- All Schema.org types and their properties
-- Google's rich result requirements
-- JSON-LD best practices
-- How to maximize rich snippet eligibility
-
-Always respond with valid JSON matching the specified schema.`;
-
-export const SCHEMA_ANALYSIS_USER = (context: {
-  url: string;
-  title?: string;
-  textContent: string;
-  existingSchema?: object[];
-  pageType?: string;
-}) => `Analyze this page and recommend structured data:
-
-<page>
-URL: ${context.url}
-Title: ${context.title || 'Unknown'}
-Detected Page Type: ${context.pageType || 'Unknown'}
-Existing Schema: ${JSON.stringify(context.existingSchema || [], null, 2)}
-
-Content Summary (first 2000 chars):
-${context.textContent.substring(0, 2000)}
-</page>
-
-Return JSON with this exact structure:
-{
-  "detectedPageType": "<article|product|service|faq|how-to|local-business|organization|person|event|recipe|other>",
-  "recommendedSchemas": [
-    {
-      "type": "<Schema.org type name>",
-      "priority": "<critical|high|medium|low>",
-      "reason": "<why this schema is recommended>"
-    }
-  ],
-  "generatedSchemas": [
-    {
-      "type": "<Schema.org type>",
-      "jsonLd": <complete valid JSON-LD object>,
-      "explanation": "<what this schema does and why>"
-    }
-  ],
-  "richSnippetPotential": [
-    {
-      "type": "<rich result type: FAQ, How-to, Review, Product, etc.>",
-      "eligible": <boolean>,
-      "requirements": [<what's needed to qualify>]
-    }
-  ]
-}
-
-Generate complete, valid JSON-LD that can be directly used.`;
-
-export const AI_VISIBILITY_SYSTEM = `You are an expert in how AI systems (LLMs like ChatGPT, Claude, Perplexity) crawl, understand, and cite web content.
-
-You understand:
-- How LLMs parse and understand content structure
-- The llms.txt standard for AI guidance
-- When to allow/block AI crawlers
-- How to optimize for AI citation
-
-Always respond with valid JSON matching the specified schema.`;
-
-export const AI_VISIBILITY_USER = (context: {
-  url: string;
-  title?: string;
-  textContent: string;
-  headings?: { level: number; text: string }[];
-  hasLlmsTxt: boolean;
-  llmsTxtContent?: string;
-  blockedBots: string[];
-}) => `Analyze this page's AI/LLM visibility:
-
-<page>
-URL: ${context.url}
-Title: ${context.title || 'Unknown'}
-Has llms.txt: ${context.hasLlmsTxt}
-llms.txt content: ${context.llmsTxtContent || 'N/A'}
-Blocked AI Bots: ${context.blockedBots.join(', ') || 'None'}
-
-Heading Structure:
-${(context.headings || []).map(h => '  '.repeat(h.level - 1) + h.text).join('\n')}
-
-Content (first 3000 chars):
-${context.textContent.substring(0, 3000)}
-</page>
-
-Return JSON with this exact structure:
-{
-  "llmReadability": {
-    "score": <0-100 integer>,
-    "structureClarity": <0-100 integer - how clear is the content structure>,
-    "contextClarity": <0-100 integer - how clear is the page's purpose/topic>,
-    "citationPotential": <0-100 integer - likelihood of being cited by AI>,
-    "improvements": [<specific improvements for AI readability>]
-  },
-  "botAccessRecommendation": {
-    "shouldAllowGPTBot": <boolean>,
-    "shouldAllowClaudeBot": <boolean>,
-    "shouldAllowPerplexityBot": <boolean>,
-    "shouldAllowGoogleExtended": <boolean>,
-    "rationale": "<explanation of bot access recommendation>"
-  },
-  "llmsTxtSuggestion": {
-    "content": "<suggested llms.txt content>",
-    "explanation": "<why this llms.txt is recommended>"
-  }
-}
-
-Consider the site's likely goals when recommending bot access.`;
-
-export const FIX_PRIORITIZATION_SYSTEM = `You are an SEO strategist who excels at prioritizing fixes for maximum impact with minimum effort.
-
-You understand:
-- Which SEO issues have the biggest ranking impact
-- Implementation effort for different types of fixes
-- How to batch related fixes together
-- Quick wins vs long-term improvements
-
-Always respond with valid JSON matching the specified schema.`;
-
-export const FIX_PRIORITIZATION_USER = (context: {
-  issues: { code: string; severity: string; title: string; category: string }[];
-  url: string;
-  framework?: string;
-}) => `Prioritize these SEO issues by impact and effort:
-
-<context>
-URL: ${context.url}
-Framework: ${context.framework || 'Unknown'}
-</context>
-
-<issues>
-${context.issues.map(i => `- [${i.severity.toUpperCase()}] ${i.code}: ${i.title} (${i.category})`).join('\n')}
-</issues>
-
-Return JSON with this exact structure:
-{
-  "prioritizedIssues": [
-    {
-      "issueCode": "<issue code>",
-      "impactScore": <0-100 integer - SEO impact if fixed>,
-      "effortScore": <0-100 integer - effort to fix, 100 = very hard>,
-      "roiScore": <calculated as impact / effort, higher is better>,
-      "rationale": "<why this priority>"
-    }
-  ],
-  "fixBatches": [
-    {
-      "batch": <1, 2, 3, etc.>,
-      "theme": "<batch theme like 'Meta Tags' or 'Technical SEO'>",
-      "estimatedImpact": "<description of combined impact>",
-      "issueCodes": [<issue codes in this batch>]
-    }
-  ]
-}
-
-Sort prioritizedIssues by roiScore descending. Group related fixes into batches.`;