**feat(tests, docs): add test coverage for database operations and vector dimension standardization**

- **Tests**:
  - Introduced `database-operations.test.ts` to validate core database functionalities, including initialization, CRUD operations, statistics retrieval, and search capabilities.
  - Added `dimension-standardization.test.ts` to ensure vector dimension consistency (fixed at 512) throughout operations like embedding, configuration, and validation.
  - Enhanced test cases to include scenarios for adding, retrieving, and handling errors for incorrect vector dimensions.

- **Documentation**:
  - Created `VECTOR_DIMENSION_STANDARDIZATION.md` to detail the transition to standardizing vectors to 512 dimensions, rationale for the change, potential impacts, and migration steps.
  - Includes best practices for handling vectors and utilizing the built-in embedding functions.

**Purpose**: Improve system robustness with comprehensive test coverage focusing on critical database and vector operations while providing clear documentation for developers to adapt to the standardized vector dimensions.

tests/database-operations.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { BrainyData } from '../dist/brainyData.js'
+
+describe('Database Operations', () => {
+  let db: BrainyData
+  
+  beforeEach(async () => {
+    db = new BrainyData()
+    await db.init()
+  })
+  
+  it('should initialize and return database status', async () => {
+    const status = await db.status()
+    expect(status).toBeDefined()
+    // The structure of status might vary, just check it exists
+  })
+  
+  it('should return statistics', async () => {
+    const stats = await db.getStatistics()
+    expect(stats).toBeDefined()
+    // The structure of stats might vary, just check it exists
+  })
+  
+  it('should retrieve all nouns', async () => {
+    const nouns = await db.getAllNouns()
+    expect(Array.isArray(nouns)).toBe(true)
+  })
+  
+  it('should retrieve all verbs', async () => {
+    const verbs = await db.getAllVerbs()
+    expect(Array.isArray(verbs)).toBe(true)
+  })
+  
+  it('should perform a search operation', async () => {
+    const searchResults = await db.searchText('test', 10)
+    expect(Array.isArray(searchResults)).toBe(true)
+  })
+  
+  it('should add and retrieve an item', async () => {
+    // Add a test item
+    const testText = 'This is a test item for searching'
+    const metadata = { noun: 'Thing', category: 'test' }
+    const id = await db.add(testText, metadata)
+    
+    // Verify the item was added
+    expect(id).toBeDefined()
+    
+    // Retrieve the item
+    const noun = await db.get(id)
+    expect(noun).toBeDefined()
+    expect(noun.id).toBe(id)
+    
+    // Check that the metadata contains our properties
+    // (The system might add additional properties)
+    expect(noun.metadata.category).toBe('test')
+    
+    // Search for the item
+    const searchResults = await db.searchText('test', 10)
+    expect(searchResults.length).toBeGreaterThan(0)
+    
+    // Clean up
+    await db.delete(id)
+  })
+})

tests/dimension-standardization.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { BrainyData } from '../dist/brainyData.js'
+
+describe('Vector Dimension Standardization', () => {
+  it('should initialize BrainyData with 512 dimensions', async () => {
+    // Initialize BrainyData
+    const db = new BrainyData()
+    await db.init()
+    
+    // Check the dimensions property
+    expect(db.dimensions).toBe(512)
+  })
+
+  it('should reject vectors with incorrect dimensions', async () => {
+    const db = new BrainyData()
+    await db.init()
+    
+    // Test with a simple vector (this should throw an error because it's not 512 dimensions)
+    const smallVector = [0.1, 0.2, 0.3]
+    
+    // Expect the add operation to throw an error
+    await expect(db.add(smallVector, { test: 'small-vector' }))
+      .rejects.toThrow()
+  })
+
+  it('should successfully embed text to 512 dimensions', async () => {
+    const db = new BrainyData()
+    await db.init()
+    
+    // Test with text that will be embedded to 512 dimensions
+    const id = await db.add('This is a test text that will be embedded to 512 dimensions', { test: 'text-embedding' })
+    
+    // Retrieve the vector and check its dimensions
+    const noun = await db.get(id)
+    expect(noun.vector.length).toBe(512)
+  })
+
+  it('should directly embed text to 512 dimensions', async () => {
+    const db = new BrainyData()
+    await db.init()
+    
+    // Test direct embedding
+    const vector = await db.embed('Another test text')
+    expect(vector.length).toBe(512)
+  })
+
+  it('should use the configured dimensions', async () => {
+    // Create a BrainyData instance with a specific dimension
+    const customDimension = 300
+    const db = new BrainyData({
+      dimensions: customDimension
+    })
+    await db.init()
+    
+    // The API appears to respect the configured dimensions
+    expect(db.dimensions).toBe(customDimension)
+  })
+})