modusa 0.1.0__py3-none-any.whl

modusa/__init__.py

@@ -0,0 +1 @@
+from modusa.utils import excp, config

modusa/config.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+
+import logging
+
+class Config:
+	LOG_LEVEL = logging.WARNING
+	SR = 44100  # Default sampling rate
+	TIME_UNIT = "sec"
+	
+	
+	def __str__(self):
+		return self.__dict__
+	
+	def __repr__(self):
+		return self.__dict__
+
+# Create a singleton instance
+config = Config()

modusa/decorators.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+
+from modusa import excp
+from functools import wraps
+from typing import Any, Callable, Type
+from inspect import signature, Parameter
+from typing import get_origin, get_args, Union
+import types
+
+
+#----------------------------------------------------
+# Safety check for plugin (apply method)
+# Check if the input type, output type is allowed,
+# Also logs plugin usage.
+#----------------------------------------------------
+def plugin_safety_check(
+	validate_plugin_input: bool = True,
+	validate_plugin_output: bool = True,
+	track_plugin_usage: bool = True
+):
+	def decorator(func: Callable) -> Callable:
+		@wraps(func)
+		def wrapper(self, signal: Any, *args, **kwargs):
+			
+			if validate_plugin_input:
+				if not hasattr(self, 'allowed_input_signal_types'):
+					raise excp.AttributeNotFoundError(f"{self.__class__.__name__} must define `allowed_input_signal_types`.")
+				
+				if type(signal) not in self.allowed_input_signal_types:
+					raise excp.PluginInputError(f"{self.__class__.__name__} must take input signal of type {self.allowed_input_signal_types} but got {type(signal)}")
+			
+			if track_plugin_usage:
+				if not hasattr(signal, '_plugin_chain'):
+					raise excp.AttributeNotFoundError(f"Signal of type {type(signal).__name__} must have a `_plugin_chain` attribute for plugin tracking.")
+					
+				if not isinstance(signal._plugin_chain, list):
+					raise excp.TypeError(f"`_plugin_chain` must be a list, but got {type(signal._plugin_chain)}")
+					
+				signal._plugin_chain.append(self.__class__.__name__)
+			
+			result = func(self, signal, *args, **kwargs)
+			
+			if validate_plugin_output:
+				if not hasattr(self, 'allowed_output_signal_types'):
+					raise excp.AttributeNotFoundError(f"{self.__class__.__name__} must define `allowed_output_signal_types`.")
+				if type(result) not in self.allowed_output_signal_types:
+					raise excp.PluginInputError(f"{self.__class__.__name__} must return output of type {self.allowed_output_signal_types} but returned {type(result)}")
+			return result
+	
+		return wrapper
+	return decorator
+
+
+#----------------------------------------------------
+# Safety check for generators (generate method)
+# Check if the ouput type is allowed.
+#----------------------------------------------------
+def generator_safety_check():
+	"""
+	We assume that the first argument is self, so that we can actually extract properties to
+	validate.
+	"""
+	def decorator(func: Callable) -> Callable:
+		@wraps(func)
+		def wrapper(self, *args, **kwargs):
+			result = func(self, *args, **kwargs)
+			
+			if not hasattr(self, 'allowed_output_signal_types'):
+				raise excp.AttributeNotFoundError(
+					f"{self.__class__.__name__} must define `allowed_output_signal_types`."
+				)
+			if type(result) not in self.allowed_output_signal_types:
+				raise excp.PluginInputError(
+					f"{self.__class__.__name__} must return output of type {self.allowed_output_signal_types}, "
+					f"but returned {type(result)}"
+				)
+				
+			return result
+		return wrapper
+	return decorator
+
+
+#----------------------------------------------------
+# Validation for args type
+# When this decorator is added to a function, it
+# automatically checks all the arguments with their
+# expected types. (self, forward type references are
+# ignored)
+#----------------------------------------------------
+
+def validate_arg(arg_name: str, value: Any, expected_type: Any) -> None:
+	"""
+	Checks if `value_type` matches `expected_type`.
+	Raises TypeError if not.
+	"""
+	import types
+	from typing import get_origin, get_args, Union
+	
+	origin = get_origin(expected_type)
+	
+	# Handle Union (e.g. int | None)
+	if origin in (Union, types.UnionType):
+		union_args = get_args(expected_type)
+		for typ in union_args:
+			typ_origin = get_origin(typ) or typ
+			if type(value) is typ_origin:
+				return
+		
+		# ❌ If none match
+		expected_names = ", ".join(
+			get_origin(t).__name__ if get_origin(t) else t.__name__ for t in union_args
+		)
+		raise excp.ValidationError(
+			f"Argument '{arg_name}' must be one of ({expected_names}), got {type(value).__name__}"
+		)
+	
+	# Handle generic types like list[float], tuple[int, str]
+	elif origin is not None:
+		if type(value) is not origin:
+			raise excp.ValidationError(
+				f"Argument '{arg_name}' must be exactly of type {origin.__name__}, got {type(value).__name__}"
+			)
+		return
+		
+	# ✅ Handle plain types
+	elif isinstance(expected_type, type):
+		if type(value) is not expected_type:
+			raise excp.ValidationError(
+				f"Argument '{arg_name}' must be exactly {expected_type.__name__}, got {type(value).__name__}"
+			)
+		return
+	# ❌ Unsupported type structure
+	else:
+		raise excp.ValidationError(f"Unsupported annotation for '{arg_name}': {expected_type}")
+
+def validate_args_type() -> Callable:
+	def decorator(func: Callable) -> Callable:
+		@wraps(func)
+		def wrapper(*args, **kwargs):
+			sig = signature(func)
+			bound = sig.bind(*args, **kwargs)
+			bound.apply_defaults()
+			
+			for arg_name, value in bound.arguments.items():
+				param = sig.parameters[arg_name]
+				expected_type = param.annotation
+				
+				# Skip unannotated or special args
+				if expected_type is Parameter.empty or arg_name in ("self", "cls") or isinstance(expected_type, str):
+					continue
+				
+				validate_arg(arg_name, value, expected_type)  # <- this is assumed to be defined elsewhere
+				
+			return func(*args, **kwargs)
+		return wrapper
+	return decorator
+
+#-----------------------------------
+# Making a property immutable
+# and raising custom error message
+# during attempt to modify the values
+#-----------------------------------
+def immutable_property(error_msg: str):
+	"""
+	Returns a read-only property. Raises an error with a custom message on mutation.
+	"""
+	def decorator(getter):
+		name = getter.__name__
+		private_name = f"_{name}"
+		
+		def setter(self, value):
+			raise excp.ImmutableAttributeError(error_msg)
+			
+		return property(getter, setter)
+	
+	return decorator

