opencode-pyneruntime 6.6.4__py3-none-any.whl

pynecore/transformers/slot_layout.py

@@ -0,0 +1,381 @@
+"""
+Shared slot-layout allocator for the slot-based instance state scheme.
+
+Every transformer that contributes per-instance state (persistent variables,
+series, isolated call sites) allocates slots from a single
+:class:`ModuleLayout` while walking the module. :func:`apply_layout` then
+materializes the result into the module AST:
+
+- the module-level ``__pyne_slot_layout__`` dict (one entry per
+  state-carrying scope),
+- a ``func.__pyne_layout__ = __pyne_slot_layout__['<scope>']`` attach
+  statement after every state-carrying function definition (inside the parent
+  body for nested definitions); decorated definitions get an innermost
+  ``@__attach_layout__(...)`` decorator instead, so the layout lands on the
+  raw function and not on the decorator's return value,
+- the hidden state parameter injected as the FIRST parameter of every
+  state-carrying function.
+
+Scope identifiers join the function-name path with the middle-dot separator
+(``main``, ``main·helper``) — the same convention the legacy global-name
+mangling used. Repeated definitions of one name within a scope (``overload``
+implementations) are disambiguated with an ordinal suffix (``highest·2``);
+the mapping comes from :func:`collect_scope_segments` and every pipeline
+stage reads it through :meth:`ModuleLayout.scope_segment`.
+
+The hidden parameter is named ``__state__`` by default. Functions that
+contain nested function definitions get a scope-qualified name
+(``__state·main__``) instead, so a nested function can reach the parent's
+state vector through a plain closure reference without its own hidden
+parameter shadowing it.
+
+The runtime side of the contract (layout dict format, ``_make_state``,
+``__resolve_slot__``, ...) lives in :mod:`pynecore.core.instance_state`.
+"""
+import ast
+from dataclasses import dataclass, field
+
+__all__ = ['ModuleLayout', 'ScopeLayout', 'apply_layout', 'scope_for_function',
+           'collect_scope_segments']
+
+DEFAULT_STATE_PARAM = '__state__'
+
+
+def _scope_defs(scope_node: ast.AST):
+    """Yield the function definitions belonging to one scope in source order
+    (descends through statements and class bodies, but not into nested
+    function definitions — those belong to the inner scope)."""
+    for child in ast.iter_child_nodes(scope_node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield child
+        elif not isinstance(child, ast.Lambda):
+            yield from _scope_defs(child)
+
+
+def collect_scope_segments(tree: ast.Module) -> dict[int, str]:
+    """Compute the scope segment of every function definition in a module.
+
+    Repeated definitions of the same name within one scope (typically
+    ``overload`` implementations) get an ordinal suffix (``highest``,
+    ``highest·2``) so each keeps its own slot layout. The result is a pure
+    function of the tree structure, so every pipeline stage that recomputes
+    it gets identical segments.
+
+    :param tree: The module AST.
+    :return: ``id(def node) -> segment`` mapping.
+    """
+    segments: dict[int, str] = {}
+
+    def assign(scope_node: ast.AST) -> None:
+        counts: dict[str, int] = {}
+        for func in _scope_defs(scope_node):
+            n = counts.get(func.name, 0) + 1
+            counts[func.name] = n
+            segments[id(func)] = func.name if n == 1 else f'{func.name}·{n}'
+            assign(func)
+
+    assign(tree)
+    return segments
+
+
+@dataclass
+class _Slot:
+    """One slot of a scope's state vector."""
+    index: int
+    kind: str  # 'var' | 'flag' | 'kahan' | 'series' | 'child' | 'anchor'
+    name: str  # debug name for the layout 'names' tuple
+    init: ast.expr  # template expression for the layout 'init' tuple
+    max_bars_back: ast.expr | None = None  # series slots only
+    series_elem: str | None = None  # series slots only: element type name ('float') or None
+    call_id: str | None = None  # child/anchor slots only
+    in_loop: bool = False  # child slots only
+    varip: bool = False  # var slots and their kahan companions only
+
+
+@dataclass
+class ScopeLayout:
+    """Slot table of one scope (one function definition)."""
+    scope: str
+    slots: list[_Slot] = field(default_factory=list)
+    state_param: str = DEFAULT_STATE_PARAM
+
+    def _add(self, slot: _Slot) -> int:
+        self.slots.append(slot)
+        return slot.index
+
+    def add_var(self, name: str, init: ast.expr, *, varip: bool = False) -> int:
+        """Allocate a slot for a persistent variable.
+
+        :param name: Source-level variable name (debug only).
+        :param init: Template expression for the init tuple (literal or ``na``;
+            lazy-initialized variables pass ``Constant(None)`` and pair this
+            slot with :meth:`add_flag`).
+        :param varip: Whether the variable is ``varip`` (excluded from var rollback).
+        :return: The allocated slot index.
+        """
+        return self._add(_Slot(len(self.slots), 'var', name, init, varip=varip))
+
+    def add_flag(self, name: str) -> int:
+        """Allocate a lazy-init flag slot (init ``False``).
+
+        :param name: Name of the variable the flag belongs to.
+        :return: The allocated slot index.
+        """
+        return self._add(_Slot(len(self.slots), 'flag', f'{name}·flag', ast.Constant(value=False)))
+
+    def add_kahan(self, name: str, *, varip: bool = False) -> int:
+        """Allocate a Kahan compensation slot (init ``0.0``).
+
+        :param name: Name of the variable the compensation belongs to.
+        :param varip: Whether the compensated variable is ``varip`` — the
+            compensation must follow it out of the var rollback, otherwise a
+            rollback would desynchronize the pair.
+        :return: The allocated slot index.
+        """
+        return self._add(_Slot(len(self.slots), 'kahan', f'{name}·kahan', ast.Constant(value=0.0),
+                               varip=varip))
+
+    def add_series(self, name: str, max_bars_back: ast.expr, elem: str | None = None) -> int:
+        """Allocate a series slot (``_make_state`` puts a fresh ``SeriesImpl`` here).
+
+        :param name: Source-level variable name (debug only).
+        :param max_bars_back: Expression for the series' ``max_bars_back`` argument.
+        :param elem: Element type name from the ``Series[T]`` annotation when it
+            is statically known (currently only ``'float'`` matters: those
+            series get the native nan as their out-of-range na value).
+        :return: The allocated slot index.
+        """
+        return self._add(_Slot(len(self.slots), 'series', name, ast.Constant(value=None),
+                               max_bars_back=max_bars_back, series_elem=elem))
+
+    def add_child(self, call_id: str, *, in_loop: bool) -> int:
+        """Allocate a child slot for an isolated call site.
+
+        :param call_id: Call-site identifier (``main·ema·0`` style).
+        :param in_loop: Whether the call site sits in a loop (slot holds a
+            child list instead of a single child state).
+        :return: The allocated slot index.
+        """
+        return self._add(_Slot(len(self.slots), 'child', call_id, ast.Constant(value=None),
+                               call_id=call_id, in_loop=in_loop))
+
+    def add_anchor(self, call_id: str, *, in_loop: bool = False) -> int:
+        """Allocate an anchor slot for a uniform-path call site.
+
+        Anchors are emitted into the layout's ``children`` tuple, so
+        ``reset()`` clears them and the next call rebinds; the bind helper
+        creates whatever it caches. Loop-shaped anchors hold a list of
+        ``(callee, bound)`` pairs indexed by the per-invocation counter.
+
+        :param call_id: Call-site identifier.
+        :param in_loop: Whether the call site sits in a loop.
+        :return: The allocated slot index.
+        """
+        return self._add(_Slot(len(self.slots), 'anchor', call_id, ast.Constant(value=None),
+                               call_id=call_id, in_loop=in_loop))
+
+
+class ModuleLayout:
+    """Slot layouts of every scope in one module, shared by the transformers."""
+
+    def __init__(self):
+        self.scopes: dict[str, ScopeLayout] = {}
+        self._segments: dict[int, str] = {}
+
+    def assign_scope_ids(self, tree: ast.Module) -> None:
+        """(Re)build the definition -> scope-segment mapping for a module.
+
+        Every transformer entry point (and :func:`apply_layout`) calls this;
+        the rebuild is deterministic, so repeated calls on the same tree
+        agree even after body mutations.
+
+        :param tree: The module AST.
+        """
+        self._segments = collect_scope_segments(tree)
+
+    def scope_segment(self, node: ast.FunctionDef) -> str:
+        """Disambiguated scope segment of a function definition.
+
+        :param node: The function definition.
+        :return: ``name`` or ``name·N`` for repeated names in one scope.
+        """
+        return self._segments.get(id(node), node.name)
+
+    def scope(self, scope_id: str) -> ScopeLayout:
+        """Return (creating on demand) the layout of a scope.
+
+        :param scope_id: Middle-dot joined function-name path.
+        :return: The scope's layout.
+        """
+        try:
+            return self.scopes[scope_id]
+        except KeyError:
+            scope = self.scopes[scope_id] = ScopeLayout(scope_id)
+            return scope
+
+    def state_carrying(self, scope_id: str) -> bool:
+        """Whether a scope has any state slot (and thus a hidden state parameter).
+
+        :param scope_id: Middle-dot joined function-name path.
+        :return: True if the scope carries state.
+        """
+        scope = self.scopes.get(scope_id)
+        return scope is not None and bool(scope.slots)
+
+    def state_param(self, scope_id: str) -> str:
+        """Name of a scope's hidden state parameter.
+
+        :param scope_id: Middle-dot joined function-name path.
+        :return: The parameter name (``__state__`` or scope-qualified).
+        """
+        scope = self.scopes.get(scope_id)
+        return scope.state_param if scope is not None else DEFAULT_STATE_PARAM
+
+
+def scope_for_function(layout: ModuleLayout, scope_id: str, node: ast.FunctionDef) -> ScopeLayout:
+    """Return the scope layout of a function definition, qualifying the state
+    parameter name when the function contains nested definitions.
+
+    Every state-contributing transformer must enter scopes through this
+    helper so they agree on the parameter name (``__state__`` vs the
+    scope-qualified ``__state·{scope}__`` that nested definitions reach
+    through a closure).
+
+    :param layout: The module's shared allocator.
+    :param scope_id: Middle-dot joined function-name path.
+    :param node: The function definition being entered.
+    :return: The scope's layout.
+    """
+    scope = layout.scope(scope_id)
+    if any(isinstance(child, ast.FunctionDef)
+           for child in ast.walk(node) if child is not node):
+        scope.state_param = f'__state·{scope_id}__'
+    return scope
+
+
+def _scope_entry_ast(scope: ScopeLayout) -> ast.Dict:
+    """Build the layout dict literal of one scope."""
+    init = ast.Tuple(elts=[slot.init for slot in scope.slots], ctx=ast.Load())
+    series = ast.Tuple(
+        elts=[ast.Tuple(elts=[ast.Constant(value=slot.index),
+                              slot.max_bars_back if slot.max_bars_back is not None
+                              else ast.Constant(value=None),
+                              ast.Constant(value=slot.series_elem)],
+                        ctx=ast.Load())
+              for slot in scope.slots if slot.kind == 'series'],
+        ctx=ast.Load())
+    varip = ast.Tuple(
+        elts=[ast.Constant(value=slot.index) for slot in scope.slots if slot.varip],
+        ctx=ast.Load())
+    children = ast.Tuple(
+        elts=[ast.Tuple(elts=[ast.Constant(value=slot.index),
+                              ast.Constant(value=slot.call_id),
+                              ast.Constant(value=slot.in_loop)],
+                        ctx=ast.Load())
+              for slot in scope.slots if slot.kind in ('child', 'anchor')],
+        ctx=ast.Load())
+    names = ast.Tuple(
+        elts=[ast.Constant(value=slot.name) for slot in scope.slots],
+        ctx=ast.Load())
+    return ast.Dict(
+        keys=[ast.Constant(value=key) for key in ('init', 'series', 'varip', 'children', 'names')],
+        values=[init, series, varip, children, names],
+    )
+
+
+def _layout_assign_ast(layout: ModuleLayout) -> ast.Assign:
+    """Build the module-level ``__pyne_slot_layout__`` assignment."""
+    carrying = [scope for scope in layout.scopes.values() if scope.slots]
+    return ast.Assign(
+        targets=[ast.Name(id='__pyne_slot_layout__', ctx=ast.Store())],
+        value=ast.Dict(
+            keys=[ast.Constant(value=scope.scope) for scope in carrying],
+            values=[_scope_entry_ast(scope) for scope in carrying],
+        ),
+    )
+
+
+def _attach_ast(func_name: str, scope_id: str) -> ast.Assign:
+    """Build the ``func.__pyne_layout__ = __pyne_slot_layout__['scope']`` attach."""
+    return ast.Assign(
+        targets=[ast.Attribute(value=ast.Name(id=func_name, ctx=ast.Load()),
+                               attr='__pyne_layout__', ctx=ast.Store())],
+        value=ast.Subscript(value=ast.Name(id='__pyne_slot_layout__', ctx=ast.Load()),
+                            slice=ast.Constant(value=scope_id), ctx=ast.Load()),
+    )
+
+
+def _attach_decorator_ast(scope_id: str) -> ast.Call:
+    """Build the ``__attach_layout__(__pyne_slot_layout__['scope'])`` decorator.
+
+    Used for decorated definitions: appended as the INNERMOST decorator it
+    tags the raw function, while a post-definition attribute assignment
+    would tag whatever the other decorators returned (e.g. an ``overload``
+    dispatcher).
+    """
+    return ast.Call(
+        func=ast.Name(id='__attach_layout__', ctx=ast.Load()),
+        args=[ast.Subscript(value=ast.Name(id='__pyne_slot_layout__', ctx=ast.Load()),
+                            slice=ast.Constant(value=scope_id), ctx=ast.Load())],
+        keywords=[])
+
+
+def _process_defs(body: list[ast.stmt], scope_prefix: str, layout: ModuleLayout,
+                  used_imports: set[str]) -> list[ast.stmt]:
+    """Inject hidden state parameters and layout attaches into a statement list."""
+    new_body: list[ast.stmt] = []
+    for stmt in body:
+        new_body.append(stmt)
+        if not isinstance(stmt, ast.FunctionDef):
+            continue
+        segment = layout.scope_segment(stmt)
+        scope_id = f'{scope_prefix}·{segment}' if scope_prefix else segment
+        stmt.body = _process_defs(stmt.body, scope_id, layout, used_imports)
+        if layout.state_carrying(scope_id):
+            stmt.args.args.insert(0, ast.arg(arg=layout.state_param(scope_id)))
+            if stmt.decorator_list:
+                stmt.decorator_list.append(_attach_decorator_ast(scope_id))
+                used_imports.add('__attach_layout__')
+            else:
+                new_body.append(_attach_ast(stmt.name, scope_id))
+    return new_body
+
+
+def _insert_index(body: list[ast.stmt]) -> int:
+    """Index right after the module docstring and the leading import block."""
+    index = 0
+    for i, stmt in enumerate(body):
+        if (isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant)
+                and isinstance(stmt.value.value, str)) or isinstance(stmt, (ast.Import,
+                                                                            ast.ImportFrom)):
+            index = i + 1
+            continue
+        break
+    return index
+
+
+def apply_layout(tree: ast.Module, layout: ModuleLayout) -> ast.Module:
+    """Materialize the collected layout into the module AST.
+
+    Inserts the ``__pyne_slot_layout__`` dict after the import block, injects
+    the hidden state parameter into every state-carrying function definition
+    and appends the ``__pyne_layout__`` attach statement after each of them.
+
+    :param tree: The module AST (already processed by the slot transformers).
+    :param layout: The shared allocator the transformers filled.
+    :return: The same module object, updated in place.
+    """
+    # The dict is emitted even when empty: its presence marks the module as
+    # transformed, which the cross-module call-site classification relies on
+    # ("transformed module + no layout attribute -> provably stateless").
+    layout.assign_scope_ids(tree)
+    used_imports: set[str] = set()
+    tree.body = _process_defs(tree.body, '', layout, used_imports)
+    index = _insert_index(tree.body)
+    tree.body.insert(index, _layout_assign_ast(layout))
+    if used_imports:
+        tree.body.insert(index, ast.ImportFrom(
+            module='pynecore.core.instance_state',
+            names=[ast.alias(name=name, asname=None) for name in sorted(used_imports)],
+            level=0))
+    return tree

