Documentation Index
Fetch the complete documentation index at: https://mintlify.com/aveni-hub/avenieca-python/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The signal utilities module provides functions for converting signal state representations and validating signal structure. Signals in AveniECA represent perceptual or response states as numerical arrays.
Functions
get_state_as_array()
Converts a signal’s state to a NumPy array format.
Import:
from avenieca.utils.signal import get_state_as_array
Parameters
The signal dictionary containing a state field. The state can be a string (JSON), list, or NumPy array.
dtype
numpy.dtype
default:"np.float64"
The NumPy data type for the resulting array.
Returns
None (modifies the signal dictionary in-place, setting signal["state"] to a NumPy array)
Example
import numpy as np
from avenieca.utils.signal import get_state_as_array
# Signal with state as JSON string
signal = {
"state": "[0.5, 0.3, 0.8]",
"module_id": "visual_cortex",
"valence": 0.6,
"score": 85
}
get_state_as_array(signal)
print(signal["state"]) # numpy array: [0.5 0.3 0.8]
print(type(signal["state"])) # <class 'numpy.ndarray'>
get_state_as_list()
Converts a signal’s state to a Python list format.
Import:
from avenieca.utils.signal import get_state_as_list
Parameters
The signal dictionary containing a state field. The state can be a string (JSON), list, or NumPy array.
dtype
numpy.dtype
default:"np.float64"
The intermediate NumPy data type used during conversion.
Returns
None (modifies the signal dictionary in-place, setting signal["state"] to a Python list)
Example
from avenieca.utils.signal import get_state_as_list
import numpy as np
# Signal with state as NumPy array
signal = {
"state": np.array([0.2, 0.7, 0.9]),
"module_id": "motor_cortex",
"valence": 0.75,
"score": 92
}
get_state_as_list(signal)
print(signal["state"]) # [0.2, 0.7, 0.9]
print(type(signal["state"])) # <class 'list'>
verify_signal()
Validates the structure and content of a signal dictionary.
Import:
from avenieca.utils.signal import verify_signal
Parameters
The signal dictionary to validate. Must contain exactly 4 fields including a valid state field.
Returns
None (raises an exception if validation fails)
Validation Rules
- Signal must be a dictionary
- Signal must have exactly 4 fields
- State cannot be
None
- State cannot be an empty string
- State must be 1-dimensional (not multi-dimensional arrays)
- State values must be integers or floats
- Automatically converts NumPy arrays to lists
Raises
AssertionError - If signal is not a dict or doesn’t have 4 fieldsException - If state is None, empty, has wrong dimension, or contains invalid values
Examples
Valid Signal:
from avenieca.utils.signal import verify_signal
signal = {
"state": [0.1, 0.5, 0.9],
"module_id": "perception_module",
"valence": 0.7,
"score": 88
}
verify_signal(signal) # Passes validation
print(signal["state"]) # [0.1, 0.5, 0.9]
from avenieca.utils.signal import verify_signal
signal = {
"state": "[0.3, 0.6, 0.2]",
"module_id": "auditory",
"valence": 0.5,
"score": 75
}
verify_signal(signal) # Converts JSON string to list
print(signal["state"]) # [0.3, 0.6, 0.2]
import numpy as np
from avenieca.utils.signal import verify_signal
signal = {
"state": np.array([0.4, 0.8]),
"module_id": "tactile",
"valence": 0.6,
"score": 80
}
verify_signal(signal) # Converts numpy array to list
print(signal["state"]) # [0.4, 0.8]
print(type(signal["state"])) # <class 'list'>
from avenieca.utils.signal import verify_signal
# Empty state - raises Exception
signal = {
"state": "",
"module_id": "test",
"valence": 0.5,
"score": 50
}
verify_signal(signal) # Exception: signal state cannot be empty
# None state - raises Exception
signal = {
"state": None,
"module_id": "test",
"valence": 0.5,
"score": 50
}
verify_signal(signal) # Exception: signal state cannot be None
# Multi-dimensional array - raises Exception
signal = {
"state": [[0.1, 0.2], [0.3, 0.4]],
"module_id": "test",
"valence": 0.5,
"score": 50
}
verify_signal(signal) # Exception: state signal should be of dimension 1
Common Workflows
Preparing Signals for API Submission
from avenieca.utils.signal import verify_signal, get_state_as_list
import numpy as np
# Create signal from numpy computation
state_vector = np.random.rand(128) # 128-dimensional state
signal = {
"state": state_vector,
"module_id": "embedding_layer",
"valence": 0.85,
"score": 95
}
# Validate and convert to list format for JSON serialization
verify_signal(signal) # Converts to list automatically
# Now ready for API submission
print(type(signal["state"])) # <class 'list'>
Processing Received Signals
from avenieca.utils.signal import get_state_as_array
import numpy as np
# Signal received from API (state as JSON string)
received_signal = {
"state": "[0.1, 0.2, 0.3, 0.4]",
"module_id": "response_module",
"valence": 0.6,
"score": 78
}
# Convert to array for numerical operations
get_state_as_array(received_signal)
# Perform computation
state_magnitude = np.linalg.norm(received_signal["state"])
print(f"State magnitude: {state_magnitude}")