modusa/devtools/generate_template.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+
+from datetime import date
+from pathlib import Path
+import questionary
+import sys
+
+ROOT_DIR = Path(__file__).parents[3].resolve()
+TEMPLATES_DIR = ROOT_DIR / "src/modusa/devtools/templates"
+
+class TemplateGenerator():
+	"""
+	Generates template for `plugin`, `engine`, `signal`, `generator`.
+	"""
+	
+	@staticmethod
+	def ask_questions(for_what: str) -> dict:
+		print("----------------------")
+		print(for_what.upper())
+		print("----------------------")
+		module_name = questionary.text("Module name (snake_case): ").ask()
+		if module_name is None:
+			sys.exit(1)
+		if Path(f"src/modusa/{for_what}/{module_name}.py").exists():
+			print(f"⚠️ File already exists, choose another name.")
+			sys.exit(1)
+		
+		class_name = questionary.text("Class name (CamelCase): ").ask()
+		if class_name is None:
+			sys.exit(1)
+			
+		author_name = questionary.text("Author name: ").ask()
+		if author_name is None:
+			sys.exit(1)
+		
+		author_email = questionary.text("Author email: ").ask()
+		if author_email is None:
+			sys.exit(1)
+		
+		answers = {"module_name": module_name, "class_name": class_name, "author_name": author_name, "author_email": author_email, "date_created": date.today()}
+			
+		return answers
+	
+	@staticmethod
+	def load_template_file(for_what: str) -> str:
+		template_path = TEMPLATES_DIR / f"{for_what}.py"
+		if not template_path.exists():
+			print(f"❌ Template not found: {template_path}")
+			sys.exit(1)
+		
+		template_code = template_path.read_text()
+		
+		return template_code
+	
+	@staticmethod
+	def fill_placeholders(template_code: str, placehoders_dict: dict) -> str:
+		template_code = template_code.format(**placehoders_dict)  # Fill placeholders
+		return template_code
+	
+	@staticmethod
+	def save_file(content: str, output_path: Path) -> None:
+		output_path.parent.mkdir(parents=True, exist_ok=True)
+		output_path.write_text(content)
+		print(f"✅ Successfully created.\n\n open {output_path.resolve()}")
+	
+	@staticmethod
+	def create_template(for_what: str) -> None:
+		
+		# Ask basic questions to create the template for `plugin`, `generator`, ...
+		answers: dict = TemplateGenerator.ask_questions(for_what)
+		
+		# Load the correct template file
+		template_code: str = TemplateGenerator.load_template_file(for_what)
+		
+		# Update the dynamic values based on the answers
+		template_code: str = TemplateGenerator.fill_placeholders(template_code, answers)
+		
+		# Save it to a file and put it in the correct folder
+		TemplateGenerator.save_file(content=template_code, output_path=ROOT_DIR / f"src/modusa/{for_what}/{answers['module_name']}.py")

