Skip to main content
The Adaptation Rule Application API is a critical component of the Sophra system’s adaptive learning pipeline. This Next.js API route, implemented in TypeScript, serves as the entry point for applying adaptation rules to incoming requests. It leverages Sophra’s core adaptation engine to dynamically adjust system behavior based on predefined rules and real-time metrics. At its core, this component integrates tightly with Sophra’s database layer, logging system, and adaptation engine. It employs a robust request validation mechanism using Zod, ensuring that incoming data adheres to the expected schema before processing. This approach significantly reduces the risk of runtime errors and improves overall system stability. Architecturally, the component follows a modular design, separating concerns between request handling, data validation, rule fetching, and rule application. This separation allows for easier maintenance and future extensibility. The use of Prisma ORM for database interactions provides type-safe database queries, enhancing reliability and performance. Performance-wise, the component is optimized for quick response times. It employs efficient database querying by fetching only the necessary rules based on provided IDs and their enabled status. The adaptation engine’s state is updated with new metrics and context for each request, ensuring that rule evaluations are based on the most current data. A unique feature of this component is its ability to handle batched rule applications. Multiple rule IDs can be provided in a single request, allowing for complex, multi-faceted adaptations to be applied simultaneously. This capability is crucial for scenarios where interdependent rules need to be evaluated together for coherent system adaptation.

​
Exported Components

export const runtime = "nodejs";

export async function POST(req: NextRequest): Promise<NextResponse>
The POST function is the main export of this component. It handles incoming HTTP POST requests and returns a NextResponse.
  • Parameters:
    • req: NextRequest - The incoming request object from Next.js
  • Return Type: Promise<NextResponse> - A promise that resolves to a Next.js response object

​
Implementation Examples

// Example usage in a client application
const response = await fetch('/api/nous/adapt/apply', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ruleIds: ['rule1', 'rule2'],
    context: { userType: 'premium', region: 'EU' },
    metrics: { searchLatency: 150, conversionRate: 0.05 },
  }),
});

const result = await response.json();
console.log(result);
This example demonstrates how a client application might interact with the Adaptation Rule Application API. It sends a POST request with rule IDs, context, and metrics data.

​
Sophra Integration Details

The component integrates with several core Sophra services:
  1. Database Layer: Uses Prisma client to fetch adaptation rules.
  2. Adaptation Engine: Updates engine state and evaluates events.
  3. Logging System: Utilizes the shared logger for error and info logging.

​
Error Handling

The component implements comprehensive error handling:
  • Uses Zod for schema validation
  • Returns 400 Bad Request with detailed error information
  • Catches and logs any Prisma-related errors
  • Returns 500 Internal Server Error with a generic message
  • Catches and logs any errors during rule evaluation
  • Returns 500 Internal Server Error with details if available

​
Performance Considerations

Optimization Strategies

  • Efficient database querying using Prisma’s findMany with filters
  • Batched rule application to minimize API calls
  • Use of Date.now() for lightweight performance timing

​
Security Implementation

This component assumes that authentication and authorization have been handled by upstream middleware. It focuses on input validation and safe data handling.
  • Input validation using Zod schema
  • No direct exposure of database errors to clients
  • Logging of application events for audit trails

​
Configuration

POSTGRESQL_URL="your-database-url"
The component relies on the following environment variables:
  • POSTGRESQL_URL: Connection string for the Prisma database client
Ensure that the Prisma schema includes the AdaptationRule model with the necessary fields (id, enabled, etc.).
⌘I