- **Core**: Improved verb creation logic by adding `createdAt`, `updatedAt`, and `createdBy` attributes. These fields include timestamped metadata (`seconds`, `nanoseconds`) and source augmentation/service information for better tracking.
- **Storage**: Refactored `BaseStorage` methods to utilize internal variants (e.g., `saveVerb_internal`, `getNoun_internal`). Added support for new verb attributes while maintaining backward compatibility with existing data structures.
- **Tests**:
- Updated `s3-storage.test.ts` and `opfs-storage.test.ts` to validate changes in verb attributes such as timestamps and augmentation metadata.
- Added assertions for `createdAt`, `updatedAt`, and `createdBy` fields in test cases.
- **Cleanup**: Replaced ambiguous type aliases like `Edge` and `HNSWNode` with clearer equivalents (`Verb` and `HNSWNoun_internal`) for consistency across storage adapters.
**Purpose**: Enhance metadata tracking and standardize attribute handling across storage and core modules to ensure accurate and consistent data throughout the system.
- **Code Cleanup**: Removed unnecessary trailing whitespaces across `src/brainyData.ts`. Adjusted formatting for inline object spreads to maintain a consistent coding style.
- **Purpose**: Enhance code readability and ensure adherence to formatting standards without altering functionality.
- **Tests**: Added new `statistics-storage.test.ts` to validate statistics storage functionality across scenarios including saving, retrieving, time-based partitioning, and backward compatibility. Ensured tests dynamically handle missing environment variables by skipping S3-related tests when credentials are unavailable.
- **Docs**: Enhanced `statistics.md` with detailed explanations of scalability improvements, including adaptive flush timing, batched updates, and time-based partitioning. Improved readability and structure.
- **Storage**: Updated all storage adapters to integrate time-based partitioning and maintain backward compatibility with legacy statistics storage formats.
- **Dependencies**: Added `dotenv` to support environmental variable management for storage adapter tests.
**Purpose**: Strengthen system reliability by adding comprehensive test coverage for statistics storage, improve scalability documentation, and ensure consistency across storage adapters with robust implementations.
- **Core**: Introduced a `getCurrentAugmentation` method for detecting active augmentation names. Updated metadata handling to include `createdBy`, `createdAt`, and `updatedAt` attributes for improved tracking.
- **Storage**: Added support for service-based statistics tracking with new methods such as `incrementStatistic`, `decrementStatistic`, and `updateHnswIndexSize`. Implemented persistence for statistics in storage adapters.
- **Statistics**: Enhanced `getStatistics` functionality to provide service-specific breakdowns and support filtering by services. Improved noun, verb, and metadata tracking mechanisms.
- **Search**: Added `service` option to filter results during searches for nouns, verbs, and metadata, ensuring accurate service-based query results.
- **Refactor**: Simplified search logic by integrating HNSW index filtering for better performance when retrieving service-specific results.
- **Tests**: Added comprehensive test coverage for service-level statistics and filtering by service.
**Purpose**: Improve service-level data tracking and analytics while enhancing functionality for filtering and maintaining metadata accuracy to support detailed insights for diverse use cases.
- **Removal**: Deleted `FileSystemStorage` and `OPFSStorage` adapters from the `/storage` directory.
- **Refactor**: Simplifies the codebase by eliminating unused, redundant, or outdated storage implementations.
- **Impact**: Ensures maintainability by focusing on actively supported storage solutions.
**Purpose**: Streamline the project by removing deprecated or unused storage adapters, reducing complexity and maintenance overhead.
- **Core**: Enhanced `getStatistics` function to support `service` and `service[]` filters, enabling statistics breakdown by service. Modified return structure to include `serviceBreakdown` for detailed insights.
- **Storage**: Implemented a new `BaseStorageAdapter` abstract class to centralize statistics-related functionality, such as incrementing/decrementing counters and updating HNSW index size. Refactored all storage adapters (`FileSystemStorage`, `S3CompatibleStorage`, `MemoryStorage`, `OPFSStorage`) to extend `BaseStorageAdapter`, ensuring consistent statistics tracking.
- **Tests**: Added new test cases in `statistics.test.ts` to validate service-level statistics tracking, breakdown accuracy, and multi-service filtering.
**Purpose**: Improve insight into data trends by tracking service-specific usage in statistics. Enhance maintainability and consistency through storage adapter centralization and robust testing.
- Updated `tsconfig.unified.json`, `tsconfig.browser.json`, and `tsconfig.json` to include `"DOM.Asynciterable"` in the `lib` option.
- Ensured compatibility with asynchronous iteration patterns in DOM APIs.
**Purpose**: Enable support for DOM asynchronous iterable utilities, improving compatibility with modern TypeScript and DOM usage scenarios.
- **Storage**: Removed redundant storage implementation files from `/storage` directory while retaining necessary `baseStorage.ts`. Verified no impact on functionality with passing tests.
- **Documentation**: Consolidated multiple overlapping `.md` files into a single `statistics.md` file. Added structured sections for easier reference. Applied markdown naming conventions for clarity.
- **Project**: Introduced `CHANGES_SUMMARY.md` and `MARKDOWN_CONVENTIONS.md` to document changes and naming guidelines, improving project organization. Updated `demo.md` file naming for consistency.
**Purpose**: Simplify the codebase by removing duplicates, enhance maintainability through consolidated and structured documentation, and improve developer experience with clear guidelines and better organization.
- **Core**: Introduced a new `getStatistics` utility function in `statistics.ts` for fetching database statistics at the root level of the library. Enhanced `BrainyData` methods to ensure metadata includes `id` field and refined statistics calculations, excluding verbs from the noun count.
- **Tests**: Added comprehensive test coverage in `statistics.test.ts` for the new utility function, validating proper error handling, statistics accuracy, and consistent results between instance methods and standalone function.
- **Storage Config**: Enabled dynamic support for AWS S3, Cloudflare R2, and Google Cloud Storage in web service configuration, utilizing environment variables for adapter setup. Addressed a race condition in `FileSystemStorage` initialization by deferring path module imports.
**Purpose**: Enhance database analytics by introducing a reusable `getStatistics` function, improve flexibility in storage configuration, and ensure robust testing for reliability and accuracy.
- **New Method**:
- Introduced a new `getStatistics` method in `brainyData.ts` to retrieve key database metrics:
- Counts for nouns, verbs, metadata entries, and HNSW index size.
- **Error Handling**:
- Added try-catch blocks to ensure robust error management when fetching metadata or logging failures.
- **Purpose**:
- Enhances observability of the database state, providing valuable insights for diagnostics and monitoring.
- Updated version to `0.18.0` in `cli-package/package.json` and `package-lock.json`.
- Upgraded `@soulcraft/brainy` dependency to `^0.17.0` for compatibility with recent changes.
- Synced package dependencies and resolved lockfile integrity for deployment.
**Purpose**: Prepare for release by synchronizing versioning across the CLI package and updating dependencies for compatibility.
- Added `autoCreateMissingNouns` and `missingNounMetadata` options to the `addVerb` method in `brainyData.ts`, enabling automatic creation of missing source or target nouns.
- Improved error handling and logging for auto-creation failures, ensuring better feedback during runtime.
- Reformatted existing code for storage options validation to improve readability and maintain consistency.
**Purpose**: Simplify the addition of relationships by automating the process for non-existing nouns and enhance developer experience with better error handling and logging.
- **Version Updates**:
- Updated `web-service-package/package.json` and `package-lock.json` from `0.15.0` to `0.16.0`.
- Updated `cli-package/package.json` and `package-lock.json` from `0.16.0` to `0.17.0`.
- **Purpose**:
- Prepares both packages for their respective new releases, ensuring version consistency across project dependencies.
- **Changes**:
- Eliminated the redundant `@ts-expect-error` comment for the `omelette` import in `cli.ts`.
- **Purpose**:
- Simplifies the code by removing an outdated comment that is no longer needed, ensuring cleaner and more readable source files.
- **Version Updates**:
- Updated `cli-package/package.json` and `package-lock.json` from `0.15.0` to `0.16.0`.
- **NPM Script Enhancements**:
- Added version-related scripts (`version`, `version:patch`, `version:minor`, `version:major`) to `web-service-package` and `cli-package`.
- Introduced `deploy` and `dry-run` scripts to streamline build and deployment workflows.
- **Script Cleanup**:
- Removed redundant `build:cli`, `deploy:cli`, and `deploy:web-service` scripts from the root `package.json`.
**Purpose**: Prepares for release 0.16.0 while introducing reusable and optimized build/release scripts, improving the development and deployment experience.
- **Removal of `generate-version.js`**:
- Deleted `scripts/generate-version.js` as it is no longer required for version handling.
- Removed associated output files, including `src/utils/version.ts`.
- **Prebuild and Version Process Updates**:
- Updated `prebuild` and `version` scripts in `package.json` to reflect the new workflow:
- Replaced `generate-version.js` with simplified echo commands for version updates and build steps.
- Adjusted deployment scripts (`deploy:cli` and `deploy:web-service`) to align with the removal of the script.
- **Documentation and Config Updates**:
- Cleaned up `README.md` by removing unused version badge references.
- Updated `cli-package/package.json` to specify a version range (`^0.15.0`) for `@soulcraft/brainy`.
**Purpose**: This refactor simplifies the version handling process by removing outdated scripts, reducing maintenance overhead, and aligning workflows with project conventions. Improves clarity and consistency in both configuration and documentation.
- **Cloud Storage Integration Testing**:
- Added `cloud-storage.test.ts` to validate cloud storage configurations (AWS S3, Cloudflare R2, Google Cloud Storage) and local storage fallback behavior:
- Includes tests for environment variable priority and configuration detection.
- Ensures proper override with `FORCE_LOCAL_STORAGE` when specified.
- **Package Settings Updates**:
- Introduced `web-service-package/package.json` with configurations for building, running, testing, and deployment:
- Added NPM scripts for building (`npm run build`), development (`npm run dev`), and testing (`npm run test:cloud`).
- Configured dependencies and devDependencies for web service functionality and cloud integration.
- **Purpose**:
- This update ensures comprehensive cloud storage testing and provides structured project configurations for seamless development and deployment workflows.
- **New Web Service Package**:
- Introduced `@soulcraft/brainy-web-service`, a REST API wrapper for the Brainy vector graph database.
- Added documentation and features to support secure, read-only search and retrieval operations.
- **Deployment Support**:
- Included comprehensive deployment instructions in the `web-service-package/README.md`:
- Options for Docker, serverless platforms, and cloud providers (AWS, GCP, Azure, Cloudflare).
- Example configurations for systemd, Nginx, and Docker Compose.
- **Scripts and Documentation Updates**:
- Added `deploy:web-service` script to `package.json` for streamlined build and publishing.
- Enhanced `README.md` to reflect the introduction of the web service package and its capabilities.
- **Purpose**:
- This update extends Brainy’s functionality by providing a production-ready, easy-to-deploy REST API for search operations. It ensures flexibility for diverse deployment scenarios while maintaining security and high performance.
- Updated `VERSION` in `version.ts` to `0.15.0`.
- Updated `npm` badge in `README.md` to reflect version `0.15.0`.
- Updated `version` field and dependency reference in `cli-package/package.json` to `0.15.0`.
**Purpose**: Prepare for release by synchronizing version across source files, documentation, and package dependencies.
- Updated all imports and exports in `src/index.ts` and `src/storage/storageFactory.ts` to use a consistent formatting style.
- Enhanced readability by standardizing spacing, alignment, and indentation across the codebase.
- Applied consistent import/export styling for structured comments and multi-line objects.
**Purpose**: Improve code maintainability and readability by enforcing uniform formatting, aligning imports and exports for better clarity.
- Introduced comprehensive mock for the Origin Private File System (OPFS) in `tests/mocks/opfs-mock.ts`, simulating environment for detailed storage testing.
- Added `tests/opfs-storage.test.ts`, containing extensive test cases for `OPFSStorage` operations including metadata, nouns, verbs, and storage status.
- Improved S3 mock implementation in `tests/mocks/s3-mock.ts` with better object persistence, validation, and logging to emulate real S3 behavior.
- Resolved issues related to metadata, nouns, verbs, and storage usage inconsistencies in mock storage adapters.
- Enhanced logging and error handling to aid in debugging and test reliability.
Purpose: Improve test completeness and reliability by introducing detailed mocks and extended test cases for S3 and OPFS storage systems.
- Added `getFile` method to `FileSystemHandle` interface for enhanced TypeScript compatibility with File System Access API.
- Improved maintainability by reformatting and aligning imports in `brainyData.ts`.
- Standardized spacing and indentation across structured comments and interface fields.
Purpose: Improve TypeScript support for file system operations and enhance code readability with consistent formatting and import management.
- Documented the use of a simplified, unified storage structure for all noun types.
- Enhanced storage system explanation to reflect recent architectural improvements.
Purpose: Improve developer understanding of the storage system by updating documentation with the latest features and design changes.
- Removed outdated test files: `test-tensorflow-import.cjs`, `test-tensorflow-import.js`, and `verify-package-size.js`.
- Introduced `tests/package-size-breakdown.test.ts` to analyze included npm package files and validate their sizes.
- Added comprehensive tests for storage adapters (`MemoryStorage`, `FileSystemStorage`, `OPFSStorage`, etc.) in `tests/storage-adapters.test.ts`.
- Improved OPFS storage mocking and test coverage for browser and Node.js environments.
- Introduced environment detection tests to ensure correct storage adapter selection.
- Created `STORAGE_TESTING.md` to document storage architecture, test coverage, and guidelines for further improvements.
Purpose: Modernize testing infrastructure and enhance storage system reliability through better test coverage and documentation.
- Added `BaseStorage` abstract class to provide common functionality for storage adapters.
- Implemented `FileSystemStorage` adapter for Node.js environments, supporting persistent file-based storage.
- Added directory structure management methods to `FileSystemStorage` (`ensureDirectoryExists`, `clear`, etc.).
- Implemented `MemoryStorage` adapter for in-memory storage suitable for non-persistent environments.
- Supported CRUD operations for nouns, verbs, and metadata in both `FileSystemStorage` and `MemoryStorage`.
- Included utility methods like `mapToObject` for serialization and deserialization of complex data structures.
Purpose: Provide extensible, reusable storage solutions with both persistent and non-persistent options for diverse application needs.
- Documented various WebSocket augmentation types (`IWebSocketSupport`, `IWebSocketSenseAugmentation`, etc.) to guide developers in extending augmentations with WebSocket capabilities.
- Added code example showcasing the creation of a WebSocket-enabled sense augmentation (`mySenseAug`) using `addWebSocketSupport`.
- Explained the purpose of combining base augmentation interfaces with `IWebSocketSupport` for type safety and autocompletion.
Purpose: Enhance developer documentation by providing clear guidance and examples for integrating WebSocket capabilities into augmentations.
- Updated `VERSION` in `version.ts` to `0.14.0`.
- Updated `npm` badge in `README.md` to reflect version `0.14.0`.
- Updated `version` field and dependency reference in `cli-package/package.json` to `0.14.0`.
Purpose: Prepare for release by synchronizing version across source files and documentation.
- Introduced `SearchResult` interface to standardize search result handling and improve code readability.
- Added TypeScript type annotations for command arguments and options in CLI methods to enforce stricter type safety.
- Updated `.version()` for CLI to align with best practices by removing redundant description parameter.
- Enhanced search logic with default parameter handling for limits and improved output formatting for results.
- Adjusted `tsconfig.json` to disable `noImplicitAny` while retaining strict typing practices.
- Streamlined CLI processes by parsing command-line arguments explicitly with `program.parse(process.argv)`.
Purpose: Improve developer productivity with better type safety, clearer interfaces, and refined CLI functionality.
- Added a check to avoid appending `ROOT_DIR` if the `rootDir` already ends with it.
- Ensures proper directory paths setup without redundant path segments.
- Refactor embedding functions to support customizable verbosity through new helper methods (`getDefaultEmbeddingFunction`, `getDefaultBatchEmbeddingFunction`).
- Ensure metadata initialization with default values when null during search results.
- **Logging Cleanup**:
- Removed redundant `console.log` statements in `brainyData.ts` and `embedding.ts` related to Universal Sentence Encoder initialization and load function detection.
- Replaced detailed logs with concise comments to streamline debugging and reduce noisy outputs.
- **Purpose**:
- Improves code readability, reduces runtime logging noise, and aligns logging verbosity with the project's streamlined debugging practices.
- **Core Improvements**:
- Refactored logging functions into a unified `logger` method for consistent output across the library.
- Enabled the `forceMemoryStorage` option in `BrainyData` initialization for improved storage flexibility in tests and specific use cases.
- **TensorFlow.js and Environment Updates**:
- Clarified the dependency structure in `README.md` to emphasize bundled dependencies and remove legacy peer dependency instructions.
- Simplified and reformatted environment detection logic for better maintainability and readability.
- **Testing Enhancements**:
- Added `tests/package-size-limit.test.ts` to monitor and validate npm package size against defined thresholds.
- Updated `tests/environment.node.test.ts` and core tests to leverage `forceMemoryStorage` for better test setup standardization.
- Improved test isolation with expanded `globalThis` utility definitions and cleanup logic.
- **Documentation**:
- Added detailed best practices for debugging and organizing tests in `DEVELOPERS.md`.
- Removed outdated installation hints from `package.json` and streamlined scripts by including `test:size` for package size validation.
**Purpose**: These changes unify core logging mechanisms, expand configurability of storage options, and improve testing reliability and coverage. Documentation and clarity are enhanced to align with updated functionality and best practices.
- **CLI Documentation Updates**:
- Updated `README.md` to reflect the separation of CLI functionality into a new package: `@soulcraft/brainy-cli`.
- Replaced inline CLI imports with instructions for installing and using `@soulcraft/brainy-cli`.
- Clarified notes on keeping the main package lightweight by decoupling CLI functionality.
- **Script and Command Adjustments**:
- Modified build instructions in `README.demo.md` to use `npm run build && npm run build:browser`.
- Updated demo scripts in `package.json` to point to `/demo/index.html` instead of `/index.html`.
- Revised style-check script in `CONTRIBUTING.md` to use `npm run check:style`.
- **Issues and Contribution Guidelines**:
- Improved issue reporting section in `DEVELOPERS.md` with clearer guidelines and examples for bug and feature requests.
**Purpose**: These changes enhance documentation accuracy, streamline developer guidance, and ensure commands/scripts are up-to-date with current usage patterns.
- Updated `version` of `@soulcraft/brainy` from `0.11.0` to `0.12.0` in `cli-package/package-lock.json`.
- Adjusted resolved package metadata (e.g., `integrity` values) to match the new release version.
**Purpose**: Ensures `package-lock.json` reflects the updated dependency version for consistency with the 0.12.0 release.
- Updated the version in `README.md`, `package.json`, and `version.ts` to `0.12.0` to reflect the new release.
- Adjusted dependency reference for `@soulcraft/brainy` in `cli-package/package.json` to use version `0.12.0`.
**Purpose**: Prepares for the 0.12.0 release, ensuring all version references are consistent across documentation and configuration files.
