Released on December 19, 2025

Overview

This release focuses on database backend modernization, major Registry performance/reliability upgrades (local cache + integrity verification), and Cluster operational improvements (worker port auto-selection + node worker tracking). It also includes substantial test coverage expansions across modules.

Major Features

Database: Unified ODM Enhancements + Auto-Initialization

• Auto-initialize database backends on first operation

  • Added auto_init and init_mode support across ODMs
  • Improved sync/async interoperability (e.g., Redis async wrappers via thread pool to avoid blocking the event loop)

• Unified ODM API Expansion

  • Added find() / find_async()
  • Added get_raw_model() for backend-specific query expressions via the active backend model

• Expanded Mongo ODM

  • New Mongo ODM implementation (mongo_odm.py) with robust initialization behavior and testing

Registry: Local Cache + Integrity Verification + New Archiver

• Local cache support for remote backends

  • Read-through cache behavior with validation (including verify_cache support)
  • Cache hash verification to detect corruption / stale state

• Artifact integrity verification

  • Hash computation and verification via compute_dir_hash
  • Hash mismatch produces explicit error signaling possible corruption/tampering

• PathArchiver

  • Added PathArchiver and default archiver registration hooks for path-based artifacts

• Reliability improvements

  • Safer metadata writes in LocalRegistryBackend (unique temp file + atomic rename)
  • Better handling of empty metadata files and version string normalization
  • Thread-safety and lock-context refactors to reduce contention and harden behavior

Cluster: Worker Port Auto-Selection + Node Worker Database

• Automatic worker port selection

  • Nodes select worker ports from a configured range (MINDTRACE_CLUSTER.WORKER_PORTS_RANGE)
  • Port range parsing supports hyphen ranges (e.g. 8092-8111) while preserving comma-separated support

• Node Worker database

  • Persist and query attached workers on a node (Redis-backed via UnifiedMindtraceODM)

Storage: GCS Handler Fixes

• GCS upload URI bug fix and expanded test coverage for GCSStorageHandler
• Improved path sanitization and bucket/path validation behavior

Improvements & Bug Fixes

Jobs

• Local client fixes
  • Preserved client_dir and corrected Registry API usage
• More robust unit tests (e.g., queue naming fixes and additional edge-case coverage)

Core

• Added WORKER_PORTS_RANGE to core settings/config defaults to support cluster auto-port selection
• Added compute_dir_hash utility and tests

Hardware

• Large expansion of unit tests (OpenCV camera backend, Basler setup/mocks, PLC systems including Allen Bradley)
• Minor cleanup (e.g., unreachable return removal)

Testing Infrastructure

• Major test suite expansion across unit + integration tests
  • Registry cache, thread-safety, race-condition paths
  • Unified ODM + registry-backed ODM integration tests
  • Large hardware coverage additions and timeout optimizations for slow tests

Documentation

• Significant updates to mindtrace-database README
  • Unified ODM usage patterns
  • Sync/async interoperability guidance
  • Initialization modes and best practices
  • Breaking rename mapping table (see Migration Notes)

Statistics

• 120 commits between v0.6.0 and v0.7.0 release commits
• 22,411 lines added, 1,853 lines removed
• 125 files changed
• Notable PRs merged:
  • #312: Cluster auto port selecting
  • #311: Node worker database
  • #306: Unified model backend tests
  • #304: Test pack / coverage push
  • #302: Registry cleanup
  • #301: Registry local cache
  • #298: Database enhancements
  • #294: Registry PathArchiver

Migration Notes

Configuration Changes

• Cluster worker port range: new config key
  • MINDTRACE_CLUSTER.WORKER_PORTS_RANGE (default 8092-8111)

Breaking Changes

• Database ODM class/file renames (removal of Backend suffix; file names updated)
  • See mindtrace/database/README.md “Breaking Changes” table for old → new names and import updates.

Upgrade Path