modusa/devtools/list_authors.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+

modusa/devtools/list_plugins.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+
+import inspect
+from pathlib import Path
+
+PLUGIN_PATH = Path(__file__).parent.parent / "plugins" # This directory contains all the plugins
+
+def find_plugin_files():
+	return [
+			path for path in PLUGIN_PATH.rglob("*.py")
+			if path.name not in {"__init__.py", "base.py"} # We do not want to show base plugins
+		]
+
+def load_plugin_class_from_file(file_path):
+	import importlib.util
+	from modusa.plugins.base import ModusaPlugin
+	
+	spec = importlib.util.spec_from_file_location(file_path.stem, file_path)
+	module = importlib.util.module_from_spec(spec)
+	try:
+		spec.loader.exec_module(module)
+	except Exception as e:
+		print(f"❌ Error loading {file_path}: {e}")
+		return []
+	
+	plugin_classes = []
+	for _, obj in inspect.getmembers(module, inspect.isclass):
+		if issubclass(obj, ModusaPlugin) and obj is not ModusaPlugin:
+			plugin_classes.append(obj)
+			
+	return plugin_classes
+
+def list_plugins():
+	from rich.console import Console
+	from rich.table import Table
+	from modusa.plugins.base import ModusaPlugin
+	
+	console = Console()
+	table = Table(title="🔌 Available Modusa Plugins")
+	
+	table.add_column("Plugin", style="bold green")
+	table.add_column("Module", style="dim")
+	table.add_column("Description", style="white")
+	
+	all_plugins = []
+	
+	for file_path in find_plugin_files():
+		plugin_classes = load_plugin_class_from_file(file_path)
+		for cls in plugin_classes:
+			name = cls.__name__
+			module = file_path.relative_to(PLUGIN_PATH.parent)
+			author = getattr(cls, "author_name", "—")
+			email = getattr(cls, "author_email", "—")
+			desc = getattr(cls, "description", "—")
+			table.add_row(name, str(module), desc)
+			table.add_row("")
+			all_plugins.append(cls)
+			
+	console.print(table)
+

