Rename spread to map

Author: dmontagu

docs/graph/beta/decisions.md

@@ -420,6 +420,6 @@ _(This example is complete, it can be run "as is" — you'll need to add `import
 
 ## Next Steps
 
-- Learn about [parallel execution](parallel.md) with broadcasting and spreading
+- Learn about [parallel execution](parallel.md) with broadcasting and mapping
 - Understand [join nodes](joins.md) for aggregating parallel results
 - See the [API reference][pydantic_graph.beta.decision] for complete decision documentation

docs/graph/beta/index.md

@@ -118,7 +118,7 @@ Every graph has:
 
 ## A More Complex Example
 
-Here's an example showcasing parallel execution with a spread operation:
+Here's an example showcasing parallel execution with a map operation:
 
 ```python {title="parallel_processing.py"}
 from dataclasses import dataclass
@@ -149,9 +149,9 @@ async def main():
     # Create a join to collect results
     collect_results = g.join(ListReducer[int])
 
-    # Build the graph with spread operation
+    # Build the graph with map operation
     g.add(
-        g.edge_from(g.start_node).spread().to(square),
+        g.edge_from(g.start_node).map().to(square),
         g.edge_from(square).to(collect_results),
         g.edge_from(collect_results).to(g.end_node),
     )
@@ -171,7 +171,7 @@ _(This example is complete, it can be run "as is" — you'll need to add `import
 In this example:
 
 1. The start node receives a list of integers
-2. The `.spread()` operation fans out each item to a separate parallel execution of the `square` step
+2. The `.map()` operation fans out each item to a separate parallel execution of the `square` step
 3. All results are collected back together using a [`ListReducer`][pydantic_graph.beta.join.ListReducer]
 4. The joined results flow to the end node
 
@@ -182,15 +182,15 @@ Explore the detailed documentation for each feature:
 - [**Steps**](steps.md) - Learn about step nodes and execution contexts
 - [**Joins**](joins.md) - Understand join nodes and reducer patterns
 - [**Decisions**](decisions.md) - Implement conditional branching
-- [**Parallel Execution**](parallel.md) - Master broadcasting and spreading
+- [**Parallel Execution**](parallel.md) - Master broadcasting and mapping
 
 ## Comparison with Original API
 
 The original graph API (documented in the [main graph page](../../graph.md)) uses a class-based approach with [`BaseNode`][pydantic_graph.nodes.BaseNode] subclasses. The beta API uses a builder pattern with decorated functions, which provides:
 
 **Advantages:**
 - More concise syntax for simple workflows
-- Explicit control over parallelism with spread/broadcast
+- Explicit control over parallelism with map/broadcast
 - Built-in reducers for common aggregation patterns
 - Easier to visualize complex data flows
 

docs/graph/beta/joins.md

@@ -4,7 +4,7 @@ Join nodes synchronize and aggregate data from parallel execution paths. They us
 
 ## Overview
 
-When you use [parallel execution](parallel.md) (broadcasting or spreading), you often need to collect and combine the results. Join nodes serve this purpose by:
+When you use [parallel execution](parallel.md) (broadcasting or mapping), you often need to collect and combine the results. Join nodes serve this purpose by:
 
 1. Waiting for all parallel tasks to complete
 2. Aggregating their outputs using a [`Reducer`][pydantic_graph.beta.join.Reducer]
@@ -41,7 +41,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate_numbers),
-        g.edge_from(generate_numbers).spread().to(square),
+        g.edge_from(generate_numbers).map().to(square),
         g.edge_from(square).to(collect),
         g.edge_from(collect).to(g.end_node),
     )
@@ -88,7 +88,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate),
-        g.edge_from(generate).spread().to(to_string),
+        g.edge_from(generate).map().to(to_string),
         g.edge_from(to_string).to(collect),
         g.edge_from(collect).to(g.end_node),
     )
@@ -131,7 +131,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate_keys),
-        g.edge_from(generate_keys).spread().to(create_entry),
+        g.edge_from(generate_keys).map().to(create_entry),
         g.edge_from(create_entry).to(merge),
         g.edge_from(merge).to(g.end_node),
     )
@@ -180,7 +180,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate),
-        g.edge_from(generate).spread().to(accumulate),
+        g.edge_from(generate).map().to(accumulate),
         g.edge_from(accumulate).to(ignore),
         g.edge_from(ignore).to(get_total),
         g.edge_from(get_total).to(g.end_node),
@@ -240,7 +240,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate),
-        g.edge_from(generate).spread().to(identity),
+        g.edge_from(generate).map().to(identity),
         g.edge_from(identity).to(sum_join),
         g.edge_from(sum_join).to(g.end_node),
     )
@@ -311,7 +311,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate),
-        g.edge_from(generate).spread().to(process),
+        g.edge_from(generate).map().to(process),
         g.edge_from(process).to(metrics),
         g.edge_from(metrics).to(g.end_node),
     )
@@ -381,8 +381,8 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(source_a, source_b),
-        g.edge_from(source_a).spread().to(process_a),
-        g.edge_from(source_b).spread().to(process_b),
+        g.edge_from(source_a).map().to(process_a),
+        g.edge_from(source_b).map().to(process_b),
         g.edge_from(process_a).to(join_a),
         g.edge_from(process_b).to(join_b),
         g.edge_from(join_a).to(store_a),
@@ -429,6 +429,6 @@ This ensures proper synchronization even with nested parallel operations.
 
 ## Next Steps
 
-- Learn about [parallel execution](parallel.md) with broadcasting and spreading
+- Learn about [parallel execution](parallel.md) with broadcasting and mapping
 - Explore [conditional branching](decisions.md) with decision nodes
 - See the [API reference][pydantic_graph.beta.join] for complete reducer documentation

docs/graph/beta/parallel.md

@@ -1,6 +1,6 @@
 # Parallel Execution
 
-The beta graph API provides two powerful mechanisms for parallel execution: **broadcasting** and **spreading**.
+The beta graph API provides two powerful mechanisms for parallel execution: **broadcasting** and **mapping**.
 
 ## Overview
 
@@ -67,7 +67,7 @@ All three steps receive the same input value (`10`) and execute in parallel.
 
 Spreading fans out elements from an iterable, processing each element in parallel:
 
-```python {title="basic_spread.py"}
+```python {title="basic_map.py"}
 from dataclasses import dataclass
 
 from pydantic_graph.beta import GraphBuilder, ListReducer, StepContext
@@ -94,7 +94,7 @@ async def main():
     # Spreading: each item in the list gets its own parallel execution
     g.add(
         g.edge_from(g.start_node).to(generate_list),
-        g.edge_from(generate_list).spread().to(square),
+        g.edge_from(generate_list).map().to(square),
         g.edge_from(square).to(collect),
         g.edge_from(collect).to(g.end_node),
     )
