Homeschool

Teach AI to understand natural language like a patient tutor. Advanced embedding-based function calling with semantic understanding, confidence scoring, and natural language parameter extraction.

Why "Homeschool"? Just like homeschooling provides personalized, one-on-one education that adapts to how each student learns best, this library teaches AI to understand your specific vocabulary, context, and intent. It learns your patterns, builds confidence gradually, and grows smarter with each interaction.

Features

• Multi-Layer Semantic Analysis: Analyzes user queries at intent, context, and action levels
• Semantic Parameter Extraction: Uses embeddings to find parameter values instead of regex patterns
• Confidence Scoring: Provides transparency and prevents low-confidence executions
• Content Isolation: Distinguishes between command words and actual content semantically
• Extensible Architecture: Easy to add new tools without complex regex engineering
• Robust: Handles natural language variations, synonyms, and contextual understanding

Installation

npm install homeschool @xenova/transformers

Quick Start

import { SemanticFunctionCaller, exampleTools } from 'homeschool';

// Initialize the caller
const caller = new SemanticFunctionCaller({
  verbose: true,
  defaultConfidenceThreshold: 0.25,
});

// Register tools
caller.registerTools(exampleTools);

// Execute function calling
const result = await caller.execute('make the background orange');

if (result.success) {
  console.log(`Tool: ${result.tool}`);
  console.log(`Parameters:`, result.parameters);
  console.log(`Confidence: ${(result.confidence * 100).toFixed(1)}%`);
}

Creating Custom Tools

import { Tool } from 'homeschool';

const customTool: Tool = {
  name: 'playMusic',
  description: 'Plays music or audio content',
  contexts: [
    'audio and entertainment',
    'media control and playback',
    'music streaming and sound',
  ],
  intentPatterns: [
    'user wants to play audio',
    'user wants to listen to music',
    'user wants to start playback',
  ],
  parameters: {
    genre: {
      type: 'semantic_category',
      semanticCandidates: ['rock', 'pop', 'jazz', 'classical', 'electronic'],
      fallback: 'pop',
    },
    volume: {
      type: 'semantic_number',
      semanticCandidates: ['quiet', 'low', 'medium', 'high', 'loud'],
      fallback: 'medium',
    },
  },
};

caller.registerTools([customTool]);

Execution Modes

Standard Mode (Default)

const result = await caller.execute('remember to call mom', {
  confidenceThreshold: 0.3,
});

Gut Instinct Mode

const result = await caller.execute('make it blue', {
  gutInstinct: true, // Lower confidence threshold, trusts model intuition
});

First Instinct Mode

const result = await caller.executeFirstInstinct(
  'take a note about the meeting',
);
// Bypasses confidence checks completely, trusts top choice

Supported Parameter Types

semantic_color

Extracts colors using semantic similarity:

{
  type: 'semantic_color',
  semanticCandidates: ['red', 'blue', 'green', /* ... */],
  modifierCandidates: ['light', 'dark', 'bright'],
  fallback: 'blue'
}

semantic_category

Extracts categories through contextual understanding:

{
  type: 'semantic_category',
  semanticCandidates: ['work', 'personal', 'ideas', /* ... */],
  fallback: 'general'
}

extracted_content

Isolates content from command words:

{
  type: 'extracted_content',
  extractionStrategy: 'semantic_content_isolation'
}

Configuration Options

const caller = new SemanticFunctionCaller({
  embeddingModel: 'Xenova/all-MiniLM-L6-v2', // Hugging Face model
  defaultConfidenceThreshold: 0.25, // Confidence threshold
  enableCaching: true, // Cache embeddings
  verbose: false, // Debug logging
});

Understanding Results

interface ExecutionResult {
  success: boolean;
  tool?: string; // Selected tool name
  parameters?: Record<string, any>; // Extracted parameters
  confidence?: number; // Confidence score (0-1)
  reasoning?: Array<{
    // Detailed reasoning
    type: string;
    text: string;
    score: number;
  }>;
  mode?: 'standard' | 'first_instinct';
  reason?: string; // Failure reason if success = false
}

Real-World Examples

Note-Taking Assistant

// "remember to buy groceries and pick up dry cleaning"
{
  tool: 'takeNote',
  parameters: {
    note: 'buy groceries and pick up dry cleaning',
    category: 'personal'
  },
  confidence: 0.847
}

UI Control

// "make the page look more vibrant and energetic"
{
  tool: 'changeBackgroundColor',
  parameters: {
    color: 'vibrant orange'
  },
  confidence: 0.721
}

Content Display

// "show the user a welcome message"
{
  tool: 'displayText',
  parameters: {
    text: 'welcome message'
  },
  confidence: 0.892
}

Advanced Usage

Custom Parameter Extractors

import { extractSemanticColor, extractSemanticContent } from 'homeschool';

// Use extractors directly
const color = await extractSemanticColor(
  'make it crimson',
  colorConfig,
  embedder,
);
const content = await extractSemanticContent('display hello world', embedder);

Batch Processing

const queries = ['make it blue', 'remember the meeting', 'show welcome text'];

const results = await Promise.all(
  queries.map((query) => caller.execute(query)),
);

Performance Monitoring

console.log(`Cache size: ${caller.getCacheSize()}`);
caller.clearCache(); // Clear embedding cache if needed

Use Cases

• Chatbots & Virtual Assistants: Natural language command processing
• Game Development: Voice commands and natural language game controls
• Mobile Apps: Voice-driven app navigation and control
• Smart Home: Natural language device control
• Business Tools: Voice-driven workflow automation
• Creative Tools: Natural language creative software control

Migration from Regex-Based Systems

Traditional regex approach:

// Brittle regex patterns
if (/make.*background.*blue/i.test(query)) {
  return { tool: 'changeColor', color: 'blue' };
}

Semantic approach:

// Robust semantic understanding
const result = await caller.execute(query);
// Handles: "make it blue", "blue background", "change to blue", etc.

Development

Quick Publishing

Use the automated release scripts for easy publishing:

# Patch release (bug fixes, docs) - 0.1.1 → 0.1.2
npm run release

# Minor release (new features) - 0.1.1 → 0.2.0
npm run publish:minor

# Major release (breaking changes) - 0.1.1 → 1.0.0
npm run publish:major

These scripts automatically:

• Bump the version in package.json
• Run tests to ensure quality
• Build the TypeScript code
• Publish to npm

See scripts/README.md for more details.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see the LICENSE file for details.

Acknowledgments

• Built on top of Transformers.js
• Inspired by advances in semantic search and embedding-based AI
• Thanks to the open-source AI community

Made with care for developers who want to homeschool their AI to truly understand human language.