Skip to content
Merged
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
227 changes: 227 additions & 0 deletions docs/external-channels.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,227 @@
# External knowledge channels

`inferrsi find` can query knowledge that lives outside this repository. This page
explains what that is, why it is not installed with the package, and what to do
when you need it.

## A fresh install has no external channel

This is the **default and intended state**, not a missing installation step.

```bash
$ inferrsi find "CeilDivision 向上取整"
no_match 135 entries searched; rephrase, or search the corpus directly with rg

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>
```

`no_match` there is honest: the packaged corpus really holds nothing for that
query. The `not_enabled` line says an external source exists, was not approved
for this checkout, and how to approve it. Without that line a caller would
conclude the knowledge does not exist anywhere, which would be wrong.

On `main` `6c7e2379`, the packaged corpus holds **6 Ascend content cards and 0
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.

## Why it is not downloaded for you

cannbot-knowledge has its own CANN Open Software License Agreement v2.0.
InferRSI requires an explicitly approved local checkout and interpreter; it
does not clone, install or deploy that source automatically. Review the upstream
terms for your intended use before enabling it. Keeping the content outside the
package does not establish permission to use, transmit or redistribute it;
that organisational decision remains open in #476 Q1.

Nothing from an external checkout is ever copied into `src/inferrsi/knowledge/data/`,
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:

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

# Build the search index once; the server refuses to answer a stale index.
~/venvs/cannbot/bin/python \
~/src/cannbot-knowledge/.agents/skills/knowledge-query/scripts/knowledge_index.py build

inferrsi cannbot enable \
--checkout ~/src/cannbot-knowledge \
--python ~/venvs/cannbot/bin/python \
--backend ascend \
--platform a2
```

`enable` proves the checkout answers before writing anything: it checks for
`.git`, the `knowledge/` bundle, the `knowledge-query` scripts and an executable
interpreter, then runs a real `discover`. A checkout that cannot answer is
refused rather than recorded, so a later search never fails for a reason you
already could have fixed.

| Flag | Meaning |
| --- | --- |
| `--checkout` | Git checkout containing `knowledge/` |
| `--python` | Interpreter with `pyyaml`, able to run the checkout's scripts |
| `--backend` | Default task backend; explicit `find --backend` takes precedence. Cannbot serves Ascend only. |
| `--platform` | Default upstream platform (`a2`, `a3`, `950`, `310p`, `910`, …) |

Check it:

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

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
approval along.

## Using it

Once approved, the default path searches automatically because the grant declares
the backend:

```bash
inferrsi find "AscendC tiling 参数怎么算"
```

Or declare it per call:

```bash
inferrsi find "AscendC tiling 参数怎么算" --backend ascend --platform a2
inferrsi cannbot search "CeilDivision 向上取整" --platform a2 --limit 100
inferrsi cannbot read ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division
```

The generated `open` command includes `--revision <revision>` and
`--sha256 <card_sha256>`. Retain both with `--page 2` and later pages. A changed
checkout revision returns `version_mismatch`, even if the card bytes did not
change; changed bytes are rejected even if HEAD did not change. The worker
checks HEAD before and after reading, within the read timeout, and refuses an
observed revision change. This is a drift check on a mutable checkout, not an
atomic snapshot or a service for retrieving old versions. Every successful read
returns the observed checkout revision and digest of the full card bytes.
The upstream CLI uses `card_sha256` for a parsed metadata/body fingerprint;
this adapter preserves it as `source_card_sha256`. Before emitting a selected
hit, it verifies the source fingerprint using the approved checkout's parser
and computes `card_sha256` over those same raw bytes. It returns neither the
bytes nor private filesystem paths in search results.
A locator-only read returns the current card, revision and digest, without
promising continuity with an earlier search or page. A card digest does not validate its
cited resources or make it eligible as campaign evidence.

`find --platform` overrides the grant's upstream platform. If neither supplies
one, the channel reports `rejected` and gives the missing-platform guidance.
The default external result cap is 100 for cannbot; `--external-limit` overrides
it (1–200). These are returned hits, not the total number of upstream matches.

`--external-timeout` covers discovery and search together. Channels run
concurrently under that deadline. On timeout the caller cancels owned worker
processes and discards late results; subprocess teardown adds a short cleanup
interval. The cannbot adapter terminates its process group on POSIX; Windows
uses `taskkill /T /F` while the worker is alive. The new process-tree regression
runs on POSIX; Windows cleanup has not been qualified by that test. Generic
Python channel adapters must cooperate with the request deadline and register
owned resources; Python cannot forcibly stop arbitrary in-process threads.

### The backend gate

| Task backend | Channels searched |
| --- | --- |
| `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` |

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
silent.

### Reading the result

```json
"external": [{
"channel": "cannbot-knowledge", "state": "ok",
"revision": "92dc2607...", "elapsed_ms": 1310,
"score_scale": "knowledge-search.v5", "count": 3,
"items": [{"locator": "ops/ascendc/apis/.../ceil_division", "score": 14.0,
"status": "stable", "platforms": ["a2", "a3"],
"card_sha256": "<raw-byte-sha256>",
"source_card_sha256": "<upstream-card-fingerprint>",
"open": "inferrsi cannbot read ops/... --sha256 <card_sha256> --revision <revision>"}]
}]
```

Three things to keep in mind:

**External hits are never in `items`.** They were not ranked on this corpus and
are not locally verified. A caller that only reads `items` therefore cannot
mistake them for validated knowledge.

**Scores are not comparable across channels.** `score_scale` names the system
that produced the number. The packaged corpus ranks 143 skills; upstream ranks
10,550 cards; the same word has a different idf in each. Merging them would mean
inventing a normalisation, so the columns stay separate.

**A state other than `ok` is not "no results".** `not_enabled`, `unreachable`,
`index_stale`, `timeout`, `version_mismatch`, `rejected` and `backend_unknown`
each mean the channel did not answer. Read `detail` and `fix`.

## Coverage measured

Six Ascend queries against a checkout at `92dc2607`, default cap 100. Local
counts are identical with and without the channel; only the external column
changes.

| Query | Local only | Local + external |
| --- | --- | --- |
| AscendC tiling 参数怎么计算 | 14 | 114 |
| CeilDivision 向上取整 | 0 | 100 |
| matmul 分块 性能 | 10 | 110 |
| 算子 精度 调试 溢出 | 75 | 175 |
| ACLGraph 图模式 捕获 | 100 | 200 |
| KV cache 显存 布局 | 128 | 228 |
| **Total** | **327** | **927** |

## Evidence and licensing

An external result is **not locally verified**. Cite it as
`cannbot-knowledge @ <revision>` and say so. It does not participate in a `PASS`
verdict.

When a receipt is added (not in this release), it will hold the locator, the
card's `card_sha256` and the index revision — never card text, never
`frontmatter`, never a `local_path`. A digest proves which card was cited without
redistributing it.

Whether CANN OSL v2.0 permits even a local read-only copy is an open question for
the organisation; see #476 Q1. This page documents the mechanism, not a legal
conclusion.

## What is not implemented

| Capability | State |
| --- | --- |
| `cannbot enable / disable / describe / search / read` | implemented |
| `find` integration with gating, budgets, per-channel states | implemented |
| MindIE as a second channel | not yet; `apps/mindie/` has the reader, not the adapter |
| `cannbot serve` (stdio MCP proxying `discover` / `search` / `read_card`) | not yet |
| `campaign import-cannbot` (receipts into evidence) | not yet |
| Automatic clone, index build or deployment | deliberately absent |
| In-memory discovery cache | deferred; discovery and search share the current call’s budget |

## Related

- [Operation guide](operations.md) — every entry point, effect class, boundary
- [#476](https://github.com/InferMatrixLab/InferRSI/issues/476) — access design and licence boundary
- [#388](https://github.com/InferMatrixLab/InferRSI/issues/388) — external dependency governance
- [Knowledge base](knowledge-base.md) — the packaged corpus this sits beside
37 changes: 37 additions & 0 deletions docs/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,43 @@ question calls for prior evidence.
- **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.

#### External channels are not installed with this package

`find` also queries external read-only channels when the task backend is
declared. **A fresh install has none**, so a query that the packaged corpus
cannot answer returns `no_match` with no external results. That is the default
state, not a fault:

```text
no_match 135 entries searched; rephrase, or search the corpus directly with rg

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>
```

Enabling a channel is a deliberate, per-checkout action by a person; see
[external knowledge channels](external-channels.md). 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.
`--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.
- **Output:** `external[]` sits beside `items`, never inside it. Each entry
carries `state`, `revision`, `elapsed_ms`, `score_scale` and `count`. A state
other than `ok` (`not_enabled`, `unreachable`, `index_stale`, `timeout`,
`version_mismatch`, `rejected`, `backend_unknown`) means the channel did not
answer — it is **not** the same as answering with no hits.
- **Side effects:** none on this repository. A channel reads an external
checkout that the person approved; nothing is copied into the package, a
wheel or `evidence/`.
- **Determinism:** `--no-external` reproduces the pre-channel output exactly.

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

