feat: add new embedding and analysis APIs for v7.1.0
New public APIs: - embedBatch(texts): Batch embed multiple texts efficiently - similarity(textA, textB): Calculate semantic similarity (0-1 score) - indexStats(): Get comprehensive index statistics with memory usage - neighbors(entityId, options): Get graph neighbors with direction/depth/filter - findDuplicates(options): Find semantic duplicates by embedding similarity - cluster(options): Cluster entities by semantic similarity with centroids All APIs: - Added to BrainyInterface for type safety - Documented in docs/API_REFERENCE.md and docs/api/README.md - Include JSDoc examples and parameter descriptions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
8e21e71980
commit
d8514ab209
4 changed files with 855 additions and 10 deletions
|
|
@ -491,6 +491,195 @@ for (const result of similar) {
|
|||
|
||||
---
|
||||
|
||||
### `async embed(data: any): Promise<Vector>` ✨ *v7.1.0*
|
||||
Generates an embedding vector from data.
|
||||
|
||||
**Parameters:**
|
||||
- `data` - Text, array, or object to embed
|
||||
|
||||
**Returns:** 384-dimensional embedding vector
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
const vector = await brain.embed('Machine learning concepts')
|
||||
console.log(vector.length) // 384
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async embedBatch(texts: string[]): Promise<number[][]>` ✨ *v7.1.0*
|
||||
Batch embed multiple texts efficiently.
|
||||
|
||||
**Parameters:**
|
||||
- `texts` - Array of strings to embed
|
||||
|
||||
**Returns:** Array of 384-dimensional vectors
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
const embeddings = await brain.embedBatch([
|
||||
'Machine learning is fascinating',
|
||||
'Deep neural networks',
|
||||
'Natural language processing'
|
||||
])
|
||||
console.log(embeddings.length) // 3
|
||||
console.log(embeddings[0].length) // 384
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async similarity(textA: string, textB: string): Promise<number>` ✨ *v7.1.0*
|
||||
Calculate semantic similarity between two texts.
|
||||
|
||||
**Parameters:**
|
||||
- `textA` - First text
|
||||
- `textB` - Second text
|
||||
|
||||
**Returns:** Similarity score between 0 (different) and 1 (identical)
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
const score = await brain.similarity(
|
||||
'The cat sat on the mat',
|
||||
'A feline was resting on the rug'
|
||||
)
|
||||
console.log(score) // ~0.85 (high semantic similarity)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async neighbors(entityId: string, options?): Promise<string[]>` ✨ *v7.1.0*
|
||||
Get graph neighbors of an entity.
|
||||
|
||||
**Parameters:**
|
||||
- `entityId` - Entity to get neighbors for
|
||||
- `options.direction` - 'outgoing', 'incoming', or 'both' (default: 'both')
|
||||
- `options.depth` - Traversal depth (default: 1)
|
||||
- `options.verbType` - Filter by relationship type
|
||||
- `options.limit` - Maximum neighbors to return
|
||||
|
||||
**Returns:** Array of neighbor entity IDs
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// Get all connected entities
|
||||
const neighbors = await brain.neighbors(entityId)
|
||||
|
||||
// Get outgoing connections only
|
||||
const outgoing = await brain.neighbors(entityId, {
|
||||
direction: 'outgoing',
|
||||
limit: 10
|
||||
})
|
||||
|
||||
// Multi-hop traversal
|
||||
const extended = await brain.neighbors(entityId, {
|
||||
depth: 2,
|
||||
direction: 'both'
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async findDuplicates(options?): Promise<DuplicateResult[]>` ✨ *v7.1.0*
|
||||
Find semantic duplicates in the database.
|
||||
|
||||
**Parameters:**
|
||||
- `options.threshold` - Minimum similarity (default: 0.85)
|
||||
- `options.type` - Filter by NounType
|
||||
- `options.limit` - Maximum duplicate groups (default: 100)
|
||||
|
||||
**Returns:** Array of duplicate groups with similarity scores
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// Find all duplicates
|
||||
const duplicates = await brain.findDuplicates()
|
||||
|
||||
for (const group of duplicates) {
|
||||
console.log('Original:', group.entity.id)
|
||||
for (const dup of group.duplicates) {
|
||||
console.log(` Duplicate: ${dup.entity.id} (${dup.similarity.toFixed(2)})`)
|
||||
}
|
||||
}
|
||||
|
||||
// Find person duplicates with higher threshold
|
||||
const personDupes = await brain.findDuplicates({
|
||||
type: NounType.PERSON,
|
||||
threshold: 0.9,
|
||||
limit: 50
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async indexStats(): Promise<IndexStats>` ✨ *v7.1.0*
|
||||
Get comprehensive index statistics.
|
||||
|
||||
**Returns:**
|
||||
- `entities` - Total entity count
|
||||
- `vectors` - Total vectors in HNSW index
|
||||
- `relationships` - Total relationships in graph
|
||||
- `metadataFields` - Indexed metadata fields
|
||||
- `memoryUsage.vectors` - Vector memory in bytes
|
||||
- `memoryUsage.graph` - Graph memory in bytes
|
||||
- `memoryUsage.metadata` - Metadata index memory in bytes
|
||||
- `memoryUsage.total` - Total memory usage
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
const stats = await brain.indexStats()
|
||||
console.log(`Entities: ${stats.entities}`)
|
||||
console.log(`Vectors: ${stats.vectors}`)
|
||||
console.log(`Relationships: ${stats.relationships}`)
|
||||
console.log(`Memory: ${(stats.memoryUsage.total / 1024 / 1024).toFixed(1)}MB`)
|
||||
console.log(`Fields: ${stats.metadataFields.join(', ')}`)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async cluster(options?): Promise<ClusterResult[]>` ✨ *v7.1.0*
|
||||
Cluster entities by semantic similarity.
|
||||
|
||||
Groups entities into clusters based on their embedding similarity using
|
||||
a greedy algorithm with HNSW-based neighbor lookup.
|
||||
|
||||
**Parameters:**
|
||||
- `options.threshold` - Similarity threshold (default: 0.8)
|
||||
- `options.type` - Filter by NounType
|
||||
- `options.minClusterSize` - Minimum entities per cluster (default: 2)
|
||||
- `options.limit` - Maximum clusters to return (default: 100)
|
||||
- `options.includeCentroid` - Calculate cluster centroids (default: false)
|
||||
|
||||
**Returns:** Array of clusters with entities
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// Find all clusters
|
||||
const clusters = await brain.cluster()
|
||||
|
||||
for (const cluster of clusters) {
|
||||
console.log(`${cluster.clusterId}: ${cluster.entities.length} entities`)
|
||||
}
|
||||
|
||||
// Find document clusters with centroids
|
||||
const docClusters = await brain.cluster({
|
||||
type: NounType.Document,
|
||||
threshold: 0.85,
|
||||
minClusterSize: 3,
|
||||
includeCentroid: true
|
||||
})
|
||||
|
||||
// Use centroids for cluster comparison
|
||||
for (const cluster of docClusters) {
|
||||
console.log(`${cluster.clusterId}: ${cluster.entities.length} entities`)
|
||||
if (cluster.centroid) {
|
||||
console.log(` Centroid dimensions: ${cluster.centroid.length}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `async insights(): Promise<InsightsResult>`
|
||||
Gets statistics and insights about the data.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
# 🧠 Brainy v6.5.0 API Reference
|
||||
# 🧠 Brainy v7.1.0 API Reference
|
||||
|
||||
> **Complete API documentation for Brainy v6.5.0**
|
||||
> Zero Configuration • Triple Intelligence • Git-Style Branching • Entity Versioning
|
||||
> **Complete API documentation for Brainy v7.1.0**
|
||||
> Zero Configuration • Triple Intelligence • Git-Style Branching • Entity Versioning • Candle WASM Embeddings
|
||||
|
||||
**Updated:** 2025-12-11 for v6.5.0
|
||||
**Updated:** 2026-01-06 for v7.1.0
|
||||
**All APIs verified against actual code**
|
||||
|
||||
---
|
||||
|
|
@ -76,6 +76,7 @@ Time-travel and history tracking for individual entities - Git-like version cont
|
|||
- [Configuration](#configuration)
|
||||
- [Storage Adapters](#storage-adapters)
|
||||
- [Utility Methods](#utility-methods)
|
||||
- [Embedding & Analysis APIs (v7.1.0)](#embedding--analysis-apis-v710)
|
||||
- [Type System Reference](#type-system-reference)
|
||||
|
||||
---
|
||||
|
|
@ -1560,17 +1561,169 @@ const count = await brain.getVerbCount()
|
|||
|
||||
---
|
||||
|
||||
### `embed(data)` → `Promise<number[]>`
|
||||
### `embed(data)` → `Promise<number[]>` ✨ *Enhanced v7.1.0*
|
||||
|
||||
Generate embedding vector from text.
|
||||
Generate embedding vector from text or data.
|
||||
|
||||
```typescript
|
||||
const vector = await brain.embed('Hello world')
|
||||
// [0.1, -0.3, 0.8, ...]
|
||||
// 384-dimensional vector
|
||||
console.log(vector.length) // 384
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `embedBatch(texts)` → `Promise<number[][]>` ✨ *New v7.1.0*
|
||||
|
||||
Batch embed multiple texts efficiently.
|
||||
|
||||
```typescript
|
||||
const embeddings = await brain.embedBatch([
|
||||
'Machine learning is fascinating',
|
||||
'Deep neural networks',
|
||||
'Natural language processing'
|
||||
])
|
||||
console.log(embeddings.length) // 3
|
||||
console.log(embeddings[0].length) // 384
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `similarity(textA, textB)` → `Promise<number>` ✨ *New v7.1.0*
|
||||
|
||||
Calculate semantic similarity between two texts.
|
||||
|
||||
```typescript
|
||||
const score = await brain.similarity(
|
||||
'The cat sat on the mat',
|
||||
'A feline was resting on the rug'
|
||||
)
|
||||
console.log(score) // ~0.85 (high semantic similarity)
|
||||
```
|
||||
|
||||
**Returns:** Score from 0 (different) to 1 (identical meaning)
|
||||
|
||||
---
|
||||
|
||||
### `neighbors(entityId, options?)` → `Promise<string[]>` ✨ *New v7.1.0*
|
||||
|
||||
Get graph neighbors of an entity.
|
||||
|
||||
```typescript
|
||||
// Get all connected entities
|
||||
const neighbors = await brain.neighbors(entityId)
|
||||
|
||||
// Get outgoing connections only
|
||||
const outgoing = await brain.neighbors(entityId, {
|
||||
direction: 'outgoing',
|
||||
limit: 10
|
||||
})
|
||||
|
||||
// Multi-hop traversal
|
||||
const extended = await brain.neighbors(entityId, {
|
||||
depth: 2,
|
||||
direction: 'both'
|
||||
})
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `direction`: `'outgoing' | 'incoming' | 'both'` (default: 'both')
|
||||
- `depth`: `number` - Traversal depth (default: 1)
|
||||
- `verbType`: `VerbType` - Filter by relationship type
|
||||
- `limit`: `number` - Maximum neighbors to return
|
||||
|
||||
---
|
||||
|
||||
### `findDuplicates(options?)` → `Promise<DuplicateResult[]>` ✨ *New v7.1.0*
|
||||
|
||||
Find semantic duplicates in the database.
|
||||
|
||||
```typescript
|
||||
// Find all duplicates
|
||||
const duplicates = await brain.findDuplicates()
|
||||
|
||||
for (const group of duplicates) {
|
||||
console.log('Original:', group.entity.id)
|
||||
for (const dup of group.duplicates) {
|
||||
console.log(` Duplicate: ${dup.entity.id} (${dup.similarity.toFixed(2)})`)
|
||||
}
|
||||
}
|
||||
|
||||
// Find person duplicates with higher threshold
|
||||
const personDupes = await brain.findDuplicates({
|
||||
type: NounType.PERSON,
|
||||
threshold: 0.9,
|
||||
limit: 50
|
||||
})
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `threshold`: `number` - Minimum similarity (default: 0.85)
|
||||
- `type`: `NounType` - Filter by entity type
|
||||
- `limit`: `number` - Maximum duplicate groups (default: 100)
|
||||
|
||||
---
|
||||
|
||||
### `indexStats()` → `Promise<IndexStats>` ✨ *New v7.1.0*
|
||||
|
||||
Get comprehensive index statistics.
|
||||
|
||||
```typescript
|
||||
const stats = await brain.indexStats()
|
||||
console.log(`Entities: ${stats.entities}`)
|
||||
console.log(`Vectors: ${stats.vectors}`)
|
||||
console.log(`Relationships: ${stats.relationships}`)
|
||||
console.log(`Memory: ${(stats.memoryUsage.total / 1024 / 1024).toFixed(1)}MB`)
|
||||
console.log(`Fields: ${stats.metadataFields.join(', ')}`)
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
- `entities` - Total entity count
|
||||
- `vectors` - Total vectors in HNSW index
|
||||
- `relationships` - Total relationships in graph
|
||||
- `metadataFields` - Indexed metadata fields
|
||||
- `memoryUsage.vectors` - Vector memory (bytes)
|
||||
- `memoryUsage.graph` - Graph memory (bytes)
|
||||
- `memoryUsage.metadata` - Metadata index memory (bytes)
|
||||
- `memoryUsage.total` - Total memory usage
|
||||
|
||||
---
|
||||
|
||||
### `cluster(options?)` → `Promise<ClusterResult[]>` ✨ *New v7.1.0*
|
||||
|
||||
Cluster entities by semantic similarity.
|
||||
|
||||
```typescript
|
||||
// Find all clusters
|
||||
const clusters = await brain.cluster()
|
||||
|
||||
for (const cluster of clusters) {
|
||||
console.log(`${cluster.clusterId}: ${cluster.entities.length} entities`)
|
||||
}
|
||||
|
||||
// Find document clusters with centroids
|
||||
const docClusters = await brain.cluster({
|
||||
type: NounType.Document,
|
||||
threshold: 0.85,
|
||||
minClusterSize: 3,
|
||||
includeCentroid: true
|
||||
})
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `threshold`: `number` - Similarity threshold (default: 0.8)
|
||||
- `type`: `NounType` - Filter by entity type
|
||||
- `minClusterSize`: `number` - Minimum cluster size (default: 2)
|
||||
- `limit`: `number` - Maximum clusters to return (default: 100)
|
||||
- `includeCentroid`: `boolean` - Calculate cluster centroids (default: false)
|
||||
|
||||
**Returns:**
|
||||
- `clusterId` - Unique cluster identifier
|
||||
- `entities` - Array of entities in the cluster
|
||||
- `centroid` - Average embedding vector (if includeCentroid is true)
|
||||
|
||||
---
|
||||
|
||||
### `getStats()` → `Statistics`
|
||||
|
||||
Get comprehensive statistics.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue