family-ai-agent 1.0.0

package/src/safety/index.ts

@@ -0,0 +1,21 @@
+// Safety module exports
+export {
+  InputGuardrail,
+  getInputGuardrail,
+  validateInput,
+  type InputValidationResult,
+} from './guardrails/input-guardrail.js';
+
+export {
+  OutputGuardrail,
+  getOutputGuardrail,
+  validateOutput,
+  type OutputValidationResult,
+} from './guardrails/output-guardrail.js';
+
+export {
+  AuditLogger,
+  getAuditLogger,
+  type AuditLogEntry,
+  type AuditActionType,
+} from './audit-logger.js';

package/src/utils/errors.ts

@@ -0,0 +1,120 @@
+export class FamilyAIError extends Error {
+  public readonly code: string;
+  public readonly statusCode: number;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    code: string,
+    statusCode: number = 500,
+    details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'FamilyAIError';
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class ConfigurationError extends FamilyAIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'CONFIGURATION_ERROR', 500, details);
+    this.name = 'ConfigurationError';
+  }
+}
+
+export class LLMError extends FamilyAIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'LLM_ERROR', 502, details);
+    this.name = 'LLMError';
+  }
+}
+
+export class MemoryError extends FamilyAIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'MEMORY_ERROR', 500, details);
+    this.name = 'MemoryError';
+  }
+}
+
+export class ToolExecutionError extends FamilyAIError {
+  constructor(
+    message: string,
+    toolName: string,
+    details?: Record<string, unknown>
+  ) {
+    super(message, 'TOOL_EXECUTION_ERROR', 500, { toolName, ...details });
+    this.name = 'ToolExecutionError';
+  }
+}
+
+export class SafetyError extends FamilyAIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'SAFETY_ERROR', 403, details);
+    this.name = 'SafetyError';
+  }
+}
+
+export class ValidationError extends FamilyAIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'VALIDATION_ERROR', 400, details);
+    this.name = 'ValidationError';
+  }
+}
+
+export class AgentError extends FamilyAIError {
+  constructor(
+    message: string,
+    agentId: string,
+    details?: Record<string, unknown>
+  ) {
+    super(message, 'AGENT_ERROR', 500, { agentId, ...details });
+    this.name = 'AgentError';
+  }
+}
+
+export class RateLimitError extends FamilyAIError {
+  constructor(retryAfter?: number) {
+    super('Rate limit exceeded', 'RATE_LIMIT_ERROR', 429, { retryAfter });
+    this.name = 'RateLimitError';
+  }
+}
+
+export class SandboxError extends FamilyAIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'SANDBOX_ERROR', 500, details);
+    this.name = 'SandboxError';
+  }
+}
+
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof FamilyAIError) {
+    return (
+      error.code === 'LLM_ERROR' ||
+      error.code === 'RATE_LIMIT_ERROR' ||
+      error.statusCode >= 500
+    );
+  }
+  return false;
+}
+
+export function formatErrorForUser(error: unknown): string {
+  if (error instanceof SafetyError) {
+    return `Request blocked: ${error.message}`;
+  }
+  if (error instanceof ValidationError) {
+    return `Invalid input: ${error.message}`;
+  }
+  if (error instanceof RateLimitError) {
+    return 'Too many requests. Please wait a moment and try again.';
+  }
+  if (error instanceof FamilyAIError) {
+    return `An error occurred: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `Unexpected error: ${error.message}`;
+  }
+  return 'An unexpected error occurred';
+}

package/src/utils/logger.ts

@@ -0,0 +1,74 @@
+import winston from 'winston';
+import { config } from '../config/index.js';
+
+const { combine, timestamp, printf, colorize, json } = winston.format;
+
+const prettyFormat = printf(({ level, message, timestamp, ...metadata }) => {
+  let msg = `${timestamp} [${level}]: ${message}`;
+  if (Object.keys(metadata).length > 0) {
+    msg += ` ${JSON.stringify(metadata)}`;
+  }
+  return msg;
+});
+
+const logFormat =
+  config.LOG_FORMAT === 'pretty'
+    ? combine(colorize(), timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), prettyFormat)
+    : combine(timestamp(), json());
+
+export const logger = winston.createLogger({
+  level: config.LOG_LEVEL,
+  format: logFormat,
+  defaultMeta: { service: 'family-ai-agent' },
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({
+      filename: 'logs/error.log',
+      level: 'error',
+    }),
+    new winston.transports.File({
+      filename: 'logs/combined.log',
+    }),
+  ],
+});
+
+// Create a child logger for specific components
+export function createLogger(component: string) {
+  return logger.child({ component });
+}
+
+// Structured logging helpers
+export function logAgentAction(
+  agentId: string,
+  action: string,
+  details: Record<string, unknown>
+) {
+  logger.info('Agent action', { agentId, action, ...details });
+}
+
+export function logToolExecution(
+  toolName: string,
+  input: unknown,
+  output: unknown,
+  durationMs: number
+) {
+  logger.debug('Tool execution', { toolName, input, output, durationMs });
+}
+
+export function logMemoryOperation(
+  operation: 'read' | 'write' | 'search',
+  memoryType: string,
+  details: Record<string, unknown>
+) {
+  logger.debug('Memory operation', { operation, memoryType, ...details });
+}
+
+export function logSafetyEvent(
+  eventType: string,
+  blocked: boolean,
+  reason?: string,
+  details?: Record<string, unknown>
+) {
+  const level = blocked ? 'warn' : 'info';
+  logger.log(level, 'Safety event', { eventType, blocked, reason, ...details });
+}

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": false,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@core/*": ["./src/core/*"],
+      "@memory/*": ["./src/memory/*"],
+      "@tools/*": ["./src/tools/*"],
+      "@safety/*": ["./src/safety/*"],
+      "@llm/*": ["./src/llm/*"],
+      "@api/*": ["./src/api/*"],
+      "@cli/*": ["./src/cli/*"],
+      "@config/*": ["./src/config/*"],
+      "@utils/*": ["./src/utils/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}