torchsystem 1.2.0__tar.gz → 1.2.2__tar.gz

torchsystem-1.2.2/PKG-INFO

@@ -0,0 +1,414 @@
+Metadata-Version: 2.3
+Name: torchsystem
+Version: 1.2.2
+Summary: A framework for creating message-driven IA systems with PyTorch
+License: MIT
+Author: mr-mapache
+Author-email: eric.m.cardozo@mi.unc.edu.ar
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: mlregistry (>=1.2.1,<2.0.0)
+Description-Content-Type: text/markdown
+
+# TorchSystem.
+
+This framework will help you to create powerful and scalable systems using the PyTorch library. It is designed under the principles of domain driven design (DDD) and includes built-in message patterns and a robust dependency injection system. It enables the creation of stateless, modular service layers and robust domain models. This design facilitates better separation of concerns, testability, and scalability, making it ideal for complex IA training systems. You can find the full documentation here: [mr-mapache.github.io/torch-system/](https://mr-mapache.github.io/torch-system/)
+
+## Table of contents:
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Instalation](#instalation)
+- [Example](#example)
+- [License](#license)
+
+## Introduction
+
+In domain-driven design, an aggregate is a cluster of associated objects that we treat as a unit for the purpose of data changes. It acts as a boundary around its constituent objects, encapsulating their behavior and ensuring that all changes to its state occur through well-defined entry points.
+
+In the context of deep learning, a model not only consists of a neural network but also a set of associated objects that are necessary for the tasks it performs, such as loss functions, tokenizers, etc. This defines an aggregate.
+
+While aggregates are in charge of data, in order to perform actions, we need to define services. Services are stateless operations that fulfill domain-specific tasks. For example, when training a neural network, the model doesn't own the data on which it is trained or how the training is performed. The training process is a stateless operation that resides outside the model and should be defined as a service.
+
+Services may produce data, such as events, metrics, or logs, that are not their responsibility to handle. This introduces the need for a messaging system that allows services to communicate with each other.
+
+With all this in mind, the need for a well-defined framework that defines aggregates and handles service interactions becomes evident. While it is up to the developer to define his domain, this framework provides a set of tools to facilitate it's implementation.
+
+## Instalation
+
+To install the framework, you can use pip:
+
+```bash
+pip install torchsystem
+```
+
+## Features
+
+- **Aggregates**: Define the structure of your domain by grouping related entities and enforcing consistency within their boundaries. They encapsulate both data and behavior, ensuring that all modifications occur through controlled operations.
+
+- **Domain Events**:  Aggregates can produce and consume domain events, which signal meaningful changes in the system or trigger actions elsewhere. Exceptions are supported to be treated as domain events, allowing them to be enqueued and handled or rised as needed. This makes it trivial to implement features like early stopping (Just enqueue an exception and raise it when needed).
+
+- **Dependency Injection**: The framework provides a robust dependency injection system that allows you to define and inject dependencies. This enables you to define your logic in terms of interfaces and inject implementations later. 
+
+- **Registry**: The registry module allows you to treat your models as entities by providing a way to calculate locally unique hashes for them that can act as their identifier. This module also provides several other utilities to help you handle the data from your domain.
+
+- **Compilers**: Building aggregates can be a complex process. In the context of deep learning, aggregates not only need to be built but also compiled, making compilation an integral part of the construction process. This framework provides a Compiler class to help define and manage the compilation process for your aggregates
+
+- **Services**: Define stateless operations that fulfill domain-specific tasks using ubiquitous language. 
+
+- **Producers/Consumers**: Events produced by services can be delivered by producers to several consumers. This allows you to decouple services and define complex interactions between them. 
+
+- **Publisher/Subscriber**: Data also can be delivered with the publisher/subscriber pattern. Publishers can send data to subscribers using a topic-based system.
+
+
+## Example
+
+Let's build a simple training system using the framework. First, we can define our domain with interfaces:
+
+```python 
+# src/domain.py
+from typing import Any
+from typing import Protocol 
+
+from torch import Tensor
+from torch.nn import Module
+from torchsystem import Events
+
+class Model(Protocol):
+    id: Any
+    phase: str
+    epoch: int
+    events: Events # You will find out why we need this later
+    nn: Module
+    criterion: Module
+    optimizer: Module
+    
+    def fit(self, *args, **kwargs) -> Any:...
+
+    def evaluate(self, *args, **kwargs) -> Any:...
+
+class Metric(Protocol):
+    name: str
+    value: Any
+
+class Metrics(Protocol):
+
+    def update(self, *args, **kwargs) -> None:...
+
+    def compute(self) -> Sequence[Metric]:...
+
+class Loader(Protocol):
+
+    def __iter__(self) -> Iterator[tuple[Tensor, Tensor]]:...
+```
+
+Notice that we didn't define any implementation. Of course you can just implement it right away, but let's define a training service first. Service handlers and events produced in the services should be modeled using an ubiquitous language. Under this idea, the framework provides a way to invoke services or produce events using their names. This is completly optional, like everything in the library, and you can invoke services handlers and dispatch events directly.
+
+```python
+# src/services/training.py
+from typing import Sequence
+from dataclasses import dataclass
+
+from torch import inference_mode
+from torchsystem import Depends
+from torchsystem.services import Service
+from torchsystem.services import Producer 
+
+from src.domain import Model
+from src.domain import Loader
+from src.domain import Metric, Metrics 
+
+service = Service() 
+producer = Producer() 
+
+@service.handler
+def iterate(model: Model, loaders: Sequence[tuple[str, Loader]], metrics: Metrics):
+    for phase, loader in loaders:
+        train(model, loader, metrics) if phase == 'train' else validate(model, loader, metrics)
+    service.handle('train', model, loader, metrics) if phase == 'train' else service.handle('validate', model, loader, metrics)
+    model.epoch += 1
+    producer.produce('iterated', model, loaders)
+
+def device() -> str:
+    raise NotImplementedError("We don't know the device yet!!!, will be injected later")
+
+@service.handler
+def train(model: Model, loader: Loader, metrics: Metrics, device: str = Depends(device)):
+    model.phase = 'train'
+    for batch, (input, target) in enumerate(loader, start=1):
+        input, target = input.to(device), target.to(device)
+        prediction, loss = model.fit(input, target)
+        metrics.update(batch, loss, prediction, target)
+    sequence = metrics.compute()
+    producer.produce('trained', model, loader, sequence)
+
+@service.handler
+def validate(model: Model, loader: Loader, metrics: Metrics, device: str = Depends(device)):
+    model.phase = 'evaluation'
+    with inference_mode():
+        for batch, (input, target) in enumerate(loader, start=1):
+            input, target = input.to(device), target.to(device)
+            prediction, loss = model.evaluate(input, target)
+            metrics.update(batch, loss, prediction, target)
+        sequence = metrics.compute()
+        producer.produce('validated', model, loader, sequence)
+
+@producer.event
+class Iterated:
+    model: Model
+    loaders: Sequence[tuple[str, Loader]]
+
+@producer.event
+class Trained:
+    model: Model
+    loader: Loader
+    metrics: Sequence[Metric]
+
+@producer.event
+class Validated:
+    model: Model
+    loader: Loader
+    metrics: Sequence[Metric]
+```
+
+And that's it! A simple training system. Notice that it is completely decoupled from the implementation of the domain. It's only task is to orchestrate the training process and produce events from it. It doesn't provide any storage logic or data manipulation, only stateless training logic. Now you can now build a whole data storage system, logging or any other service you need around this simple service, thanks to the event system.
+
+Let's create a simple tensorboard consumer for this service:
+
+```python
+# src/services/tensorboard.py
+from torchsystem import Depends
+from torchsystem.services import Consumer
+from torch.utils.tensorboard.writer import SummaryWriter
+from trainsys.services.training import (
+    Trained,
+    Validated
+)
+
+consumer = Consumer()
+
+def writer() -> SummaryWriter:
+    raise NotImplementedError("We don't want to handle the writer here!!!, will be injected later in the application layer") 
+
+
+@consumer.handler
+def deliver_metrics(event: Trained | Validated, writer: SummaryWriter = Depends(writer)):
+    for metric in event.metrics:
+        writer.add_scalar(f'{event.model.id}/{metric.name}/{event.model.phase}', metric.value, event.model.epoch)
+
+    # When you pass an Union of types as annotation, the consumer will register the handler for all types in the Union
+    # automatically. This is a good way to handle events that share the same logic.
+```
+
+Since several consumers can consume from the same producer, you can plug any service you want to the training system. The service don't need to know who is consuming the events it produces. This is known a dependency inversion principle. You now build a whole system around this simple training service. All kind of logic can be implemented from here, from weights storage to early stopping. Let's create an early stopping service:
+
+```python
+# src/services/earlystopping.py
+from torchsystem.services import Subscriber
+from torchsystem.services import Consumer
+
+from trainsys.services.training import Metric
+from trainsys.services.training import Trained, Validated
+
+subscriber = Subscriber()
+consumer = Consumer()
+
+@consumer.handler
+def deliver_metrics(event: Trained | Validated):
+    for metric in event.metrics:
+        try:
+            subscriber.receive(metric, metric.name)
+        except StopIteration:
+            event.model.events.enqueue(StopIteration) # Exceptions are also supported as domain events
+                                                      # If you prefer you can create a domain event for this
+                                                      # and enqueue it here.
+@subscriber.subscribe('loss')
+def on_low_loss(metric: Metric):
+    if metric.value < 0.001:
+        raise StopIteration # Built-in exception from Python
+    
+@subscriber.subscribe('accuracy')
+def on_high_accuracy(metric: Metric):
+    if metric.value > 0.995:
+        raise StopIteration # Exceptions are a good way to propagate information backwards in the system.
+```
+
+This is a simple early stopping service. It listens to the metrics produced by the training service and raises a StopIteration exception when the loss is low enough or the accuracy is high enough. This exception is enqueued in the model events and can be raised again when needed, for example within the `onepoch` hook in the aggregate. A `Publisher` could also be used to send the messages to the subscribers but it wasn't necessary in this case.
+
+Now we are going to implement a simple classifier aggregate in order to train a neural network for image classification tasks.
+
+```python
+from torch import argmax
+from torch import Tensor 
+from torch.nn import Module
+from torch.nn import Flatten
+from torch.optim import Optimizer
+from torchsystem.domain import Event
+from torchsystem.domain import Aggregate
+from torchsystem.registry import gethash
+
+class Classifier(Aggregate): 
+    def __init__(self, nn: Module, criterion: Module, optimizer: Optimizer):
+        super().__init__()
+        self.epoch = 0
+        self.nn = nn
+        self.criterion = criterion
+        self.optimizer = optimizer 
+        self.flatten = Flatten()
+
+    @property
+    def id(self) -> str:
+        return gethash(self.nn) # This will return an identifier for the root 
+
+    def forward(self, input: Tensor) -> tuple[Tensor, Tensor]:
+        input = self.flatten(input)
+        return self.nn(input)
+    
+    def loss(self, output: Tensor, target: Tensor) -> Tensor:
+        return self.criterion(output, target)
+    
+    def fit(self, input: Tensor, target: Tensor) -> tuple[Tensor, Tensor]:
+        self.optimizer.zero_grad()
+        output = self(input)
+        loss = self.loss(output, target)
+        loss.backward()
+        self.optimizer.step()
+        return argmax(output, dim=1), loss # returns classification predictions and their loss
+
+    def evaluate(self, input: Tensor, target: Tensor) -> tuple[Tensor, Tensor]:
+        output = self(input)
+        return argmax(output, dim=1), self.loss(output, target)
+    
+    def onepoch(self):
+        # Hook that will be called after the epoch attribute is updated. The aggregate handle this
+        # automatically for epochs and phase.
+        self.events.commit() # This will raise the StopIteration exception when the epoch is over
+```
+
+As you see, aggregates is just a simple facade to encapsulate things you already knew. Aggregates have also the capability to handle domain events or domain exceptions. 
+
+```python
+class SomeDomainEvent(Event):...
+# A simple class can represent a domain event.
+
+class DomainException(Exception):...
+# Exceptions are also supported as domain events.
+# If no handler is found, they will be raised when the event queue is commited.
+
+class DomainEventWithData(Event):
+    # They also can carry data
+    def __init__(self, data: Any):
+        self.data = data
+
+class DomainEventWithIgnoredData(Event):
+    def __init__(self, data: Any):
+        self.data = data
+
+class Classifier(Aggregate): 
+    def __init__(self, nn: Module, criterion: Module, optimizer: Optimizer):
+        super().__init__()        
+        self.events.handlers[SomeDomainEvent] = lambda: print('SomeDomainEvent handled!')
+        self.events.handlers[DomainException] = lambda: print('DomainException handled!')
+        self.events.handlers[DomainEventWithData] = lambda event: print(f'DomainEventWithData handled with data: {event.data}')
+        self.events.handlers[DomainEventWithIgnoredData] = lambda: print(f'DomainEventWithIgnoredData handled')
+        # Usually you need to define the handlers outside the aggregate and pass them in the building process. But
+        # This is an example of how you can handle complex domain logic within the aggregate.
+        ...
+```
+
+The `Classifier` aggregate we just created can be built and compiled in a simple way. However you will find yourself in situations where you need to pick a torch backend, create and clean multiprocessing resources, pickle modules, etc., and you will need a tool to build it an compile it. I will implement a compilation pipeline, just to show you how to use the compiler:
+
+```python
+# src/services/compilation.py
+from logging import getLogger
+from torch.nn import Module
+from torch.optim import Optimizer
+from torchsystem import Depends
+from torchsystem.compiler import compile
+from torchsystem.compiler import Compiler
+from trainsys.domain.models import Repository
+from trainsys.ports.models import Models
+from src.classifier import Classifier
+
+logger = getLogger(__name__)
+compiler = Compiler[Classifier]()
+
+def device() -> str:...
+
+def epoch() -> int:
+    return 10 # Just for the sake of the example
+
+@compiler.step
+def build_classifier(model: Module, criterion: Module, optimizer: Optimizer):
+    logger.info(f'Building Classifier') 
+    return Classifier(model, criterion, optimizer)
+
+@compiler.step
+def move_to_device(classifier: Classifier, device = Depends(device)):
+    logger.info(f'Moving classifier to device: {device}')
+    return classifier.to(device)
+
+@compiler.step
+def compile_classifier(classifier: Classifier):
+    logger.info(f'Compiling classifier')
+    return compile(classifier)
+
+@compiler.step
+def get_current_epoch(classifier: Classifier, epoch: int = Depends(epoch)):
+    # Implement this with some database query or api call. 
+    classifier.epoch = epoch
+    return classifier
+```
+
+Finally, you can put all together in the application layer as follows:
+
+```python
+# src/main.py
+
+from torch import cuda
+from torch.utils.tensorboard.writer import SummaryWriter
+
+from src.service import (
+    training,
+    tensorboard,
+    earlystopping
+)
+
+model = MLP(...)
+criterion = CrossEntropyLoss(...)
+optimizer = Adam(...)
+metrics = Metrics(...)
+loaders = [
+    ('train', DataLoader(...)),
+    ('validation', DataLoader(...))
+]
+
+def device():
+    return 'cuda' if cuda.is_available() else 'cpu'
+
+def summary_writer():
+    writter = SummaryWriter(...)
+    yield writter
+    writter.close()
+
+training.service.dependency_overrides[training.device] = device
+compilation.compiler.dependency_overrides[compilation.device] = device
+tensorboard.consumer.dependency_overrides[tensorboard.writer] = summary_writer
+
+...
+
+classifier = compilation.compiler.compile(model, criterion, optimizer)
+
+training.service.handle('iterate', classifier, loaders, metrics)
+
+...
+```
+
+This is a simple example of how to build a training system using the framework. Since services can be called by their name, you can easily write a REST API with CQS or a CLI interfaces for your training system. The possibilities are endless. 
+
+## License
+
+This project is licensed under the MIT License - Use it as you wish in your projects. 

torchsystem-1.2.2/README.md

@@ -0,0 +1,399 @@
+# TorchSystem.
+
+This framework will help you to create powerful and scalable systems using the PyTorch library. It is designed under the principles of domain driven design (DDD) and includes built-in message patterns and a robust dependency injection system. It enables the creation of stateless, modular service layers and robust domain models. This design facilitates better separation of concerns, testability, and scalability, making it ideal for complex IA training systems. You can find the full documentation here: [mr-mapache.github.io/torch-system/](https://mr-mapache.github.io/torch-system/)
+
+## Table of contents:
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Instalation](#instalation)
+- [Example](#example)
+- [License](#license)
+
+## Introduction
+
+In domain-driven design, an aggregate is a cluster of associated objects that we treat as a unit for the purpose of data changes. It acts as a boundary around its constituent objects, encapsulating their behavior and ensuring that all changes to its state occur through well-defined entry points.
+
+In the context of deep learning, a model not only consists of a neural network but also a set of associated objects that are necessary for the tasks it performs, such as loss functions, tokenizers, etc. This defines an aggregate.
+
+While aggregates are in charge of data, in order to perform actions, we need to define services. Services are stateless operations that fulfill domain-specific tasks. For example, when training a neural network, the model doesn't own the data on which it is trained or how the training is performed. The training process is a stateless operation that resides outside the model and should be defined as a service.
+
+Services may produce data, such as events, metrics, or logs, that are not their responsibility to handle. This introduces the need for a messaging system that allows services to communicate with each other.
+
+With all this in mind, the need for a well-defined framework that defines aggregates and handles service interactions becomes evident. While it is up to the developer to define his domain, this framework provides a set of tools to facilitate it's implementation.
+
+## Instalation
+
+To install the framework, you can use pip:
+
+```bash
+pip install torchsystem
+```
+
+## Features
+
+- **Aggregates**: Define the structure of your domain by grouping related entities and enforcing consistency within their boundaries. They encapsulate both data and behavior, ensuring that all modifications occur through controlled operations.
+
+- **Domain Events**:  Aggregates can produce and consume domain events, which signal meaningful changes in the system or trigger actions elsewhere. Exceptions are supported to be treated as domain events, allowing them to be enqueued and handled or rised as needed. This makes it trivial to implement features like early stopping (Just enqueue an exception and raise it when needed).
+
+- **Dependency Injection**: The framework provides a robust dependency injection system that allows you to define and inject dependencies. This enables you to define your logic in terms of interfaces and inject implementations later. 
+
+- **Registry**: The registry module allows you to treat your models as entities by providing a way to calculate locally unique hashes for them that can act as their identifier. This module also provides several other utilities to help you handle the data from your domain.
+
+- **Compilers**: Building aggregates can be a complex process. In the context of deep learning, aggregates not only need to be built but also compiled, making compilation an integral part of the construction process. This framework provides a Compiler class to help define and manage the compilation process for your aggregates
+
+- **Services**: Define stateless operations that fulfill domain-specific tasks using ubiquitous language. 
+
+- **Producers/Consumers**: Events produced by services can be delivered by producers to several consumers. This allows you to decouple services and define complex interactions between them. 
+
+- **Publisher/Subscriber**: Data also can be delivered with the publisher/subscriber pattern. Publishers can send data to subscribers using a topic-based system.
+
+
+## Example
+
+Let's build a simple training system using the framework. First, we can define our domain with interfaces:
+
+```python 
+# src/domain.py
+from typing import Any
+from typing import Protocol 
+
+from torch import Tensor
+from torch.nn import Module
+from torchsystem import Events
+
+class Model(Protocol):
+    id: Any
+    phase: str
+    epoch: int
+    events: Events # You will find out why we need this later
+    nn: Module
+    criterion: Module
+    optimizer: Module
+    
+    def fit(self, *args, **kwargs) -> Any:...
+
+    def evaluate(self, *args, **kwargs) -> Any:...
+
+class Metric(Protocol):
+    name: str
+    value: Any
+
+class Metrics(Protocol):
+
+    def update(self, *args, **kwargs) -> None:...
+
+    def compute(self) -> Sequence[Metric]:...
+
+class Loader(Protocol):
+
+    def __iter__(self) -> Iterator[tuple[Tensor, Tensor]]:...
+```
+
+Notice that we didn't define any implementation. Of course you can just implement it right away, but let's define a training service first. Service handlers and events produced in the services should be modeled using an ubiquitous language. Under this idea, the framework provides a way to invoke services or produce events using their names. This is completly optional, like everything in the library, and you can invoke services handlers and dispatch events directly.
+
+```python
+# src/services/training.py
+from typing import Sequence
+from dataclasses import dataclass
+
+from torch import inference_mode
+from torchsystem import Depends
+from torchsystem.services import Service
+from torchsystem.services import Producer 
+
+from src.domain import Model
+from src.domain import Loader
+from src.domain import Metric, Metrics 
+
+service = Service() 
+producer = Producer() 
+
+@service.handler
+def iterate(model: Model, loaders: Sequence[tuple[str, Loader]], metrics: Metrics):
+    for phase, loader in loaders:
+        train(model, loader, metrics) if phase == 'train' else validate(model, loader, metrics)
+    service.handle('train', model, loader, metrics) if phase == 'train' else service.handle('validate', model, loader, metrics)
+    model.epoch += 1
+    producer.produce('iterated', model, loaders)
+
+def device() -> str:
+    raise NotImplementedError("We don't know the device yet!!!, will be injected later")
+
+@service.handler
+def train(model: Model, loader: Loader, metrics: Metrics, device: str = Depends(device)):
+    model.phase = 'train'
+    for batch, (input, target) in enumerate(loader, start=1):
+        input, target = input.to(device), target.to(device)
+        prediction, loss = model.fit(input, target)
+        metrics.update(batch, loss, prediction, target)
+    sequence = metrics.compute()
+    producer.produce('trained', model, loader, sequence)
+
+@service.handler
+def validate(model: Model, loader: Loader, metrics: Metrics, device: str = Depends(device)):
+    model.phase = 'evaluation'
+    with inference_mode():
+        for batch, (input, target) in enumerate(loader, start=1):
+            input, target = input.to(device), target.to(device)
+            prediction, loss = model.evaluate(input, target)
+            metrics.update(batch, loss, prediction, target)
+        sequence = metrics.compute()
+        producer.produce('validated', model, loader, sequence)
+
+@producer.event
+class Iterated:
+    model: Model
+    loaders: Sequence[tuple[str, Loader]]
+
+@producer.event
+class Trained:
+    model: Model
+    loader: Loader
+    metrics: Sequence[Metric]
+
+@producer.event
+class Validated:
+    model: Model
+    loader: Loader
+    metrics: Sequence[Metric]
+```
+
+And that's it! A simple training system. Notice that it is completely decoupled from the implementation of the domain. It's only task is to orchestrate the training process and produce events from it. It doesn't provide any storage logic or data manipulation, only stateless training logic. Now you can now build a whole data storage system, logging or any other service you need around this simple service, thanks to the event system.
+
+Let's create a simple tensorboard consumer for this service:
+
+```python
+# src/services/tensorboard.py
+from torchsystem import Depends
+from torchsystem.services import Consumer
+from torch.utils.tensorboard.writer import SummaryWriter
+from trainsys.services.training import (
+    Trained,
+    Validated
+)
+
+consumer = Consumer()
+
+def writer() -> SummaryWriter:
+    raise NotImplementedError("We don't want to handle the writer here!!!, will be injected later in the application layer") 
+
+
+@consumer.handler
+def deliver_metrics(event: Trained | Validated, writer: SummaryWriter = Depends(writer)):
+    for metric in event.metrics:
+        writer.add_scalar(f'{event.model.id}/{metric.name}/{event.model.phase}', metric.value, event.model.epoch)
+
+    # When you pass an Union of types as annotation, the consumer will register the handler for all types in the Union
+    # automatically. This is a good way to handle events that share the same logic.
+```
+
+Since several consumers can consume from the same producer, you can plug any service you want to the training system. The service don't need to know who is consuming the events it produces. This is known a dependency inversion principle. You now build a whole system around this simple training service. All kind of logic can be implemented from here, from weights storage to early stopping. Let's create an early stopping service:
+
+```python
+# src/services/earlystopping.py
+from torchsystem.services import Subscriber
+from torchsystem.services import Consumer
+
+from trainsys.services.training import Metric
+from trainsys.services.training import Trained, Validated
+
+subscriber = Subscriber()
+consumer = Consumer()
+
+@consumer.handler
+def deliver_metrics(event: Trained | Validated):
+    for metric in event.metrics:
+        try:
+            subscriber.receive(metric, metric.name)
+        except StopIteration:
+            event.model.events.enqueue(StopIteration) # Exceptions are also supported as domain events
+                                                      # If you prefer you can create a domain event for this
+                                                      # and enqueue it here.
+@subscriber.subscribe('loss')
+def on_low_loss(metric: Metric):
+    if metric.value < 0.001:
+        raise StopIteration # Built-in exception from Python
+    
+@subscriber.subscribe('accuracy')
+def on_high_accuracy(metric: Metric):
+    if metric.value > 0.995:
+        raise StopIteration # Exceptions are a good way to propagate information backwards in the system.
+```
+
+This is a simple early stopping service. It listens to the metrics produced by the training service and raises a StopIteration exception when the loss is low enough or the accuracy is high enough. This exception is enqueued in the model events and can be raised again when needed, for example within the `onepoch` hook in the aggregate. A `Publisher` could also be used to send the messages to the subscribers but it wasn't necessary in this case.
+
+Now we are going to implement a simple classifier aggregate in order to train a neural network for image classification tasks.
+
+```python
+from torch import argmax
+from torch import Tensor 
+from torch.nn import Module
+from torch.nn import Flatten
+from torch.optim import Optimizer
+from torchsystem.domain import Event
+from torchsystem.domain import Aggregate
+from torchsystem.registry import gethash
+
+class Classifier(Aggregate): 
+    def __init__(self, nn: Module, criterion: Module, optimizer: Optimizer):
+        super().__init__()
+        self.epoch = 0
+        self.nn = nn
+        self.criterion = criterion
+        self.optimizer = optimizer 
+        self.flatten = Flatten()
+
+    @property
+    def id(self) -> str:
+        return gethash(self.nn) # This will return an identifier for the root 
+
+    def forward(self, input: Tensor) -> tuple[Tensor, Tensor]:
+        input = self.flatten(input)
+        return self.nn(input)
+    
+    def loss(self, output: Tensor, target: Tensor) -> Tensor:
+        return self.criterion(output, target)
+    
+    def fit(self, input: Tensor, target: Tensor) -> tuple[Tensor, Tensor]:
+        self.optimizer.zero_grad()
+        output = self(input)
+        loss = self.loss(output, target)
+        loss.backward()
+        self.optimizer.step()
+        return argmax(output, dim=1), loss # returns classification predictions and their loss
+
+    def evaluate(self, input: Tensor, target: Tensor) -> tuple[Tensor, Tensor]:
+        output = self(input)
+        return argmax(output, dim=1), self.loss(output, target)
+    
+    def onepoch(self):
+        # Hook that will be called after the epoch attribute is updated. The aggregate handle this
+        # automatically for epochs and phase.
+        self.events.commit() # This will raise the StopIteration exception when the epoch is over
+```
+
+As you see, aggregates is just a simple facade to encapsulate things you already knew. Aggregates have also the capability to handle domain events or domain exceptions. 
+
+```python
+class SomeDomainEvent(Event):...
+# A simple class can represent a domain event.
+
+class DomainException(Exception):...
+# Exceptions are also supported as domain events.
+# If no handler is found, they will be raised when the event queue is commited.
+
+class DomainEventWithData(Event):
+    # They also can carry data
+    def __init__(self, data: Any):
+        self.data = data
+
+class DomainEventWithIgnoredData(Event):
+    def __init__(self, data: Any):
+        self.data = data
+
+class Classifier(Aggregate): 
+    def __init__(self, nn: Module, criterion: Module, optimizer: Optimizer):
+        super().__init__()        
+        self.events.handlers[SomeDomainEvent] = lambda: print('SomeDomainEvent handled!')
+        self.events.handlers[DomainException] = lambda: print('DomainException handled!')
+        self.events.handlers[DomainEventWithData] = lambda event: print(f'DomainEventWithData handled with data: {event.data}')
+        self.events.handlers[DomainEventWithIgnoredData] = lambda: print(f'DomainEventWithIgnoredData handled')
+        # Usually you need to define the handlers outside the aggregate and pass them in the building process. But
+        # This is an example of how you can handle complex domain logic within the aggregate.
+        ...
+```
+
+The `Classifier` aggregate we just created can be built and compiled in a simple way. However you will find yourself in situations where you need to pick a torch backend, create and clean multiprocessing resources, pickle modules, etc., and you will need a tool to build it an compile it. I will implement a compilation pipeline, just to show you how to use the compiler:
+
+```python
+# src/services/compilation.py
+from logging import getLogger
+from torch.nn import Module
+from torch.optim import Optimizer
+from torchsystem import Depends
+from torchsystem.compiler import compile
+from torchsystem.compiler import Compiler
+from trainsys.domain.models import Repository
+from trainsys.ports.models import Models
+from src.classifier import Classifier
+
+logger = getLogger(__name__)
+compiler = Compiler[Classifier]()
+
+def device() -> str:...
+
+def epoch() -> int:
+    return 10 # Just for the sake of the example
+
+@compiler.step
+def build_classifier(model: Module, criterion: Module, optimizer: Optimizer):
+    logger.info(f'Building Classifier') 
+    return Classifier(model, criterion, optimizer)
+
+@compiler.step
+def move_to_device(classifier: Classifier, device = Depends(device)):
+    logger.info(f'Moving classifier to device: {device}')
+    return classifier.to(device)
+
+@compiler.step
+def compile_classifier(classifier: Classifier):
+    logger.info(f'Compiling classifier')
+    return compile(classifier)
+
+@compiler.step
+def get_current_epoch(classifier: Classifier, epoch: int = Depends(epoch)):
+    # Implement this with some database query or api call. 
+    classifier.epoch = epoch
+    return classifier
+```
+
+Finally, you can put all together in the application layer as follows:
+
+```python
+# src/main.py
+
+from torch import cuda
+from torch.utils.tensorboard.writer import SummaryWriter
+
+from src.service import (
+    training,
+    tensorboard,
+    earlystopping
+)
+
+model = MLP(...)
+criterion = CrossEntropyLoss(...)
+optimizer = Adam(...)
+metrics = Metrics(...)
+loaders = [
+    ('train', DataLoader(...)),
+    ('validation', DataLoader(...))
+]
+
+def device():
+    return 'cuda' if cuda.is_available() else 'cpu'
+
+def summary_writer():
+    writter = SummaryWriter(...)
+    yield writter
+    writter.close()
+
+training.service.dependency_overrides[training.device] = device
+compilation.compiler.dependency_overrides[compilation.device] = device
+tensorboard.consumer.dependency_overrides[tensorboard.writer] = summary_writer
+
+...
+
+classifier = compilation.compiler.compile(model, criterion, optimizer)
+
+training.service.handle('iterate', classifier, loaders, metrics)
+
+...
+```
+
+This is a simple example of how to build a training system using the framework. Since services can be called by their name, you can easily write a REST API with CQS or a CLI interfaces for your training system. The possibilities are endless. 
+
+## License
+
+This project is licensed under the MIT License - Use it as you wish in your projects. 

{torchsystem-1.2.0 → torchsystem-1.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "torchsystem"
-version = "1.2.0"
+version = "1.2.2"
 description = "A framework for creating message-driven IA systems with PyTorch"
 authors = ["mr-mapache <eric.m.cardozo@mi.unc.edu.ar>"]
 license = "MIT"

{torchsystem-1.2.0 → torchsystem-1.2.2}/torchsystem/compiler.py

@@ -8,15 +8,14 @@ from torchsystem.depends import Provider
 
 class Compiler[T]:
     """
-    AGGREGATES usually have a complex initialization and are built from multiple components. Sometimes
-    database queries, API calls, or other external resources are required to build it. Each one with it's
-    own lifecycle tath may require some initialization method or cleanup after they are no longer needed.
+    Sometimes AGGREGATES may require complex initialization and be built from multiple sources, like database
+    queries, API calls, or other external resources are required to build it. Each one with it's own lifecycle
+    that may require some initialization method or cleanup after they are no longer needed.
      
     In the context of neural networks, AGGREGATES not only should be built but also compiled. Compilation
     is the process of converting a high-level neural network model into a low-level representation that can
     be executed on a specific hardware platform, and can be seen as an integral part of the process of building 
-    the AGGREGATE. This process get even more complex when performing distributed training and
-    a dedicated pipeline is required to build and compile AGGREGATES.
+    the AGGREGATE. This process get even more complex when performing distributed training. 
 
     A `Compiler` is a class that compiles a pipeline of functions to be executed in sequence in order
     to build an a low-level representation of the AGGREGATE. Since some compilation steps sometimes

{torchsystem-1.2.0 → torchsystem-1.2.2}/torchsystem/services/prodcon.py

@@ -2,7 +2,9 @@ from re import sub
 from typing import Callable
 from typing import Any
 from typing import Union
+from typing import overload
 from inspect import signature
+from dataclasses import dataclass
 
 from torchsystem.depends import inject, Provider
 from torchsystem.depends import Depends as Depends
@@ -18,6 +20,10 @@ class Consumer:
     for deciding which handlers to invoke based on the type of the message it consumes. The message type should
     describe the ocurrence in past tense as DDD suggests when modeling events.
 
+    The EVENTS should be modeled with UBIQUITOUS LANGUAGE. This means that the names of the events should reflect
+    the domain ocurrences that the consumer is responsible for. Keep this in mind when naming the events that will
+    be consumed by the consumer. The consumer maps it's handlers to keys generated by the EVENT's name.
+
     Methods:
         register:
             Registers a message type and its corresponding handler function.
@@ -61,8 +67,8 @@ class Consumer:
         self, 
         name: str = None,
         *,
-        generator: Callable[[str], str] = lambda name: sub(r'(?<!^)(?=[A-Z])', '-', name).lower(),
-        provider: Provider = None
+        provider: Provider = None,
+        generator: Callable[[str], str] = lambda name: sub(r'(?<!^)(?=[A-Z])', '-', name).lower()
     ):
         self.name = name
         self.handlers = dict[str, list[Callable[[Any], None]]]()
@@ -161,15 +167,13 @@ class Producer:
         from torchsystem.services import Consumer
         from torchsystem.services import Producer
 
-        class Event:...
-
         @dataclass
-        class ModelTrained(Event):
+        class ModelTrained:
             model: Callable
             metrics: Sequence
 
         @dataclass
-        class ModelEvaluated(Event):
+        class ModelEvaluated:
             model: Callable
             metrics: Sequence
 
@@ -178,10 +182,25 @@ class Producer:
         producer = Producer()
         producer.register(consumer)
         producer.dispatch(ModelTrained(model, [{'name': 'loss', 'value': 0.1}, {'name': 'accuracy', 'value': 0.9}]))     
+
+        # Events can also be produced and dispatched by the produce method.
+
+        @producer.event
+        class ModelIterated:
+            model: Callable
+            metrics: Sequence
+
+        producer.produce('model-iterated', model, [{'name': 'loss', 'value': 0.1}, {'name': 'accuracy', 'value': 0.9}])
         ```
     """
-    def __init__(self):
+    def __init__(
+        self,
+        *,
+        generator: Callable[[str], str] = lambda name: sub(r'(?<!^)(?=[A-Z])', '-', name).lower()
+    ):
         self.consumers = list[Consumer]()
+        self.types = dict[str, str]()
+        self.generator = generator
 
     def register(self, *consumers: Consumer):
         """
@@ -200,4 +219,44 @@ class Producer:
             message (Any): The event to dispatch.
         """
         for consumer in self.consumers:
-            consumer.consume(message)
+            consumer.consume(message)
+
+    def event(self, cls: type):
+        """
+        Decorator for registering an event type. The event type is registered with the name of the class as the key.
+
+        Args:
+            cls (type): The event class to be registered.
+
+        Returns:
+            type: The event class.
+        """
+        key = self.generator(cls.__name__)
+        self.types[key] = dataclass(cls)
+        return dataclass(cls)
+    
+    @overload
+    def produce(self, event_type: str, *args, **kwargs):
+        ...
+
+    @overload
+    def produce(self, event_type: type, *args, **kwargs):
+        ...
+
+    def produce(self, event_type: str | type, *args, **kwargs):
+        """
+        Produces an event by instantiating the event class and dispatching it to all registered consumers.
+
+        Args:
+            event_type (str | type): The event type to produce.
+            *args: The event class arguments.
+            **kwargs: The event class keyword arguments.
+        """
+        if isinstance(event_type, str):
+            event_type = self.types.get(event_type, None)
+            if event_type is None:
+                raise ValueError(f'Event of type {event_type} is not registered.')
+            self.dispatch(event_type(*args, **kwargs))
+
+        elif isinstance(event_type, type):
+            self.dispatch(event_type(*args, **kwargs))

{torchsystem-1.2.0 → torchsystem-1.2.2}/torchsystem/services/service.py

@@ -13,6 +13,17 @@ class Service:
     The `Service` serves as an entry point for the service layer and provides a simple way to
     build stateless logic for executing domain operations.
 
+    A SERVICE should be modeled with UBIQUITOUS LANGUAGE. This means that the names of handler
+    functions should reflect the domain operations that the service is responsible for. Keep
+    this in mind when naming the functions that will be registered as handlers, since the `Service`
+    class provides a method to call the handlers by their registered name. This is useful for example 
+    when building REST APIs with Command Query Segregation (CQS) and you want to invoke a handler based
+    on the action they perfom (aka. The handler's name).
+
+    A naming generator can be provided to the `Service` constructor in order to customize the function names
+    to the ubiquitous language of the domain. The default generator transforms the function name from snake_case
+    to kebab-case.
+
     Methods:
         register:
             Registers a handler for a specific command or query type. Handles nested or generic annotations.
@@ -46,8 +57,8 @@ class Service:
         self, 
         name: str = None,
         *,
-        generator: Callable[[str], str] = lambda name: sub(r'_', '-', name),
-        provider: Provider = None
+        provider: Provider = None,
+        generator: Callable[[str], str] = lambda name: sub(r'_', '-', name)
     ):
         self.name = name
         self.handlers = dict[str, Callable[..., Any]]()
@@ -57,7 +68,7 @@ class Service:
     @property
     def dependency_overrides(self) -> dict:
         """
-        Returns the dependency overrides for the service. This is useful for late binding,
+        An entry point for overriding the dependencies for the service. This is useful for late binding,
         testing and changing the behavior of the service in runtime.
 
         Returns:
@@ -110,16 +121,16 @@ class Service:
             service = Service()
 
             @service.handler
-            def train(model: Model, data: DataLoader, device: str = Depends(device)):
+            def train_model(model: Model, data: DataLoader, device: str = Depends(device)):
                 # Your training logic here
                 ...
 
             model = Model()
             data = Data()
 
-            service.handle('train', model, data) # train(model, data) will also work
-                                                 # but this is usefull when building REST APIs
-                                                 # with Command Query Segregation (CQS)
+            service.handle('train-model', model, data) # train(model, data) will also work
+                                                       # but this is usefull when building REST APIs
+                                                       # with Command Query Segregation (CQS)
             ```
         """
         handler = self.handlers.get(action, None)

torchsystem-1.2.0/PKG-INFO

@@ -1,19 +0,0 @@
-Metadata-Version: 2.3
-Name: torchsystem
-Version: 1.2.0
-Summary: A framework for creating message-driven IA systems with PyTorch
-License: MIT
-Author: mr-mapache
-Author-email: eric.m.cardozo@mi.unc.edu.ar
-Requires-Python: >=3.12,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: mlregistry (>=1.2.1,<2.0.0)
-Description-Content-Type: text/markdown
-
-# TorchSystem
-An IA training system based on event driven programming, unit of work pattern, pubsub and domain driven desing.
-
-Rebuilding!!! stay tuned.

torchsystem-1.2.0/README.md

@@ -1,4 +0,0 @@
-# TorchSystem
-An IA training system based on event driven programming, unit of work pattern, pubsub and domain driven desing.
-
-Rebuilding!!! stay tuned.