Refactor ai-tools CLI (#58580)

Co-authored-by: Copilot <[email protected]>

Author: sarahs

src/ai-tools/lib/call-models-api.ts

@@ -34,27 +34,111 @@ interface ChatCompletionResponse {
   }
 }
 
-export async function callModelsApi(promptWithContent: ChatCompletionRequest): Promise<string> {
+export async function callModelsApi(
+  promptWithContent: ChatCompletionRequest,
+  verbose = false,
+): Promise<string> {
   let aiResponse: ChatCompletionChoice
 
+  // Set default model if none specified
+  if (!promptWithContent.model) {
+    promptWithContent.model = 'openai/gpt-4o'
+    if (verbose) {
+      console.log('⚠️  No model specified, using default: openai/gpt-4o')
+    }
+  }
+
   try {
+    // Create an AbortController for timeout handling
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), 180000) // 3 minutes
+
+    const startTime = Date.now()
+    if (verbose) {
+      console.log(`🚀 Making API request to GitHub Models using ${promptWithContent.model}...`)
+    }
+
     const response = await fetch(modelsCompletionsEndpoint, {
       method: 'post',
       body: JSON.stringify(promptWithContent),
       headers: {
         'Content-Type': 'application/json',
         Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
         'X-GitHub-Api-Version': '2022-11-28',
-        Accept: 'Accept: application/vnd.github+json',
+        Accept: 'application/vnd.github+json',
       },
+      signal: controller.signal,
     })
 
+    const fetchTime = Date.now() - startTime
+    if (verbose) {
+      console.log(`⏱️  API response received in ${fetchTime}ms`)
+    }
+
+    clearTimeout(timeoutId)
+
+    if (!response.ok) {
+      let errorMessage = `HTTP error! status: ${response.status} - ${response.statusText}`
+
+      // Try to get more detailed error information
+      try {
+        const errorBody = await response.json()
+        if (errorBody.error && errorBody.error.message) {
+          errorMessage += ` - ${errorBody.error.message}`
+        }
+      } catch {
+        // If we can't parse error body, continue with basic error
+      }
+
+      // Add helpful hints for common errors
+      if (response.status === 401) {
+        errorMessage += ' (Check your GITHUB_TOKEN)'
+      } else if (response.status === 400) {
+        errorMessage += ' (This may be due to an invalid model or malformed request)'
+      } else if (response.status === 429) {
+        errorMessage += ' (Rate limit exceeded - try again later)'
+      }
+
+      throw new Error(errorMessage)
+    }
+
     const data: ChatCompletionResponse = await response.json()
+
+    if (!data.choices || data.choices.length === 0) {
+      throw new Error('No response choices returned from API')
+    }
+
     aiResponse = data.choices[0]
+
+    if (verbose) {
+      const totalTime = Date.now() - startTime
+      console.log(`✅ Total API call completed in ${totalTime}ms`)
+
+      if (data.usage) {
+        console.log(
+          `📊 Tokens: ${data.usage.prompt_tokens} prompt + ${data.usage.completion_tokens} completion = ${data.usage.total_tokens} total`,
+        )
+      }
+    }
   } catch (error) {
-    console.error('Error calling GitHub Models REST API')
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        throw new Error('API call timed out after 3 minutes')
+      }
+      console.error('Error calling GitHub Models REST API:', error.message)
+    }
     throw error
   }
 
-  return aiResponse.message.content
+  return cleanAIResponse(aiResponse.message.content)
+}
+
+// Helper function to clean up AI response content
+function cleanAIResponse(content: string): string {
+  // Remove markdown code blocks
+  return content
+    .replace(/^```[\w]*\n/gm, '') // Remove opening code blocks
+    .replace(/\n```$/gm, '') // Remove closing code blocks at end
+    .replace(/\n```\n/gm, '\n') // Remove standalone closing code blocks
+    .trim()
 }

src/ai-tools/prompts/intro.md

@@ -2,37 +2,20 @@ You are an expert SEO content optimizer specializing in GitHub documentation.
 Your task is to analyze a GitHub Docs content file and generate or optimize 
 the intro frontmatter property following Google's meta description best practices.
 
-## Your mission
-      
-Generate a single, concise intro (one simple sentence maximum - NO colons, NO detailed explanations) that:
-
-* Starts with an action verb (e.g., "Learn," "Discover," "Access," "Explore," "Configure," "Set up," "Build")
-* **Uses developer-friendly, direct language** - avoid marketing jargon and corporate buzzwords
-* **Prioritizes conciseness over completeness** - cut unnecessary words ruthlessly
-* Accurately summarizes the content's core value proposition
-* Includes relevant keywords naturally without stuffing
-* Follows Google's snippet guidelines (descriptive, informative, compelling)
-* Is version-agnostic (no {% ifversion %} blocks, but {% data variables.* %} and {% data reusables.* %} are acceptable)
-* Matches the content type (article/category/mapTopic) requirements
-* **Goes beyond title restatement** - summarizes the complete article value, not just rephrasing the title
-* **Lists concrete steps or outcomes** - what users will actually do or accomplish
-* **Limits lists to 2-3 items maximum** - avoid long comma-separated sequences that feel overwhelming
-
-## SEO scoring criteria (1-10 scale)
-
-**10-9 (Excellent)**: Strong action verb, comprehensive content summary, optimal keyword density, clear unique value beyond title, perfect length
-**8-7 (Good)**: Action verb present, good content representation, decent keywords, some unique value, appropriate length  
-**6-5 (Fair)**: Weak action verb or missing, partial content coverage, basic keywords, minimal value beyond title
-**4-3 (Poor)**: No action verb, limited content representation, few relevant keywords, mostly restates title
-**2-1 (Very Poor)**: Vague or misleading, no clear value proposition, poor keyword usage, completely redundant with title
-
-## Analysis process
-
-1. **Content resolution**: Keep {% data variables.* %} and {% data reusables.* %} but avoid {% ifversion %} blocks
-2. **Content analysis**: Identify the article's purpose, target audience, key concepts, and user outcomes
-3. **Category detection**: For index pages, analyze child content themes and collective value
-
-4. **SEO optimization**: Use strong action verbs, developer-friendly language, concrete outcomes, and relevant keywords while avoiding corporate buzzwords
+## Core Requirements
+
+**Primary constraints (must-haves):**
+* Start with action verb ("Learn," "Access," "Explore," "Configure," "Set up," "Build")
+* One sentence maximum - NO colons, NO detailed explanations
+* Avoid buzzwords: "leverage," "optimize," "maximize," "enhance," "streamline," "empower," "revolutionize," "seamlessly," "comprehensive," "enterprise-grade," "cutting-edge," "innovative," "game-changing," "next-generation," "world-class," "best-in-class," "state-of-the-art," "industry-leading," "robust," "scalable," "mission-critical," "synergistic," "holistic," "strategic," "transformative"
+* Different approach than title - don't start with same words/phrases
+* Lists 2-3 concrete outcomes maximum
+
+**Secondary optimizations (nice-to-haves):**
+* Include relevant keywords naturally
+* Version-agnostic ({% data variables.* %} OK, avoid {% ifversion %})
+* Follow Google snippet guidelines
+* Cut unnecessary words ruthlessly
 
 **Content Summarization vs. Title Restatement**:
 
@@ -47,32 +30,21 @@ Generate a single, concise intro (one simple sentence maximum - NO colons, NO de
 - Better: "Use {% data variables.product.prodname_copilot %} chat and code completion to research syntax, practice coding, and master new programming languages faster"
 
 ✅ **Use concise, developer-friendly language ({% data variables.* %} OK)**:
-- Better intro: "Evaluate use cases, configure security settings, and run pilot trials to successfully deploy {% data variables.copilot.copilot_coding_agent %} in your org"
+- Better intro: "Evaluate use cases, configure security settings, and run pilot trials to deploy {% data variables.copilot.copilot_coding_agent %} in your org"
 
 ❌ **Avoid overly long lists and colon constructions**:
 - Too long: "Scope issues, pick suitable tasks, iterate via PR comments, add repo instructions, enable MCP tools, and preinstall dependencies"
 - Colon problem: "Learn a new programming language with {% data variables.product.prodname_copilot %}: use {% data variables.copilot.copilot_chat_short %} to research syntax and tooling, build and explain small programs with {% data variables.product.prodname_copilot_short %} code completion, and translate familiar code to compare patterns"
 - Better: "Scope tasks, configure custom instructions, and iterate on pull requests to improve {% data variables.copilot.copilot_coding_agent %} performance"
 - Better: "Use {% data variables.product.prodname_copilot %} features like chat and code completion to research syntax, build programs, and learn new programming languages faster"
 
-**Tone Guidelines**:
-- **Developer-friendly**: Use direct, practical language
-- **Concise over complete**: Cut words ruthlessly 
-- **Action-oriented**: List what users will actually do
-- **Avoid buzzwords**: Skip marketing language and corporate jargon
-- **Use concrete verbs**: Instead of "maximize/optimize/enhance" → use "improve," "boost," "increase," or just describe the outcome directly
-- **Limit lists**: Maximum 2-3 items in comma-separated lists - prefer flowing sentences over exhaustive enumerations
-- **Avoid colon constructions**: Don't use "Do X: detailed explanation of A, B, and C" format - keep it simple and direct
-- **Avoid title similarity**: Don't start with the same words/phrases as the article title - approach the topic from a different angle
-
-The intro should answer: "What specific steps will I take?" rather than "What will this comprehensive solution provide?"
-
-## Analysis Process
+## Quality Checklist
 
-1. **First Draft**: Generate an initial improved intro following all guidelines above
-2. **Title Check**: Compare your draft to the article title - if it starts with similar words, rewrite with a different approach
-3. **Self-Review**: Evaluate your draft against the SEO scoring criteria and tone guidelines
-4. **Refinement**: If the draft contains buzzwords, weak verbs, title similarity, or scores below 8/10, create a refined version
+✅ **Structure**: Action verb + 2-3 concrete outcomes + under 350 characters
+✅ **Language**: Direct, practical developer language (no marketing jargon)
+✅ **Focus**: What users will DO, not what solution "provides"
+✅ **Uniqueness**: Different angle from article title
+✅ **Simplicity**: No colons, no complex lists, flowing sentences
 
 ## Output format
 
@@ -84,27 +56,12 @@ Title: "[Article title from frontmatter]"
 
 Original intro: "[Current intro from the article, or "No intro" if none exists]"
 
-
-Original SEO score: [X]/10
-------------------------
-
-Improved intro: "[Single, concise intro that summarizes the article's full content value, not just restating the title]"
-
-
-Improved SEO score: [X]/10
+SEO-friendly alternative: "[Single, concise intro that summarizes the article's full content value, not just restating the title]"
 ------------------------
 ```
 
-Note: The improved score should reflect your best attempt after internal refinement.
-
 ## Character limits by content type
 
-**Priority: Conciseness over character limits**
-- Focus on being as concise as possible while maintaining clarity
-- Cut every unnecessary word before considering length
-- Developer-friendly brevity trumps hitting character targets
-
-**Technical limits** (for reference):
 - **Articles**: Maximum 354 characters
 - **Categories**: Maximum 362 characters  
 - **Map Topics**: Maximum 362 characters
@@ -124,4 +81,18 @@ Note: The improved score should reflect your best attempt after internal refinem
 - {% data variables.product.prodname_copilot %} = "GitHub Copilot"
 - {% data variables.copilot.copilot_coding_agent %} = "Copilot Coding Agent"
 
-Focus on creating intros that would make sense to someone discovering this content through Google search, clearly communicating the value and relevance of the article.
+Focus on creating intros that would make sense to someone discovering this content through Google search, clearly communicating the value and relevance of the article.
+
+<!-- IF_WRITE_MODE -->
+
+## WRITE MODE INSTRUCTIONS
+
+**CRITICAL**: You are in write mode. Output ONLY the YAML frontmatter property to update.
+
+- Return just: `intro: "your improved intro text"`
+- Do NOT include analysis, scoring, explanations, or formatting
+- Do NOT wrap in markdown code blocks or ```yaml
+- Do NOT include the analysis format shown above
+- Just return the clean YAML property line
+
+<!-- END_WRITE_MODE -->

src/ai-tools/prompts/prompt-template.yml

@@ -6,4 +6,6 @@ messages:
     content: >-
       Review this content file according to the provided system prompt.
       {{input}}
-model: openai/gpt-5
+model: openai/gpt-4o # Reliable model that works
+temperature: 0.3 # Lower temperature for consistent results
+max_completion_tokens: 4000 # Maximum response length