feat: add ai search in docs

[DarkPhoenix2704]

No description provided.

[github-actions]

✅ Build Status: Success!

• ✅ Build completed successfully
• 🚀 Ready for review

📝 Latest commit: 91e97cc
⏰ Updated: 2025-10-16 08:48:19 UTC

[DarkPhoenix2704]

@claude Review

[claude]

Claude finished @DarkPhoenix2704's task —— View job

---

Code Review Complete ✅

I've reviewed the AI search feature implementation. This is a substantial addition that integrates OpenAI's GPT-4 with Typesense search to provide intelligent documentation assistance. Below is my detailed feedback:

---

🎯 Overview

The PR successfully adds an AI-powered search interface that:

• Uses GPT-4 to answer documentation questions
• Searches and fetches relevant docs via Typesense
• Provides a clean chat UI with markdown rendering
• Tracks analytics events for user interactions

---

🔴 Critical Issues

1. Hardcoded API Key in Production Code 🚨

File: lib/ai-tools/search-and-fetch.ts:9

apiKey: process.env.TYPESENSE_API_KEY || 'lNKDTZdJrE76Sg8WEyeN9mXT29l1xq7Q',

Issue: The fallback API key should never be hardcoded. This is a security vulnerability.

Recommendation:

const apiKey = process.env.TYPESENSE_API_KEY;
if (!apiKey) {
  throw new Error('TYPESENSE_API_KEY environment variable is required');
}

2. Missing Environment Variable Validation

File: app/api/chat/route.ts:7-9

The OpenAI API key has no fallback handling. If OPENAI_API_KEY is missing, the error will be cryptic.

Recommendation: Add validation at module level or in the route handler:

if (!process.env.OPENAI_API_KEY) {
  console.error('Missing OPENAI_API_KEY environment variable');
}

3. Unprotected API Route

File: app/api/chat/route.ts:11

The /api/chat endpoint has no authentication, rate limiting, or input validation.

Issues:

• Anyone can call this endpoint and consume OpenAI credits
• No rate limiting to prevent abuse
• No input validation on reqJson.messages

Recommendations:

export async function POST(req: Request) {
  // 1. Add rate limiting (e.g., using Vercel Edge Config or Redis)
  // 2. Validate request body
  const reqJson = await req.json();
  
  if (!reqJson.messages || !Array.isArray(reqJson.messages)) {
    return new Response('Invalid request body', { status: 400 });
  }
  
  // 3. Consider adding API key authentication or using Next.js middleware
  // to protect this route from unauthorized access
  
  // ... rest of handler
}

---

⚠️ Important Issues

4. Silent Error Handling

File: lib/ai-tools/search-and-fetch.ts:119-121, 132-137

Empty catch blocks swallow errors without logging, making debugging impossible.

Current:

} catch {
  // Continue with next page
}

Recommended:

} catch (error) {
  console.error(`Failed to fetch page content for ${pageUrl}:`, error);
  // Continue with next page
}

5. Missing Error Boundaries in UI

File: components/search.tsx

The chat component lacks error handling for failed API calls. Users won't see helpful error messages if the API fails.

Recommendation: Add error state handling in the useChat hook:

const chat = useChat({
  id: "search",
  transport: new DefaultChatTransport({
    api: "/api/chat",
  }),
  onError: (error) => {
    console.error('Chat error:', error);
    // Show user-friendly error message
  },
});

6. Model Version Hardcoded

File: app/api/chat/route.ts:15

model: openai('gpt-4.1-2025-04-14'),

This specific model version may be deprecated. Consider making it configurable via environment variable:

model: openai(process.env.OPENAI_MODEL || 'gpt-4-turbo'),

7. Unbounded Token Usage

File: app/api/chat/route.ts:21

The searchAndFetchDocs function fetches full page content with no token/size limits. This could:

• Exceed context windows
• Increase costs significantly
• Cause slow responses

Recommendation: Add a max token limit or truncate content:

const { markdown, links } = await searchAndFetchDocs(query, 3);
// Truncate markdown if too long
const maxChars = 10000; // or calculate based on tokens
const truncatedMarkdown = markdown.length > maxChars 
  ? markdown.substring(0, maxChars) + '\n\n[Content truncated...]'
  : markdown;

---

🟡 Moderate Issues

8. Type Safety Concerns

File: components/search.tsx:232-233

if (part.type === "tool-provideLinks" && part.input) {
  links = (part.input as z.infer<typeof ProvideLinksToolSchema>).links;
}

Using type assertions without validation. Consider using Zod's safeParse:

const parsed = ProvideLinksToolSchema.safeParse(part.input);
if (parsed.success) {
  links = parsed.data.links;
}

9. Memory Leak Potential

File: components/markdown.tsx:114

const cache = new Map<string, Promise<ReactNode>>();

The cache grows unbounded. Consider using an LRU cache or clearing it periodically.

10. Analytics Hook Called Inside Effect

File: components/Analytics.tsx:46

useEffect(() => {
  // ... 
}, [trackEvent]);

trackEvent is recreated on every render (it's not memoized in useAnalytics). This could cause the effect to re-run unnecessarily.

Recommendation in hooks/useAnalytics.ts:

const trackEvent = useCallback((event: AnalyticsEvent) => {
  if (pushRef.current) {
    pushRef.current({
      $current_url: window.location.href,
      path: window.location.pathname,
      hash: window.location.hash,
      ...event,
    });
  }
}, []);

11. Inconsistent Error Messages

File: lib/ai-tools/search-and-fetch.ts:74, 125, 134

Generic error messages don't help users understand what went wrong:

• "No relevant documentation found" - Could mean search failed or truly no results
• "Could not fetch documentation content" - Doesn't explain why
• "An error occurred while searching" - Too vague

---

💡 Suggestions & Best Practices

12. CLI Config File Purpose Unclear

File: cli.json

This file was added but it's not clear what CLI tool uses it. Consider adding a comment or README section explaining its purpose.

13. Accessibility Improvements

File: components/search.tsx

• The close button (<X />) lacks an aria-label
• The AI input should have proper ARIA attributes for screen readers
• Keyboard navigation could be improved with proper focus management

Recommendations:

<button
 
  className={cn(...)}
  onClick={() => setOpen(false)}
>
  <X />
</button>

14. Performance: Auto-scroll on Every Resize

File: components/search.tsx:155-176

The ResizeObserver triggers scroll on every size change, which could be expensive. Consider debouncing or using requestAnimationFrame.

15. Hard-coded Width Values

File: components/search.tsx:334, 348

max-w-[600px] min-w-[600px]
w-[min(600px,90vw)]

Consider making these configurable or using CSS custom properties for easier theming.

16. Step Count Limit

File: app/api/chat/route.ts:33

stopWhen: stepCountIs(10),

This limits tool calls to 10, which might not be enough for complex queries. Consider:

• Making this configurable
• Adding comments explaining why 10 was chosen
• Implementing better termination logic based on answer completeness

---

✅ Positive Aspects

1. Well-structured prompting - The system prompt in lib/searchPrompt.ts is comprehensive and includes good examples
2. Clean separation of concerns - AI tools, UI components, and API routes are well organized
3. Analytics integration - Good tracking of user interactions for product insights
4. Markdown rendering - Nice implementation with code highlighting and animations
5. TypeScript usage - Generally good type safety throughout
6. Reusable analytics hook - The useAnalytics hook centralizes tracking logic well

---

📋 Testing Recommendations

Since I cannot run the build or tests, please ensure:

1. Environment variables are documented (add .env.example)
2. API route is tested with:
   • Missing messages
   • Malformed messages
   • Very long messages
   • Missing API keys
3. Error scenarios are handled gracefully in the UI
4. Rate limiting is tested to prevent abuse
5. Cost monitoring is set up for OpenAI API usage

---

📝 Documentation Needed

Consider adding:

1. README section explaining:

   • How to set up OpenAI API key
   • How the AI search feature works
   • Cost implications
   • Rate limiting strategy

2. .env.example with required variables:

   OPENAI_API_KEY=your_key_here
   OPENAI_MODEL=gpt-4-turbo
   TYPESENSE_API_KEY=your_key_here
   TYPESENSE_HOST=your_host_here
   

3. Inline comments in complex areas like the markdown processor

---

🎯 Summary

This is a solid implementation of an AI search feature with good UX and clean architecture. However, the security issues (hardcoded API key, unprotected endpoint) must be addressed before merging to production. The error handling and rate limiting should also be improved to prevent abuse and provide better user experience.

Priority fixes:

1. Remove hardcoded Typesense API key (CRITICAL)
2. Add authentication/rate limiting to /api/chat (CRITICAL)
3. Improve error handling and logging (HIGH)
4. Add environment variable validation (HIGH)
5. Consider token limits for cost control (MEDIUM)

---

Job: [View run](https://github.com/nocodb/noco-docs-v2/actions/runs/${{ github.run_id }})
Branch: fix-blogs