modusa/devtools/main.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+
+
+from .generate_template import TemplateGenerator
+from .list_plugins import list_plugins
+from . import list_authors
+
+import argparse
+import sys
+
+def main():
+	try:
+		parser = argparse.ArgumentParser(
+			prog="modusa-dev",
+			description="Modusa CLI Tools"
+		)
+		subparsers = parser.add_subparsers(dest="group", required=True)
+		
+		# --- CREATE group ---
+		create_parser = subparsers.add_parser("create", help="Create new Modusa components")
+		create_subparsers = create_parser.add_subparsers(dest="what", required=True)
+		
+		create_subparsers.add_parser("engine", help="Create a new engine class").set_defaults(func=lambda:TemplateGenerator.create_template("engines"))
+		create_subparsers.add_parser("plugin", help="Create a new plugin class").set_defaults(func=lambda:TemplateGenerator.create_template("plugins"))
+		create_subparsers.add_parser("signal", help="Create a new signal class").set_defaults(func=lambda:TemplateGenerator.create_template("signals"))
+		create_subparsers.add_parser("generator", help="Create a new signal generator class").set_defaults(func=lambda:TemplateGenerator.create_template("generators"))
+		
+		# --- LIST group ---
+		list_parser = subparsers.add_parser("list", help="List information about Modusa components")
+		list_subparsers = list_parser.add_subparsers(dest="what", required=True)
+		
+		list_subparsers.add_parser("plugins", help="List available plugins").set_defaults(func=list_plugins)
+		list_subparsers.add_parser("authors", help="List plugin authors").set_defaults(func=list_authors)
+		
+		# --- Parse and execute ---
+		args = parser.parse_args()
+		args.func()
+		
+	except KeyboardInterrupt:
+		print("\n❌ Aborted by user.")
+		sys.exit(1)
+		

modusa/devtools/templates/engines.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.engines.base import ModusaEngine
+from typing import Any
+
+class {class_name}(ModusaEngine):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "{author_name}"
+	author_email = "{author_email}"
+	created_at = "{date_created}"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+	
+	
+	@validate_args_type()
+	def run(self) -> Any:
+		pass

modusa/devtools/templates/generators.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+
+from modusa.decorators import validate_args_type
+from modusa.generators.base import ModusaGenerator
+
+
+class {class_name}(ModusaGenerator):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "{author_name}"
+	author_email = "{author_email}"
+	created_at = "{date_created}"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+	
+	
+	def generate(self) -> Any:
+		pass

modusa/devtools/templates/plugins.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+
+from modusa.plugins.base import ModusaPlugin
+from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
+
+
+class {class_name}(ModusaPlugin):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "{author_name}"
+	author_email = "{author_email}"
+	created_at = "{date_created}"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+		
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_input_signal_types(self) -> tuple[type, ...]:
+		return ()
+	
+	
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		return ()
+	
+	
+	@plugin_safety_check()
+	@validate_args_type()
+	def apply(self, signal: "") -> "":
+		
+		# Run the engine here
+		
+		return 

modusa/devtools/templates/signals.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import immutable_property, validate_args_type
+from modusa.signals.base import ModusaSignal
+from typing import Self, Any
+import numpy as np
+
+class {class_name}(ModusaSignal):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "{author_name}"
+	author_email = "{author_email}"
+	created_at = "{date_created}"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__() # Instantiating `ModusaSignal` class
+	
+	
+	def _with_data(self, new_data: np.ndarray) -> Self:
+		"""Subclasses must override this to return a copy with new data."""
+		raise NotImplementedError("Subclasses must implement _with_data")
+		
+	
+	#----------------------
+	# From methods
+	#----------------------
+	@classmethod
+	def from_array(cls) -> Self:
+		pass
+		
+	
+	#----------------------
+	# Setters
+	#----------------------
+	
+	
+	
+	
+	#----------------------
+	# Properties
+	#----------------------
+	@immutable_property("Create a new object instead.")
+	def data(self) -> np.ndarray:
+		""""""
+		pass
+	
+	#----------------------
+	# Plugins Access
+	#----------------------
+	def plot(self) -> Any:
+		"""
+		
+		"""
+		pass
+	

modusa/engines/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+
+from .plot_1dsignal import Plot1DSignalEngine
+from .plot_2dmatrix import Plot2DMatrixEngine

modusa/engines/base.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+class ModusaEngine(ABC):
+	"""
+	Base class for all core logic components in the Modusa system.
+	Every subclass must implement the `run` method.
+	"""
+	
+	@abstractmethod
+	def run(self, *args, **kwargs) -> Any:
+		pass

modusa/engines/plot_1dsignal.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.engines.base import ModusaEngine
+from typing import Any
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle
+
+
+class Plot1DSignalEngine(ModusaEngine):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = "Plot 1D Signal"
+	description = ""
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-02"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+	
+	
+	@validate_args_type()
+	def run(
+		self,
+		y: np.ndarray,
+		x: np.ndarray | None,
+		scale_y: tuple[float, float] | None,
+		scale_x: tuple[float, float] | None ,
+		ax: plt.Axes | None,
+		color: str,
+		marker: str | None,
+		linestyle: str | None,
+		stem: bool | None,
+		labels: tuple[str, str, str] | None,
+		legend_loc: str | None,
+		zoom: tuple | None,
+		highlight: list[tuple[float, float], ...] | None,
+	) -> plt.Figure | None:
+				
+		
+		# Validate the important args and get the signal that needs to be plotted
+		if y.ndim != 1:
+			raise excp.InputValueError(f"`y` must be of dimension 1 not {y.ndim}.")
+		if y.shape[0] < 1:
+			raise excp.InputValueError(f"`y` must not be empty.")
+			
+		if x is None:
+			x = np.arange(y.shape[0])
+		elif x.ndim != 1:
+			raise excp.InputValueError(f"`x` must be of dimension 1 not {x.ndim}.")
+		elif x.shape[0] < 1:
+			raise excp.InputValueError(f"`x` must not be empty.")
+		
+		if x.shape[0] != y.shape[0]:
+			raise excp.InputValueError(f"`y` and `x` must be of same shape")
+		
+		# Scale the signal if needed
+		if scale_y is not None:
+			if len(scale_y) != 2:
+				raise excp.InputValueError(f"`scale_y` must be tuple of two values (1, 2) => 1y+2")
+			a, b = scale_y
+			y = a * y + b
+		
+		if scale_x is not None:
+			if len(scale_x) != 2:
+				raise excp.InputValueError(f"`scale_x` must be tuple of two values (1, 2) => 1x+2")
+			a, b = scale_x
+			x = a * x + b
+			
+		# Create a figure
+		if ax is None:
+			fig, ax = plt.subplots(figsize=(15, 2))
+			created_fig = True
+		else:
+			fig = ax.get_figure()
+			created_fig = False 
+		
+		# Plot the signal with right configurations
+		plot_label = labels[0] if labels is not None and len(labels) > 0 else None
+		if stem:
+			ax.stem(x, y, linefmt=color, markerfmt='o', label=plot_label)
+		elif marker is not None:
+			ax.plot(x, y, c=color, linestyle=linestyle, lw=1.5, marker=marker, label=plot_label)
+		else:
+			ax.plot(x, y, c=color, linestyle=linestyle, lw=1.5, label=plot_label)
+			
+		# Add legend
+		if plot_label is not None:
+			legend_loc = "upper right" if legend_loc is None else legend_loc
+			ax.legend(loc=legend_loc)
+		
+		# Set the labels
+		if labels is not None:
+			if len(labels) > 0:
+				ax.set_title(labels[0])
+			if len(labels) > 1:
+				ax.set_ylabel(labels[1])
+			if len(labels) > 2:
+				ax.set_xlabel(labels[2])
+	
+		# Zoom into a region
+		if zoom is not None:
+			ax.set_xlim(zoom)
+		
+		# Highlight a list of regions
+		if highlight is not None:
+			for highlight_region in highlight:
+				if len(highlight_region) != 2:
+					raise excp.InputValueError(f"`highlight should be a list of tuple of 2 values (left, right) => (1, 10.5)")
+				l, r = highlight_region
+				ax.add_patch(Rectangle((l, np.min(y)), r - l, np.max(y) - np.min(y), color='red', alpha=0.2, zorder=10))
+		
+		# Show/Return the figure as per needed
+		if created_fig:
+			fig.tight_layout()
+			try:
+				get_ipython
+				plt.close(fig) # Without this, you will see two plots in the jupyter notebook
+				return fig
+			except NameError:
+				plt.show()
+				return fig