Keep/_bmad-output/implementation-artifacts/2-5-create-ai-server-actions-stub.md

Story 2.5: Create AI Server Actions Stub

Status: review

Story

As a developer, I want a stub foundation file for AI server actions, so that all AI-related server actions are organized in one centralized location following consistent patterns.

Acceptance Criteria

1. Given the existing AI server actions pattern in the codebase,
2. When I create the AI server actions stub file,
3. Then the stub should:
   • Be located at keep-notes/app/actions/ai-actions.ts (NEW)
   • Export TypeScript interfaces for all AI action request/response types
   • Include placeholder functions with JSDoc comments for future AI features
   • Follow the established server action pattern ('use server', auth checks, error handling)
   • Be importable from client components
   • NOT break existing AI server actions (they remain functional)

Tasks / Subtasks

• Create app/actions/ai-actions.ts stub file (AC: 3)
  • Add 'use server' directive at top
  • Import dependencies (auth, prisma, revalidatePath, AI services)
  • Define TypeScript interfaces for request/response types
  • Add placeholder functions with JSDoc comments for:
    • Title suggestions (already exists in title-suggestions.ts - reference it)
    • Semantic search (already exists in semantic-search.ts - reference it)
    • Paragraph reformulation (already exists in paragraph-refactor.ts - reference it)
    • Memory Echo (to be implemented)
    • Language detection (already exists in detect-language.ts - reference it)
    • AI settings (already exists in ai-settings.ts - reference it)
  • Add TODO comments indicating which features are stubs vs implemented
  • Ensure file compiles without TypeScript errors
• Verify existing AI server actions still work (AC: 4)
  • Test that title-suggestions.ts still functions
  • Test that semantic-search.ts still functions
  • Confirm no breaking changes to existing functionality

Dev Notes

Architecture Context

Current State:

• AI server actions already exist as separate files:
  • app/actions/title-suggestions.ts
  • app/actions/semantic-search.ts
  • app/actions/paragraph-refactor.ts
  • app/actions/detect-language.ts
  • app/actions/ai-settings.ts

Existing Pattern (from notes.ts:1-8):

'use server'

import { auth } from '@/auth'
import { prisma } from '@/lib/prisma'
import { revalidatePath } from 'next/cache'

export async function actionName(params: ParamType): Promise<ResponseType> {
  const session = await auth()
  if (!session?.user?.id) {
    throw new Error('Unauthorized')
  }

  try {
    // ... implementation
  } catch (error) {
    console.error('Error description:', error)
    throw error
  }
}

Purpose of This Story: This story creates a stub/placeholder file (ai-actions.ts) that:

1. Establishes the TypeScript interfaces for all AI action types
2. Documents the expected server action signatures for future AI features
3. Provides a centralized location for AI-related server actions
4. Serves as documentation for the AI server action architecture
5. Does NOT replace or break existing AI server actions

Note: The actual implementations of Memory Echo and other features will be done in separate stories (Epic 5: Contextual AI Features). This story is about creating the structural foundation.

Technical Requirements

File Structure:

keep-notes/app/actions/
├── ai-actions.ts           # NEW: Stub file with interfaces and placeholders
├── title-suggestions.ts    # EXISTING: Keep unchanged
├── semantic-search.ts      # EXISTING: Keep unchanged
├── paragraph-refactor.ts   # EXISTING: Keep unchanged
├── detect-language.ts      # EXISTING: Keep unchanged
├── ai-settings.ts          # EXISTING: Keep unchanged
└── notes.ts                # EXISTING: Core note CRUD

TypeScript Interfaces to Define:

// Title Suggestions
export interface GenerateTitlesRequest {
  noteId: string
}

export interface GenerateTitlesResponse {
  suggestions: Array<{
    title: string
    confidence: number
    reasoning?: string
  }>
  noteId: string
}

// Semantic Search
export interface SemanticSearchRequest {
  query: string
  options?: {
    limit?: number
    threshold?: number
    notebookId?: string
  }
}

export interface SemanticSearchResponse {
  results: SearchResult[]
  query: string
  totalResults: number
}

// Paragraph Reformulation
export interface RefactorParagraphRequest {
  noteId: string
  selectedText: string
  option: 'clarify' | 'shorten' | 'improve'
}

export interface RefactorParagraphResponse {
  originalText: string
  refactoredText: string
}

// Memory Echo (STUB - to be implemented in Epic 5)
export interface GenerateMemoryEchoRequest {
  // No params - uses current user session
}

export interface GenerateMemoryEchoResponse {
  success: boolean
  insight: {
    note1Id: string
    note2Id: string
    similarityScore: number
  } | null
}

// Language Detection
export interface DetectLanguageRequest {
  content: string
}

export interface DetectLanguageResponse {
  language: string
  confidence: number
  method: 'tinyld' | 'ai'
}

// AI Settings
export interface UpdateAISettingsRequest {
  settings: Partial<{
    titleSuggestions: boolean
    semanticSearch: boolean
    paragraphRefactor: boolean
    memoryEcho: boolean
    aiProvider: 'auto' | 'openai' | 'ollama'
  }>
}

export interface UpdateAISettingsResponse {
  success: boolean
}

Stub Function Pattern:

/**
 * Generate Memory Echo insights
 * STUB: To be implemented in Epic 5 (Story 5-1)
 *
 * This will analyze all user notes with embeddings to find
 * connections with cosine similarity > 0.75
 */
export async function generateMemoryEcho(): Promise<GenerateMemoryEchoResponse> {
  // TODO: Implement Memory Echo background processing
  // - Fetch all user notes with embeddings
  // - Calculate pairwise cosine similarities
  // - Find top connection with similarity > 0.75
  // - Store in MemoryEchoInsight table
  // - Return insight or null if none found

  throw new Error('Not implemented: See Epic 5 Story 5-1')
}

Project Structure Notes

Alignment with unified project structure:

• Path: app/actions/ai-actions.ts (follows Next.js App Router conventions)
• Naming: kebab-case filename (ai-actions.ts), PascalCase interfaces
• Imports: Use @/ alias for all imports
• Directives: 'use server' at line 1
• No conflicts: Existing AI server actions remain in separate files

Detected conflicts or variances: None

Testing Requirements

Verification Steps:

1. Create ai-actions.ts file
2. Verify TypeScript compilation: npx tsc --noEmit
3. Confirm no errors in existing AI server action files
4. Test that imports work: import { GenerateTitlesRequest } from '@/app/actions/ai-actions'
5. Verify existing features still work:
   • Title suggestions still functional
   • Semantic search still functional
   • No breaking changes to UI

No E2E tests required - This is a stub/placeholder file with no actual implementation

References

• Server Action Pattern: keep-notes/app/actions/notes.ts:1-8
• Existing AI Actions:
  • keep-notes/app/actions/title-suggestions.ts (reference for pattern)
  • keep-notes/app/actions/semantic-search.ts (reference for pattern)
• Architecture: _bmad-output/planning-artifacts/architecture.md (Decision 2: Memory Echo Architecture)
• Project Context: _bmad-output/planning-artifacts/project-context.md (Server Actions Pattern section)
• Epic Definition: _bmad-output/planning-artifacts/epics.md (Epic 5: Contextual AI Features)

Dev Agent Record

Agent Model Used

claude-sonnet-4-5-20250929

Debug Log References

None (stub creation story)

Completion Notes List

• Created story file with comprehensive context
• Documented existing AI server action patterns
• Defined TypeScript interfaces for all AI actions
• Specified stub file structure and location
• Identified references to existing implementations
• Implemented ai-actions.ts stub file with all interfaces
• Added comprehensive JSDoc comments and TODO markers
• Verified no breaking changes to existing actions
• All acceptance criteria satisfied

File List

Files Created:

• keep-notes/app/actions/ai-actions.ts ✅

Files Referenced (NOT MODIFIED):

• keep-notes/app/actions/title-suggestions.ts (reference for pattern)
• keep-notes/app/actions/semantic-search.ts (reference for pattern)
• keep-notes/app/actions/paragraph-refactor.ts (reference for pattern)
• keep-notes/app/actions/detect-language.ts (reference for pattern)
• keep-notes/app/actions/ai-settings.ts (reference for pattern)