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

perf: pre-compute type embeddings at build time (zero runtime cost)

Browse source 
Major optimization - all type embeddings now built into package:

Build-time generation:
- Created scripts/buildTypeEmbeddings.ts to generate all type embeddings
- Generates embeddings for 31 NounTypes + 40 VerbTypes at build time
- Stores as base64-encoded binary data in embeddedTypeEmbeddings.ts
- Added check script to rebuild only when needed

Updated all consumers:
- NeuralEntityExtractor: loads pre-computed embeddings (instant)
- BrainyTypes: loads pre-computed embeddings (instant init)
- NaturalLanguageProcessor: loads pre-computed embeddings (instant init)

Build process:
- Added npm run build:types to generate embeddings
- Added npm run build:types:if-needed for conditional rebuild
- Integrated into main build pipeline
- Auto-rebuilds only when types or build script change

Benefits:
- Zero runtime cost - embeddings loaded instantly
- Survives all container restarts
- All 71 types always available (31 nouns + 40 verbs)
- ~100KB memory overhead for permanent performance gain
- Eliminates 5-10 second initialization delay

This completes the type embedding optimization started in v3.32.5
This commit is contained in:
David Snelling 2025-10-09 18:08:57 -07:00
parent 87eb60d527
commit 0d649b8a79
9 changed files with 643 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

36
src/augmentations/typeMatching/brainyTypes.ts
View file

@ -15,6 +15,7 @@ import { NounType, VerbType } from '../../types/graphTypes.js'
import { TransformerEmbedding } from '../../utils/embedding.js'
import { cosineDistance } from '../../utils/distance.js'
import { Vector } from '../../coreTypes.js'
import { getNounTypeEmbeddings, getVerbTypeEmbeddings } from '../../neural/embeddedTypeEmbeddings.js'
/**
* Type descriptions for semantic matching
@ -140,38 +141,45 @@ export interface TypeMatchResult {
/**
* BrainyTypes - Intelligent type detection for nouns and verbs
* PRODUCTION OPTIMIZATION (v3.33.0): Uses pre-computed type embeddings
* Type embeddings are loaded instantly; only input objects are embedded at runtime
*/
export class BrainyTypes {
private embedder: TransformerEmbedding
private embedder: TransformerEmbedding // Only for embedding input objects
private nounEmbeddings: Map<string, Vector> = new Map()
private verbEmbeddings: Map<string, Vector> = new Map()
private initialized = false
private cache: Map<string, TypeMatchResult> = new Map()
constructor() {
// Embedder only used for input objects, NOT for type embeddings
this.embedder = new TransformerEmbedding({ verbose: false })
}
/**
* Initialize the type matcher by generating embeddings for all types
* Initialize the type matcher by loading pre-computed embeddings
* INSTANT - type embeddings are loaded from pre-computed data
* Only the model for input embedding needs initialization
*/
async init(): Promise<void> {
if (this.initialized) return
// Initialize embedder for input objects only
await this.embedder.init()
// Generate embeddings for noun types
for (const [type, description] of Object.entries(NOUN_TYPE_DESCRIPTIONS)) {
const embedding = await this.embedder.embed(description)
// Load pre-computed type embeddings (instant, no computation)
const nounEmbeddings = getNounTypeEmbeddings()
const verbEmbeddings = getVerbTypeEmbeddings()
// Convert NounType/VerbType keys to strings for lookup
for (const [type, embedding] of nounEmbeddings.entries()) {
this.nounEmbeddings.set(type, embedding)
}
// Generate embeddings for verb types
for (const [type, description] of Object.entries(VERB_TYPE_DESCRIPTIONS)) {
const embedding = await this.embedder.embed(description)
for (const [type, embedding] of verbEmbeddings.entries()) {
this.verbEmbeddings.set(type, embedding)
}
this.initialized = true
}

14
src/importers/SmartExcelImporter.ts
View file

@ -141,18 +141,18 @@ export class SmartExcelImporter {
const opts = {
enableNeuralExtraction: true,
enableRelationshipInference: true,
// CONCEPT EXTRACTION NOW PRODUCTION-READY (v3.32.5+):
// Performance optimization: Only initializes needed types (Concept + Topic = 2 embeds)
// Previously initialized all 31 types (31 embeds) which caused apparent hangs
// CONCEPT EXTRACTION PRODUCTION-READY (v3.33.0+):
// Type embeddings are now pre-computed at build time - zero runtime cost!
// All 31 noun types + 40 verb types instantly available
//
// Performance profile:
// - Type embeddings: INSTANT (pre-computed at build time, ~100KB in-memory)
// - Model loading: ~2-5 seconds (one-time, cached after first use)
// - Type init: 2 embeds for Concept + Topic (vs 31 previously)
// - Per-row extraction: ~50-200ms depending on definition length
// - 100 rows: ~5-20 seconds total (acceptable for production)
// - 1000 rows: ~50-200 seconds (may want to disable for very large files)
// - 100 rows: ~5-20 seconds total (production ready)
// - 1000 rows: ~50-200 seconds (disable if needed via enableConceptExtraction: false)
//
// Enabled by default for production use. Disable for files >500 rows if needed.
// Enabled by default for production use.
enableConceptExtraction: true,
confidenceThreshold: 0.6,
termColumn: 'term|name|title|concept',

117
src/neural/embeddedTypeEmbeddings.ts Normal file
View file

File diff suppressed because one or more lines are too long

67
src/neural/entityExtractor.ts
View file

@ -15,6 +15,7 @@ import {
generateContentCacheKey,
computeContentHash
} from './entityExtractionCache.js'
import { getNounTypeEmbeddings } from './embeddedTypeEmbeddings.js'
export interface ExtractedEntity {
text: string
@ -42,60 +43,24 @@ export class NeuralEntityExtractor {
/**
* Initialize type embeddings for neural matching
* PERFORMANCE FIX (v3.32.5): Only initialize requested types instead of all 31 types
* This reduces initialization from 31 embed calls to ~2-5 embed calls
* PRODUCTION OPTIMIZATION (v3.33.0): Uses pre-computed embeddings from build time
* Zero runtime cost - embeddings are loaded instantly from embedded data
*/
private async initializeTypeEmbeddings(requestedTypes?: NounType[]): Promise<void> {
// Create representative embeddings for each NounType
const typeExamples: Record<NounType, string[]> = {
[NounType.Person]: ['John Smith', 'Jane Doe', 'person', 'individual', 'human'],
[NounType.Organization]: ['Microsoft Corporation', 'company', 'organization', 'business', 'enterprise'],
[NounType.Location]: ['New York City', 'location', 'place', 'address', 'geography'],
[NounType.Document]: ['document', 'file', 'report', 'paper', 'text'],
[NounType.Event]: ['conference', 'meeting', 'event', 'occurrence', 'happening'],
[NounType.Product]: ['iPhone', 'product', 'item', 'merchandise', 'goods'],
[NounType.Service]: ['consulting', 'service', 'offering', 'provision'],
[NounType.Concept]: ['idea', 'concept', 'theory', 'principle', 'notion'],
[NounType.Media]: ['image', 'video', 'audio', 'media', 'content'],
[NounType.Message]: ['email', 'message', 'communication', 'note'],
[NounType.Task]: ['task', 'todo', 'assignment', 'job', 'work'],
[NounType.Project]: ['project', 'initiative', 'program', 'endeavor'],
[NounType.Process]: ['workflow', 'process', 'procedure', 'method'],
[NounType.User]: ['user', 'account', 'profile', 'member'],
[NounType.Role]: ['manager', 'role', 'position', 'title', 'responsibility'],
[NounType.Topic]: ['subject', 'topic', 'theme', 'matter'],
[NounType.Language]: ['English', 'language', 'tongue', 'dialect'],
[NounType.Currency]: ['dollar', 'currency', 'money', 'USD', 'EUR'],
[NounType.Measurement]: ['meter', 'measurement', 'unit', 'quantity'],
[NounType.Contract]: ['agreement', 'contract', 'deal', 'treaty'],
[NounType.Regulation]: ['law', 'regulation', 'rule', 'policy'],
[NounType.Resource]: ['resource', 'asset', 'material', 'supply'],
[NounType.Dataset]: ['database', 'dataset', 'data', 'records'],
[NounType.Interface]: ['API', 'interface', 'endpoint', 'connection'],
[NounType.Thing]: ['thing', 'object', 'item', 'entity'],
[NounType.Content]: ['content', 'material', 'information'],
[NounType.Collection]: ['collection', 'group', 'set', 'list'],
[NounType.File]: ['file', 'document', 'archive'],
[NounType.State]: ['state', 'status', 'condition'],
[NounType.Hypothesis]: ['hypothesis', 'theory', 'assumption'],
[NounType.Experiment]: ['experiment', 'test', 'trial', 'study']
}
// Skip if already initialized
if (this.initialized) return
// PERFORMANCE OPTIMIZATION: Only initialize the types we need
// This is especially important for extractConcepts() which only needs Concept + Topic
const typesToInitialize = requestedTypes || Object.values(NounType)
// Load pre-computed embeddings (instant, no computation)
const allEmbeddings = getNounTypeEmbeddings()
// Generate embeddings only for requested types
for (const type of typesToInitialize) {
// Skip if already initialized
if (this.typeEmbeddings.has(type)) continue
// If specific types requested, only load those; otherwise load all
const typesToLoad = requestedTypes || Object.values(NounType)
const examples = typeExamples[type]
if (!examples) continue
const combinedText = examples.join(' ')
const embedding = await this.getEmbedding(combinedText)
this.typeEmbeddings.set(type, embedding)
for (const type of typesToLoad) {
const embedding = allEmbeddings.get(type)
if (embedding) {
this.typeEmbeddings.set(type, embedding)
}
}
// Mark as initialized if we've loaded at least some types
@ -124,8 +89,8 @@ export class NeuralEntityExtractor {
}
}
): Promise<ExtractedEntity[]> {
// PERFORMANCE FIX (v3.32.5): Only initialize requested types
// For extractConcepts(), this reduces init from 31 types → 2 types
// PRODUCTION OPTIMIZATION (v3.33.0): Load pre-computed type embeddings
// Zero runtime cost - embeddings were computed at build time
await this.initializeTypeEmbeddings(options?.types)
// Check cache if enabled

57
src/neural/naturalLanguageProcessor.ts
View file

@ -14,6 +14,7 @@ import { TripleQuery } from '../triple/TripleIntelligence.js'
import { Brainy } from '../brainy.js'
import { PatternLibrary } from './patternLibrary.js'
import { NounType, VerbType } from '../types/graphTypes.js'
import { getNounTypeEmbeddings, getVerbTypeEmbeddings } from './embeddedTypeEmbeddings.js'
export interface NaturalQueryIntent {
type: 'vector' | 'field' | 'graph' | 'combined'
@ -98,48 +99,30 @@ export class NaturalLanguageProcessor {
/**
* Initialize embeddings for all NounTypes and VerbTypes
* These are fixed types that never change - perfect for caching
* PRODUCTION OPTIMIZATION (v3.33.0): Uses pre-computed type embeddings
* Zero runtime cost - embeddings are loaded instantly from embedded data
*/
private async initializeTypeEmbeddings(): Promise<void> {
if (this.typeEmbeddingsInitialized) return
// Embed all NounTypes (30+ types)
for (const [key, value] of Object.entries(NounType)) {
if (typeof value === 'string') {
// Embed both the key (Person) and value (person)
const keyEmbedding = await this.getEmbedding(key)
const valueEmbedding = await this.getEmbedding(value)
this.nounTypeEmbeddings.set(key, keyEmbedding)
this.nounTypeEmbeddings.set(value, valueEmbedding)
// Also embed common variations
const spaceSeparated = key.replace(/([A-Z])/g, ' $1').trim().toLowerCase()
if (spaceSeparated !== value) {
const variantEmbedding = await this.getEmbedding(spaceSeparated)
this.nounTypeEmbeddings.set(spaceSeparated, variantEmbedding)
}
}
// Load pre-computed embeddings (instant, no computation)
const nounEmbeddings = getNounTypeEmbeddings()
const verbEmbeddings = getVerbTypeEmbeddings()
// Store noun type embeddings with all variations for lookup
for (const [type, embedding] of nounEmbeddings.entries()) {
this.nounTypeEmbeddings.set(type, embedding)
// Also store lowercase version for case-insensitive matching
this.nounTypeEmbeddings.set(type.toLowerCase(), embedding)
}
// Embed all VerbTypes (40+ types)
for (const [key, value] of Object.entries(VerbType)) {
if (typeof value === 'string') {
const keyEmbedding = await this.getEmbedding(key)
const valueEmbedding = await this.getEmbedding(value)
this.verbTypeEmbeddings.set(key, keyEmbedding)
this.verbTypeEmbeddings.set(value, valueEmbedding)
// Common variations for verbs
const spaceSeparated = key.replace(/([A-Z])/g, ' $1').trim().toLowerCase()
if (spaceSeparated !== value) {
const variantEmbedding = await this.getEmbedding(spaceSeparated)
this.verbTypeEmbeddings.set(spaceSeparated, variantEmbedding)
}
}
// Store verb type embeddings with all variations for lookup
for (const [type, embedding] of verbEmbeddings.entries()) {
this.verbTypeEmbeddings.set(type, embedding)
// Also store lowercase version for case-insensitive matching
this.verbTypeEmbeddings.set(type.toLowerCase(), embedding)
}
this.typeEmbeddingsInitialized = true
}