tensor - Validated Arrays

The tensor module provides Pydantic-validated wrappers around numpy arrays. This is Layer 2 of the architecture.

Key Features

Serializable arrays: Numpy arrays that can be serialized/deserialized
Shape validation: Enforce dimensionality constraints
Type safety: Validate dtype and shape at creation time

Classes

Tensor Module

This module provides Pydantic-validated wrappers around numpy arrays. Tensors are serializable, type-safe, and integrate with the pyswark serialization system.

Classes

Vector: A 1-dimensional validated array.
Matrix: A 2-dimensional validated array.
Tensor: Base class for n-dimensional arrays.

Example

>>> from pyswark.tensor.tensor import Vector, Matrix
>>>
>>> v = Vector([1.0, 2.0, 3.0, 4.0, 5.0])
>>> print(v.shape)  # (5,)
>>>
>>> m = Matrix([[1, 2, 3], [4, 5, 6]])
>>> print(m.shape)  # (2, 3)
>>>
>>> # Tensors are serializable
>>> print(v.model_dump())

class pyswark.tensor.tensor.Inputs(*args)

Bases: BaseInputs

Input specification for Tensor creation.

Parameters:

data (array-like) – The array data (list, tuple, or numpy array).
dtype (str, optional) – The numpy dtype (e.g., ‘float64’, ‘int32’).

after()

data: array | List

dtype: Any

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyswark.tensor.tensor.Matrix(inputs=None)

Bases: Tensor

A validated 2-dimensional array.

Validates that the input data is exactly 2-dimensional.

Example

>>> m = Matrix([[1, 2, 3], [4, 5, 6]])
>>> print(m.shape)  # (2, 3)
>>> print(m.matrix)

inputs: Inputs

property matrix: Return the underlying 2D numpy array.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyswark.tensor.tensor.Tensor(inputs=None)

Bases: ConverterModel

Base class for validated numpy arrays.

Wraps numpy arrays with Pydantic validation, enabling serialization and type-safe array operations.

Parameters:: inputs (Inputs or array-like) – The input data specification.

tensor

The underlying numpy array.

Type:: numpy.ndarray

shape

The array shape.

Type:: tuple

classmethod convert(inputs: Inputs) → ndarray

inputs: Inputs

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property shape: Return the shape of the tensor.

property tensor: Return the underlying numpy array.

class pyswark.tensor.tensor.Vector(inputs=None)

Bases: Tensor

A validated 1-dimensional array.

Validates that the input data is exactly 1-dimensional.

Example

>>> v = Vector([1.0, 2.0, 3.0])
>>> print(v.shape)  # (3,)
>>> print(v.vector)  # array([1., 2., 3.])

inputs: Inputs

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property vector: Return the underlying 1D numpy array.

Usage Examples

Creating Vectors

from pyswark.tensor.tensor import Vector
import numpy as np

# Create from list
v = Vector([1.0, 2.0, 3.0, 4.0, 5.0])
print(v.shape)   # (5,)
print(v.vector)  # array([1., 2., 3., 4., 5.])

# Create from numpy array
arr = np.array([10, 20, 30])
v2 = Vector(arr)

# Specify dtype
v3 = Vector([1, 2, 3], dtype='float32')

Creating Matrices

from pyswark.tensor.tensor import Matrix

# Create from nested lists
m = Matrix([[1, 2, 3], [4, 5, 6]])
print(m.shape)   # (2, 3)
print(m.matrix)

# Create from numpy array
arr = np.zeros((3, 4))
m2 = Matrix(arr)

Serialization

Tensors are fully serializable:

from pyswark.tensor.tensor import Vector
from pyswark.lib.pydantic import ser_des

v = Vector([1.0, 2.0, 3.0])

# Serialize to dict
data = v.model_dump()
# {'inputs': {'data': [1.0, 2.0, 3.0], 'dtype': 'float64'}}

# Full serialization with type info
json_str = ser_des.toJson(v)

# Deserialize
restored = ser_des.fromJson(json_str)
assert type(restored) == Vector

Shape Validation

Vectors must be 1-dimensional, Matrices must be 2-dimensional:

from pyswark.tensor.tensor import Vector, Matrix

# This works
v = Vector([1, 2, 3])

# This raises ValueError
try:
    v = Vector([[1, 2], [3, 4]])  # 2D data
except ValueError as e:
    print(e)  # "Array tensor must be 1 dimensional..."

# Similarly for Matrix
m = Matrix([[1, 2], [3, 4]])  # OK
# Matrix([1, 2, 3])  # ValueError - must be 2D