abstract-block-dumper 0.0.1__py3-none-any.whl → 0.0.4__py3-none-any.whl

abstract_block_dumper/{dal → _internal/dal}/django_dal.py

@@ -6,8 +6,8 @@ from django.db import transaction
 from django.db.models.query import QuerySet
 from django.utils import timezone
 
+import abstract_block_dumper._internal.services.utils as abd_utils
 import abstract_block_dumper.models as abd_models
-import abstract_block_dumper.services.utils as abd_utils
 
 
 def get_ready_to_retry_attempts() -> QuerySet[abd_models.TaskAttempt]:
@@ -76,7 +76,7 @@ def task_mark_as_success(task: abd_models.TaskAttempt, result_data: dict) -> Non
     task.save()
 
 
-def task_mark_as_failed(task) -> None:
+def task_mark_as_failed(task: abd_models.TaskAttempt) -> None:
     DEFAULT_BLOCK_TASK_RETRY_BACKOFF = 1
     MAX_RETRY_DELAY_MINUTES = 1440  # 24 hours max delay
 
@@ -98,7 +98,7 @@ def task_mark_as_failed(task) -> None:
     task.save()
 
 
-def task_schedule_to_retry(task):
+def task_schedule_to_retry(task: abd_models.TaskAttempt) -> None:
     task.status = abd_models.TaskAttempt.Status.PENDING
     task.save()
 
@@ -110,6 +110,7 @@ def task_create_or_get_pending(
 ) -> tuple[abd_models.TaskAttempt, bool]:
     """
     Create or get a pending task attempt.
+
     Returns (task, created) where created indicates if a new task was created.
 
     For failed tasks that can retry:

abstract_block_dumper/{dal → _internal/dal}/memory_registry.py

@@ -6,7 +6,7 @@ from typing import Any
 import structlog
 from celery import Task
 
-from abstract_block_dumper.exceptions import ConditionEvaluationError
+from abstract_block_dumper._internal.exceptions import ConditionEvaluationError
 
 logger = structlog.getLogger(__name__)
 
@@ -19,10 +19,8 @@ class RegistryItem:
     backfilling_lookback: int | None = None
     celery_kwargs: dict[str, Any] = field(default_factory=dict)
 
-    def match_condition(self, block_number: int, **kwargs) -> bool:
-        """
-        Check if condition matches for given block and arguments
-        """
+    def match_condition(self, block_number: int, **kwargs: dict[str, Any]) -> bool:
+        """Check if condition matches for given block and arguments."""
         try:
             return self.condition(block_number, **kwargs)
         except Exception as e:
@@ -32,28 +30,23 @@ class RegistryItem:
                 block_number=block_number,
                 exc_info=True,
             )
-            raise ConditionEvaluationError(f"Failed to evaluate condition: {e}") from e
+            msg = f"Failed to evaluate condition: {e}"
+            raise ConditionEvaluationError(msg) from e
 
     def get_execution_args(self) -> list[dict[str, Any]]:
-        """
-        Get list of argument sets for execution
-        """
+        """Get list of argument sets for execution."""
         return self.args or [{}]
 
     @property
     def executable_path(self) -> str:
-        """
-        Get the importable path to the function.
-        """
+        """Get the importable path to the function."""
         if hasattr(self.function, "name") and self.function.name is not None:
             return self.function.name
 
-        return ".".join([self.function.__module__, self.function.__name__])
+        return f"{self.function.__module__}.{self.function.__name__}"
 
     def requires_backfilling(self) -> bool:
-        """
-        Check if this item requires backfilling.
-        """
+        """Check if this item requires backfilling."""
         return self.backfilling_lookback is not None
 
 
@@ -84,7 +77,7 @@ class MemoryRegistry(BaseRegistry):
             "Registered function",
             function_name=item.function.__name__,
             executable_path=item.executable_path,
-            args=item.args,
+            args_counter=len(item.args or []),
             backfilling_lookback=item.backfilling_lookback,
         )
 
@@ -94,12 +87,11 @@ class MemoryRegistry(BaseRegistry):
     def clear(self) -> None:
         self._functions = []
 
-    def get_by_executable_path(self, executable_path: str) -> RegistryItem:
+    def get_by_executable_path(self, executable_path: str) -> RegistryItem | None:
         for registry_item in self.get_functions():
             if registry_item.executable_path == executable_path:
                 return registry_item
-        # TODO: Improve this
-        raise Exception("Function Not Found")
+        return None
 
 
 task_registry = MemoryRegistry()

abstract_block_dumper/{discovery.py → _internal/discovery.py}

@@ -11,7 +11,7 @@ def ensure_modules_loaded() -> None:
 
     @block_task must be loaded, otherwise it won't be registered.
     """
-    from django.apps import apps
+    from django.apps import apps  # noqa: PLC0415
 
     for app_config in apps.get_app_configs():
         for module_suffix in ["tasks", "block_tasks"]:

abstract_block_dumper/{exceptions.py → _internal/exceptions.py}

@@ -10,7 +10,7 @@ class ConditionEvaluationError(AbstractBlockDumperError):
     pass
 
 
-class CeleryTaskLocked(Exception):
+class CeleryTaskLockedError(AbstractBlockDumperError):
     """Celery task execution is locked"""
 
     pass

abstract_block_dumper/{services → _internal/services}/block_processor.py

@@ -1,12 +1,12 @@
 import structlog
 from django.db import transaction
 
-import abstract_block_dumper.dal.django_dal as abd_dal
-from abstract_block_dumper.dal.memory_registry import BaseRegistry, RegistryItem, task_registry
-from abstract_block_dumper.exceptions import ConditionEvaluationError
+import abstract_block_dumper._internal.dal.django_dal as abd_dal
+from abstract_block_dumper._internal.dal.memory_registry import BaseRegistry, RegistryItem, task_registry
+from abstract_block_dumper._internal.exceptions import ConditionEvaluationError
+from abstract_block_dumper._internal.services.executor import CeleryExecutor
+from abstract_block_dumper._internal.services.utils import serialize_args
 from abstract_block_dumper.models import TaskAttempt
-from abstract_block_dumper.services.executor import CeleryExecutor
-from abstract_block_dumper.services.utils import serialize_args
 
 logger = structlog.get_logger(__name__)
 
@@ -100,22 +100,22 @@ class BlockProcessor:
         This handles tasks that may have been lost due to scheduler restarts.
         """
         retry_count = 0
-        for task_attempt in abd_dal.get_ready_to_retry_attempts():
+        for retry_attempt in abd_dal.get_ready_to_retry_attempts():
             try:
                 # Find the registry item to get celery_kwargs
-                registry_item = self.registry.get_by_executable_path(task_attempt.executable_path)
+                registry_item = self.registry.get_by_executable_path(retry_attempt.executable_path)
                 if not registry_item:
                     logger.warning(
                         "Registry item not found for failed task, skipping retry recovery",
-                        task_id=task_attempt.id,
-                        executable_path=task_attempt.executable_path,
+                        task_id=retry_attempt.id,
+                        executable_path=retry_attempt.executable_path,
                     )
                     continue
 
                 # Use atomic transaction to prevent race conditions
                 with transaction.atomic():
                     # Re-fetch with select_for_update to prevent concurrent modifications
-                    task_attempt = TaskAttempt.objects.select_for_update(nowait=True).get(id=task_attempt.id)
+                    task_attempt = TaskAttempt.objects.select_for_update(nowait=True).get(id=retry_attempt.id)
 
                     # Verify task is still in FAILED state and ready for retry
                     if task_attempt.status == TaskAttempt.Status.SUCCESS:
@@ -150,16 +150,16 @@ class BlockProcessor:
             except Exception:
                 logger.error(
                     "Failed to recover retry",
-                    task_id=task_attempt.id,
+                    task_id=retry_attempt.id,
                     exc_info=True,
                 )
                 # Reload task to see current state after potential execution failure
                 try:
-                    task_attempt.refresh_from_db()
+                    retry_attempt.refresh_from_db()
                     # If task is still PENDING after error, revert to FAILED
                     # (execution may have failed before celery task could mark it)
-                    if task_attempt.status == TaskAttempt.Status.PENDING:
-                        abd_dal.revert_to_failed(task_attempt)
+                    if retry_attempt.status == TaskAttempt.Status.PENDING:
+                        abd_dal.revert_to_failed(retry_attempt)
                 except TaskAttempt.DoesNotExist:
                     # Task was deleted during recovery, nothing to revert
                     pass
@@ -170,6 +170,7 @@ class BlockProcessor:
     def _cleanup_phantom_tasks(self) -> None:
         """
         Clean up tasks marked as SUCCESS but never actually started.
