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

refactor: remove augmentation system and semantic type matching

Browse source 
Remove the entire augmentation pipeline infrastructure (52 files,
~15,000 lines) and the semantic type matching system. These were
unused middleware layers adding complexity without value.

What was removed:
- src/augmentations/ directory (all augmentation implementations)
- src/augmentationManager.ts (pipeline orchestrator)
- src/types/augmentations.ts, src/types/pipelineTypes.ts
- src/shared/default-augmentations.ts
- Semantic type suggestion (BrainyTypes.suggestNoun/suggestVerb)
- src/utils/typeMatching/ (embedding-based type matcher)

What was preserved by relocating:
- Import handlers (CSV, PDF, Excel) -> src/importers/handlers/
- NeuralImportAugmentation -> src/cortex/neuralImportAugmentation.ts
- Type matching utilities -> heuristic inference in consumers

What was simplified:
- brainy.ts: operations call storage directly (no execute() wrapper)
- IntegrationBase: standalone class (no BaseAugmentation parent)
- BrainyTypes: validation-only (nouns, verbs, isValid*, get*)
- Pipeline: direct execution (no augmentation interception)
- index.ts: removed TypeSuggestion, suggestType exports
- package.json: removed stale types/augmentations export

Build passes, 1176 tests pass, 0 failures.
This commit is contained in:
David Snelling 2026-02-01 10:48:56 -08:00
parent ac7a1f772c
commit d1db3510be
97 changed files with 349 additions and 19705 deletions
Download patch file Download diff file Expand all files Collapse all files

216
src/utils/brainyTypes.ts
View file