1. If using Cluster Nodes, set/confirm MINDTRACE_CLUSTER.WORKER_PORTS_RANGE to match your deployment constraints.
2. If importing database ODM classes by old names/files, update imports to the new *ODM names.
3. Registry users can optionally enable/lean on cache + hash verification for stronger integrity guarantees (especially on remote backends).

Released on November 28, 2025

Overview

This release introduces major new features including GCP backend support for the Registry, native MongoDB querying for Datalake, feature detection and classification utilities, comprehensive documentation improvements, and significant performance optimizations across multiple modules.

Major Features

Registry GCP Backend

• Complete GCP Backend Implementation: Full Google Cloud Storage backend support for distributed registry operations

  • Atomic operations using GCS object generation numbers
  • Distributed locking with generation-based concurrency control
  • Automatic bucket creation and management
  • Support for service account credentials
  • Comprehensive error handling and race condition fixes

• Registry Performance Optimizations:

  • Direct existence checks instead of listing all objects for has_object() operations
  • Caching for list_versions() with configurable TTL (default 60 seconds)
  • Thread-safe cache invalidation on save/delete operations
  • Optimized metadata path generation with helper methods

• Registry Configuration:

  • Configurable versions_cache_ttl parameter in Registry class
  • Enhanced GCP configuration support in core settings
  • Improved credentials handling for GCS storage

Datalake MongoDB Query

• Native MongoDB Querying: Complete rewrite of query_data() using MongoDB's native aggregation pipeline

  • Significant performance improvements for common query patterns
  • Single aggregation pipeline instead of multiple round trips
  • Support for complex multi-level derivation queries
  • Improved handling of "random" strategy for derived queries

• Query Enhancements:

  • Better error handling and edge case coverage
  • Improved async fixture handling in integration tests
  • Enhanced documentation with comprehensive examples

Automation Feature Detection

• Feature Detection System: Complete feature detection and classification framework

  • FeatureDetector: Cross-compare expected ROIs/labels with model predictions
  • FeatureClassifier: Pluggable classification rules system
  • Support for bounding box and segmentation mask detection
  • Resolution scaling support for different annotation and inference resolutions
  • Configurable classification rules (e.g., length thresholds)

• Feature Models:

  • Feature dataclass with presence detection and status reporting
  • FeatureConfig for configuring expected features
  • Measurement calculations with pixel-to-millimeter conversion
  • Support for shared union bounding boxes across feature groups

• Feature Extractors:

  • BoxFeatureExtractor for bounding box-based detection
  • MaskFeatureExtractor for segmentation mask-based detection
  • Contour extraction and matching logic

Core Enhancements

• BoundingBox Improvements:

  • Added x1 and y1 properties for syntactic sugar
  • Improved type hints and documentation

• Configuration System:

  • Added MINDTRACE_GCP configuration section with full GCP support
  • Enhanced configuration loading and validation
  • Improved environment variable handling

Improvements & Bug Fixes

Registry

• Fixed metadata creation and fallback path handling in GCP backend
• Improved exception handling and batch registration operations
• Fixed race conditions in GCP backend lock acquisition
• Enhanced unit tests for all backend types (Local, MinIO, GCP)
• Fixed overwrite verification warning paths
• Improved idempotent deletion handling
• Capped MinIO version to avoid breaking changes in 7.2.19
• Added comprehensive integration tests for GCP backend

Datalake

• Fixed random strategy for derived queries
• Improved async fixture handling in integration tests
• Enhanced query pipeline documentation
• Better error messages and edge case handling

Jobs

• Fixed Redis connection unit tests with proper thread patching
• Improved mock handling for Redis operations
• Enhanced test reliability and isolation

Storage

• Improved GCS storage handler credentials handling
• Fixed concurrent operations integration test timing issues
• Enhanced error handling for storage operations

Cluster

• Fixed linting issues in cluster integration tests
• Improved early failure detection in integration tests
• Enhanced pre-existing service checks

Testing Infrastructure

• Comprehensive Test Coverage:

  • Added extensive unit tests for GCP registry backend (2000+ lines)
  • Enhanced MinIO backend test coverage
  • Improved Local backend test coverage
  • Added ultralytics archiver tests (SAM, YOLO, YOLOE)
  • Comprehensive datalake query unit tests

