brainy/docs/api-returns.md

Brainy API Return Values

Core Operations

brain.add() - Adding Entities

Returns: Promise<string> - The ID of the created entity

// ✅ Correct usage - add() returns the ID string directly
const id = await brain.add({
  type: 'document',
  data: 'My document content'
})

console.log('Created entity with ID:', id)

// Use the ID to create relationships
await brain.relate({
  from: id,
  to: anotherId,
  type: 'references'
})

// ❌ Incorrect - trying to access .id property
const result = await brain.add({
  type: 'document',
  data: 'My content'
})

console.log(result.id) // ❌ undefined - result IS the ID, not an object!

Getting the Full Entity

If you need the full entity object after creation, use brain.get():

// Add entity and get its ID
const id = await brain.add({
  type: 'document',
  data: 'My content',
  metadata: { label: 'Important Doc' }
})

// Get the full entity
const entity = await brain.get(id)
console.log(entity.id)          // The ID
console.log(entity.type)        // 'document'
console.log(entity.data)        // 'My content'
console.log(entity.metadata)    // { label: 'Important Doc', ... }
console.log(entity.vector)      // The embedding vector
console.log(entity.createdAt)   // Timestamp

brain.find() - Finding Entities

Returns: Promise<Entity[]> - Array of full entity objects

const entities = await brain.find({
  query: 'machine learning',
  limit: 10
})

// Each entity has full information
for (const entity of entities) {
  console.log(entity.id)
  console.log(entity.type)
  console.log(entity.data)
  console.log(entity.metadata)
}

brain.relate() - Creating Relationships

Returns: Promise<string> - The ID of the created relationship

const relationId = await brain.relate({
  from: entityId1,
  to: entityId2,
  type: 'references'
})

console.log('Created relationship with ID:', relationId)

Data Field Behavior

String Data - Used for Embeddings

When data is a string, it's used to generate embeddings for semantic search:

await brain.add({
  type: 'document',
  data: 'This text will be converted to an embedding vector',
  metadata: {
    title: 'My Document',
    year: 2024
  }
})

Object Data - Structured Information

When data is an object, it's treated as structured data:

await brain.add({
  type: 'product',
  data: {
    name: 'Widget',
    price: 29.99,
    category: 'Tools'
  },
  vector: precomputedVector  // Must provide vector when using object data
})

Important: If you provide object data without a vector, you must include a string somewhere for embedding generation, or the operation will fail.

Metadata vs Data

• data: Primary content - used for embeddings (if string) or stored as structured data (if object)
• metadata: Auxiliary information - always stored as structured data, used for filtering

Best practice for labels:

await brain.add({
  type: 'document',
  data: 'The full text content of the document...',  // For semantic search
  metadata: {
    label: 'Quick Reference Label',  // For display
    author: 'John Doe',
    category: 'Technical'
  }
})

Summary

Method	Returns	Contains
brain.add()	string	The ID of the created entity
brain.get()	Entity | null	Full entity object with all fields
brain.find()	Entity[]	Array of full entity objects
brain.relate()	string	The ID of the created relationship
brain.getRelations()	Relation[]	Array of relationship objects