comments and docs

Zhuoming Chen · Zhuoming Chen · commit 29174fee15c5 · 2026-05-23T22:10:28.000-04:00
diff --git a/docs/api/vortex_torch.abs.context_base.rst b/docs/api/vortex_torch.abs.context_base.rst
@@ -3,7 +3,6 @@ vortex\_torch.abs.context\_base
 
 .. automodule:: vortex_torch.abs.context_base
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.abs.op.rst b/docs/api/vortex_torch.abs.op.rst
@@ -3,7 +3,6 @@ vortex\_torch.abs.op
 
 .. automodule:: vortex_torch.abs.op
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.context.rst b/docs/api/vortex_torch.cache.context.rst
@@ -3,7 +3,6 @@ vortex\_torch.cache.context
 
 .. automodule:: vortex_torch.cache.context
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.elementwise.rst b/docs/api/vortex_torch.cache.elementwise.rst
@@ -3,7 +3,6 @@ vortex\_torch.cache.elementwise
 
 .. automodule:: vortex_torch.cache.elementwise
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.elementwise_binary.rst b/docs/api/vortex_torch.cache.elementwise_binary.rst
@@ -3,7 +3,6 @@ vortex\_torch.cache.elementwise\_binary
 
 .. automodule:: vortex_torch.cache.elementwise_binary
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.fill.rst b/docs/api/vortex_torch.cache.fill.rst
@@ -3,7 +3,6 @@ vortex\_torch.cache.fill
 
 .. automodule:: vortex_torch.cache.fill
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.mask.rst b/docs/api/vortex_torch.cache.mask.rst
@@ -0,0 +1,12 @@
+﻿vortex\_torch.cache.mask
+========================
+
+.. automodule:: vortex_torch.cache.mask
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      MaskSlice
+   
diff --git a/docs/api/vortex_torch.cache.matmul.rst b/docs/api/vortex_torch.cache.matmul.rst
@@ -3,7 +3,6 @@ vortex\_torch.cache.matmul
 
 .. automodule:: vortex_torch.cache.matmul
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.reduce.rst b/docs/api/vortex_torch.cache.reduce.rst
@@ -3,7 +3,6 @@ vortex\_torch.cache.reduce
 
 .. automodule:: vortex_torch.cache.reduce
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.cache.reduce_interleave.rst b/docs/api/vortex_torch.cache.reduce_interleave.rst
@@ -0,0 +1,16 @@
+﻿vortex\_torch.cache.reduce\_interleave
+======================================
+
+.. automodule:: vortex_torch.cache.reduce_interleave
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      L2NormInterleave
+      MaxInterleave
+      MeanInterleave
+      MinInterleave
+      ReduceInterleave
+   
diff --git a/docs/api/vortex_torch.cache.reshape.rst b/docs/api/vortex_torch.cache.reshape.rst
@@ -0,0 +1,12 @@
+﻿vortex\_torch.cache.reshape
+===========================
+
+.. automodule:: vortex_torch.cache.reshape
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      Reshape
+   
diff --git a/docs/api/vortex_torch.cache.rst b/docs/api/vortex_torch.cache.rst
@@ -14,5 +14,8 @@ vortex\_torch.cache
    elementwise
    elementwise_binary
    fill
+   mask
    matmul
    reduce
+   reduce_interleave
+   reshape
diff --git a/docs/api/vortex_torch.flow.algorithms.rst b/docs/api/vortex_torch.flow.algorithms.rst
@@ -1,21 +1,86 @@
 vortex\_torch.flow.algorithms
 =============================
 
-.. automodule:: vortex_torch.flow.algorithms
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   
-   .. rubric:: Classes
-
-   .. autosummary::
-
-      BlockSparseAttention
-      GQABlockSparseAttention
-      GQAQuestSparseAttention
-      LServeSparseAttention
-      LServeCentroidSparseAttention
-      MaskedQuestSparseAttention
-      CenteredBlockSparseAttention
-      RunningAvgBlockSparse
-      VEnergyGatedCentroid
+.. currentmodule:: vortex_torch.flow.algorithms
+
+Ready-made sparse-attention flows. Each entry shows the routing **math**
+(rendered from the class docstring) followed by the **code** that implements
+it — the ``__init__`` op set and the ``forward_cache`` / ``forward_indexer`` /
+``create_cache`` methods.
+
+.. note::
+   ``GeMM(x, y) = y xᵀ``; reductions keep dims; ``q`` is ``[B, H_q, D]`` and a
+   cache tensor is ``[S, r, D]`` in the indexer (page-packed) / ``[B, r, D]`` in
+   the cache (batch-major). Register key is in ``@register(...)``.
+
+block_sparse_attention
+----------------------
+
+.. autoclass:: BlockSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: BlockSparseAttention
+
+gqa_block_sparse_attention
+--------------------------
+
+.. autoclass:: GQABlockSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: GQABlockSparseAttention
+
+gqa_quest_sparse_attention
+--------------------------
+
+.. autoclass:: GQAQuestSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: GQAQuestSparseAttention
+
+lserve_sparse_attention
+-----------------------
+
+.. autoclass:: LServeSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: LServeSparseAttention
+
+lserve_centroid_sparse_attention
+--------------------------------
+
+.. autoclass:: LServeCentroidSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: LServeCentroidSparseAttention
+
+masked_quest_sparse_attention
+-----------------------------
+
+.. autoclass:: MaskedQuestSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: MaskedQuestSparseAttention
+
+centered_block_sparse_attention
+-------------------------------
+
+.. autoclass:: CenteredBlockSparseAttention
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: CenteredBlockSparseAttention
+
+running_avg_block_sparse
+------------------------
+
+.. autoclass:: RunningAvgBlockSparse
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: RunningAvgBlockSparse
+
+venergy_gated_centroid
+----------------------
+
+.. autoclass:: VEnergyGatedCentroid
+
+.. literalinclude:: ../../vortex_torch/flow/algorithms.py
+   :pyobject: VEnergyGatedCentroid
diff --git a/docs/api/vortex_torch.flow.flow.rst b/docs/api/vortex_torch.flow.flow.rst
@@ -3,7 +3,6 @@ vortex\_torch.flow.flow
 
 .. automodule:: vortex_torch.flow.flow
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.flow.loader.rst b/docs/api/vortex_torch.flow.loader.rst
@@ -3,7 +3,6 @@ vortex\_torch.flow.loader
 
 .. automodule:: vortex_torch.flow.loader
    :members:
-   :undoc-members:
    :show-inheritance:
 
    .. rubric:: Functions
diff --git a/docs/api/vortex_torch.flow.registry.rst b/docs/api/vortex_torch.flow.registry.rst
@@ -3,7 +3,6 @@ vortex\_torch.flow.registry
 
 .. automodule:: vortex_torch.flow.registry
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Functions
diff --git a/docs/api/vortex_torch.indexer.context.rst b/docs/api/vortex_torch.indexer.context.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.context
 
 .. automodule:: vortex_torch.indexer.context
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Functions
diff --git a/docs/api/vortex_torch.indexer.elementwise.rst b/docs/api/vortex_torch.indexer.elementwise.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.elementwise
 
 .. automodule:: vortex_torch.indexer.elementwise
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.elementwise_binary.rst b/docs/api/vortex_torch.indexer.elementwise_binary.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.elementwise\_binary
 
 .. automodule:: vortex_torch.indexer.elementwise_binary
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.kron.rst b/docs/api/vortex_torch.indexer.kron.rst
@@ -0,0 +1,12 @@
+﻿vortex\_torch.indexer.kron
+==========================
+
+.. automodule:: vortex_torch.indexer.kron
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      Kron
+   
diff --git a/docs/api/vortex_torch.indexer.mask.rst b/docs/api/vortex_torch.indexer.mask.rst
@@ -0,0 +1,12 @@
+﻿vortex\_torch.indexer.mask
+==========================
+
+.. automodule:: vortex_torch.indexer.mask
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      MaskSlice
+   
diff --git a/docs/api/vortex_torch.indexer.matmul.rst b/docs/api/vortex_torch.indexer.matmul.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.matmul
 
 .. automodule:: vortex_torch.indexer.matmul
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.output_func.rst b/docs/api/vortex_torch.indexer.output_func.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.output\_func
 
 .. automodule:: vortex_torch.indexer.output_func
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.reduce.rst b/docs/api/vortex_torch.indexer.reduce.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.reduce
 
 .. automodule:: vortex_torch.indexer.reduce
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.reshape.rst b/docs/api/vortex_torch.indexer.reshape.rst
@@ -0,0 +1,12 @@
+﻿vortex\_torch.indexer.reshape
+=============================
+
+.. automodule:: vortex_torch.indexer.reshape
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      Reshape
+   
diff --git a/docs/api/vortex_torch.indexer.rst b/docs/api/vortex_torch.indexer.rst
@@ -13,10 +13,14 @@ vortex\_torch.indexer
    context
    elementwise
    elementwise_binary
+   kron
+   mask
    matmul
    output_func
    reduce
+   reshape
    save_load
    scan
+   select
    transpose
    utils_sglang
diff --git a/docs/api/vortex_torch.indexer.save_load.rst b/docs/api/vortex_torch.indexer.save_load.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.save\_load
 
 .. automodule:: vortex_torch.indexer.save_load
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.scan.rst b/docs/api/vortex_torch.indexer.scan.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.scan
 
 .. automodule:: vortex_torch.indexer.scan
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.select.rst b/docs/api/vortex_torch.indexer.select.rst
@@ -0,0 +1,12 @@
+﻿vortex\_torch.indexer.select
+============================
+
+.. automodule:: vortex_torch.indexer.select
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      TopK
+   
diff --git a/docs/api/vortex_torch.indexer.transpose.rst b/docs/api/vortex_torch.indexer.transpose.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.transpose
 
 .. automodule:: vortex_torch.indexer.transpose
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Classes
diff --git a/docs/api/vortex_torch.indexer.utils_sglang.rst b/docs/api/vortex_torch.indexer.utils_sglang.rst
@@ -3,7 +3,6 @@ vortex\_torch.indexer.utils\_sglang
 
 .. automodule:: vortex_torch.indexer.utils_sglang
    :members:
-   :undoc-members:
    :show-inheritance:
    
    .. rubric:: Functions
diff --git a/docs/api/vortex_torch.utils.rst b/docs/api/vortex_torch.utils.rst