• Integration Test Improvements:

  • Fixed async fixture handling across multiple modules
  • Improved GCP integration test reliability with conditional execution
  • Enhanced test fixtures with better isolation
  • Added support for skipping tests when credentials are unavailable

• Test Organization:

  • Better fixture naming to avoid conflicts
  • Improved test markers and organization
  • Enhanced error messages in test failures

Documentation

• Comprehensive Registry Documentation:

  • Complete README with all backend types (Local, MinIO, GCP)
  • Usage examples for each backend
  • Advanced usage patterns and custom materializers
  • Version management documentation

• Datalake Documentation:

  • Enhanced README with MongoDB query examples
  • Comprehensive query strategy documentation
  • Multi-level query examples and patterns
  • Performance considerations and best practices

• Automation Documentation:

  • Complete feature detection and classification guide
  • Configuration examples and usage patterns
  • Resolution scaling documentation

• API Documentation:

  • Fixed and improved docstrings throughout codebase
  • Enhanced API documentation generation
  • Added favicon and improved navigation in MkDocs

• Integration Test Documentation:

  • Added comprehensive README for integration tests
  • Test setup and execution guides

Code Quality

• Ruff Formatting: Applied consistent formatting across all modules
• Import Cleanup: Removed unused imports and fixed import paths
• Type Hints: Enhanced type hints across multiple modules
• Linting: Fixed all linting issues across the codebase
• Code Organization: Improved module structure and exports

Dependencies

• Updated fastmcp version to address dependabot alerts
• Added mindtrace-storage dependency to registry module
• Capped MinIO version to <7.2.19 due to breaking changes

Testing

• Registry Tests: Comprehensive test suite covering all backends

  • Unit tests for Local, MinIO, and GCP backends
  • Integration tests with race condition testing
  • Edge case and error handling tests

• Datalake Tests: Enhanced query testing

  • Unit tests for query pipeline
  • Integration tests with MongoDB
  • Strategy-specific test coverage

• Automation Tests: Feature detection testing

  • Unit tests for feature detection and classification
  • Integration test examples

• Integration Tests: Improved reliability

  • Better async fixture handling
  • Enhanced error detection and reporting
  • Conditional test execution for cloud services

Statistics

• 123 commits between v0.5.0 and v0.6.0
• 10,458 lines added, 559 lines removed
• 96 files changed
• Multiple Pull Requests merged:
  • #270: Registry GCP backend implementation
  • #268: Datalake MongoDB query improvements
  • #262: Documentation and docstring fixes
  • #255: Documentation improvements
  • #186: Feature detection and classification functionality
  • #254: v0.5.0 release candidate

Migration Notes

New Features

• GCP Registry Backend: New backend option for Google Cloud Storage

  • Requires GCP project ID and bucket configuration
  • Service account credentials needed for authentication
  • See Registry README for setup instructions

• Datalake Query: query_data() now uses native MongoDB aggregation

  • Backward compatible with existing query syntax
  • Significant performance improvements for complex queries
  • query_data_legacy() available for legacy behavior if needed

• Feature Detection: New automation utilities available

  • Import from mindtrace.automation.utils
  • Requires configuration JSON files
  • See automation README for usage examples

Configuration Changes

• GCP Support: Added MINDTRACE_GCP configuration section
  • GCP_REGISTRY_URI: Registry URI for GCP backend
  • GCP_PROJECT_ID: GCP project identifier
  • GCP_BUCKET_NAME: GCS bucket name
  • GCP_CREDENTIALS_PATH: Path to service account JSON
  • GCP_LOCATION: Bucket location
  • GCP_STORAGE_CLASS: Storage class for buckets

Breaking Changes

None in this release. All changes are backward compatible.

Deprecations

None in this release.

Upgrade Path

1. For GCP backend usage, configure GCP settings in environment or config files
2. Datalake queries will automatically use the new MongoDB aggregation pipeline
3. Feature detection utilities are opt-in and don't affect existing code

