mapFolding 0.12.1__py3-none-any.whl → 0.12.3__py3-none-any.whl

mapFolding/someAssemblyRequired/toolkitNumba.py

@@ -1,30 +1,63 @@
 """
-Numba-specific Tools for Generating Optimized Code
+Map folding AST transformation system: Numba integration and just-in-time compilation optimization.
 
-This module provides specialized tools for transforming standard Python code into
-Numba-accelerated implementations. It implements a comprehensive transformation
-assembly-line that:
+This module provides the compilation optimization layer of the map folding AST transformation system,
+implementing comprehensive tools for applying Numba's just-in-time compilation to functions generated
+by the core transformation tools. Building upon the dataclass decomposition and function optimization
+capabilities established in the operational core, this module completes the transformation process
+by applying aggressive performance optimizations through strategic compiler configuration.
 
-1. Converts dataclass-based algorithm implementations into Numba-compatible versions.
-2. Applies appropriate Numba decorators with optimized configuration settings.
-3. Restructures code to work within Numba's constraints.
-4. Manages type information for optimized compilation.
+The integration addresses the final stage of the transformation process where decomposed, optimized
+functions receive Numba decorators with carefully configured optimization parameters. The module
+handles the complexities of type signature generation, import management, and decorator conflict
+resolution that arise when converting high-level map folding algorithms into machine-optimized code.
 
-The module bridges the gap between readable, maintainable Python code and
-highly-optimized numerical computing implementations, enabling significant
-performance improvements while preserving code semantics and correctness.
+Two primary compilation strategies accommodate different performance and compatibility requirements:
+aggressive optimization for production numerical computing provides maximum performance through
+comprehensive compiler directives including nopython mode, bounds checking elimination, forced
+function inlining, and fastmath optimizations; lightweight optimization maintains broader compatibility
+while achieving significant performance gains through selective compiler optimizations suitable for
+development and testing environments.
+
+The strategic application of these optimization configurations enables map folding calculations that
+require hours or days to complete, transforming abstract mathematical algorithms into highly efficient
+computational modules. The compilation layer integrates seamlessly with the broader transformation
+system to produce standalone modules optimized for specific map dimensions and computational contexts.
 """
 
-from collections.abc import Callable, Sequence
-from mapFolding import NotRequired, TypedDict
-from astToolkit import  IngredientsFunction, Make, str_nameDOTname
-from astToolkit.transformationTools import write_astModule
-from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, cast, Final
+from astToolkit import identifierDotAttribute, IngredientsFunction, Make
+from typing import cast, Final, NotRequired, TYPE_CHECKING, TypedDict
 import ast
 import dataclasses
+import warnings
+
+if TYPE_CHECKING:
+	from collections.abc import Sequence
 
 class ParametersNumba(TypedDict):
+	"""
+	Configuration parameters for Numba compilation decorators.
+
+	This TypedDict defines all possible configuration options that can be passed to Numba's
+	`@jit` decorator to control compilation behavior. The parameters enable fine-tuned control
+	over optimization strategies, debugging features, and runtime behavior.
+
+	Key compilation modes:
+		nopython: Forces compilation without Python fallback for maximum performance
+		cache: Enables compilation result caching to disk for faster subsequent runs
+		fastmath: Allows aggressive mathematical optimizations at cost of IEEE compliance
+		parallel: Enables automatic parallelization of supported operations
+
+	Debug and development options:
+		debug: Enables debug information generation
+		boundscheck: Controls array bounds checking (disabled for performance in production)
+		error_model: Defines how numerical errors are handled ('numpy' vs 'python')
+
+	Only `cache`, `error_model`, and `fastmath` are required fields. All other fields are
+	optional via `NotRequired`, allowing flexible configuration while requiring explicit
+	decisions on critical performance and correctness parameters.
+	"""
+
 	_dbg_extend_lifetimes: NotRequired[bool]
 	_dbg_optnone: NotRequired[bool]
 	_nrt: NotRequired[bool]
@@ -36,7 +69,7 @@ class ParametersNumba(TypedDict):
 	forceinline: NotRequired[bool]
 	forceobj: NotRequired[bool]
 	inline: NotRequired[str]
-	locals: NotRequired[dict[str, Any]]
+	# locals: NotRequired[dict[str, Any]]
 	looplift: NotRequired[bool]
 	no_cfunc_wrapper: NotRequired[bool]
 	no_cpython_wrapper: NotRequired[bool]
