fpstreams 2.3.0__tar.gz → 2.4.1__tar.gz

{fpstreams-2.3.0 → fpstreams-2.4.1}/CHANGELOG.md

@@ -3,6 +3,142 @@
 This file records user-visible and compatibility-relevant changes in fpstreams 2,
 including changed defaults.
 
+## Unreleased
+
+## 2.4.1 - 2026-10-18
+
+### Changed
+
+- Separate relational candidate recognition and tree compilation from the general
+  compiler. Native grouping, Collector grouping, and synchronous terminal helpers
+  now live in domain modules; public interfaces and execution rules stay the same.
+
+## 2.4.0 - 2026-10-18
+
+### Added
+
+- `ExecutionReport.to_dict()` and `ExecutionEvent.to_dict()` export plain
+  metadata. Report and plan dictionaries carry an independent schema version;
+  reports include metric units, query-owned resource scope, and event limits.
+
+- `Flow.collapse(predicate, collector)` and its async equivalent reduce each
+  adjacent run with existing Collector state. Completion stops further steps
+  within a run while predicates continue to find its boundary. Collector hooks
+  remain synchronous, and awaitable finisher results are emitted as data.
+
+- `Flow.window_reduce(size, combine, step=1)` and `AsyncFlow.window_reduce(...)`
+  reuse ordered partial aggregates across count-based windows. The synchronous
+  combine function must be associative and nonmutating. Cached entries are
+  bounded by `size + 1`; byte sizes and individual stack transfers are not.
+  Nonoverlapping windows use a running fold without retaining a raw window buffer.
+
+- `flow.unfold(seed, function)` and `aflow.unfold(...)` generate values lazily
+  from `(value, next_state)` transitions until the callback returns `None`.
+  Class constructors expose the same operation; async transitions may be awaitable.
+- `Flow.map_accum(initial, function)` and `AsyncFlow.map_accum(...)` thread
+  state through ordered callbacks returning `(next_state, output)`, emitting
+  one output per input through the existing gather/scan execution paths.
+- `agg.min_by(selector)` and `agg.max_by(selector)` retain a whole winning
+  item in one pass. Ties keep the first item and empty input returns `None`;
+  the factories reuse existing grouped, async, and spill aggregation.
+- `agg.top(count, key=...)` and `agg.bottom(count, key=...)` retain a bounded
+  list of whole items per group, ordered by key with stable ties. They compose
+  with the existing global, async, sorted, and spill aggregation paths.
+- `run_with_report()` includes up to 64 immutable plan and route events in
+  `report.events`, with `events_truncated` marking further observations. Child
+  plans keep their own labels without replacing the outer route. Flow, Rows,
+  Pairs, and AsyncFlow use the same recorder.
+- `BoundedExecutor(executor, max_pending=...)` shares one unfinished-task budget
+  across independent queries. It accepts existing thread or process pools,
+  releases capacity on completion or cancellation, and keeps the borrowed pool open.
+- `FileCheckpoint(directory, version=...)` stores verified outputs for stable
+  file partitions. Each successful callback publishes an output file and its
+  metadata together; later runs verify input and output hashes before reuse.
+
+### Changed
+
+- `filter_map()` avoids intermediate tuple adaptation in synchronous pipelines
+  and the extra predicate callback in async serial fusion. It calls the mapper
+  once per input and keeps every result except `None`.
+- Proven primitive Arrow comparison chains can share a selection mask,
+  filtering payload once or counting directly from the mask. Offline Optuna
+  tuning favored nonempty batches with at least one column in the measured shapes.
+- Spill decoding releases encoded buffers before yielding decoded records
+  and releases completed decoded frames before reading the next frame.
+
+- `Collectors.head()` and `tail()` accept integer-index objects, with matching
+  `SupportsIndex` annotations. Partitioned reducer execution and reducer-law
+  layouts use the same integer protocol.
+- `Collectors.teeing()` can combine partial states when both downstream
+  collectors provide combiners. It keeps their live callbacks and carries no
+  inferred reducer laws or native metadata.
+- Named `aggregate()` and `Pairs.aggregate_values()` accept any `Collector`,
+  including composed `Collectors` and existing `agg` factory results. Global,
+  async, grouped, sorted, and spill paths share the existing collector lifecycle.
+- Multi-collector Python aggregation reuses its state-list references within
+  each row while retaining live callbacks and their declaration order.
+- Retained primitive Arrow tables and record batches can keep their native
+  buffers when `arrow_batches(schema=...)` receives the matching output schema,
+  including metadata. Safe direct-field projections and primitive filters can
+  execute columnarly. Casts, Python callbacks, and unsupported sources retain
+  the existing conversion path.
+- Arrow execution accepts chains of safe direct comparisons followed by a
+  direct projection. Parquet keeps only the leading comparison as an automatic
+  scan hint; all filters remain in the ordered residual program.
+- Default local Parquet scans with one fragment can omit safe unused fields
+  from validation scans, retaining query dependencies and fields whose Python
+  conversion can fail. Sources with possible scanner casts retain the full
+  caller-visible projection before automatic filtering and projection.
+
+### Fixed
+
+- Query-wide task/file limits and task-scope limits reject noninteger values,
+  including NaN, before resource acquisition. Integer-index values are
+  normalized once during construction.
+
+- `Collectors.first()` and `head(count)` preserve completed state when used
+  inside `grouping_by` or `partitioning_by`. Previously, `first()` returned the
+  last group item and `head()` could retain the whole group, even with a zero
+  count. Grouping adapters continue to read all input and step custom collectors.
+- `Flow` and `AsyncFlow` validate `take`, `limit`, `drop`, and `skip` counts
+  through the integer index protocol before building the operation. Noninteger
+  values, including NaN and infinity, raise `TypeError` before opening the source.
+  This prevents async prefix operations from silently rounding counts or losing
+  their limit.
+- `Flow.collect()` and `AsyncFlow.collect()` preserve a single streaming
+  collector's finished result type in type checkers. Named collectors return
+  a dictionary, while optional or dynamically forwarded arguments retain the
+  general result union. Runtime dispatch and validation are unchanged.
+- `Collectors.head()` and `tail()` reject floats, including NaN and infinity,
+  at construction. Partitioned reducer execution validates `partition_size`
+  before creating state or opening input, preventing non-integer values from
+  silently removing partition boundaries.
+- Partitioned reducer execution closes its input iterator on exhaustion and
+  failure, before merging states or finishing. Cleanup failures preserve an
+  active source or callback exception.
+- Collector programs reject missing combiners before invoking any merge
+  callback, preventing avoidable partial mutations on invalid merge requests.
+- Reducer law checks build independent states for each merge expression,
+  preventing in-place combiners from producing false identity or associativity
+  results. The input iterator closes before the examples are replayed.
+- Unsafe Arrow batches evaluate filters in row order and stop when downstream
+  consumers stop, preserving Python exception order and early-exit behavior.
+- Arrow prefix fallbacks reuse converted rows, so custom extension scalars
+  cross the Python conversion boundary once per input batch.
+- Automatic Parquet hints preserve conversion errors in discarded fields and
+  rows, including casts across fragments and supplied dataset schemas.
+  Types whose Python conversion can fail are validated before automatic
+  filtering or projection; explicit source `columns` and `filter` still define
+  which values the source exposes.
+- `scan_csv()` validates every caller-visible column before query projection,
+  preserving conversion errors in later CSV blocks. It opens the typed source
+  once; explicit source conversion options still control included columns.
+- An explicit zero-column Arrow schema preserves the input row count in
+  `arrow_batches()` and `to_arrow()`, including partial final batches.
+- Polars batch exports preserve the height of zero-column inputs. Parquet
+  writes reject nonempty rows without columns, preserving an existing target
+  instead of publishing a file that loses the input row count.
+
 ## 2.3.0 - 2026-10-15
 
 ### Fixed

{fpstreams-2.3.0 → fpstreams-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpstreams
-Version: 2.3.0
+Version: 2.4.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -66,9 +66,10 @@ Lazy Python pipelines for iterables and records, with bounded async concurrency.
 
 Python 3.11 or newer is required.
 
-The current stable release is [2.3.0](https://github.com/steventimes/fpstreams/releases/tag/v2.3.0).
-It adds explicit `map_batches()` for sync and async pipelines, reusable mapping
-executors, and async callback typing fixes. See the
+The current stable release is [2.4.1](https://github.com/steventimes/fpstreams/releases/tag/v2.4.1).
+This maintenance release reorganizes planner and execution internals with no public API changes.
+Version 2.4.0 added stateful pipeline operations, composed aggregation, shared execution
+limits, file recovery, and versioned execution metadata. See the
 [changelog](https://github.com/steventimes/fpstreams/blob/master/CHANGELOG.md) for its scope and the
 [performance guide](https://steventimes.github.io/fpstreams/user-guide/performance/#process-mapping-and-explicit-batches)
 for batch and executor examples. The
@@ -369,23 +370,39 @@ python_result = pipeline.with_engine("python").to_list()
 native_result = pipeline.with_engine("native").to_list()
 ~~~
 
-Use `run_with_report()` to execute a terminal and inspect its recorded route.
-Version 2.2.0 adds Pairs terminals such as
-`flow([("a", 1)]).pairs().run_with_report("group_values")`. See the
+Use `run_with_report()` to get a terminal's value, recorded route, and query-owned
+resource counts in one execution. Pairs supports terminals such as
+`flow([("a", 1)]).pairs().run_with_report("group_values")`. Version 2.4.0 also
+includes up to 64 child plan and route observations in `report.events`. See the
 [execution report guide](https://steventimes.github.io/fpstreams/user-guide/execution-reports/)
 for supported terminals and the limits of route reporting.
 
+In 2.4.0, `report.to_dict()` exports versioned metadata with metric units,
+resource scope, and event limits. It excludes the terminal value and does not
+rerun the query. See the
+[metadata export guide](https://steventimes.github.io/fpstreams/user-guide/execution-reports/#metadata-export-unreleased)
+for JSON storage and caller-managed OpenLineage integration. Report export
+requires 2.4.0 or newer.
+
+Version 2.4.0 also includes `BoundedExecutor` for a shared submission limit
+across queries and `FileCheckpoint` for verified file-partition recovery. See
+the [resource controls](https://steventimes.github.io/fpstreams/user-guide/performance/#share-a-submission-budget-unreleased)
+and [file-partition recipe](https://steventimes.github.io/fpstreams/user-guide/analytics/#resume-file-partitions-unreleased)
+for ownership, memory, and retry semantics. These additions require 2.4.0 or newer.
+
+In 2.4.0, `flow.unfold` / `aflow.unfold` generate values from explicit state
+transitions. `Flow.map_accum` and `AsyncFlow.map_accum` update state while mapping
+each input to one output. See the
+[state examples](https://steventimes.github.io/fpstreams/reference/flow/#state-driven-generation-and-mapping-unreleased)
+for termination, tuple ordering, and mutable-state ownership. These APIs require
+2.4.0 or newer.
+
 A forced native plan raises `NativeUnsupportedError` if its complete types or
 operations cannot run natively. In particular, the presence of an internal
 native relational specialization does not make the complete relation eligible
 for `with_engine("native")`. An unsupported forced relational plan fails before
 claiming its one-shot sources; `auto` selects a legal fallback path.
 
-[`run_with_report()`](https://steventimes.github.io/fpstreams/user-guide/execution-reports/)
-returns a terminal's value, recorded route, and query-owned resource counts in
-one execution. It records the outer plan and some direct paths; it does not
-identify every internal kernel or runtime fallback.
-
 Identity list and tuple materialization stays in Python. Large, supported integer
 sums and numeric range reductions may use Rust in `auto` mode. `count()` uses a
 known exact size in O(1) when no operation changes cardinality and the source is

{fpstreams-2.3.0 → fpstreams-2.4.1}/README.md

@@ -11,9 +11,10 @@ Lazy Python pipelines for iterables and records, with bounded async concurrency.
 
 Python 3.11 or newer is required.
 
-The current stable release is [2.3.0](https://github.com/steventimes/fpstreams/releases/tag/v2.3.0).
-It adds explicit `map_batches()` for sync and async pipelines, reusable mapping
-executors, and async callback typing fixes. See the
+The current stable release is [2.4.1](https://github.com/steventimes/fpstreams/releases/tag/v2.4.1).
+This maintenance release reorganizes planner and execution internals with no public API changes.
+Version 2.4.0 added stateful pipeline operations, composed aggregation, shared execution
+limits, file recovery, and versioned execution metadata. See the
 [changelog](https://github.com/steventimes/fpstreams/blob/master/CHANGELOG.md) for its scope and the
 [performance guide](https://steventimes.github.io/fpstreams/user-guide/performance/#process-mapping-and-explicit-batches)
 for batch and executor examples. The
@@ -314,23 +315,39 @@ python_result = pipeline.with_engine("python").to_list()
 native_result = pipeline.with_engine("native").to_list()
 ~~~
 
-Use `run_with_report()` to execute a terminal and inspect its recorded route.
-Version 2.2.0 adds Pairs terminals such as
-`flow([("a", 1)]).pairs().run_with_report("group_values")`. See the
+Use `run_with_report()` to get a terminal's value, recorded route, and query-owned
+resource counts in one execution. Pairs supports terminals such as
+`flow([("a", 1)]).pairs().run_with_report("group_values")`. Version 2.4.0 also
+includes up to 64 child plan and route observations in `report.events`. See the
 [execution report guide](https://steventimes.github.io/fpstreams/user-guide/execution-reports/)
 for supported terminals and the limits of route reporting.
 
+In 2.4.0, `report.to_dict()` exports versioned metadata with metric units,
+resource scope, and event limits. It excludes the terminal value and does not
+rerun the query. See the
+[metadata export guide](https://steventimes.github.io/fpstreams/user-guide/execution-reports/#metadata-export-unreleased)
+for JSON storage and caller-managed OpenLineage integration. Report export
+requires 2.4.0 or newer.
+
+Version 2.4.0 also includes `BoundedExecutor` for a shared submission limit
+across queries and `FileCheckpoint` for verified file-partition recovery. See
+the [resource controls](https://steventimes.github.io/fpstreams/user-guide/performance/#share-a-submission-budget-unreleased)
+and [file-partition recipe](https://steventimes.github.io/fpstreams/user-guide/analytics/#resume-file-partitions-unreleased)
+for ownership, memory, and retry semantics. These additions require 2.4.0 or newer.
+
+In 2.4.0, `flow.unfold` / `aflow.unfold` generate values from explicit state
+transitions. `Flow.map_accum` and `AsyncFlow.map_accum` update state while mapping
+each input to one output. See the
+[state examples](https://steventimes.github.io/fpstreams/reference/flow/#state-driven-generation-and-mapping-unreleased)
+for termination, tuple ordering, and mutable-state ownership. These APIs require
+2.4.0 or newer.
+
 A forced native plan raises `NativeUnsupportedError` if its complete types or
 operations cannot run natively. In particular, the presence of an internal
 native relational specialization does not make the complete relation eligible
 for `with_engine("native")`. An unsupported forced relational plan fails before
 claiming its one-shot sources; `auto` selects a legal fallback path.
 
-[`run_with_report()`](https://steventimes.github.io/fpstreams/user-guide/execution-reports/)
-returns a terminal's value, recorded route, and query-owned resource counts in
-one execution. It records the outer plan and some direct paths; it does not
-identify every internal kernel or runtime fallback.
-
 Identity list and tuple materialization stays in Python. Large, supported integer
 sums and numeric range reductions may use Rust in `auto` mode. `count()` uses a
 known exact size in O(1) when no operation changes cardinality and the source is

{fpstreams-2.3.0 → fpstreams-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "fpstreams"
-version = "2.3.0"
+version = "2.4.1"
 description = "Lazy Python pipelines for iterables and records, with bounded async concurrency."
 readme = "README.md"
 authors = [

{fpstreams-2.3.0 → fpstreams-2.4.1}/rust/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "fpstreams-native"
-version = "2.3.0"
+version = "2.4.1"
 dependencies = [
  "pyo3",
  "pyo3-build-config",

{fpstreams-2.3.0 → fpstreams-2.4.1}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fpstreams-native"
-version = "2.3.0"
+version = "2.4.1"
 edition = "2024"
 rust-version = "1.85"
 description = "Native fused execution kernels for fpstreams."

{fpstreams-2.3.0 → fpstreams-2.4.1}/src/fpstreams/__init__.py

@@ -27,7 +27,9 @@ from .errors import (
 from .expressions import Expr, FExpr, RowExpr, coalesce, col, fitem, item, lit, when
 from .functional import curry, pipe, retry
 from .primitives import Err, Ok, Option, Result
-from .runtime.report import ExecutionReport, ExecutionResult
+from .runtime.executor import BoundedExecutor
+from .runtime.report import ExecutionEvent, ExecutionReport, ExecutionResult
+from .storage.checkpoint import FileCheckpoint
 from .streams import (
     AsyncFlow,
     AsyncStream,
@@ -42,7 +44,7 @@ from .streams import (
 from .tabular import Rows, SpillLimits
 from .tabular.factory import rows as rows
 
-__version__ = "2.3.0"
+__version__ = "2.4.1"
 Stream = Flow
 ParallelStream = Flow
 
@@ -50,6 +52,7 @@ __all__ = [
     "Aggregator",
     "AsyncFlow",
     "AsyncStream",
+    "BoundedExecutor",
     "BufferLimitError",
     "Collector",
     "Collectors",
@@ -58,10 +61,12 @@ __all__ = [
     "EmptyFlowError",
     "EmptyInputPolicy",
     "Err",
+    "ExecutionEvent",
     "ExecutionReport",
     "ExecutionResult",
     "Expr",
     "FExpr",
+    "FileCheckpoint",
     "Flow",
     "FlowConsumedError",
     "FlowError",

{fpstreams-2.3.0 → fpstreams-2.4.1}/src/fpstreams/collecting/aggregation.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import heapq
+import operator
 from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass
 from types import CodeType, FunctionType, MappingProxyType
@@ -12,6 +14,8 @@ from ..runtime._distinct import DistinctKey, HashFailure
 from . import _collector_base
 from ._collector_base import Aggregator as Aggregator
 from .collector import (
+    Collector,
+    CollectorItems,
     finish_collectors,
     initialize_collectors,
     step_collectors,
@@ -561,7 +565,9 @@ _CANONICAL_GROUP_SELECTOR_MATCHES_STEP = _group_selector_matches_step
 _CANONICAL_GROUP_SELECTOR_MATCHES_STEP_CODE = _group_selector_matches_step.__code__
 
 
-def native_group_aggregation(aggregation: Aggregator) -> NativeGroupAggregation | None:
+def native_group_aggregation(
+    aggregation: Collector[Any, Any, Any],
+) -> NativeGroupAggregation | None:
     """Recognize a factory result without trusting user-constructible native metadata."""
     if (
         _GROUP_STEP_KINDS is not _CANONICAL_GROUP_STEP_KINDS
@@ -620,7 +626,7 @@ def native_group_aggregation(aggregation: Aggregator) -> NativeGroupAggregation
     )
 
 
-def project_count_aggregation(aggregation: Aggregator) -> bool:
+def project_count_aggregation(aggregation: Collector[Any, Any, Any]) -> bool:
     """Recognize only the constant-size count reducer built by :meth:`agg.count`.
 
     Native metadata and reducer laws are user-constructible, so neither is enough
@@ -647,7 +653,7 @@ def project_count_aggregation(aggregation: Aggregator) -> bool:
     )
 
 
-def native_aggregation_is_live(aggregation: Aggregator) -> bool:
+def native_aggregation_is_live(aggregation: Collector[Any, Any, Any]) -> bool:
     """Recognize an unchanged project-created whole-value native aggregation."""
     if project_count_aggregation(aggregation):
         return True
@@ -709,14 +715,16 @@ class _DistinctState:
         return len(self.hashable) + len(self.unhashable)
 
 
-AggregationItems = tuple[tuple[str, Aggregator], ...]
+AggregationItems = CollectorItems
 
 
-def prepare_aggregations(aggregations: Mapping[str, Aggregator]) -> AggregationItems:
+def prepare_aggregations(
+    aggregations: Mapping[str, Collector[Any, Any, Any]],
+) -> AggregationItems:
     """Validate named aggregators and freeze mapping order as `(name, aggregator)` pairs.
 
-    The mapping must be nonempty, names must be truthy, and every value must be an
-    :class:`Aggregator` rather than an arbitrary collector.
+    The mapping must be nonempty, names must be truthy, and every value must be a
+    :class:`Collector`, including aggregators built by :data:`agg`.
     """
     if not aggregations:
         raise ValueError("aggregate requires at least one named aggregation")
@@ -724,8 +732,8 @@ def prepare_aggregations(aggregations: Mapping[str, Aggregator]) -> AggregationI
     for name, aggregation in items:
         if not name:
             raise ValueError("aggregate names cannot be empty")
-        if not isinstance(aggregation, Aggregator):
-            raise TypeError(f"aggregate {name!r} must be an Aggregator")
+        if not isinstance(aggregation, Collector):
+            raise TypeError(f"aggregate {name!r} must be an Aggregator or Collector")
     return items
 
 
@@ -799,6 +807,75 @@ def finish_native_aggregations(
     return result
 
 
+def _extremum_by(selector: Selector, better: Callable[[Any, Any], bool]) -> Aggregator:
+    """Retain a winning item and its once-selected key without comparing payloads."""
+    select = compile_selector(selector)
+
+    def step(state: Any, row: Any) -> Any:
+        key = select(row)
+        return (key, row) if state is _MISSING or better(key, state[0]) else state
+
+    return Aggregator(
+        lambda: _MISSING,
+        step,
+        lambda state: None if state is _MISSING else state[1],
+    )
+
+
+@dataclass(slots=True, eq=False)
+class _RankedItem:
+    """Order heap entries by key and encounter index, never by their payload."""
+
+    key: Any
+    index: int
+    value: Any
+    largest: bool
+
+    def __lt__(self, other: _RankedItem) -> bool:
+        if self.key is other.key or self.key == other.key:
+            return self.index > other.index
+        return bool(self.key < other.key if self.largest else other.key < self.key)
+
+
+@dataclass(slots=True)
+class _RankedState:
+    """Retain only the requested winners and the next encounter index."""
+
+    heap: list[_RankedItem]
+    index: int = 0
+
+
+def _ranked(count: int, key: Selector | None, *, largest: bool) -> Aggregator:
+    size = operator.index(count)
+    if size < 0:
+        raise ValueError("count must be non-negative")
+    select = _identity if key is None else compile_selector(key)
+    if size == 0:
+        return Aggregator(list, lambda state, _row: state, done=lambda _state: True)
+
+    def step(state: _RankedState, row: Any) -> _RankedState:
+        selected = select(row)
+        index = state.index
+        state.index += 1
+        if len(state.heap) < size:
+            heapq.heappush(state.heap, _RankedItem(selected, index, row, largest))
+        else:
+            worst = state.heap[0]
+            # Later ties cannot displace an earlier item. Avoid allocating an
+            # entry for every discarded row while keeping key comparisons live.
+            if worst.key is selected or worst.key == selected:
+                return state
+            if worst.key < selected if largest else selected < worst.key:
+                heapq.heapreplace(state.heap, _RankedItem(selected, index, row, largest))
+        return state
+
+    return Aggregator(
+        lambda: _RankedState([]),
+        step,
+        lambda state: [item.value for item in sorted(state.heap, reverse=True)],
+    )
+
+
 class _AggFactory:
     """Construct built-in aggregators for `Flow.aggregate` and tabular grouping."""
 
@@ -1066,6 +1143,72 @@ class _AggFactory:
             selector,
         )
 
+    def min_by(self, selector: Selector) -> Aggregator:
+        """Keep the first whole input item with the smallest selected key.
+
+        The selector runs once per item. Each subsequent key is compared with the
+        retained key using `<`; ties keep the earlier item. One key and one item
+        are retained per aggregation state. The source is fully consumed.
+
+        Args:
+            selector: Required field, path, index, expression, or callable selecting a key.
+
+        Returns:
+            An aggregator returning the original winning item, or `None` for empty input.
+                Keys follow Python comparison rules, including errors and NaN behavior.
+        """
+        return _extremum_by(selector, operator.lt)
+
+    def max_by(self, selector: Selector) -> Aggregator:
+        """Keep the first whole input item with the largest selected key.
+
+        The selector runs once per item. Each subsequent key is compared with the
+        retained key using `>`; ties keep the earlier item. One key and one item
+        are retained per aggregation state. The source is fully consumed.
+
+        Args:
+            selector: Required field, path, index, expression, or callable selecting a key.
+
+        Returns:
+            An aggregator returning the original winning item, or `None` for empty input.
+                Keys follow Python comparison rules, including errors and NaN behavior.
+        """
+        return _extremum_by(selector, operator.gt)
+
+    def top(self, count: int, *, key: Selector | None = None) -> Aggregator:
+        """Keep up to `count` whole items in descending key order.
+
+        Equal keys retain input order. The key runs once per item and payloads
+        are never compared. Each state retains at most `count` items. Keys use
+        Python heap and sorting comparisons; use consistently ordered keys.
+
+        Args:
+            count: Non-negative integer number of items to retain.
+            key: Optional selector; `None` compares whole items.
+
+        Returns:
+            An aggregator returning a list, empty for empty input or zero count.
+                Zero count does not invoke the key or pull an independent source.
+        """
+        return _ranked(count, key, largest=True)
+
+    def bottom(self, count: int, *, key: Selector | None = None) -> Aggregator:
+        """Keep up to `count` whole items in ascending key order.
+
+        Equal keys retain input order. The key runs once per item and payloads
+        are never compared. Each state retains at most `count` items. Keys use
+        Python heap and sorting comparisons; use consistently ordered keys.
+
+        Args:
+            count: Non-negative integer number of items to retain.
+            key: Optional selector; `None` compares whole items.
+
+        Returns:
+            An aggregator returning a list, empty for empty input or zero count.
+                Zero count does not invoke the key or pull an independent source.
+        """
+        return _ranked(count, key, largest=False)
+
     def first(self, selector: Selector | None = None) -> Aggregator:
         """Build an aggregator that stops after the first selected value.