+
         Only removes tasks that were created recently (within last hour) to avoid
         deleting legitimate tasks marked as success by external processes.
         """

abstract_block_dumper/{services → _internal/services}/executor.py

@@ -2,8 +2,8 @@ from typing import Any
 
 import structlog
 
-import abstract_block_dumper.dal.django_dal as abd_dal
-from abstract_block_dumper.dal.memory_registry import RegistryItem
+import abstract_block_dumper._internal.dal.django_dal as abd_dal
+from abstract_block_dumper._internal.dal.memory_registry import RegistryItem
 from abstract_block_dumper.models import TaskAttempt
 
 logger = structlog.get_logger(__name__)

abstract_block_dumper/{services → _internal/services}/scheduler.py

@@ -4,9 +4,9 @@ import bittensor as bt
 import structlog
 from django.conf import settings
 
-import abstract_block_dumper.dal.django_dal as abd_dal
-import abstract_block_dumper.services.utils as abd_utils
-from abstract_block_dumper.services.block_processor import BlockProcessor, block_processor_factory
+import abstract_block_dumper._internal.dal.django_dal as abd_dal
+import abstract_block_dumper._internal.services.utils as abd_utils
+from abstract_block_dumper._internal.services.block_processor import BlockProcessor, block_processor_factory
 
 logger = structlog.get_logger(__name__)
 
@@ -61,18 +61,20 @@ class TaskScheduler:
         logger.info("TaskScheduler stopped.")
 
     def initialize_last_block(self) -> None:
-        start_from_block_setting = getattr(settings, "BLOCK_DUMPER_START_FROM_BLOCK")
+        # Safe getattr in case setting is not defined
+        start_from_block_setting = getattr(settings, "BLOCK_DUMPER_START_FROM_BLOCK", None)
 
         if start_from_block_setting is not None:
             if start_from_block_setting == "current":
                 self.last_processed_block = self.subtensor.get_current_block()
-                logger.info(f"Starting from current blockchain block {self.last_processed_block}")
+                logger.info("Starting from current blockchain block", block_number=self.last_processed_block)
 
             elif isinstance(start_from_block_setting, int):
                 self.last_processed_block = start_from_block_setting
-                logger.info(f"Starting from configured block {self.last_processed_block}")
+                logger.info("Starting from configured block", block_number=self.last_processed_block)
             else:
-                raise ValueError(f"Invalid BLOCK_DUMPER_START_FROM_BLOCK value: {start_from_block_setting}")
+                error_msg = f"Invalid BLOCK_DUMPER_START_FROM_BLOCK value: {start_from_block_setting}"
+                raise ValueError(error_msg)
         else:
             # Default behavior - resume from database
             last_block_number = abd_dal.get_the_latest_executed_block_number()

abstract_block_dumper/{services → _internal/services}/utils.py

@@ -20,14 +20,12 @@ def get_bittensor_client() -> bt.Subtensor:
     """
     DEFAULT_BITTENSOR_NETWORK = "finney"
     network = getattr(settings, "BITTENSOR_NETWORK", DEFAULT_BITTENSOR_NETWORK)
-    logger.info(f"Creating new bittensor client for network: {network}")
+    logger.info("Creating new bittensor client for network", network=network)
     return bt.subtensor(network=network)
 
 
 def get_current_celery_task_id() -> str:
-    """
-    Get current celery task id
-    """
+    """Get current celery task id."""
     try:
         celery_task_id = current_task.id
     except Exception:
@@ -36,9 +34,7 @@ def get_current_celery_task_id() -> str:
 
 
 def get_executable_path(func: Callable) -> str:
-    """
-    Get executable path for the callable `func`
-    """
+    """Get executable path for the callable `func`."""
     return ".".join([func.__module__, func.__name__])
 
 

abstract_block_dumper/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.1'
-__version_tuple__ = version_tuple = (0, 0, 1)
+__version__ = version = '0.0.4'
+__version_tuple__ = version_tuple = (0, 0, 4)
 
 __commit_id__ = commit_id = None

abstract_block_dumper/management/commands/{block_tasks.py → block_tasks_v1.py}

@@ -1,14 +1,17 @@
 from django.core.management.base import BaseCommand
 
-from abstract_block_dumper.dal.memory_registry import task_registry
-from abstract_block_dumper.discovery import ensure_modules_loaded
-from abstract_block_dumper.services.scheduler import task_scheduler_factory
+from abstract_block_dumper._internal.dal.memory_registry import task_registry
+from abstract_block_dumper._internal.discovery import ensure_modules_loaded
+from abstract_block_dumper._internal.services.scheduler import task_scheduler_factory
 
 
 class Command(BaseCommand):
     help = "Run the block scheduler daemon."
 
     def handle(self, *args, **options) -> None:
+        """
+        Handle the management command to start the block scheduler.
+        """
         self.stdout.write("Syncing decorated functions...")
         ensure_modules_loaded()
         functions_counter = len(task_registry.get_functions())

abstract_block_dumper/models.py

@@ -3,7 +3,7 @@ from typing import Any
 
 from django.db import models
 
-import abstract_block_dumper.services.utils as abd_utils
+import abstract_block_dumper._internal.services.utils as abd_utils
 
 
 class TaskAttempt(models.Model):

abstract_block_dumper/v1/celery.py

@@ -0,0 +1,53 @@
+"""
+Celery integration helpers for abstract-block-dumper.
+
+This module provides utilities to integrate @block_task decorated functions
+with Celery workers.
+"""
+
+from abstract_block_dumper._internal.discovery import ensure_modules_loaded
+
+
+def setup_celery_tasks() -> None:
+    """
+    Discover and register all @block_task decorated functions for Celery.
+
+    This function MUST be called when Celery workers start to ensure that
+    all @block_task decorated functions are registered and available to
+    receive tasks from the message broker.
+
+    Usage in your project's celery.py:
+
+        from celery import Celery
+        from celery.signals import worker_ready
+
+        app = Celery('your_project')
+        app.config_from_object('django.conf:settings', namespace='CELERY')
+        app.autodiscover_tasks()
+
+        @worker_ready.connect
+        def on_worker_ready(**kwargs):
+            '''Load block tasks when worker is ready.'''
+            from abstract_block_dumper.v1.celery import setup_celery_tasks
+            setup_celery_tasks()
+
+    Why is this needed?
+    -------------------
+    The @block_task decorator uses Celery's @shared_task, which requires
+    the decorated functions to be imported before workers can receive
+    messages for those tasks. Without calling this function, you'll see
+    errors like:
+
+        "Received unregistered task of type 'your_app.block_tasks.task_name'"
+
+    What does it do?
+    ----------------
+    - Automatically imports all 'tasks.py' and 'block_tasks.py' modules
+      from your INSTALLED_APPS
+    - Triggers @block_task decorator registration
+    - Makes tasks available to Celery workers
+    """
+    ensure_modules_loaded()
+
+
+__all__ = ["setup_celery_tasks"]

