@soulcraft/brainy 4.1.2 → 4.1.4

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [4.1.4](https://github.com/soulcraftlabs/brainy/compare/v4.1.3...v4.1.4) (2025-10-21)
+
+- feat: add import API validation and v4.x migration guide (a1a0576)
+
+
+### [4.1.3](https://github.com/soulcraftlabs/brainy/compare/v4.1.2...v4.1.3) (2025-10-21)
+
+- perf: make getRelations() pagination consistent and efficient (54d819c)
+- fix: resolve getRelations() empty array bug and add string ID shorthand (8d217f3)
+
+
+### [4.1.3](https://github.com/soulcraftlabs/brainy/compare/v4.1.2...v4.1.3) (2025-10-21)
+
+
+### 🐛 Bug Fixes
+
+* **api**: fix getRelations() returning empty array when called without parameters
+  - Fixed critical bug where `brain.getRelations()` returned `[]` instead of all relationships
+  - Added support for retrieving all relationships with pagination (default limit: 100)
+  - Added string ID shorthand syntax: `brain.getRelations(entityId)` as alias for `brain.getRelations({ from: entityId })`
+  - **Performance**: Made pagination consistent - now ALL query patterns paginate at storage layer
+  - **Efficiency**: `getRelations({ from: id, limit: 10 })` now fetches only 10 instead of fetching ALL then slicing
+  - Fixed storage.getVerbs() offset handling - now properly converts offset to cursor for adapters
+  - Production safety: Warns when fetching >10k relationships without filters
+  - Fixed broken method calls in improvedNeuralAPI.ts (replaced non-existent `getVerbsForNoun` with `getRelations`)
+  - Fixed property access bugs: `verb.target` → `verb.to`, `verb.verb` → `verb.type`
+  - Added comprehensive integration tests (14 tests covering all query patterns)
+  - Updated JSDoc documentation with usage examples
+  - **Impact**: Resolves Workshop team bug where 524 imported relationships were inaccessible
+  - **Breaking**: None - fully backward compatible
+
 ### [4.1.2](https://github.com/soulcraftlabs/brainy/compare/v4.1.1...v4.1.2) (2025-10-21)
 
 
@@ -197,22 +228,110 @@ $ brainy import ./research-papers --extract-concepts --progress
 
 ### ⚠️ Breaking Changes
 
-**NONE** - v4.0.0 is 100% backward compatible!
+#### 💥 Import API Redesign
+
+The import API has been redesigned for clarity and better feature control. **Old v3.x option names are no longer recognized** and will throw errors.
+
+**What Changed:**
+
+| v3.x Option | v4.x Option | Action Required |
+|-------------|-------------|-----------------|
+| `extractRelationships` | `enableRelationshipInference` | **Rename option** |
+| `autoDetect` | *(removed)* | **Delete option** (always enabled) |
+| `createFileStructure` | `vfsPath` | **Replace** with VFS path |
+| `excelSheets` | *(removed)* | **Delete option** (all sheets processed) |
+| `pdfExtractTables` | *(removed)* | **Delete option** (always enabled) |
+| - | `enableNeuralExtraction` | **Add option** (new in v4.x) |
+| - | `enableConceptExtraction` | **Add option** (new in v4.x) |
+| - | `preserveSource` | **Add option** (new in v4.x) |
+
+**Why These Changes?**
+
+1. **Clearer option names**: `enableRelationshipInference` explicitly indicates AI-powered relationship inference
+2. **Separation of concerns**: Neural extraction, relationship inference, and VFS are now separate, explicit options
+3. **Better defaults**: Auto-detection and AI features are enabled by default
+4. **Reduced confusion**: Removed redundant options like `autoDetect` and format-specific options
+
+**Migration Examples:**
+
+<details>
+<summary>Example 1: Basic Excel Import</summary>
+
+```typescript
+// v3.x (OLD - Will throw error)
+await brain.import('./glossary.xlsx', {
+  extractRelationships: true,
+  createFileStructure: true
+})
+
+// v4.x (NEW - Use this)
+await brain.import('./glossary.xlsx', {
+  enableRelationshipInference: true,
+  vfsPath: '/imports/glossary'
+})
+```
+</details>
+
+<details>
+<summary>Example 2: Full-Featured Import</summary>
+
+```typescript
+// v3.x (OLD - Will throw error)
+await brain.import('./data.xlsx', {
+  extractRelationships: true,
+  autoDetect: true,
+  createFileStructure: true
+})
+
+// v4.x (NEW - Use this)
+await brain.import('./data.xlsx', {
+  enableNeuralExtraction: true,      // Extract entity names
+  enableRelationshipInference: true, // Infer semantic relationships
+  enableConceptExtraction: true,     // Extract entity types
+  vfsPath: '/imports/data',          // VFS directory
+  preserveSource: true               // Save original file
+})
+```
+</details>
+
+**Error Messages:**
 
-All v4.0.0 features are:
+If you use old v3.x options, you'll get a clear error message:
+
+```
+❌ Invalid import options detected (Brainy v4.x breaking changes)
+
+The following v3.x options are no longer supported:
+
+  ❌ extractRelationships
+     → Use: enableRelationshipInference
+     → Why: Option renamed for clarity in v4.x
+
+📖 Migration Guide: https://brainy.dev/docs/guides/migrating-to-v4
+```
+
+**Other v4.0.0 Features (Non-Breaking):**
+
+All other v4.0.0 features are:
 - ✅ Opt-in (lifecycle, compression, batch operations)
 - ✅ Additive (new CLI commands, new methods)
 - ✅ Non-breaking (existing code continues to work)
 
 ### 📝 Migration
 
-**No migration required!** All v4.0.0 features are optional enhancements.
+**Import API migration required** if you use `brain.import()` with the old v3.x option names.
 
-To use new features:
+#### Required Changes:
 1. Update to v4.0.0: `npm install @soulcraft/brainy@4.0.0`
-2. Enable lifecycle policies: `brainy storage lifecycle set`
-3. Use batch operations: `brainy storage batch-delete entities.txt`
-4. See `docs/MIGRATION-V3-TO-V4.md` for full feature documentation
+2. Update import calls to use new option names (see table above)
+3. Test your imports - you'll get clear error messages if you use old options
+
+#### Optional Enhancements:
+- Enable lifecycle policies: `brainy storage lifecycle set`
+- Use batch operations: `brainy storage batch-delete entities.txt`
+- See full migration guide: `docs/guides/migrating-to-v4.md`
+
+**Complete Migration Guide:** [docs/guides/migrating-to-v4.md](./docs/guides/migrating-to-v4.md)
 
 ### 🎓 What This Means
 

package/dist/brainy.d.ts

@@ -314,9 +314,38 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      */
     unrelate(id: string): Promise<void>;
     /**
-     * Get relationships
+     * Get relationships between entities
+     *
+     * Supports multiple query patterns:
+     * - No parameters: Returns all relationships (paginated, default limit: 100)
+     * - String ID: Returns relationships from that entity (shorthand for { from: id })
+     * - Parameters object: Fine-grained filtering and pagination
+     *
+     * @param paramsOrId - Optional string ID or parameters object
+     * @returns Promise resolving to array of relationships
+     *
+     * @example
+     * ```typescript
+     * // Get all relationships (first 100)
+     * const all = await brain.getRelations()
+     *
+     * // Get relationships from specific entity (shorthand syntax)
+     * const fromEntity = await brain.getRelations(entityId)
+     *
+     * // Get relationships with filters
+     * const filtered = await brain.getRelations({
+     *   type: VerbType.FriendOf,
+     *   limit: 50
+     * })
+     *
+     * // Pagination
+     * const page2 = await brain.getRelations({ offset: 100, limit: 100 })
+     * ```
+     *
+     * @since v4.1.3 - Fixed bug where calling without parameters returned empty array
+     * @since v4.1.3 - Added string ID shorthand syntax: getRelations(id)
      */
-    getRelations(params?: GetRelationsParams): Promise<Relation<T>[]>;
+    getRelations(paramsOrId?: string | GetRelationsParams): Promise<Relation<T>[]>;
     /**
      * Unified find method - supports natural language and structured queries
      * Implements Triple Intelligence with parallel search optimization
@@ -657,33 +686,91 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
         limit?: number;
     }): Promise<string[]>;
     /**
-     * Import files with auto-detection and dual storage (VFS + Knowledge Graph)
+     * Import files with intelligent extraction and dual storage (VFS + Knowledge Graph)
      *
      * Unified import system that:
      * - Auto-detects format (Excel, PDF, CSV, JSON, Markdown)
-     * - Extracts entities and relationships
+     * - Extracts entities with AI-powered name/type detection
+     * - Infers semantic relationships from context
      * - Stores in both VFS (organized files) and Knowledge Graph (connected entities)
      * - Links VFS files to graph entities
      *
-     * @example
-     * // Import from file path
-     * const result = await brain.import('/path/to/file.xlsx')
+     * @since 4.0.0
      *
-     * @example
-     * // Import from buffer
+     * @example Quick Start (All AI features enabled by default)
+     * ```typescript
+     * const result = await brain.import('./glossary.xlsx')
+     * // Auto-detects format, extracts entities, infers relationships
+     * ```
+     *
+     * @example Full-Featured Import (v4.x)
+     * ```typescript
+     * const result = await brain.import('./data.xlsx', {
+     *   // AI features
+     *   enableNeuralExtraction: true,      // Extract entity names/metadata
+     *   enableRelationshipInference: true, // Detect semantic relationships
+     *   enableConceptExtraction: true,     // Extract types/concepts
+     *
+     *   // VFS features
+     *   vfsPath: '/imports/my-data',       // Store in VFS directory
+     *   groupBy: 'type',                   // Organize by entity type
+     *   preserveSource: true,              // Keep original file
+     *
+     *   // Progress tracking
+     *   onProgress: (p) => console.log(p.message)
+     * })
+     * ```
+     *
+     * @example Performance Tuning (Large Files)
+     * ```typescript
+     * const result = await brain.import('./huge-file.csv', {
+     *   enableDeduplication: false,  // Skip dedup for speed
+     *   confidenceThreshold: 0.8,    // Higher threshold = fewer entities
+     *   onProgress: (p) => console.log(`${p.processed}/${p.total}`)
+     * })
+     * ```
+     *
+     * @example Import from Buffer or Object
+     * ```typescript
+     * // From buffer
      * const result = await brain.import(buffer, { format: 'pdf' })
      *
-     * @example
-     * // Import JSON object
+     * // From object
      * const result = await brain.import({ entities: [...] })
+     * ```
      *
-     * @example
-     * // Custom VFS path and grouping
-     * const result = await brain.import(buffer, {
-     *   vfsPath: '/my-imports/data',
-     *   groupBy: 'type',
-     *   onProgress: (progress) => console.log(progress.message)
-     * })
+     * @throws {Error} If invalid options are provided (v4.x breaking changes)
+     *
+     * @see {@link https://brainy.dev/docs/api/import API Documentation}
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     *
+     * @remarks
+     * **⚠️ Breaking Changes from v3.x:**
+     *
+     * The import API was redesigned in v4.0.0 for clarity and better feature control.
+     * Old v3.x option names are **no longer recognized** and will throw errors.
+     *
+     * **Option Changes:**
+     * - ❌ `extractRelationships` → ✅ `enableRelationshipInference`
+     * - ❌ `createFileStructure` → ✅ `vfsPath: '/your/path'`
+     * - ❌ `autoDetect` → ✅ *(removed - always enabled)*
+     * - ❌ `excelSheets` → ✅ *(removed - all sheets processed)*
+     * - ❌ `pdfExtractTables` → ✅ *(removed - always enabled)*
+     *
+     * **New Options:**
+     * - ✅ `enableNeuralExtraction` - Extract entity names via AI
+     * - ✅ `enableConceptExtraction` - Extract entity types via AI
+     * - ✅ `preserveSource` - Save original file in VFS
+     *
+     * **If you get an error:**
+     * The error message includes migration instructions and examples.
+     * See the complete migration guide for all details.
+     *
+     * **Why these changes?**
+     * - Clearer option names (explicitly describe what they do)
+     * - Separation of concerns (neural, relationships, VFS are separate)
+     * - Better defaults (AI features enabled by default)
+     * - Reduced confusion (removed redundant options)
      */
     import(source: Buffer | string | object, options?: {
         format?: 'excel' | 'pdf' | 'csv' | 'json' | 'markdown';

package/dist/brainy.js

@@ -719,33 +719,75 @@ export class Brainy {
         });
     }
     /**
-     * Get relationships
+     * Get relationships between entities
+     *
+     * Supports multiple query patterns:
+     * - No parameters: Returns all relationships (paginated, default limit: 100)
+     * - String ID: Returns relationships from that entity (shorthand for { from: id })
+     * - Parameters object: Fine-grained filtering and pagination
+     *
+     * @param paramsOrId - Optional string ID or parameters object
+     * @returns Promise resolving to array of relationships
+     *
+     * @example
+     * ```typescript
+     * // Get all relationships (first 100)
+     * const all = await brain.getRelations()
+     *
+     * // Get relationships from specific entity (shorthand syntax)
+     * const fromEntity = await brain.getRelations(entityId)
+     *
+     * // Get relationships with filters
+     * const filtered = await brain.getRelations({
+     *   type: VerbType.FriendOf,
+     *   limit: 50
+     * })
+     *
+     * // Pagination
+     * const page2 = await brain.getRelations({ offset: 100, limit: 100 })
+     * ```
+     *
+     * @since v4.1.3 - Fixed bug where calling without parameters returned empty array
+     * @since v4.1.3 - Added string ID shorthand syntax: getRelations(id)
      */
-    async getRelations(params = {}) {
+    async getRelations(paramsOrId) {
         await this.ensureInitialized();
-        const relations = [];
+        // Handle string ID shorthand: getRelations(id) -> getRelations({ from: id })
+        const params = typeof paramsOrId === 'string'
+            ? { from: paramsOrId }
+            : (paramsOrId || {});
+        const limit = params.limit || 100;
+        const offset = params.offset || 0;
+        // Production safety: warn for large unfiltered queries
+        if (!params.from && !params.to && !params.type && limit > 10000) {
+            console.warn(`[Brainy] getRelations(): Fetching ${limit} relationships without filters. ` +
+                `Consider adding 'from', 'to', or 'type' filter for better performance.`);
+        }
+        // Build filter for storage query
+        const filter = {};
         if (params.from) {
-            const verbs = await this.storage.getVerbsBySource(params.from);
-            relations.push(...this.verbsToRelations(verbs));
+            filter.sourceId = params.from;
         }
         if (params.to) {
-            const verbs = await this.storage.getVerbsByTarget(params.to);
-            relations.push(...this.verbsToRelations(verbs));
+            filter.targetId = params.to;
         }
-        // Filter by type
-        let filtered = relations;
         if (params.type) {
-            const types = Array.isArray(params.type) ? params.type : [params.type];
-            filtered = relations.filter((r) => types.includes(r.type));
+            filter.verbType = Array.isArray(params.type) ? params.type : [params.type];
         }
-        // Filter by service
         if (params.service) {
-            filtered = filtered.filter((r) => r.service === params.service);
-        }
-        // Apply pagination
-        const limit = params.limit || 100;
-        const offset = params.offset || 0;
-        return filtered.slice(offset, offset + limit);
+            filter.service = params.service;
+        }
+        // Fetch from storage with pagination at storage layer (efficient!)
+        const result = await this.storage.getVerbs({
+            pagination: {
+                limit,
+                offset,
+                cursor: params.cursor
+            },
+            filter: Object.keys(filter).length > 0 ? filter : undefined
+        });
+        // Convert to Relation format
+        return this.verbsToRelations(result.items);
     }
     // ============= SEARCH & DISCOVERY =============
     /**
@@ -1551,33 +1593,91 @@ export class Brainy {
         return options?.limit ? concepts.slice(0, options.limit) : concepts;
     }
     /**
-     * Import files with auto-detection and dual storage (VFS + Knowledge Graph)
+     * Import files with intelligent extraction and dual storage (VFS + Knowledge Graph)
      *
      * Unified import system that:
      * - Auto-detects format (Excel, PDF, CSV, JSON, Markdown)
-     * - Extracts entities and relationships
+     * - Extracts entities with AI-powered name/type detection
+     * - Infers semantic relationships from context
      * - Stores in both VFS (organized files) and Knowledge Graph (connected entities)
      * - Links VFS files to graph entities
      *
-     * @example
-     * // Import from file path
-     * const result = await brain.import('/path/to/file.xlsx')
+     * @since 4.0.0
      *
-     * @example
-     * // Import from buffer
+     * @example Quick Start (All AI features enabled by default)
+     * ```typescript
+     * const result = await brain.import('./glossary.xlsx')
+     * // Auto-detects format, extracts entities, infers relationships
+     * ```
+     *
+     * @example Full-Featured Import (v4.x)
+     * ```typescript
+     * const result = await brain.import('./data.xlsx', {
+     *   // AI features
+     *   enableNeuralExtraction: true,      // Extract entity names/metadata
+     *   enableRelationshipInference: true, // Detect semantic relationships
+     *   enableConceptExtraction: true,     // Extract types/concepts
+     *
+     *   // VFS features
+     *   vfsPath: '/imports/my-data',       // Store in VFS directory
+     *   groupBy: 'type',                   // Organize by entity type
+     *   preserveSource: true,              // Keep original file
+     *
+     *   // Progress tracking
+     *   onProgress: (p) => console.log(p.message)
+     * })
+     * ```
+     *
+     * @example Performance Tuning (Large Files)
+     * ```typescript
+     * const result = await brain.import('./huge-file.csv', {
+     *   enableDeduplication: false,  // Skip dedup for speed
+     *   confidenceThreshold: 0.8,    // Higher threshold = fewer entities
+     *   onProgress: (p) => console.log(`${p.processed}/${p.total}`)
+     * })
+     * ```
+     *
+     * @example Import from Buffer or Object
+     * ```typescript
+     * // From buffer
      * const result = await brain.import(buffer, { format: 'pdf' })
      *
-     * @example
-     * // Import JSON object
+     * // From object
      * const result = await brain.import({ entities: [...] })
+     * ```
      *
-     * @example
-     * // Custom VFS path and grouping
-     * const result = await brain.import(buffer, {
-     *   vfsPath: '/my-imports/data',
-     *   groupBy: 'type',
-     *   onProgress: (progress) => console.log(progress.message)
-     * })
+     * @throws {Error} If invalid options are provided (v4.x breaking changes)
+     *
+     * @see {@link https://brainy.dev/docs/api/import API Documentation}
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     *
+     * @remarks
+     * **⚠️ Breaking Changes from v3.x:**
+     *
+     * The import API was redesigned in v4.0.0 for clarity and better feature control.
+     * Old v3.x option names are **no longer recognized** and will throw errors.
+     *
+     * **Option Changes:**
+     * - ❌ `extractRelationships` → ✅ `enableRelationshipInference`
+     * - ❌ `createFileStructure` → ✅ `vfsPath: '/your/path'`
+     * - ❌ `autoDetect` → ✅ *(removed - always enabled)*
+     * - ❌ `excelSheets` → ✅ *(removed - all sheets processed)*
+     * - ❌ `pdfExtractTables` → ✅ *(removed - always enabled)*
+     *
+     * **New Options:**
+     * - ✅ `enableNeuralExtraction` - Extract entity names via AI
+     * - ✅ `enableConceptExtraction` - Extract entity types via AI
+     * - ✅ `preserveSource` - Save original file in VFS
+     *
+     * **If you get an error:**
+     * The error message includes migration instructions and examples.
+     * See the complete migration guide for all details.
+     *
+     * **Why these changes?**
+     * - Clearer option names (explicitly describe what they do)
+     * - Separation of concerns (neural, relationships, VFS are separate)
+     * - Better defaults (AI features enabled by default)
+     * - Reduced confusion (removed redundant options)
      */
     async import(source, options) {
         // Lazy load ImportCoordinator

package/dist/import/ImportCoordinator.d.ts

@@ -21,7 +21,10 @@ export interface ImportSource {
     /** Optional filename hint */
     filename?: string;
 }
-export interface ImportOptions {
+/**
+ * Valid import options for v4.x
+ */
+export interface ValidImportOptions {
     /** Force specific format (skip auto-detection) */
     format?: SupportedFormat;
     /** VFS root path for imported files */
@@ -55,6 +58,45 @@ export interface ImportOptions {
     /** Progress callback */
     onProgress?: (progress: ImportProgress) => void;
 }
+/**
+ * Deprecated import options from v3.x
+ * Using these will cause TypeScript compile errors
+ *
+ * @deprecated These options are no longer supported in v4.x
+ * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+ */
+export interface DeprecatedImportOptions {
+    /**
+     * @deprecated Use `enableRelationshipInference` instead
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     */
+    extractRelationships?: never;
+    /**
+     * @deprecated Removed in v4.x - auto-detection is now always enabled
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     */
+    autoDetect?: never;
+    /**
+     * @deprecated Use `vfsPath` to specify the directory path instead
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     */
+    createFileStructure?: never;
+    /**
+     * @deprecated Removed in v4.x - all sheets are now processed automatically
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     */
+    excelSheets?: never;
+    /**
+     * @deprecated Removed in v4.x - table extraction is now automatic for PDF imports
+     * @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
+     */
+    pdfExtractTables?: never;
+}
+/**
+ * Complete import options interface
+ * Combines valid v4.x options with deprecated v3.x options (which cause TypeScript errors)
+ */
+export type ImportOptions = ValidImportOptions & DeprecatedImportOptions;
 export interface ImportProgress {
     stage: 'detecting' | 'extracting' | 'storing-vfs' | 'storing-graph' | 'relationships' | 'complete';
     /** Phase of import - extraction or relationship building (v3.49.0) */
@@ -165,4 +207,14 @@ export declare class ImportCoordinator {
      * Normalize extraction result to unified format (Excel-like structure)
      */
     private normalizeExtractionResult;
+    /**
+     * Validate options and reject deprecated v3.x options (v4.0.0+)
+     * Throws clear errors with migration guidance
+     */
+    private validateOptions;
+    /**
+     * Build detailed error message for invalid options
+     * Respects LOG_LEVEL for verbosity (detailed in dev, concise in prod)
+     */
+    private buildValidationErrorMessage;
 }

package/dist/import/ImportCoordinator.js

@@ -62,6 +62,8 @@ export class ImportCoordinator {
     async import(source, options = {}) {
         const startTime = Date.now();
         const importId = uuidv4();
+        // Validate options (v4.0.0+: Reject deprecated v3.x options)
+        this.validateOptions(options);
         // Normalize source
         const normalizedSource = this.normalizeSource(source, options.format);
         // Report detection stage
@@ -558,5 +560,101 @@ export class ImportCoordinator {
         // Fallback: return as-is
         return result;
     }
+    /**
+     * Validate options and reject deprecated v3.x options (v4.0.0+)
+     * Throws clear errors with migration guidance
+     */
+    validateOptions(options) {
+        const invalidOptions = [];
+        // Check for v3.x deprecated options
+        if ('extractRelationships' in options) {
+            invalidOptions.push({
+                old: 'extractRelationships',
+                new: 'enableRelationshipInference',
+                message: 'Option renamed for clarity in v4.x - explicitly indicates AI-powered relationship inference'
+            });
+        }
+        if ('autoDetect' in options) {
+            invalidOptions.push({
+                old: 'autoDetect',
+                new: '(removed)',
+                message: 'Auto-detection is now always enabled - no need to specify this option'
+            });
+        }
+        if ('createFileStructure' in options) {
+            invalidOptions.push({
+                old: 'createFileStructure',
+                new: 'vfsPath',
+                message: 'Use vfsPath to explicitly specify the virtual filesystem directory path'
+            });
+        }
+        if ('excelSheets' in options) {
+            invalidOptions.push({
+                old: 'excelSheets',
+                new: '(removed)',
+                message: 'All sheets are now processed automatically - no configuration needed'
+            });
+        }
+        if ('pdfExtractTables' in options) {
+            invalidOptions.push({
+                old: 'pdfExtractTables',
+                new: '(removed)',
+                message: 'Table extraction is now automatic for PDF imports'
+            });
+        }
+        // If invalid options found, throw error with detailed message
+        if (invalidOptions.length > 0) {
+            const errorMessage = this.buildValidationErrorMessage(invalidOptions);
+            throw new Error(errorMessage);
+        }
+    }
+    /**
+     * Build detailed error message for invalid options
+     * Respects LOG_LEVEL for verbosity (detailed in dev, concise in prod)
+     */
+    buildValidationErrorMessage(invalidOptions) {
+        // Check environment for verbosity level
+        const verbose = process.env.LOG_LEVEL === 'debug' ||
+            process.env.LOG_LEVEL === 'verbose' ||
+            process.env.NODE_ENV === 'development' ||
+            process.env.NODE_ENV === 'dev';
+        if (verbose) {
+            // DETAILED mode (development)
+            const optionDetails = invalidOptions
+                .map((opt) => `
+  ❌ ${opt.old}
+     → Use: ${opt.new}
+     → Why: ${opt.message}`)
+                .join('\n');
+            return `
+❌ Invalid import options detected (Brainy v4.x breaking changes)
+
+The following v3.x options are no longer supported:
+${optionDetails}
+
+📖 Migration Guide: https://brainy.dev/docs/guides/migrating-to-v4
+💡 Quick Fix Examples:
+
+   Before (v3.x):
+   await brain.import(file, {
+     extractRelationships: true,
+     createFileStructure: true
+   })
+
+   After (v4.x):
+   await brain.import(file, {
+     enableRelationshipInference: true,
+     vfsPath: '/imports/my-data'
+   })
+
+🔗 Full API docs: https://brainy.dev/docs/api/import
+      `.trim();
+        }
+        else {
+            // CONCISE mode (production)
+            const optionsList = invalidOptions.map((o) => `'${o.old}'`).join(', ');
+            return `Invalid import options: ${optionsList}. See https://brainy.dev/docs/guides/migrating-to-v4`;
+        }
+    }
 }
 //# sourceMappingURL=ImportCoordinator.js.map

package/dist/neural/improvedNeuralAPI.js

@@ -1310,14 +1310,14 @@ export class ImprovedNeuralAPI {
         for (const sourceId of itemIds) {
             const sourceVerbs = await this.brain.getRelations(sourceId);
             for (const verb of sourceVerbs) {
-                const targetId = verb.target;
+                const targetId = verb.to;
                 if (nodes.has(targetId) && sourceId !== targetId) {
                     // Initialize edge map if needed
                     if (!edges.has(sourceId)) {
                         edges.set(sourceId, new Map());
                     }
                     // Calculate edge weight from verb type and metadata
-                    const verbType = verb.verb;
+                    const verbType = verb.type;
                     const baseWeight = relationshipWeights[verbType] || 0.5;
                     const confidenceWeight = verb.confidence || 1.0;
                     const weight = baseWeight * confidenceWeight;
@@ -2743,7 +2743,7 @@ export class ImprovedNeuralAPI {
         const sampleSize = Math.min(50, itemIds.length);
         for (let i = 0; i < sampleSize; i++) {
             try {
-                const verbs = await this.brain.getVerbsForNoun(itemIds[i]);
+                const verbs = await this.brain.getRelations({ from: itemIds[i] });
                 connectionCount += verbs.length;
             }
             catch (error) {
@@ -2797,9 +2797,9 @@ export class ImprovedNeuralAPI {
                 if (fromType !== toType) {
                     for (const fromItem of fromItems.slice(0, 10)) { // Sample to avoid N^2
                         try {
-                            const verbs = await this.brain.getVerbsForNoun(fromItem.id);
+                            const verbs = await this.brain.getRelations({ from: fromItem.id });
                             for (const verb of verbs) {
-                                const toItem = toItems.find(item => item.id === verb.target);
+                                const toItem = toItems.find(item => item.id === verb.to);
                                 if (toItem) {
                                     connections.push({
                                         from: fromItem.id,

package/dist/storage/baseStorage.js

@@ -600,13 +600,15 @@ export class BaseStorage extends BaseStorageAdapter {
             // Check if the adapter has a paginated method for getting verbs
             if (typeof this.getVerbsWithPagination === 'function') {
                 // Use the adapter's paginated method
+                // Convert offset to cursor if no cursor provided (adapters use cursor for offset)
+                const effectiveCursor = cursor || (offset > 0 ? offset.toString() : undefined);
                 const result = await this.getVerbsWithPagination({
                     limit,
-                    cursor,
+                    cursor: effectiveCursor,
                     filter: options?.filter
                 });
-                // Apply offset if needed (some adapters might not support offset)
-                const items = result.items.slice(offset);
+                // Items are already offset by the adapter via cursor, no need to slice
+                const items = result.items;
                 // CRITICAL SAFETY CHECK: Prevent infinite loops
                 // If we have no items but hasMore is true, force hasMore to false
                 // This prevents pagination bugs from causing infinite loops

package/dist/types/brainy.types.d.ts

@@ -172,14 +172,83 @@ export interface SimilarParams<T = any> {
 }
 /**
  * Parameters for getting relationships
+ *
+ * All parameters are optional. When called without parameters, returns all relationships
+ * with pagination (default limit: 100).
+ *
+ * @example
+ * ```typescript
+ * // Get all relationships (default limit: 100)
+ * const all = await brain.getRelations()
+ *
+ * // Get relationships from a specific entity (string shorthand)
+ * const fromEntity = await brain.getRelations(entityId)
+ *
+ * // Equivalent to:
+ * const fromEntity2 = await brain.getRelations({ from: entityId })
+ *
+ * // Get relationships to a specific entity
+ * const toEntity = await brain.getRelations({ to: entityId })
+ *
+ * // Filter by relationship type
+ * const friends = await brain.getRelations({ type: VerbType.FriendOf })
+ *
+ * // Pagination
+ * const page2 = await brain.getRelations({ offset: 100, limit: 50 })
+ *
+ * // Combined filters
+ * const filtered = await brain.getRelations({
+ *   from: entityId,
+ *   type: VerbType.WorksWith,
+ *   limit: 20
+ * })
+ * ```
+ *
+ * @since v4.1.3 - Fixed bug where calling without parameters returned empty array
+ * @since v4.1.3 - Added string ID shorthand syntax
  */
 export interface GetRelationsParams {
+    /**
+     * Filter by source entity ID
+     *
+     * Returns all relationships originating from this entity.
+     */
     from?: string;
+    /**
+     * Filter by target entity ID
+     *
+     * Returns all relationships pointing to this entity.
+     */
     to?: string;
+    /**
+     * Filter by relationship type(s)
+     *
+     * Can be a single VerbType or array of VerbTypes.
+     */
     type?: VerbType | VerbType[];
+    /**
+     * Maximum number of results to return
+     *
+     * @default 100
+     */
     limit?: number;
+    /**
+     * Number of results to skip (offset-based pagination)
+     *
+     * @default 0
+     */
     offset?: number;
+    /**
+     * Cursor for cursor-based pagination
+     *
+     * More efficient than offset for large result sets.
+     */
     cursor?: string;
+    /**
+     * Filter by service (multi-tenancy)
+     *
+     * Only return relationships belonging to this service.
+     */
     service?: string;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",