modusa 0.1.0__tar.gz

modusa-0.1.0/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 [Ankit Anand @meluron]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

modusa-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.1
+Name: modusa
+Version: 0.1.0
+Summary: A modular signal analysis python library.
+Author-Email: Ankit Anand <ankit0.anand0@gmail.com>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: jupyter>=1.1.1
+Requires-Dist: pytest>=8.4.0
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: librosa>=0.11.0
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: sqlalchemy>=2.0.41
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: sphinx==8.1.2
+Requires-Dist: sphinx-autodoc-typehints==2.1.0
+Requires-Dist: sphinx-copybutton>=0.5.2
+Requires-Dist: furo>=2024.8.6
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: snakeviz>=2.2.2
+Requires-Dist: line-profiler>=4.2.0
+Requires-Dist: nbsphinx==0.9.7
+Requires-Dist: ghp-import>=2.1.0
+Description-Content-Type: text/markdown
+
+# modusa
+
+**modusa**: **Mod**ular **U**nified **S**ignal **A**rchitecture* is a flexible, extensible Python framework for building, transforming, and analyzing different signal representations. It is a domain-agnostic core architecture for modern signal processing workflows.
+
+---
+
+## 🔧 Features
+
+- ⚙️ **modusa Signals**
+- 🧩 **modusa Plugins**
+- 📊 **modusa Genetators**
+- ♻️ **modusa Engine**
+
+---
+
+## 🚀 Installation
+
+> modusa is under active development. You can install the latest version via:
+
+```bash
+git clone https://github.com/meluron/modusa.git
+cd modusa
+pdm install
+```
+
+---
+
+## 🧪 Tests
+
+```bash
+pytest tests/
+```
+
+---
+
+## 🧊 Status
+
+modusa is in **early alpha**. Expect rapid iteration, breaking changes, and big ideas.  
+If you like the direction, consider ⭐ starring the repo and opening issues or ideas.
+
+---
+
+## 🧠 About
+
+**modusa** is developed and maintained by [meluron](https://www.github.com/meluron),
+
+---
+
+## 📜 License
+
+MIT License. See `LICENSE` for details.
+
+---
+
+## 🙌 Contributions
+
+Pull requests, ideas, and discussions are welcome!  
+No matter which domain you are in, if you work with any signal, we'd love your input.

modusa-0.1.0/README.md

@@ -0,0 +1,58 @@
+# modusa
+
+**modusa**: **Mod**ular **U**nified **S**ignal **A**rchitecture* is a flexible, extensible Python framework for building, transforming, and analyzing different signal representations. It is a domain-agnostic core architecture for modern signal processing workflows.
+
+---
+
+## 🔧 Features
+
+- ⚙️ **modusa Signals**
+- 🧩 **modusa Plugins**
+- 📊 **modusa Genetators**
+- ♻️ **modusa Engine**
+
+---
+
+## 🚀 Installation
+
+> modusa is under active development. You can install the latest version via:
+
+```bash
+git clone https://github.com/meluron/modusa.git
+cd modusa
+pdm install
+```
+
+---
+
+## 🧪 Tests
+
+```bash
+pytest tests/
+```
+
+---
+
+## 🧊 Status
+
+modusa is in **early alpha**. Expect rapid iteration, breaking changes, and big ideas.  
+If you like the direction, consider ⭐ starring the repo and opening issues or ideas.
+
+---
+
+## 🧠 About
+
+**modusa** is developed and maintained by [meluron](https://www.github.com/meluron),
+
+---
+
+## 📜 License
+
+MIT License. See `LICENSE` for details.
+
+---
+
+## 🙌 Contributions
+
+Pull requests, ideas, and discussions are welcome!  
+No matter which domain you are in, if you work with any signal, we'd love your input.

modusa-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "modusa"
+version = "0.1.0"
+description = "A modular signal analysis python library."
+authors = [
+    { name = "Ankit Anand", email = "ankit0.anand0@gmail.com" },
+]
+dependencies = [
+    "jupyter>=1.1.1",
+    "pytest>=8.4.0",
+    "numpy>=2.2.6",
+    "librosa>=0.11.0",
+    "matplotlib>=3.10.3",
+    "pandas>=2.3.0",
+    "pydantic>=2.11.5",
+    "sqlalchemy>=2.0.41",
+    "tqdm>=4.67.1",
+    "sphinx==8.1.2",
+    "sphinx-autodoc-typehints==2.1.0",
+    "sphinx-copybutton>=0.5.2",
+    "furo>=2024.8.6",
+    "questionary>=2.1.0",
+    "rich>=14.0.0",
+    "snakeviz>=2.2.2",
+    "line-profiler>=4.2.0",
+    "nbsphinx==0.9.7",
+    "ghp-import>=2.1.0",
+]
+requires-python = ">=3.12"
+readme = "README.md"
+
+[project.license]
+text = "MIT"
+
+[project.scripts]
+modusa-dev = "modusa.devtools.main:main"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.package-dir]
+"" = "src"

modusa-0.1.0/src/modusa/__init__.py

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

modusa-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/modusa/devtools/list_authors.py

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

modusa-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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