@ -1,64 +1,34 @@
/**
* BrainyTypes - Complete type management for Brainy
*
* Provides type lists, validation, and intelligent suggestions
* for nouns and verbs using semantic embeddings.
*
* BrainyTypes - Type validation and lookup for Brainy
*
* Provides type lists and validation for the 42 noun types and 127 verb types.
* Source of truth: graphTypes.ts
*
* @example
* ```typescript
* import { BrainyTypes } from '@soulcraft/brainy'
*
*
* // Get all available types
* const nounTypes = BrainyTypes.nouns // ['Person', 'Organization', ...]
* const verbTypes = BrainyTypes.verbs // ['Contains', 'Creates', ...]
*
*
* // Validate types
* BrainyTypes.isValidNoun('Person') // true
* BrainyTypes.isValidVerb('Unknown') // false
*
* // Get intelligent suggestions
* const personData = {
* name: 'John Doe',
* email: 'john@example.com'
* }
* const suggestion = await BrainyTypes.suggestNoun(personData)
* console.log(suggestion.type) // 'Person'
* console.log(suggestion.confidence) // 0.92
* ```
*/
import { NounType, VerbType } from '../types/graphTypes.js'
import { BrainyTypes as InternalBrainyTypes, TypeMatchResult } from '../augmentations/typeMatching/brainyTypes.js'
/**
* Type suggestion result
*/
export interface TypeSuggestion {
/** The suggested type */
type: NounType | VerbType
/** Confidence score between 0 and 1 */
confidence: number
/** Human-readable explanation */
reason?: string
/** Alternative suggestions */
alternatives?: Array<{
type: NounType | VerbType
confidence: number
}>
}
/**
* BrainyTypes - Complete type management for Brainy
*
* Static class providing type lists, validation, and intelligent suggestions.
* BrainyTypes - Type validation and lookup for Brainy
*
* Static class providing type lists and validation.
* No instantiation needed - all methods are static.
*/
export class BrainyTypes {
private static instance: InternalBrainyTypes | null = null
private static initialized = false
/**
* All available noun types
* All available noun types (42)
* @example
* ```typescript
* BrainyTypes.nouns.forEach(type => console.log(type))
@ -68,7 +38,7 @@ export class BrainyTypes {
static readonly nouns: readonly NounType[] = Object.freeze(Object.values(NounType))
/**
* All available verb types
* All available verb types (127)
* @example
* ```typescript
* BrainyTypes.verbs.forEach(type => console.log(type))
@ -77,24 +47,12 @@ export class BrainyTypes {
*/
static readonly verbs: readonly VerbType[] = Object.freeze(Object.values(VerbType))
/**
* Get or create the internal matcher instance
*/
private static async getInternalMatcher(): Promise<InternalBrainyTypes> {
if (!this.instance) {
this.instance = new InternalBrainyTypes()
await this.instance.init()
this.initialized = true
}
return this.instance
}
/**
* Check if a string is a valid noun type
*
*
* @param type The type string to check
* @returns True if valid noun type
*
*
* @example
* ```typescript
* BrainyTypes.isValidNoun('Person') // true
@ -108,10 +66,10 @@ export class BrainyTypes {
/**
* Check if a string is a valid verb type
*
*
* @param type The type string to check
* @returns True if valid verb type
*
*
* @example
* ```typescript
* BrainyTypes.isValidVerb('Contains') // true
@ -123,92 +81,13 @@ export class BrainyTypes {
return (this.verbs as readonly string[]).includes(type)
}
/**
* Suggest the most appropriate noun type for an object
*
* @param data The object or data to analyze
* @returns Promise resolving to type suggestion with confidence score
*
* @example
* ```typescript
* const data = {
* title: 'Quarterly Report',
* author: 'Jane Smith',
* pages: 42
* }
* const suggestion = await BrainyTypes.suggestNoun(data)
* console.log(suggestion.type) // 'Document'
* console.log(suggestion.confidence) // 0.88
*
* // Check alternatives if confidence is low
* if (suggestion.confidence < 0.8) {
* console.log('Also consider:', suggestion.alternatives)
* }
* ```
*/
static async suggestNoun(data: any): Promise<TypeSuggestion> {
const matcher = await this.getInternalMatcher()
const result = await matcher.matchNounType(data)
return {
type: result.type as NounType,
confidence: result.confidence,
reason: result.reasoning,
alternatives: result.alternatives?.map(alt => ({
type: alt.type as NounType,
confidence: alt.confidence
}))
}
}
/**
* Suggest the most appropriate verb type for a relationship
*
* @param source The source entity
* @param target The target entity
* @param hint Optional hint about the relationship
* @returns Promise resolving to type suggestion with confidence score
*
* @example
* ```typescript
* const source = { type: 'Person', name: 'Alice' }
* const target = { type: 'Document', title: 'Research Paper' }
*
* const suggestion = await BrainyTypes.suggestVerb(source, target, 'authored')
* console.log(suggestion.type) // 'CreatedBy'
* console.log(suggestion.confidence) // 0.91
*
* // Without hint
* const suggestion2 = await BrainyTypes.suggestVerb(source, target)
* console.log(suggestion2.type) // 'RelatedTo' (more generic)
* ```
*/
static async suggestVerb(
source: any,
target: any,
hint?: string
): Promise<TypeSuggestion> {
const matcher = await this.getInternalMatcher()
const result = await matcher.matchVerbType(source, target, hint)
return {
type: result.type as VerbType,
confidence: result.confidence,
reason: result.reasoning,
alternatives: result.alternatives?.map(alt => ({
type: alt.type as VerbType,
confidence: alt.confidence
}))
}
}
/**
* Get a noun type by name (with validation)
*
*
* @param name The noun type name
* @returns The NounType enum value
* @throws Error if invalid noun type
*
*
* @example
* ```typescript
* const type = BrainyTypes.getNoun('Person') // NounType.Person
@ -224,11 +103,11 @@ export class BrainyTypes {
/**
* Get a verb type by name (with validation)
*
*
* @param name The verb type name
* @returns The VerbType enum value
* @throws Error if invalid verb type
*
*
* @example
* ```typescript
* const type = BrainyTypes.getVerb('Contains') // VerbType.Contains
@ -242,26 +121,6 @@ export class BrainyTypes {
return name as VerbType
}
/**
* Clear the internal cache
* Useful when processing many different types of data
*/
static clearCache(): void {
this.instance?.clearCache()
}
/**
* Dispose of resources
* Call when completely done using BrainyTypes
*/
static async dispose(): Promise<void> {
if (this.instance) {
await this.instance.dispose()
this.instance = null
this.initialized = false
}
}
/**
* Get noun types as a plain object (for iteration)
* @returns Object with noun type names as keys
@ -289,38 +148,3 @@ export class BrainyTypes {
// Re-export the enums for convenience
export { NounType, VerbType }
/**
* Helper function to validate and suggest types in one call
*
* @example
* ```typescript
* import { suggestType } from '@soulcraft/brainy'
*
* // For nouns
* const nounSuggestion = await suggestType('noun', data)
*
* // For verbs
* const verbSuggestion = await suggestType('verb', source, target)
* ```
*/
export async function suggestType(
kind: 'noun',
data: any
): Promise<TypeSuggestion>
export async function suggestType(
kind: 'verb',
source: any,
target: any,
hint?: string
): Promise<TypeSuggestion>
export async function suggestType(
kind: 'noun' | 'verb',
...args: any[]
): Promise<TypeSuggestion> {
if (kind === 'noun') {
return BrainyTypes.suggestNoun(args[0])
} else {
return BrainyTypes.suggestVerb(args[0], args[1], args[2])
}
}