Contributors

Thank you to all contributors who made this release possible!

Released on October 31, 2025

Overview

This release includes significant enhancements across multiple modules, with major features in the Registry backend, Datalake integration, Discord services, structured logging, hardware sensors, and comprehensive testing improvements.

Major Features

Registry Backend Enhancements

• Registry-backed Local Jobs Client: Local jobs client now uses Registry as a backend for improved persistence and versioning
• Registry ODM Backend: New MongoDB ODM backend integration for database operations

Datalake Integration

• Query Strategies: Added "latest", "earliest", "random", "missing", and "quickest" strategies for data retrieval
• Query Enhancements:
  • Added transpose parameter to query_data
  • Added datums_wanted parameter for controlling result count
  • Switched to returning list of dictionaries for better usability
• Async Operations: Improved async data fetching with asyncio.gather for parallel operations
• Registry Integration: Comprehensive integration with Registry backend for metadata and object management

Discord Service

• New Discord Integration: Complete Discord service implementation for programmatic bot interactions
• Discord Client: Full-featured Discord client for connecting and managing Discord bots
• HTTP API Support: Implemented programmatic Discord command execution via HTTP API
• Service Implementation: Discord service with proper configuration handling and lifecycle management
• Separate Testing API: Added separate testing API token support for tests
• Bot Connection Handling: Robust connection handling including cases when bot user is None

Structured Logging

• Service Structlog: Comprehensive structured logging implementation for services
• Operation Tracking: Replaced autolog with track_operation for better observability
• Service Name Middleware: Added service name identification in middleware
• System Metrics: Included system metrics collection in logging
• Promtail Configuration: Updated Promtail configuration for better log aggregation

Hardware Sensors

• MQTT Sensor Backend: Full MQTT sensor backend implementation
• Sensor System Infrastructure: Complete sensor system with unified interface
• Sensor Connection Manager: Typed client access via SensorConnectionManager
• Sensor Manager Service: MCP endpoint registration for sensor operations
• Sensor Simulator: Comprehensive sensor simulator with MQTT, HTTP, and Serial backends
• Testing Suite: Complete sensor system testing suite

Jobs Module

• Orchestrator Improvements:
  • Moved Orchestrator to jobs core module
  • Added support for passing TaskSchemas directly to Orchestrator.publish
  • Set LocalClient as default backend
• Local Priority Queue: Added priority queue support with PriorityQueueArchiver
• Stack Support: Added Stack data structure with StackArchiver
• Redis Consumer Fixes: Fixed Redis Consumer bug and improved timeout handling
• LocalClient Bug Fixes: Fixed multiple LocalClient issues

Improvements & Bug Fixes

Registry

• Fixed metadata creation and fallback path handling
• Improved exception handling and batch registration
• Enhanced unit tests for backend types

Database

• Added MongoDB ODM backend with Registry integration
• Fixed database query issues with limited rows
• Improved type hints and code quality
• Enhanced unit test coverage

Services

• Fixed coroutine cleanup when run_coroutine_threadsafe fails
• Replaced print statements with proper logger.info calls
• Improved error handling and connection management

Cluster

• Fixed port numbering conflicts in tests
• Changed Worker Consumer from Process to Thread
• Fixed connection manager timeouts (increased to 60s)
• Added status check before submitting jobs to avoid race conditions
• Fixed lazy properties for RabbitMQ client connection and channel

Testing Infrastructure

• Port Standardization: Standardized test ports across services:
  • Redis: 6380
  • RabbitMQ: 5673
  • MinIO: 9100
  • MongoDB: 27018
• Pytest Improvements:
  • Added --rootdir flag for fixture discovery
  • Added pytest markers for better test organization
  • Made pypylon docker image opt-in for integration tests
• Test Coverage: Significant improvements across all modules

Documentation

• Added comprehensive documentation for Registry integration
• Updated sensor system documentation with service layer and MCP integration
• Added README for Datalake module
• Improved docstrings throughout the codebase

