knucklesuganda/py_assimilator

Assimilator is a Python library that provides a unified, pattern-based interface for data access and event handling across multiple storage backends, including SQLAlchemy (PostgreSQL/MySQL), MongoDB, and Redis. It abstracts common database operations like CRUD, filtering, and transaction management through a consistent API, while also supporting reliable outbox patterns for event publishing. The system is designed to allow developers to switch between different database providers without changing application code, facilitated by a registry-based architecture.

16 changes.

This period focused on establishing the foundational architecture for the assimilator library, introducing core abstractions for database repositories, unit of work, and event handling. The work included implementing specific integrations for SQLAlchemy, Redis, and MongoDB, alongside internal in-memory implementations for testing and development.

16 changes.

This period focused on expanding the framework's data access layer by adding support for Redis, MongoDB, and Kafka, alongside standardizing query specifications across all backends. The work introduced a unified pattern-based architecture for creating repositories and unit of work instances, enabling consistent interactions with diverse storage providers.

A new AlchemyOutboxRepository class is introduced to handle database events by saving both the primary object and its associated outbox event. This repository extends the existing AlchemyRepository and integrates with the ErrorWrapper pattern for exception handling, providing a dedicated mechanism for managing database-level events within the Alchemy framework.

assimilator/alchemy/events/database · high confidence

Added a new FastAPI example demonstrating CRUD operations (list, get, create, update, delete) for users. The example supports multiple storage backends (Alchemy, internal, Redis, Mongo) via environment variable configuration, providing a concrete implementation of the CRUDService across different database technologies.

_examples/fastapi\_crud\example · high confidence

Introduced new core components for the assimilator library: an event system with Event, ExternalEvent, and AckEvent classes; a pattern registry for managing repository, unit of work, and CRUD service mappings; and database model implementations for Redis (RedisModel with TTL and conditional update options) and MongoDB (MongoModel with ObjectId handling). Additionally, example applications for complex and simple database scenarios were added, demonstrating usage with SQLAlchemy, Redis, and MongoDB.

_py\assimilator · high confidence

Added a new example in the examples/simple\_events directory that demonstrates basic event production and consumption. The example includes a RecordCreated event class and a main script that uses either an in-memory or Redis-based event producer and consumer, depending on command-line arguments.

_examples/simple\events · high confidence

Introduced the simple\_database example, providing a runnable demonstration of the library's core features across multiple database backends (Alchemist, Internal, Redis, and MongoDB). The example showcases unit-of-work patterns, repository operations (create, read, update, delete), and filtering capabilities, allowing users to see how to configure and interact with different storage providers.

_examples/simple\database · high confidence

Introduced a new AlchemyOutboxRelay implementation that persists events to a database table and delivers them via a provided EventProducer. This change enables reliable outbox pattern support for SQLAlchemy-based repositories, ensuring events are stored and processed through the specified producer.

assimilator/alchemy/events · high confidence

Users can now use Kafka for event publishing and consumption. This change introduces \KafkaEventConsumer\ and \KafkaEventProducer\ classes in the \assimilator/kafka\_/events/events\_bus.py\ module, enabling integration with Apache Kafka for handling external events.

assimilator/kafka\, assimilator/redis\/events · high confidence

Introduced MongoDB support in the \assimilator/mongo/database\ package. This includes a new \MongoRepository\ for performing CRUD operations, a \MongoUnitOfWork\ for managing transactions, and a \MongoErrorWrapper\ to map MongoDB-specific errors to internal exceptions. The repository implements standard database interface methods such as \get\, \filter\, \save\, \delete\, \update\, \count\, and \refresh\.

assimilator/mongo/database · high confidence

Introduced new specification classes for MongoDB, including MongoFilteringOptions to handle field name conversion (e.g., 'id' to '\_id') and operator mapping for queries. Added MongoFilter for constructing and combining filter conditions, along with specification functions for ordering (mongo\_order), pagination (mongo\_paginate), and field projection (mongo\_only). These changes enable the application to construct and execute MongoDB-specific database queries.

assimilator/mongo/database/specifications · high confidence

Introduced Redis support in the data access layer by adding a new \RedisRepository\ and \RedisUnitOfWork\ implementation. The \RedisRepository\ provides CRUD operations (get, filter, save, delete, update, count) backed by Redis, including support for lazy commands, specification-based filtering, and transactional commits/rollbacks via \RedisUnitOfWork\. This enables users to persist and query models using Redis as a backend store.

assimilator/redis\/database · high confidence_

A new example file, examples/simplest\_example.py, has been added to demonstrate the creation of a CRUDService pattern using SQLAlchemy. This example shows how to define a user model, create a CRUD service, and perform create and read operations, serving as a starting point for new users.

examples · high confidence

Added a new example in the \examples/complex\_database\ directory that demonstrates working with complex database relations and foreign keys across multiple backends. The example includes \dependencies.py\ to configure UnitOfWork and Repository instances for SQLAlchemy, internal memory, Redis, and MongoDB, and \main.py\ to showcase CRUD operations, filtering, and joins. This provides a concrete reference for implementing multi-database strategies in applications using the Assimilator framework.

_examples/complex\database · high confidence

The assimilator/core module now includes an \_\init\\_.py file to initialize the package, and a new exceptions.py file that defines a ParsingError exception class for handling parsing-related errors.

assimilator/core · high confidence

Introduced new modules in the internal database specifications package to support in-memory filtering, ordering, and pagination for internal models. The changes add \filter\_specifications.py\ (defining \InternalFilter\ and \CompositeFilter\ for boolean logic), \filtering\_options.py\ (defining \InternalFilteringOptions\ with comparison operators like \eq\, \gt\, \like\, etc.), \internal\_operator.py\ (providing the underlying comparison functions), \specifications.py\ (implementing \internal\_order\, \internal\_paginate\, \internal\_join\, and \internal\_only\), and \utils.py\ (helper functions for model attribute access). These components enable the internal database layer to process query specifications directly in Python rather than relying solely on SQL or ORM constructs.

assimilator/internal/database/specifications · high confidence

Introduced a new internal event bus mechanism, providing \InternalEventConsumer\ and \InternalEventProducer\ classes that manage event storage via a list. This change establishes the internal infrastructure for handling events within the assimilator module.

assimilator/internal/events · high confidence

The package now displays a welcome banner with documentation and GitHub links upon import. Users can suppress this message by setting the PY\_ASSIMILATOR\_MESSAGE environment variable to 'False' or 'False' in their system or .env file.

assimilator · high confidence

The internal package is now initialized with a registration of internal implementations (InternalRepository, InternalUnitOfWork, and CRUDService) into the pattern registry, making these components available for use within the framework.

assimilator/internal · high confidence

Added a new CRUDService class in the core services module that provides create, update, list, get, and delete operations. The service integrates with the UnitOfWork and Repository patterns, handling transaction management and object persistence through the underlying repository.

assimilator/core/services · high confidence

Added the foundational classes for the event system: \EventBus\, \EventConsumer\, and \EventProducer\ in \events\_bus.py\, an \OutboxRelay\ abstract base class in \outbox\_relay.py\, and specific exception types in \exceptions.py\. These components provide the core interfaces for producing and consuming events, as well as handling outbox patterns.

assimilator/core/events · high confidence

Added the internal in-memory database implementation, including the \InternalRepository\ and \InternalUnitOfWork\ classes. The repository provides in-memory storage for \BaseModel\ entities with support for filtering, saving, updating, and deleting records, while the unit of work manages transactional boundaries for that in-memory session.

assimilator/internal/database · high confidence

Added new Alchemy implementations for database specifications, including \AlchemyFilteringOptions\ and \AlchemyFilter\ to handle field parsing and composite filter operations (AND, OR, NOT). The update also introduces Alchemy-specific specifications for ordering, pagination, joining, and field selection (\only\), enabling users to construct complex database queries with native SQLAlchemy constructs.

assimilator/alchemy/database/specifications · high confidence

Added new files for the SQLAlchemy database layer, including AlchemyRepository, AlchemyUnitOfWork, and AlchemyErrorWrapper. The AlchemyRepository implements database operations (get, filter, update, save, delete, count) using SQLAlchemy, while the AlchemyErrorWrapper maps SQLAlchemy exceptions to internal application errors. The AlchemyUnitOfWork manages database sessions with begin, commit, and rollback capabilities.

assimilator/alchemy/database · medium confidence

The database specifications module has been restructured to support adaptive filtering and standardized query specifications. A new \AdaptiveFilter\ class enables dynamic composition of filter conditions using logical operators (AND/OR), while \FilteringOptions\ provides a pluggable interface for defining comparison operators (e.g., eq, gt, like). The core \specifications.py\ file introduces a \Specification\ base class and a \specification\ decorator for creating query builders (order, paginate, join, only). Additionally, type protocols (\OrderSpecificationProtocol\, etc.) are added to enforce consistent interfaces for these query components.

assimilator/core/database/specifications · high confidence

Added the foundational database layer for the library, including a \BaseModel\ for data models with automatic ID generation and serialization, a generic \Repository\ interface for data access operations (get, filter, save, delete, update, count), and a \UnitOfWork\ for transaction management. The \UnitOfWork\ now supports autocommit modes and wraps transactional methods with an \ErrorWrapper\ for consistent exception handling.

assimilator/core/database · high confidence

Added a new MongoDB implementation for the data access layer, registering MongoRepository, MongoUnitOfWork, and CRUDService as the default providers for the 'mongo' pattern.

assimilator/mongo · high confidence

The \assimilator/core/patterns\ module now includes new \ErrorWrapper\ and \LazyCommand\ patterns. \ErrorWrapper\ provides a context manager and decorator to map and wrap external exceptions into internal application exceptions, while \LazyCommand\ enables deferred execution of commands, allowing results to be cached and accessed later. These patterns are now exported from the \assimilator.core.patterns\ package.

assimilator/core/patterns · high confidence

The alchemy module now requires SQLAlchemy 2.0 or higher. Attempting to use the library with older versions will raise a RuntimeWarning, as support for SQLAlchemy versions below 2.0 has been dropped.

assimilator/alchemy · high confidence

The SQLAlchemy-based database layer has been removed from the codebase. This includes the deletion of the \AlchemyRepository\ and \AlchemyUnitOfWork\ classes, along with the abstract base classes \BaseRepository\ and \Specification\ that defined the previous data access patterns. Users relying on this specific SQLAlchemy implementation will no longer have access to these components.

database · high confidence

The \pattern\_creator.py\ module is added to provide factory functions (\create\_repository\, \create\_uow\, \create\_crud\) that instantiate components using a \get\pattern\ registry, enabling provider-specific implementations. Additionally, core usability files (\\\init\\_.py\, \exceptions.py\) are moved from \database/base\ and \database/alchemy\ to \assimilator/core/usability\, and exception classes are renamed to \PatternNotFoundError\ and \ProviderNotFoundError\ to reflect the new pattern-based architecture.

assimilator/core/usability · medium confidence

Users can now register the Redis implementation under both 'redis' and 'redis\_' provider names, ensuring that the RedisRepository, RedisUnitOfWork, and CRUDService are correctly associated with the Redis pattern. This allows the system to resolve Redis-based components via either provider alias.

assimilator/redis\ · high confidence_

Added an empty \_\init\\_.py file in the tests directory to ensure the tests directory is recognized as a Python package.

tests · high confidence

The project has switched from a traditional setup.py and requirements.txt-based dependency management to a modern pyproject.toml configuration. This change introduces a new build system (hatchling) and updates the dependency specifications, including adding optional dependencies for SQLAlchemy, Kafka, Redis, and MongoDB, while removing the legacy requirements.txt file.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 65 → 66 (+0.7)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 100 (+0.2)
• Architecture 100 → 87 (-13.2)
• Maturity 53 → 55 (+2.8)
• Readiness 60 → 57 (-3.7)
• Security 83 → 98 (+14.2)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• LLM evaluation failed
• No exposed public API
• Test reliability not included
• single-maintainer — knowledge-concentration (bus factor) risk

• Change coupling: repository.py ↔ repository.py (assimilator/alchemy/database/repository.py)
• Dependency hygiene PARTLY measured — Python dependencies read, no exact pin to grade for currency
• Documentation: no usage examples (README.md)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• No dependency advisory monitoring
• Scattered collaborators

• Unchanged — 0 containers · 1 contexts · 0 edges

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

knucklesuganda/py_assimilator was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.