pynecore/transformers/type_checking_stripper.py

@@ -0,0 +1,25 @@
+import ast
+
+
+class TypeCheckingStripperTransformer(ast.NodeTransformer):
+    """
+    Remove `if TYPE_CHECKING:` blocks and the TYPE_CHECKING import from @pyne files.
+    These blocks contain IDE-only type hints (casts, re-annotations) that are unnecessary at runtime.
+    """
+
+    def visit_If(self, node: ast.If) -> ast.AST | None:
+        # Match: if TYPE_CHECKING:
+        if isinstance(node.test, ast.Name) and node.test.id == 'TYPE_CHECKING':
+            return None
+        # Match: if typing.TYPE_CHECKING:
+        if (isinstance(node.test, ast.Attribute) and node.test.attr == 'TYPE_CHECKING'
+                and isinstance(node.test.value, ast.Name) and node.test.value.id == 'typing'):
+            return None
+        return self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> ast.ImportFrom | None:
+        if node.module == 'typing':
+            node.names = [alias for alias in node.names if alias.name != 'TYPE_CHECKING']
+            if not node.names:
+                return None
+        return node

pynecore/transformers/unused_series_detector.py

@@ -0,0 +1,267 @@
+"""
+Unused Series Detector Transformer
+
+This transformer detects Series[T] annotated variables that are never actually indexed
+and removes the Series annotation to optimize performance.
+
+It runs before SeriesTransformer in the AST transformation pipeline.
+"""
+
+import ast
+from typing import Set, Dict
+
+
+def _is_in_annotation_context(node: ast.Subscript) -> bool:
+    """Check if a subscript is part of a type annotation"""
+    # This is a simple heuristic: if the subscript value is "Series",
+    # it's likely a type annotation
+    if isinstance(node.value, ast.Name) and node.value.id == "Series":
+        return True
+    return False
+
+
+class UnusedSeriesDetectorTransformer(ast.NodeTransformer):
+    """
+    AST transformer that removes unnecessary Series annotations.
+
+    For variables annotated as Series[T] but never indexed with subscript operator [],
+    this transformer changes their type to just T, avoiding unnecessary Series overhead.
+    """
+
+    def __init__(self):
+        # Track variables with their scope
+        self.series_vars: Dict[str, Set[str]] = {}  # scope -> set of variable names
+        self.indexed_vars: Dict[str, Set[str]] = {}  # scope -> set of variable names
+        self.current_scope: str = "__module__"
+        self.scope_stack: list[str] = []
+        # Track local variables in each scope to handle shadowing
+        self.local_vars: Dict[str, Set[str]] = {}  # scope -> set of local variable names
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:
+        """Track function scope and process function definitions"""
+        # Save current scope
+        self.scope_stack.append(self.current_scope)
+        self.current_scope = f"{self.current_scope}.{node.name}" if self.current_scope != "__module__" else node.name
+
+        # Process the function
+        self.generic_visit(node)
+
+        # Restore scope
+        self.current_scope = self.scope_stack.pop()
+
+        return node
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> ast.AnnAssign:
+        """Detect Series annotations in variable assignments"""
+        if isinstance(node.target, ast.Name):
+            var_name = node.target.id
+
+            # Check if this is a Series annotation
+            if self._is_series_annotation(node.annotation):
+                if self.current_scope not in self.series_vars:
+                    self.series_vars[self.current_scope] = set()
+                self.series_vars[self.current_scope].add(var_name)
+
+                # Track local variables to handle shadowing
+                if self.current_scope not in self.local_vars:
+                    self.local_vars[self.current_scope] = set()
+                self.local_vars[self.current_scope].add(var_name)
+
+        # Continue visiting child nodes
+        self.generic_visit(node)
+        return node
+
+    def visit_arg(self, node: ast.arg) -> ast.arg:
+        """Detect Series annotations in function arguments"""
+        if node.annotation and self._is_series_annotation(node.annotation):
+            if self.current_scope not in self.series_vars:
+                self.series_vars[self.current_scope] = set()
+            self.series_vars[self.current_scope].add(node.arg)
+
+            # Track local variables to handle shadowing
+            if self.current_scope not in self.local_vars:
+                self.local_vars[self.current_scope] = set()
+            self.local_vars[self.current_scope].add(node.arg)
+
+        return node
+
+    def visit_Subscript(self, node: ast.Subscript) -> ast.Subscript:
+        """Track which variables are actually indexed"""
+        # Only track subscripts that are NOT type annotations
+        # Type annotations like Series[float] should not be counted as indexing
+        if isinstance(node.value, ast.Name) and not _is_in_annotation_context(node):
+            var_name = node.value.id
+
+            # Mark this variable as indexed
+            self._mark_variable_as_indexed(var_name)
+
+        # Continue visiting child nodes
+        self.generic_visit(node)
+        return node
+
+    def visit_Call(self, node: ast.Call) -> ast.Call:
+        """Just visit child nodes - we don't need to track function calls"""
+        # The key insight: if a variable is passed to a function, that doesn't mean
+        # it needs to be Series in the calling scope. Only direct indexing matters.
+        # The ClosureArgumentsTransformer preserves Series annotations on parameters
+        # that actually get indexed, so we can rely on that.
+
+        # Continue visiting child nodes
+        self.generic_visit(node)
+        return node
+
+    def _mark_variable_as_indexed(self, var_name: str):
+        """Mark a variable as indexed in the current scope"""
+        if self.current_scope not in self.indexed_vars:
+            self.indexed_vars[self.current_scope] = set()
+        self.indexed_vars[self.current_scope].add(var_name)
+
+    @staticmethod
+    def _is_series_annotation(annotation: ast.AST) -> bool:
+        """Check if an annotation is Series[T]"""
+        if isinstance(annotation, ast.Subscript):
+            if isinstance(annotation.value, ast.Name) and annotation.value.id == "Series":
+                return True
+            elif isinstance(annotation.value, ast.Attribute):
+                # Handle cases like types.Series
+                if annotation.value.attr == "Series":
+                    return True
+        return False
+
+    @staticmethod
+    def _get_inner_type(annotation: ast.AST) -> ast.expr:
+        """Extract T from Series[T]"""
+        if isinstance(annotation, ast.Subscript) and isinstance(annotation.slice, ast.Name):
+            return annotation.slice
+        elif isinstance(annotation, ast.Subscript) and hasattr(annotation.slice, 'value'):
+            # Handle ast.Index in older Python versions
+            return getattr(annotation.slice, 'value')
+        # Default to Any if we can't determine the inner type
+        return ast.Name(id='Any', ctx=ast.Load())
+
+    def _resolve_series_owner(self, scope: str, var_name: str) -> str | None:
+        """Nearest enclosing scope (including ``scope`` itself) that declares
+        ``var_name`` as a Series.
+
+        Mirrors :meth:`SeriesTransformer._lookup`: a subscript resolves to the
+        closest series declaration walking outwards through the scope chain.
+        """
+        parts = scope.split('.')
+        for i in range(len(parts), 0, -1):
+            candidate = '.'.join(parts[:i])
+            if var_name in self.series_vars.get(candidate, set()):
+                return candidate
+        if var_name in self.series_vars.get("__module__", set()):
+            return "__module__"
+        return None
+
+    def optimize(self, tree: ast.AST) -> ast.AST:
+        """
+        Main optimization pass - removes unused Series annotations
+        """
+        # First pass: collect all Series variables and indexed variables
+        self.visit(tree)
+
+        # A parent-scope series indexed only from within a nested function is
+        # resolved through the scope chain by SeriesTransformer, so it must not
+        # be pruned. Credit the nearest enclosing scope that declares each
+        # indexed name as a Series, mirroring that resolution.
+        for scope, names in list(self.indexed_vars.items()):
+            for var_name in names:
+                owner = self._resolve_series_owner(scope, var_name)
+                if owner is not None and owner != scope:
+                    self.indexed_vars.setdefault(owner, set()).add(var_name)
+
+        # Second pass: remove Series annotations from non-indexed variables
+        optimizer = SeriesOptimizer(self.series_vars, self.indexed_vars)
+        return optimizer.visit(tree)
+
+
+class SeriesOptimizer(ast.NodeTransformer):
+    """Second pass transformer that actually removes the unused Series annotations"""
+
+    def __init__(self, series_vars: Dict[str, Set[str]], indexed_vars: Dict[str, Set[str]]):
+        self.series_vars = series_vars
+        self.indexed_vars = indexed_vars
+        self.current_scope = "__module__"
+        self.scope_stack: list[str] = []
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:
+        """Track function scope"""
+        self.scope_stack.append(self.current_scope)
+        self.current_scope = f"{self.current_scope}.{node.name}" if self.current_scope != "__module__" else node.name
+
+        # Process the function
+        self.generic_visit(node)
+
+        # Restore scope
+        self.current_scope = self.scope_stack.pop()
+
+        return node
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> ast.AnnAssign:
+        """Remove Series annotation if variable is never indexed"""
+        if isinstance(node.target, ast.Name):
+            var_name = node.target.id
+
+            # Check if this is an unused Series variable
+            if self._is_unused_series(var_name) and self._is_series_annotation(node.annotation):
+                # Replace Series[T] with just T
+                node.annotation = self._get_inner_type(node.annotation)
+
+        self.generic_visit(node)
+        return node
+
+    def visit_arg(self, node: ast.arg) -> ast.arg:
+        """Remove Series annotation from function arguments if never indexed"""
+        if (node.annotation and self._is_unused_series(node.arg) and
+                self._is_series_annotation(node.annotation)):
+            # Replace Series[T] with just T
+            node.annotation = self._get_inner_type(node.annotation)
+
+        return node
+
+    def _is_unused_series(self, var_name: str) -> bool:
+        """Check if a variable is Series-annotated but never indexed in the current scope"""
+        # Check if variable is Series in current scope
+        is_series = (self.current_scope in self.series_vars and
+                     var_name in self.series_vars[self.current_scope])
+
+        # Check if variable is indexed in current scope
+        is_indexed = (self.current_scope in self.indexed_vars and
+                      var_name in self.indexed_vars[self.current_scope])
+
+        # Return True if it's Series but not indexed in this scope
+        return is_series and not is_indexed
+
+    def _get_relevant_scopes(self) -> list[str]:
+        """Get all scopes that could contain the variable (current + parents)"""
+        scopes = ["__module__"]
+        if self.current_scope != "__module__":
+            parts = self.current_scope.split('.')
+            for i in range(len(parts)):
+                scopes.append('.'.join(parts[:i + 1]))
+        return scopes
+
+    @staticmethod
+    def _is_series_annotation(annotation: ast.AST) -> bool:
+        """Check if an annotation is Series[T]"""
+        if isinstance(annotation, ast.Subscript):
+            if isinstance(annotation.value, ast.Name) and annotation.value.id == "Series":
+                return True
+            elif isinstance(annotation.value, ast.Attribute):
+                if annotation.value.attr == "Series":
+                    return True
+        return False
+
+    @staticmethod
+    def _get_inner_type(annotation: ast.AST) -> ast.expr:
+        """Extract T from Series[T]"""
+        if isinstance(annotation, ast.Subscript):
+            if isinstance(annotation.slice, ast.Name):
+                return annotation.slice
+            elif hasattr(annotation.slice, 'value'):
+                # Handle ast.Index in older Python versions
+                return getattr(annotation.slice, 'value')
+        # Default to float if we can't determine
+        return ast.Name(id='float', ctx=ast.Load())