soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

feat: add simplified LLM commands and presets with detailed CLI support

Browse source 
Implemented new simplified commands (`create-simple`, `train-simple`, `generate-simple`) for easier LLM model management. Added pre-configured model presets (`tiny`, `small`, `medium`, `large`) and enhanced options to streamline usage for beginners. Updated CLI and API documentation with detailed examples. Incremented version to 0.8.0.
This commit is contained in:
David Snelling 2025-06-10 11:47:05 -07:00
parent cb43391ee2
commit f0537a3fc4
4 changed files with 569 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

160
docs/llm-augmentation.md
View file

@ -30,7 +30,7 @@ npm install @soulcraft/brainy --legacy-peer-deps
## Usage
### Basic Usage
### Simplified Usage (Recommended for New Users)
```javascript
import { BrainyData, augmentationPipeline } from '@soulcraft/brainy'
@ -51,7 +51,42 @@ const { cognition, activation } = await createLLMAugmentations({
augmentationPipeline.register(cognition)
augmentationPipeline.register(activation)
// Create a model
// Create a model using a preset (tiny, small, medium, large)
const createResult = await cognition.createModelFromPreset('small', 'my-model')
const modelId = createResult.data.modelId
// Train the model with simplified options (quick, standard, thorough)
await cognition.trainModelSimple(modelId, 'standard')
// Generate text with simplified creativity options (conservative, balanced, creative)
const generateResult = await cognition.generateTextSimple(modelId, 'What is a', 'balanced')
console.log(`Generated text: ${generateResult.data.text}`)
```
### Advanced Usage
```javascript
import { BrainyData, augmentationPipeline } from '@soulcraft/brainy'
import { createLLMAugmentations } from '@soulcraft/brainy/src/augmentations/llmAugmentations.js'
// Initialize Brainy
const db = new BrainyData()
await db.init()
// Create LLM augmentations
const { cognition, activation } = await createLLMAugmentations({
cognitionName: 'my-llm-cognition',
activationName: 'my-llm-activation',
brainyDb: db
})
// Register augmentations with the pipeline
augmentationPipeline.register(cognition)
augmentationPipeline.register(activation)
// Create a model with advanced configuration
const createResult = await cognition.createModel({
name: 'my-model',
modelType: 'simple',
@ -63,18 +98,18 @@ const createResult = await cognition.createModel({
const modelId = createResult.data.modelId
// Train the model
// Train the model with advanced options
await cognition.trainModel(modelId, {
maxSamples: 100,
validationSplit: 0.2
})
// Generate text
// Generate text with advanced options
const generateResult = await cognition.generateText(modelId, 'What is a', {
temperature: 0.7
})
console.log(`Generated text: ${generateResult.data}`)
console.log(`Generated text: ${generateResult.data.text}`)
```
### Using the Augmentation Pipeline
@ -93,7 +128,7 @@ const pipelineCreateResult = await augmentationPipeline.executeCognitionPipeline
if (pipelineCreateResult[0] && (await pipelineCreateResult[0]).success) {
const pipelineModelId = (await pipelineCreateResult[0]).data.modelId
// Train the model through the pipeline
await augmentationPipeline.executeCognitionPipeline(
'trainModel',
@ -102,11 +137,122 @@ if (pipelineCreateResult[0] && (await pipelineCreateResult[0]).success) {
}
```
## CLI Usage
The LLM functionality is also available through the Brainy CLI. The CLI provides both simplified and advanced commands for working with LLM models.
### Simplified CLI Commands (Recommended for New Users)
```bash
# Create a model using a preset (tiny, small, medium, large)
brainy llm create-simple [preset] --name my-model
# Train a model with simplified options (quick, standard, thorough)
brainy llm train-simple <modelId> [level]
# Generate text with simplified creativity options (conservative, balanced, creative)
brainy llm generate-simple <modelId> "Your prompt here" [creativity]
```
### Advanced CLI Commands
```bash
# Create a model with advanced configuration
brainy llm create --name my-model --type simple --vocab-size 5000
# Train a model with advanced options
brainy llm train <modelId> --max-samples 100 --epochs 10
# Test a model
brainy llm test <modelId> --generate-samples
# Export a model
brainy llm export <modelId> --format json --include-metadata
# Deploy a model
brainy llm deploy <modelId> --target browser
# Generate text with advanced options
brainy llm generate <modelId> "Your prompt here" --temperature 0.7
```
## API Reference
### LLMCognitionAugmentation
#### Creating Models
#### Simplified Methods (Recommended for New Users)
##### Creating Models with Presets
```javascript
createModelFromPreset(presetName: string = 'small', customName?: string): Promise<AugmentationResponse<{ modelId: string, metadata: LLMModelMetadata }>>
```
Creates a new LLM model using a predefined preset.
**Parameters:**
- `presetName`: Name of the preset to use ('tiny', 'small', 'medium', 'large')
- `customName`: Optional custom name for the model
**Returns:**
- `modelId`: Unique identifier for the created model
- `metadata`: Metadata about the model
**Preset Details:**
- `tiny`: Simple model with minimal parameters, fast but less accurate
- `small`: Simple model with balanced parameters, good for most use cases
- `medium`: Transformer model with moderate parameters, better accuracy
- `large`: Transformer model with more parameters, best accuracy but slower
##### Training Models with Simplified Options
```javascript
trainModelSimple(modelId: string, trainingLevel: 'quick' | 'standard' | 'thorough' = 'standard'): Promise<AugmentationResponse<{ modelId: string, metadata: LLMModelMetadata, trainingHistory: tf.History, metrics?: { loss: number, accuracy: number, epochs: number } }>>
```
Trains an LLM model with simplified options.
**Parameters:**
- `modelId`: ID of the model to train
- `trainingLevel`: Training level ('quick', 'standard', 'thorough')
**Returns:**
- `modelId`: ID of the trained model
- `metadata`: Updated metadata about the model
- `trainingHistory`: Training history with metrics
- `metrics`: Training metrics (loss, accuracy, epochs)
**Training Level Details:**
- `quick`: Faster training with fewer samples (100 samples, 5 epochs)
- `standard`: Balanced training (500 samples, 10 epochs)
- `thorough`: More thorough training for better results (1000 samples, 20 epochs)
##### Generating Text with Simplified Creativity Options
```javascript
generateTextSimple(modelId: string, prompt: string, creativity: 'conservative' | 'balanced' | 'creative' = 'balanced'): Promise<AugmentationResponse<{ text: string, tokens?: number, timeMs?: number }>>
```
Generates text using the LLM model with simplified creativity options.
**Parameters:**
- `modelId`: ID of the model to use
- `prompt`: Input prompt for text generation
- `creativity`: Creativity level ('conservative', 'balanced', 'creative')
**Returns:**
- `text`: Generated text
- `tokens`: Number of tokens generated (if available)
- `timeMs`: Generation time in milliseconds (if available)
**Creativity Level Details:**
- `conservative`: More predictable, focused output (temperature: 0.3, topK: 3)
- `balanced`: Mix of predictability and creativity (temperature: 0.7, topK: 5)
- `creative`: More varied, unexpected output (temperature: 1.0, topK: 10)
#### Advanced Methods
##### Creating Models
```javascript
createModel(config: Partial<LLMModelConfig>): Promise<AugmentationResponse<{ modelId: string, metadata: LLMModelMetadata }>>

257
src/augmentations/llmAugmentations.ts
View file

@ -74,6 +74,8 @@ interface LLMTrainingOptions {
includeEmbeddings?: boolean
augmentData?: boolean
earlyStoppingPatience?: number
epochs?: number
batchSize?: number
}
/**
@ -145,6 +147,60 @@ export class LLMCognitionAugmentation implements ICognitionAugmentation {
epochs: 10
}
// Simplified model presets for easy model creation
private modelPresets: Record<string, Partial<LLMModelConfig>> = {
'tiny': {
name: 'tiny-llm-model',
modelType: 'simple',
vocabSize: 3000,
embeddingDim: 32,
hiddenDim: 64,
numLayers: 1,
dropoutRate: 0.1,
maxSequenceLength: 50,
batchSize: 16,
epochs: 5
},
'small': {
name: 'small-llm-model',
modelType: 'simple',
vocabSize: 5000,
embeddingDim: 64,
hiddenDim: 128,
numLayers: 2,
dropoutRate: 0.1,
maxSequenceLength: 100,
batchSize: 32,
epochs: 10
},
'medium': {
name: 'medium-llm-model',
modelType: 'transformer',
vocabSize: 8000,
embeddingDim: 128,
hiddenDim: 256,
numLayers: 3,
numHeads: 4,
dropoutRate: 0.1,
maxSequenceLength: 200,
batchSize: 32,
epochs: 15
},
'large': {
name: 'large-llm-model',
modelType: 'transformer',
vocabSize: 10000,
embeddingDim: 256,
hiddenDim: 512,
numLayers: 4,
numHeads: 8,
dropoutRate: 0.1,
maxSequenceLength: 300,
batchSize: 16,
epochs: 20
}
}
constructor(name: string = 'llm-cognition') {
this.name = name
}
@ -214,6 +270,33 @@ export class LLMCognitionAugmentation implements ICognitionAugmentation {
return this.brainyDb
}
/**
* Create a new LLM model from Brainy data using a preset
* @param presetName Name of the preset to use ('tiny', 'small', 'medium', 'large')
* @param customName Optional custom name for the model
* @returns Model ID and metadata
*/
async createModelFromPreset(
presetName: string = 'small',
customName?: string
): Promise<AugmentationResponse<{ modelId: string, metadata: LLMModelMetadata }>> {
const preset = this.modelPresets[presetName];
if (!preset) {
return {
success: false,
data: null as any,
error: `Unknown preset: ${presetName}. Available presets: ${Object.keys(this.modelPresets).join(', ')}`
};
}
const config = { ...preset };
if (customName) {
config.name = customName;
}
return this.createModel(config);
}
/**
* Create a new LLM model from Brainy data
* @param config Configuration for the model
@ -465,6 +548,53 @@ export class LLMCognitionAugmentation implements ICognitionAugmentation {
return positionEncoding
}
/**
* Train an LLM model with simplified options
* @param modelId ID of the model to train
* @param trainingLevel Training level ('quick', 'standard', 'thorough')
* @returns Training results
*/
async trainModelSimple(
modelId: string,
trainingLevel: 'quick' | 'standard' | 'thorough' = 'standard'
): Promise<AugmentationResponse<{
modelId: string,
metadata: LLMModelMetadata,
trainingHistory: tf.History,
metrics?: {
loss: number,
accuracy: number,
epochs: number
}
}>> {
// Define training options based on level
const trainingOptions: LLMTrainingOptions = {};
switch (trainingLevel) {
case 'quick':
trainingOptions.maxSamples = 100;
trainingOptions.epochs = 5;
trainingOptions.batchSize = 32;
trainingOptions.validationSplit = 0.1;
break;
case 'standard':
trainingOptions.maxSamples = 500;
trainingOptions.epochs = 10;
trainingOptions.batchSize = 32;
trainingOptions.validationSplit = 0.2;
break;
case 'thorough':
trainingOptions.maxSamples = 1000;
trainingOptions.epochs = 20;
trainingOptions.batchSize = 16;
trainingOptions.validationSplit = 0.2;
trainingOptions.earlyStoppingPatience = 5;
break;
}
return this.trainModel(modelId, trainingOptions);
}
/**
* Train an LLM model on Brainy data
* @param modelId ID of the model to train
@ -537,8 +667,8 @@ export class LLMCognitionAugmentation implements ICognitionAugmentation {
// Train the model
const history = await model.fit(xs, ys, {
epochs: this.defaultModelConfig.epochs,
batchSize: this.defaultModelConfig.batchSize,
epochs: options.epochs || this.defaultModelConfig.epochs,
batchSize: options.batchSize || this.defaultModelConfig.batchSize,
validationSplit: options.validationSplit || 0.2,
callbacks: tf.callbacks.earlyStopping({
monitor: 'val_loss',
@ -1153,6 +1283,50 @@ export class LLMCognitionAugmentation implements ICognitionAugmentation {
}
}
/**
* Generate text using the LLM model with simplified creativity options
* @param modelId ID of the model to use
* @param prompt Input prompt
* @param creativity Creativity level ('conservative', 'balanced', 'creative')
* @returns Generated text
*/
async generateTextSimple(
modelId: string,
prompt: string,
creativity: 'conservative' | 'balanced' | 'creative' = 'balanced'
): Promise<AugmentationResponse<{
text: string,
tokens?: number,
timeMs?: number
}>> {
// Define generation options based on creativity level
const generationOptions: {
maxLength?: number,
temperature?: number,
topK?: number
} = {};
switch (creativity) {
case 'conservative':
generationOptions.temperature = 0.3;
generationOptions.topK = 3;
generationOptions.maxLength = 50;
break;
case 'balanced':
generationOptions.temperature = 0.7;
generationOptions.topK = 5;
generationOptions.maxLength = 100;
break;
case 'creative':
generationOptions.temperature = 1.0;
generationOptions.topK = 10;
generationOptions.maxLength = 200;
break;
}
return this.generateText(modelId, prompt, generationOptions);
}
/**
* Generate text using the LLM model
* @param modelId ID of the model to use
@ -1440,8 +1614,12 @@ export class LLMActivationAugmentation implements IActivationAugmentation {
switch (actionName) {
case 'createModel':
return this.handleCreateModel(parameters || {})
case 'createModelSimple':
return this.handleCreateModelSimple(parameters || {})
case 'trainModel':
return this.handleTrainModel(parameters || {})
case 'trainModelSimple':
return this.handleTrainModelSimple(parameters || {})
case 'testModel':
return this.handleTestModel(parameters || {})
case 'exportModel':
@ -1450,6 +1628,8 @@ export class LLMActivationAugmentation implements IActivationAugmentation {
return this.handleDeployModel(parameters || {})
case 'generateText':
return this.handleGenerateText(parameters || {})
case 'generateTextSimple':
return this.handleGenerateTextSimple(parameters || {})
default:
return {
success: false,
@ -1584,6 +1764,79 @@ export class LLMActivationAugmentation implements IActivationAugmentation {
}
}
/**
* Handle the createModelSimple action
* @param parameters Action parameters
*/
private handleCreateModelSimple(
parameters: Record<string, unknown>
): AugmentationResponse<unknown> {
const presetName = parameters.preset as string || 'small'
const customName = parameters.name as string
return {
success: true,
data: this.cognitionAugmentation!.createModelFromPreset(presetName, customName)
}
}
/**
* Handle the trainModelSimple action
* @param parameters Action parameters
*/
private handleTrainModelSimple(
parameters: Record<string, unknown>
): AugmentationResponse<unknown> {
const modelId = parameters.modelId as string
const trainingLevel = parameters.level as 'quick' | 'standard' | 'thorough' || 'standard'
if (!modelId) {
return {
success: false,
data: null,
error: 'modelId parameter is required'
}
}
return {
success: true,
data: this.cognitionAugmentation!.trainModelSimple(modelId, trainingLevel)
}
}
/**
* Handle the generateTextSimple action
* @param parameters Action parameters
*/
private handleGenerateTextSimple(
parameters: Record<string, unknown>
): AugmentationResponse<unknown> {
const modelId = parameters.modelId as string
const prompt = parameters.prompt as string
const creativity = parameters.creativity as 'conservative' | 'balanced' | 'creative' || 'balanced'
if (!modelId) {
return {
success: false,
data: null,
error: 'modelId parameter is required'
}
}
if (!prompt) {
return {
success: false,
data: null,
error: 'prompt parameter is required'
}
}
return {
success: true,
data: this.cognitionAugmentation!.generateTextSimple(modelId, prompt, creativity)
}
}
/**
* Handle the generateText action
* @param parameters Action parameters

190
src/cli.ts
View file

@ -1149,14 +1149,58 @@ program
console.log('Autocomplete setup complete. Please restart your shell.')
})
// Helper function to initialize LLM augmentations and database
async function initializeLLM() {
const db = createDb();
await db.init();
// Initialize LLM augmentations
const { cognition, activation } = await createLLMAugmentations();
// Set the database for the cognition augmentation
cognition.setBrainyDb(db);
return { db, cognition, activation };
}
// Parse command line arguments
// LLM Commands
const llmCommand = new Command('llm')
.description('LLM (Language Learning Model) operations')
llmCommand
.command('create-simple')
.description('Create a new LLM model using a preset (tiny, small, medium, large)')
.argument('[preset]', 'Model preset to use (tiny, small, medium, large)', 'small')
.option('-n, --name <name>', 'Custom name for the model')
.action(async (preset, options) => {
try {
console.log(`Creating LLM model using '${preset}' preset...`)
// Initialize LLM
const { cognition } = await initializeLLM();
// Create the model using preset
const result = await cognition.createModelFromPreset(preset, options.name);
if (result.success) {
console.log(`Model created successfully with ID: ${result.data.modelId}`)
console.log(`Model name: ${result.data.metadata.name}`)
console.log(`Model type: ${result.data.metadata.modelType}`)
console.log(`\nUse this ID with other commands, for example:`)
console.log(` brainy llm train-simple ${result.data.modelId} standard`)
} else {
console.error(`Failed to create model: ${result.error}`)
}
} catch (error) {
console.error('Error:', (error as Error).message)
process.exit(1)
}
})
llmCommand
.command('create')
.description('Create a new LLM model from Brainy data')
.description('Create a new LLM model from Brainy data (advanced)')
.option('-n, --name <name>', 'Name of the model')
.option('-d, --description <description>', 'Description of the model')
.option('-t, --type <type>', 'Type of model (simple, transformer, custom)', 'simple')
@ -1169,16 +1213,10 @@ llmCommand
.option('--max-seq-length <length>', 'Maximum sequence length', '100')
.action(async (options) => {
try {
const db = createDb()
await db.init()
console.log('Creating LLM model with advanced options...')
console.log('Creating LLM model...')
// Initialize LLM augmentations
const { cognition, activation } = await createLLMAugmentations()
// Set the database for the cognition augmentation
cognition.setBrainyDb(db)
// Initialize LLM
const { cognition } = await initializeLLM();
// Parse options
const config = {
@ -1211,9 +1249,59 @@ llmCommand
}
})
llmCommand
.command('train-simple')
.description('Train an LLM model with simplified options')
.argument('<modelId>', 'ID of the model to train')
.argument('[level]', 'Training level (quick, standard, thorough)', 'standard')
.action(async (modelId, level) => {
try {
console.log(`Training LLM model ${modelId} with '${level}' training level...`)
// Initialize LLM
const { cognition } = await initializeLLM();
// Display training level details
switch (level) {
case 'quick':
console.log('Quick training: Faster but less accurate (100 samples, 5 epochs)')
break;
case 'standard':
console.log('Standard training: Balanced speed and accuracy (500 samples, 10 epochs)')
break;
case 'thorough':
console.log('Thorough training: Slower but more accurate (1000 samples, 20 epochs)')
break;
default:
console.log(`Unknown level '${level}', using 'standard' instead`)
level = 'standard';
}
// Train the model
const result = await cognition.trainModelSimple(modelId, level as any)
if (result.success) {
console.log(`\nModel ${modelId} trained successfully!`)
console.log(`Training metrics:`)
if (result.data.metrics) {
console.log(` Final loss: ${result.data.metrics.loss.toFixed(4)}`)
console.log(` Final accuracy: ${result.data.metrics.accuracy.toFixed(4)}`)
console.log(` Epochs completed: ${result.data.metrics.epochs}`)
}
console.log(`\nYou can now generate text with:`)
console.log(` brainy llm generate-simple ${modelId} "Your prompt here"`)
} else {
console.error(`\nFailed to train model: ${result.error}`)
}
} catch (error) {
console.error('Error:', (error as Error).message)
process.exit(1)
}
})
llmCommand
.command('train')
.description('Train an LLM model on Brainy data')
.description('Train an LLM model on Brainy data (advanced)')
.argument('<modelId>', 'ID of the model to train')
.option('-s, --max-samples <count>', 'Maximum number of training samples')
.option('-v, --validation-split <ratio>', 'Validation split ratio', '0.2')
@ -1222,16 +1310,10 @@ llmCommand
.option('-p, --patience <count>', 'Early stopping patience', '3')
.action(async (modelId, options) => {
try {
const db = createDb()
await db.init()
console.log(`Training LLM model ${modelId} with advanced options...`)
console.log(`Training LLM model ${modelId}...`)
// Initialize LLM augmentations
const { cognition, activation } = await createLLMAugmentations()
// Set the database for the cognition augmentation
cognition.setBrainyDb(db)
// Initialize LLM
const { cognition } = await initializeLLM();
// Parse options
const trainingOptions = {
@ -1458,9 +1540,63 @@ llmCommand
}
})
llmCommand
.command('generate-simple')
.description('Generate text using an LLM model with simplified creativity options')
.argument('<modelId>', 'ID of the model to use')
.argument('<prompt>', 'Input prompt for text generation')
.argument('[creativity]', 'Creativity level (conservative, balanced, creative)', 'balanced')
.action(async (modelId, prompt, creativity) => {
try {
console.log(`Generating text using LLM model ${modelId}...`)
console.log(`Prompt: "${prompt}"`)
// Initialize LLM
const { cognition } = await initializeLLM();
// Display creativity level details
switch (creativity) {
case 'conservative':
console.log('Conservative creativity: More predictable, focused output')
break;
case 'balanced':
console.log('Balanced creativity: Mix of predictability and creativity')
break;
case 'creative':
console.log('High creativity: More varied, unexpected output')
break;
default:
console.log(`Unknown creativity level '${creativity}', using 'balanced' instead`)
creativity = 'balanced';
}
// Generate text
const result = await cognition.generateTextSimple(modelId, prompt, creativity as any)
if (result.success) {
console.log(`\nGenerated text:`)
console.log(`--------------`)
console.log(result.data.text)
console.log(`--------------`)
if (result.data.tokens) {
console.log(`\nTokens generated: ${result.data.tokens}`)
}
if (result.data.timeMs) {
console.log(`Generation time: ${result.data.timeMs}ms`)
}
} else {
console.error(`\nFailed to generate text: ${result.error}`)
}
} catch (error) {
console.error('Error:', (error as Error).message)
process.exit(1)
}
})
llmCommand
.command('generate')
.description('Generate text using an LLM model')
.description('Generate text using an LLM model (advanced)')
.argument('<modelId>', 'ID of the model to use')
.argument('<prompt>', 'Input prompt for text generation')
.option('-t, --temperature <temp>', 'Temperature for sampling', '0.7')
@ -1468,17 +1604,11 @@ llmCommand
.option('-l, --max-length <length>', 'Maximum length of generated text', '100')
.action(async (modelId, prompt, options) => {
try {
const db = createDb()
await db.init()
console.log(`Generating text using LLM model ${modelId}...`)
console.log(`Generating text using LLM model ${modelId} with advanced options...`)
console.log(`Prompt: "${prompt}"`)
// Initialize LLM augmentations
const { cognition, activation } = await createLLMAugmentations()
// Set the database for the cognition augmentation
cognition.setBrainyDb(db)
// Initialize LLM
const { cognition } = await initializeLLM();
// Parse options
const generateOptions = {

2
src/utils/version.ts
View file

@ -3,4 +3,4 @@
* Do not modify this file directly.
*/
export const VERSION = '0.7.7';
export const VERSION = '0.8.0';