repo-maintenance
Maintain the LlamaIndex monorepo safely: inspect package layout and pyproject metadata, use llama-dev package/test commands, run targeted package tests, and triage docs/examples automation without performing release, publish, or credentialed sync actions.
- License 许可
- MIT
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- repo-maintenance
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Maintain the LlamaIndex monorepo safely: inspect package layout and pyproject metadata, use llama-dev package/test commands, run targeted package tests, and triage docs/examples automation without performing release, publish, or credentialed sync actions.
- disable-model-invocation
- true
02 资源文件 5
- 参考文档references/llama-dev-cli.md2.9 KB
- 参考文档references/monorepo-layout.md2.8 KB
- 参考文档references/source-script-inventory.md2.2 KB
- 参考文档references/troubleshooting.md2.8 KB
- 脚本scripts/list_llama_packages.py4.8 KB
03 SKILL.md 正文
LlamaIndex Repo Maintenance
Use this sub-skill when an agent is working inside the LlamaIndex monorepo and needs to reason about package boundaries, test one package or a small changed set, inspect package metadata, or decide which maintenance scripts are safe to adapt.
Safe Maintenance Defaults
- Treat the monorepo as many package projects, not one install target; package-local commands usually run from the package directory.
- Prefer read-only inspection before mutation: list packages, read
pyproject.toml, inspect tests, then choose the narrowest command. - Use
uvpackage-local workflows for ordinary development and tests; avoid installing every integration unless the task explicitly requires broad validation. - Keep release, publish, version bump, and credentialed docs sync commands out of normal runnable guidance unless a human explicitly asks for those workflows and confirms credentials/scope.
- When using
llama-dev, run it from the repo root or pass--repo-root; package arguments are repository-relative package paths such asllama-index-coreorllama-index-integrations/llms/llama-index-llms-openai.
Start Here
-
Identify the package path and distribution name with the bundled read-only helper:
python skills/llama-index/sub-skills/repo-maintenance/scripts/list_llama_packages.py --repo-root . --filter openai -
Inspect the relevant package metadata:
python skills/llama-index/sub-skills/repo-maintenance/scripts/list_llama_packages.py --repo-root . --package-path llama-index-core -
Run package-local tests from the package directory when you only touched one package:
cd llama-index-integrations/llms/llama-index-llms-openai uv run -- pytest -
Use
llama-dev testwhen you need changed-package/dependant selection or a consistent package test harness:llama-dev test llama-index-integrations/llms/llama-index-llms-openai --workers 1 -
If a command would bump versions, publish packages, sync external docs, or require secrets, stop and ask for explicit human approval.
Common Workflows
Run Tests for One Integration
- Locate the integration under
llama-index-integrations/<category>/<distribution-name>/. - Read its
pyproject.tomland confirm its own dependency group instead of syncing unrelated integrations. - From that package directory, run
uv run -- pytest; this letsuvcreate/use the package-local environment. - If local changes affect another package dependency, either install that changed package into the package environment deliberately or use
llama-dev test <package-path>so the CLI can install local changed packages for test execution.
Add or Update a Package
- Ensure the directory name,
project.name, import namespace, and optionaltool.llamahub.import_pathall point to the intended integration. - Confirm
requires-python, runtime dependencies, and test/dev dependencies match package needs without inheriting unrelated integrations. - Use the helper script to compare neighboring packages in the same integration category.
- Add or update package-local tests and run only the changed package first; broaden to dependant packages only after the narrow run passes.
Use llama-dev Safely
- Safe inspection:
llama-dev pkg info <package-path>,llama-dev pkg info --all, and JSON output when machine parsing helps. - Safe targeted execution:
llama-dev pkg exec --cmd "uv sync" <package-path>only when dependency installation is expected. - Safe tests:
llama-dev test <package-path> --workers 1orllama-dev test --base-ref main --workers <n>for changed-package selection. - Reference-only:
llama-dev pkg bumpmutates package versions;llama-dev release ...supports release automation. Do not run these as routine maintenance.
References
Bundled Script
scripts/list_llama_packages.pyscans a supplied repository root forpyproject.tomlfiles withproject.name, prints paths and package metadata, and can emit JSON. It is read-only and safe to run with--help.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).