Skip to main content
The Search Patterns Learning API is a crucial component of Sophra’s adaptive learning system, designed to capture, analyze, and store search patterns to continuously improve the platform’s search capabilities. This API endpoint, implemented as a Next.js API route, serves as the bridge between user interactions and Sophra’s machine learning pipeline, enabling real-time pattern detection and model updates. At its core, this API leverages Prisma ORM to interact with the underlying database, storing complex search pattern data in a structured format. The implementation utilizes TypeScript for type safety and Zod for runtime schema validation, ensuring data integrity throughout the process. By capturing detailed metadata about each search query, including relevance metrics, latency, and applied adaptation rules, the system builds a comprehensive dataset for ongoing search optimization. The architecture of this component reflects Sophra’s commitment to scalability and performance. By using Node.js as the runtime, it can handle high concurrency efficiently. The API is designed with both GET and POST endpoints, allowing for flexible querying of existing patterns and bulk insertion of new patterns, respectively. This dual-mode operation supports both real-time learning and batch processing scenarios, catering to various integration patterns within the Sophra ecosystem. Performance considerations are evident in the implementation, with careful attention to database transaction management for bulk inserts and efficient query construction for pattern retrieval. The use of Prisma’s $transaction ensures atomicity for multi-pattern insertions, while the GET endpoint employs pagination and flexible filtering to optimize query performance even as the pattern database grows. One of the unique features of this API is its ability to calculate and store derived metrics in real-time. For instance, it computes pattern confidence based on the number of adaptation rules applied, providing immediate feedback on the effectiveness of search optimizations. This real-time processing capability, combined with detailed error logging and structured response formats, makes the Search Patterns Learning API a powerful tool for driving Sophra’s adaptive search intelligence.

​
Exported Components

export async function GET(req: NextRequest): Promise<NextResponse>

​
GET Request Handler

The GET endpoint allows querying of stored search patterns with flexible filtering options.

​
Parameters

  • query: string - Search term for pattern matching
  • limit: number (optional, default: 10, max: 100) - Number of results to return
  • offset: number (optional, default: 0) - Offset for pagination
  • filters: object (optional) - Additional filtering criteria

​
Return Type

Promise<NextResponse> containing:
  • success: boolean
  • data: ModelState[] - Array of matching pattern records
  • metadata: object - Query metadata including count, query params, etc.

​
POST Request Handler

The POST endpoint enables bulk insertion of new search patterns for analysis and storage.

​
Request Body

{
  patterns: Array<{
    query: string;
    timestamp: string; // ISO 8601 datetime
    metadata: {
      relevantHits?: number;
      totalHits?: number;
      took?: number;
      adaptationRulesApplied?: number;
      searchType: string;
      facetsUsed?: boolean;
      source?: string;
    };
  }>;
}

​
Return Type

Promise<NextResponse> containing:
  • success: boolean
  • data: ModelState[] - Array of created pattern records
  • metadata: object - Processing metadata including counts and timings

​
Implementation Examples

const response = await fetch('/api/nous/learn/search-patterns?query=machine+learning&limit=20&offset=0');
const { success, data, metadata } = await response.json();

if (success) {
  console.log(`Found ${metadata.count} patterns matching "machine learning"`);
  data.forEach(pattern => {
    console.log(`Pattern: ${pattern.featureNames[0]}, Confidence: ${pattern.metrics[0].validationMetrics.pattern_confidence}`);
  });
}

​
Sophra Integration Details

The Search Patterns Learning API integrates deeply with Sophra’s core systems:
  1. Search Service: Sends real-time search pattern data for analysis and storage.
  2. Analytics Engine: Utilizes stored patterns for trend analysis and reporting.
  3. Machine Learning Pipeline: Consumes pattern data to train and update search relevance models.
Search Patterns Data Flow

​
Error Handling

The API implements comprehensive error handling:
  • Catches and logs Prisma-specific errors
  • Returns 500 status with detailed error information
  • Implements retry logic for transient database issues
  • Uses Zod for schema validation
  • Returns 400 status with specific validation failure details
  • Logs invalid requests for further analysis
  • Catches unexpected errors in a top-level try-catch
  • Logs errors with stack traces for debugging
  • Returns generic 500 error to clients to avoid exposing sensitive information

​
Data Flow

​
Performance Considerations

  • Implements database indexing on frequently queried fields (e.g., featureNames, modelType)
  • Uses Prisma’s $transaction for bulk inserts to optimize database operations
  • Implements caching layer (e.g., Redis) for frequently accessed patterns (not shown in current implementation)
Current implementation processes up to 100 patterns per request. For larger batch sizes, consider implementing a queue-based system for asynchronous processing.

​
Security Implementation

  • Assumes authentication is handled by an upstream middleware
  • Implements input sanitization using Zod schema validation
  • Utilizes Prisma’s parameterized queries to prevent SQL injection
Ensure proper rate limiting and authentication mechanisms are in place to protect against abuse of this API endpoint.

​
Configuration

DATABASE_URL=postgresql://username:password@localhost:5432/sophra
LOG_LEVEL=info
MAX_BATCH_SIZE=100

Integration Settings

  • Configure Prisma client in src/lib/shared/database/client.ts
  • Set up logging in src/lib/shared/logger.ts
  • Adjust Zod schemas for changing validation requirements
⌘I