Code Quality

• Ruff Formatting: Applied consistent formatting across all modules
• Import Cleanup: Removed unused imports and fixed import paths
• Type Hints: Enhanced type hints across multiple modules
• Code Organization:
  • Moved samples to dedicated samples/ directory
  • Improved module exports and organization

Dependencies

• Updated dependency groups to use dependency-groups.dev instead of deprecated tool.uv.dev-dependencies
• Added aiomqtt for MQTT sensor functionality
• Added pymongo for MongoDB ODM backend

Testing

• Registry Tests: Comprehensive unit test suite for backend types (MinIO, Local)
• Integration Tests: Fixed integration test issues and added support for ultralytics fixtures
• Database Tests: Improved test coverage with better fixtures and structure
• Jobs Tests: Added complete test suite reaching 100% coverage
• Hardware Tests: Comprehensive sensor system testing suite
• Discord Tests: Unit and integration tests for Discord functionality

Statistics

• 229 commits between v0.4.0 and v0.5.0
• 38,263 lines of changes
• Multiple Pull Requests merged:
  • #224: Datalake/Registry and Database integration
  • #226: Service structlog implementation
  • #205: Discord cleanup
  • #134: Registry-backed local jobs client
  • #137: MongoDB ODM
  • #183: Sensor MQTT
  • #208: Cluster port renumbering
  • And many more...

Migration Notes

Breaking Changes

• Orchestrator: Now defaults to LocalClient backend instead of Redis
• Samples: Moved from sample/ to samples/ directory

Deprecations

• tool.uv.dev-dependencies replaced with dependency-groups.dev

Upgrade Path

1. Update Orchestrator configurations if relying on Redis as default
2. Ensure test ports match new standardized values

Contributors

Thank you to all contributors who made this release possible!

Released on September 26, 2025

Major Features

Hardware Overhaul

• Introduced a new service-based camera management API with async improvements.
• Added support for PIL image format, HDR, and extended Basler and OpenCV backends with better error handling, executor/thread management, and timeout handling.
• Refactored camera classes into:
  • Camera, AsyncCamera
  • CameraManager, AsyncCameraManager
• Deprecated Daheng camera support and legacy route-based API.
• Comprehensive new unit and integration test suites for hardware components.

Label Studio Integration

• New mindtrace.automation.label_studio package:
  • High-level LabelStudio API client wrapper.
  • Support for project creation, deletion, task import/export, GCP storage sync, and annotation management.
  • Custom exception hierarchy for predictable error handling.
• Added README and sample usage scripts for Label Studio automation.

Configuration Enhancements

• Introduced pydantic-settings dependency for configuration management.
• Added config tests and support for environment variable overrides (via MINDTRACE_ keys).
• Extended cluster config with MinIO and GCS integration.

Testing & QA

• Added TESTING.md quick reference for ds test commands:

  ds test          # unit + integration
  ds test --unit   # unit only
  ds test --integration
  ds test --stress

• Expanded hardware tests (Basler/OpenCV backends, CameraManager).
• Mocked Basler setup to avoid downloads in unit tests.
• Skips for ultralytics tests when model servers are unavailable.

Documentation

• Added CONTRIBUTING.md with detailed workflow, PR guidelines, and quality standards.
• Added downloads badge to README.
• Added Label Studio usage documentation and sample projects.

Developer Experience

• Adopted ruff ≥0.13 for linting and formatting.
• Shortened imports and removed redundant loggers.
• Cleanup:
  • Removed legacy uv.lock
  • Removed redundant APIs
  • Removed Daheng camera code
• Improved Docker environment setup (Basler SDK, GCP credentials).
• Improved cluster integration test stability.

Fixes

• Hardware:
  • Proper exception raising instead of returning False.
  • Raise connection errors when cameras not initialized.
  • Fixed exposure, gain, and ROI handling in Basler/OpenCV backends.
• Fixed async race conditions in camera tests.
• Fixed cluster and registry test flakiness.
• Fixed Reflex .gitignore coverage.

