syncraft 0.2.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

syncraft/__init__.py

@@ -0,0 +1,59 @@
+from .syntax import (
+	Syntax,
+	choice,
+	lazy,
+	success,
+	fail,
+    run,
+)
+from .parser import (
+	parse,
+	sqlglot,
+	token,
+	identifier,
+	variable,
+	literal,
+	number,
+	string,
+	regex,
+	until,
+)
+from .generator import (
+	generate,
+)
+from .finder import (
+	find,
+	matches,
+	anything,
+)
+from .constraint import (
+	Constraint,
+	Quantifier,
+	forall,
+	exists,
+)
+from .ast import (
+	AST,
+	Token,
+	Then,
+	ThenKind,
+	Choice,
+	ChoiceKind,
+	Many,
+	Marked,
+	Collect,
+)
+
+__all__ = [
+	# syntax & core
+	"Syntax", "choice", "lazy", "success", "fail", "run",
+	# parsing/generation helpers
+	"parse", "sqlglot", "token", "identifier", "variable", "literal", "number", "string", "regex", "until",
+	"generate",
+	# finder
+	"find", "matches", "anything",
+	# constraints
+	"Constraint", "Quantifier", "forall", "exists",
+	# ast
+	"AST", "Token", "Then", "ThenKind", "Choice", "ChoiceKind", "Many", "Marked", "Collect",
+]

syncraft/algebra.py

@@ -93,8 +93,38 @@ class Algebra(Generic[A, S]):
     def __call__(self, input: S, use_cache: bool) -> Either[Any, Tuple[A, S]]:
         return self.run(input, use_cache=use_cache)
 
-    
     def run(self, input: S, use_cache: bool) -> Either[Any, Tuple[A, S]]:
+        """Execute this algebra on the given state with optional memoization.
+
+        This is the core evaluation entry point used by all combinators. It
+        supports per-"parser" memoization and protects against infinite
+        recursion by detecting left-recursive re-entrance.
+
+        Args:
+            input: The initial state to run against. Must be hashable as it's
+                used as a cache key.
+            use_cache: When True, memoize results for ``(self.run_f, input)``
+                so repeated calls short-circuit. When False, the cache entry is
+                cleared after the run to effectively disable the cache. 
+
+        Returns:
+            Either[Error, Tuple[A, S]]: On success, ``Right((value, next_state))``.
+            On failure, ``Left(Error)``. Errors produced downstream are
+            automatically enriched with ``this=self`` and ``state=input`` to
+            preserve context. If an exception escapes the user code, it's
+            captured and returned as ``Left(Error)`` with a traceback in
+            ``stack``.
+
+        Notes:
+            - Left recursion: if a re-entrant call is observed on the same
+              ``input`` while an evaluation is in progress, a ``Left(Error)``
+              is returned indicating left-recursion was detected.
+            - Memoization scope: results are cached per ``run_f`` (the concrete
+              compiled function of this algebra) and keyed by the input state.
+            - Commitment: downstream combinators (e.g. ``cut``) may set the
+              ``committed`` flag in ``Error``; ``run`` preserves that flag but
+              does not set it itself.
+        """
         cache = self._cache[self.run_f]
         assert cache is not None, "Cache should be initialized in __post_init__"
         if input in cache:
@@ -136,12 +166,31 @@ class Algebra(Generic[A, S]):
         
     @classmethod
     def lazy(cls, thunk: Callable[[], Algebra[A, S]]) -> Algebra[A, S]:
+        """Lazily construct an algebra at run time.
+
+        Useful for recursive definitions. The thunk is evaluated when this
+        algebra runs, and the resulting algebra is executed.
+
+        Args:
+            thunk: Zero-argument function returning the underlying algebra.
+
+        Returns:
+            An algebra that defers to the thunk-provided algebra.
+        """
         def lazy_run(input: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
             return thunk().run(input, use_cache)
         return cls(lazy_run, name=cls.__name__ + '.lazy')
     
     @classmethod
     def fail(cls, error: Any) -> Algebra[Any, S]:
+        """Return an algebra that always fails with ``error``.
+
+        Args:
+            error: The error payload to wrap in ``Left``.
+
+        Returns:
+            An algebra producing ``Left(Error(...))`` without consuming input.
+        """
         def fail_run(input: S, use_cache:bool) -> Either[Any, Tuple[Any, S]]:
             return Left(Error(
                 error=error,
@@ -152,12 +201,35 @@ class Algebra(Generic[A, S]):
     
     @classmethod
     def success(cls, value: Any) -> Algebra[Any, S]:
+        """Return an algebra that always succeeds with ``value``.
+
+        The input state is passed through unchanged.
+
+        Args:
+            value: The constant value to return.
+
+        Returns:
+            ``Right((value, input))`` for any input state.
+        """
         def success_run(input: S, use_cache:bool) -> Either[Any, Tuple[Any, S]]:
             return Right((value, input))
         return cls(success_run, name=cls.__name__ + '.success')
     
     @classmethod
     def factory(cls, name: str, *args: Any, **kwargs: Any) -> Algebra[A, S]:
+        """Call a named class method to construct an algebra.
+
+        Args:
+            name: Name of a classmethod/staticmethod on this class.
+            *args: Positional args passed to the method.
+            **kwargs: Keyword args passed to the method.
+
+        Returns:
+            The algebra returned by the method.
+
+        Raises:
+            ValueError: If the method is missing or not callable.
+        """
         method = getattr(cls, name, None)
         if method is None or not callable(method):
             raise ValueError(f"Method {name} is not defined in {cls.__name__}")
@@ -166,6 +238,14 @@ class Algebra(Generic[A, S]):
 
 
     def cut(self) -> Algebra[A, S]:
+        """Commit this branch by marking failures as committed.
+
+        Converts downstream errors into committed errors (``committed=True``),
+        which prevents alternatives from being tried in ``or_else``.
+
+        Returns:
+            An algebra that commits errors produced by this one.
+        """
         def commit_error(e: Any) -> Error:
             match e:
                 case Error():
@@ -188,6 +268,15 @@ class Algebra(Generic[A, S]):
                     ], 
                     Either[Any, Tuple[B, S]]], 
                     ctx: Optional[Any] = None) -> Algebra[A | B, S]:
+        """Run a handler only when this algebra fails.
+
+        Args:
+            func: Callback ``(alg, input, left, ctx) -> Either`` executed on failure.
+            ctx: Optional context object passed to the callback.
+
+        Returns:
+            An algebra that intercepts failures and can recover or transform them.
+        """
         assert callable(func), "func must be callable"
         def fail_run(input: S, use_cache:bool) -> Either[Any, Tuple[A | B, S]]:
             result = self.run(input, use_cache)
@@ -206,6 +295,15 @@ class Algebra(Generic[A, S]):
                         ], 
                         Either[Any, Tuple[B, S]]], 
                         ctx: Optional[Any] = None) -> Algebra[A | B, S]:
+        """Run a handler only when this algebra succeeds.
+
+        Args:
+            func: Callback ``(alg, input, right, ctx) -> Either`` executed on success.
+            ctx: Optional context object passed to the callback.
+
+        Returns:
+            An algebra that can transform or post-process successes.
+        """
         assert callable(func), "func must be callable"
         def success_run(input: S, use_cache:bool) -> Either[Any, Tuple[A | B, S]]:
             result = self.run(input, use_cache)
@@ -244,24 +342,29 @@ class Algebra(Generic[A, S]):
         return lazy_self
 
 ######################################################## map on state ###########################################
