feat: rename generative slots -> generative stubs (#801)

* feat: rename generative slots -> generative stubs

* feat: add backwards compat with deprecation warning; add genslot fixer cli

Author: jakelorocco

cli/fix/__init__.py

@@ -14,6 +14,7 @@ class _FixMode(StrEnum):
     ADD_STREAM_LOOP = "add-stream-loop"
 
 
-from cli.fix.commands import fix_async  # noqa: E402
+from cli.fix.commands import fix_async, fix_genslots  # noqa: E402
 
 fix_app.command("async")(fix_async)
+fix_app.command("genslots")(fix_genslots)

cli/fix/fixer.py cli/fix/async_fixer.pycli/fix/fixer.py renamed to cli/fix/async_fixer.py

@@ -1,4 +1,4 @@
-"""CLI command for `m fix async`."""
+"""CLI commands for `m fix async` and `m fix genslots`."""
 
 from pathlib import Path
 
@@ -54,7 +54,7 @@ def fix_async(
         `await r.astream()`, or a `while not r.is_computed()` loop are
         automatically skipped, even when nested inside if/try/for blocks.
     """
-    from cli.fix.fixer import fix_path
+    from cli.fix.async_fixer import fix_path
 
     target = Path(path)
     if not target.exists():
@@ -75,3 +75,51 @@ def fix_async(
         typer.echo(
             f"  {loc.filepath}:{loc.line} - {loc.function_name}() [{loc.call_style}]"
         )
+
+
+def fix_genslots(
+    path: str = typer.Argument(..., help="File or directory to scan"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Report locations without modifying files"
+    ),
+):
+    """Rewrite old genslot imports and class names to genstub equivalents.
+
+    Args:
+        path: File or directory to scan.
+        dry_run: If ``True``, report locations without modifying files.
+
+    Raises:
+        typer.Exit: If *path* does not exist.
+
+    \b
+    Rewrites:
+      - mellea.stdlib.components.genslot → mellea.stdlib.components.genstub
+      - GenerativeSlot      → GenerativeStub
+      - SyncGenerativeSlot  → SyncGenerativeStub
+      - AsyncGenerativeSlot → AsyncGenerativeStub
+
+    \b
+    Best practices:
+      - Run with --dry-run first to review what will be changed.
+      - The tool is idempotent — running it twice on the same file is safe.
+    """
+    from cli.fix.genstub_fixer import fix_genslot_path
+
+    target = Path(path)
+    if not target.exists():
+        typer.echo(f"Error: {path} does not exist", err=True)
+        raise typer.Exit(code=1)
+
+    result = fix_genslot_path(target, dry_run=dry_run)
+
+    if result.total_fixes == 0:
+        typer.echo("No genslot references found.")
+        return
+
+    action = "Found" if dry_run else "Fixed"
+    typer.echo(
+        f"{action} {result.total_fixes} reference(s) in {result.files_affected} file(s):"
+    )
+    for loc in result.locations:
+        typer.echo(f"  {loc.filepath}:{loc.line} - {loc.description}")

cli/fix/commands.py

@@ -0,0 +1,195 @@
+"""Line-based detection and rewriting of old genslot imports and class names.
+
+Targets:
+- ``from mellea.stdlib.components.genslot import ...`` → ``genstub``
+- ``import mellea.stdlib.components.genslot [as ...]`` → ``genstub``
+- ``from mellea.stdlib.components import genslot [as ...]`` → ``genstub``
+- ``from .genslot import ...`` (relative imports) → ``genstub``
+- ``GenerativeSlot`` → ``GenerativeStub`` (and Sync/Async variants)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+# Directories to skip during traversal.
+SKIP_DIRS = {"__pycache__", ".git", ".venv", "node_modules"}
+
+# Ordered longest-first so ``SyncGenerativeSlot`` is replaced before ``GenerativeSlot``.
+_CLASS_RENAMES: list[tuple[str, str]] = [
+    ("AsyncGenerativeSlot", "AsyncGenerativeStub"),
+    ("SyncGenerativeSlot", "SyncGenerativeStub"),
+    ("GenerativeSlot", "GenerativeStub"),
+]
+
+# --- Module-path patterns ---
+
+# Fully-qualified module path (handles both `from … import` and `import …`).
+_MODULE_OLD = "mellea.stdlib.components.genslot"
+_MODULE_NEW = "mellea.stdlib.components.genstub"
+_MODULE_RE = re.compile(re.escape(_MODULE_OLD))
+
+# `from mellea.stdlib.components import genslot` (with optional ` as …`).
+_FROM_PARENT_RE = re.compile(
+    r"(\bfrom\s+mellea\.stdlib\.components\s+import\s+)"  # prefix
+    r"(\bgenslot\b)"  # the name to replace
+)
+
+# Relative imports: `from .genslot import …` or `from ..components.genslot import …`
+# Matches any leading dots followed by an optional dotted path ending in `.genslot`.
+_RELATIVE_RE = re.compile(
+    r"(\bfrom\s+\.[\w.]*?)"  # `from .` or `from ..foo.bar`
+    r"(\bgenslot\b)"  # the segment to replace
+)
+
+# Patterns for old class names — word-boundary aware to avoid false positives.
+_CLASS_RES: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(rf"\b{old}\b"), new) for old, new in _CLASS_RENAMES
+]
+
+
+@dataclass
+class GenStubFixLocation:
+    """A single replacement within a file.
+
+    Args:
+        filepath: Path to the source file.
+        line: One-based line number.
+        description: Human-readable description of the replacement.
+    """
+
+    filepath: Path
+    line: int
+    description: str
+
+
+@dataclass
+class GenStubFixResult:
+    """Aggregated results across all scanned files.
+
+    Args:
+        locations: Individual fix locations.
+        total_fixes: Total replacements made (or found in dry-run).
+        files_affected: Number of distinct files modified.
+    """
+
+    locations: list[GenStubFixLocation]
+    total_fixes: int
+    files_affected: int
+
+
+def _fix_line(line: str) -> tuple[str, list[str]]:
+    """Apply all genslot→genstub replacements to a single line.
+
+    Returns:
+        A (new_line, descriptions) tuple.  *descriptions* is empty when the
+        line was not changed.
+    """
+    descriptions: list[str] = []
+
+    # Fully-qualified module path.
+    if _MODULE_RE.search(line):
+        line = _MODULE_RE.sub(_MODULE_NEW, line)
+        descriptions.append(f"{_MODULE_OLD} → {_MODULE_NEW}")
+
+    # `from mellea.stdlib.components import genslot`
+    if _FROM_PARENT_RE.search(line):
+        line = _FROM_PARENT_RE.sub(r"\1genstub", line)
+        descriptions.append("import genslot → import genstub")
+
+    # Relative imports: `from .genslot import …`
+    if _RELATIVE_RE.search(line):
+        line = _RELATIVE_RE.sub(r"\1genstub", line)
+        descriptions.append(".genslot → .genstub")
+
+    for pattern, replacement in _CLASS_RES:
+        if pattern.search(line):
+            line = pattern.sub(replacement, line)
+            old = pattern.pattern.replace(r"\b", "")
+            descriptions.append(f"{old} → {replacement}")
+
+    return line, descriptions
+
+
+def find_genslot_refs(source: str, filepath: Path) -> list[GenStubFixLocation]:
+    """Scan *source* for old genslot references and return their locations.
+
+    Args:
+        source: Python source text.
+        filepath: Used for the ``filepath`` field in returned locations.
+
+    Returns:
+        List of locations that would be changed.
+    """
+    locations: list[GenStubFixLocation] = []
+    for lineno, line in enumerate(source.splitlines(), start=1):
+        _, descriptions = _fix_line(line)
+        for desc in descriptions:
+            locations.append(
+                GenStubFixLocation(filepath=filepath, line=lineno, description=desc)
+            )
+    return locations
+
+
+def fix_genslot_file(
+    filepath: Path, *, dry_run: bool = False
+) -> list[GenStubFixLocation]:
+    """Fix a single file.
+
+    Args:
+        filepath: Path to the Python file to fix.
+        dry_run: If ``True``, return locations without modifying the file.
+
+    Returns:
+        List of locations found (and optionally fixed).
+    """
+    source = filepath.read_text()
+    locations = find_genslot_refs(source, filepath)
+
+    if not locations or dry_run:
+        return locations
+
+    new_lines: list[str] = []
+    for line in source.splitlines(keepends=True):
+        fixed, _ = _fix_line(line)
+        new_lines.append(fixed)
+
+    filepath.write_text("".join(new_lines))
+    return locations
+
+
+def fix_genslot_path(path: Path, *, dry_run: bool = False) -> GenStubFixResult:
+    """Fix a file or directory recursively.
+
+    Args:
+        path: File or directory to process.
+        dry_run: If ``True``, report locations without modifying files.
+
+    Returns:
+        Aggregated result with all fix locations and summary counts.
+    """
+    all_locations: list[GenStubFixLocation] = []
+    files_affected = 0
+
+    if path.is_file():
+        files = [path]
+    else:
+        files = sorted(path.rglob("*.py"))
+
+    for f in files:
+        parts = f.relative_to(path).parts if path.is_dir() else ()
+        if any(part in SKIP_DIRS for part in parts):
+            continue
+
+        locs = fix_genslot_file(f, dry_run=dry_run)
+        if locs:
+            all_locations.extend(locs)
+            files_affected += 1
+
+    return GenStubFixResult(
+        locations=all_locations,
+        total_fixes=len(all_locations),
+        files_affected=files_affected,
+    )

cli/fix/genstub_fixer.py

@@ -162,7 +162,7 @@ from typing import Literal
 
 from mellea import generative, start_session
 from mellea.core import Requirement
-from mellea.stdlib.components.genslot import PreconditionException
+from mellea.stdlib.components.genstub import PreconditionException
 from mellea.stdlib.requirements import simple_validate
 from mellea.stdlib.sampling import RejectionSamplingStrategy
 

docs/docs/concepts/requirements-system.md

@@ -33,7 +33,7 @@
             "pages": [
               "tutorials/01-your-first-generative-program",
               "tutorials/02-streaming-and-async",
-              "tutorials/03-using-generative-slots",
+              "tutorials/03-using-generative-stubs",
               "tutorials/04-making-agents-reliable",
               "tutorials/05-mifying-legacy-code"
             ]

docs/docs/docs.json

@@ -8,7 +8,7 @@ This example shows the most direct path from raw text to typed, structured
 output in Mellea: a `@generative` function whose return annotation tells the
 runtime exactly what shape the result must have.
 
-**Source file:** `docs/examples/information_extraction/101_with_gen_slots.py`
+**Source file:** `docs/examples/information_extraction/101_with_gen_stubs.py`
 
 ## Concepts covered
 
@@ -46,7 +46,7 @@ def extract_all_person_names(doc: str) -> list[str]:
 ```
 
 The `@generative` decorator converts a bare function stub into a generative
-slot. Three things drive the extraction:
+stub. Three things drive the extraction:
 
 - **Parameter names** (`doc`) become the named inputs the model receives.
 - **Return annotation** (`list[str]`) tells the runtime to parse and validate
@@ -79,7 +79,7 @@ extracted, type-validated data — not a raw string or a thunk.
 ```python
 # pytest: ollama, llm
 
-"""Simple Example of information extraction with Mellea using generative slots."""
+"""Simple Example of information extraction with Mellea using generative stubs."""
 
 from mellea import generative, start_session
 from mellea.backends import model_ids

docs/docs/examples/data-extraction-pipeline.md

@@ -28,7 +28,7 @@ to run.
 | Category | What it shows |
 | -------- | ------------- |
 | `instruct_validate_repair/` | The IVR loop end-to-end: basic generation, adding requirements, automatic repair on failure, custom validators |
-| `generative_slots/` | `@generative` functions with typed returns, pipeline composition, `ChatContext` persona injection, pre/postcondition checks |
+| `generative_stubs/` | `@generative` functions with typed returns, pipeline composition, `ChatContext` persona injection, pre/postcondition checks |
 | `context/` | Context inspection, sampling with context trees, parallel context branches |
 | `sessions/` | Custom session types and backend selection |
 | `async/` | How to utilize basic async capabilities |
@@ -103,7 +103,7 @@ to run.
 | Category | What it shows |
 | -------- | ------------- |
 | `hello_world.py` | Minimal single-file starting point |
-| `tutorial/` | Python script versions of the tutorials: email generation, IVR, generative slots, contexts, MObjects, model options, and more |
+| `tutorial/` | Python script versions of the tutorials: email generation, IVR, generative stubs, contexts, MObjects, model options, and more |
 | `notebooks/` | Jupyter notebook versions of the same tutorials for interactive, cell-by-cell exploration |
 
 ---

docs/docs/examples/index.md

@@ -100,7 +100,7 @@ is never called:
 ```python
 from mellea import generative, start_session
 from mellea.core import Requirement
-from mellea.stdlib.components.genslot import PreconditionException
+from mellea.stdlib.components.genstub import PreconditionException
 from mellea.stdlib.requirements import simple_validate
 from typing import Literal
 

docs/docs/guide/generative-functions.md

@@ -528,7 +528,7 @@ fails — i.e., before the LLM call is made. Catch it to handle pre-call validat
 failures gracefully.
 
 ```python
-from mellea.stdlib.components.genslot import PreconditionException
+from mellea.stdlib.components.genstub import PreconditionException
 
 try:
     result = my_generative_fn(m, ...)