Upgrade Notes

• Hardware API refactor: migration from old route-based API to new async service-based API is required.
• Daheng cameras are no longer supported.
• Requires Python 3.12+.

Re-install dependencies:

uv sync --dev
uv tool install ds-run
uv tool install ruff

✦ Thanks to all contributors who helped shape this release!

mindtrace-core

• Image conversion utilities
• Updated tests

mindtrace-registry

• Materializer registration at import time

mindtrace-services

• MCP Client Manager session for connecting and discovering tools in Services
• Better interrupt handling for connecting to Services

mindtrace-hardware

• Tests included in standard ds test suite
• Reduced time taken by unit tests

tests

• ds test: module [--unit] [--integration] command for running tests for one or more modules by name (core, services, database etc.)

- mindtrace-database

• Unified ODM backend (UnifiedMindtraceODMBackend) supporting MongoDB and Redis with a single API.
• MongoDB backend using Beanie ODM
• Redis backend using Redis ODM
• Standardized exceptions

- mindtrace-cluster

• ClusterManager gateway for distributed job orchestration and worker lifecycle management.
• REST endpoints for job submission/status, worker and node registration, worker launch, and status queries.
• Redis-backed state via UnifiedMindtraceODMBackend
• RabbitMQ-based orchestration
• MinIO-backed worker registry

- mindtrace-jobs

• Multi-backend job queue support: Local, Redis, RabbitMQ.
• Orchestrator for routing jobs to backend-specific clients.
• Backend clients and consumer backends: LocalClient/LocalConsumerBackend, RedisClient/RedisConsumerBackend, RabbitMQClient/RabbitMQConsumerBackend.
• Core types: Job, JobSchema, ExecutionStatus, BackendType.
• Utility: job_from_schema for creating jobs from typed schemas.

- mindtrace-registry

• Registry core with pluggable RegistryBackend interface for artifact versioning and metadata.
• Backends: LocalRegistryBackend, MinioRegistryBackend, GCPRegistryBackend.
• Archiver abstraction and ConfigArchiver for persisting mindtrace.core.Config.
• Locking/error handling with LockTimeoutError.

- mindtrace-services

• Integrated MCP server using fastmcp to expose service functionality as tools.
• Automatic MCP HTTP app creation and mount at /mcp-server.
• add_endpoint(..., as_tool=True) to register REST endpoints as MCP tools.
• add_tool(tool_name, func) helper to register standalone MCP tools with enriched descriptions.

Core Features

• Base Classes & Metaclasses : Provides MindtraceABC, MindtraceMeta, and Mindtrace for consistent architecture and extensibility.
• Configuration Management : Centralized Config class for robust configuration handling and validation.
• Event System: Lightweight EventBus for publish-subscribe event dispatching.
  ObservableContext decorator for automatic property observation and reactivity.
  ContextListener for easy event-driven observers with built-in logging.
• Utilities : Type checking, dynamic imports, and helper functions (check_libs, ifnone, instantiate_target).
• Structured Logging : Unified logging utilities for all Mindtrace components.

Registry Features

• Pluggable Registry Backends
• Central Registry class for managing objects, versions, and metadata.
• Register and retrieve custom materializers for object serialization/deserialization.
• Config archiver for storing and retrieving configuration snapshots.

Storage Features

• Abstract Storage Interface
• Implements GCSStorageHandler for interaction with Google Cloud Storage buckets.
• Support for Bulk upload/download and folder-level operations

Service Features

• Unified Microservice Base
• Auto-Generated Connection Managers
• Endpoint Management via TaskSchema

Test Suite Organization

• unit/: Fast, isolated unit tests.
• integration/: Integration tests for multi-component and backend scenarios.
• stress/: Stress and performance tests for long-running or high-load scenarios.

Test Orchestration

• Unified test runner script (scripts/run_tests.sh) for running all or specific test suites.
• Docker Compose integration for spinning up required services (e.g., MinIO) during integration tests.
• Automatic coverage collection and reporting.