Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,8 +224,9 @@ python -m venv .venv
source .venv/bin/activate
python -m pip install .

# Explore tuning knowledge, then export context for your coding agent.
inferrsi knowledge search 'Qwen-Image-2.1' --repo-type vllm_omni --backend ascend
# Find relevant tuning knowledge and follow the printed open command.
inferrsi find 'Qwen-Image-2.1 Ascend memory bottleneck'
# Export a context bundle for an agent that needs one.
inferrsi context --repo-type vllm_omni --backend cuda --output context.md
```

Expand Down
9 changes: 7 additions & 2 deletions docs/knowledge-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,9 @@ inferrsi collect 'Ascend OOM' --kind case --limit 3 --material --skill-root src/
inferrsi read calibrate-serving-simulation --skill-root src/inferrsi/knowledge/data/skill_library
```

The `--skill-root` selections require the `skills` extra (`python -m pip install
'.[skills]'`); package-only collect/read work with the base install.
Reading checkout skill bodies requires the `skills` extra (`python -m pip install
'.[skills]'`). Package-only operations and checkout case reads work with the base
install.

Every item has an owning `authority` (`package`, `checkout` or `store`) and a qualified
`ref` of the form `<authority>:<id>`. Public IDs are unchanged and may be used
Expand Down Expand Up @@ -202,6 +203,10 @@ Selected resource reads require the exact returned revision. A changed checkout
or installation rejects an old revision; it never substitutes new bytes.
This reader does not itself retain history or claim standalone exports.

`read --material --omit-resources` returns the full entrypoint, provenance,
applicability and revision. Remove `--omit-resources` to list resource paths and
digests. Both forms use the same full-bundle revision.

- Local skills include their complete owner folder (except incidental
`__pycache__`, `*.pyc` and `.DS_Store`) and declared cross-skill references,
whether declared in the sidecar or in legacy frontmatter. Other links remain navigation in the required full checkout.
Expand Down
87 changes: 87 additions & 0 deletions docs/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ Effect classes used below:
| Search packaged records | CLI `knowledge search` / `knowledge show`; catalog API | Read-only | Installed package catalog with the existing tier/repo/backend/scenario filters and IDs; these package-only filters exclude skills and cases from every other authority |
| Prepare model-aware engine research | CLI `knowledge research`; Python `research_knowledge` | Read-only | Independent model/framework/task/modality/mechanism queries over the same package catalog; source-grounded known profiles, deduplicated matches and explicit target annotations; no engine/hardware qualification |
| Discover/read packaged or custom skills | CLI `skills list` / `show` / `resource` / `reference` | Read-only | Metadata-first listing; `show` loads one named instruction body; `resource`/`reference` resolve paths for your file reader without loading or executing them |
| Rank relevant cases, skills and records | CLI `find` | Read-only | Search the registered library and package records in one list. Follow the emitted command to read a hit and its revision |
| Collect normalized knowledge | CLI `collect`; Python `KnowledgeReader.collect` | Read-only | Explicit sources, authority-qualified identities, exact revisions, bounded output and explicit omissions |
| Read exact material/resources | CLI `read` / `resource`; Python `KnowledgeReader.read` / `KnowledgeReader.resource` | Read-only | Returns the requested revision or an explicit unavailable/stale error; never substitutes newer bytes |
| Export legacy cited material | CLI `context` | Read-only | Cited package export for manual use with a coding agent; not a conversation store and not a full Collect equivalent |
Expand Down Expand Up @@ -169,6 +170,92 @@ upstream instructions.

## Normalized knowledge (Python)

### Find — `find` / `inferrsi.knowledge.knowledge_find.find`

One ranked list for one question, across packaged skills, imported records and
checkout cases. Run a result's `open` command to read its complete entry and
receive a revision. Use that revision with the same ID and source selection
for a pinned `read` or `resource` call.

