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: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,11 @@ Portable operator guidance and candidate procedures live in [src/inferrsi/knowle

## Optimization requests

For Ascend tasks, follow the [external knowledge preflight](docs/external-channels.md#ascend-task-preflight).
If cannbot is unavailable or not enabled, proactively provide the installation
recommendation and guide link, then verify discovery, search and a pinned card
read after setup. Respect explicit local-only or knowledge-off conditions.

Ordinary project optimization stays in the current Agent conversation. Follow
the [shared optimization workflow](docs/optimization-workflow-unification.md):
prepare explicit workload, quality/measurement scripts, metric, gates, declared
Expand Down
84 changes: 79 additions & 5 deletions docs/external-channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ no_match 135 entries searched; rephrase, or search the corpus directly with r

external (not locally verified; scores are not comparable across channels)
cannbot-knowledge [not_enabled] cannbot knowledge is not enabled for this project
fix: inferrsi cannbot enable --checkout <path> --python <interpreter>
fix: For Ascend tasks, install cannbot-knowledge if needed (checkout, Python environment and index), then enable it: inferrsi cannbot enable --checkout <path> --python <interpreter> --backend ascend --platform <platform>. Installation and verification: https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md#setting-one-up . For local-only search, use inferrsi find <query> --no-external.
```

`no_match` there is honest: the packaged corpus really holds nothing for that
Expand All @@ -27,6 +27,41 @@ per-API cards**. The external cannbot-knowledge corpus holds **10,550 cards,
2,993 of them Ascend C API cards**. Ignoring that gap is what the channel exists
to prevent.

## Ascend task preflight

When the user declares an Ascend task, check external knowledge availability
before researching optimization directions. Confirm the actual platform (`a2`,
`a3`, etc.); do not infer it from query text. If the task explicitly requires
local-only or knowledge-off operation, honor that condition and skip this probe.

1. From the target Git project, run `inferrsi cannbot describe` and inspect its
JSON `state`. Exit code 0 alone does not establish that the channel is ready.
2. For `not_enabled`, proactively recommend cannbot-knowledge for Ascend API
and operator references and provide the [installation guide](#setting-one-up)
([web link](https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md#setting-one-up)).
Explain that the missing project grant does not prove the source is absent:
an existing installation only needs project enablement. Offer
`inferrsi find <query> --no-external` for local-only work.
3. For a missing checkout or reader (`unreachable`), use the same guide to
restore the installation or enable its new location. For `index_stale`,
rebuild the approved source's index using the returned guidance. Other
failure states require their stated repair; do not report them as zero hits.
4. Apply existing installation/access authorization; if absent, obtain it before
installing or enabling a source. Then complete all three
[verification steps](#verify-the-installation) below before reporting that
external knowledge is usable. If setup is deferred, continue with the
permitted local knowledge and state that external coverage was unavailable.

`find --backend ascend` also emits the installation recommendation, enable
command and complete guide URL in text and JSON when the channel is not enabled,
whether or not local hits exist. Explicit `--no-external` and nonmatching
backends such as `cuda` omit this channel and its suggestion.

This integration uses a local checkout and reader process. Registering an MCP
server in an Agent host is not a prerequisite, and an installed host MCP does
not create an InferRSI project grant. InferRSI's `cannbot serve` proxy is not
implemented; the steps below configure the current CLI integration.

## Why it is not downloaded for you

cannbot-knowledge has its own CANN Open Software License Agreement v2.0.
Expand All @@ -42,9 +77,13 @@ a wheel, or `evidence/`.
## Setting one up

You supply a checkout, an interpreter, and the backend it serves. The `git`
executable must be available for read-time revision checks:
executable must be available for read-time revision checks. Use Python 3.10+
and an interpreter with PyYAML. The following POSIX shell example uses `a2`;
replace it with the confirmed target platform. If the checkout, environment and
index already exist, reuse them and proceed to `enable` in the target Git project.

```bash
mkdir -p ~/src ~/venvs
git clone https://gitcode.com/cann/cannbot-knowledge.git ~/src/cannbot-knowledge
python3 -m venv ~/venvs/cannbot && ~/venvs/cannbot/bin/pip install pyyaml

Expand Down Expand Up @@ -72,15 +111,50 @@ already could have fixed.
| `--backend` | Default task backend; explicit `find --backend` takes precedence. Cannbot serves Ascend only. |
| `--platform` | Default upstream platform (`a2`, `a3`, `950`, `310p`, `910`, …) |

Check it:
### Verify the installation

Run these checks from the same target Git project that was enabled. Choose a
platform supported by the task; the example below uses `a2`.

**1. Check discovery and configuration.**

```bash
$ inferrsi cannbot describe
{"state": "ok", "revision": "92dc2607...", "cards": 10550,
"index": {"schema": "cannbot-knowledge-index.v1", "version": 3,
"content_fingerprint": "75ef3269..."}}
"content_fingerprint": "75ef3269..."}, "platforms": ["a2"]}
```

Require `state: "ok"`, a source revision and the intended platform in

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

describe reports the grant's default platforms, not the platforms the checkout can answer. A project with default a3 can still run the explicit --platform a2 search below, so requiring a2 in platforms could send users through unnecessary re-enablement. Could we check that list only when relying on the default, and verify an explicit target in the search and pinned read steps?

`platforms`. A successful `enable` or process exit alone is insufficient.

**2. Check integrated search.**

```bash
inferrsi find "CeilDivision" --backend ascend --platform a2 --external-limit 1 --json
```

Inspect the `cannbot-knowledge` entry in `external[]`: require `state: "ok"`,
its revision and at least one result with an `open` command. Local `no_match`
does not make this check fail. If the source answers with zero hits, discovery
worked but search-to-read verification is still incomplete; use a term known to
exist on the selected platform. A timeout or stale index needs repair first.

**3. Open the returned card with its identity.**

Run the exact `open` command returned by step 2. Its shape is:

```bash
inferrsi cannbot read <locator> --sha256 <card_sha256> --revision <revision>
```

Require `state: "ok"`, non-empty `text`, and a `card_sha256` and `revision`
matching the search result. If another page is needed, append `--page 2` to the
same command, preserving both identity flags. A drift rejection requires a new
search; do not drop the flags to make verification succeed. This verifies the
delivery path, not the card's technical claims or campaign evidence eligibility.
Do not copy the returned body into shared logs or evidence.

Revoke it with `inferrsi cannbot disable`. The grant lives at
`~/.config/inferrsi/cannbot-projects/<sha256(checkout)>.json` and is bound to the
project's `.git` identity, so copying it to another clone does not carry the
Expand Down Expand Up @@ -140,7 +214,7 @@ owned resources; Python cannot forcibly stop arbitrary in-process threads.
| --- | --- |
| `ascend` | `cannbot-knowledge`, plus any platform-neutral channel |
| `cuda`, `mlx`, `rocm`, `cpu` | none — an Ascend source must not answer a CUDA task |
| not declared, no grant | none; each channel reports `backend_unknown` |
| not declared, no grant | none; cannbot reports `not_enabled` with setup guidance |

The backend is never inferred from the query text. A query containing "asc" is
not evidence that the task is an Ascend task, and a wrong inference would be
Expand Down
16 changes: 11 additions & 5 deletions docs/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,18 +275,24 @@ no_match 135 entries searched; rephrase, or search the corpus directly with r

external (not locally verified; scores are not comparable across channels)
cannbot-knowledge [not_enabled] cannbot knowledge is not enabled for this project
fix: inferrsi cannbot enable --checkout <path> --python <interpreter>
fix: For Ascend tasks, install cannbot-knowledge if needed (checkout, Python environment and index), then enable it: inferrsi cannbot enable --checkout <path> --python <interpreter> --backend ascend --platform <platform>. Installation and verification: https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md#setting-one-up . For local-only search, use inferrsi find <query> --no-external.
```

Enabling a channel is a deliberate, per-checkout action by a person; see
[external knowledge channels](external-channels.md). This repository does not
For Ascend tasks, follow the [availability preflight](external-channels.md#ascend-task-preflight)
and proactively present the [installation guide](external-channels.md#setting-one-up)
when the source is missing or not enabled. After setup, verify discovery,
integrated search and a revision/digest-bound read using the
[verification steps](external-channels.md#verify-the-installation). Enabling a
channel is a deliberate, per-checkout action. This repository does not
clone, download or bundle the corpus automatically. Review the upstream terms
for the intended use before granting access; source permissions remain separate
from this integration mechanism.

- **Inputs:** `--backend <name>` declares the task backend; **without it and
without an approved grant, no channel is searched** and each one reports
`backend_unknown`. `--no-external` skips all channels for CI and offline runs.
without an approved grant, no channel is searched**; cannbot reports
`not_enabled` with setup guidance. `backend_unknown` applies to a channel
without a task declaration and without a more specific availability hint.
`--no-external` skips all channels and setup suggestions for CI and offline runs.
`--external-limit <N>` overrides the per-channel cap (`cannbot-knowledge` 100,
`mindie-agent` 5). `--external-timeout <S>` bounds discovery and search
together (8s default); `--platform` overrides the upstream platform in the grant.
Expand Down
5 changes: 5 additions & 0 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,11 @@ Its common catalog ID and the separate MLX-LM procedure remain unchanged.

## Discover knowledge and skills

For Ascend tasks, first follow the [external knowledge preflight](external-channels.md#ascend-task-preflight).
If cannbot is not installed or enabled for the project, the CLI recommends setup
and links the [installation and verification guide](external-channels.md#setting-one-up).
External knowledge is optional; an explicit `--no-external` keeps the search local.

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:
Expand Down
28 changes: 24 additions & 4 deletions src/inferrsi/apps/cannbot/project.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,17 @@
# refused rather than forwarded: the upstream CLI is fail-closed about platform
# and a typo there would silently change which cards answer.
PLATFORMS = ("a2", "a3", "950", "310p", "910", "kirin_x90", "kirin_9030", "agnostic")
SETUP_GUIDE = (
"https://github.com/InferMatrixLab/InferRSI/blob/main/docs/external-channels.md"
"#setting-one-up"
)
_SETUP_FIX = (
"For Ascend tasks, install cannbot-knowledge if needed (checkout, Python "
"environment and index), then enable it: inferrsi cannbot enable "
"--checkout <path> --python <interpreter> --backend ascend --platform <platform>. "
f"Installation and verification: {SETUP_GUIDE} . "
"For local-only search, use inferrsi find <query> --no-external."
)


class ChannelFailure(ValueError):
Expand All @@ -44,7 +55,7 @@ def project_root() -> Path:
return folder
raise ChannelFailure(
"Open a Git project to use project-scoped cannbot knowledge",
state="not_enabled", fix="Open a Git project, then enable cannbot knowledge",
state="not_enabled", fix="Open a Git project first. " + _SETUP_FIX,
)


Expand Down Expand Up @@ -105,10 +116,11 @@ def load_grant(root: Path | None = None) -> dict:
except FileNotFoundError:
raise ChannelFailure(
"cannbot knowledge is not enabled for this project", state="not_enabled",
fix="inferrsi cannbot enable --checkout <path> --python <interpreter>",
fix=_SETUP_FIX,
) from None
except OSError:
raise ChannelFailure("The cannbot project grant could not be read", state="not_enabled") \
raise ChannelFailure("The cannbot project grant could not be read", state="not_enabled",
fix=_SETUP_FIX) \
from None
if (grant.get("schema") != _SCHEMA or grant.get("project_root") != str(root)
or grant.get("checkout_identity") != checkout
Expand All @@ -126,6 +138,13 @@ def load_grant(root: Path | None = None) -> dict:


def _run(grant: dict, action: str, arguments: dict, *, timeout: float, request=None) -> dict:
upstream = Path(grant["upstream"])
query_script = upstream / ".agents/skills/knowledge-query/scripts/knowledge_query.py"
if not (upstream / "knowledge").is_dir() or not query_script.is_file():
raise ChannelFailure(
"The approved cannbot checkout is missing or incomplete", state="unreachable",
fix=_SETUP_FIX,
)
environment = os.environ.copy()
for key in ("CANNBOT_MCP_TOKENS", "CANNBOT_KNOWLEDGE_PLATFORM"):
environment.pop(key, None)
Expand All @@ -147,7 +166,8 @@ def _run(grant: dict, action: str, arguments: dict, *, timeout: float, request=N
raise ChannelFailure("cannbot output exceeded 2 MiB", state="rejected") from None
except OSError:
raise ChannelFailure(
"The approved cannbot reader could not be started", state="unreachable"
"The approved cannbot reader could not be started", state="unreachable",
fix=_SETUP_FIX,
) from None
if len(result.stdout) > MAX_BYTES:
raise ChannelFailure("cannbot returned more than 2 MiB", state="rejected")
Expand Down
3 changes: 2 additions & 1 deletion src/inferrsi/apps/cli/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,8 @@ def _print_external(result: dict) -> None:
line += f"\t{_clip(entry['detail'], 100)}"
print(line)
if entry.get("fix"):
print(f" fix: {_clip(entry['fix'], 120)}")
# Keep setup URLs and recovery commands complete and copyable.
print(f" fix: {_tsv(entry['fix']).strip()}")
continue
revision = (entry.get("revision") or "")[:12] or "unpinned"
print(f" {entry['channel']} @ {revision}\t[{entry['score_scale']}]"
Expand Down
75 changes: 75 additions & 0 deletions tests/test_cannbot_boundaries.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
import json
import os
import shlex
import shutil
import subprocess
import sys
import time
Expand Down Expand Up @@ -285,6 +286,80 @@ def test_outside_git_project_reports_not_enabled(tmp_path, monkeypatch, backend)
assert payload["items"]
assert payload["external"][0]["state"] == "not_enabled"
assert "Git project" in payload["external"][0]["fix"]
assert project.SETUP_GUIDE in payload["external"][0]["fix"]


@pytest.mark.parametrize("query, no_match", [("tiling", False), ("qzxvjkqzxvjk", True)])
@pytest.mark.parametrize("json_output", [False, True])
def test_uninstalled_channel_suggests_setup_with_complete_link(
tmp_path, monkeypatch, query, no_match, json_output,
):
home, root = tmp_path / "home", tmp_path / "project"
home.mkdir()
(root / ".git").mkdir(parents=True)
monkeypatch.setenv("HOME", str(home))
monkeypatch.setenv("USERPROFILE", str(home))
monkeypatch.setenv("PYTHONPATH", str(REPO / "src"))
output_flags = ["--json"] if json_output else []
result = cli("find", query, "--backend", "ascend", *output_flags, cwd=root)
assert result.returncode == 0, result.stderr
if json_output:
payload = json.loads(result.stdout)
assert payload["no_match"] is no_match
entry = payload["external"][0]
assert entry["state"] == "not_enabled"
guidance = entry["fix"]
else:
assert ("no_match\t" in result.stdout) is no_match
assert "[not_enabled]" in result.stdout
guidance = result.stdout
assert "install cannbot-knowledge if needed" in guidance
assert project.SETUP_GUIDE in guidance
assert "--platform <platform>" in guidance
assert "--no-external" in guidance
# A suggestion must not silently install or authorize an external source.
assert not (home / ".config/inferrsi/cannbot-projects").exists()


@pytest.mark.parametrize("args", [("--backend", "cuda"), ("--backend", "ascend", "--no-external")])
def test_explicit_local_only_conditions_omit_setup_suggestion(upstream, args):
_, script, _ = upstream
project.disable()
script.write_text("raise RuntimeError('source must not be probed')\n")
result = cli("find", "tiling", *args, "--json")
assert result.returncode == 0, result.stderr
assert "external" not in json.loads(result.stdout)
assert project.SETUP_GUIDE not in result.stdout + result.stderr


def test_installed_but_disabled_source_suggests_setup_without_probing(upstream):
source, script, _ = upstream
project.disable()
marker = source / "unexpected-probe"
script.write_text("from pathlib import Path\nPath('unexpected-probe').touch()\n")
info = json.loads(cli("cannbot", "describe").stdout)
assert info["state"] == "not_enabled"
assert project.SETUP_GUIDE in info["fix"]
assert "if needed" in info["fix"]
assert not marker.exists()


@pytest.mark.parametrize("missing", ["checkout", "interpreter"])
def test_missing_approved_dependency_includes_installation_guidance(upstream, missing):
source, _, _ = upstream
if missing == "checkout":
shutil.rmtree(source)
else:
path = project._grant_path(project.project_root())
grant = project.load_grant()
grant["python"] = str(source / "missing-python")
path.write_text(json.dumps(grant))
result = cli("find", "tiling", "--backend", "ascend", "--json")
assert result.returncode == 0, result.stderr
payload = json.loads(result.stdout)
assert payload["items"]
assert payload["external"][0]["state"] == "unreachable"
assert project.SETUP_GUIDE in payload["external"][0]["fix"]


def test_platform_override_and_cuda_gate(upstream):
Expand Down
Loading