external-cannbot-ops-pypto-api-explore

pypto-api-explore

Use Explore subagent to explore the PyPTO API and provide API mapping, constraint checking, and Tiling requirement analysis for operator development.

Input

Accept input in any form and extract the operator computation logic:

• Natural language description (e.g. "compute softmax")
• Mathematical formula (e.g. softmax(x) = exp(x)/sum(exp(x)))
• Code snippet (PyTorch or pseudocode)
• Existing spec document content

If the information is insufficient, ask the user for additional details.

Output

• Output artifact：API_REPORT.md
• Format: markdown, using the templates/api_report.md template
• Output path: the current directory or a user-specified location
• front matter: Fill in at least schema_version、op_name, and it is recommended to fill in supported_dtypes、axes_list、shape_constraints、tiling_required、feasibility(where axes_list should be a YAML list, for example ['N'] or ['N','M']）

---

Core workflow

Note: You must use the Explore subagent to explore APIs and constraints to ensure the comprehensiveness and accuracy of the search.

Step 1: Input parsing

Accept input in any form and extract:

• Operator name (if any)
• Mathematical formula / computation logic
• Input/output specifications (shape, dtype)
• Other constraints

Step 2: Formula decomposition

Decompose the computation logic into a sequence of atomic operations:

Operation type:

• elementwise: add, sub, mul, div, exp, log, sin, cos...
• reduction: sum, max, min, mean, var...
• matmul: matmul, bmm, linear...
• shape: reshape, transpose, concat...
• index: gather, scatter, index_select...
• activation: relu, sigmoid, softmax...

Step 3: Parallel exploration

Combine API exploration, reference implementation search, and constraint exploration intothree parallel Explore subagents, each responsible for a different top-level directory. You mustinitiate all Agent calls in the same messageto ensure parallel execution.

Explore subagent 1: pypto/docs/zh/ — API documentation and constraints

Search scope：pypto/docs/zh/ directory

Task：

1. Check pypto/docs/zh/api/operation/index.md to confirm API existence
2. Read the specific API documentation pypto/docs/zh/api/operation/pypto-*.md to obtain parameters and constraints
3. Not found → mark as unsupported and try a substitute approach
4. Extract entry constraints (pypto/docs/zh/api/others/pypto-from_torch.md）：dtype、contiguous、format
5. Extract API constraints: dtype support, shape ranges, broadcasting rules, special value restrictions
6. Extract Tiling constraints (pypto/docs/zh/api/config/pypto-set_vec_tile_shapes.md、pypto/docs/zh/api/config/pypto-set_cube_tile_shapes.md）
7. Consult pypto/docs/zh/api/datatype/ to obtain DataType and TileOpFormat enum information

Return content: API mapping table, three-layer constraint check results, Tiling requirements, evidence index path list

Explore subagent 2: models/ — Production-grade reference implementation

Search scope：models/ directory,excluding models/experimental/(experimental implementation, not fully verified, reference prohibited)

Task：

1. Search for production-grade model operator implementations related to the current operator
2. Extract reusable implementation patterns: API call methods, Tiling configuration, Loop structure, data type handling
3. Do not stop as soon as you find one; traverse all candidates and collectAll matching reference implementations

Return content: the path, similarity, confidence, and reusable points of each matching implementation; if there is no match, mark "No match"

Explore subagent 3: examples/ — Official example implementation

Search scope：examples/ directory

Task：

1. In pypto/examples/02_intermediate/operators/ search for complete operator reference implementations
2. In pypto/examples/03_advanced/patterns/ search for advanced composition patterns
3. Extract reusable implementation patterns: API call methods, Tiling configuration, Loop structure, boundary handling
4. Do not stop once you find one; traverse all candidates and collectall matching reference implementations

Return content: the path, similarity, confidence, and reusable points of each matching implementation; if there is no match, mark "No match"

---

Summary of parallel exploration results

After waiting for all three Explore subagents to return:

1. Merge API mapping and constraint check results (from subagent 1)
2. Merge reference implementation search results (from subagents 2 and 3), compare and evaluate to select thebest match
3. If multiple high-quality references exist, list the Top 3 in the report, and explain the recommended first choice and the reason

Step 4: Generate report

Based on the templates/api_report.md template, generate API_REPORT.md.

---

Search directory

Assign to the corresponding Explore subagent by first-level directory:

Subagent	Directory	Search content	Priority
1: pypto/docs/zh/	pypto/docs/zh/api/operation/index.md	API list, confirm existence	Entry
	pypto/docs/zh/api/operation/pypto-*.md	Specific API documentation	Primary
	pypto/docs/zh/api/others/pypto-from_torch.md	Entry constraints	Must check
	pypto/docs/zh/api/config/pypto-set_vec_tile_shapes.md	Vector Tiling	Conditional
	pypto/docs/zh/api/config/pypto-set_cube_tile_shapes.md	Cube Tiling	Conditional
	pypto/docs/zh/api/datatype/	DataType, TileOpFormat enums	Reference
2: models/	models/(excluding experimental)	Production-grade model operator implementations	First choice
3: examples/	pypto/examples/02_intermediate/operators/	Complete operator reference implementations	Second choice
	pypto/examples/03_advanced/patterns/	Advanced composition patterns	Reference

---

Embedded knowledge

Operation → API mapping quick reference

Operation category	Common operations	PyPTO API
Element-wise	add, sub, mul, div, neg	pypto.{op}
Math	exp, log, sin, cos, sqrt, rsqrt	pypto.{op}
Comparison	eq, ne, lt, le, gt, ge	pypto.{op}
Bitwise	bitwise_and, bitwise_or, bitwise_xor	pypto.bitwise_{op}
Reduction	sum, amax, amin, prod, var	pypto.{op}
Matrix	matmul	pypto.matmul
Shape	reshape, transpose, concat, view	pypto.{op}
Indexing	gather, scatter, index_select	pypto.{op}
Activation	relu, sigmoid, softmax	pypto.{op}
Construction	zeros, ones, full, arange	pypto.{op}
Type conversion	cast	pypto.cast

Common Substitutes (no direct API)：

• mean → sum/count
• gelu → combine mul + sigmoid + mul(x * sigmoid(1.702 * x)), consistent with activation.py
• sigmoid → supports only FP32; in other dtype scenarios, first cast to FP32 and then call

Operator type determination

公式分析
    │
    ├── 含 matmul/@ → Cube 类型 → set_cube_tile_shapes
    │
    ├── 仅逐元素/归约 → Vector 类型 → set_vec_tile_shapes
    │
    └── matmul + 逐元素 → 混合类型 → 两者都需要

Hard constraint quick reference

Constraint type	Rule	Source
dtype entry	FP16/BF16/FP32/FP64/INT8/INT16/INT32/INT64/UINT8/UINT16/UINT32/UINT64/BOOL	from_torch documentation
shape entry	Non-empty Tensor	from_torch documentation
contiguous	Must be contiguous	from_torch documentation
TileShape	Each dimension > 0, at most 4 dimensions	set_vec_tile_shapes documentation
Cube TileShape	32-byte alignment; buffer space must satisfy K axis × 2 ≤ L1 capacity	set_cube_tile_shapes documentation
shape size	≤ INT32_MAX	Documentation for each API
sigmoid dtype	Only DT_FP32 is supported	pypto.sigmoid API documentation
Dynamic shape compatibility	**Computation APIs such as matmul / reduction types require a concrete shape at compile time and do not accept tensors containing DYNAMIC dimensions (error:has invalid shape value: -1). If the operator has dynamic axes and uses such APIs, it must be flagged in the risk assessment, and it must be explained that a "loop tile slicing" strategy is required (see execution-constraints.md §5)

---

Checklist

Verify the gating conditions of API_REPORT.md:

1. The file exists
2. The following 6 sections exist and their content is not empty:
   • ## 1. 概述
   • ## 3. API 映射
   • ## 6. 参考实现(may be marked "no match" but must not be missing)
   • ## 7. 风险评估
   • ## 8. 证据索引
   • ## 9. 结论

---

Error handling

Scenario	Handling
Input cannot be parsed	Guide the user to provide a formula or code
API does not exist	Mark as unsupported, explain in the risks
Constraints not satisfied	Mark ✗, provide an alternative in the risks
No matching reference implementation	Mark "no match" in the "Reference Implementation" section; do not block the process