Three properties distinguish it from the Collect selection path below. Cases are
ranked beside skills instead of being reachable only after their owner is
chosen, because a recorded rejected direction is the material retrieval can
supply that re-reading current source cannot. Nothing is filtered on the query:
requiring every token to appear returns nothing for a question phrased in
sentences, so ranking degrades and `--limit` truncates. Scoring reads corpus
files directly rather than Bundles, whose metadata lists the whole packaged
library as one dependency closure. The reader validates the returned material
without pinning a revision during search.

Scoring is `idf x field weight x sqrt(occurrences)` summed over query terms,
with titles, summaries, tags and case findings weighted above bodies. Bodies
longer than the corpus median get less weight so a broad manual needs more
specific matches to outrank a short case. Separators
do not bind: `kv_cache`, `kv-cache` and `KV cache` all tokenise to the same two
terms, so a query in plain words reaches the punctuated spellings this corpus
also uses. Latin terms still match on boundaries, so `oom` does not match inside
`headroom`. CJK is cut into overlapping bigrams, because single characters make
idf treat grammatical particles as rare terms. Ties break towards the stronger
recorded state rather than alphabetical identity. This is deterministic lexical
matching, not a learned ranking, and a hit never asserts that an entry applies.

Chinese query terms expand through `data/query_aliases.json` before ranking.
The packaged library is English by policy while its readers work in Chinese, and
the corpus holds too few Chinese characters for a Chinese query to score on its
subject. Expansion is one-way and query-side: 显存 reaches `device memory`, not
the reverse, and an entry is only listed when that English form actually occurs
in the corpus. A query whose terms were expanded reports them under `expanded`,
so a wrong expansion is visible in the result rather than only in the ranking.

Three limits are inherent to lexical ranking and are recorded here rather than
worked around. A query made only of terms common to this corpus ("operator",
"test", "graph", "speedup") has little to rank on and may bury the intended
entry. A query that shares no words with its target does not reach it: asking
for "moving attention state to host memory" misses an entry that says `kv`,
`offload` and `tier` throughout, because nothing matches. Name the specific
symptom, operator or flag where you can, and when a plausible query returns
nothing useful, search the corpus directly rather than assuming it holds
nothing — `find` ranks words, not meanings.

The third is that `find` always answers. It cannot tell a question the corpus
can help with from one the caller can already settle from the facts in front of
them, and it returns its best matches either way. On the labelled set, a
majority of queries were ones an engineer should decide without searching at
all, and `find` returned results for every one of them; their scores overlap
the answerable range too broadly for a cutoff to separate the two without
suppressing real answers. Deciding whether the question needs the corpus
remains the caller's judgement, and a returned list is not evidence that it
did.

- **Inputs:** the query, `--limit`, `--kinds` (subset of `case,skill,record`), `--skill-root` to rank an explicit root, `--explain` for per-term contributions, `--json`.
- **Scope:** installed package records and the packaged (or selected) skill library, including its cases. Packaged-skill projections are excluded from the record side so one owner is not ranked under two identities.
- **Output.** Items identify their `id`, `authority` (`package` or `checkout`),
`kind`, recorded `state`, `score`, `title` and corpus-relative `path`.
Where recorded, items carry source, summary, applicability, limitations and
local verification status. Case findings are ordered by query overlap,
with `findings_total` and `findings_withheld` describing the available preview.
Each finding carries its outcome, reason, revisit condition and any assessed
scope and bounds. `bounds_source` identifies whether bounds apply to the
finding or the whole entry. The envelope reports `corpus_size`, `matched`,
`no_match`, any `expanded` terms and retrieval limitations.
- **Reading a hit.** Plain output prints a POSIX `open` command or a labelled
PowerShell command on Windows. JSON exposes the rendered command as `ref`,
full subprocess arguments as `open_argv` and InferRSI CLI arguments as
`read_args`. The arguments include the source-qualified ID and a skill root
where needed. They use `read --material --omit-resources` to return the
entrypoint, provenance and revision with a smaller response. Remove
`--omit-resources` to list the bundle's resources. Hits that fail the reader's
material check carry `unreadable` with the reason.
- **Base installation fallback.** When a Skill hit requires PyYAML, run a new
search of the packaged Skills with
`inferrsi collect --relevance "<same query>" --limit 1 --material --json`.
It may select a different Skill. Check that the returned Skill fits your
task, then fetch its `skill_documents.original` with
`inferrsi resource <ref> <path> --revision <revision> --output <file>` using
the `ref` and `revision` from the new result.
- **Side effects:** none. No revision is pinned; use `read`/`resource` when a capture or evidence record needs exact bytes.
- **Example:** `inferrsi find "NPU OOM after caching per-step masks" --limit 3` returns the casebook entry recording that attempt first. A vaguer phrasing ranks the procedural skills above it, which is the first limit below rather than a defect.

