@rankcli/agent-runtime 0.0.23 → 0.0.25

package/dist/index.d.mts

@@ -1631,6 +1631,39 @@ declare function runKeywordResearch(options: KeywordResearchOptions): Promise<Ke
 declare function formatKeywordReport(result: KeywordResearchResult): string;
 declare function extractSeedKeywords(url: string): Promise<string[]>;
 
+interface KeywordLLM {
+    /**
+     * A reply to one prompt that asks for a JSON object. `best` asks for the provider's stronger
+     * model where it has one. Replies are parsed with parseJsonReply, never trusted to be clean.
+     */
+    complete(prompt: string, opts?: {
+        system?: string;
+        maxTokens?: number;
+        temperature?: number;
+        best?: boolean;
+    }): Promise<string>;
+    /** Embeddings for keyword clustering. Without it, clustering falls back to term vectors. */
+    embed?(texts: string[]): Promise<number[][]>;
+    /** Most page text worth sending in one prompt: small-context models get less. */
+    maxContentChars?: number;
+    /** How many tool ideas to judge (two calls each): slow local models get fewer. */
+    maxToolIdeas?: number;
+}
+/** The engine's original backend: gpt-4o-mini, gpt-4o for `best`, JSON mode, text-embedding-3-small. */
+declare function openAIKeywordLLM(apiKey: string, opts?: {
+    model?: string;
+}): KeywordLLM;
+/** The model to use: an explicit one, else OpenAI when there's a key, else none. */
+declare function keywordLLM(options: {
+    llm?: KeywordLLM;
+    openaiApiKey?: string;
+}): KeywordLLM | undefined;
+/**
+ * The JSON object in a model reply. Local and small models wrap it in ``` fences, prepend prose
+ * or emit <think> blocks; this takes the outermost {...} and tolerates trailing commas.
+ */
+declare function parseJsonReply(text: string): Record<string, any> | null;
+
 /**
  * Site Crawler for Keyword Research
  *
@@ -1687,7 +1720,7 @@ declare function extractKeyPhrases(crawlResult: SiteCrawlResult): string[];
 /**
  * AI-Powered Site Summarizer
  *
- * Uses OpenAI to understand what a site does from crawled content.
+ * Uses the configured AI provider (llm.ts) to understand what a site does from crawled content.
  * Extracts: product, audience, features, industry, positioning.
  */
 
@@ -1724,7 +1757,10 @@ interface SiteSummary {
     uncertainties: string[];
 }
 interface SummarizerOptions {
-    openaiApiKey: string;
+    /** The model to ask (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
+    openaiApiKey?: string;
+    /** OpenAI model override, with openaiApiKey. */
     model?: string;
     maxTokens?: number;
 }
@@ -1831,10 +1867,12 @@ declare function calculateBM25(documents: string[], query: string, k1?: number,
     docIndex: number;
     score: number;
 }>;
+/** An OpenAI client, or any function returning one embedding per text (llm.ts). */
+type Embedder = OpenAI | ((texts: string[]) => Promise<number[][]>);
 /**
  * Cluster keywords using embeddings
  */
-declare function clusterKeywordsByEmbedding(keywords: string[], openai: OpenAI, numClusters?: number): Promise<KeywordCluster[]>;
+declare function clusterKeywordsByEmbedding(keywords: string[], openai: Embedder, numClusters?: number): Promise<KeywordCluster[]>;
 /**
  * Extract entity-like phrases (capitalized sequences, proper nouns)
  */
