homeschool/README.md

🏠 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.

# 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

```bash
npm install homeschool @xenova/transformers
```

## Quick Start

```typescript
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

```typescript
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)

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

### Gut Instinct Mode

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

### First Instinct Mode

```typescript
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:

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

### semantic_category

Extracts categories through contextual understanding:

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

### extracted_content

Isolates content from command words:

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

## Configuration Options

```typescript
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

```typescript
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

```typescript
// "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

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

### Content Display

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

## Advanced Usage

### Custom Parameter Extractors

```typescript
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

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

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

### Performance Monitoring

```typescript
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:

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

Semantic approach:

```typescript
// 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:

```bash
# 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](scripts/README.md) for more details.

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built on top of [Transformers.js](https://github.com/xenova/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.**