AIDK API Reference / aidk-server

aidk-server

AIDK Server

Framework-agnostic utilities for engine backend implementations. Works with Express, NestJS, Fastify, or any Node.js server framework.

Features

• Persistence Repositories - Store executions, messages, metrics
• In-Memory Store - Development and testing storage
• Context Utilities - Extract and manage request context
• ID Generators - UUID and prefixed ID generation

Quick Start

import {
  createInMemoryRepositories,
  defaultContextExtractor,
  buildEngineContext,
} from 'aidk-server';

// Create persistence layer
const repos = createInMemoryRepositories();

// Extract context from request
const ctx = defaultContextExtractor(req.body, req.headers);

// Build engine context
const engineCtx = buildEngineContext({ ...ctx, executionId: 'exec_123' });

Classes

Class	Description
InMemoryExecutionRepository	-
InMemoryInteractionRepository	-
InMemoryMessageBlockRepository	-
InMemoryMessageRepository	-
InMemoryMetricsRepository	-
InMemoryToolStateRepository	-

Interfaces

Interface	Description
ExecutionContext	Full execution context passed to handlers. Built by middleware from request + config.
ExecutionContextConfig	Configuration for execution context middleware. Framework adapters use this to build their middleware.
ExecutionEntity	-
ExecutionRepository	-
InMemoryStore	-
InteractionEntity	-
InteractionRepository	-
MessageBlockEntity	-
MessageBlockRepository	-
MessageEntity	-
MessageRepository	-
MetricsEntity	-
MetricsRepository	-
PersistenceRepositories	-
RequestContext	Extracted context from an incoming request. Framework adapters map their request shape to this.
RequestWithContext	Generic request-like object that can have context attached. Works with Express, Fastify, Koa, NestJS, etc.
StandardRequestBody	Raw request body shape (our conventions). Apps with different conventions provide their own extractor.
ToolStateEntity	-
ToolStateRepository	-

Type Aliases

Type Alias	Description
ContextExtractor	-
IdGenerator	-
InputTransformer	-

Variables

Variable	Description
AIDK_CONTEXT_KEY	Symbol key for storing AIDK context on request objects. Using a symbol prevents collisions with other properties.
defaultContextExtractor	Default context extractor following our conventions. Override this for apps with different field names or auth patterns.
defaultInputTransformer	Default input transformer following our conventions. Expects messages in body, transforms to Engine timeline format.
uuidV4Generator	Default UUID v4 generator

Functions

Function	Description
attachContext	Attach AIDK context to a request object. Call this in your framework's middleware/interceptor after extracting context.
buildEngineContext	Build the withContext options for engine execution
clearStore	Clear all data from a store
createContextExtractor	Create a context extractor with custom field mappings
createIdGenerator	Create an ID generator that uses a provided function Useful for DB sequences, UUIDv7, etc.
createInMemoryRepositories	Create all repositories backed by an in-memory store
createInMemoryStore	Create a new in-memory store instance
createInputTransformer	Create an input transformer with custom transformation logic
createPrefixedIdGenerator	Create a prefixed ID generator
generateUUID	Generate a UUID v4
getContext	Get AIDK context from a request object. Returns undefined if no context has been attached.
messagesToTimeline	Transform standard message format to Engine timeline. Uses loose typing to handle various frontend message formats.
requireContext	Get AIDK context from a request object, throwing if not present.
resolveConfig	Resolved config with defaults applied