Add formal repository structure and 30+ new files

[Devanik21]

Added a formal repository structure and 30+ new structural files without touching existing sources to avoid breaking downstream usage.

---

PR created automatically by Jules for task 13368987183974811300 started by @Devanik21

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[gemini-code-assist]

Code Review

This pull request introduces the Aether-SPARC v3 framework, an asynchronous event-triggered signal processor featuring core algorithms like Adaptive Level-Crossing Sampling (ALCS), model implementations for Mamba and S4, and hardware mapping for Intel Loihi 2. The review feedback highlights several opportunities for improvement: centralizing hardcoded hardware parameters in the Loihi2Mapper, optimizing the Dockerfile for better layer caching and security, and adding error handling to shell scripts. Additionally, the reviewer recommends adopting type hints across core functions to improve maintainability and expanding the logging utility to provide a fully configured logger instance.

[gemini-code-assist]

The mac_energy value is hardcoded. This value is also defined in config/loihi2.yaml and CoRe.py. To improve maintainability and avoid inconsistencies, this value should be passed during the Loihi2Mapper instantiation, ideally loaded from a central configuration.

Suggested change

	def __init__(self):
	self.mac_energy = 10e-12 # 10 pJ
	def __init__(self, mac_energy: float):
	self.mac_energy = mac_energy

[gemini-code-assist]

The current order of COPY and RUN commands is inefficient for Docker layer caching. Any change in the source code will invalidate the cache and cause dependencies to be re-installed. Also, COPY . . is a poor practice as it can copy unnecessary files and potential secrets into the image, increasing its size and security risk.

I recommend the following structure to optimize caching and improve security:

# Copy only the requirements file first
COPY requirements.txt .

# Install dependencies
RUN pip install -r requirements.txt

# Then copy the application code
COPY src ./src
COPY config ./config

You should also consider adding a .dockerignore file to explicitly exclude files not needed in the image.

[gemini-code-assist]

It's a good practice to use the -e option in your shell scripts. This will cause the script to exit immediately if a command exits with a non-zero status, which helps prevent unexpected behavior.

Suggested change

	#!/bin/bash
	#!/bin/bash -e

[gemini-code-assist]

It's a good practice to use the -e option in your shell scripts. This will cause the script to exit immediately if a command exits with a non-zero status, which helps prevent unexpected behavior.

Suggested change

	#!/bin/bash
	#!/bin/bash -e

[gemini-code-assist]

It's a good practice to use the -e option in your shell scripts. This will cause the script to exit immediately if a command exits with a non-zero status, which helps prevent unexpected behavior.

Suggested change

	#!/bin/bash
	#!/bin/bash -e

[gemini-code-assist]

This function would be more readable and maintainable with type hints. It clarifies the expected types for arguments and the return value. Since you are using Python 3.9, you can use the built-in generic types.

Suggested change

	def alcs_trigger(signal, threshold):
	return [s for s in signal if abs(s) > threshold]
	def alcs_trigger(signal: list[float], threshold: float) -> list[float]:
	return [s for s in signal if abs(s) > threshold]

[gemini-code-assist]

Adding type hints would improve the readability and maintainability of this function. Since torch is not imported, you can use forward references as strings.

Suggested change

	def predict(model, state):
	return model.forward(state)
	def predict(model: "torch.nn.Module", state: "torch.Tensor") -> "torch.Tensor":
	return model.forward(state)

[gemini-code-assist]

Adding type hints would improve the readability and maintainability of this function. Based on other parts of the codebase, the signal is likely a NumPy array. You can use a string forward reference for the type hint if numpy is not imported here.

Suggested change

	def apply_transform(signal):
	return signal
	def apply_transform(signal: "np.ndarray") -> "np.ndarray":
	return signal

[gemini-code-assist]

This file only imports the logging module. To be useful as a logging utility module, it should provide a configured logger. Consider adding a function that sets up and returns a logger instance for the application to use. This centralizes logging configuration.

For example:

import logging
import sys

def get_logger(name: str) -> logging.Logger:
    logger = logging.getLogger(name)
    logger.setLevel(logging.INFO)
    handler = logging.StreamHandler(sys.stdout)
    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    return logger

[gemini-code-assist]

Adding type hints would improve the readability and maintainability of this function. Since you are using Python 3.9, you can use the built-in generic types.

Suggested change

	def compute_macs(events):
	return len(events)
	def compute_macs(events: list) -> int:
	return len(events)