abstract_block_dumper/{decorators.py → v1/decorators.py}

@@ -5,10 +5,10 @@ import structlog
 from celery import Task, shared_task
 from django.db import OperationalError, transaction
 
-import abstract_block_dumper.dal.django_dal as abd_dal
-import abstract_block_dumper.services.utils as abd_utils
-from abstract_block_dumper.dal.memory_registry import RegistryItem, task_registry
-from abstract_block_dumper.exceptions import CeleryTaskLocked
+import abstract_block_dumper._internal.dal.django_dal as abd_dal
+import abstract_block_dumper._internal.services.utils as abd_utils
+from abstract_block_dumper._internal.dal.memory_registry import RegistryItem, task_registry
+from abstract_block_dumper._internal.exceptions import CeleryTaskLockedError
 from abstract_block_dumper.models import TaskAttempt
 
 logger = structlog.get_logger(__name__)
@@ -20,7 +20,6 @@ def schedule_retry(task_attempt: TaskAttempt) -> None:
 
     Task must already be in FAILED state with next_retry_at set by mark_failed()
     """
-
     if not task_attempt.next_retry_at:
         logger.error(
             "Cannot schedule retry without next_retry_at",
@@ -63,7 +62,9 @@ def schedule_retry(task_attempt: TaskAttempt) -> None:
     )
 
 
-def _celery_task_wrapper(func, block_number: int, **kwargs) -> dict[str, Any] | None:
+def _celery_task_wrapper(
+    func: Callable[..., Any], block_number: int, **kwargs: dict[str, Any]
+) -> dict[str, Any] | None:
     executable_path = abd_utils.get_executable_path(func)
 
     with transaction.atomic():
@@ -73,21 +74,15 @@ def _celery_task_wrapper(func, block_number: int, **kwargs) -> dict[str, Any] |
                 executable_path=executable_path,
                 args_json=abd_utils.serialize_args(kwargs),
             )
-        except TaskAttempt.DoesNotExist:
-            logger.warning(
-                "TaskAttempt not found - task may have been canceled directly",
-                block_number=block_number,
-                executable_path=executable_path,
-            )
-            raise CeleryTaskLocked("TaskAttempt not found - task may have been canceled directly")
+        except TaskAttempt.DoesNotExist as exc:
+            msg = "TaskAttempt not found - task may have been canceled directly"
+            logger.warning(msg, block_number=block_number, executable_path=executable_path)
+            raise CeleryTaskLockedError(msg) from exc
+
         except OperationalError as e:
-            logger.info(
-                "Task already being processed by another worker",
-                block_number=block_number,
-                executable_path=executable_path,
-                operational_error=str(e),
-            )
-            raise CeleryTaskLocked("Task already being processed by another worker")
+            msg = "Task already being processed by another worker"
+            logger.info(msg, block_number=block_number, executable_path=executable_path, operational_error=str(e))
+            raise CeleryTaskLockedError(msg) from e
 
         if task_attempt.status != TaskAttempt.Status.PENDING:
             logger.info(
@@ -118,11 +113,11 @@ def _celery_task_wrapper(func, block_number: int, **kwargs) -> dict[str, Any] |
             logger.info("Task completed successfully", task_id=task_attempt.id)
             return {"result": result}
         except Exception as e:
-            logger.error(
+            logger.exception(
                 "Task execution failed",
                 task_id=task_attempt.id,
                 error_type=type(e).__name__,
-                exc_info=True,
+                error_message=str(e),
             )
             abd_dal.task_mark_as_failed(task_attempt)
 
@@ -131,10 +126,9 @@ def _celery_task_wrapper(func, block_number: int, **kwargs) -> dict[str, Any] |
         try:
             schedule_retry(task_attempt)
         except Exception:
-            logger.error(
+            logger.exception(
                 "Failed to schedule retry",
                 task_id=task_attempt.id,
-                exc_info=True,
             )
     return None
 
@@ -146,7 +140,7 @@ def block_task(
     celery_kwargs: dict[str, Any] | None = None,
 ) -> Callable[..., Any]:
     """
-    Decorator for registering block tasks.
+    Register a block task.
 
     Args:
         condition: Lambda function that determines when to execute