@@ -1848,6 +1886,8 @@ declare function extractTopics(documents: string[], numTopics?: number): TopicMo
  * Run full NLP analysis on content
  */
 declare function runNLPAnalysis(content: string | string[], options?: {
+    /** Embeddings come from here when it has them (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
     openaiApiKey?: string;
     numClusters?: number;
     numTopics?: number;
@@ -1871,6 +1911,8 @@ type PlanTier = 'free' | 'solo' | 'pro' | 'agency';
 interface AIKeywordResearchOptions {
     url: string;
     tier: PlanTier;
+    /** The model to ask for paid-tier research (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
     openaiApiKey?: string;
     maxPages?: number;
     userContext?: {
@@ -2066,6 +2108,8 @@ interface WizardResult {
  * Start a new wizard session
  */
 declare function startWizardSession(url: string, options?: {
+    /** The model for the site summary (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
     openaiApiKey?: string;
     existingResponses?: WizardResponse[];
 }): Promise<WizardSession>;
@@ -2370,7 +2414,9 @@ interface EnhancedToolIdea {
     priority: number;
 }
 interface LLMJudgeOptions {
-    openaiApiKey: string;
+    /** The model to ask (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
+    openaiApiKey?: string;
     minFeasibilityScore?: number;
     minSpecificityScore?: number;
     minProductFitScore?: number;
@@ -4691,11 +4737,9 @@ declare class RankTracker {
      */
     private saveRanking;
     /**
-     * Get ranking history for a keyword
-     * Note: Full history requires keyword_ranking_history table with keyword_ranking_id
-     * For now, returns current state as single history entry
+     * Ranking history for a keyword: one entry per check in the last `days`, newest first.
      */
-    getHistory(keywordId: string, _days?: number): Promise<RankHistory[]>;
+    getHistory(keywordId: string, days?: number): Promise<RankHistory[]>;
     /**
      * Get keyword trends for a project
      */
@@ -5498,4 +5542,4 @@ declare namespace index {
   export { type index_Framework as Framework, type index_FrameworkCheck as FrameworkCheck, type index_FrameworkInfo as FrameworkInfo, type index_FrameworkRecipe as FrameworkRecipe, index_SUPPORTED_FRAMEWORKS as SUPPORTED_FRAMEWORKS, index_detectFramework as detectFramework, index_detectFromHeaders as detectFromHeaders, index_detectFromHtml as detectFromHtml, index_detectFromPackageJson as detectFromPackageJson, index_embedRecipe as embedRecipe, index_getFrameworkChecks as getFrameworkChecks, index_getFrameworkDisplayName as getFrameworkDisplayName, index_getFrameworkIssues as getFrameworkIssues, index_getFrameworkSuggestions as getFrameworkSuggestions, index_getFrameworkSummary as getFrameworkSummary, index_getMigrationPaths as getMigrationPaths, index_getPerformanceTips as getPerformanceTips, index_getSeoChallenges as getSeoChallenges, index_getTotalFrameworkChecks as getTotalFrameworkChecks, index_loadRecipe as loadRecipe };
 }
 
-export { type AIContentConfig, type AIKeywordResearchOptions, type AgentDefinition, type AgentTool, type AlertChannel, type AlertConfig, type AlertMessage, type AlertResult, type AlertSeverity, type AlertType, type AuditAlertPayload, type AuditIssue, type AuditIssueData, type AuditOptions, type AuditPRResult, type AuditReport, type AuditReportData, type AuditRunnerOptions, type AuditRunnerResult, type AuditSchedule, type BlogPostConfig, type BrandConfig, type CIAction, type CIKeywordOptions, type CIKeywordResult, COMMIT_TYPES, type ChangelogConfig, type ChangelogResult, type CitationCheckOptions, type CommitConfig, type ComparisonConfig, type ComparisonRow, type CompetitiveInsight, type CompetitiveSearchOptions, type CompetitiveSearchResult, type CompetitorComparison, type CompetitorKeywordResult, type CompetitorOverlap, type CompetitorTool, type CompetitorUrl, type ContentElements, type ContentGeneratorOptions, type ContentRecommendation, type ConventionalCommit, type CrawlResult, type CrawlStats, type CrawledPage, type CreateAuditPROptions, type CreatePROptions, type DataForSEOCredentials, type DiscoveredPage, type EnhancedToolIdea, type ExecOptions, type ExecuteOptions, type ExecutionResult, type FAQItem, type FAQSchemaOptions, type FeaturedSnippetAnalysis, type Fix, type FixFile, type FixGeneratorOptions, type FixResult, type FrameworkInfo$1 as FrameworkInfo, type FreeKeywordResult, type FreeToolIdea, type GA4Config, type GEOAlert, type GEOAlertType, type GEOHistory, type GEOHistoryOptions, type GEOQuery, type GEOReport, type GEOResult, type GEOTrend, type GSCConfig, type GSCCredentials, type GSCPerformanceData, type GSCQueryData, type GSCQueryResult, type GeneratedCode, type GeneratedContent, type GeneratedFix, type HeadingStructure, type HeadlineAnalysis, type HealthScore, ISSUE_DEFINITIONS, type ImageInfo$2 as ImageInfo, type InjectionResult, type IntentAnalysis, type IssueCategory, type IssueDefinition, type IssueSeverity, type KeyFact, type KeyFactsOptions, type KeywordAction, type KeywordCluster, type KeywordData, type KeywordDensityAnalysis, type KeywordOpportunity, type KeywordRecommendation, type KeywordResearchOptions, type KeywordResearchResult, type KeywordStats, type KeywordTopic, type KeywordTrend, type LLMCitationResult, type LLMJudgeOptions, type LLMProvider, LOCATION_CODES, type LSIKeyword, type LinkInfo$1 as LinkInfo, type Mention, type MentionType, type MetaData, type MetaFixOptions, type NGram, type NLPAnalysisResult, OG_IMAGE_SPECS, type OptimizeOptions, type PRConfig, type PRDescription, PRIORITY_WEIGHTS, type PRResult, type PageAudit, type PageData, type PageMeta, type PaidKeywordResult, type ParsedResponse, type PlanTier, type ProviderStats, type QuickWin, type RankCheckOptions, type RankCheckResult, type RankHistory, RankTracker, type RankingResult, type RankingTierLimits, type ReadabilityResult, type ReadmeConfig, type ReadmeResult, type ReportBranding, type ReportConfig, type ReportData, type ReportPageData, type RouteInfo, type SEOAnalysisResult, type SEOFixCommit, type SEOFixSummary, type SEOIssue, type SEORecommendation, type SEOScore, SEO_SCOPES, SITE_PROFILE_QUESTIONS, type ScheduledAuditConfig, type ScheduledAuditResult, type SchemaData, Schemas, type SearchIntent, type Sentiment, type SerpApiConfig, SerpClient, type SerpClientConfig, type SerpFeature, type SiteCrawlResult, type SiteProfile, type SiteSummary, type SnippetRecommendation, type SnippetType, type SocialMetaConfig, type SocialMetaFix, type SummarizerOptions, type TFIDFResult, TIER_LIMITS, type ToolFeasibilityScore, type ToolFunction, type ToolResult, type TopicClusterResult, type TopicModel, type TrackedKeyword, type TrackerConfig, type TrackingOptions, type TrendDirection, type UncertaintyAssessment, type WizardQuestion, type WizardResponse, type WizardResult, type WizardSession, type WorkflowConfig, addTrackingResult, analyzeAnchorText, analyzeCanonicalAdvanced, analyzeClientRendering, analyzeContentFreshness, analyzeDOMStructure, analyzeFeaturedSnippetPotential, analyzeHeadings, analyzeHeadline, analyzeHreflang, analyzeImages$1 as analyzeImages, analyzeKeywordDensity, analyzeKeywords, analyzeLinks, analyzeLocalSEO, analyzeMobile, analyzeModernImages, analyzeOnPage, analyzePagination, analyzePerformance, analyzeReadability, analyzeRedirectChain, analyzeRedirects, analyzeResponsiveImages, analyzeSERPPreview, analyzeSecurity, analyzeSecurityHeaders$1 as analyzeSecurityHeaders, analyzeSocialMeta, analyzeStructuredData$1 as analyzeStructuredData, analyzeTrackerBloat, analyzeUrl, analyzeUrlSafety, index$1 as analyzers, applyFixes, buildGSCApiRequest, buildGSCRequest, calculateAIVisibilityScore, calculateBM25, calculateTFIDF$1 as calculateKeywordTFIDF, calculateNextRun, calculateTFIDF, checkAIBotBlocking, checkAMP, checkAdsTxt, checkAppleTouchIcon, checkBalance, checkCertificate, checkDMARC, checkGitHubCLI, checkInternalRedirects, checkJSRenderingRatio, checkLLMCitations, checkLlmsTxt, checkMobileResources, checkPlaintextEmails, checkRedirects, checkRobots, checkRobotsTxt, checkSPF, checkSitemap, classifyIntent, classifyIntents, clusterKeywordsByEmbedding, compareCompetitorVisibility, comparePeriods, completeWizard, crawlSite, crawlUrl, createAuditPR, createFallbackSummary, createGEOHistory, createPullRequest, createSEOCommit, createSEOCommits, detectDuplicates, detectFramework$1 as detectFramework, detectGitHubPages, detectMentions, detectSoft404, detectTechnologies, detectVisibilityChanges, discoverCompetitorKeywords, discoverPagesFromLinks, discoverRoutesFromRepo, enhanceSummaryWithCompetitors, enhanceToolIdea, enrichKeywordsWithEstimates, ensureGitRepo, evaluateAndEnhanceToolIdeas, evaluateToolFeasibility, executeAgent, extractContentHash, extractEntityPhrases, extractImages, extractKeyPhrases, extractLinks, extractMeta, extractNgrams, extractSchema, extractSeedKeywords, extractTopics, fetchCoreWebVitals, findAlmostPage1Keywords, findCTROpportunities, findHtmlEntry, findLSIKeywords, findPageFiles, findTopPerformers, formatAlertMessage, formatCIResult, formatCompetitorReport, formatConventionalCommit, formatFeaturedSnippetReport, formatHeadlineReport, formatIntentReport, formatKeywordDensityReport, formatKeywordReport, formatPRBody, formatPRTitle, formatReadabilityReport, formatReport, formatSEOCommitMessage, formatTopicReport, formatWizardProgress, index as frameworks, generateAICitableContent, generateAllFixes, generateAngularSEOService, generateAspNetCoreSEO, generateAstroBaseHead, generateAstroMeta, generateBlogPost, generateBranchName, generateChangelog, generateCommitSummary, generateComparisonTable, generateCompleteSocialMetaSetup, generateDjangoSEOHelper, generateDuplicateIssues, generateEleventySEO, generateFAQSchema, generateFixes, generateGA4EnvTemplate, generateGA4ReactComponent, generateGA4Script, generateGA4ViteScript, generateGEOReport, generateGSCVerificationTag, generateGitHubActionSetup, generateGoSEO, generateHTMLReport, generateHTMLSocialMeta, generateHTMXSEO, generateHeadlineVariations, generateHugoSEO, generateJekyllSEO, generateJsonReport, generateKeyFacts, generateLaravelSEOHelper, generateMarkdownReport, generateNextAppMetadata, generateNextJsAppRouterMetadata, generateNextJsPagesRouterHead, generateNextPagesHead, generateNuxtSEOHead, generatePDFReport, generatePRDescription, generatePhoenixSEO, generateRailsSEOHelper, generateReactHelmetSocialMeta, generateReactSEOHead, generateRecommendationQueries, generateRemixMeta, generateRemixSEO, generateSecretsDoc, generateSocialMetaFix, generateSpringBootSEO, generateSvelteKitMeta, generateSvelteKitSEOHead, generateUncertaintyQuestions, generateVueSEOHead, generateWizardQuestions, generateWorkflow, getAIVisibilitySummary, getAutocompleteSuggestions, getDateRange, getExpandedSuggestions, getFrameworkSpecificFix, getFrameworkSpecificFixExtended, getGSCSetupInstructions, getGitUser, getKeywordData, getKeywordSuggestions, getMaxKdThreshold, getNextQuestion, getRelatedKeywords, getVisibilityTrend, groupKeywordsByTopic, identifyQuickWins, injectGA4, injectGSCVerification, interpolatePrompt, isGitRepo, listFiles, loadAgent, loadAgentByName, mergePages, optimizeForAI, optimizeReadme, parseGEOResponse, parseGSCResponse, parseSitemap, prioritizeKeywords, processWizardResponse, readFile, routesToUrls, runAIKeywordResearch, runAIReadinessChecks, runAdditionalChecks, runAuditWithFixes, runCIKeywordResearch, runCrawlabilityChecks, runDirectAnalysis, runFullAudit, runKeywordResearch, runNLPAnalysis, runScheduledAudit, scoreContentSEO, scoreMention, searchCompetitors, searchFormatConverters, searchHackerNews, sendAlert, sendAlerts, sendDiscordAlert, sendSlackAlert, shouldRunAudit, shouldSendAlert, startWizardSession, suggestSchemaTypes, summarizeSite, tokenize, tools, trackLLMVisibility, transformGSCData, urlSafetyDatabase, wizardResponsesToContext, writeFile, writeGitHubActionFiles };
+export { type AIContentConfig, type AIKeywordResearchOptions, type AgentDefinition, type AgentTool, type AlertChannel, type AlertConfig, type AlertMessage, type AlertResult, type AlertSeverity, type AlertType, type AuditAlertPayload, type AuditIssue, type AuditIssueData, type AuditOptions, type AuditPRResult, type AuditReport, type AuditReportData, type AuditRunnerOptions, type AuditRunnerResult, type AuditSchedule, type BlogPostConfig, type BrandConfig, type CIAction, type CIKeywordOptions, type CIKeywordResult, COMMIT_TYPES, type ChangelogConfig, type ChangelogResult, type CitationCheckOptions, type CommitConfig, type ComparisonConfig, type ComparisonRow, type CompetitiveInsight, type CompetitiveSearchOptions, type CompetitiveSearchResult, type CompetitorComparison, type CompetitorKeywordResult, type CompetitorOverlap, type CompetitorTool, type CompetitorUrl, type ContentElements, type ContentGeneratorOptions, type ContentRecommendation, type ConventionalCommit, type CrawlResult, type CrawlStats, type CrawledPage, type CreateAuditPROptions, type CreatePROptions, type DataForSEOCredentials, type DiscoveredPage, type EnhancedToolIdea, type ExecOptions, type ExecuteOptions, type ExecutionResult, type FAQItem, type FAQSchemaOptions, type FeaturedSnippetAnalysis, type Fix, type FixFile, type FixGeneratorOptions, type FixResult, type FrameworkInfo$1 as FrameworkInfo, type FreeKeywordResult, type FreeToolIdea, type GA4Config, type GEOAlert, type GEOAlertType, type GEOHistory, type GEOHistoryOptions, type GEOQuery, type GEOReport, type GEOResult, type GEOTrend, type GSCConfig, type GSCCredentials, type GSCPerformanceData, type GSCQueryData, type GSCQueryResult, type GeneratedCode, type GeneratedContent, type GeneratedFix, type HeadingStructure, type HeadlineAnalysis, type HealthScore, ISSUE_DEFINITIONS, type ImageInfo$2 as ImageInfo, type InjectionResult, type IntentAnalysis, type IssueCategory, type IssueDefinition, type IssueSeverity, type KeyFact, type KeyFactsOptions, type KeywordAction, type KeywordCluster, type KeywordData, type KeywordDensityAnalysis, type KeywordLLM, type KeywordOpportunity, type KeywordRecommendation, type KeywordResearchOptions, type KeywordResearchResult, type KeywordStats, type KeywordTopic, type KeywordTrend, type LLMCitationResult, type LLMJudgeOptions, type LLMProvider, LOCATION_CODES, type LSIKeyword, type LinkInfo$1 as LinkInfo, type Mention, type MentionType, type MetaData, type MetaFixOptions, type NGram, type NLPAnalysisResult, OG_IMAGE_SPECS, type OptimizeOptions, type PRConfig, type PRDescription, PRIORITY_WEIGHTS, type PRResult, type PageAudit, type PageData, type PageMeta, type PaidKeywordResult, type ParsedResponse, type PlanTier, type ProviderStats, type QuickWin, type RankCheckOptions, type RankCheckResult, type RankHistory, RankTracker, type RankingResult, type RankingTierLimits, type ReadabilityResult, type ReadmeConfig, type ReadmeResult, type ReportBranding, type ReportConfig, type ReportData, type ReportPageData, type RouteInfo, type SEOAnalysisResult, type SEOFixCommit, type SEOFixSummary, type SEOIssue, type SEORecommendation, type SEOScore, SEO_SCOPES, SITE_PROFILE_QUESTIONS, type ScheduledAuditConfig, type ScheduledAuditResult, type SchemaData, Schemas, type SearchIntent, type Sentiment, type SerpApiConfig, SerpClient, type SerpClientConfig, type SerpFeature, type SiteCrawlResult, type SiteProfile, type SiteSummary, type SnippetRecommendation, type SnippetType, type SocialMetaConfig, type SocialMetaFix, type SummarizerOptions, type TFIDFResult, TIER_LIMITS, type ToolFeasibilityScore, type ToolFunction, type ToolResult, type TopicClusterResult, type TopicModel, type TrackedKeyword, type TrackerConfig, type TrackingOptions, type TrendDirection, type UncertaintyAssessment, type WizardQuestion, type WizardResponse, type WizardResult, type WizardSession, type WorkflowConfig, addTrackingResult, analyzeAnchorText, analyzeCanonicalAdvanced, analyzeClientRendering, analyzeContentFreshness, analyzeDOMStructure, analyzeFeaturedSnippetPotential, analyzeHeadings, analyzeHeadline, analyzeHreflang, analyzeImages$1 as analyzeImages, analyzeKeywordDensity, analyzeKeywords, analyzeLinks, analyzeLocalSEO, analyzeMobile, analyzeModernImages, analyzeOnPage, analyzePagination, analyzePerformance, analyzeReadability, analyzeRedirectChain, analyzeRedirects, analyzeResponsiveImages, analyzeSERPPreview, analyzeSecurity, analyzeSecurityHeaders$1 as analyzeSecurityHeaders, analyzeSocialMeta, analyzeStructuredData$1 as analyzeStructuredData, analyzeTrackerBloat, analyzeUrl, analyzeUrlSafety, index$1 as analyzers, applyFixes, buildGSCApiRequest, buildGSCRequest, calculateAIVisibilityScore, calculateBM25, calculateTFIDF$1 as calculateKeywordTFIDF, calculateNextRun, calculateTFIDF, checkAIBotBlocking, checkAMP, checkAdsTxt, checkAppleTouchIcon, checkBalance, checkCertificate, checkDMARC, checkGitHubCLI, checkInternalRedirects, checkJSRenderingRatio, checkLLMCitations, checkLlmsTxt, checkMobileResources, checkPlaintextEmails, checkRedirects, checkRobots, checkRobotsTxt, checkSPF, checkSitemap, classifyIntent, classifyIntents, clusterKeywordsByEmbedding, compareCompetitorVisibility, comparePeriods, completeWizard, crawlSite, crawlUrl, createAuditPR, createFallbackSummary, createGEOHistory, createPullRequest, createSEOCommit, createSEOCommits, detectDuplicates, detectFramework$1 as detectFramework, detectGitHubPages, detectMentions, detectSoft404, detectTechnologies, detectVisibilityChanges, discoverCompetitorKeywords, discoverPagesFromLinks, discoverRoutesFromRepo, enhanceSummaryWithCompetitors, enhanceToolIdea, enrichKeywordsWithEstimates, ensureGitRepo, evaluateAndEnhanceToolIdeas, evaluateToolFeasibility, executeAgent, extractContentHash, extractEntityPhrases, extractImages, extractKeyPhrases, extractLinks, extractMeta, extractNgrams, extractSchema, extractSeedKeywords, extractTopics, fetchCoreWebVitals, findAlmostPage1Keywords, findCTROpportunities, findHtmlEntry, findLSIKeywords, findPageFiles, findTopPerformers, formatAlertMessage, formatCIResult, formatCompetitorReport, formatConventionalCommit, formatFeaturedSnippetReport, formatHeadlineReport, formatIntentReport, formatKeywordDensityReport, formatKeywordReport, formatPRBody, formatPRTitle, formatReadabilityReport, formatReport, formatSEOCommitMessage, formatTopicReport, formatWizardProgress, index as frameworks, generateAICitableContent, generateAllFixes, generateAngularSEOService, generateAspNetCoreSEO, generateAstroBaseHead, generateAstroMeta, generateBlogPost, generateBranchName, generateChangelog, generateCommitSummary, generateComparisonTable, generateCompleteSocialMetaSetup, generateDjangoSEOHelper, generateDuplicateIssues, generateEleventySEO, generateFAQSchema, generateFixes, generateGA4EnvTemplate, generateGA4ReactComponent, generateGA4Script, generateGA4ViteScript, generateGEOReport, generateGSCVerificationTag, generateGitHubActionSetup, generateGoSEO, generateHTMLReport, generateHTMLSocialMeta, generateHTMXSEO, generateHeadlineVariations, generateHugoSEO, generateJekyllSEO, generateJsonReport, generateKeyFacts, generateLaravelSEOHelper, generateMarkdownReport, generateNextAppMetadata, generateNextJsAppRouterMetadata, generateNextJsPagesRouterHead, generateNextPagesHead, generateNuxtSEOHead, generatePDFReport, generatePRDescription, generatePhoenixSEO, generateRailsSEOHelper, generateReactHelmetSocialMeta, generateReactSEOHead, generateRecommendationQueries, generateRemixMeta, generateRemixSEO, generateSecretsDoc, generateSocialMetaFix, generateSpringBootSEO, generateSvelteKitMeta, generateSvelteKitSEOHead, generateUncertaintyQuestions, generateVueSEOHead, generateWizardQuestions, generateWorkflow, getAIVisibilitySummary, getAutocompleteSuggestions, getDateRange, getExpandedSuggestions, getFrameworkSpecificFix, getFrameworkSpecificFixExtended, getGSCSetupInstructions, getGitUser, getKeywordData, getKeywordSuggestions, getMaxKdThreshold, getNextQuestion, getRelatedKeywords, getVisibilityTrend, groupKeywordsByTopic, identifyQuickWins, injectGA4, injectGSCVerification, interpolatePrompt, isGitRepo, keywordLLM, listFiles, loadAgent, loadAgentByName, mergePages, openAIKeywordLLM, optimizeForAI, optimizeReadme, parseGEOResponse, parseGSCResponse, parseJsonReply, parseSitemap, prioritizeKeywords, processWizardResponse, readFile, routesToUrls, runAIKeywordResearch, runAIReadinessChecks, runAdditionalChecks, runAuditWithFixes, runCIKeywordResearch, runCrawlabilityChecks, runDirectAnalysis, runFullAudit, runKeywordResearch, runNLPAnalysis, runScheduledAudit, scoreContentSEO, scoreMention, searchCompetitors, searchFormatConverters, searchHackerNews, sendAlert, sendAlerts, sendDiscordAlert, sendSlackAlert, shouldRunAudit, shouldSendAlert, startWizardSession, suggestSchemaTypes, summarizeSite, tokenize, tools, trackLLMVisibility, transformGSCData, urlSafetyDatabase, wizardResponsesToContext, writeFile, writeGitHubActionFiles };

package/dist/index.d.ts

@@ -1631,6 +1631,39 @@ declare function runKeywordResearch(options: KeywordResearchOptions): Promise<Ke
 declare function formatKeywordReport(result: KeywordResearchResult): string;
 declare function extractSeedKeywords(url: string): Promise<string[]>;
 
+interface KeywordLLM {
+    /**
+     * A reply to one prompt that asks for a JSON object. `best` asks for the provider's stronger
+     * model where it has one. Replies are parsed with parseJsonReply, never trusted to be clean.
+     */
+    complete(prompt: string, opts?: {
+        system?: string;
+        maxTokens?: number;
+        temperature?: number;
+        best?: boolean;
+    }): Promise<string>;
+    /** Embeddings for keyword clustering. Without it, clustering falls back to term vectors. */
+    embed?(texts: string[]): Promise<number[][]>;
+    /** Most page text worth sending in one prompt: small-context models get less. */
+    maxContentChars?: number;
+    /** How many tool ideas to judge (two calls each): slow local models get fewer. */
+    maxToolIdeas?: number;
+}
+/** The engine's original backend: gpt-4o-mini, gpt-4o for `best`, JSON mode, text-embedding-3-small. */
+declare function openAIKeywordLLM(apiKey: string, opts?: {
+    model?: string;
+}): KeywordLLM;
+/** The model to use: an explicit one, else OpenAI when there's a key, else none. */
+declare function keywordLLM(options: {
+    llm?: KeywordLLM;
+    openaiApiKey?: string;
+}): KeywordLLM | undefined;
+/**
+ * The JSON object in a model reply. Local and small models wrap it in ``` fences, prepend prose
+ * or emit <think> blocks; this takes the outermost {...} and tolerates trailing commas.
+ */
+declare function parseJsonReply(text: string): Record<string, any> | null;
+
 /**
  * Site Crawler for Keyword Research
  *
@@ -1687,7 +1720,7 @@ declare function extractKeyPhrases(crawlResult: SiteCrawlResult): string[];
 /**
  * AI-Powered Site Summarizer
  *
- * Uses OpenAI to understand what a site does from crawled content.
+ * Uses the configured AI provider (llm.ts) to understand what a site does from crawled content.
  * Extracts: product, audience, features, industry, positioning.
  */
 
@@ -1724,7 +1757,10 @@ interface SiteSummary {
     uncertainties: string[];
 }
 interface SummarizerOptions {
-    openaiApiKey: string;
+    /** The model to ask (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
+    openaiApiKey?: string;
+    /** OpenAI model override, with openaiApiKey. */
     model?: string;
     maxTokens?: number;
 }
@@ -1831,10 +1867,12 @@ declare function calculateBM25(documents: string[], query: string, k1?: number,
     docIndex: number;
     score: number;
 }>;
+/** An OpenAI client, or any function returning one embedding per text (llm.ts). */
+type Embedder = OpenAI | ((texts: string[]) => Promise<number[][]>);
 /**
  * Cluster keywords using embeddings
  */
-declare function clusterKeywordsByEmbedding(keywords: string[], openai: OpenAI, numClusters?: number): Promise<KeywordCluster[]>;
+declare function clusterKeywordsByEmbedding(keywords: string[], openai: Embedder, numClusters?: number): Promise<KeywordCluster[]>;
 /**
  * Extract entity-like phrases (capitalized sequences, proper nouns)
  */
@@ -1848,6 +1886,8 @@ declare function extractTopics(documents: string[], numTopics?: number): TopicMo
  * Run full NLP analysis on content
  */
 declare function runNLPAnalysis(content: string | string[], options?: {
+    /** Embeddings come from here when it has them (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
     openaiApiKey?: string;
     numClusters?: number;
     numTopics?: number;
@@ -1871,6 +1911,8 @@ type PlanTier = 'free' | 'solo' | 'pro' | 'agency';
 interface AIKeywordResearchOptions {
     url: string;
     tier: PlanTier;
+    /** The model to ask for paid-tier research (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
     openaiApiKey?: string;
     maxPages?: number;
     userContext?: {
@@ -2066,6 +2108,8 @@ interface WizardResult {
  * Start a new wizard session
  */
 declare function startWizardSession(url: string, options?: {
+    /** The model for the site summary (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
     openaiApiKey?: string;
     existingResponses?: WizardResponse[];
 }): Promise<WizardSession>;
@@ -2370,7 +2414,9 @@ interface EnhancedToolIdea {
     priority: number;
 }
 interface LLMJudgeOptions {
-    openaiApiKey: string;
+    /** The model to ask (see llm.ts); or an OpenAI key, as before. */
+    llm?: KeywordLLM;
+    openaiApiKey?: string;
     minFeasibilityScore?: number;
     minSpecificityScore?: number;
     minProductFitScore?: number;
@@ -4691,11 +4737,9 @@ declare class RankTracker {
      */
     private saveRanking;
     /**
-     * Get ranking history for a keyword
-     * Note: Full history requires keyword_ranking_history table with keyword_ranking_id
-     * For now, returns current state as single history entry
+     * Ranking history for a keyword: one entry per check in the last `days`, newest first.
      */
-    getHistory(keywordId: string, _days?: number): Promise<RankHistory[]>;
+    getHistory(keywordId: string, days?: number): Promise<RankHistory[]>;
     /**
      * Get keyword trends for a project
      */
@@ -5498,4 +5542,4 @@ declare namespace index {
   export { type index_Framework as Framework, type index_FrameworkCheck as FrameworkCheck, type index_FrameworkInfo as FrameworkInfo, type index_FrameworkRecipe as FrameworkRecipe, index_SUPPORTED_FRAMEWORKS as SUPPORTED_FRAMEWORKS, index_detectFramework as detectFramework, index_detectFromHeaders as detectFromHeaders, index_detectFromHtml as detectFromHtml, index_detectFromPackageJson as detectFromPackageJson, index_embedRecipe as embedRecipe, index_getFrameworkChecks as getFrameworkChecks, index_getFrameworkDisplayName as getFrameworkDisplayName, index_getFrameworkIssues as getFrameworkIssues, index_getFrameworkSuggestions as getFrameworkSuggestions, index_getFrameworkSummary as getFrameworkSummary, index_getMigrationPaths as getMigrationPaths, index_getPerformanceTips as getPerformanceTips, index_getSeoChallenges as getSeoChallenges, index_getTotalFrameworkChecks as getTotalFrameworkChecks, index_loadRecipe as loadRecipe };
 }
 
-export { type AIContentConfig, type AIKeywordResearchOptions, type AgentDefinition, type AgentTool, type AlertChannel, type AlertConfig, type AlertMessage, type AlertResult, type AlertSeverity, type AlertType, type AuditAlertPayload, type AuditIssue, type AuditIssueData, type AuditOptions, type AuditPRResult, type AuditReport, type AuditReportData, type AuditRunnerOptions, type AuditRunnerResult, type AuditSchedule, type BlogPostConfig, type BrandConfig, type CIAction, type CIKeywordOptions, type CIKeywordResult, COMMIT_TYPES, type ChangelogConfig, type ChangelogResult, type CitationCheckOptions, type CommitConfig, type ComparisonConfig, type ComparisonRow, type CompetitiveInsight, type CompetitiveSearchOptions, type CompetitiveSearchResult, type CompetitorComparison, type CompetitorKeywordResult, type CompetitorOverlap, type CompetitorTool, type CompetitorUrl, type ContentElements, type ContentGeneratorOptions, type ContentRecommendation, type ConventionalCommit, type CrawlResult, type CrawlStats, type CrawledPage, type CreateAuditPROptions, type CreatePROptions, type DataForSEOCredentials, type DiscoveredPage, type EnhancedToolIdea, type ExecOptions, type ExecuteOptions, type ExecutionResult, type FAQItem, type FAQSchemaOptions, type FeaturedSnippetAnalysis, type Fix, type FixFile, type FixGeneratorOptions, type FixResult, type FrameworkInfo$1 as FrameworkInfo, type FreeKeywordResult, type FreeToolIdea, type GA4Config, type GEOAlert, type GEOAlertType, type GEOHistory, type GEOHistoryOptions, type GEOQuery, type GEOReport, type GEOResult, type GEOTrend, type GSCConfig, type GSCCredentials, type GSCPerformanceData, type GSCQueryData, type GSCQueryResult, type GeneratedCode, type GeneratedContent, type GeneratedFix, type HeadingStructure, type HeadlineAnalysis, type HealthScore, ISSUE_DEFINITIONS, type ImageInfo$2 as ImageInfo, type InjectionResult, type IntentAnalysis, type IssueCategory, type IssueDefinition, type IssueSeverity, type KeyFact, type KeyFactsOptions, type KeywordAction, type KeywordCluster, type KeywordData, type KeywordDensityAnalysis, type KeywordOpportunity, type KeywordRecommendation, type KeywordResearchOptions, type KeywordResearchResult, type KeywordStats, type KeywordTopic, type KeywordTrend, type LLMCitationResult, type LLMJudgeOptions, type LLMProvider, LOCATION_CODES, type LSIKeyword, type LinkInfo$1 as LinkInfo, type Mention, type MentionType, type MetaData, type MetaFixOptions, type NGram, type NLPAnalysisResult, OG_IMAGE_SPECS, type OptimizeOptions, type PRConfig, type PRDescription, PRIORITY_WEIGHTS, type PRResult, type PageAudit, type PageData, type PageMeta, type PaidKeywordResult, type ParsedResponse, type PlanTier, type ProviderStats, type QuickWin, type RankCheckOptions, type RankCheckResult, type RankHistory, RankTracker, type RankingResult, type RankingTierLimits, type ReadabilityResult, type ReadmeConfig, type ReadmeResult, type ReportBranding, type ReportConfig, type ReportData, type ReportPageData, type RouteInfo, type SEOAnalysisResult, type SEOFixCommit, type SEOFixSummary, type SEOIssue, type SEORecommendation, type SEOScore, SEO_SCOPES, SITE_PROFILE_QUESTIONS, type ScheduledAuditConfig, type ScheduledAuditResult, type SchemaData, Schemas, type SearchIntent, type Sentiment, type SerpApiConfig, SerpClient, type SerpClientConfig, type SerpFeature, type SiteCrawlResult, type SiteProfile, type SiteSummary, type SnippetRecommendation, type SnippetType, type SocialMetaConfig, type SocialMetaFix, type SummarizerOptions, type TFIDFResult, TIER_LIMITS, type ToolFeasibilityScore, type ToolFunction, type ToolResult, type TopicClusterResult, type TopicModel, type TrackedKeyword, type TrackerConfig, type TrackingOptions, type TrendDirection, type UncertaintyAssessment, type WizardQuestion, type WizardResponse, type WizardResult, type WizardSession, type WorkflowConfig, addTrackingResult, analyzeAnchorText, analyzeCanonicalAdvanced, analyzeClientRendering, analyzeContentFreshness, analyzeDOMStructure, analyzeFeaturedSnippetPotential, analyzeHeadings, analyzeHeadline, analyzeHreflang, analyzeImages$1 as analyzeImages, analyzeKeywordDensity, analyzeKeywords, analyzeLinks, analyzeLocalSEO, analyzeMobile, analyzeModernImages, analyzeOnPage, analyzePagination, analyzePerformance, analyzeReadability, analyzeRedirectChain, analyzeRedirects, analyzeResponsiveImages, analyzeSERPPreview, analyzeSecurity, analyzeSecurityHeaders$1 as analyzeSecurityHeaders, analyzeSocialMeta, analyzeStructuredData$1 as analyzeStructuredData, analyzeTrackerBloat, analyzeUrl, analyzeUrlSafety, index$1 as analyzers, applyFixes, buildGSCApiRequest, buildGSCRequest, calculateAIVisibilityScore, calculateBM25, calculateTFIDF$1 as calculateKeywordTFIDF, calculateNextRun, calculateTFIDF, checkAIBotBlocking, checkAMP, checkAdsTxt, checkAppleTouchIcon, checkBalance, checkCertificate, checkDMARC, checkGitHubCLI, checkInternalRedirects, checkJSRenderingRatio, checkLLMCitations, checkLlmsTxt, checkMobileResources, checkPlaintextEmails, checkRedirects, checkRobots, checkRobotsTxt, checkSPF, checkSitemap, classifyIntent, classifyIntents, clusterKeywordsByEmbedding, compareCompetitorVisibility, comparePeriods, completeWizard, crawlSite, crawlUrl, createAuditPR, createFallbackSummary, createGEOHistory, createPullRequest, createSEOCommit, createSEOCommits, detectDuplicates, detectFramework$1 as detectFramework, detectGitHubPages, detectMentions, detectSoft404, detectTechnologies, detectVisibilityChanges, discoverCompetitorKeywords, discoverPagesFromLinks, discoverRoutesFromRepo, enhanceSummaryWithCompetitors, enhanceToolIdea, enrichKeywordsWithEstimates, ensureGitRepo, evaluateAndEnhanceToolIdeas, evaluateToolFeasibility, executeAgent, extractContentHash, extractEntityPhrases, extractImages, extractKeyPhrases, extractLinks, extractMeta, extractNgrams, extractSchema, extractSeedKeywords, extractTopics, fetchCoreWebVitals, findAlmostPage1Keywords, findCTROpportunities, findHtmlEntry, findLSIKeywords, findPageFiles, findTopPerformers, formatAlertMessage, formatCIResult, formatCompetitorReport, formatConventionalCommit, formatFeaturedSnippetReport, formatHeadlineReport, formatIntentReport, formatKeywordDensityReport, formatKeywordReport, formatPRBody, formatPRTitle, formatReadabilityReport, formatReport, formatSEOCommitMessage, formatTopicReport, formatWizardProgress, index as frameworks, generateAICitableContent, generateAllFixes, generateAngularSEOService, generateAspNetCoreSEO, generateAstroBaseHead, generateAstroMeta, generateBlogPost, generateBranchName, generateChangelog, generateCommitSummary, generateComparisonTable, generateCompleteSocialMetaSetup, generateDjangoSEOHelper, generateDuplicateIssues, generateEleventySEO, generateFAQSchema, generateFixes, generateGA4EnvTemplate, generateGA4ReactComponent, generateGA4Script, generateGA4ViteScript, generateGEOReport, generateGSCVerificationTag, generateGitHubActionSetup, generateGoSEO, generateHTMLReport, generateHTMLSocialMeta, generateHTMXSEO, generateHeadlineVariations, generateHugoSEO, generateJekyllSEO, generateJsonReport, generateKeyFacts, generateLaravelSEOHelper, generateMarkdownReport, generateNextAppMetadata, generateNextJsAppRouterMetadata, generateNextJsPagesRouterHead, generateNextPagesHead, generateNuxtSEOHead, generatePDFReport, generatePRDescription, generatePhoenixSEO, generateRailsSEOHelper, generateReactHelmetSocialMeta, generateReactSEOHead, generateRecommendationQueries, generateRemixMeta, generateRemixSEO, generateSecretsDoc, generateSocialMetaFix, generateSpringBootSEO, generateSvelteKitMeta, generateSvelteKitSEOHead, generateUncertaintyQuestions, generateVueSEOHead, generateWizardQuestions, generateWorkflow, getAIVisibilitySummary, getAutocompleteSuggestions, getDateRange, getExpandedSuggestions, getFrameworkSpecificFix, getFrameworkSpecificFixExtended, getGSCSetupInstructions, getGitUser, getKeywordData, getKeywordSuggestions, getMaxKdThreshold, getNextQuestion, getRelatedKeywords, getVisibilityTrend, groupKeywordsByTopic, identifyQuickWins, injectGA4, injectGSCVerification, interpolatePrompt, isGitRepo, listFiles, loadAgent, loadAgentByName, mergePages, optimizeForAI, optimizeReadme, parseGEOResponse, parseGSCResponse, parseSitemap, prioritizeKeywords, processWizardResponse, readFile, routesToUrls, runAIKeywordResearch, runAIReadinessChecks, runAdditionalChecks, runAuditWithFixes, runCIKeywordResearch, runCrawlabilityChecks, runDirectAnalysis, runFullAudit, runKeywordResearch, runNLPAnalysis, runScheduledAudit, scoreContentSEO, scoreMention, searchCompetitors, searchFormatConverters, searchHackerNews, sendAlert, sendAlerts, sendDiscordAlert, sendSlackAlert, shouldRunAudit, shouldSendAlert, startWizardSession, suggestSchemaTypes, summarizeSite, tokenize, tools, trackLLMVisibility, transformGSCData, urlSafetyDatabase, wizardResponsesToContext, writeFile, writeGitHubActionFiles };
+export { type AIContentConfig, type AIKeywordResearchOptions, type AgentDefinition, type AgentTool, type AlertChannel, type AlertConfig, type AlertMessage, type AlertResult, type AlertSeverity, type AlertType, type AuditAlertPayload, type AuditIssue, type AuditIssueData, type AuditOptions, type AuditPRResult, type AuditReport, type AuditReportData, type AuditRunnerOptions, type AuditRunnerResult, type AuditSchedule, type BlogPostConfig, type BrandConfig, type CIAction, type CIKeywordOptions, type CIKeywordResult, COMMIT_TYPES, type ChangelogConfig, type ChangelogResult, type CitationCheckOptions, type CommitConfig, type ComparisonConfig, type ComparisonRow, type CompetitiveInsight, type CompetitiveSearchOptions, type CompetitiveSearchResult, type CompetitorComparison, type CompetitorKeywordResult, type CompetitorOverlap, type CompetitorTool, type CompetitorUrl, type ContentElements, type ContentGeneratorOptions, type ContentRecommendation, type ConventionalCommit, type CrawlResult, type CrawlStats, type CrawledPage, type CreateAuditPROptions, type CreatePROptions, type DataForSEOCredentials, type DiscoveredPage, type EnhancedToolIdea, type ExecOptions, type ExecuteOptions, type ExecutionResult, type FAQItem, type FAQSchemaOptions, type FeaturedSnippetAnalysis, type Fix, type FixFile, type FixGeneratorOptions, type FixResult, type FrameworkInfo$1 as FrameworkInfo, type FreeKeywordResult, type FreeToolIdea, type GA4Config, type GEOAlert, type GEOAlertType, type GEOHistory, type GEOHistoryOptions, type GEOQuery, type GEOReport, type GEOResult, type GEOTrend, type GSCConfig, type GSCCredentials, type GSCPerformanceData, type GSCQueryData, type GSCQueryResult, type GeneratedCode, type GeneratedContent, type GeneratedFix, type HeadingStructure, type HeadlineAnalysis, type HealthScore, ISSUE_DEFINITIONS, type ImageInfo$2 as ImageInfo, type InjectionResult, type IntentAnalysis, type IssueCategory, type IssueDefinition, type IssueSeverity, type KeyFact, type KeyFactsOptions, type KeywordAction, type KeywordCluster, type KeywordData, type KeywordDensityAnalysis, type KeywordLLM, type KeywordOpportunity, type KeywordRecommendation, type KeywordResearchOptions, type KeywordResearchResult, type KeywordStats, type KeywordTopic, type KeywordTrend, type LLMCitationResult, type LLMJudgeOptions, type LLMProvider, LOCATION_CODES, type LSIKeyword, type LinkInfo$1 as LinkInfo, type Mention, type MentionType, type MetaData, type MetaFixOptions, type NGram, type NLPAnalysisResult, OG_IMAGE_SPECS, type OptimizeOptions, type PRConfig, type PRDescription, PRIORITY_WEIGHTS, type PRResult, type PageAudit, type PageData, type PageMeta, type PaidKeywordResult, type ParsedResponse, type PlanTier, type ProviderStats, type QuickWin, type RankCheckOptions, type RankCheckResult, type RankHistory, RankTracker, type RankingResult, type RankingTierLimits, type ReadabilityResult, type ReadmeConfig, type ReadmeResult, type ReportBranding, type ReportConfig, type ReportData, type ReportPageData, type RouteInfo, type SEOAnalysisResult, type SEOFixCommit, type SEOFixSummary, type SEOIssue, type SEORecommendation, type SEOScore, SEO_SCOPES, SITE_PROFILE_QUESTIONS, type ScheduledAuditConfig, type ScheduledAuditResult, type SchemaData, Schemas, type SearchIntent, type Sentiment, type SerpApiConfig, SerpClient, type SerpClientConfig, type SerpFeature, type SiteCrawlResult, type SiteProfile, type SiteSummary, type SnippetRecommendation, type SnippetType, type SocialMetaConfig, type SocialMetaFix, type SummarizerOptions, type TFIDFResult, TIER_LIMITS, type ToolFeasibilityScore, type ToolFunction, type ToolResult, type TopicClusterResult, type TopicModel, type TrackedKeyword, type TrackerConfig, type TrackingOptions, type TrendDirection, type UncertaintyAssessment, type WizardQuestion, type WizardResponse, type WizardResult, type WizardSession, type WorkflowConfig, addTrackingResult, analyzeAnchorText, analyzeCanonicalAdvanced, analyzeClientRendering, analyzeContentFreshness, analyzeDOMStructure, analyzeFeaturedSnippetPotential, analyzeHeadings, analyzeHeadline, analyzeHreflang, analyzeImages$1 as analyzeImages, analyzeKeywordDensity, analyzeKeywords, analyzeLinks, analyzeLocalSEO, analyzeMobile, analyzeModernImages, analyzeOnPage, analyzePagination, analyzePerformance, analyzeReadability, analyzeRedirectChain, analyzeRedirects, analyzeResponsiveImages, analyzeSERPPreview, analyzeSecurity, analyzeSecurityHeaders$1 as analyzeSecurityHeaders, analyzeSocialMeta, analyzeStructuredData$1 as analyzeStructuredData, analyzeTrackerBloat, analyzeUrl, analyzeUrlSafety, index$1 as analyzers, applyFixes, buildGSCApiRequest, buildGSCRequest, calculateAIVisibilityScore, calculateBM25, calculateTFIDF$1 as calculateKeywordTFIDF, calculateNextRun, calculateTFIDF, checkAIBotBlocking, checkAMP, checkAdsTxt, checkAppleTouchIcon, checkBalance, checkCertificate, checkDMARC, checkGitHubCLI, checkInternalRedirects, checkJSRenderingRatio, checkLLMCitations, checkLlmsTxt, checkMobileResources, checkPlaintextEmails, checkRedirects, checkRobots, checkRobotsTxt, checkSPF, checkSitemap, classifyIntent, classifyIntents, clusterKeywordsByEmbedding, compareCompetitorVisibility, comparePeriods, completeWizard, crawlSite, crawlUrl, createAuditPR, createFallbackSummary, createGEOHistory, createPullRequest, createSEOCommit, createSEOCommits, detectDuplicates, detectFramework$1 as detectFramework, detectGitHubPages, detectMentions, detectSoft404, detectTechnologies, detectVisibilityChanges, discoverCompetitorKeywords, discoverPagesFromLinks, discoverRoutesFromRepo, enhanceSummaryWithCompetitors, enhanceToolIdea, enrichKeywordsWithEstimates, ensureGitRepo, evaluateAndEnhanceToolIdeas, evaluateToolFeasibility, executeAgent, extractContentHash, extractEntityPhrases, extractImages, extractKeyPhrases, extractLinks, extractMeta, extractNgrams, extractSchema, extractSeedKeywords, extractTopics, fetchCoreWebVitals, findAlmostPage1Keywords, findCTROpportunities, findHtmlEntry, findLSIKeywords, findPageFiles, findTopPerformers, formatAlertMessage, formatCIResult, formatCompetitorReport, formatConventionalCommit, formatFeaturedSnippetReport, formatHeadlineReport, formatIntentReport, formatKeywordDensityReport, formatKeywordReport, formatPRBody, formatPRTitle, formatReadabilityReport, formatReport, formatSEOCommitMessage, formatTopicReport, formatWizardProgress, index as frameworks, generateAICitableContent, generateAllFixes, generateAngularSEOService, generateAspNetCoreSEO, generateAstroBaseHead, generateAstroMeta, generateBlogPost, generateBranchName, generateChangelog, generateCommitSummary, generateComparisonTable, generateCompleteSocialMetaSetup, generateDjangoSEOHelper, generateDuplicateIssues, generateEleventySEO, generateFAQSchema, generateFixes, generateGA4EnvTemplate, generateGA4ReactComponent, generateGA4Script, generateGA4ViteScript, generateGEOReport, generateGSCVerificationTag, generateGitHubActionSetup, generateGoSEO, generateHTMLReport, generateHTMLSocialMeta, generateHTMXSEO, generateHeadlineVariations, generateHugoSEO, generateJekyllSEO, generateJsonReport, generateKeyFacts, generateLaravelSEOHelper, generateMarkdownReport, generateNextAppMetadata, generateNextJsAppRouterMetadata, generateNextJsPagesRouterHead, generateNextPagesHead, generateNuxtSEOHead, generatePDFReport, generatePRDescription, generatePhoenixSEO, generateRailsSEOHelper, generateReactHelmetSocialMeta, generateReactSEOHead, generateRecommendationQueries, generateRemixMeta, generateRemixSEO, generateSecretsDoc, generateSocialMetaFix, generateSpringBootSEO, generateSvelteKitMeta, generateSvelteKitSEOHead, generateUncertaintyQuestions, generateVueSEOHead, generateWizardQuestions, generateWorkflow, getAIVisibilitySummary, getAutocompleteSuggestions, getDateRange, getExpandedSuggestions, getFrameworkSpecificFix, getFrameworkSpecificFixExtended, getGSCSetupInstructions, getGitUser, getKeywordData, getKeywordSuggestions, getMaxKdThreshold, getNextQuestion, getRelatedKeywords, getVisibilityTrend, groupKeywordsByTopic, identifyQuickWins, injectGA4, injectGSCVerification, interpolatePrompt, isGitRepo, keywordLLM, listFiles, loadAgent, loadAgentByName, mergePages, openAIKeywordLLM, optimizeForAI, optimizeReadme, parseGEOResponse, parseGSCResponse, parseJsonReply, parseSitemap, prioritizeKeywords, processWizardResponse, readFile, routesToUrls, runAIKeywordResearch, runAIReadinessChecks, runAdditionalChecks, runAuditWithFixes, runCIKeywordResearch, runCrawlabilityChecks, runDirectAnalysis, runFullAudit, runKeywordResearch, runNLPAnalysis, runScheduledAudit, scoreContentSEO, scoreMention, searchCompetitors, searchFormatConverters, searchHackerNews, sendAlert, sendAlerts, sendDiscordAlert, sendSlackAlert, shouldRunAudit, shouldSendAlert, startWizardSession, suggestSchemaTypes, summarizeSite, tokenize, tools, trackLLMVisibility, transformGSCData, urlSafetyDatabase, wizardResponsesToContext, writeFile, writeGitHubActionFiles };

package/dist/index.js

@@ -3515,14 +3515,17 @@ __export(index_exports, {
   injectGSCVerification: () => injectGSCVerification,
   interpolatePrompt: () => interpolatePrompt,
   isGitRepo: () => isGitRepo,
+  keywordLLM: () => keywordLLM,
   listFiles: () => listFiles,
   loadAgent: () => loadAgent,
   loadAgentByName: () => loadAgentByName,
   mergePages: () => mergePages,
+  openAIKeywordLLM: () => openAIKeywordLLM,
   optimizeForAI: () => optimizeForAI,
   optimizeReadme: () => optimizeReadme,
   parseGEOResponse: () => parseGEOResponse,
   parseGSCResponse: () => parseGSCResponse,
+  parseJsonReply: () => parseJsonReply,
   parseSitemap: () => parseSitemap,
   prioritizeKeywords: () => prioritizeKeywords,
   processWizardResponse: () => processWizardResponse,
@@ -7844,21 +7847,28 @@ var HTML_SIGNATURES = [
   {
     framework: "wordpress",
     language: "php",
-    patterns: [/wp-content/, /wp-includes/, /wp-json/, /wordpress/i],
+    // Technical signatures only. These patterns run over the whole page, so the old
+    // /wordpress/i matched the word anywhere in the copy: rankcli.dev's own "detects
+    // Rails, Django, Laravel, and WordPress" line was enough to detect its React SPA as
+    // WordPress and then tell it to install an SEO plugin. A generator meta tag is the
+    // one place the page says it about itself.
+    patterns: [/wp-content/, /wp-includes/, /wp-json/, /name=["']generator["'][^>]*content=["']WordPress/i],
     confidence: "high"
   },
   // Laravel
   {
     framework: "laravel",
     language: "php",
-    patterns: [/laravel_session/, /XSRF-TOKEN/, /@csrf/, /laravel/i],
+    // /laravel/i had the same problem as WordPress above - it matched the word in prose.
+    patterns: [/laravel_session/, /XSRF-TOKEN/, /@csrf/],
     confidence: "medium"
   },
   // Symfony
   {
     framework: "symfony",
     language: "php",
-    patterns: [/symfony/, /sf2/, /_sf_/, /profiler\.css/],
+    // Likewise /symfony/, which matched any lowercase mention.
+    patterns: [/sf2/, /_sf_/, /profiler\.css/],
     confidence: "medium"
   },
   // ============ Ruby Frameworks ============
@@ -20111,6 +20121,50 @@ async function extractSeedKeywords(url) {
   }
 }
 
+// src/keywords/llm.ts
+var import_openai = __toESM(require("openai"));
+function openAIKeywordLLM(apiKey, opts = {}) {
+  const openai = new import_openai.default({ apiKey });
+  const openAIModel = opts.model;
+  return {
+    async complete(prompt, opts2 = {}) {
+      const response = await openai.chat.completions.create({
+        model: opts2.best ? "gpt-4o" : openAIModel ?? "gpt-4o-mini",
+        messages: [
+          ...opts2.system ? [{ role: "system", content: opts2.system }] : [],
+          { role: "user", content: prompt }
+        ],
+        response_format: { type: "json_object" },
+        temperature: opts2.temperature ?? 0.3,
+        ...opts2.maxTokens ? { max_tokens: opts2.maxTokens } : {}
+      });
+      return response.choices[0]?.message?.content || "";
+    },
+    async embed(texts) {
+      const response = await openai.embeddings.create({ model: "text-embedding-3-small", input: texts });
+      return response.data.map((item) => item.embedding);
+    }
+  };
+}
+function keywordLLM(options) {
+  return options.llm ?? (options.openaiApiKey ? openAIKeywordLLM(options.openaiApiKey) : void 0);
+}
+function parseJsonReply(text) {
+  const cleaned = text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  const candidate = cleaned.slice(start, end + 1);
+  for (const attempt of [candidate, candidate.replace(/,\s*([}\]])/g, "$1")]) {
+    try {
+      const parsed = JSON.parse(attempt);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    } catch {
+    }
+  }
+  return null;
+}
+
 // src/keywords/site-crawler.ts
 var cheerio40 = __toESM(require("cheerio"));
 init_http();
@@ -20321,7 +20375,11 @@ function extractKeyPhrases(crawlResult) {
 }
 
 // src/keywords/ai-summarizer.ts
-var import_openai = __toESM(require("openai"));
+function summarizerLLM(options) {
+  const llm = options.llm ?? (options.openaiApiKey ? openAIKeywordLLM(options.openaiApiKey, { model: options.model }) : void 0);
+  if (!llm) throw new Error("An AI provider is required to summarize the site");
+  return llm;
+}
 var SUMMARIZER_PROMPT = `You are an expert SEO analyst. Analyze the following website content and extract key information for keyword research.
 
 WEBSITE CONTENT:
@@ -20364,37 +20422,26 @@ IMPORTANT:
 
 Respond ONLY with the JSON object, no other text.`;
 async function summarizeSite(crawlResult, options) {
-  const openai = new import_openai.default({ apiKey: options.openaiApiKey });
-  const model = options.model || "gpt-4o-mini";
+  const llm = summarizerLLM(options);
+  const maxContent = llm.maxContentChars ?? 15e3;
   let content = crawlResult.aggregatedContent;
-  if (content.length > 15e3) {
-    content = content.substring(0, 15e3) + "\n...[truncated]";
+  if (content.length > maxContent) {
+    content = content.substring(0, maxContent) + "\n...[truncated]";
   }
   const headings = crawlResult.uniqueHeadings.slice(0, 30).join("\n");
   const prompt = SUMMARIZER_PROMPT.replace("{content}", content).replace("{headings}", headings).replace("{productPages}", String(crawlResult.detectedPageTypes.product)).replace("{pricingPages}", String(crawlResult.detectedPageTypes.pricing)).replace("{blogPages}", String(crawlResult.detectedPageTypes.blog)).replace("{featurePages}", String(crawlResult.detectedPageTypes.feature));
   console.log("\u{1F916} Analyzing site content with AI...");
   try {
-    const response = await openai.chat.completions.create({
-      model,
-      messages: [
-        {
-          role: "system",
-          content: "You are an expert SEO analyst. Always respond with valid JSON only."
-        },
-        {
-          role: "user",
-          content: prompt
-        }
-      ],
+    const responseText = await llm.complete(prompt, {
+      system: "You are an expert SEO analyst. Always respond with valid JSON only.",
       temperature: 0.3,
-      max_tokens: options.maxTokens || 2e3
+      maxTokens: options.maxTokens || 2e3
     });
-    const responseText = response.choices[0]?.message?.content || "";
-    const jsonMatch = responseText.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) {
+    const parsed = parseJsonReply(responseText);
+    if (!parsed) {
       throw new Error("No JSON found in response");
     }
-    const summary = JSON.parse(jsonMatch[0]);
+    const summary = parsed;
     return {
       productName: summary.productName || "Unknown Product",
       productDescription: summary.productDescription || "No description available",
@@ -20456,7 +20503,7 @@ function createFallbackSummary(crawlResult) {
   };
 }
 async function enhanceSummaryWithCompetitors(summary, competitors, options) {
-  const openai = new import_openai.default({ apiKey: options.openaiApiKey });
+  const llm = summarizerLLM(options);
   const prompt = `Given this product summary:
 Product: ${summary.productName}
 Description: ${summary.productDescription}
@@ -20475,19 +20522,13 @@ Analyze the competitive positioning. If this product focuses on a niche segment
   "updatedUncertainties": ["uncertainty1", "uncertainty2"]
 }`;
   try {
-    const response = await openai.chat.completions.create({
-      model: options.model || "gpt-4o-mini",
-      messages: [
-        { role: "system", content: "Respond with valid JSON only." },
-        { role: "user", content: prompt }
-      ],
+    const responseText = await llm.complete(prompt, {
+      system: "Respond with valid JSON only.",
       temperature: 0.3,
-      max_tokens: 1e3
+      maxTokens: 1e3
     });
-    const responseText = response.choices[0]?.message?.content || "";
-    const jsonMatch = responseText.match(/\{[\s\S]*\}/);
-    if (jsonMatch) {
-      const analysis = JSON.parse(jsonMatch[0]);
+    const analysis = parseJsonReply(responseText);
+    if (analysis) {
       return {
         ...summary,
         competitivePositioning: analysis.competitivePositioning || "",
@@ -20574,7 +20615,6 @@ function generateUncertaintyQuestions(summary) {
 }
 
 // src/keywords/nlp-analysis.ts
-var import_openai2 = __toESM(require("openai"));
 var STOP_WORDS2 = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -20859,19 +20899,18 @@ function createTermVectors(keywords, vocabulary) {
     return vector;
   });
 }
+async function embedBatch(embedder, batch) {
+  if (typeof embedder === "function") return embedder(batch);
+  const response = await embedder.embeddings.create({ model: "text-embedding-3-small", input: batch });
+  return response.data.map((item) => item.embedding);
+}
 async function getEmbeddings(texts, openai) {
   const embeddings = [];
   const batchSize = 100;
   for (let i = 0; i < texts.length; i += batchSize) {
     const batch = texts.slice(i, i + batchSize);
     try {
-      const response = await openai.embeddings.create({
-        model: "text-embedding-3-small",
-        input: batch
-      });
-      for (const item of response.data) {
-        embeddings.push(item.embedding);
-      }
+      embeddings.push(...await embedBatch(openai, batch));
     } catch (error) {
       console.warn("Embedding API failed, using fallback BOW vectors");
       for (const text of batch) {
@@ -21026,12 +21065,12 @@ async function runNLPAnalysis(content, options = {}) {
   const entityPhrases = extractEntityPhrases(combinedText);
   let clusters = [];
   const keywordsToCluster = tfidfKeywords.slice(0, 50).map((k) => k.term);
-  if (options.openaiApiKey && keywordsToCluster.length > 0) {
+  const embed = keywordLLM(options)?.embed;
+  if (embed && keywordsToCluster.length > 0) {
     try {
-      const openai = new import_openai2.default({ apiKey: options.openaiApiKey });
       clusters = await clusterKeywordsByEmbedding(
         keywordsToCluster,
-        openai,
+        (texts) => embed(texts),
         options.numClusters
       );
     } catch (error) {
@@ -21374,9 +21413,13 @@ async function searchHackerNews(query, maxResults = 10) {
 }
 
 // src/keywords/llm-judge.ts
-var import_openai3 = __toESM(require("openai"));
+function judgeLLM(options) {
+  const llm = keywordLLM(options);
+  if (!llm) throw new Error("An AI provider is required to judge tool ideas");
+  return llm;
+}
 async function evaluateToolFeasibility(toolIdea, siteSummary, competitiveData, options) {
-  const openai = new import_openai3.default({ apiKey: options.openaiApiKey });
+  const llm = judgeLLM(options);
   const minFeasibility = options.minFeasibilityScore ?? 3;
   const minSpecificity = options.minSpecificityScore ?? 3;
   const minProductFit = options.minProductFitScore ?? 2;
@@ -21452,13 +21495,10 @@ Respond in JSON:
   "blockers": ["<issues that prevent building>"],
   "improvements": ["<suggestions to make it more specific/buildable>"]
 }`;
-  const response = await openai.chat.completions.create({
-    model: "gpt-4o-mini",
-    messages: [{ role: "user", content: prompt }],
-    response_format: { type: "json_object" },
-    temperature: 0.3
-  });
-  const result = JSON.parse(response.choices[0].message.content || "{}");
+  const result = parseJsonReply(await llm.complete(prompt, { temperature: 0.3 })) ?? {};
+  for (const key of ["feasibility", "specificity", "productFit", "marketOpportunity"]) {
+    result[key] = Number(result[key]) || 0;
+  }
   const overallScore = result.feasibility * 0.3 + result.specificity * 0.3 + result.productFit * 0.2 + result.marketOpportunity * 0.2;
   const passes = result.feasibility >= minFeasibility && result.specificity >= minSpecificity && result.productFit >= minProductFit;
   return {
@@ -21474,7 +21514,7 @@ Respond in JSON:
   };
 }
 async function enhanceToolIdea(toolIdea, siteSummary, competitiveData, options) {
-  const openai = new import_openai3.default({ apiKey: options.openaiApiKey });
+  const llm = judgeLLM(options);
   const feasibilityScore = await evaluateToolFeasibility(
     toolIdea,
     siteSummary,
@@ -21519,13 +21559,7 @@ ${competitiveData?.openSourceOptions.slice(0, 3).map((t) => `- OSS: ${t.name} ($
   "canUseExistingOSS": <true if an OSS library does most of the work>,
   "ossLibrary": "<name of OSS library to use, or null>"
 }`;
-  const response = await openai.chat.completions.create({
-    model: "gpt-4o",
-    messages: [{ role: "user", content: prompt }],
-    response_format: { type: "json_object" },
-    temperature: 0.5
-  });
-  const enhanced = JSON.parse(response.choices[0].message.content || "{}");
+  const enhanced = parseJsonReply(await llm.complete(prompt, { temperature: 0.5, best: true })) ?? {};
   const priority = Math.round(
     feasibilityScore.overallScore * 20 + toolIdea.volume / 1e3 * 10 + (100 - toolIdea.difficulty) / 100 * 20
   );
@@ -21576,7 +21610,7 @@ async function evaluateAndEnhanceToolIdeas(toolIdeas, siteSummary, getCompetitiv
 
 // src/keywords/ai-keyword-engine.ts
 async function runAIKeywordResearch(options) {
-  const { url, tier, openaiApiKey, maxPages = 20 } = options;
+  const { url, tier, maxPages = 20 } = options;
   console.log(`
 \u{1F52C} Starting AI Keyword Research (${tier} tier)...
 `);
@@ -21584,10 +21618,11 @@ async function runAIKeywordResearch(options) {
   if (tier === "free") {
     return runFreeKeywordResearch(crawlResult, options);
   } else {
-    if (!openaiApiKey) {
-      throw new Error("OpenAI API key required for paid tier keyword research");
+    const llm = keywordLLM(options);
+    if (!llm) {
+      throw new Error("An AI provider (or an OpenAI API key) is required for paid tier keyword research");
     }
-    return runPaidKeywordResearch(crawlResult, options);
+    return runPaidKeywordResearch(crawlResult, options, llm);
   }
 }
 async function runFreeKeywordResearch(crawlResult, options) {
@@ -21641,13 +21676,11 @@ async function runFreeKeywordResearch(crawlResult, options) {
     ]
   };
 }
-async function runPaidKeywordResearch(crawlResult, options) {
-  const { openaiApiKey, userContext, wizardResponses, ciMode, competitiveSearchKeys } = options;
+async function runPaidKeywordResearch(crawlResult, options, llm) {
+  const { userContext, wizardResponses, ciMode, competitiveSearchKeys } = options;
   const enableEnhancedToolIdeas = options.enableEnhancedToolIdeas !== false;
   console.log("\u{1F680} Running full AI analysis...");
-  let siteSummary = await summarizeSite(crawlResult, {
-    openaiApiKey
-  });
+  let siteSummary = await summarizeSite(crawlResult, { llm });
   if (userContext) {
     siteSummary = applyUserContext(siteSummary, userContext);
   }
@@ -21656,7 +21689,7 @@ async function runPaidKeywordResearch(crawlResult, options) {
   }
   const documents = crawlResult.pages.map((p) => p.mainContent);
   const nlpAnalysis = await runNLPAnalysis(documents, {
-    openaiApiKey,
+    llm,
     numClusters: 8,
     numTopics: 6
   });
@@ -21683,13 +21716,13 @@ async function runPaidKeywordResearch(crawlResult, options) {
     nlpAnalysis
   );
   let freeToolIdeas;
-  if (enableEnhancedToolIdeas && openaiApiKey) {
+  if (enableEnhancedToolIdeas) {
     console.log("\u{1F52C} Running enhanced tool idea analysis with competitive research...");
     freeToolIdeas = await generateEnhancedFreeToolIdeas(
       opportunities,
       siteSummary,
       {
-        openaiApiKey,
+        llm,
         ...competitiveSearchKeys
       }
     );
@@ -21787,7 +21820,7 @@ async function generateEnhancedFreeToolIdeas(opportunities, summary, options) {
     kw.volume >= 300 && // Slightly lower threshold
     (kw.keyword.includes("generator") || kw.keyword.includes("tool") || kw.keyword.includes("maker") || kw.keyword.includes("builder") || kw.keyword.includes("converter") || kw.keyword.includes("calculator") || kw.keyword.includes("checker") || kw.keyword.includes("validator") || kw.keyword.includes("formatter") || kw.keyword.includes("free") || kw.intent === "informational")
   );
-  const basicIdeas = toolKeywords.slice(0, 15).map((kw) => ({
+  const basicIdeas = toolKeywords.slice(0, options.llm.maxToolIdeas ?? 15).map((kw) => ({
     keyword: kw.keyword,
     toolName: generateToolName(kw.keyword),
     toolDescription: generateToolDescription(kw.keyword, summary),
@@ -21817,7 +21850,7 @@ async function generateEnhancedFreeToolIdeas(opportunities, summary, options) {
     basicIdeas,
     summary,
     getCompetitiveData,
-    { openaiApiKey: options.openaiApiKey }
+    { llm: options.llm }
   );
   return enhancedIdeas.map((enhanced) => ({
     keyword: enhanced.keyword,
@@ -22148,10 +22181,9 @@ async function startWizardSession(url, options = {}) {
   console.log("\u{1F50D} Analyzing your site...");
   const crawlResult = await crawlSite(url, { maxPages: 10 });
   let siteSummary;
-  if (options.openaiApiKey) {
-    siteSummary = await summarizeSite(crawlResult, {
-      openaiApiKey: options.openaiApiKey
-    });
+  const llm = keywordLLM(options);
+  if (llm) {
+    siteSummary = await summarizeSite(crawlResult, { llm });
   } else {
     siteSummary = {
       productName: crawlResult.domain,
@@ -35072,24 +35104,32 @@ var RankTracker = class {
     }).eq("id", keywordId);
     if (updateError) {
       console.error(`Failed to save ranking for ${result.keyword}:`, updateError);
+      return;
+    }
+    const { error: historyError } = await this.supabase.from("keyword_position_history").insert({
+      keyword_id: keywordId,
+      position: result.position,
+      url: result.url,
+      checked_at: result.checkedAt.toISOString()
+    });
+    if (historyError) {
+      console.error(`Failed to record history for ${result.keyword}:`, historyError);
     }
   }
   /**
-   * Get ranking history for a keyword
-   * Note: Full history requires keyword_ranking_history table with keyword_ranking_id
-   * For now, returns current state as single history entry
+   * Ranking history for a keyword: one entry per check in the last `days`, newest first.
    */
-  async getHistory(keywordId, _days = 30) {
-    const { data, error } = await this.supabase.from("keywords").select("current_position, target_url, last_checked").eq("id", keywordId).single();
+  async getHistory(keywordId, days = 30) {
+    const { data, error } = await this.supabase.from("keyword_position_history").select("position, url, checked_at").eq("keyword_id", keywordId).gte("checked_at", new Date(Date.now() - days * 24 * 60 * 60 * 1e3).toISOString()).order("checked_at", { ascending: false });
     if (error || !data) {
       return [];
     }
-    return [{
-      position: data.current_position,
-      url: data.target_url,
+    return data.map((row) => ({
+      position: row.position,
+      url: row.url,
       serpFeatures: [],
-      recordedAt: data.last_checked ? new Date(data.last_checked) : /* @__PURE__ */ new Date()
-    }];
+      recordedAt: new Date(row.checked_at)
+    }));
   }
   /**
    * Get keyword trends for a project
@@ -35594,14 +35634,17 @@ var SUPPORTED_FRAMEWORKS = [
   injectGSCVerification,
   interpolatePrompt,
   isGitRepo,
+  keywordLLM,
   listFiles,
   loadAgent,
   loadAgentByName,
   mergePages,
+  openAIKeywordLLM,
   optimizeForAI,
   optimizeReadme,
   parseGEOResponse,
   parseGSCResponse,
+  parseJsonReply,
   parseSitemap,
   prioritizeKeywords,
   processWizardResponse,

package/dist/index.mjs

@@ -4326,21 +4326,28 @@ var HTML_SIGNATURES = [
   {
     framework: "wordpress",
     language: "php",
-    patterns: [/wp-content/, /wp-includes/, /wp-json/, /wordpress/i],
+    // Technical signatures only. These patterns run over the whole page, so the old
+    // /wordpress/i matched the word anywhere in the copy: rankcli.dev's own "detects
+    // Rails, Django, Laravel, and WordPress" line was enough to detect its React SPA as
+    // WordPress and then tell it to install an SEO plugin. A generator meta tag is the
+    // one place the page says it about itself.
+    patterns: [/wp-content/, /wp-includes/, /wp-json/, /name=["']generator["'][^>]*content=["']WordPress/i],
     confidence: "high"
   },
   // Laravel
   {
     framework: "laravel",
     language: "php",
-    patterns: [/laravel_session/, /XSRF-TOKEN/, /@csrf/, /laravel/i],
+    // /laravel/i had the same problem as WordPress above - it matched the word in prose.
+    patterns: [/laravel_session/, /XSRF-TOKEN/, /@csrf/],
     confidence: "medium"
   },
   // Symfony
   {
     framework: "symfony",
     language: "php",
-    patterns: [/symfony/, /sf2/, /_sf_/, /profiler\.css/],
+    // Likewise /symfony/, which matched any lowercase mention.
+    patterns: [/sf2/, /_sf_/, /profiler\.css/],
     confidence: "medium"
   },
   // ============ Ruby Frameworks ============
@@ -16564,6 +16571,50 @@ async function extractSeedKeywords(url) {
   }
 }
 
+// src/keywords/llm.ts
+import OpenAI from "openai";
+function openAIKeywordLLM(apiKey, opts = {}) {
+  const openai = new OpenAI({ apiKey });
+  const openAIModel = opts.model;
+  return {
+    async complete(prompt, opts2 = {}) {
+      const response = await openai.chat.completions.create({
+        model: opts2.best ? "gpt-4o" : openAIModel ?? "gpt-4o-mini",
+        messages: [
+          ...opts2.system ? [{ role: "system", content: opts2.system }] : [],
+          { role: "user", content: prompt }
+        ],
+        response_format: { type: "json_object" },
+        temperature: opts2.temperature ?? 0.3,
+        ...opts2.maxTokens ? { max_tokens: opts2.maxTokens } : {}
+      });
+      return response.choices[0]?.message?.content || "";
+    },
+    async embed(texts) {
+      const response = await openai.embeddings.create({ model: "text-embedding-3-small", input: texts });
+      return response.data.map((item) => item.embedding);
+    }
+  };
+}
+function keywordLLM(options) {
+  return options.llm ?? (options.openaiApiKey ? openAIKeywordLLM(options.openaiApiKey) : void 0);
+}
+function parseJsonReply(text) {
+  const cleaned = text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  const candidate = cleaned.slice(start, end + 1);
+  for (const attempt of [candidate, candidate.replace(/,\s*([}\]])/g, "$1")]) {
+    try {
+      const parsed = JSON.parse(attempt);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    } catch {
+    }
+  }
+  return null;
+}
+
 // src/keywords/site-crawler.ts
 import * as cheerio40 from "cheerio";
 var EXCLUDED_PATHS = [
@@ -16773,7 +16824,11 @@ function extractKeyPhrases(crawlResult) {
 }
 
 // src/keywords/ai-summarizer.ts
-import OpenAI from "openai";
+function summarizerLLM(options) {
+  const llm = options.llm ?? (options.openaiApiKey ? openAIKeywordLLM(options.openaiApiKey, { model: options.model }) : void 0);
+  if (!llm) throw new Error("An AI provider is required to summarize the site");
+  return llm;
+}
 var SUMMARIZER_PROMPT = `You are an expert SEO analyst. Analyze the following website content and extract key information for keyword research.
 
 WEBSITE CONTENT:
@@ -16816,37 +16871,26 @@ IMPORTANT:
 
 Respond ONLY with the JSON object, no other text.`;
 async function summarizeSite(crawlResult, options) {
-  const openai = new OpenAI({ apiKey: options.openaiApiKey });
-  const model = options.model || "gpt-4o-mini";
+  const llm = summarizerLLM(options);
+  const maxContent = llm.maxContentChars ?? 15e3;
   let content = crawlResult.aggregatedContent;
-  if (content.length > 15e3) {
-    content = content.substring(0, 15e3) + "\n...[truncated]";
+  if (content.length > maxContent) {
+    content = content.substring(0, maxContent) + "\n...[truncated]";
   }
   const headings = crawlResult.uniqueHeadings.slice(0, 30).join("\n");
   const prompt = SUMMARIZER_PROMPT.replace("{content}", content).replace("{headings}", headings).replace("{productPages}", String(crawlResult.detectedPageTypes.product)).replace("{pricingPages}", String(crawlResult.detectedPageTypes.pricing)).replace("{blogPages}", String(crawlResult.detectedPageTypes.blog)).replace("{featurePages}", String(crawlResult.detectedPageTypes.feature));
   console.log("\u{1F916} Analyzing site content with AI...");
   try {
-    const response = await openai.chat.completions.create({
-      model,
-      messages: [
-        {
-          role: "system",
-          content: "You are an expert SEO analyst. Always respond with valid JSON only."
-        },
-        {
-          role: "user",
-          content: prompt
-        }
-      ],
+    const responseText = await llm.complete(prompt, {
+      system: "You are an expert SEO analyst. Always respond with valid JSON only.",
       temperature: 0.3,
-      max_tokens: options.maxTokens || 2e3
+      maxTokens: options.maxTokens || 2e3
     });
-    const responseText = response.choices[0]?.message?.content || "";
-    const jsonMatch = responseText.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) {
+    const parsed = parseJsonReply(responseText);
+    if (!parsed) {
       throw new Error("No JSON found in response");
     }
-    const summary = JSON.parse(jsonMatch[0]);
+    const summary = parsed;
     return {
       productName: summary.productName || "Unknown Product",
       productDescription: summary.productDescription || "No description available",
@@ -16908,7 +16952,7 @@ function createFallbackSummary(crawlResult) {
   };
 }
 async function enhanceSummaryWithCompetitors(summary, competitors, options) {
-  const openai = new OpenAI({ apiKey: options.openaiApiKey });
+  const llm = summarizerLLM(options);
   const prompt = `Given this product summary:
 Product: ${summary.productName}
 Description: ${summary.productDescription}
@@ -16927,19 +16971,13 @@ Analyze the competitive positioning. If this product focuses on a niche segment
   "updatedUncertainties": ["uncertainty1", "uncertainty2"]
 }`;
   try {
-    const response = await openai.chat.completions.create({
-      model: options.model || "gpt-4o-mini",
-      messages: [
-        { role: "system", content: "Respond with valid JSON only." },
-        { role: "user", content: prompt }
-      ],
+    const responseText = await llm.complete(prompt, {
+      system: "Respond with valid JSON only.",
       temperature: 0.3,
-      max_tokens: 1e3
+      maxTokens: 1e3
     });
-    const responseText = response.choices[0]?.message?.content || "";
-    const jsonMatch = responseText.match(/\{[\s\S]*\}/);
-    if (jsonMatch) {
-      const analysis = JSON.parse(jsonMatch[0]);
+    const analysis = parseJsonReply(responseText);
+    if (analysis) {
       return {
         ...summary,
         competitivePositioning: analysis.competitivePositioning || "",
@@ -17026,7 +17064,6 @@ function generateUncertaintyQuestions(summary) {
 }
 
 // src/keywords/nlp-analysis.ts
-import OpenAI2 from "openai";
 var STOP_WORDS2 = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -17311,19 +17348,18 @@ function createTermVectors(keywords, vocabulary) {
     return vector;
   });
 }
+async function embedBatch(embedder, batch) {
+  if (typeof embedder === "function") return embedder(batch);
+  const response = await embedder.embeddings.create({ model: "text-embedding-3-small", input: batch });
+  return response.data.map((item) => item.embedding);
+}
 async function getEmbeddings(texts, openai) {
   const embeddings = [];
   const batchSize = 100;
   for (let i = 0; i < texts.length; i += batchSize) {
     const batch = texts.slice(i, i + batchSize);
     try {
-      const response = await openai.embeddings.create({
-        model: "text-embedding-3-small",
-        input: batch
-      });
-      for (const item of response.data) {
-        embeddings.push(item.embedding);
-      }
+      embeddings.push(...await embedBatch(openai, batch));
     } catch (error) {
       console.warn("Embedding API failed, using fallback BOW vectors");
       for (const text of batch) {
@@ -17478,12 +17514,12 @@ async function runNLPAnalysis(content, options = {}) {
   const entityPhrases = extractEntityPhrases(combinedText);
   let clusters = [];
   const keywordsToCluster = tfidfKeywords.slice(0, 50).map((k) => k.term);
-  if (options.openaiApiKey && keywordsToCluster.length > 0) {
+  const embed = keywordLLM(options)?.embed;
+  if (embed && keywordsToCluster.length > 0) {
     try {
-      const openai = new OpenAI2({ apiKey: options.openaiApiKey });
       clusters = await clusterKeywordsByEmbedding(
         keywordsToCluster,
-        openai,
+        (texts) => embed(texts),
         options.numClusters
       );
     } catch (error) {
@@ -17826,9 +17862,13 @@ async function searchHackerNews(query, maxResults = 10) {
 }
 
 // src/keywords/llm-judge.ts
-import OpenAI3 from "openai";
+function judgeLLM(options) {
+  const llm = keywordLLM(options);
+  if (!llm) throw new Error("An AI provider is required to judge tool ideas");
+  return llm;
+}
 async function evaluateToolFeasibility(toolIdea, siteSummary, competitiveData, options) {
-  const openai = new OpenAI3({ apiKey: options.openaiApiKey });
+  const llm = judgeLLM(options);
   const minFeasibility = options.minFeasibilityScore ?? 3;
   const minSpecificity = options.minSpecificityScore ?? 3;
   const minProductFit = options.minProductFitScore ?? 2;
@@ -17904,13 +17944,10 @@ Respond in JSON:
   "blockers": ["<issues that prevent building>"],
   "improvements": ["<suggestions to make it more specific/buildable>"]
 }`;
-  const response = await openai.chat.completions.create({
-    model: "gpt-4o-mini",
-    messages: [{ role: "user", content: prompt }],
-    response_format: { type: "json_object" },
-    temperature: 0.3
-  });
-  const result = JSON.parse(response.choices[0].message.content || "{}");
+  const result = parseJsonReply(await llm.complete(prompt, { temperature: 0.3 })) ?? {};
+  for (const key of ["feasibility", "specificity", "productFit", "marketOpportunity"]) {
+    result[key] = Number(result[key]) || 0;
+  }
   const overallScore = result.feasibility * 0.3 + result.specificity * 0.3 + result.productFit * 0.2 + result.marketOpportunity * 0.2;
   const passes = result.feasibility >= minFeasibility && result.specificity >= minSpecificity && result.productFit >= minProductFit;
   return {
@@ -17926,7 +17963,7 @@ Respond in JSON:
   };
 }
 async function enhanceToolIdea(toolIdea, siteSummary, competitiveData, options) {
-  const openai = new OpenAI3({ apiKey: options.openaiApiKey });
+  const llm = judgeLLM(options);
   const feasibilityScore = await evaluateToolFeasibility(
     toolIdea,
     siteSummary,
@@ -17971,13 +18008,7 @@ ${competitiveData?.openSourceOptions.slice(0, 3).map((t) => `- OSS: ${t.name} ($
   "canUseExistingOSS": <true if an OSS library does most of the work>,
   "ossLibrary": "<name of OSS library to use, or null>"
 }`;
-  const response = await openai.chat.completions.create({
-    model: "gpt-4o",
-    messages: [{ role: "user", content: prompt }],
-    response_format: { type: "json_object" },
-    temperature: 0.5
-  });
-  const enhanced = JSON.parse(response.choices[0].message.content || "{}");
+  const enhanced = parseJsonReply(await llm.complete(prompt, { temperature: 0.5, best: true })) ?? {};
   const priority = Math.round(
     feasibilityScore.overallScore * 20 + toolIdea.volume / 1e3 * 10 + (100 - toolIdea.difficulty) / 100 * 20
   );
@@ -18028,7 +18059,7 @@ async function evaluateAndEnhanceToolIdeas(toolIdeas, siteSummary, getCompetitiv
 
 // src/keywords/ai-keyword-engine.ts
 async function runAIKeywordResearch(options) {
-  const { url, tier, openaiApiKey, maxPages = 20 } = options;
+  const { url, tier, maxPages = 20 } = options;
   console.log(`
 \u{1F52C} Starting AI Keyword Research (${tier} tier)...
 `);
@@ -18036,10 +18067,11 @@ async function runAIKeywordResearch(options) {
   if (tier === "free") {
     return runFreeKeywordResearch(crawlResult, options);
   } else {
-    if (!openaiApiKey) {
-      throw new Error("OpenAI API key required for paid tier keyword research");
+    const llm = keywordLLM(options);
+    if (!llm) {
+      throw new Error("An AI provider (or an OpenAI API key) is required for paid tier keyword research");
     }
-    return runPaidKeywordResearch(crawlResult, options);
+    return runPaidKeywordResearch(crawlResult, options, llm);
   }
 }
 async function runFreeKeywordResearch(crawlResult, options) {
@@ -18093,13 +18125,11 @@ async function runFreeKeywordResearch(crawlResult, options) {
     ]
   };
 }
-async function runPaidKeywordResearch(crawlResult, options) {
-  const { openaiApiKey, userContext, wizardResponses, ciMode, competitiveSearchKeys } = options;
+async function runPaidKeywordResearch(crawlResult, options, llm) {
+  const { userContext, wizardResponses, ciMode, competitiveSearchKeys } = options;
   const enableEnhancedToolIdeas = options.enableEnhancedToolIdeas !== false;
   console.log("\u{1F680} Running full AI analysis...");
-  let siteSummary = await summarizeSite(crawlResult, {
-    openaiApiKey
-  });
+  let siteSummary = await summarizeSite(crawlResult, { llm });
   if (userContext) {
     siteSummary = applyUserContext(siteSummary, userContext);
   }
@@ -18108,7 +18138,7 @@ async function runPaidKeywordResearch(crawlResult, options) {
   }
   const documents = crawlResult.pages.map((p) => p.mainContent);
   const nlpAnalysis = await runNLPAnalysis(documents, {
-    openaiApiKey,
+    llm,
     numClusters: 8,
     numTopics: 6
   });
@@ -18135,13 +18165,13 @@ async function runPaidKeywordResearch(crawlResult, options) {
     nlpAnalysis
   );
   let freeToolIdeas;
-  if (enableEnhancedToolIdeas && openaiApiKey) {
+  if (enableEnhancedToolIdeas) {
     console.log("\u{1F52C} Running enhanced tool idea analysis with competitive research...");
     freeToolIdeas = await generateEnhancedFreeToolIdeas(
       opportunities,
       siteSummary,
       {
-        openaiApiKey,
+        llm,
         ...competitiveSearchKeys
       }
     );
@@ -18239,7 +18269,7 @@ async function generateEnhancedFreeToolIdeas(opportunities, summary, options) {
     kw.volume >= 300 && // Slightly lower threshold
     (kw.keyword.includes("generator") || kw.keyword.includes("tool") || kw.keyword.includes("maker") || kw.keyword.includes("builder") || kw.keyword.includes("converter") || kw.keyword.includes("calculator") || kw.keyword.includes("checker") || kw.keyword.includes("validator") || kw.keyword.includes("formatter") || kw.keyword.includes("free") || kw.intent === "informational")
   );
-  const basicIdeas = toolKeywords.slice(0, 15).map((kw) => ({
+  const basicIdeas = toolKeywords.slice(0, options.llm.maxToolIdeas ?? 15).map((kw) => ({
     keyword: kw.keyword,
     toolName: generateToolName(kw.keyword),
     toolDescription: generateToolDescription(kw.keyword, summary),
@@ -18269,7 +18299,7 @@ async function generateEnhancedFreeToolIdeas(opportunities, summary, options) {
     basicIdeas,
     summary,
     getCompetitiveData,
-    { openaiApiKey: options.openaiApiKey }
+    { llm: options.llm }
   );
   return enhancedIdeas.map((enhanced) => ({
     keyword: enhanced.keyword,
@@ -18600,10 +18630,9 @@ async function startWizardSession(url, options = {}) {
   console.log("\u{1F50D} Analyzing your site...");
   const crawlResult = await crawlSite(url, { maxPages: 10 });
   let siteSummary;
-  if (options.openaiApiKey) {
-    siteSummary = await summarizeSite(crawlResult, {
-      openaiApiKey: options.openaiApiKey
-    });
+  const llm = keywordLLM(options);
+  if (llm) {
+    siteSummary = await summarizeSite(crawlResult, { llm });
   } else {
     siteSummary = {
       productName: crawlResult.domain,
@@ -31517,24 +31546,32 @@ var RankTracker = class {
     }).eq("id", keywordId);
     if (updateError) {
       console.error(`Failed to save ranking for ${result.keyword}:`, updateError);
+      return;
+    }
+    const { error: historyError } = await this.supabase.from("keyword_position_history").insert({
+      keyword_id: keywordId,
+      position: result.position,
+      url: result.url,
+      checked_at: result.checkedAt.toISOString()
+    });
+    if (historyError) {
+      console.error(`Failed to record history for ${result.keyword}:`, historyError);
     }
   }
   /**
-   * Get ranking history for a keyword
-   * Note: Full history requires keyword_ranking_history table with keyword_ranking_id
-   * For now, returns current state as single history entry
+   * Ranking history for a keyword: one entry per check in the last `days`, newest first.
    */
-  async getHistory(keywordId, _days = 30) {
-    const { data, error } = await this.supabase.from("keywords").select("current_position, target_url, last_checked").eq("id", keywordId).single();
+  async getHistory(keywordId, days = 30) {
+    const { data, error } = await this.supabase.from("keyword_position_history").select("position, url, checked_at").eq("keyword_id", keywordId).gte("checked_at", new Date(Date.now() - days * 24 * 60 * 60 * 1e3).toISOString()).order("checked_at", { ascending: false });
     if (error || !data) {
       return [];
     }
-    return [{
-      position: data.current_position,
-      url: data.target_url,
+    return data.map((row) => ({
+      position: row.position,
+      url: row.url,
       serpFeatures: [],
-      recordedAt: data.last_checked ? new Date(data.last_checked) : /* @__PURE__ */ new Date()
-    }];
+      recordedAt: new Date(row.checked_at)
+    }));
   }
   /**
    * Get keyword trends for a project
@@ -32031,14 +32068,17 @@ export {
   injectGSCVerification,
   interpolatePrompt,
   isGitRepo,
+  keywordLLM,
   listFiles,
   loadAgent,
   loadAgentByName,
   mergePages,
+  openAIKeywordLLM,
   optimizeForAI,
   optimizeReadme,
   parseGEOResponse,
   parseGSCResponse,
+  parseJsonReply,
   parseSitemap,
   prioritizeKeywords,
   processWizardResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rankcli/agent-runtime",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "RankCLI agent runtime - executes SEO audits and fixes with AI",
   "homepage": "https://rankcli.dev",
   "main": "dist/index.js",