@@ -44,35 +77,154 @@ class ParametersNumba(TypedDict):
 	nogil: NotRequired[bool]
 	nopython: NotRequired[bool]
 	parallel: NotRequired[bool]
-	pipeline_class: NotRequired[type[numbaCompilerBase]]
-	signature_or_function: NotRequired[Any | Callable[..., Any] | str | tuple[Any, ...]]
+	# pipeline_class: NotRequired[type[numbaCompilerBase]]
+	# signature_or_function: NotRequired[Any | Callable[..., Any] | str | tuple[Any, ...]]
 	target: NotRequired[str]
 
-parametersNumbaDefault: Final[ParametersNumba] = { '_nrt': True, 'boundscheck': False, 'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True, 'inline': 'always', 'looplift': False, 'no_cfunc_wrapper': False, 'no_cpython_wrapper': False, 'nopython': True, 'parallel': False, }
-"""Middle of the road: fast, lean, but will talk to non-jitted functions."""
+parametersNumbaDefault: Final[ParametersNumba] = { '_nrt': True, 'boundscheck': False, 'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True, 'inline': 'always', 'looplift': False, 'no_cfunc_wrapper': False, 'no_cpython_wrapper': False, 'nopython': True, 'parallel': False }
+"""
+Comprehensive Numba configuration for maximum performance optimization.
+
+This configuration provides aggressive optimization settings suitable for production
+numerical computing code. Key characteristics:
+	Enables nopython mode for full compilation without Python fallback
+	Disables bounds checking for maximum array access performance
+	Forces function inlining with 'always' policy for reduced call overhead
+	Uses numpy error model for consistent numerical behavior
+	Enables fastmath for aggressive floating-point optimizations
+	Disables loop lifting to prevent unexpected performance penalties
+
+The configuration prioritizes execution speed over compatibility, producing highly
+optimized machine code at the cost of reduced interoperability with uncompiled
+Python functions.
+"""
+
 parametersNumbaLight: Final[ParametersNumba] = {'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True}
+"""
+Minimal Numba configuration for basic optimization with maximum compatibility.
+
+This lightweight configuration provides essential optimizations while maintaining
+broad compatibility with existing Python code. Suitable for:
+	Development and debugging phases
+	Code that needs to interoperate with non-Numba functions
+	Situations where full nopython mode causes compilation issues
+
+Key features:
+	Enables compilation caching for faster subsequent runs
+	Uses numpy error model for consistent mathematical behavior
+	Enables fastmath and function inlining for performance gains
+	Allows Python object mode fallback when needed
+"""
+
+Z0Z_numbaDataTypeModule: identifierDotAttribute = 'numba'
+"""
+Module identifier for Numba imports and type annotations.
+
+This constant specifies the module path used when importing Numba-specific types and decorators
+in generated code. It serves as the single source of truth for the Numba module reference,
+enabling consistent import statements across all generated functions.
+"""
 
-Z0Z_numbaDataTypeModule: str_nameDOTname = 'numba'
 Z0Z_decoratorCallable: str = 'jit'
+"""
+The Numba decorator function name used for just-in-time compilation.
+
+This constant identifies the specific Numba decorator applied to functions for compilation.
+While Numba offers multiple decorators (`@jit`, `@njit`, `@vectorize`), this toolkit focuses
+on the general-purpose `@jit` decorator with configurable parameters for flexibility.
+"""
+
+def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:  # noqa: C901
+	"""Transform a Python function into a Numba-accelerated version with appropriate decorators.
+
+	(AI generated docstring)
 
-def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:
+	This function applies Numba's `@jit` decorator to an existing function definition within
+	an `IngredientsFunction` container. It handles the complete transformation pipeline
+	including removing any existing decorators that might conflict with Numba, constructing
+	type signatures for Numba compilation when possible, applying the `@jit` decorator with
+	specified or default parameters, and updating import requirements to include necessary
+	Numba modules.
+
+	The transformation preserves function semantics while enabling significant performance
+	improvements through just-in-time compilation. Type inference is attempted for
+	function parameters and return values to enable optimized compilation paths.
+
+	Parameters
+	----------
+	ingredientsFunction : IngredientsFunction
+		Container holding the function definition and associated metadata.
+	parametersNumba : ParametersNumba | None = None
+		Optional Numba configuration; uses `parametersNumbaDefault` if `None`.
+
+	Returns
+	-------
+	ingredientsFunction : IngredientsFunction
+		Modified `IngredientsFunction` with Numba decorator applied and imports updated.
+
+	"""
 	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
-		# TODO: more explicit handling of decorators. I'm able to ignore this because I know `algorithmSource` doesn't have any decorators.
+		"""Remove existing decorators from function definition to prevent conflicts with Numba.
+
+		(AI generated docstring)
+
+		Numba compilation can be incompatible with certain Python decorators, so this
+		function strips all existing decorators from a function definition before
+		applying the Numba `@jit` decorator. Removed decorators are logged as warnings
+		for debugging purposes.
+
+		TODO: Implement more sophisticated decorator handling that can preserve
+		compatible decorators and intelligently handle decorator composition.
+
+		Parameters
+		----------
+		astCallable : ast.FunctionDef
+			Function definition AST node to process.
+
+		Returns
+		-------
+		astCallable : ast.FunctionDef
+			Function definition with decorator list cleared.
+
+		"""
+		# TODO more explicit handling of decorators. I'm able to ignore this because I know `algorithmSource` doesn't have any decorators.
 		for decoratorItem in astCallable.decorator_list.copy():
-			import warnings
 			astCallable.decorator_list.remove(decoratorItem)
-			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}")
+			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}", stacklevel=2)
 		return astCallable
 
 	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None: # pyright: ignore[reportUnusedFunction]
+		"""Generate Numba-compatible type signatures for function parameters.
+
+		(AI generated docstring)
+
+		This function analyzes function parameter type annotations and converts them into
+		Numba-compatible type signature expressions. It handles various annotation patterns
+		including array types with shape and dtype information, scalar types with simple
+		name annotations, and complex subscripted types requiring special handling.
+
+		The generated signatures enable Numba to perform more efficient compilation by
+		providing explicit type information rather than relying solely on type inference.
+
+		Parameters
+		----------
+		signatureElement : ast.arg
+			Function parameter with type annotation to convert.
+
+		Returns
+		-------
+		ast.Subscript | ast.Name | None
+			Numba-compatible type signature AST node, or None if conversion not possible.
+
+		"""
 		if isinstance(signatureElement.annotation, ast.Subscript) and isinstance(signatureElement.annotation.slice, ast.Tuple):
 			annotationShape: ast.expr = signatureElement.annotation.slice.elts[0]
 			if isinstance(annotationShape, ast.Subscript) and isinstance(annotationShape.slice, ast.Tuple):
 				shapeAsListSlices: list[ast.Slice] = [ast.Slice() for _axis in range(len(annotationShape.slice.elts))]
-				shapeAsListSlices[-1] = ast.Slice(step=ast.Constant(value=1))
-				shapeAST: ast.Slice | ast.Tuple = ast.Tuple(elts=list(shapeAsListSlices), ctx=ast.Load())
+				shapeAsListSlices[-1] = Make.Slice(step=Make.Constant(1))
+				shapeAST: ast.Slice | ast.Tuple = Make.Tuple(list(shapeAsListSlices))
 			else:
-				shapeAST = ast.Slice(step=ast.Constant(value=1))
+				shapeAST = Make.Slice(step=Make.Constant(1))
 
 			annotationDtype: ast.expr = signatureElement.annotation.slice.elts[1]
 			if (isinstance(annotationDtype, ast.Subscript) and isinstance(annotationDtype.slice, ast.Attribute)):
@@ -84,9 +236,9 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 			Z0Z_hacky_dtype: str = ndarrayName
 			datatype_attr = datatypeAST or Z0Z_hacky_dtype
 			ingredientsFunction.imports.addImportFrom_asStr(datatypeModuleDecorator, datatype_attr)
-			datatypeNumba = ast.Name(id=datatype_attr, ctx=ast.Load())
+			datatypeNumba = Make.Name(datatype_attr)
 
-			return ast.Subscript(value=datatypeNumba, slice=shapeAST, ctx=ast.Load())
+			return Make.Subscript(datatypeNumba, slice=shapeAST)
 
 		elif isinstance(signatureElement.annotation, ast.Name):
 			return signatureElement.annotation
@@ -105,15 +257,16 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 	if ingredientsFunction.astFunctionDef.returns and isinstance(ingredientsFunction.astFunctionDef.returns, ast.Name):
 		theReturn: ast.Name = ingredientsFunction.astFunctionDef.returns
-		list_argsDecorator = [cast(ast.expr, ast.Call(func=ast.Name(id=theReturn.id, ctx=ast.Load())
-							, args=list_arg4signature_or_function if list_arg4signature_or_function else [], keywords=[] ) )]
+		list_argsDecorator = [cast("ast.expr", Make.Call(Make.Name(theReturn.id)
+							, list_arg4signature_or_function if list_arg4signature_or_function else [], [] ) )]
 	elif list_arg4signature_or_function:
-		list_argsDecorator = [cast(ast.expr, ast.Tuple(elts=list_arg4signature_or_function, ctx=ast.Load()))]
+		list_argsDecorator = [cast("ast.expr", Make.Tuple(list_arg4signature_or_function))]
 
 	ingredientsFunction.astFunctionDef = Z0Z_UnhandledDecorators(ingredientsFunction.astFunctionDef)
 	if parametersNumba is None:
 		parametersNumba = parametersNumbaDefault
-	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()]
+
+	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()] # pyright: ignore[reportArgumentType]
 
 	decoratorModule = Z0Z_numbaDataTypeModule
 	decoratorCallable = Z0Z_decoratorCallable
@@ -127,6 +280,35 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 @dataclasses.dataclass
 class SpicesJobNumba:
+	"""Configuration container for Numba-specific job processing options.
+
+	(AI generated docstring)
+
+	This dataclass encapsulates configuration settings that control how Numba
+	compilation and execution is applied to job processing functions. It provides
+	a centralized way to manage Numba-specific settings that affect both
+	compilation behavior and runtime features like progress reporting.
+
+	The class serves as a bridge between the generic job processing system and
+	Numba's specialized requirements, enabling consistent application of
+	optimization settings across different computational contexts.
+
+	Attributes
+	----------
+	useNumbaProgressBar : bool
+		Enable progress bar display for long-running computations.
+	numbaProgressBarIdentifier : str
+		Progress bar implementation identifier.
+	parametersNumba : ParametersNumba
+		Numba compilation parameters with sensible defaults.
+
+	"""
+
 	useNumbaProgressBar: bool = True
+	"""Enable progress bar display for Numba-compiled functions with long execution times."""
+
 	numbaProgressBarIdentifier: str = 'ProgressBarGroupsOfFolds'
+	"""Identifier for the progress bar implementation used in Numba-compiled code."""
+
 	parametersNumba: ParametersNumba = dataclasses.field(default_factory=ParametersNumba)  # pyright: ignore[reportArgumentType, reportCallIssue, reportUnknownVariableType]
+	"""Numba compilation parameters; defaults to empty dict allowing decorator defaults."""

mapFolding/someAssemblyRequired/transformationTools.py

@@ -1,47 +1,43 @@
 """
-AST Transformation Tools for Python Code Generation
-
-This module provides tools for manipulating and transforming Python abstract syntax trees
-to generate optimized code. It implements a system that:
-
-1. Extracts functions and classes from existing modules.
-2. Reshapes and transforms them through AST manipulation.
-3. Manages dependencies and imports.
-4. Generates optimized code with specialized implementations.
-
-The module is particularly focused on transforming general-purpose Python code into
-high-performance implementations, especially through dataclass decomposition and
-function inlining for Numba compatibility.
-
-At its core, the module implements a transformation assembly-line where code flows from
-readable, maintainable implementations to highly optimized versions while preserving
-logical structure and correctness.
+Map folding AST transformation system: Core dataclass decomposition and function optimization tools.
+
+This module implements the essential transformation capabilities that form the operational core of
+the map folding AST transformation system. Working with the pattern recognition foundation and
+decomposition containers established in the foundational layers, these tools execute the critical
+transformations that convert dataclass-based functions into optimized implementations suitable
+for Numba just-in-time compilation.
+
+The transformation process addresses the fundamental incompatibility between dataclass-dependent
+map folding algorithms and Numba's compilation requirements. While dataclass instances provide
+clean, maintainable interfaces for complex mathematical state, Numba cannot directly process
+these objects but excels at optimizing operations on primitive values and tuples. The tools
+bridge this architectural gap through systematic function signature transformation and calling
+convention adaptation.
+
+The three-stage transformation pattern implemented here follows a precise sequence: dataclass
+decomposition breaks down dataclass definitions into constituent AST components while extracting
+field definitions and type annotations; function transformation converts functions accepting
+dataclass parameters to functions accepting individual field parameters with updated signatures
+and return types; caller adaptation modifies calling code to unpack dataclass instances, invoke
+transformed functions, and repack results back into dataclass instances.
+
+This approach enables seamless integration between high-level dataclass-based interfaces and
+low-level optimized implementations, maintaining code clarity while achieving performance gains
+through specialized compilation paths essential for computationally intensive map folding research.
 """
 