Optional `--relevance <CUE>` ranks generated packaged skills after the existing
Expand Down
107 changes: 107 additions & 0 deletions src/inferrsi/apps/cannbot/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
"""The cannbot-knowledge channel: an external read-only corpus beside ours."""

from __future__ import annotations

import time
from pathlib import Path

from ...knowledge.channels import (
ChannelHit,
ChannelRequest,
ChannelResult,
ChannelStatus,
)
from . import project

__all__ = ["CannbotChannel", "project"]

SCORE_SCALE = "cannbot/knowledge-search.v5"


class CannbotChannel:
"""Approved cannbot-knowledge checkout, queried through its own interpreter."""

def __init__(self, *, root: Path | None = None, timeout: float = 8.0):
from . import project

self._project = project
self.root = root
self.timeout = timeout
# `hint` records why this channel cannot answer before any search runs.
# Keeping it lets `find` report "not enabled" instead of telling the
# caller to declare a backend for a source that is not approved yet.
self.hint: ChannelStatus | None = None
try:
grant = project.load_grant(root)
except project.ChannelFailure as exc:
grant = {}
self.hint = ChannelStatus(exc.state, detail=str(exc), fix=exc.fix)
except (OSError, ValueError) as exc:
grant = {}
self.hint = ChannelStatus("rejected", detail=str(exc))
self.backend = "ascend"
self.declared_backend = grant.get("backend")
self.name = "cannbot-knowledge"

def describe(self, *, request: ChannelRequest) -> ChannelStatus:
try:
info = self._project.describe(self.root, timeout=request.remaining(), request=request)
except self._project.ChannelFailure as exc:
return ChannelStatus(exc.state, detail=str(exc), fix=exc.fix)
state = info.get("state", "rejected")
if state != "ok":
return ChannelStatus(
state if state != "rejected" else "rejected",
detail=str(info.get("detail") or ""), fix=str(info.get("fix") or ""),
)
return ChannelStatus("ok", revision=info.get("revision"))

def search(
self, query: str, *, platform: str | None, limit: int, request: ChannelRequest
) -> ChannelResult:
started = time.monotonic()
try:
payload = self._project.search(
query, platform=platform, limit=limit, root=self.root,
timeout=request.remaining(), request=request,
)
except self._project.ChannelFailure as exc:
return ChannelResult(
name=self.name, status=ChannelStatus(
exc.state, detail=str(exc), fix=exc.fix,
),
elapsed_ms=max(1, int((time.monotonic() - started) * 1000)),
)
elapsed = int((time.monotonic() - started) * 1000)
items = tuple(
ChannelHit(
locator=str(row.get("locator") or ""),
title=str(row.get("title") or ""),
summary=str(row.get("summary") or ""),
score=float(row.get("score") or 0),
score_scale=str(payload.get("score_scale") or SCORE_SCALE),
status=str(row.get("status") or ""),
platforms=tuple(row.get("platforms") or ()),
card_sha256=str(row.get("card_sha256") or ""),
source_card_sha256=str(row.get("source_card_sha256") or ""),
)
for row in payload.get("items") or []
if row.get("locator")
)
return ChannelResult(
name=self.name,
status=ChannelStatus("ok", revision=payload.get("revision")),
items=items,
elapsed_ms=elapsed,
score_scale=str(payload.get("score_scale") or SCORE_SCALE),
read_prefix="inferrsi cannbot read",
)

def read(self, locator: str, *, expected_sha256: str | None = None,
expected_revision: str | None = None) -> str:
payload = self._project.read(
locator, expected_sha256=expected_sha256, root=self.root,
expected_revision=expected_revision,
timeout=max(self.timeout, 15.0),
)
return str(payload.get("text") or "")
Loading
Loading