@@ -107,11 +107,11 @@ async def main():
 
 _(This example is complete, it can be run "as is" — you'll need to add `import asyncio; asyncio.run(main())` to run `main`)_
 
-### Using `add_spreading_edge()`
+### Using `add_mapping_edge()`
 
-The convenience method [`add_spreading_edge()`][pydantic_graph.beta.graph_builder.GraphBuilder.add_spreading_edge] provides a simpler syntax:
+The convenience method [`add_mapping_edge()`][pydantic_graph.beta.graph_builder.GraphBuilder.add_mapping_edge] provides a simpler syntax:
 
-```python {title="spreading_convenience.py"}
+```python {title="mapping_convenience.py"}
 from dataclasses import dataclass
 
 from pydantic_graph.beta import GraphBuilder, ListReducer, StepContext
@@ -136,7 +136,7 @@ async def main():
     collect = g.join(ListReducer[str])
 
     g.add(g.edge_from(g.start_node).to(generate_numbers))
-    g.add_spreading_edge(generate_numbers, stringify)
+    g.add_mapping_edge(generate_numbers, stringify)
     g.add(
         g.edge_from(stringify).to(collect),
         g.edge_from(collect).to(g.end_node),
@@ -152,9 +152,9 @@ _(This example is complete, it can be run "as is" — you'll need to add `import
 
 ## Empty Iterables
 
-When spreading an empty iterable, you can specify a `downstream_join_id` to ensure the join still executes:
+When mapping an empty iterable, you can specify a `downstream_join_id` to ensure the join still executes:
 
-```python {title="empty_spread.py"}
+```python {title="empty_map.py"}
 from dataclasses import dataclass
 
 from pydantic_graph.beta import GraphBuilder, ListReducer, StepContext
@@ -179,7 +179,7 @@ async def main():
     collect = g.join(ListReducer[int])
 
     g.add(g.edge_from(g.start_node).to(generate_empty))
-    g.add_spreading_edge(generate_empty, double, downstream_join_id=collect.id)
+    g.add_mapping_edge(generate_empty, double, downstream_join_id=collect.id)
     g.add(
         g.edge_from(double).to(collect),
         g.edge_from(collect).to(g.end_node),
@@ -195,11 +195,11 @@ _(This example is complete, it can be run "as is" — you'll need to add `import
 
 ## Nested Parallel Operations
 
-You can nest broadcasts and spreads for complex parallel patterns:
+You can nest broadcasts and maps for complex parallel patterns:
 
 ### Spread then Broadcast
 
-```python {title="spread_then_broadcast.py"}
+```python {title="map_then_broadcast.py"}
 from dataclasses import dataclass
 
 from pydantic_graph.beta import GraphBuilder, ListReducer, StepContext
@@ -230,7 +230,7 @@ async def main():
     g.add(
         g.edge_from(g.start_node).to(generate_list),
         # Spread the list, then broadcast each item to both steps
-        g.edge_from(generate_list).spread().to(add_one, add_two),
+        g.edge_from(generate_list).map().to(add_one, add_two),
         g.edge_from(add_one, add_two).to(collect),
         g.edge_from(collect).to(g.end_node),
     )
@@ -249,7 +249,7 @@ The result contains:
 
 ### Multiple Sequential Spreads
 
-```python {title="sequential_spreads.py"}
+```python {title="sequential_maps.py"}
 from dataclasses import dataclass
 
 from pydantic_graph.beta import GraphBuilder, ListReducer, StepContext
@@ -279,10 +279,10 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate_pairs),
-        # First spread: one task per tuple
-        g.edge_from(generate_pairs).spread().to(unpack_pair),
-        # Second spread: one task per number in each tuple
-        g.edge_from(unpack_pair).spread().to(stringify),
+        # First map: one task per tuple
+        g.edge_from(generate_pairs).map().to(unpack_pair),
+        # Second map: one task per number in each tuple
+        g.edge_from(unpack_pair).map().to(stringify),
         g.edge_from(stringify).to(collect),
         g.edge_from(collect).to(g.end_node),
     )
@@ -324,11 +324,11 @@ async def main():
     collect = g.join(ListReducer[str])
 
     g.add(g.edge_from(g.start_node).to(generate))
-    g.add_spreading_edge(
+    g.add_mapping_edge(
         generate,
         process,
-        pre_spread_label='before spread',
-        post_spread_label='after spread',
+        pre_map_label='before map',
+        post_map_label='after map',
     )
     g.add(
         g.edge_from(process).to(collect),
@@ -375,7 +375,7 @@ async def main():
 
     g.add(
         g.edge_from(g.start_node).to(generate),
-        g.edge_from(generate).spread().to(track_and_square),
+        g.edge_from(generate).map().to(track_and_square),
         g.edge_from(track_and_square).to(collect),
         g.edge_from(collect).to(g.end_node),
     )

docs/graph/beta/steps.md

@@ -345,6 +345,6 @@ async def returns_str(ctx: StepContext[MyState, None, None]) -> str:
 
 ## Next Steps
 
-- Learn about [parallel execution](parallel.md) with broadcasting and spreading
+- Learn about [parallel execution](parallel.md) with broadcasting and mapping
 - Understand [join nodes](joins.md) for aggregating parallel results
 - Explore [conditional branching](decisions.md) with decision nodes

pydantic_graph/pydantic_graph/beta/decision.py

@@ -112,7 +112,7 @@ class DecisionBranch(Generic[SourceT]):
     path: Path
     """The execution path to follow when an input value matches this branch of a decision node.
 
-    This can include transforming, spreading, and broadcasting the output before sending to the next node or nodes.
+    This can include transforming, mapping, and broadcasting the output before sending to the next node or nodes.
 
     The path can also include position-aware labels which are used when generating mermaid diagrams."""
 
@@ -211,7 +211,7 @@ def transform(
             path_builder=self.path_builder.transform(func),
         )
 
-    def spread(
+    def map(
         self: DecisionBranchBuilder[StateT, DepsT, Iterable[T], SourceT, HandledT],
         *,
         fork_id: ForkID | None = None,
@@ -224,16 +224,16 @@ def spread(
 
         Args:
             fork_id: Optional ID for the fork, defaults to a generated value
-            downstream_join_id: Optional ID of a downstream join node which is involved when spreading empty iterables
+            downstream_join_id: Optional ID of a downstream join node which is involved when mapping empty iterables
 
         Returns:
-            A new DecisionBranchBuilder where spreading is performed prior to generating the final output.
+            A new DecisionBranchBuilder where mapping is performed prior to generating the final output.
         """
         return DecisionBranchBuilder(
             decision=self.decision,
             source=self.source,
             matches=self.matches,
-            path_builder=self.path_builder.spread(fork_id=fork_id, downstream_join_id=downstream_join_id),
+            path_builder=self.path_builder.map(fork_id=fork_id, downstream_join_id=downstream_join_id),
         )
 
     def label(self, label: str) -> DecisionBranchBuilder[StateT, DepsT, OutputT, SourceT, HandledT]:

pydantic_graph/pydantic_graph/beta/graph.py

@@ -659,23 +659,23 @@ def _handle_path(self, path: Path, inputs: Any, fork_stack: ForkStack) -> Sequen
             try:
                 iter(inputs)
             except TypeError:
-                raise RuntimeError(f'Cannot spread non-iterable value: {inputs!r}')
+                raise RuntimeError(f'Cannot map non-iterable value: {inputs!r}')
 
             node_run_id = NodeRunID(str(uuid.uuid4()))
 
-            # If the spread specifies a downstream join id, eagerly create a reducer for it
+            # If the map specifies a downstream join id, eagerly create a reducer for it
             if item.downstream_join_id is not None:
                 join_node = self.graph.nodes[item.downstream_join_id]
                 assert isinstance(join_node, Join)
                 self._active_reducers[(item.downstream_join_id, node_run_id)] = join_node.create_reducer(), fork_stack
 
-            spread_tasks: list[GraphTask] = []
+            map_tasks: list[GraphTask] = []
             for thread_index, input_item in enumerate(inputs):
                 item_tasks = self._handle_path(
                     path.next_path, input_item, fork_stack + (ForkStackItem(item.fork_id, node_run_id, thread_index),)
                 )
-                spread_tasks += item_tasks
-            return spread_tasks
+                map_tasks += item_tasks
+            return map_tasks
         elif isinstance(item, BroadcastMarker):
             return [GraphTask(item.fork_id, inputs, fork_stack)]
         elif isinstance(item, TransformMarker):