-from astToolkit import ClassIsAndAttribute
-from mapFolding.someAssemblyRequired import (
-	DeReConstructField2ast,
-	IfThis,
-	ShatteredDataclass,
-)
-from astToolkit import(
-	Be,
-	extractClassDef,
-	IngredientsFunction,
-	Make,
-	NodeChanger,
-	parseLogicalPath2astModule,
-	str_nameDOTname,
-	Then,
-)
+from astToolkit import (
+	Be, extractClassDef, identifierDotAttribute, IngredientsFunction, Make, NodeChanger, parseLogicalPath2astModule, Then)
 from astToolkit.transformationTools import unparseFindReplace
-from Z0Z_tools import importLogicalPath2Callable
+from hunterMakesPy import importLogicalPath2Identifier
+from mapFolding.someAssemblyRequired import DeReConstructField2ast, IfThis, ShatteredDataclass
 import ast
 import dataclasses
 
-def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclassIdentifier: str, instanceIdentifier: str) -> ShatteredDataclass:
-	"""
-	Decompose a dataclass definition into AST components for manipulation and code generation.
+def shatter_dataclassesDOTdataclass(logicalPathModule: identifierDotAttribute, dataclassIdentifier: str, instanceIdentifier: str) -> ShatteredDataclass:
+	"""Decompose a dataclass definition into AST components for manipulation and code generation.
+
+	(AI generated docstring)
 
 	This function breaks down a complete dataclass (like ComputationState) into its constituent
 	parts as AST nodes, enabling fine-grained manipulation of its fields for code generation.
@@ -57,35 +53,44 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 	where dataclass instances can't be directly used but their fields need to be individually
 	manipulated and passed to computational functions.
 
-	Parameters:
-		logicalPathModule: The fully qualified module path containing the dataclass definition.
-		dataclassIdentifier: The name of the dataclass to decompose.
-		instanceIdentifier: The variable name to use for the dataclass instance in generated code.
-
-	Returns:
-		shatteredDataclass: A ShatteredDataclass containing AST representations of all dataclass components,
-			with imports, field definitions, annotations, and repackaging code.
+	Parameters
+	----------
+	logicalPathModule : identifierDotAttribute
+		The fully qualified module path containing the dataclass definition.
+	dataclassIdentifier : str
+		The name of the dataclass to decompose.
+	instanceIdentifier : str
+		The variable name to use for the dataclass instance in generated code.
+
+	Returns
+	-------
+	ShatteredDataclass
+		A ShatteredDataclass containing AST representations of all dataclass components,
+		with imports, field definitions, annotations, and repackaging code.
+
+	Raises
+	------
+	ValueError
+		If the dataclass cannot be found in the specified module or if no counting variable is identified in the dataclass.
 
-	Raises:
-		ValueError: If the dataclass cannot be found in the specified module or if no counting variable is identified in the dataclass.
 	"""
 	Official_fieldOrder: list[str] = []
 	dictionaryDeReConstruction: dict[str, DeReConstructField2ast] = {}
 
-	dataclassClassDef = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclassIdentifier)
-	if not isinstance(dataclassClassDef, ast.ClassDef): raise ValueError(f"I could not find `{dataclassIdentifier = }` in `{logicalPathModule = }`.")
+	dataclassClassDef: ast.ClassDef | None = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclassIdentifier)
+	if not dataclassClassDef:
+		message = f"I could not find `{dataclassIdentifier = }` in `{logicalPathModule = }`."
+		raise ValueError(message)
 
 	countingVariable = None
-	for aField in dataclasses.fields(importLogicalPath2Callable(logicalPathModule, dataclassIdentifier)): # pyright: ignore [reportArgumentType]
+	for aField in dataclasses.fields(importLogicalPath2Identifier(logicalPathModule, dataclassIdentifier)): # pyright: ignore [reportArgumentType]
 		Official_fieldOrder.append(aField.name)
 		dictionaryDeReConstruction[aField.name] = DeReConstructField2ast(logicalPathModule, dataclassClassDef, instanceIdentifier, aField)
 		if aField.metadata.get('theCountingIdentifier', False):
 			countingVariable = dictionaryDeReConstruction[aField.name].name
-
 	if countingVariable is None:
-		import warnings
-		warnings.warn(message=f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`.", category=UserWarning)
-		raise Exception
+		message = f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`."
+		raise ValueError(message)
 
 	shatteredDataclass = ShatteredDataclass(
 		countingVariableAnnotation=dictionaryDeReConstruction[countingVariable].astAnnotation,
@@ -109,7 +114,36 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 	return shatteredDataclass
 
 def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shatteredDataclass: ShatteredDataclass) -> IngredientsFunction:
-	ingredientsTarget.astFunctionDef.args = Make.arguments(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
+	"""Transform a function that operates on dataclass instances to work with individual field parameters.
+
+	(AI generated docstring)
+
+	This function performs the core transformation required for Numba compatibility by removing dataclass
+	dependencies from function signatures and implementations. It modifies the target function to:
+
+	1. Replace the single dataclass parameter with individual field parameters.
+	2. Update the return type annotation to return a tuple of field values.
+	3. Transform return statements to return the tuple of fields.
+	4. Replace all dataclass attribute access with direct field variable access.
+
+	This transformation is essential for creating Numba-compatible functions from dataclass-based
+	implementations, as Numba cannot handle dataclass instances directly but can efficiently
+	process individual primitive values and tuples.
+
+	Parameters
+	----------
+	ingredientsTarget : IngredientsFunction
+		The function definition and its dependencies to be transformed.
+	shatteredDataclass : ShatteredDataclass
+		The decomposed dataclass components providing AST mappings and transformations.
+
+	Returns
+	-------
+	IngredientsFunction
+		The modified function ingredients with dataclass dependencies removed.
+
+	"""
+	ingredientsTarget.astFunctionDef.args = Make.arguments(list_arg=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
 	ingredientsTarget.astFunctionDef.returns = shatteredDataclass.signatureReturnAnnotation
 	changeReturnCallable = NodeChanger(Be.Return, Then.replaceWith(Make.Return(shatteredDataclass.fragments4AssignmentOrParameters)))
 	changeReturnCallable.visit(ingredientsTarget.astFunctionDef)
@@ -117,10 +151,43 @@ def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shattere
 	return ingredientsTarget
 
 def unpackDataclassCallFunctionRepackDataclass(ingredientsCaller: IngredientsFunction, targetCallableIdentifier: str, shatteredDataclass: ShatteredDataclass) -> IngredientsFunction:
+	"""Transform a caller function to interface with a dataclass-free target function.
+
+	(AI generated docstring)
+
+	This function complements `removeDataclassFromFunction` by modifying calling code to work with
+	the transformed target function. It implements the unpacking and repacking pattern required
+	when a dataclass-based caller needs to invoke a function that has been converted to accept
+	individual field parameters instead of dataclass instances.
+
+	The transformation creates a three-step pattern around the target function call:
+	1. Unpack the dataclass instance into individual field variables.
+	2. Call the target function with the unpacked field values.
+	3. Repack the returned field values back into a dataclass instance.
+
+	This enables seamless integration between dataclass-based high-level code and optimized
+	field-based implementations, maintaining the original interface while enabling performance
+	optimizations in the target function.
+
+	Parameters
+	----------
+	ingredientsCaller : IngredientsFunction
+		The calling function definition and its dependencies to be transformed.
+	targetCallableIdentifier : str
+		The name of the target function being called.
+	shatteredDataclass : ShatteredDataclass
+		The decomposed dataclass components providing unpacking and repacking logic.
+
+	Returns
+	-------
+	IngredientsFunction
+		The modified caller function with appropriate unpacking and repacking around the target call.
+
+	"""
 	astCallTargetCallable = Make.Call(Make.Name(targetCallableIdentifier), shatteredDataclass.listName4Parameters)
-	replaceAssignTargetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.replaceWith(Make.Assign([shatteredDataclass.fragments4AssignmentOrParameters], value=astCallTargetCallable)))
-	unpack4targetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))
-	repack4targetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisBelow([shatteredDataclass.repack]))
+	replaceAssignTargetCallable = NodeChanger(Be.Assign.valueIs(IfThis.isCallIdentifier(targetCallableIdentifier)), Then.replaceWith(Make.Assign([shatteredDataclass.fragments4AssignmentOrParameters], value=astCallTargetCallable)))
+	unpack4targetCallable = NodeChanger(Be.Assign.valueIs(IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))
+	repack4targetCallable = NodeChanger(Be.Assign.valueIs(IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisBelow([shatteredDataclass.repack]))
 	replaceAssignTargetCallable.visit(ingredientsCaller.astFunctionDef)
 	unpack4targetCallable.visit(ingredientsCaller.astFunctionDef)
 	repack4targetCallable.visit(ingredientsCaller.astFunctionDef)