@@ -174,10 +168,11 @@ def block_task(
 
     def decorator(func: Callable[..., Any]) -> Any:
         if not callable(condition):
-            raise ValueError("condition must be a callable.")
+            msg = "condition must be a callable."
+            raise TypeError(msg)
 
         # Celery task wrapper
-        def shared_celery_task(block_number: int, **kwargs) -> None | Any:
+        def shared_celery_task(block_number: int, **kwargs: dict[str, Any]) -> None | Any:
             """
             Wrapper that handles TaskAttempt tracking and executed the original
             function
@@ -194,13 +189,13 @@ def block_task(
         )(shared_celery_task)
 
         # Store original function referefence for introspection
-        celery_task._original_func = func
+        celery_task._original_func = func  # noqa: SLF001
 
         # Register the Celery task
         task_registry.register_item(
             RegistryItem(
                 condition=condition,
-                function=cast(Task, celery_task),
+                function=cast("Task", celery_task),
                 args=args,
                 backfilling_lookback=backfilling_lookback,
                 celery_kwargs=celery_kwargs or {},

abstract_block_dumper/{tasks.py → v1/tasks.py}

@@ -14,7 +14,7 @@ from django.utils import timezone
 from abstract_block_dumper.models import TaskAttempt
 
 
-@shared_task(name="abstract_block_dumper.cleanup_old_tasks")
+@shared_task(name="abstract_block_dumper.v1.cleanup_old_tasks")
 def cleanup_old_tasks(days: int = 7) -> dict[str, int | str]:
     """
     Delete all succeeded or unrecoverable failed tasks older than the specified number of days.
@@ -47,12 +47,12 @@ def cleanup_old_tasks(days: int = 7) -> dict[str, int | str]:
 
         Example cron (daily at 2 AM):
         0 2 * * * python manage.py shell -c \
-            "from abstract_block_dumper.tasks import cleanup_old_tasks; cleanup_old_tasks.delay()"
+            "from abstract_block_dumper.v1.tasks import cleanup_old_tasks; cleanup_old_tasks.delay()"
 
         Example Celery beat schedule (in settings.py):
         CELERY_BEAT_SCHEDULE = {
             'cleanup-old-tasks': {
-                'task': 'abstract_block_dumper.cleanup_old_tasks',
+                'task': 'abstract_block_dumper.v1.cleanup_old_tasks',
                 'schedule': crontab(hour=2, minute=0),  # Daily at 2 AM
                 'kwargs': {'days': 7},
             },

{abstract_block_dumper-0.0.1.dist-info → abstract_block_dumper-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstract-block-dumper
-Version: 0.0.1
+Version: 0.0.4
 Project-URL: Source, https://github.com/bactensor/abstract-block-dumper
 Project-URL: Issue Tracker, https://github.com/bactensor/abstract-block-dumper/issues
 Author-email: Reef Technologies <opensource@reef.pl>
@@ -26,6 +26,22 @@ Description-Content-Type: text/markdown
 This package provides a simplified framework for creating block processing tasks in Django applications.
 Define tasks with lambda conditions using the @block_task decorator and run them asynchronously with Celery.
 
+## Usage
+
+> [!IMPORTANT]
+> This package uses [ApiVer](#versioning), make sure to import `abstract_block_dumper.v1`.
+
+
+## Versioning
+
+This package uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+TL;DR you are safe to use [compatible release version specifier](https://packaging.python.org/en/latest/specifications/version-specifiers/#compatible-release) `~=MAJOR.MINOR` in your `pyproject.toml` or `requirements.txt`.
+
+Additionally, this package uses [ApiVer](https://www.youtube.com/watch?v=FgcoAKchPjk) to further reduce the risk of breaking changes.
+This means, the public API of this package is explicitly versioned, e.g. `abstract_block_dumper.v1`, and will not change in a backwards-incompatible way even when `abstract_block_dumper.v2` is released.
+
+Internal packages, i.e. prefixed by `abstract_block_dumper._` do not share these guarantees and may change in a backwards-incompatible way at any time even in patch releases.
+
 ## Implementation Details
 
 ### General Workflow:
@@ -82,6 +98,28 @@ INSTALLED_APPS = [
 python manage.py migrate
 ```
 
+4. **Configure Celery to discover block tasks:**
+
+In your project's `celery.py` file, add the following to ensure Celery workers can discover your `@block_task` decorated functions:
+
+```python
+from celery import Celery
+from celery.signals import worker_ready
+from django.conf import settings
+
+app = Celery('your_project')
+app.config_from_object('django.conf:settings', namespace='CELERY')
+app.autodiscover_tasks()
+
+@worker_ready.connect
+def on_worker_ready(**kwargs):
+    """Load block tasks when worker starts."""
+    from abstract_block_dumper.v1.celery import setup_celery_tasks
+    setup_celery_tasks()
+```
+
+> **Important:** Without this step, Celery workers will not recognize your `@block_task` decorated functions, and you'll see "Received unregistered task" errors.
+
 ## Usage
 
 ### 1. Define Block Processing Tasks
@@ -93,7 +131,7 @@ Create block processing tasks in `tasks.py` or `block_tasks.py` file inside any
 ### 3. Start the Block Scheduler
 Run the scheduler to start processing blocks:
 ```bash
-$ python manage.py block_tasks
+$ python manage.py block_tasks_v1
 ```
 
 This command will:
@@ -112,7 +150,7 @@ See examples below:
 Use the `@block_task` decorator with lambda conditions to create block processing tasks:
 
 ```python
-from abstract_block_dumper.decorators import block_task
+from abstract_block_dumper.v1.decorators import block_task
 
 
 # Process every block
@@ -144,7 +182,7 @@ def process_multi_netuid_task(block_number: int, netuid: int):
 The framework provides a maintenance task to clean up old task records and maintain database performance:
 
 ```python
-from abstract_block_dumper.tasks import cleanup_old_tasks
+from abstract_block_dumper.v1.tasks import cleanup_old_tasks
 
 # Delete tasks older than 7 days (default)
 cleanup_old_tasks.delay()
@@ -160,13 +198,13 @@ This task deletes all succeeded or unrecoverable failed tasks older than the spe
 **Option 1: Manual Execution**
 ```bash
 # Using Django shell
-python manage.py shell -c "from abstract_block_dumper.tasks import cleanup_old_tasks; cleanup_old_tasks.delay()"
+python manage.py shell -c "from abstract_block_dumper.v1.tasks import cleanup_old_tasks; cleanup_old_tasks.delay()"
 ```
 
 **Option 2: Cron Job (Recommended - once per day)**
 ```bash
 # Add to crontab (daily at 2 AM)
-0 2 * * * cd /path/to/your/project && python manage.py shell -c "from abstract_block_dumper.tasks import cleanup_old_tasks; cleanup_old_tasks.delay()"
+0 2 * * * cd /path/to/your/project && python manage.py shell -c "from abstract_block_dumper.v1.tasks import cleanup_old_tasks; cleanup_old_tasks.delay()"
 ```
 
 **Option 3: Celery Beat (Automated Scheduling)**
@@ -210,55 +248,92 @@ BLOCK_DUMPER_MAX_ATTEMPTS = 3  # maximum retry attempts
 BLOCK_TASK_MAX_RETRY_DELAY_MINUTES = 1440  # maximum retry delay (24 hours)
 ```
 
-### Configuration Options Reference
-
-#### Core Settings
-
-**BITTENSOR_NETWORK** (str, default: `'finney'`) Specifies which [Bittensor network](https://docs.learnbittensor.org/concepts/bittensor-networks) to connect to
-
-**BLOCK_DUMPER_START_FROM_BLOCK** (str|int|None, default: `None`)
-- **Purpose**: Determines the starting block for processing when the scheduler first runs
-- **Valid Values**:
-  - `None`: Resume from the last processed block stored in database
-  - `'current'`: Start from the current blockchain block (skips historical blocks)
-  - `int`: Start from a specific block number (e.g., `1000000`)
-- **Example**: `BLOCK_DUMPER_START_FROM_BLOCK = 'current'`
-- **Performance Impact**: Starting from historical blocks may require significant processing time
-
-#### Scheduler Settings
-
-**BLOCK_DUMPER_POLL_INTERVAL** (int, default: `1`)
-- **Purpose**: Seconds to wait between checking for new blocks
-- **Valid Range**: `1` to `3600` (1 second to 1 hour)
-- **Example**: `BLOCK_DUMPER_POLL_INTERVAL = 5`
-- **Performance Impact**:
-  - Lower values (1-2s): Near real-time processing, higher CPU/network usage
-  - Higher values (10-60s): Reduced load but delayed processing
-  - Very low values (<1s) may cause rate limiting
-
-#### Retry and Error Handling Settings
-
-**BLOCK_DUMPER_MAX_ATTEMPTS** (int, default: `3`)
-- **Purpose**: Maximum number of attempts to retry a failed task before giving up
-- **Valid Range**: `1` to `10`
-- **Example**: `BLOCK_DUMPER_MAX_ATTEMPTS = 5`
-- **Performance Impact**: Higher values increase resilience but may delay failure detection
-
-**BLOCK_TASK_RETRY_BACKOFF** (int, default: `1`)
-- **Purpose**: Base number of minutes for exponential backoff retry delays
-- **Valid Range**: `1` to `60`
-- **Example**: `BLOCK_TASK_RETRY_BACKOFF = 2`
-- **Calculation**: Actual delay = `backoff ** attempt_count` minutes
+## Configuration Options Reference
+
+### `BITTENSOR_NETWORK`
+- **Type:** `str`
+- **Default:** `'finney'`
+- **Description:** Specifies which [Bittensor network](https://docs.learnbittensor.org/concepts/bittensor-networks) to connect to
+
+---
+
+### `BLOCK_DUMPER_START_FROM_BLOCK`
+- **Type:** `str | int | None`
+- **Default:** `None`
+- **Valid Range:** `None`, `'current'`, or any positive integer
+- **Description:** Determines the starting block for processing when the scheduler first runs
+  - `None` → Resume from the last processed block stored in database
+  - `'current'` → Start from the current blockchain block (skips historical blocks)
+  - Integer → Start from a specific block number (e.g., `1000000`)
+
+```python
+BLOCK_DUMPER_START_FROM_BLOCK = 'current'
+```
+
+> **Performance Impact:** Starting from historical blocks may require significant processing time
+
+---
+
+### `BLOCK_DUMPER_POLL_INTERVAL`
+- **Type:** `int`
+- **Default:** `1`
+- **Valid Range:** `1` to `3600` (seconds)
+- **Description:** Seconds to wait between checking for new blocks
+
+```python
+BLOCK_DUMPER_POLL_INTERVAL = 5
+```
+
+> **Performance Impact:**
+> - Lower values (1-2s): Near real-time processing, higher CPU/network usage
+> - Higher values (10-60s): Reduced load but delayed processing
+> - Very low values (<1s): May cause rate limiting
+
+---
+
+### `BLOCK_DUMPER_MAX_ATTEMPTS`
+- **Type:** `int`
+- **Default:** `3`
+- **Valid Range:** `1` to `10`
+- **Description:** Maximum number of attempts to retry a failed task before giving up
+
+```python
+BLOCK_DUMPER_MAX_ATTEMPTS = 5
+```
+
+> **Performance Impact:** Higher values increase resilience but may delay failure detection
+
+---
+
+### `BLOCK_TASK_RETRY_BACKOFF`
+- **Type:** `int`
+- **Default:** `1`
+- **Valid Range:** `1` to `60` (minutes)
+- **Description:** Base number of minutes for exponential backoff retry delays
+- **Calculation:** Actual delay = `backoff ** attempt_count` minutes
   - Attempt 1: 2¹ = 2 minutes
-  - Attempt 2: 2² = 4 minutes  
+  - Attempt 2: 2² = 4 minutes
   - Attempt 3: 2³ = 8 minutes
-- **Performance Impact**: Lower values retry faster but may overwhelm failing services
 
-**BLOCK_TASK_MAX_RETRY_DELAY_MINUTES** (int, default: `1440`)
-- **Purpose**: Maximum delay (in minutes) between retry attempts, caps exponential backoff
-- **Valid Range**: `1` to `10080` (1 minute to 1 week)
-- **Example**: `BLOCK_TASK_MAX_RETRY_DELAY_MINUTES = 720`  # 12 hours max
-- **Performance Impact**: Prevents extremely long delays while maintaining backoff benefits
+```python
+BLOCK_TASK_RETRY_BACKOFF = 2
+```
+
+> **Performance Impact:** Lower values retry faster but may overwhelm failing services
+
+---
+
+### `BLOCK_TASK_MAX_RETRY_DELAY_MINUTES`
+- **Type:** `int`
+- **Default:** `1440` (24 hours)
+- **Valid Range:** `1` to `10080` (1 minute to 1 week)
+- **Description:** Maximum delay (in minutes) between retry attempts, caps exponential backoff
+
+```python
+BLOCK_TASK_MAX_RETRY_DELAY_MINUTES = 720  # 12 hours max
+```
+
+> **Performance Impact:** Prevents extremely long delays while maintaining backoff benefits
 
 
 ## Example Project

abstract_block_dumper-0.0.4.dist-info/RECORD

@@ -0,0 +1,29 @@
+abstract_block_dumper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/_version.py,sha256=QlXZ5JTjE_pgpDaeHk0GTExkc75xUZFmd0hA7kGYCJ0,704
+abstract_block_dumper/admin.py,sha256=3J3I_QOKFgfMNpTXW-rTQGO_q5Ls6uNuL0FkPVdIsYg,1654
+abstract_block_dumper/apps.py,sha256=DXATdrjsL3T2IletTbKeD6unr8ScLaxg7wz0nAHTAns,215
+abstract_block_dumper/models.py,sha256=MO9824dmHB6xF3PrFE_RERh7whVjQtS4tt6QA0wSbg0,2022
+abstract_block_dumper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/_internal/discovery.py,sha256=sISOL8vq6rC0pOndrCfWKDZjyYwzzZIChG-BH9mteq0,745
+abstract_block_dumper/_internal/exceptions.py,sha256=jVXQ8b3gneno2XYvO0XisJPMlkAWb6H5u10egIpPJ4k,335
+abstract_block_dumper/_internal/dal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/_internal/dal/django_dal.py,sha256=pBGEFeo_U0ac2Za-dwzJvf04Ng8lP51aR60c_DUrGIw,5426
+abstract_block_dumper/_internal/dal/memory_registry.py,sha256=yMNF7jrvWGF-S1pqyR2zOCNLWwrdsImcvV6cGqu1wYE,2972
+abstract_block_dumper/_internal/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/_internal/services/block_processor.py,sha256=wB-zeft3Ys8zmqCdF_v12rXd6umNWvGfy2Ts6XSGkL8,8132
+abstract_block_dumper/_internal/services/executor.py,sha256=ZZmQ9TzoNEoAE4amiU8lHRsTfP7YusUkWXasrArfo2g,1806
+abstract_block_dumper/_internal/services/scheduler.py,sha256=NrT3t0oVR-osf50tWWqcxojkVkxhd2PHsk0PuXD5RMc,3593
+abstract_block_dumper/_internal/services/utils.py,sha256=Y8b8KdKn53mcuWchw6b5EJq9ipO4p1FFf6g_Fpbg7cQ,1273
+abstract_block_dumper/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/management/commands/block_tasks_v1.py,sha256=jSi04ahIKYwlm_dNKCUGL_cmALv1iP-ZjfXrmz0pn-4,880
+abstract_block_dumper/migrations/0001_initial.py,sha256=ImPHC3G6kPkq4Xn_4YVAm4Labh1Xi7PkCRszYRGpTiI,2298
+abstract_block_dumper/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+abstract_block_dumper/v1/celery.py,sha256=X4IqVs5i6ZpyY7fy1SqMZgsZy4SXP-jK2qG-FYnjU38,1722
+abstract_block_dumper/v1/decorators.py,sha256=i-CVanS-yiBMKCEOLjGmwmopefWePhyMdodlWNIfJFg,7002
+abstract_block_dumper/v1/tasks.py,sha256=u9iMYdDUqzYT3yPrNwZecHnlweZ3yFipV9BcIWHCbus,2647
+abstract_block_dumper-0.0.4.dist-info/METADATA,sha256=wBsIWl5439xp-EYInzV-mQaAKIoa_CDP97FJoeaB-ng,12916
+abstract_block_dumper-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+abstract_block_dumper-0.0.4.dist-info/RECORD,,

abstract_block_dumper-0.0.1.dist-info/RECORD

@@ -1,25 +0,0 @@
-abstract_block_dumper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-abstract_block_dumper/_version.py,sha256=qf6R-J7-UyuABBo8c0HgaquJ8bejVbf07HodXgwAwgQ,704
-abstract_block_dumper/admin.py,sha256=3J3I_QOKFgfMNpTXW-rTQGO_q5Ls6uNuL0FkPVdIsYg,1654
-abstract_block_dumper/apps.py,sha256=DXATdrjsL3T2IletTbKeD6unr8ScLaxg7wz0nAHTAns,215
-abstract_block_dumper/decorators.py,sha256=lV1ueIlEbBNojnXVH5GQiRCbck3-SQgtWOil5OqeTHo,7061
-abstract_block_dumper/discovery.py,sha256=kZlb8y-0ltJE-L-1GLxZ_xlziibY8AjggvHJ9sxsScw,728
-abstract_block_dumper/exceptions.py,sha256=EunFH-H5eXNNkKl2CvHlhZ2wvtdry969Gle-CZc7YM0,315
-abstract_block_dumper/models.py,sha256=l229tar4FdQ52eETLKGeskgkXHWa4ealF6DWbG8M4Mc,2012
-abstract_block_dumper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-abstract_block_dumper/tasks.py,sha256=8ppGWxML3krVdrS_08WnKuCpERRhB_6DIyVEkpYZMrw,2638
-abstract_block_dumper/dal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-abstract_block_dumper/dal/django_dal.py,sha256=unAA4Mt5dBBaUhvyezfyC0VtWMD6Ru79NyjKaOMNNSw,5359
-abstract_block_dumper/dal/memory_registry.py,sha256=rgU2CYGm2MHPgSZefgr-kuLxOtPu5wxINa3Y5ELgMUo,3029
-abstract_block_dumper/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-abstract_block_dumper/management/commands/block_tasks.py,sha256=dEfFnoZCIIDsrNL5vRPtIDrkpcJk36yev_aoGAScgoQ,758
-abstract_block_dumper/migrations/0001_initial.py,sha256=ImPHC3G6kPkq4Xn_4YVAm4Labh1Xi7PkCRszYRGpTiI,2298
-abstract_block_dumper/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-abstract_block_dumper/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-abstract_block_dumper/services/block_processor.py,sha256=4guYwtVYh-N1UewiqVN7xG5pM56adyGe8vPG_kCDmQI,8072
-abstract_block_dumper/services/executor.py,sha256=TDbrtVGiz7GNGJwHYB6ZqqhrrTDDL7JGzxOehpF-QTY,1786
-abstract_block_dumper/services/scheduler.py,sha256=zKY24zSwjcQSVk3wt39GBurSNXkfylWsdV7Mgmv1RO8,3443
-abstract_block_dumper/services/utils.py,sha256=Iqa-9xhNxOCnvSWjGBclOUvmO4qsUhhievUllVh82I4,1286
-abstract_block_dumper-0.0.1.dist-info/METADATA,sha256=g26Qm3r1ZwH5OCCVCndRdjwnn-VY4YdIxwQyGKuVHXA,11022
-abstract_block_dumper-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-abstract_block_dumper-0.0.1.dist-info/RECORD,,