### Collect — `collect` / `KnowledgeReader.collect`

Optional `--relevance <CUE>` ranks generated packaged skills after the existing
Expand Down
21 changes: 19 additions & 2 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,24 @@ Its common catalog ID and the separate MLX-LM procedure remain unchanged.

## Discover knowledge and skills

Read-only discovery and export — the [operation guide](operations.md) maps every
entry point, effect class and boundary:
Start from the problem. `find` ranks packaged skills, imported records and
casebook entries together and reports what each one's evidence covers, so a
direction already tried and dropped surfaces beside the procedure for trying it:

```bash
inferrsi find 'mask caching ran out of device memory'
inferrsi find '算子测过了但整图质量没过' --limit 3
```

Run the `open` command on a relevant hit to read the entry and its source,
applicability, limitations and revision. Add `--kinds case` to focus the search
on recorded observations and failed directions.

Nothing is filtered out for an unmatched word, so a question phrased in
sentences still returns something; read the reported state, `scope` and bounds
before acting on a hit. The remaining commands are exact-lookup and export —
the [operation guide](operations.md) maps every entry point, effect class and
boundary:

```bash
inferrsi knowledge search 'Qwen-Image-2.1' --repo-type vllm_omni --backend ascend
Expand Down Expand Up @@ -113,6 +129,7 @@ plan/run: all doctor flags, plus
--repetitions --min-improvement-pct --max-minutes
--workload-id --model --model-revision --output-dir --dry-run
status/report: --run-id --output-dir
find: QUERY --limit --kinds --skill-root --explain --json
knowledge search: QUERY --tier --repo-type --backend --scenario --limit --json
knowledge show: ID
context: QUERY --tier --repo-type --backend --scenario --limit --output
Expand Down
42 changes: 33 additions & 9 deletions plugins/inferrsi/skills/inferrsi/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,15 +121,39 @@ Use the CLI's help for exact flags. Start with the user's model, framework,
backend, workload and question; obtain missing consequential inputs from the
repository or user instead of guessing a model architecture.

- `knowledge research <model>` unions independent research dimensions.
- `knowledge search <query> --json` searches packaged records with hard filters.
- `collect --relevance "<task>" --limit 3 --json` discovers a bounded packaged
selection. Adjust the limit to the task. Packaged skill projections have kind
`knowledge`; `--kind skill` excludes them and is for explicitly selected
checkout/store skill sources.
- `read <ref> --revision <revision> --material` loads a selected exact revision.
Use the returned resource keys with `resource --help` when further material
is needed.
Use `find "<problem or symptom>"` to rank skills, imported records and casebook
entries. Add `--kinds case` when you specifically need a past observation.
Open a promising hit using its displayed `open` command or the JSON
`open_argv` argument list.

When a Skill hit is unreadable because PyYAML is missing, run a new search of
the packaged Skills with `collect --relevance "<same query>" --limit 1 --material --json`.
It may select a different Skill. Check that the returned Skill fits the task,
then use that result's `ref`, `revision` and `skill_documents.original` to
fetch the body with `resource <ref> <path> --revision <revision> --output <file>`.
For other `cannot open` results, check the reason before choosing another hit.

`read` returns the material, its source, applicability, limitations and
revision. To cite or reopen exact evidence, add `--revision <revision>` to the
same read arguments. Remove `--omit-resources` to list bundle resource keys.
Use those keys with `resource --help` for further material.

A ranked hit is not a substitute for reading the repository. `find` supplies
what re-reading current source cannot: directions already tried, why they were
dropped, and the cohort each observation belongs to. Keep searching the tree
directly for anything about present-day code.

`find` ranks words, not meanings. A query sharing no vocabulary with its target
will not reach it, so when a plausible query returns nothing useful, try the
terms the corpus itself would use, then grep the library directly. Do not report
that nothing is recorded on the strength of one query. Each result states how
far its evidence reaches: `scope` and `bounds` name the cohort an observation
belongs to, and their absence means not assessed, never "holds anywhere".

`find` also always answers. It cannot tell that a question is already settled by
the measurements and source in front of you, so a returned list is not evidence
that searching was the right move. When the recorded facts decide the question,
decide it and say so rather than looking for support.

Use qualified identities and revisions returned by the runtime. Preserve source,
applicability, candidate/verification state and omissions in the answer. Package
Expand Down
26 changes: 14 additions & 12 deletions plugins/inferrsi/skills/inferrsi/scripts/inferrsi.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,13 @@
from pathlib import Path


def main() -> int:
def main(*, launcher_path: Path | None = None) -> int:
if sys.version_info < (3, 10):
print("InferRSI requires Python 3.10 or newer; select a compatible interpreter.",
file=sys.stderr)
return 2
root = Path(__file__).resolve().parents[3]
script = Path(__file__).resolve()
root = script.parents[3]
runtime = root / "runtime"
if os.name == "nt" and not str(runtime).startswith("\\\\?\\"):
runtime = Path("\\\\?\\UNC\\" + str(runtime)[2:]
Expand Down Expand Up @@ -53,16 +54,17 @@ def main() -> int:
"optional_skills_dependency": has_yaml,
}, indent=2))
return 0
needs_yaml = args[:1] == ["skills"] or any(
arg == "--skill-root" or arg.startswith("--skill-root=") for arg in args
)
if needs_yaml and not has_yaml and not any(arg in ("--help", "-h") for arg in args):
print(
"This operation needs the optional skills dependency: install PyYAML in the "
"selected interpreter, or use packaged knowledge/collect/read without --skill-root.",
file=sys.stderr,
)
return 2
# No PyYAML precheck here. The runtime raises its own install hint, exit 2,
# from the one call that parses skill frontmatter; guessing from argument
# names refused operations that never parse any -- reading a case under
# --skill-root, which is exactly the reference `find` hands back.

# Commands the CLI prints for a reader to run next must start the way this
# process was started. A plugin host has no `inferrsi` on PATH, so a
# printed `inferrsi read ...` fails where this launcher would succeed. The
# argv is passed as JSON so the CLI can quote it for the host's shell.
launcher = launcher_path.resolve() if launcher_path is not None else script
os.environ["INFERRSI_LAUNCHER"] = json.dumps([sys.executable, "-X", "utf8", str(launcher)])

from inferrsi.apps.cli import main as cli_main

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -159,10 +159,10 @@ def main() -> int:
entry = cache_runtime(manifest_bytes, launcher, content)
# No wrapper subprocess: the host still owns the foreground CLI process.
try:
runpy.run_path(str(entry), run_name="__main__")
runtime_main = runpy.run_path(str(entry))["main"]
return runtime_main(launcher_path=Path(__file__))
except SystemExit as exit_status:
return exit_status.code if isinstance(exit_status.code, int) else 1
return 0
except (OSError, ValueError, KeyError, zipfile.BadZipFile) as error:
print(f"InferRSI plugin bundle is incomplete: {error}. "
"See the package-integrity and runtime-cache repair steps in the bundled README.",
Expand Down
Loading
Loading