-    def post_state(self, f: Callable[[S], S]) -> Algebra[A, S]:
-        def post_state_run(input: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
-            match self.run(input, use_cache):
-                case Right((value, state)):
-                    return Right((value, f(state)))
-                case Left(err):
-                    return Left(err)
-                case x:
-                    raise ValueError(f"Unexpected result from self.run {x}")
-        return self.__class__(post_state_run, name=self.name) 
+    def map_state(self, f: Callable[[S], S]) -> Algebra[A, S]:
+        """Map the input state before running this algebra.
+
+        Args:
+            f: ``S -> S`` function applied to the state prior to running.
 
-    def pre_state(self, f: Callable[[S], S]) -> Algebra[A, S]:
-        def pre_state_run(state: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
+        Returns:
+            An algebra that runs with ``f(state)``.
+        """
+        def map_state_run(state: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
             return self.run(f(state), use_cache)
-        return self.__class__(pre_state_run, name=self.name) 
+        return self.__class__(map_state_run, name=self.name) 
 
 
     def map_all(self, f: Callable[[A, S], Tuple[B, S]]) -> Algebra[B, S]:
+        """Map both the produced value and the resulting state on success.
+
+        Args:
+            f: Function mapping ``(value, state)`` to ``(new_value, new_state)``.
+
+        Returns:
+            An algebra producing the transformed value and state.
+        """
         def map_all_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
             match self.run(input, use_cache):
                 case Right((value, state)):
@@ -273,23 +376,54 @@ class Algebra(Generic[A, S]):
                     raise ValueError(f"Unexpected result from self.run {x}")
         return self.__class__(map_all_run, name=self.name) # type: ignore
 ######################################################## fundamental combinators ############################################    
-    def fmap(self, f: Callable[[A], B]) -> Algebra[B, S]:
-        def fmap_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
+    def map(self, f: Callable[[A], B]) -> Algebra[B, S]:
+        """Transform the success value, leaving the state unchanged.
+
+        Args:
+            f: Mapper from ``A`` to ``B``.
+
+        Returns:
+            An algebra that yields ``B`` with the same resulting state.
+        """
+        def map_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
             parsed = self.run(input, use_cache)
             if isinstance(parsed, Right):
                 return Right((f(parsed.value[0]), parsed.value[1]))            
             else:
                 return cast(Either[Any, Tuple[B, S]], parsed)
-        return self.__class__(fmap_run, name=self.name)  # type: ignore
+        return self.__class__(map_run, name=self.name)  # type: ignore
 
-    
-    def map(self, f: Callable[[A], B]) -> Algebra[B, S]:
-        return self.fmap(f)
-    
+        
     def bimap(self, f: Callable[[A], B], i: Callable[[B], A]) -> Algebra[B, S]:
-        return self.fmap(f).pre_state(lambda s: s.map(i))
+        """Bidirectionally map values with an inverse, updating the state.
+
+        Applies ``f`` to the success value. The state is pre-mapped with the
+        inverse ``i`` via the state's ``map`` method to preserve round-trips.
+
+        Args:
+            f: Forward mapping ``A -> B``.
+            i: Inverse mapping ``B -> A`` applied to the state.
+
+        Returns:
+            An algebra producing ``B`` while keeping value/state alignment.
+        
+        Note:
+            Different subclass of Algebra can override state.map method to change 
+            the behavior of bimap. For example, ParserState.map will return the
+            state unchanged, and GenState.map will apply the inverse map and update 
+            the next AST node for generation.
+        """
+        return self.map(f).map_state(lambda s: s.map(i))
 
     def map_error(self, f: Callable[[Optional[Any]], Any]) -> Algebra[A, S]:
+        """Transform the error payload when this algebra fails.
+
+        Args:
+            f: Function applied to the error payload inside ``Left``.
+
+        Returns:
+            An algebra that preserves successes and maps failures.
+        """
         def map_error_run(input: S, use_cache:bool) -> Either[Any, Tuple[A, S]]:
             parsed = self.run(input, use_cache)
             if isinstance(parsed, Left):
@@ -298,6 +432,17 @@ class Algebra(Generic[A, S]):
         return self.__class__(map_error_run, name=self.name)  
 
     def flat_map(self, f: Callable[[A], Algebra[B, S]]) -> Algebra[B, S]:
+        """Chain computations where the next algebra depends on the value.
+
+        On success, passes the produced value to ``f`` to obtain the next
+        algebra, then runs it with the resulting state.
+
+        Args:
+            f: Mapper from a value to the next algebra.
+
+        Returns:
+            An algebra yielding the result of the chained computation.
+        """
         def flat_map_run(input: S, use_cache:bool) -> Either[Any, Tuple[B, S]]:
             parsed = self.run(input, use_cache)
             if isinstance(parsed, Right):
@@ -308,6 +453,18 @@ class Algebra(Generic[A, S]):
 
     
     def or_else(self: Algebra[A, S], other: Algebra[B, S]) -> Algebra[Choice[A, B], S]:
+        """Try this algebra; if it fails uncommitted, try ``other``.
+
+        If the failure is committed (``committed=True``), the alternative is
+        not attempted and the error is propagated.
+
+        Args:
+            other: Fallback algebra to try from the same input state.
+
+        Returns:
+            An algebra producing ``Choice.LEFT`` for this success or
+            ``Choice.RIGHT`` for the other's success.
+        """
         def or_else_run(input: S, use_cache:bool) -> Either[Any, Tuple[Choice[A, B], S]]:
             match self.run(input, use_cache):
                 case Right((value, state)):
@@ -325,27 +482,75 @@ class Algebra(Generic[A, S]):
         return self.__class__(or_else_run, name=f'{self.name} | {other.name}')  # type: ignore
 
     def then_both(self, other: Algebra[B, S]) -> Algebra[Then[A, B], S]:
+        """Sequence two algebras and keep both values.
+
+        Returns a ``Then(kind=BOTH)`` holding the left and right values.
+
+        Args:
+            other: The algebra to run after this one.
+
+        Returns:
+            An algebra producing ``Then(left, right, kind=BOTH)``.
+        """
         def then_both_f(a: A) -> Algebra[Then[A, B], S]:
             def combine(b: B) -> Then[A, B]:
                 return Then(left=a, right=b, kind=ThenKind.BOTH)
-            return other.fmap(combine)
+            return other.map(combine)
         return self.flat_map(then_both_f).named(f'{self.name} + {other.name}')
 
     def then_left(self, other: Algebra[B, S]) -> Algebra[Then[A, B], S]:
+        """Sequence two algebras, keep the left value in the result.
+
+        Produces ``Then(kind=LEFT)`` with both values attached.
+
+        Args:
+            other: The algebra to run after this one.
+
+        Returns:
+            An algebra producing ``Then(left, right, kind=LEFT)``.
+        """
         def then_left_f(a: A) -> Algebra[Then[A, B], S]:
             def combine(b: B) -> Then[A, B]:
                 return Then(left=a, right=b, kind=ThenKind.LEFT)
-            return other.fmap(combine)
+            return other.map(combine)
         return self.flat_map(then_left_f).named(f'{self.name} // {other.name}')
 
     def then_right(self, other: Algebra[B, S]) -> Algebra[Then[A, B], S]:
+        """Sequence two algebras, keep the right value in the result.
+
+        Produces ``Then(kind=RIGHT)`` with both values attached.
+
+        Args:
+            other: The algebra to run after this one.
+
+        Returns:
+            An algebra producing ``Then(left, right, kind=RIGHT)``.
+        """
         def then_right_f(a: A) -> Algebra[Then[A, B], S]:
             def combine(b: B) -> Then[A, B]:
                 return Then(left=a, right=b, kind=ThenKind.RIGHT)
-            return other.fmap(combine)
+            return other.map(combine)
         return self.flat_map(then_right_f).named(f'{self.name} >> {other.name}')
 
     def many(self, *, at_least: int, at_most: Optional[int]) -> Algebra[Many[A], S]:
+        """Repeat this algebra and collect results into ``Many``.
+
+        Repeats greedily until failure or no progress. Enforces cardinality
+        constraints. If ``at_most`` is ``None``, there is no upper bound.
+
+        Args:
+            at_least: Minimum number of matches required (>= 1).
+            at_most: Optional maximum number of matches.
+
+        Returns:
+            On success, ``Right((Many(values), state))``.
+        Note:
+            at_most, if given, is enforced strictly, more than at_most matches 
+            is treated as an error.
+        Raises:
+            ValueError: If bounds are invalid (e.g., ``at_least<=0`` or
+            ``at_most<at_least``).
+        """
         if at_least <=0 or (at_most is not None and at_most < at_least):
             raise ValueError(f"Invalid arguments for many: at_least={at_least}, at_most={at_most}")
         def many_run(input: S, use_cache:bool) -> Either[Any, Tuple[Many[A], S]]:

syncraft/ast.py

@@ -90,10 +90,28 @@ class Lens(Generic[C, A]):
 
 @dataclass(frozen=True)
 class Bimap(Generic[A, B]):
+    """A reversible mapping that returns both a forward value and an inverse function.
+
+    ``Bimap`` is like a function ``A -> B`` paired with a way to map a value
+    of type ``B`` back into an ``A``. It composes with other ``Bimap``s or a
+    ``Biarrow`` using ``>>`` and ``<<``-style operations, preserving an
+    automatically derived inverse.
+    """
     run_f: Callable[[A], Tuple[B, Callable[[B], A]]]
     def __call__(self, a: A) -> Tuple[B, Callable[[B], A]]:
+        """Apply the mapping to ``a``.
+
+        Returns:
+            tuple: ``(forward_value, inverse)`` where ``inverse`` maps
+            a compatible ``B`` back into an ``A``.
+        """
         return self.run_f(a)    
     def __rshift__(self, other: Bimap[B, C] | Biarrow[B, C]) -> Bimap[A, C]:
+        """Compose this mapping with another mapping/arrow.
+
+        ``self >> other`` first applies ``self``, then ``other``. The produced
+        inverse runs ``other``'s inverse followed by ``self``'s inverse.
+        """
         if isinstance(other, Biarrow):
             def biarrow_then_run(a: A) -> Tuple[C, Callable[[C], A]]:
                 b, inv1 = self(a)
@@ -114,6 +132,7 @@ class Bimap(Generic[A, B]):
         else:
             raise TypeError(f"Unsupported type for Bimap >>: {type(other)}")
     def __rrshift__(self, other: Bimap[C, A] | Biarrow[C, A]) -> Bimap[C, B]:
+        """Right-composition so arrows or bimaps can be on the left of ``>>``."""
         if isinstance(other, Biarrow):
             def biarrow_then_run(c: C) -> Tuple[B, Callable[[B], C]]:
                 a = other.forward(c)
@@ -137,18 +156,28 @@ class Bimap(Generic[A, B]):
 
 
     @staticmethod
-    def const(a: B)->Bimap[B, B]:
+    def const(a: B) -> Bimap[B, B]:
+        """Return a bimap that ignores input and always yields ``a``.
+
+        The inverse is identity for the output type.
+        """
         return Bimap(lambda _: (a, lambda b: b))
 
     @staticmethod
-    def identity()->Bimap[A, A]:
+    def identity() -> Bimap[A, A]:
+        """The identity bimap where forward and inverse are no-ops."""
         return Bimap(lambda a: (a, lambda b: b))
 
     @staticmethod
     def when(cond: Callable[[A], bool],
              then: Bimap[A, B],
              otherwise: Optional[Bimap[A, C]] = None) -> Bimap[A, A | B | C]:
-        def when_run(a:A) -> Tuple[A | B | C, Callable[[A | B | C], A]]:
+        """Choose a mapping depending on the input value.
+
+        Applies ``then`` when ``cond(a)`` is true; otherwise applies
+        ``otherwise`` if provided, or ``identity``.
+        """
+        def when_run(a: A) -> Tuple[A | B | C, Callable[[A | B | C], A]]:
             bimap = then if cond(a) else (otherwise if otherwise is not None else Bimap.identity())
             abc, inv = bimap(a)
             def inv_f(b: Any) -> A:
@@ -184,11 +213,22 @@ class Reducer(Generic[A, S]):
 
 @dataclass(frozen=True)    
 class AST:
+    """Base class for all Syncraft AST nodes.
+
+    Nodes implement ``bimap`` to transform contained values while providing an
+    inverse that can reconstruct the original node from transformed output.
+    """
     def bimap(self, r: Bimap[Any, Any]=Bimap.identity()) -> Tuple[Any, Callable[[Any], Any]]:
+        """Apply a bimap to this node, returning a value and an inverse.
+
+        The default behavior defers to the provided mapping ``r`` with the
+        node itself as input. The ``r`` only applies to the leaf node of AST tree.
+        """
         return r(self)
 
 @dataclass(frozen=True)
 class Nothing(AST):
+    """Singleton sentinel representing the absence of a value in the AST."""
     _instance = None
     def __new__(cls):
         if cls._instance is None:
@@ -202,9 +242,19 @@ class Nothing(AST):
 
 @dataclass(frozen=True)
 class Marked(Generic[A], AST):
+    """Annotate a AST node with a name.
+
+    Used to tag subtrees so they can be collected by name later (e.g., in
+    collectors) without altering the structural shape.
+    """
     name: str
     value: A
     def bimap(self, r: Bimap[A, B]=Bimap.identity()) -> Tuple[Marked[B], Callable[[Marked[B]], Marked[A]]]:
+        """Transform the inner value while preserving the mark name.
+
+        Returns a new ``Marked`` with transformed value and an inverse that
+        expects a ``Marked`` to recover the original.
+        """
         v, inner_f = self.value.bimap(r) if isinstance(self.value, AST) else r(self.value)
         return Marked(name=self.name, value=v), lambda b: Marked(name = b.name, value=inner_f(b.value))
     
@@ -214,9 +264,19 @@ class ChoiceKind(Enum):
 
 @dataclass(frozen=True)
 class Choice(Generic[A, B], AST):
+    """Represent a binary alternative between left and right values.
+
+    ``kind`` indicates which branch was taken, or ``None`` when unknown.
+    """
     kind: Optional[ChoiceKind]
     value: Optional[A | B] = None
     def bimap(self, r: Bimap[A | B, C]=Bimap.identity()) -> Tuple[Optional[C], Callable[[Optional[C]], Choice[A, B]]]:
+        """Map over the held value if present; propagate ``None`` otherwise.
+
+        The inverse resets ``kind`` to ``None`` to avoid biasing the result.
+        When user edit the data we cannot assume which branch the data should go
+        back to. Set ``kind`` to ``None`` to indicate this situation.
+        """
         if self.value is None:
             return None, lambda c: replace(self, value=None, kind=None)
         else:
@@ -225,8 +285,15 @@ class Choice(Generic[A, B], AST):
 
 @dataclass(frozen=True)
 class Many(Generic[A], AST):
+    """A finite sequence of values within the AST."""
     value: Tuple[A, ...]
     def bimap(self, r: Bimap[A, B]=Bimap.identity()) -> Tuple[List[B], Callable[[List[B]], Many[A]]]:
+        """Map each element to a list and provide an inverse.
+
+        The inverse accepts a list of transformed elements. If the provided
+        list is shorter than the original, only the prefix is used. If longer,
+        the extra values are inverted using the last element's inverse.
+        """
         ret = [v.bimap(r) if isinstance(v, AST) else r(v) for v in self.value]
         def inv(bs: List[B]) -> Many[A]:
             if len(bs) <= len(ret):
@@ -244,6 +311,12 @@ class ThenKind(Enum):
     
 @dataclass(eq=True, frozen=True)
 class Then(Generic[A, B], AST):
+    """Pair two values with a composition kind (both, left, or right).
+
+    The ``kind`` determines how values are combined.
+    ``LEFT``/``RIGHT`` indicate single-sided results; ``BOTH`` flattens both
+    sides.
+    """
     kind: ThenKind
     left: A
     right: B
@@ -259,7 +332,15 @@ class Then(Generic[A, B], AST):
         else:
             return 1
 
-    def bimap(self, r: Bimap[A|B, Any]=Bimap.identity()) -> Tuple[Any | Tuple[Any, ...], Callable[[Any | Tuple[Any, ...]], Then[A, B]]]:
+    def bimap(self, r: Bimap[A | B, Any] = Bimap.identity()) -> Tuple[Any | Tuple[Any, ...], Callable[[Any | Tuple[Any, ...]], Then[A, B]]]:
+        """Transform the left/right values according to ``kind``.
+
+        - ``LEFT``: map and return the left value; inverse sets only ``left``.
+        - ``RIGHT``: map and return the right value; inverse sets only ``right``.
+        - ``BOTH``: return a flattened tuple of mapped left values followed by
+          mapped right values. The inverse expects a tuple whose length equals
+          ``left.arity() + right.arity()`` and reconstructs the structure.
+        """
         def need_wrap(x: Any) -> bool:
             return not (isinstance(x, Then) and x.kind == ThenKind.BOTH)
         match self.kind:
@@ -296,9 +377,23 @@ E = TypeVar("E", bound=DataclassInstance)
 Collector = Type[E] | Callable[..., E]
 @dataclass(frozen=True)
 class Collect(Generic[A, E], AST): 
+    """Apply a collector to a value to build a dataclass-like instance.
+
+    When the inner value is a ``Then`` and the forward result is a tuple, any
+    ``Marked`` elements become named arguments to the collector; the remainder
+    are passed positionally. The inverse breaks the produced instance back into
+    a structure compatible with the original ``Then``.
+    """
     collector: Collector
     value: A
     def bimap(self, r: Bimap[A, B]=Bimap.identity()) -> Tuple[B | E, Callable[[B | E], Collect[A, E]]]:
+        """Map the inner value, collect it, and supply a matching inverse.
+
+        For multi-field tuples derived from ``Then``, the inverse rebuilds the
+        appropriate mix of ``Marked`` and positional elements using the
+        collector's dataclass fields. For single-argument collectors, the first
+        field of the dataclass is used.
+        """
 
         def inv_one_positional(e: E) -> B:
             if not is_dataclass(e):
@@ -341,6 +436,7 @@ class Collect(Generic[A, E], AST):
 #########################################################################################################################
 @dataclass(frozen=True)
 class Token(AST):
+    """Leaf node representing a single token with type and text."""
     token_type: Enum
     text: str
     def __str__(self) -> str:
@@ -374,6 +470,7 @@ class TokenSpec:
         return type_match and value_match
 
 
+#: Union-like type describing the shape of AST parse results across nodes.
 ParseResult = Union[
     Then['ParseResult[T]', 'ParseResult[T]'], 
     Marked['ParseResult[T]'],