ml/agent-framework

@lilith/ml-agent-framework

Reusable framework for building ML agents with Fastify server, configuration management, and query runtime.

Features

• Agent Factory: Create configured agent instances with consistent patterns
• Fastify Server: HTTP server with CORS, health checks, and consult endpoints
• Configuration System: Validated config with host config, paths, and security
• Query Runtime: Execute agent queries with speech callback support
• Claude Integration: Re-exports from @lilith/ml-agent-claude

Installation

pnpm add @lilith/ml-agent-framework

Quick Start

import {
  createAgent,
  createFastifyServer,
  runAgentQuery,
} from '@lilith/ml-agent-framework';

// Create an agent
const agent = await createAgent({
  name: 'my-agent',
  personality: {
    name: 'Assistant',
    description: 'A helpful AI assistant',
    systemPrompt: 'You are a helpful assistant.',
  },
  config: {
    // Configuration options
  },
});

// Start the server
const server = await createFastifyServer(agent, {
  port: 3000,
  host: '0.0.0.0',
});

// Or run queries directly
const result = await runAgentQuery({
  agent,
  query: 'Hello, how can you help me?',
  onSpeech: (text) => console.log('Speech:', text),
});

API Reference

Factory

createAgent(options)

Create a configured agent instance.

interface CreateAgentOptions {
  name: string;
  personality: AgentPersonality;
  config?: Partial<AgentConfig>;
  knowledge?: KnowledgeOptions;
}

const agent = await createAgent({
  name: 'my-agent',
  personality: {
    name: 'Assistant',
    description: 'Helpful AI assistant',
    systemPrompt: 'You are helpful.',
  },
});

Configuration

createConfig(options)

Create a validated configuration object.

const config = createConfig({
  contextLimit: 100000,
  securityConfig: {
    maxInputLength: 10000,
  },
});

validateConfig(config)

Validate a configuration object.

const { valid, errors } = validateConfig(config);

readHostConfig() / saveHostConfig(config)

Read and write host-level configuration.

const hostConfig = await readHostConfig();
await saveHostConfig({
  ...hostConfig,
  projectPath: '/path/to/project',
});

Runtime

runAgentQuery(options)

Execute a query against an agent.

interface QueryRunnerOptions {
  agent: Agent;
  query: string;
  conversationId?: string;
  onSpeech?: SpeechCallback;
}

const result = await runAgentQuery({
  agent,
  query: 'What is the weather?',
  onSpeech: (text, isFinal) => {
    console.log(isFinal ? 'Final:' : 'Partial:', text);
  },
});

Server

createFastifyServer(agent, config)

Create a Fastify HTTP server for an agent.

interface ServerConfig {
  port: number;
  host?: string;
  cors?: CorsOptions;
}

const server = await createFastifyServer(agent, {
  port: 3000,
  host: '0.0.0.0',
  cors: {
    origin: ['http://localhost:5173'],
  },
});

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/agent	Get agent info
POST	/consult	Send query to agent
GET	/consult/stream	SSE stream for responses

Request/Response Schemas

interface ConsultRequest {
  query: string;
  conversationId?: string;
  stream?: boolean;
}

interface ConsultResponse {
  response: string;
  conversationId: string;
  usage?: UsageInfo;
}

interface HealthResponse {
  status: 'ok' | 'degraded' | 'error';
  version: string;
  uptime: number;
}

Types

Agent

interface Agent {
  name: string;
  personality: AgentPersonality;
  config: AgentConfig;
  consult(query: string, options?: ConsultOptions): Promise<AgentResult>;
}

interface AgentPersonality {
  name: string;
  description: string;
  systemPrompt: string;
  voice?: string;
}

interface AgentResult {
  response: string;
  usage?: UsageInfo;
  speechSegments?: string[];
}

Configuration

interface AgentConfig {
  contextLimit: number;
  basePaths: BasePaths;
  security: SecurityConfig;
  tts?: AgentTTSConfig;
}

interface HostConfig {
  projectPath?: string;
  username?: string;
  tts?: AgentTTSConfig;
}

Re-exports from @lilith/ml-agent-claude

export {
  DirectApiProvider,
  ClaudeMLProvider,
  createMcpServer,
  tool,
  z,
} from '@lilith/ml-agent-claude';

Dependencies

• fastify - HTTP server
• @fastify/cors - CORS support
• ioredis - Redis client
• zod - Schema validation
• @lilith/ml-agent-claude - Claude provider
• @lilith/ml-agent-core - Core agent functionality
• @lilith/ml-directory-semantic - Semantic directory operations

License

MIT