API Reference

Complete API documentation for all classes, methods, and interfaces in the Persona SDK.

Core Classes

Persona

Main persona class representing an individual with attributes.

Constructor

new Persona(name: string, attributes: PersonaAttributes)

Creates a new persona with required attributes: age, occupation, sex.

Properties

readonly id: string          // Unique identifier
readonly name: string        // Persona name
readonly age: number         // Age in years
readonly occupation: string  // Job/occupation
readonly sex: Sex           // 'male' | 'female' | 'other'
readonly attributes: Record<string, any> // Custom attributes

Methods

toObject(): PersonaData        // Serialize to plain object
toJSON(): string              // Serialize to JSON string
getSummary(): string          // Get human-readable summary
clone(newName?: string): Persona // Create a copy
setAttribute(key: string, value: any): void // Update attribute
getAttribute(key: string): any // Get attribute value
hasAttribute(key: string): boolean // Check if attribute exists

PersonaBuilder

Fluent API for constructing personas with method chaining.

Static Methods

PersonaBuilder.create(): PersonaBuilder
PersonaBuilder.fromPrompt(prompt: string, options?: AIOptions): Promise<Persona>
PersonaBuilder.generateMultiple(prompt: string, count: number, options?: AIOptions): Promise<Persona[]>

Builder Methods

withName(name: string | Distribution<string>): PersonaBuilder
withAge(age: number | Distribution<number>): PersonaBuilder
withOccupation(occupation: string | Distribution<string>): PersonaBuilder
withSex(sex: Sex): PersonaBuilder
withAttribute(key: string, value: any): PersonaBuilder
withAttributes(attributes: Record<string, any>): PersonaBuilder
withValidation(rules: ValidationRule[]): PersonaBuilder

Build Methods

build(): Persona
buildMany(count: number, namePrefix?: string): Persona[]
buildWithCorrelations(config: CorrelationConfig): Persona

PersonaGroup

Collection manager for multiple personas with analysis capabilities.

Constructor

new PersonaGroup(name: string, personas?: Persona[])

Properties

readonly name: string
readonly size: number
readonly personas: Persona[]

Methods

add(persona: Persona): void
addMany(personas: Persona[]): void
remove(id: string): boolean
clear(): void
find(predicate: (persona: Persona) => boolean): Persona | undefined
filter(predicate: (persona: Persona) => boolean): Persona[]
getStatistics(attribute: string): AttributeStatistics
groupBy(attribute: string): Map<any, Persona[]>
sample(count: number): Persona[]
toArray(): Persona[]
toObject(): GroupData

Distribution Classes

NormalDistribution

new NormalDistribution(
  mean: number,
  stdDev: number,
  seed?: number
)

UniformDistribution

new UniformDistribution(
  min: number,
  max: number,
  seed?: number
)

CategoricalDistribution

new CategoricalDistribution(
  categories: CategoryOption[],
  seed?: number
)

ExponentialDistribution

new ExponentialDistribution(
  lambda: number,
  seed?: number
)

Distribution Interface

All distributions implement the Distribution interface:

interface Distribution<T> {
  sample(): T;           // Generate a random sample
  mean(): number;        // Expected value
  variance(): number;    // Variance
  toString(): string;    // String representation
}

Type Definitions

Core Types

type Sex = 'male' | 'female' | 'other';

interface PersonaAttributes {
  age: number;
  occupation: string;
  sex: Sex;
  [key: string]: any;
}

interface PersonaData {
  id: string;
  name: string;
  attributes: PersonaAttributes;
}

interface GroupData {
  name: string;
  size: number;
  personas: PersonaData[];
}

Correlation Types

interface CorrelationConfig {
  attributes: Record<string, Distribution<any>>;
  correlations: Correlation[];
  conditionals?: Conditional[];
}

interface Correlation {
  attribute1: string;
  attribute2: string;
  correlation: number;
  type?: 'linear' | 'exponential' | 'logarithmic';
}

interface Conditional {
  attribute: string;
  dependsOn: string;
  transform: (value: any, dependency: any) => any;
}

AI Integration Types

interface AIOptions {
  apiKey: string;
  model?: string;
  temperature?: number;
  maxTokens?: number;
}

interface StructuredOutputSchema {
  name: string;
  description: string;
  schema: any; // Zod schema
}

📚 Additional Resources

• GitHub Repository - Source code and examples
• npm Package - Installation and version info
• TypeScript Support: Full type definitions included
• Node.js Compatibility: Requires Node.js 16+
• Browser Support: Modern browsers with ES2020+ support

Advanced Usage