Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
84ce0cd
Organize knowledge by inference task and evidence purpose
david6666666 Nov 19, 2026
809598d
Pin generated knowledge records to the published source layout
david6666666 Nov 19, 2026
5a8c98c
Clarify optional task navigation and historical revision behavior
david6666666 Nov 19, 2026
e1e301d
Point the knowledge authoring procedure to the unified records directory
david6666666 Nov 19, 2026
e23afdf
Unify knowledge resources under skill_library and assemble catalog vi…
david6666666 Nov 19, 2026
72866ca
Align the public read contract diagrams with the compiled inputs
david6666666 Nov 19, 2026
4739b6d
Pin the completed library tree for Git-backed evaluation planning
david6666666 Nov 19, 2026
e10721e
Preserve the recorded catalog and historical snapshot helper interfaces
david6666666 Nov 19, 2026
de6758c
Merge the shared Find ranker into the single-root knowledge layout
david6666666 Nov 19, 2026
f49cd4f
Refresh combined source pins, verify protected projections and docume…
david6666666 Nov 19, 2026
977fda9
Promote seven inference goals into independently loadable task skills
david6666666 Nov 19, 2026
04e81c5
Load the primary inference procedure before searching supporting evid…
david6666666 Nov 19, 2026
bda7dee
Isolate exact knowledge reads and ignore OS metadata beside records
david6666666 Nov 19, 2026
d83fa45
Merge main serving relocation while retaining the single knowledge root
david6666666 Nov 19, 2026
c27a359
Verify the Apps reader resolves once without a global owner scan
david6666666 Nov 19, 2026
20d9b6a
Keep the canonical library overview outside projection input checks
david6666666 Nov 19, 2026
58c022f
Validate the task-oriented knowledge layout on a single B300 H3 Image…
david6666666 Nov 19, 2026
ebe5e68
Record the completed native campaign and baseline selection
david6666666 Nov 19, 2026
217d0b3
Fold paired skill metadata into the canonical SKILL.md sources
david6666666 Nov 19, 2026
a96d451
Read single-file skills and verify search against clean pre-layout main
david6666666 Nov 19, 2026
f6502a6
Keep full procedures inside the original retrieval context budgets
david6666666 Nov 19, 2026
306d7b4
Verify saved task captures can reconstruct each pinned procedure
david6666666 Nov 19, 2026
024241b
Check raw and delivered skill bytes separately in the installed wheel
david6666666 Nov 19, 2026
d03bbb7
Verify projected bytes and real omission fixtures across delivery cli…
david6666666 Nov 19, 2026
cb2421a
Merge main and retain procedure provenance in the campaign workflow
david6666666 Nov 20, 2026
30e69b5
Bound Find cards and deliver verifiable skill procedures on material …
david6666666 Nov 20, 2026
7c19974
Clarify the snapshot and read mode behind Find size hints
david6666666 Nov 20, 2026
1f74e34
Verify Find size estimates across edits to a live checkout
david6666666 Nov 20, 2026
c3f8d7f
Correct the contributor guide for the single knowledge-library root
david6666666 Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
/evidence/_template/** text eol=lf

# Retain this upstream license's original CRLF Git blob bytes.
/src/inferrsi/knowledge/data/skill_library/frameworks/torch-npu/torch-npu/references/licenses/op-plugin-LICENSE.txt -text
/src/inferrsi/knowledge/data/skill_library/systems/frameworks/torch-npu/torch-npu/references/licenses/op-plugin-LICENSE.txt -text

# Generated third-party bundles, with source references and notices beside them.
/plugins/inferrsi-dsh/vendor/ssh2.cjs linguist-generated=true linguist-vendored=true
Expand Down
8 changes: 5 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Parameterized or manual acceptance runs are issue-scoped; they are not the defau

## RSI contract

- **Resolve acceptance criteria** — preserve user-supplied criteria; when absent, use [performance-ceiling-analysis](src/inferrsi/knowledge/data/skill_library/methods/performance-ceiling-analysis/references/acceptance-criteria.md) to derive evidence-backed campaign targets. Retain partial requirements and derive only missing fields; unresolved evidence stays explicit.
- **Resolve acceptance criteria** — preserve user-supplied criteria; when absent, use [performance-ceiling-analysis](src/inferrsi/knowledge/data/skill_library/playbooks/measurement/performance-ceiling-analysis/references/acceptance-criteria.md) to derive evidence-backed campaign targets. Retain partial requirements and derive only missing fields; unresolved evidence stays explicit.
- **Freeze gates before search** — checklist and `validator/` locked in `plan/` before Phase 3 candidate experiments ([validation levels](docs/contributing.md#validation-levels)).
- **One plane per campaign step** — change only the declared SIAS plane per step: `harness` | `model` | `infra` (under `src/inferrsi/`).
- **Emit RunSpec snapshots** — record repo × revision × backend × device × model × scenario (`contracts/runspec.py`, campaign `plan/`).
Expand All @@ -83,7 +83,7 @@ Parameterized or manual acceptance runs are issue-scoped; they are not the defau

- Cite **acceptance issues + pinned SHAs** in downstream text; do not invent gain or quality bars.
- **Public wording only after `PASS`** — follow [evidence and claim rules](docs/contributing.md#evidence-and-claims); until then, label unverified or `INCONCLUSIVE`.
- Use [cite-check-downstream-pr](src/inferrsi/knowledge/data/skill_library/workflows/cite-check-downstream-pr/SKILL.md) and [competitor-scan](src/inferrsi/knowledge/data/skill_library/workflows/competitor-scan/SKILL.md) as **operators**, not campaign scripts (no pins in skill bodies).
- Use [cite-check-downstream-pr](src/inferrsi/knowledge/data/skill_library/workflows/governance/cite-check-downstream-pr/SKILL.md) and [competitor-scan](src/inferrsi/knowledge/data/skill_library/workflows/research/competitor-scan/SKILL.md) as **operators**, not campaign scripts (no pins in skill bodies).

## Evidence and clearing the bar

Expand All @@ -104,7 +104,9 @@ Agents and human reviewers **clear** work only with artifacts—not vibes. Green

## Skills

Portable operator guidance and candidate procedures live in [src/inferrsi/knowledge/data/skill_library/](src/inferrsi/knowledge/data/skill_library/README.md), with hardware-specific guidance under `hardware/<backend-or-host>/`, framework/repository guidance under its owner, and generic `methods/` and `workflows/`. The library owns complete procedures, metadata, references and cases. Keep library content in English; supporting documents stay in owner-local resource directories. The [knowledge-base contract](docs/knowledge-base.md) and two matrices define ownership and coverage. Keep **AGENTS.md** short; follow skill bodies for procedures—skills must remain free of campaign SHAs.
For an inference task, first select one of the [seven required primary skills by deliverable](plugins/inferrsi/skills/inferrsi/SKILL.md#load-the-primary-inference-task). Run `inferrsi skills enter <primary-id>` and read the returned instructions before the first evidence search. For an accuracy regression, use `inferrsi skills enter task-accuracy`. If the required skill cannot load, report the blocker. Frozen evaluations follow their assigned entry and knowledge condition.

Portable operator guidance and candidate procedures live in the [skill library](src/inferrsi/knowledge/data/skill_library/README.md). Keep complete English instructions, metadata, references and cases with the owner. The [knowledge-base contract](docs/knowledge-base.md) and two matrices define ownership and coverage. Keep campaign SHAs out of skill bodies.

## Optimization requests

Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ real-model gains remain unmeasured. [Flow, limits and reproduction →](docs/har

| You want to… | Start at |
| --- | --- |
| Choose a starting point for a new model, performance, debug, accuracy, upgrade or engine task | Choose the [primary skill for the requested outcome](docs/knowledge-layout.md#seven-deliverables) and read its procedure with `inferrsi skills enter <task-id>` before the first evidence search. Follow its decision points using the actual run and acceptance criteria. |
| Modify InferRSI itself | [Contributor guide](docs/contributing.md) and [agent collaboration](docs/agent-collaboration.md), under an accepted Issue scope |
| Use the Workbench to run experiments | [Quickstart](docs/quickstart.md): prepared target environment, benchmark/quality contracts, authorized experiment, recorded evidence |
| Complete an optimization benchmark in the current Agent | [Iterative task sessions](docs/optimization-benchmarks.md), with frozen rounds, independent feedback and final retesting |
Expand Down Expand Up @@ -298,12 +299,12 @@ performance evidence or an autonomous model-backed optimizer.
| [Qwen Ascend](docs/qwen-image-2.1-turbo-ascend.md) | NPU results, rejected rounds and verification scope |
| [h3-metal lessons](docs/h3-metal-apple-silicon-lessons.md) | MiniMax-H3 on Apple silicon: measurement pitfalls, gains, rejected directions and search-loop lessons |
| [Apple silicon playbook](docs/apple-silicon-playbook.md) | Measured, engine-agnostic lessons for Metal/MLX engines: unified memory, Metal execution and benchmarking a shared Mac |
| [Knowledge base](src/inferrsi/knowledge/data/knowledge_packs/README.md) | Three learning tiers: contribution, dependency impact and peer techniques |
| [Skill catalog](src/inferrsi/knowledge/data/repo_packs/inferrsi/knowledge/README.md) | Searchable records linking categorized skills to full packaged procedures and resources |
| [Knowledge base](src/inferrsi/knowledge/data/skill_library/records/README.md) | Three learning tiers: contribution, dependency impact and peer techniques |
| [Skill catalog](src/inferrsi/knowledge/data/skill_library/README.md) | Searchable records linking categorized skills to full packaged procedures and resources |
| [Source audit](docs/reviews/source-audit-ac70272.md) | 34 review points with proposed remedies, qualifications and validation criteria |
| [Daily learning prompt](docs/daily-learning-prompt.md) | 06:00 Asia/Shanghai L2C + performance workflow and prerequisites |
| [Complete skill library](src/inferrsi/knowledge/data/skill_library/README.md) | Registered skills and English engine/workflow documents, organized by owner |
| [vLLM-Omni experience records](src/inferrsi/knowledge/data/repo_packs/vllm_omni/knowledge/README.md) | Backend-scoped tuning methods, sources, and applicability |
| [Complete skill library](src/inferrsi/knowledge/data/skill_library/README.md) | Task entrypoint, system knowledge, playbooks, workflows and casebooks |
| [vLLM-Omni experience records](src/inferrsi/knowledge/data/skill_library/records/README.md) | Backend-scoped tuning methods, sources, and applicability |
| [Contributor guide](docs/contributing.md) | Development workflow, evidence contracts, and CI |
| [Engine delivery template](docs/template/README.md) | Copyable engine scaffold, branding, evidence and schema-v1 catalog recipe |

Expand Down
6 changes: 3 additions & 3 deletions docs/apple-silicon-playbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ acceptance result.

| Existing source-derived guidance | What it leaves open | Measured observation here |
| --- | --- | --- |
| [h3.c runtime audit](../src/inferrsi/knowledge/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/SKILL.md), [64 GiB worked preparation](../src/inferrsi/knowledge/data/skill_library/repositories/h3-c/audit-h3-runtime-residency/references/minimax-h3-apple.md) | Target execution and peak memory unverified; tensor counters are not physical footprint | Process peaks for three configurations, the component that sets the memory floor, and cold-load cost ([Unified memory](#unified-memory)) |
| [MLX lazy evaluation and stream lifetimes](../src/inferrsi/knowledge/data/skill_library/frameworks/mlx/lazy-evaluation-stream-lifetimes/SKILL.md) | Submission versus completion stated from source; no device timing | CPU encoding and GPU wait measured separately; a large encode cost that did not move wall time ([Metal execution](#metal-execution)) |
| [vLLM Metal cache lifecycle](../src/inferrsi/knowledge/data/skill_library/repositories/vllm-metal/sub-skills/cache-lifecycle/SKILL.md) | One physical unified pool stated from source; memory pressure not measured | Resident weights evicting other weights from the page cache, with the cold-start cost |
| [h3.c runtime audit](../src/inferrsi/knowledge/data/skill_library/systems/engines/h3-c/audit-h3-runtime-residency/SKILL.md), [64 GiB worked preparation](../src/inferrsi/knowledge/data/skill_library/systems/engines/h3-c/audit-h3-runtime-residency/references/minimax-h3-apple.md) | Target execution and peak memory unverified; tensor counters are not physical footprint | Process peaks for three configurations, the component that sets the memory floor, and cold-load cost ([Unified memory](#unified-memory)) |
| [MLX lazy evaluation and stream lifetimes](../src/inferrsi/knowledge/data/skill_library/systems/frameworks/mlx/lazy-evaluation-stream-lifetimes/SKILL.md) | Submission versus completion stated from source; no device timing | CPU encoding and GPU wait measured separately; a large encode cost that did not move wall time ([Metal execution](#metal-execution)) |
| [vLLM Metal cache lifecycle](../src/inferrsi/knowledge/data/skill_library/systems/engines/vllm-metal/sub-skills/cache-lifecycle/SKILL.md) | One physical unified pool stated from source; memory pressure not measured | Resident weights evicting other weights from the page cache, with the cold-start cost |
| [Quickstart A/B experiments](quickstart.md) | Generic; no Apple-specific interference sources | Interference seen on a shared Mac and how each was detected ([Benchmarking a shared Mac](#benchmarking-a-shared-mac)) |

## Unified memory
Expand Down
66 changes: 28 additions & 38 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ Reviewed paper comparisons, readsets and cases live under their owning skill's
Paper knowledge does not supply repository-only schema fields such as a Git SHA,
so it remains linked Markdown rather than a parallel registry or fabricated
`repo_packs` record. The [knowledge-base contract](knowledge-base.md) defines
local sidecar ownership, typed source examples, shared checkout references and
skill-local metadata ownership, typed source examples, shared checkout references and
legacy package compatibility. Normalized reads and bounded Collect
([knowledge-operations.md](knowledge-operations.md)) and the authorized local
store ([knowledge-store.md](knowledge-store.md)) are implemented Python
Expand Down Expand Up @@ -281,10 +281,8 @@ src/inferrsi/
image.py OpenAI-style image payload and PNG response protocol
infra/
artifacts.py Hashing and evidence writes
data/
repo_packs/ Contribution descriptors and versioned tuning knowledge
knowledge_packs/ Dependency and peer knowledge, preserving existing tiers
skill_library/ Complete categorized English skills and resources
knowledge/data/skill_library/ Registered skills, engineering records, configuration and compiled inputs
harness/data/repo_packs/ Execution target descriptors
examples/ Current Qwen runner, image validator and v4 adapter
tests/fixtures/legacy/ Frozen historical validation dependencies for regressions
```
Expand Down Expand Up @@ -437,26 +435,17 @@ operations or the control CLI to Linux.
Package data is the canonical source for noneditable installations:

```text
inferrsi/knowledge/data/repo_packs/REPO/knowledge/
README.md Organization and navigation only
BACKEND/COMPONENT/ENTRY.json One canonical reusable experience
inferrsi/knowledge/data/repo_packs/inferrsi/knowledge/
Generated from data/skill_library/, never hand-edited
inferrsi/knowledge/data/knowledge_packs/
README.md Three-tier source navigation
dependency/REPO/BACKEND/COMPONENT/ENTRY.json
peer/REPO/BACKEND/COMPONENT/ENTRY.json
inferrsi/knowledge/data/skill_library/
tasks/ systems/ playbooks/ workflows/ casebooks/ Registered owners
records/<stable-id>.json One authored engineering finding
config/ Aliases and research profiles
_compiled/ Build-time YAML headers and Git fingerprints
skill-index.json Stable ID, physical path and backend
```

JSON owns applicability, claims, recommendations, validation and limitations;
`knowledge search`, `knowledge show` and human-readable `context` use that same
record. Per-entry duplicate READMEs are removed. The loader validates that
repository, backend, component and stable ID agree with the path.
The learning tier is an independent acquisition policy: contribution packs
retain their paths, while external dependency/peer packs add source-owned
candidates. Tier/source/backend/scenario filters intersect before ranking and
limits; no downstream repository inherits external knowledge implicitly.
Knowledge-only sources do not extend the executable repository registry.
record. The tier identifies each source relationship. The reader validates the repository, backend and component encoded in the stable filename.

A backend filter includes that backend and repository-local `common` methods;
scenario filters select exact workloads or component wildcards. Model, SKU,
Expand All @@ -469,25 +458,26 @@ guidance or reported measurements independently from a source's merge status.
Imported skills are source material, not executable tool authority. CPU tests
do not upgrade imported knowledge to a validated claim.

The optional `skills` CLI defaults to the installed `data/skill_library/` and
its `skill-index.json` registry of stable skill IDs. Hardware-specific content
lives under `hardware/ascend`, `hardware/cuda` or `hardware/host`; other skills
are grouped by framework, repository, method or workflow. Full procedures,
sidecars, references and cases ship with the package. Engine entry skills live
under `repositories/<engine>/`, the collection router under
`workflows/inference-engine-research/`. All library content is in English.
Supporting documents are owner-local; only `README.md` and `skill-index.json`
remain at the library root. An explicit
`--root` can still select a custom flat skills tree or a registry-based library. The CLI uses PyYAML from the `skills` extra,
lists metadata, reads a named body or resolves a named resource for an external
file reader. It never executes, installs or promotes skills. Core knowledge
commands read catalog JSON and packaged documents without the optional parser;
the two matrices retain their authority.
The bundled skill CLI uses `data/skill_library/` and its `skill-index.json` registry.
The main agent selects one primary procedure from `tasks/` and reads it with
`skills enter <task-id>` before searching for supporting evidence. The base
runtime loads the complete packaged primary procedure and its host header without PyYAML.
The structured InferRSI annotation stays in the pinned source file.

Supporting procedures live in `systems/`, `playbooks/`, `workflows/` and
`casebooks/`. Engine owners live under `systems/engines/<engine>/`. Each owner
packages its full English procedure, embedded metadata, references and cases. The library
also owns authored findings in `records/`, search configuration in `config/`
and generated build inputs in `_compiled/`. An explicit `--root` selects a
custom flat or registry-based library. Readers that parse skill frontmatter use
PyYAML from the `skills` extra. Core knowledge commands read catalog views and
packaged documents with the base interpreter. The two matrices retain their
authority. [Directory and search diagrams](knowledge-layout.md)

Run evidence remains in the caller-selected run directory; frozen campaign
plans/results/patches/validators remain under `evidence/`.

See the [knowledge guide](../src/inferrsi/knowledge/data/knowledge_packs/README.md)
See the [knowledge guide](../src/inferrsi/knowledge/data/skill_library/records/README.md)
for all entries, retrieval rules and the maintenance workflow.

The earlier [component design](assets/component-architecture-en.svg) and
Expand All @@ -503,8 +493,8 @@ automatic promotion into the knowledge catalog or RunSpec. The original diagram
is preserved; the [source audit](reviews/source-audit-ac70272.md) tracks cleanup
portability and other implementation gaps.

The migrated skills have [generated catalog records](../src/inferrsi/knowledge/data/repo_packs/inferrsi/knowledge/README.md)
in `data/repo_packs/inferrsi/knowledge/`, with backend-scoped IDs and
The migrated skills have [generated catalog records](../src/inferrsi/knowledge/data/skill_library/README.md)
assembled at read time, with backend-scoped IDs and
`skill_documents.original` pointing to the complete packaged procedures.
Normalized reads retain the library's dependency resources. The library is the
single content owner.
Binary file added docs/assets/knowledge-layout/01-task-layers.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/knowledge-layout/04-before-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/assets/modular-directory-map-en.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading