diff --git a/docs/external-channels.md b/docs/external-channels.md new file mode 100644 index 00000000..6db248f5 --- /dev/null +++ b/docs/external-channels.md @@ -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 --python +``` + +`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/.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 ` and +`--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": "", + "source_card_sha256": "", + "open": "inferrsi cannbot read ops/... --sha256 --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 @ ` 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 diff --git a/docs/operations.md b/docs/operations.md index 46eb49bc..d1a88810 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -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 --python +``` + +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 ` 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 ` overrides the per-channel cap (`cannbot-knowledge` 100, + `mindie-agent` 5). `--external-timeout ` 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 ` ranks generated packaged skills after the existing diff --git a/src/inferrsi/apps/cannbot/__init__.py b/src/inferrsi/apps/cannbot/__init__.py new file mode 100644 index 00000000..28f61ace --- /dev/null +++ b/src/inferrsi/apps/cannbot/__init__.py @@ -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 "") diff --git a/src/inferrsi/apps/cannbot/project.py b/src/inferrsi/apps/cannbot/project.py new file mode 100644 index 00000000..7386f049 --- /dev/null +++ b/src/inferrsi/apps/cannbot/project.py @@ -0,0 +1,283 @@ +"""An opt-in, per-checkout grant for an external cannbot-knowledge checkout. + +The upstream corpus is CANN-licensed and stays where it is. This module records +only which checkout, interpreter and default platform this project approved; it +never copies knowledge into the repository, the wheel or an evidence tree. +""" + +from __future__ import annotations + +import hashlib +import json +import os +import re +import subprocess +import tempfile +from pathlib import Path + +from .read_worker import OutputLimitError, _finite, capture + +_SCHEMA = "inferrsi-cannbot-project/1" +_WORKER = Path(__file__).with_name("read_worker.py") +MAX_BYTES = 2 * 1024 * 1024 +_BACKEND = re.compile(r"[a-z][a-z0-9]{0,31}") +# Upstream platform values this adapter will pass through. An unlisted value is +# 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") + + +class ChannelFailure(ValueError): + """A channel-level failure carrying the state the caller should report.""" + + def __init__(self, message, *, state="rejected", fix="", exit_code=None): + super().__init__(message) + self.state = state + self.fix = fix + self.exit_code = exit_code + + +def project_root() -> Path: + cwd = Path.cwd().resolve() + for folder in (cwd, *cwd.parents): + if (folder / ".git").exists(): + 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", + ) + + +def _grant_path(root: Path) -> Path: + project_id = hashlib.sha256(os.fsencode(root)).hexdigest() + return Path.home() / ".config" / "inferrsi" / "cannbot-projects" / (project_id + ".json") + + +def _checkout_identity(root: Path) -> dict: + marker = root / ".git" + info = marker.stat() + identity = {"device": info.st_dev, "inode": info.st_ino} + if hasattr(info, "st_birthtime"): + identity["created"] = info.st_birthtime + return identity + + +def _json(value) -> bytes: + return (json.dumps(value, ensure_ascii=True, allow_nan=False) + "\n").encode("utf-8") + + +def _parse(raw: bytes) -> dict: + def _object(pairs): + value = {} + for key, item in pairs: + if key in value: + raise ValueError("cannbot response contains duplicate JSON keys") + value[key] = item + return value + + def _invalid(_): + raise ValueError("cannbot response contains a non-finite JSON value") + + try: + value = json.loads(raw, object_pairs_hook=_object, parse_constant=_invalid, + parse_float=_finite) + except (ValueError, UnicodeError, RecursionError) as exc: + raise ValueError("cannbot did not return a JSON object") from exc + if not isinstance(value, dict): + raise ValueError("cannbot did not return a JSON object") + return value + + +def load_grant(root: Path | None = None) -> dict: + root = project_root() if root is None else root + path = _grant_path(root) + try: + info = path.stat() + if (path.is_symlink() or not path.is_file() + or os.name == "posix" and (info.st_uid != os.getuid() or info.st_mode & 0o077)): + raise ValueError("The cannbot project grant must be a private local file") + with path.open("rb") as source: + raw = source.read(MAX_BYTES + 1) + if len(raw) > MAX_BYTES: + raise ValueError("The cannbot project grant exceeds 2 MiB") + grant = _parse(raw) + checkout = _checkout_identity(root) + except FileNotFoundError: + raise ChannelFailure( + "cannbot knowledge is not enabled for this project", state="not_enabled", + fix="inferrsi cannbot enable --checkout --python ", + ) from None + except OSError: + raise ChannelFailure("The cannbot project grant could not be read", state="not_enabled") \ + from None + if (grant.get("schema") != _SCHEMA or grant.get("project_root") != str(root) + or grant.get("checkout_identity") != checkout + or not isinstance(grant.get("upstream"), str) + or not Path(grant["upstream"]).is_absolute() + or not isinstance(grant.get("python"), str) + or not Path(grant["python"]).is_absolute() + or not isinstance(grant.get("backend"), str) + or not _BACKEND.fullmatch(grant["backend"])): + raise ChannelFailure("The cannbot grant does not match this project", state="rejected") + platforms = grant.get("platforms", []) + if not isinstance(platforms, list) or any(item not in PLATFORMS for item in platforms): + raise ChannelFailure("The cannbot grant has an invalid platform list", state="rejected") + return grant + + +def _run(grant: dict, action: str, arguments: dict, *, timeout: float, request=None) -> dict: + environment = os.environ.copy() + for key in ("CANNBOT_MCP_TOKENS", "CANNBOT_KNOWLEDGE_PLATFORM"): + environment.pop(key, None) + try: + with tempfile.TemporaryDirectory(prefix="inferrsi-cannbot-read-") as temporary: + cwd = Path(temporary) / "reader" + cwd.mkdir(mode=0o700) + result = capture( + [grant["python"], "-I", "-B", str(_WORKER), + grant["upstream"], action, json.dumps(arguments), str(timeout)], + cwd=cwd, environment=environment, timeout=timeout, request=request, + own_group=True, + ) + except subprocess.TimeoutExpired: + raise ChannelFailure( + f"cannbot did not answer within {timeout:g}s", state="timeout" + ) from None + except OutputLimitError: + 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" + ) from None + if len(result.stdout) > MAX_BYTES: + raise ChannelFailure("cannbot returned more than 2 MiB", state="rejected") + try: + payload = _parse(result.stdout) + except ValueError: + raise ChannelFailure("cannbot returned invalid JSON", state="rejected") from None + if result.returncode or payload.get("isError"): + raise ChannelFailure( + str(payload.get("error") or "The approved cannbot reader failed"), + state=str(payload.get("state") or "rejected"), + fix=str(payload.get("fix") or ""), + exit_code=result.returncode, + ) + return payload + + +def describe(root: Path | None = None, *, timeout: float = 15.0, request=None) -> dict: + try: + grant = load_grant(root) + except ChannelFailure as exc: + return {"state": exc.state, "detail": str(exc), "fix": exc.fix} + try: + payload = _run(grant, "discover", {}, timeout=timeout, request=request) + except ChannelFailure as exc: + return {"state": exc.state, "detail": str(exc), "fix": exc.fix} + return { + "state": "ok", + "revision": payload.get("revision"), + "cards": payload.get("cards"), + "index": payload.get("index", {}), + "platforms": list(grant.get("platforms", [])), + } + + +def search( + query: str, *, platform: str | None = None, limit: int = 100, + root: Path | None = None, timeout: float = 8.0, request=None, +) -> dict: + if not isinstance(query, str) or not query.strip(): + raise ChannelFailure("cannbot search needs a non-empty query") + if type(limit) is not int or not 1 <= limit <= 200: + raise ChannelFailure("cannbot limit must be an integer from 1 through 200") + grant = load_grant(root) + platforms = list(grant.get("platforms", [])) + if platform is None: + if not platforms: + raise ChannelFailure( + "cannbot search needs a platform", state="rejected", + fix="inferrsi find --backend ascend --platform ", + ) + platform = platforms[0] + if platform not in PLATFORMS: + raise ChannelFailure(f"cannbot does not know platform {platform!r}", state="rejected") + return _run(grant, "search", { + "query": query, "platform": platform, "limit": limit, + }, timeout=timeout, request=request) + + +def read(locator: str, *, page: int = 1, expected_sha256: str | None = None, + expected_revision: str | None = None, + root: Path | None = None, timeout: float = 15.0) -> dict: + if not isinstance(locator, str) or not locator.strip(): + raise ChannelFailure("cannbot read needs a locator from a search result") + if type(page) is not int or page < 1: + raise ChannelFailure("cannbot page must be a positive integer") + if expected_sha256 is not None and ( + not isinstance(expected_sha256, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_sha256) + ): + raise ChannelFailure("cannbot expected_sha256 must be a lowercase 64-hex digest") + if expected_revision is not None and ( + not isinstance(expected_revision, str) + or not re.fullmatch(r"[0-9a-f]{40}", expected_revision) + ): + raise ChannelFailure("cannbot expected_revision must be a full lowercase Git revision") + arguments = {"locator": locator, "page": page} + if expected_sha256: + arguments["expected_sha256"] = expected_sha256 + if expected_revision: + arguments["expected_revision"] = expected_revision + return _run(load_grant(root), "read", arguments, timeout=timeout) + + +def enable(*, upstream: Path, python: Path, backend: str = "ascend", + platforms: list[str] | None = None) -> dict: + """Approve one checkout for this project after proving it answers. + + The probe is deliberate: a grant that records a checkout which cannot answer + would turn every later search into a failure the user has to debug. + """ + root = project_root() + upstream = Path(upstream).expanduser() + if not (upstream / ".git").exists(): + raise ValueError("--checkout must be a Git checkout of cannbot-knowledge") + if not (upstream / "knowledge").is_dir(): + raise ValueError("--checkout must contain the knowledge/ bundle root") + if not (upstream / ".agents/skills/knowledge-query/scripts/knowledge_query.py").is_file(): + raise ValueError("--checkout is missing the knowledge-query scripts") + interpreter = Path(python).expanduser() + if not interpreter.is_file() or not os.access(interpreter, os.X_OK): + raise ValueError("--python must be an executable interpreter with pyyaml installed") + if not _BACKEND.fullmatch(backend): + raise ValueError("--backend must be a lowercase backend name") + chosen = list(platforms or []) + if any(item not in PLATFORMS for item in chosen): + raise ValueError("--platform takes one of " + ", ".join(PLATFORMS)) + grant = { + "schema": _SCHEMA, "project_root": str(root), + "checkout_identity": _checkout_identity(root), + "upstream": str(upstream.resolve()), + # Record the interpreter path as given. Resolving the symlink in a venv + # bin/ lands on the base interpreter, which loses every installed + # dependency -- the probe would pass and every later search would fail. + "python": str(interpreter.absolute()), + "backend": backend, "platforms": chosen, + } + info = _run(grant, "discover", {}, timeout=30.0) + path = _grant_path(root) + path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) + with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as output: + pending = Path(output.name) + try: + output.write(_json(grant)) + output.close() + pending.replace(path) + finally: + pending.unlink(missing_ok=True) + return {"enabled": True, "revision": info.get("revision"), "cards": info.get("cards")} + + +def disable() -> dict: + _grant_path(project_root()).unlink(missing_ok=True) + return {"enabled": False, "reason": "cannbot knowledge is not enabled for this project"} diff --git a/src/inferrsi/apps/cannbot/read_worker.py b/src/inferrsi/apps/cannbot/read_worker.py new file mode 100644 index 00000000..0ff4055d --- /dev/null +++ b/src/inferrsi/apps/cannbot/read_worker.py @@ -0,0 +1,369 @@ +"""Call the approved cannbot-knowledge checkout with its own interpreter. + +Run this worker with the interpreter recorded in the project grant: upstream +requires the MCP SDK constraints and PyYAML from its own environment, and this +program must not import the upstream package into the InferRSI process. Nothing +here writes to the upstream tree; the query CLI is read-only except for an +optional receipt, which is not requested. +""" + +import hashlib +import json +import math +import os +import queue +import re +import signal +import subprocess +import sys +import threading +import time +from pathlib import Path + +_SCRIPT = ".agents/skills/knowledge-query/scripts/knowledge_query.py" +_INDEX = ".agents/skills/knowledge-query/scripts/knowledge_index.py" +_STALE_MARKERS = ("stale", "missing", "rebuild", "index build", "inconsistent") +_FIX_BUILD = ( + "cd && python3 " + _INDEX + " build" +) +# Upstream output is untrusted input. Bound it while reading, not after the +# whole stream is already in memory. +_MAX_UPSTREAM = 2 * 1024 * 1024 + + +def _fail(message, *, state="rejected", fix=""): + print(json.dumps({"isError": True, "error": message, "state": state, "fix": fix})) + raise SystemExit(1) + + +def _object(pairs): + value = {} + for key, item in pairs: + if key in value: + raise ValueError("cannbot source JSON has duplicate keys") + value[key] = item + return value + + +def _invalid(_): + raise ValueError("cannbot source JSON has a non-finite number") + + +def _finite(value): + number = float(value) + if not math.isfinite(number): + _invalid(value) + return number + + +def _strict(raw): + """Reject duplicate keys and non-finite numbers at the source boundary. + + `json.loads` collapses a duplicate key before any caller can see it, so a + later re-serialisation cannot repair a document that was ambiguous on + arrival. The check has to run on the upstream bytes themselves. + """ + try: + value = json.loads( + raw, object_pairs_hook=_object, parse_constant=_invalid, parse_float=_finite, + ) + except (ValueError, UnicodeError, RecursionError): + _fail("cannbot returned malformed JSON", state="rejected") + if not isinstance(value, dict): + _fail("cannbot did not return a JSON object", state="rejected") + return value + + +class OutputLimitError(ValueError): + """A pipe exceeded the bounded capture size.""" + + +def _stop(process, *, own_group): + if own_group and os.name == "posix": + try: + os.killpg(process.pid, signal.SIGKILL) + except ProcessLookupError: + pass + elif own_group and os.name == "nt" and process.poll() is None: + subprocess.run( + ["taskkill", "/PID", str(process.pid), "/T", "/F"], + stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2, check=False, + ) + if process.poll() is None: + process.kill() + process.wait(timeout=2) + + +def capture(argv, *, cwd, timeout, environment=None, request=None, own_group=False): + """Capture at most 2 MiB + 1 per pipe, with no unbounded communicate(). + + The outer worker owns a process group; upstream queries inherit it. Both + the caller's cancellation and this function's finally block reap that group. + Each pipe is drained concurrently so a full stderr cannot deadlock stdout. + """ + deadline = time.monotonic() + timeout + + def start(): + return subprocess.Popen( + argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + cwd=cwd, env=environment, start_new_session=own_group and os.name == "posix", + creationflags=(subprocess.CREATE_NEW_PROCESS_GROUP + if own_group and os.name == "nt" else 0), + ) + + def stop(process): + _stop(process, own_group=own_group) + + process = request.start(start, stop) if request else start() + received = queue.Queue(maxsize=2) + + def drain(name, stream): + try: + with stream: + received.put((name, stream.read(_MAX_UPSTREAM + 1))) + except OSError: + received.put((name, b"")) + + for name, stream in (("stdout", process.stdout), ("stderr", process.stderr)): + threading.Thread(target=drain, args=(name, stream), daemon=True).start() + try: + output = {} + for _ in range(2): + try: + name, raw = received.get(timeout=max(0, deadline - time.monotonic())) + except queue.Empty: + raise subprocess.TimeoutExpired(argv, timeout) from None + if len(raw) > _MAX_UPSTREAM: + raise OutputLimitError("cannbot output exceeded 2 MiB") + output[name] = raw + code = process.wait(timeout=max(0, deadline - time.monotonic())) + return subprocess.CompletedProcess(argv, code, output["stdout"], output["stderr"]) + finally: + if request: + request.finish(process) + else: + stop(process) + + +def _run(upstream, script, argv, *, timeout): + try: + result = capture( + [sys.executable, "-I", "-B", str(upstream / script), *argv], + cwd=str(upstream), timeout=timeout, + ) + except OutputLimitError: + _fail("cannbot output exceeded 2 MiB") + if result.returncode: + lowered = result.stderr.decode("utf-8", "replace").casefold() + state = "index_stale" if any(m in lowered for m in _STALE_MARKERS) else "rejected" + # Never relay arbitrary upstream stderr: it may contain private paths. + _fail("cannbot index needs rebuilding" if state == "index_stale" + else "cannbot query failed", state=state, + fix=_FIX_BUILD if state == "index_stale" else "") + return _strict(result.stdout) + + +def _index(payload): + index = payload.get("index") + if not isinstance(index, dict): + _fail("cannbot response needs an index object") + state = index.get("built_repository_state") + if not isinstance(state, dict) or not isinstance(state.get("commit"), str): + _fail("cannbot response needs an index revision") + if not re.fullmatch(r"[0-9a-f]{40}", state["commit"]): + _fail("cannbot response has an invalid index revision") + return index, state + + +def discover(upstream, *, timeout=30): + payload = _run(upstream, _SCRIPT, ["discover", "--json"], timeout=timeout) + if payload.get("schema_version") != "knowledge-discovery.v1": + _fail("Unsupported cannbot discovery schema", state="version_mismatch") + if type(payload.get("cards")) is not int or payload["cards"] < 0: + _fail("cannbot discovery needs a non-negative card count") + index, state = _index(payload) + return { + "state": "ok", + "revision": state.get("commit"), + "cards": payload.get("cards"), + "domains": payload.get("domains", {}), + "index": { + "schema": index.get("schema_version"), + "version": index.get("version") or index.get("index_version"), + "content_fingerprint": index.get("content_fingerprint"), + }, + } + + +def _card_bytes(upstream, locator): + root = (upstream / "knowledge").resolve() + card = (root / (locator + ".md")).resolve() + if not card.is_relative_to(root) or not card.is_file(): + _fail("No such card in the approved checkout") + with card.open("rb") as source: + raw = source.read(_MAX_UPSTREAM + 1) + if len(raw) > _MAX_UPSTREAM: + _fail("cannbot card exceeded 2 MiB") + return raw + + +def _source_fingerprint(upstream): + # The query index hashes parsed metadata + body, unlike MCP read_card's + # raw-byte digest. Use the approved source's own implementation; never copy + # its parser or fingerprint algorithm into this package. + sys.path.insert(0, str((upstream / _SCRIPT).parent)) + try: + from retrieval.index import card_fingerprint, load_contract + + _, split_frontmatter = load_contract(upstream) + except (ImportError, AttributeError): + _fail("Unsupported cannbot card identity API", state="version_mismatch") + return card_fingerprint, split_frontmatter + + +def search(upstream, arguments, *, timeout=60): + payload = _run(upstream, _SCRIPT, [ + "search", "--json", "--query", arguments["query"], + "--platform", arguments["platform"], "--limit", str(arguments["limit"]), + ], timeout=timeout) + if payload.get("schema_version") != "knowledge-search.v5": + _fail("Unsupported cannbot search schema", state="version_mismatch") + rows = payload.get("results") + if not isinstance(rows, list): + _fail("cannbot search needs a results list") + # Bound card verification too, rather than trimming only the final output. + rows = rows[:arguments["limit"]] + hits = [] + if rows: + fingerprint, split_frontmatter = _source_fingerprint(upstream) + for row in rows: + if not isinstance(row, dict): + _fail("cannbot search result must be an object") + locator, digest = row.get("path"), row.get("card_sha256") + if (not isinstance(locator, str) or not locator or locator.startswith("/") + or "\\" in locator or any(p in ("", ".", "..") for p in locator.split("/"))): + _fail("cannbot search result has an invalid locator") + if not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest): + _fail("cannbot search result needs a card digest") + score = row.get("score") + if type(score) not in (int, float) or not math.isfinite(score): + _fail("cannbot search result needs a finite score") + if any(row.get(key) is not None and not isinstance(row[key], str) + for key in ("title", "description", "status")): + _fail("cannbot search result has invalid text fields") + platforms = row.get("platforms") + if platforms is not None and (not isinstance(platforms, list) + or any(not isinstance(p, str) for p in platforms)): + _fail("cannbot search result has an invalid platform list") + raw = _card_bytes(upstream, locator) + metadata, body = split_frontmatter(raw.decode("utf-8")) + if fingerprint(metadata, body) != digest: + _fail("cannbot card differs from its search index", state="index_stale", + fix=_FIX_BUILD) + hits.append({ + "locator": row.get("path"), + "title": row.get("title") or (row.get("path") or "").rsplit("/", 1)[-1], + "summary": row.get("description") or "", + "score": row.get("score") or 0, + "status": row.get("status") or "", + "platforms": row.get("platforms") or [], + "source_card_sha256": digest, + "card_sha256": hashlib.sha256(raw).hexdigest(), + }) + index, state = _index(payload) + # The pin lives on the index provenance, not at the top level: that is the + # revision the index was built from, which is what a citation must name. + return { + "state": "ok", + "revision": state.get("commit"), + "index": { + "schema": index.get("schema_version"), + "version": index.get("index_version"), + "content_fingerprint": index.get("content_fingerprint"), + }, + "score_scale": payload.get("schema_version") or "cannbot", + "items": hits, + } + + +def _revision(upstream, *, timeout): + # Inherited repository-selection variables must not redirect this check. + environment = {key: value for key, value in os.environ.items() + if not key.startswith("GIT_")} + try: + result = capture( + ["git", "-C", str(upstream), "rev-parse", "--verify", "HEAD"], + cwd=str(upstream), timeout=timeout, environment=environment, + ) + except OutputLimitError: + _fail("cannbot revision output exceeded 2 MiB") + revision = result.stdout.decode("ascii", "replace").strip() + if result.returncode or not re.fullmatch(r"[0-9a-f]{40}", revision): + _fail("Cannot determine the approved cannbot checkout revision", + state="version_mismatch") + return revision + + +def read(upstream, arguments, *, timeout=15): + deadline = time.monotonic() + timeout + revision = _revision(upstream, timeout=max(0, deadline - time.monotonic())) + expected_revision = arguments.get("expected_revision") + if expected_revision and revision != expected_revision: + _fail("The cannbot revision changed since the search; search again", + state="version_mismatch") + locator = arguments["locator"] + body = _card_bytes(upstream, locator) + if _revision(upstream, timeout=max(0, deadline - time.monotonic())) != revision: + _fail("The cannbot revision changed during the read; search again", + state="version_mismatch") + digest = hashlib.sha256(body).hexdigest() + # Search reports what it matched; read reports what it actually returned. + # Without both, a card edited between the two is served under the old + # locator and a citation names bytes nobody verified. A caller that passed + # an expected digest gets a refusal instead of silent drift. + expected = arguments.get("expected_sha256") + if expected and expected != digest: + _fail( + "The card changed since the search that found it " + f"(expected {expected[:12]}…, read {digest[:12]}…); search again", + state="rejected", + ) + lines = body.decode("utf-8").splitlines() + size, page = 200, arguments.get("page", 1) + start = (page - 1) * size + chunk = lines[start:start + size] + return { + "state": "ok", + "locator": locator, + "revision": revision, + "page": page, + "pages": max(1, (len(lines) + size - 1) // size), + "line_count": len(lines), + "card_sha256": digest, + "text": "\n".join(chunk), + "has_more": start + size < len(lines), + } + + +if __name__ == "__main__": + try: + upstream = Path(sys.argv[1]).resolve() + action, raw = sys.argv[2], sys.argv[3] if len(sys.argv) > 3 else "{}" + arguments = _strict(raw or "{}") + timeout = float(sys.argv[4]) if len(sys.argv) > 4 else 30.0 + if action == "discover": + result = discover(upstream, timeout=timeout) + elif action == "search": + result = search(upstream, arguments, timeout=timeout) + elif action == "read": + result = read(upstream, arguments, timeout=timeout) + else: + _fail("Unknown cannbot read action") + except SystemExit: + raise + except subprocess.TimeoutExpired: + _fail("cannbot query timed out", state="timeout") + except (OSError, ValueError, KeyError, TypeError): + # Paths and upstream internals must not reach the caller. + _fail("The local cannbot checkout is unavailable", state="unreachable") + print(json.dumps(result, ensure_ascii=True, allow_nan=False)) diff --git a/src/inferrsi/apps/cli/__init__.py b/src/inferrsi/apps/cli/__init__.py index 7d84e23d..b8df0fc3 100644 --- a/src/inferrsi/apps/cli/__init__.py +++ b/src/inferrsi/apps/cli/__init__.py @@ -134,11 +134,60 @@ def _clip(value: str, limit: int = 160) -> str: return text if len(text) <= limit else text[: limit - 1].rstrip() + "…" +def _channels(): + """Build the external channel registry from whatever this checkout approved. + + The grant is the second source of a declared backend, after an explicit + `--backend`. Reading it here is what makes `cannbot enable --backend ascend` + mean something: without it, an approved Ascend source would only ever run + when the caller repeated the flag, and the approval would silently do + nothing on the default path. + + Constructing a channel reads its grant, which is a cheap local file read. + An unreadable or absent grant is not fatal: the channel still exists and + reports `not_enabled` with a fix when asked, which is more useful than + dropping it from the list. + """ + from ...knowledge.channels import ChannelRegistry + from ..cannbot import CannbotChannel + + channel = CannbotChannel() + return ChannelRegistry([channel], declared_backend=channel.declared_backend) + + +def _print_external(result: dict) -> None: + """Print the external column under the local one, never mixed into it.""" + entries = result.get("external") or [] + if not entries: + return + print("\nexternal (not locally verified; scores are not comparable across channels)") + for entry in entries: + state = entry.get("state", "unknown") + if state != "ok": + line = f" {entry['channel']}\t[{state}]" + if entry.get("detail"): + line += f"\t{_clip(entry['detail'], 100)}" + print(line) + if entry.get("fix"): + print(f" fix: {_clip(entry['fix'], 120)}") + continue + revision = (entry.get("revision") or "")[:12] or "unpinned" + print(f" {entry['channel']} @ {revision}\t[{entry['score_scale']}]" + f"\t{entry.get('count', 0)} hit(s)\t{entry.get('elapsed_ms', 0)} ms") + for item in entry.get("items", []): + print(f" {item['score']}\t{_clip(item['title'], 60)}\t{item['locator']}") + if entry.get("items"): + print(f" open: {entry['items'][0].get('open', '')}") + for note in result.get("external_notes", []): + print(f" note: {_clip(note, 140)}") + + def _print_find(result: dict) -> None: """Lead with what was tried and how far the evidence goes, then the path.""" if result["no_match"]: print(f"no_match\t{result['corpus_size']} entries searched; " f"rephrase, or search the corpus directly with rg") + _print_external(result) return for item in result["items"]: labels = [_FIND_KIND.get(item["kind"], item["kind"]), _tsv(item["state"])] @@ -187,6 +236,7 @@ def _print_find(result: dict) -> None: print(f" source: {item['source']}") for token, gain in item.get("matched", {}).items(): print(f" [{token}] {gain}") + _print_external(result) def _context(records: list[dict]) -> str: @@ -247,6 +297,30 @@ def main(argv: list[str] | None = None) -> int: if result is not None: _print(result) return 0 + if args.command == "cannbot": + from .. import cannbot + + action = args.cannbot_action + if action == "enable": + result = cannbot.project.enable( + upstream=args.checkout, python=args.python, + backend=args.backend, platforms=args.platform, + ) + elif action == "disable": + result = cannbot.project.disable() + elif action == "describe": + result = cannbot.project.describe() + elif action == "search": + result = cannbot.project.search( + args.query, platform=args.platform, limit=args.limit, + ) + else: + result = cannbot.project.read( + args.locator, page=args.page, expected_sha256=args.sha256, + expected_revision=args.revision, + ) + _print(result) + return 0 if args.command == "agents": from ...harness import agent_sessions @@ -372,8 +446,14 @@ def main(argv: list[str] | None = None) -> int: unknown = [k for k in kinds if k not in ("case", "skill", "record")] if unknown or not kinds: raise ValueError("--kinds takes a subset of case,skill,record") - result = find(args.query, load_corpus(args.skill_root, kinds=kinds), - limit=args.limit, explain=args.explain) + result = find( + args.query, load_corpus(args.skill_root, kinds=kinds), + limit=args.limit, explain=args.explain, + registry=None if args.no_external else _channels(), + backend=args.backend, platform=args.platform, + external_limit=args.external_limit, + external_timeout=args.external_timeout, + ) if args.json: _print(result) else: diff --git a/src/inferrsi/apps/cli/arguments.py b/src/inferrsi/apps/cli/arguments.py index b85c667d..5d24e528 100644 --- a/src/inferrsi/apps/cli/arguments.py +++ b/src/inferrsi/apps/cli/arguments.py @@ -121,6 +121,42 @@ def parser() -> argparse.ArgumentParser: for action in ("query", "explain"): read = mindie_actions.add_parser(action, help=f"Run a MindIE {action} and keep a receipt") read.add_argument("--input", type=Path, required=True, help="JSON tool arguments") + cannbot = commands.add_parser( + "cannbot", help="Use a project-approved, external cannbot-knowledge checkout" + ) + cannbot_actions = cannbot.add_subparsers(dest="cannbot_action", required=True) + cannbot_enable = cannbot_actions.add_parser( + "enable", help="Approve one cannbot-knowledge checkout for this project" + ) + cannbot_enable.add_argument("--checkout", type=Path, required=True) + cannbot_enable.add_argument( + "--python", type=Path, required=True, + help="Interpreter with pyyaml that can run the checkout's knowledge-query scripts", + ) + cannbot_enable.add_argument("--backend", default="ascend") + cannbot_enable.add_argument( + "--platform", action="append", default=[], + help="Default upstream platform; repeatable. Required for a platform-less search.", + ) + cannbot_actions.add_parser("disable", help="Revoke the project grant") + cannbot_actions.add_parser("describe", help="Probe the approved checkout and its index") + cannbot_search = cannbot_actions.add_parser( + "search", help="Search the approved checkout; returns card locators, not text" + ) + cannbot_search.add_argument("query") + cannbot_search.add_argument("--platform") + cannbot_search.add_argument("--limit", type=int, default=100) + cannbot_read = cannbot_actions.add_parser("read", help="Read one card by locator") + cannbot_read.add_argument("locator") + cannbot_read.add_argument( + "--sha256", + help="Expected card digest from a search result; refuse the read if the " + "card changed since then", + ) + cannbot_read.add_argument("--page", type=int, default=1) + cannbot_read.add_argument( + "--revision", help="Expected full checkout revision from a search result", + ) agents = commands.add_parser("agents", help="Record native host fresh-session handoffs") agent_actions = agents.add_subparsers(dest="agent_action", required=True) prepare = agent_actions.add_parser("prepare", help="Freeze a task for the current host") @@ -431,6 +467,24 @@ def parser() -> argparse.ArgumentParser: find.add_argument( "--explain", action="store_true", help="Report each query term's contribution" ) + find.add_argument( + "--backend", + help="Declare the task backend once, e.g. ascend; external channels run only " + "for a declared backend and are never inferred from the query", + ) + find.add_argument("--platform", help="Override the grant’s upstream platform, e.g. a2") + find.add_argument( + "--no-external", action="store_true", + help="Skip every external channel; use in CI and offline runs", + ) + find.add_argument( + "--external-limit", type=int, + help="Override the per-channel result cap (cannbot 100, MindIE 5 by default)", + ) + find.add_argument( + "--external-timeout", type=float, default=8.0, + help="Per-channel budget in seconds; a timeout is reported, never shown as no hit", + ) find.add_argument("--json", action="store_true") collect = commands.add_parser( diff --git a/src/inferrsi/knowledge/channels.py b/src/inferrsi/knowledge/channels.py new file mode 100644 index 00000000..8489b060 --- /dev/null +++ b/src/inferrsi/knowledge/channels.py @@ -0,0 +1,394 @@ +"""Read-only external knowledge channels, ranked beside the local corpus. + +An external channel answers "what does a source outside this repository know +about this problem" without vendoring its content. Only locators come back: +the caller opens what it needs through the channel's own `read`. That is what +keeps a CANN-licensed corpus out of this repository's package, wheel and +evidence tree while still making it searchable. + +Three rules follow from that and are enforced here rather than by convention: + +* A channel result is never merged into the local ranked list. Scores come from + different corpora and are not comparable, so each result carries the scale it + was ranked on and the caller compares across columns, not within one. +* A failure is a state, not an empty list. "Searched and found nothing" and + "could not search" are different facts, and conflating them lets a caller + conclude the source has no such knowledge. +* No card text is returned on the ranking path. An adapter may verify selected + card bytes to bind locators to a digest; material reads are separate calls. + +Channels are opt-in. Resolving a registry never imports or probes one until the +platform gate has selected it, and an absent registry leaves `find` behaving +exactly as it did before channels existed. +""" + +from __future__ import annotations + +import concurrent.futures +import math +import shlex +import threading +import time +from dataclasses import dataclass, field, replace +from typing import Any, Protocol, runtime_checkable + +# States a channel can report. `ok` is the only one that carries items; every +# other value means the caller did not get an answer and must say so. +OK = "ok" +NOT_ENABLED = "not_enabled" +UNREACHABLE = "unreachable" +INDEX_STALE = "index_stale" +TIMEOUT = "timeout" +VERSION_MISMATCH = "version_mismatch" +REJECTED = "rejected" +UNKNOWN = "unknown" +BACKEND_UNKNOWN = "backend_unknown" +SKIPPED = "skipped" + +CHANNEL_STATES = ( + OK, NOT_ENABLED, UNREACHABLE, INDEX_STALE, TIMEOUT, + VERSION_MISMATCH, REJECTED, UNKNOWN, BACKEND_UNKNOWN, SKIPPED, +) + +# Per-channel result budget. The upstream locator is precise (a Concept ID) and +# a lexical query can legitimately match hundreds of cards, so the default is +# wide enough that the count reflects coverage rather than the cap; MindIE +# returns coarser refs and buries local hits past a handful. Callers override +# with --external-limit. +DEFAULT_LIMITS = { + "cannbot-knowledge": 100, + "mindie-agent": 5, +} +FALLBACK_LIMIT = 5 + + +@dataclass(frozen=True) +class ChannelStatus: + """Why a channel did or did not answer. Never silently 'empty'.""" + + state: str + revision: str | None = None + detail: str = "" + fix: str = "" + checked_at: float = 0.0 + + def __post_init__(self) -> None: + if self.state not in CHANNEL_STATES: + raise ValueError(f"Unknown channel state: {self.state}") + + def view(self) -> dict: + record: dict[str, Any] = {"state": self.state} + if self.revision: + record["revision"] = self.revision + if self.detail: + record["detail"] = self.detail + if self.fix: + record["fix"] = self.fix + return record + + +@dataclass(frozen=True) +class ChannelHit: + """A locator, not knowledge. Read the card through the channel to use it.""" + + locator: str + title: str + score: float + score_scale: str + summary: str = "" + status: str = "" + platforms: tuple[str, ...] = () + card_sha256: str = "" + source_card_sha256: str = "" + + def view(self, *, read_prefix: str, revision: str | None = None) -> dict: + record: dict[str, Any] = { + "locator": self.locator, + "title": self.title, + "score": round(self.score, 2), + "score_scale": self.score_scale, + } + if self.summary: + record["summary"] = self.summary + if self.status: + record["status"] = self.status + if self.platforms: + record["platforms"] = list(self.platforms) + if self.card_sha256: + record["card_sha256"] = self.card_sha256 + if self.source_card_sha256: + record["source_card_sha256"] = self.source_card_sha256 + if read_prefix: + argv = [*shlex.split(read_prefix), self.locator] + if self.card_sha256: + argv.extend(["--sha256", self.card_sha256]) + if revision: + argv.extend(["--revision", revision]) + record["open"] = shlex.join(argv) + return record + + +@dataclass(frozen=True) +class ChannelResult: + """One channel's answer for one query.""" + + name: str + status: ChannelStatus + items: tuple[ChannelHit, ...] = () + elapsed_ms: int = 0 + score_scale: str = "" + read_prefix: str = "" + + def view(self) -> dict: + record: dict[str, Any] = {"channel": self.name, **self.status.view()} + record["elapsed_ms"] = self.elapsed_ms + if self.score_scale: + record["score_scale"] = self.score_scale + record["count"] = len(self.items) + if self.items: + record["items"] = [ + item.view(read_prefix=self.read_prefix, revision=self.status.revision) + for item in self.items + ] + return record + + +@runtime_checkable +class Channel(Protocol): + """One external read-only source. + + `backend` is a declaration, not a guess: a channel that serves one platform + says so, and a channel with `None` is platform-neutral. Selection never + infers a backend from a query string, because a wrong inference is silent. + """ + + name: str + backend: str | None + + def describe(self, *, request: ChannelRequest) -> ChannelStatus: ... + + def search( + self, query: str, *, platform: str | None, limit: int, request: ChannelRequest + ) -> ChannelResult: ... + + def read(self, locator: str, *, expected_sha256: str | None = None, + expected_revision: str | None = None) -> str: ... + + +@dataclass +class ChannelRegistry: + """The channels this checkout has, and the gate that decides which run. + + `declared_backend` is a fact about the task, not about a channel: it comes + from an explicit `--backend` or from an approved grant. `Channel.backend` + says which platform a source serves and is only used to *select* channels. + Conflating the two made an undeclared task search anyway, because a + channel's own backend looked like a declaration. + """ + + channels: list[Channel] = field(default_factory=list) + declared_backend: str | None = None + + def for_backend(self, backend: str | None) -> list[Channel]: + """Return channels eligible for a declared task backend. + + No backend means no external search: an undeclared platform is not + evidence that the task is platform-neutral, and querying every channel + "just in case" would let a CUDA task silently receive Ascend guidance. + """ + if backend is None: + return [] + return [ + channel for channel in self.channels + if channel.backend is None or channel.backend == backend + ] + + def ungated(self) -> list[Channel]: + """Channels that would have run, for explaining a missing gate.""" + return [ + channel for channel in self.channels + if channel.backend is not None + ] or list(self.channels) + + +def _empty(name: str, state: str, *, detail: str = "", fix: str = "", + revision: str | None = None) -> ChannelResult: + return ChannelResult( + name=name, status=ChannelStatus(state, revision=revision, detail=detail, fix=fix) + ) + + +class ChannelRequest: + """One deadline and owned resources for describe plus search. + + Adapters must start subprocesses through this request, so cancellation and + process creation cannot race. Cleanup is idempotent and synchronous; once + cancelled, a late worker cannot start more work. Pure Python adapters must + cooperate with the deadline. Their daemon threads cannot delay CLI exit. + """ + + def __init__(self, deadline: float): + self.deadline = deadline + self._lock = threading.Lock() + self._cancelled = False + self._resources: dict = {} + + def remaining(self) -> float: + remaining = self.deadline - time.monotonic() + if self._cancelled or remaining <= 0: + raise TimeoutError("external channel deadline expired") + return remaining + + def start(self, factory, cleanup): + with self._lock: + self.remaining() + resource = factory() + self._resources[resource] = cleanup + return resource + + def finish(self, resource): + with self._lock: + cleanup = self._resources.get(resource) + if cleanup: + cleanup(resource) + self._resources.pop(resource) + + def cancel(self): + with self._lock: + self._cancelled = True + failed = False + for resource, cleanup in self._resources.items(): + try: + cleanup(resource) + except Exception: + failed = True + self._resources.clear() + return not failed + + +def _run_one( + channel: Channel, query: str, *, platform: str | None, limit: int, + request: ChannelRequest, started: float, +) -> ChannelResult: + phase = "describe" + try: + request.remaining() + described = channel.describe(request=request) + request.remaining() + if described.state != OK: + result = ChannelResult(name=channel.name, status=described) + else: + phase = "search" + result = channel.search(query, platform=platform, limit=limit, request=request) + request.remaining() + # The public cap must hold even when an adapter ignores its limit. + result = replace(result, items=result.items[:limit]) + except TimeoutError: + result = _empty(channel.name, TIMEOUT, detail="external channel deadline expired") + except Exception as exc: + result = _empty( + channel.name, UNREACHABLE if phase == "describe" else REJECTED, + detail=_reason(exc), + ) + return replace(result, elapsed_ms=max(1, int((time.monotonic() - started) * 1000))) + + +def _reason(exc: BaseException) -> str: + text = str(exc).strip() + return text or type(exc).__name__ + + +def search_channels( + registry: ChannelRegistry, + query: str, + *, + backend: str | None, + platform: str | None = None, + limit: int | None = None, + timeout: float = 8.0, +) -> list[ChannelResult]: + """Query eligible channels concurrently, cancel owned work at one deadline. + + There is no executor shutdown/atexit join and no fresh timeout per future. + Adapters receive the same request for both phases, including the remaining + budget and resource cleanup. A late answer is discarded, never labelled OK. + """ + if not math.isfinite(timeout) or timeout <= 0: + raise ValueError("external timeout must be positive and finite") + if limit is not None and (type(limit) is not int or limit < 1): + raise ValueError("external limit must be a positive integer") + eligible = registry.for_backend(backend) + started = time.monotonic() + pending = [] + + def work(channel, request, future): + future.set_result(_run_one( + channel, query, platform=platform, + limit=limit or DEFAULT_LIMITS.get(channel.name, FALLBACK_LIMIT), + request=request, started=started, + )) + + for channel in eligible: + request = ChannelRequest(started + timeout) + future = concurrent.futures.Future() + threading.Thread( + target=work, args=(channel, request, future), daemon=True, + name="inferrsi-channel", + ).start() + pending.append((channel, request, future)) + + results = [] + for channel, request, future in pending: + try: + result = future.result(timeout=max(0, request.deadline - time.monotonic())) + except concurrent.futures.TimeoutError: + result = replace( + _empty(channel.name, TIMEOUT, detail=f"no answer within {timeout:g}s"), + elapsed_ms=max(1, int((time.monotonic() - started) * 1000)), + ) + finally: + cleaned = request.cancel() + if not cleaned: + result = replace( + _empty(channel.name, REJECTED, detail="channel resource cleanup failed"), + elapsed_ms=max(1, int((time.monotonic() - started) * 1000)), + ) + results.append(result) + return results + + +def explain_gate(registry: ChannelRegistry, backend: str | None) -> list[dict]: + """Say which channels exist but were not asked, and why. + + An undeclared backend is the one case where a caller could reasonably + expect an answer and get none, so it is reported rather than passed over. + A channel that already knows it cannot answer overrides the gate reason: + telling someone to declare a backend for a source that is not approved yet + sends them down the wrong fix. + """ + if backend is not None: + return [] + records = [] + for channel in registry.ungated(): + hint = getattr(channel, "hint", None) + if isinstance(hint, ChannelStatus) and hint.state != OK: + records.append({ + "channel": channel.name, + "state": hint.state, + "detail": hint.detail, + **({"fix": hint.fix} if hint.fix else {}), + }) + continue + records.append({ + "channel": channel.name, + "backend": channel.backend, + "state": BACKEND_UNKNOWN, + "fix": f"inferrsi find --backend {channel.backend or ''}", + "detail": "No task backend was declared; external channels are not searched.", + }) + return records + + +def external_view(results: list[ChannelResult], *, notes: list[str] | None = None) -> list[dict]: + """Render channel results for `find`'s output, unchanged in shape when empty.""" + return [result.view() for result in results] diff --git a/src/inferrsi/knowledge/knowledge_find.py b/src/inferrsi/knowledge/knowledge_find.py index c005c0e3..f73fdfde 100644 --- a/src/inferrsi/knowledge/knowledge_find.py +++ b/src/inferrsi/knowledge/knowledge_find.py @@ -33,7 +33,10 @@ from io import BytesIO from pathlib import Path from statistics import median -from typing import Any +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + from .channels import ChannelRegistry from ._skill_selection import TASK_STOP_WORDS, named_backends from .catalog import BACKENDS @@ -729,7 +732,18 @@ def _why_unreadable(document: Document, readers: dict) -> str | None: return None -def find(query: str, corpus: Corpus, *, limit: int = 5, explain: bool = False) -> dict: +def find( + query: str, + corpus: Corpus, + *, + limit: int = 5, + explain: bool = False, + registry: "ChannelRegistry | None" = None, + backend: str | None = None, + platform: str | None = None, + external_limit: int | None = None, + external_timeout: float = 8.0, +) -> dict: if type(limit) is not int or limit < 1: raise ValueError("limit must be a positive integer") # A topic alias can add backend terms for matching, as 图模式 adds cuda graph. @@ -774,4 +788,51 @@ def find(query: str, corpus: Corpus, *, limit: int = 5, explain: bool = False) - # Report what a query term was taken to mean, so a wrong expansion is # visible in the result rather than only in the ranking. result["expanded"] = {term: list(values) for term, values in applied.items()} + return _with_channels( + result, query, registry=registry, backend=backend, platform=platform, + external_limit=external_limit, external_timeout=external_timeout, + ) + + +def _with_channels( + result: dict, + query: str, + *, + registry: "ChannelRegistry | None", + backend: str | None, + platform: str | None, + external_limit: int | None, + external_timeout: float, +) -> dict: + """Add the external column, or leave the result untouched when there is none. + + External hits stay out of `items`. They were not ranked on this corpus and + are not locally verified, so putting them in the same list would let any + caller that only reads `items` treat them as validated knowledge. The list + is also absent rather than empty when no channel exists, so callers that + predate channels see the output they always got. + """ + if registry is None or not registry.channels: + return result + from .channels import explain_gate, search_channels + + declared = backend if backend is not None else registry.declared_backend + results = search_channels( + registry, query, backend=declared, platform=platform, + limit=external_limit, timeout=external_timeout, + ) + if declared is not None: + result["backend"] = declared + if results: + result["external"] = [item.view() for item in results] + gated = explain_gate(registry, declared) + if gated: + result.setdefault("external", []).extend(gated) + if results or gated: + result["external_notes"] = [ + "External results are not locally verified; scores are not " + "comparable across channels.", + "Pin the reported revision when citing an external locator.", + "Open external cards with the channel's read command, not `read`.", + ] return result diff --git a/tests/test_cannbot_boundaries.py b/tests/test_cannbot_boundaries.py new file mode 100644 index 00000000..bf0648ee --- /dev/null +++ b/tests/test_cannbot_boundaries.py @@ -0,0 +1,370 @@ +"""Synthetic upstream processes exercise the actual CLI and raw-byte boundary.""" + +import hashlib +import json +import os +import shlex +import subprocess +import sys +import time +from pathlib import Path + +import pytest + +from inferrsi.apps.cannbot import project +from inferrsi.apps.cannbot.read_worker import _MAX_UPSTREAM + +REPO = Path(__file__).resolve().parents[1] +REVISION = "ab" * 20 + + +def cli(*args, cwd=None, timeout=12): + return subprocess.run( + [sys.executable, "-m", "inferrsi", *args], + cwd=cwd, capture_output=True, text=True, timeout=timeout, check=False, + ) + + +def discovery(): + return {"schema_version": "knowledge-discovery.v1", "cards": 1, + "index": {"built_repository_state": {"commit": REVISION}}} + + +def commit_revision(source): + subprocess.run( + ["git", "-C", str(source), "-c", "user.name=Synthetic Fixture", + "-c", "user.email=fixture@example.invalid", "-c", "commit.gpgsign=false", + "commit", "--allow-empty", "-qm", "synthetic revision"], check=True, + ) + return subprocess.check_output( + ["git", "-C", str(source), "rev-parse", "HEAD"], text=True, + ).strip() + + +@pytest.fixture +def upstream(tmp_path, monkeypatch): + home = tmp_path / "home" + home.mkdir() + monkeypatch.setenv("HOME", str(home)) + monkeypatch.setenv("USERPROFILE", str(home)) + monkeypatch.setenv("PYTHONPATH", str(REPO / "src")) + root = tmp_path / "project" + root.mkdir() + (root / ".git").mkdir() + monkeypatch.chdir(root) + source = tmp_path / "upstream" + subprocess.run(["git", "init", "-q", str(source)], check=True) + monkeypatch.setattr(sys.modules[__name__], "REVISION", commit_revision(source)) + (source / "knowledge/ops").mkdir(parents=True) + card = source / "knowledge/ops/card.md" + card.write_text("\n".join(f"synthetic line {i}" for i in range(401))) + script = source / ".agents/skills/knowledge-query/scripts/knowledge_query.py" + script.parent.mkdir(parents=True) + native = script.parent / "retrieval" + native.mkdir() + (native / "__init__.py").touch() + (native / "index.py").write_text( + "import hashlib\n" + "def load_contract(root):\n" + " return None, lambda text: ({}, text)\n" + "def card_fingerprint(metadata, body):\n" + " return hashlib.sha256(body.encode()).hexdigest()\n" + ) + script.write_text(f"import json\nprint(json.dumps({discovery()!r}))\n") + project.enable(upstream=source, python=Path(sys.executable), platforms=["a2"]) + return source, script, card + + +def search_payload(card): + return {"schema_version": "knowledge-search.v5", "index": discovery()["index"], + "results": [{"path": "ops/card", "title": "synthetic", "score": 1.0, + "platforms": ["a2"], + "card_sha256": hashlib.sha256(card.read_bytes()).hexdigest()}]} + + +def set_source(script, raw): + script.write_text(f"import sys\nsys.stdout.buffer.write({raw!r})\n") + + +@pytest.mark.parametrize("raw", [ + b'{"cards": 1, "cards": 2}', b'{"x": NaN}', b'{"x": Infinity}', + b'{"x": -Infinity}', b'{"x": 1e999}', b'[]', b'{"x": {"y": 1, "y": 2}}', + b'\xff', b'{"schema_version": "knowledge-discovery.v1", "cards": 1, "index": []}', +]) +def test_rejects_original_source_bytes(upstream, raw): + _, script, _ = upstream + set_source(script, raw) + assert project.describe()["state"] == "rejected" + + +@pytest.mark.parametrize("mutation", [ + {"results": {}}, {"results": [42]}, + {"results": [{"path": "ops/card", "score": "bad"}]}, + {"index": []}, +]) +def test_search_shape_is_rejected(upstream, mutation): + _, script, card = upstream + set_source(script, json.dumps({**search_payload(card), **mutation}).encode()) + with pytest.raises(project.ChannelFailure) as error: + project.search("query") + assert error.value.state == "rejected" + + +@pytest.mark.parametrize("args", [ + ("cannbot", "search", "tiling", "--limit", "1"), + ("find", "tiling", "--external-limit", "1", "--json"), +]) +def test_source_cap_precedes_card_reads(upstream, args): + _, script, card = upstream + payload = search_payload(card) + first = payload["results"][0] + # These extra rows are well-shaped, but their files do not exist. Reading + # either of them would reject the query instead of returning the first hit. + payload["results"].extend([ + {**first, "path": "ops/not-requested-a"}, + {**first, "path": "ops/not-requested-b"}, + ]) + script.write_text( + "import json, sys\n" + f"print(json.dumps({discovery()!r} if sys.argv[1] == 'discover' " + f"else {payload!r}))\n" + ) + result = cli(*args) + assert result.returncode == 0, result.stderr + response = json.loads(result.stdout) + if args[0] == "find": + response = response["external"][0] + assert response["state"] == "ok" + assert [hit["locator"] for hit in response["items"]] == ["ops/card"] + + +def test_unknown_schema_is_version_mismatch(upstream): + _, script, _ = upstream + set_source(script, json.dumps({**discovery(), "schema_version": "future"}).encode()) + assert project.describe()["state"] == "version_mismatch" + + +@pytest.mark.parametrize("pipe", ["stdout", "stderr"]) +def test_output_cap_stops_a_producer_before_it_finishes(upstream, pipe): + source, script, _ = upstream + marker = source / "finished" + script.write_text( + "import sys, time\nfrom pathlib import Path\n" + f"sys.{pipe}.buffer.write(b'x' * {_MAX_UPSTREAM + 1})\n" + f"sys.{pipe}.flush()\ntime.sleep(3)\n" + "Path('finished').touch()\n" + ) + started = time.monotonic() + assert project.describe(timeout=6)["state"] == "rejected" + assert time.monotonic() - started < 2 + assert not marker.exists() + + +def test_read_binds_all_pages_to_search_digest(upstream): + _, script, card = upstream + script.write_text( + "import json, sys\n" + f"print(json.dumps({discovery()!r} if sys.argv[1] == 'discover' " + f"else {search_payload(card)!r}))\n" + ) + result = cli("find", "synthetic", "--backend", "ascend", "--json") + assert result.returncode == 0, result.stderr + hit = json.loads(result.stdout)["external"][0]["items"][0] + opened = cli(*shlex.split(hit["open"])[1:]) + body = json.loads(opened.stdout) + assert body["revision"] == REVISION + assert body["card_sha256"] == hit["card_sha256"] + assert body["has_more"] + page = cli(*shlex.split(hit["open"])[1:], "--page", "2") + assert json.loads(page.stdout)["card_sha256"] == hit["card_sha256"] + assert json.loads(page.stdout)["revision"] == REVISION + card.write_text("changed") + changed = cli(*shlex.split(hit["open"])[1:], "--page", "2") + assert changed.returncode != 0 + assert "changed since the search" in changed.stderr + assert not changed.stdout + current = json.loads(cli("cannbot", "read", "ops/card").stdout) + assert current["card_sha256"] == hashlib.sha256(card.read_bytes()).hexdigest() + + +def test_read_refuses_path_escape(upstream): + source, _, _ = upstream + (source / "private.md").write_text("not knowledge") + result = cli("cannbot", "read", "../private") + assert result.returncode != 0 + assert "not knowledge" not in result.stdout + result.stderr + + +@pytest.mark.parametrize("page", [1, 2]) +def test_read_rejects_revision_drift_with_unchanged_card(upstream, page): + source, script, card = upstream + script.write_text( + "import json, sys\n" + f"print(json.dumps({discovery()!r} if sys.argv[1] == 'discover' " + f"else {search_payload(card)!r}))\n" + ) + found = json.loads(cli("find", "synthetic", "--json").stdout)["external"][0] + hit = found["items"][0] + assert f"--revision {found['revision']}" in hit["open"] + changed_revision = commit_revision(source) + assert changed_revision != found["revision"] + result = cli(*shlex.split(hit["open"])[1:], "--page", str(page)) + assert result.returncode != 0 + assert "revision changed since the search" in result.stderr + assert "synthetic line" not in result.stdout + result.stderr + current = project.read(hit["locator"], page=page) + assert current["revision"] == changed_revision + assert current["card_sha256"] == hit["card_sha256"] + + +def test_read_rejects_revision_change_during_read(upstream, monkeypatch, capsys): + from inferrsi.apps.cannbot import read_worker + + source, _, _ = upstream + original = read_worker._card_bytes + + def changing_card(root, locator): + raw = original(root, locator) + commit_revision(source) + return raw + + monkeypatch.setattr(read_worker, "_card_bytes", changing_card) + with pytest.raises(SystemExit): + read_worker.read(source, {"locator": "ops/card", "expected_revision": REVISION}) + result = json.loads(capsys.readouterr().out) + assert result["state"] == "version_mismatch" + assert "text" not in result + + +def test_read_uses_approved_checkout_not_inherited_git_directory(upstream, monkeypatch): + source, _, _ = upstream + monkeypatch.setenv("GIT_DIR", str(source / "nonexistent-git-directory")) + assert project.read("ops/card", expected_revision=REVISION)["revision"] == REVISION + + +@pytest.mark.parametrize("revision", ["", "HEAD", "abc", "A" * 40, "a" * 39, 42]) +def test_read_rejects_invalid_expected_revision_before_worker(monkeypatch, revision): + def unexpected(*args, **kwargs): + pytest.fail("invalid revision started a worker") + + monkeypatch.setattr(project, "_run", unexpected) + with pytest.raises(project.ChannelFailure, match="expected_revision"): + project.read("ops/card", expected_revision=revision) + + +def test_native_fingerprint_and_raw_byte_digest_are_distinct(upstream): + _, script, card = upstream + native = script.parent / "retrieval/index.py" + native.write_text(native.read_text().replace( + "hashlib.sha256(body.encode())", "hashlib.sha256(b'parsed:' + body.encode())" + )) + raw_digest = hashlib.sha256(card.read_bytes()).hexdigest() + native_digest = hashlib.sha256(b"parsed:" + card.read_bytes()).hexdigest() + payload = search_payload(card) + payload["results"][0]["card_sha256"] = native_digest + set_source(script, json.dumps(payload).encode()) + hit = project.search("query")["items"][0] + assert hit["source_card_sha256"] == native_digest + assert hit["card_sha256"] == raw_digest != native_digest + assert project.read(hit["locator"], expected_sha256=raw_digest)["card_sha256"] == raw_digest + card.write_text("different indexed content") + with pytest.raises(project.ChannelFailure) as error: + project.search("query") + assert error.value.state == "index_stale" + + +@pytest.mark.parametrize("backend", [[], ["--backend", "ascend"]]) +def test_outside_git_project_reports_not_enabled(tmp_path, monkeypatch, backend): + root = tmp_path.resolve() + if any((parent / ".git").exists() for parent in (root, *root.parents)): + pytest.skip("temporary directory is inside a Git project") + monkeypatch.setenv("PYTHONPATH", str(REPO / "src")) + result = cli("find", "tiling", *backend, "--json", cwd=tmp_path) + assert result.returncode == 0, result.stderr + payload = json.loads(result.stdout) + assert payload["items"] + assert payload["external"][0]["state"] == "not_enabled" + assert "Git project" in payload["external"][0]["fix"] + + +def test_platform_override_and_cuda_gate(upstream): + _, script, card = upstream + script.write_text( + "import json, sys\n" + "if sys.argv[1] == 'search':\n" + " assert sys.argv[sys.argv.index('--platform') + 1] == 'a3'\n" + f"print(json.dumps({discovery()!r} if sys.argv[1] == 'discover' " + f"else {search_payload(card)!r}))\n" + ) + result = cli("find", "synthetic", "--platform", "a3", "--json") + assert json.loads(result.stdout)["external"][0]["state"] == "ok" + script.write_text("raise RuntimeError('must not be called')\n") + for args in (("--backend", "cuda"), ("--no-external",)): + result = cli("find", "tiling", *args, "--json") + assert "external" not in json.loads(result.stdout) + + +@pytest.mark.skipif(os.name != "posix", reason="POSIX process-group cleanup") +@pytest.mark.parametrize("phase", ["discover", "search"]) +def test_cli_deadline_kills_upstream_descendants(upstream, phase): + source, script, _ = upstream + script.write_text( + "import json, os, subprocess, sys, time\nfrom pathlib import Path\n" + f"if sys.argv[1] == {phase!r}:\n" + " child = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(30)'])\n" + " Path('pids.json').write_text(json.dumps([os.getpid(), child.pid]))\n" + " time.sleep(30)\n" + f"print(json.dumps({discovery()!r}))\n" + ) + started = time.monotonic() + result = cli("find", "tiling", "--external-timeout", "0.8", "--json", timeout=5) + assert result.returncode == 0, result.stderr + assert time.monotonic() - started < 4 + entry = json.loads(result.stdout)["external"][0] + assert entry["state"] == "timeout" + assert entry["elapsed_ms"] >= 700 + assert "items" not in entry + pids = json.loads((source / "pids.json").read_text()) + for pid in pids: + # Linux may briefly retain a reparented zombie; it cannot execute work. + state = subprocess.run(["ps", "-o", "stat=", "-p", str(pid)], + capture_output=True, text=True, check=False).stdout.strip() + assert not state or state.startswith("Z"), (pid, state) + + +def test_cli_larger_budget_reaches_subprocess(upstream): + _, script, card = upstream + script.write_text( + "import json, sys, time\ntime.sleep(0.4)\n" + f"print(json.dumps({discovery()!r} if sys.argv[1] == 'discover' " + f"else {search_payload(card)!r}))\n" + ) + short = cli("find", "tiling", "--external-timeout", "0.6", "--json") + assert json.loads(short.stdout)["external"][0]["state"] == "timeout" + long = cli("find", "tiling", "--external-timeout", "2", "--json") + assert json.loads(long.stdout)["external"][0]["state"] == "ok" + + +@pytest.mark.parametrize("count", [1, 3]) +def test_nonreturning_adapter_cannot_hold_cli_exit(count): + code = f''' +import json, threading, time +from inferrsi.knowledge.channels import ChannelRegistry, search_channels +class Hung: + name = "hung" + backend = "ascend" + def describe(self, *, request): + threading.Event().wait() +started = time.monotonic() +results = search_channels(ChannelRegistry([Hung() for _ in range({count})]), + "q", backend="ascend", timeout=0.1) +print(json.dumps({{"elapsed": time.monotonic() - started, + "states": [r.status.state for r in results], + "times": [r.elapsed_ms for r in results]}})) +''' + result = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, + timeout=3, check=True) + data = json.loads(result.stdout) + assert data["states"] == ["timeout"] * count + assert data["elapsed"] < 0.25 + assert all(t >= 80 for t in data["times"]) diff --git a/tests/test_cannbot_channel_acceptance.py b/tests/test_cannbot_channel_acceptance.py new file mode 100644 index 00000000..9f46e6d5 --- /dev/null +++ b/tests/test_cannbot_channel_acceptance.py @@ -0,0 +1,156 @@ +"""Before/after: does the external channel actually widen what `find` reaches. + +This file is the acceptance measurement for the cannbot channel. It runs the +real CLI twice per query -- once gated off, once gated on -- and reports the +counts. The upstream half needs an approved checkout and a built index, so it +is skipped rather than faked when either is absent: a fabricated number here +would be worse than no number. +""" + +import functools +import json +import subprocess +import sys +from pathlib import Path + +import pytest + +PROJECT = Path(__file__).resolve().parents[1] +QUERIES = ( + "AscendC tiling 参数怎么计算", + "CeilDivision 向上取整", + "matmul 分块 性能", + "算子 精度 调试 溢出", + "ACLGraph 图模式 捕获", + "KV cache 显存 布局", +) + + +def _run(*args): + argv = [sys.executable, "-m", "inferrsi", *args] + if args[0] != "cannbot": # `cannbot` subcommands print JSON already + argv.append("--json") + result = subprocess.run(argv, capture_output=True, text=True, cwd=PROJECT) + if result.returncode: + return None + return json.loads(result.stdout) + + +@functools.lru_cache(maxsize=1) +def _approved(): + info = _run("cannbot", "describe") + return bool(info) and info.get("state") == "ok" + + +def test_gate_off_matches_the_pre_channel_behaviour(): + """`--no-external` must reproduce the output callers already relied on. + + An unflagged run is *supposed* to differ: it adds the gate explanation. + The invariant is only about `--no-external`, and it must be exact. + """ + from inferrsi.apps.cli import _channels + from inferrsi.knowledge.knowledge_find import find, load_corpus + + corpus = load_corpus() + pre_channel = find("AscendC tiling", corpus, limit=5) + gated = _run("find", "AscendC tiling", "--no-external") + assert gated is not None + assert "external" not in gated + # Same keys, same counts, same order as the function before channels existed. + assert sorted(gated) == sorted(pre_channel) + assert [i["id"] for i in gated["items"]] == [i["id"] for i in pre_channel["items"]] + assert _channels() is not None # the registry exists; the flag is what skips it + + +def test_undeclared_backend_reports_the_gate(): + """Only an undeclared backend may skip a channel without a grant. + + Once a grant records `backend: ascend`, the default path is a declaration + and must search. The gate explanation is for the case where neither an + explicit flag nor an approved grant says what platform this is. + """ + result = _run("find", "AscendC tiling") + assert result is not None + from inferrsi.apps.cli import _channels + + registry = _channels() + entries = result.get("external", []) + if registry.declared_backend is None: + assert all(entry["state"] != "ok" for entry in entries) + assert any("fix" in entry for entry in entries) + else: + assert any(entry["state"] == "ok" for entry in entries), ( + "an approved grant declares the backend, so the default path must search" + ) + + +@pytest.mark.skipif(not _approved(), reason="no approved cannbot checkout with a built index") +def test_local_corpus_is_unchanged_by_the_channel(): + """The channel adds a column; it never re-ranks or trims the local list.""" + for query in QUERIES: + before = _run("find", query, "--no-external") + after = _run("find", query, "--backend", "ascend") + assert before["matched"] == after["matched"], query + assert [item["id"] for item in before["items"]] == [ + item["id"] for item in after["items"] + ], query + + +@pytest.mark.skipif(not _approved(), reason="no approved cannbot checkout with a built index") +def test_channel_returns_locators_with_a_pin(): + result = _run("find", QUERIES[1], "--backend", "ascend") + entry = next(item for item in result["external"] if item["channel"] == "cannbot-knowledge") + assert entry["state"] == "ok" + assert len(entry["revision"]) == 40 + assert entry["score_scale"].startswith("knowledge-search") + assert entry["items"], "the upstream source has cards for this query" + for hit in entry["items"]: + assert hit["locator"] and "/" in hit["locator"] + assert hit["card_sha256"] + assert hit["open"].startswith("inferrsi cannbot read ") + + +@pytest.mark.skipif(not _approved(), reason="no approved cannbot checkout with a built index") +def test_external_hits_never_enter_items(): + for query in QUERIES: + result = _run("find", query, "--backend", "ascend") + local_ids = {item["id"] for item in result["items"]} + for entry in result["external"]: + for hit in entry.get("items", []): + assert hit["locator"] not in local_ids + + +@pytest.mark.skipif(not _approved(), reason="no approved cannbot checkout with a built index") +def test_every_query_reaches_more_than_the_local_corpus(): + """The point of the channel: each query gains upstream coverage.""" + rows = [] + for query in QUERIES: + before = _run("find", query, "--no-external") + after = _run("find", query, "--backend", "ascend") + external = sum( + entry.get("count", 0) for entry in after["external"] if entry["state"] == "ok" + ) + rows.append((query, before["matched"], external)) + report = "\n".join( + f"{query:28} local={local:>4} external={external:>3}" for query, local, external in rows + ) + print("\nfind coverage before/after:\n" + report) + assert all(external > 0 for _, _, external in rows), report + assert any(before == 0 for _, before, _ in rows), ( + "at least one Ascend query should be empty locally and answered upstream" + ) + + +@pytest.mark.skipif(not _approved(), reason="no approved cannbot checkout with a built index") +def test_read_returns_one_pinned_card(): + result = _run("find", "CeilDivision", "--backend", "ascend") + entry = next(item for item in result["external"] if item["channel"] == "cannbot-knowledge") + hit = entry["items"][0] + locator = hit["locator"] + card = _run("cannbot", "read", locator, "--sha256", hit["card_sha256"], + "--revision", entry["revision"]) + assert card["card_sha256"] == hit["card_sha256"] + assert card["revision"] == entry["revision"] + assert card["state"] == "ok" + assert card["locator"] == locator + assert card["text"].strip() diff --git a/tests/test_knowledge_channels.py b/tests/test_knowledge_channels.py new file mode 100644 index 00000000..f039b85f --- /dev/null +++ b/tests/test_knowledge_channels.py @@ -0,0 +1,254 @@ +"""External channels: gating, per-channel states, and no mixing into `items`.""" + +import pytest + +from inferrsi.knowledge.channels import ( + BACKEND_UNKNOWN, + DEFAULT_LIMITS, + NOT_ENABLED, + OK, + TIMEOUT, + UNREACHABLE, + ChannelHit, + ChannelRegistry, + ChannelResult, + ChannelStatus, + explain_gate, + search_channels, +) +from inferrsi.knowledge.knowledge_find import Corpus, Document, find + + +class FakeChannel: + """One channel with scripted behaviour, so every state is reachable.""" + + def __init__(self, *, name="fake", backend="ascend", status=None, items=(), error=None, + delay_state=None): + self.name = name + self.backend = backend + self._status = status or ChannelStatus(OK, revision="deadbeef" * 5) + self._items = tuple(items) + self._error = error + self._delay_state = delay_state + self.searched = 0 + self.platform_seen = None + self.limit_seen = None + + def describe(self, *, request): + if self._error: + raise RuntimeError(self._error) + return self._status + + def search(self, query, *, platform, limit, request): + self.searched += 1 + self.platform_seen = platform + self.limit_seen = limit + if self._delay_state: + raise TimeoutError() + return ChannelResult( + name=self.name, status=ChannelStatus(OK, revision="deadbeef" * 5), + items=self._items, elapsed_ms=12, score_scale="fake/v1", + read_prefix="fake read", + ) + + def read(self, locator): + return locator + + +def _hit(locator="ops/x/card", score=1.5): + return ChannelHit( + locator=locator, title="t", score=score, score_scale="fake/v1", + card_sha256="ab" * 32, + ) + + +@pytest.fixture(scope="module") +def corpus(): + return Corpus([ + Document( + identity="ascendc-tiling", kind="skill", state="validated", path="a/SKILL.md", + title="ascendc tiling design", summary="tiling", qualified="checkout:ascendc-tiling", + backend="ascend", source_location="checkout", + fields={"title": "ascendc tiling design", "summary": "tiling param", + "tags": "", "findings": "", "applicability": "", "body": "tiling"}, + ), + ]) + + +def test_registry_without_channels_leaves_result_untouched(corpus): + plain = find("tiling", corpus, limit=3) + gated = find("tiling", corpus, limit=3, registry=ChannelRegistry([]), backend="ascend") + assert plain == gated + assert "external" not in gated + + +def test_undeclared_backend_does_not_search(corpus): + channel = FakeChannel(items=[_hit()]) + result = find("tiling", corpus, backend=None, registry=ChannelRegistry([channel])) + assert channel.searched == 0 + assert result["items"] + assert result["external"][0]["state"] == BACKEND_UNKNOWN + assert "fix" in result["external"][0] + + +def test_ascend_backend_searches_even_when_local_matches(corpus): + channel = FakeChannel(items=[_hit()]) + result = find("tiling", corpus, backend="ascend", registry=ChannelRegistry([channel])) + assert result["matched"] >= 1 # local still hits + assert channel.searched == 1 # and the channel still ran + assert result["external"][0]["count"] == 1 + + +def test_other_backend_skips_ascend_channel(corpus): + channel = FakeChannel(items=[_hit()]) + result = find("tiling", corpus, backend="cuda", registry=ChannelRegistry([channel])) + assert channel.searched == 0 + assert "external" not in result + + +def test_external_hits_never_enter_items(corpus): + channel = FakeChannel(items=[_hit("ops/only/external")]) + result = find("tiling", corpus, backend="ascend", registry=ChannelRegistry([channel])) + assert all(item["id"] != "ops/only/external" for item in result["items"]) + assert result["external"][0]["items"][0]["locator"] == "ops/only/external" + + +def test_hit_carries_score_scale_and_sha(corpus): + channel = FakeChannel(items=[_hit()]) + result = find("tiling", corpus, backend="ascend", registry=ChannelRegistry([channel])) + hit = result["external"][0]["items"][0] + assert hit["score_scale"] == "fake/v1" + assert hit["card_sha256"] == "ab" * 32 + assert hit["open"] == ( + "fake read ops/x/card --sha256 " + "ab" * 32 + " --revision " + "deadbeef" * 5 + ) + + +def test_failure_is_a_state_not_empty_list(corpus): + channel = FakeChannel(status=ChannelStatus(NOT_ENABLED, detail="no grant", + fix="inferrsi cannbot enable")) + result = find("tiling", corpus, backend="ascend", registry=ChannelRegistry([channel])) + entry = result["external"][0] + assert entry["state"] == NOT_ENABLED + assert entry["fix"] == "inferrsi cannbot enable" + assert channel.searched == 0 + + +def test_timeout_is_reported_with_its_own_state(corpus): + channel = FakeChannel(delay_state=True) + results = search_channels(ChannelRegistry([channel]), "tiling", backend="ascend", timeout=1) + assert results[0].status.state == TIMEOUT + assert results[0].items == () + + +def test_broken_describe_is_unreachable(): + channel = FakeChannel(error="boom") + results = search_channels(ChannelRegistry([channel]), "q", backend="ascend") + assert results[0].status.state == UNREACHABLE + assert "boom" in results[0].status.detail + + +def test_one_channel_failure_does_not_hide_another(): + good = FakeChannel(name="good", items=[_hit()]) + bad = FakeChannel(name="bad", error="down") + results = search_channels( + ChannelRegistry([good, bad]), "q", backend="ascend", timeout=2, + ) + by_name = {item.name: item for item in results} + assert by_name["good"].items + assert by_name["bad"].status.state == UNREACHABLE + + +def test_default_limits_match_the_design(): + assert DEFAULT_LIMITS["cannbot-knowledge"] == 100 + assert DEFAULT_LIMITS["mindie-agent"] == 5 + + +def test_explicit_limit_overrides_per_channel_default(): + channel = FakeChannel() + search_channels(ChannelRegistry([channel]), "q", backend="ascend", limit=3) + assert channel.limit_seen == 3 + + +@pytest.mark.parametrize("name,limit,expected", [ + ("fake", 1, 1), ("cannbot-knowledge", None, 100), ("mindie-agent", None, 5), +]) +def test_public_cap_holds_when_adapter_ignores_it(corpus, name, limit, expected): + hits = [_hit(f"ops/x/card-{i}") for i in range(expected + 2)] + channel = FakeChannel(name=name, items=hits) + local = find("tiling", corpus) + result = find( + "tiling", corpus, backend="ascend", registry=ChannelRegistry([channel]), + external_limit=limit, + ) + assert result["items"] == local["items"] + entry = result["external"][0] + assert entry["state"] == OK + assert entry["count"] == expected + assert [hit["locator"] for hit in entry["items"]] == [ + hit.locator for hit in hits[:expected] + ] + + +def test_each_channel_gets_its_own_default_limit(): + cannbot = FakeChannel(name="cannbot-knowledge") + mindie = FakeChannel(name="mindie-agent") + search_channels(ChannelRegistry([cannbot, mindie]), "q", backend="ascend") + assert cannbot.limit_seen == 100 + assert mindie.limit_seen == 5 + + +def test_platform_is_passed_through(): + channel = FakeChannel() + search_channels(ChannelRegistry([channel]), "q", backend="ascend", platform="a3") + assert channel.platform_seen == "a3" + + +def test_not_enabled_hint_beats_backend_unknown(): + channel = FakeChannel(backend=None) + channel.hint = ChannelStatus(NOT_ENABLED, detail="no grant", fix="enable it") + gate = explain_gate(ChannelRegistry([channel]), None) + assert gate[0]["state"] == NOT_ENABLED + assert gate[0]["fix"] == "enable it" + + +def test_rejects_non_positive_timeout(): + with pytest.raises(ValueError): + search_channels(ChannelRegistry([FakeChannel()]), "q", backend="ascend", timeout=0) + + +def test_registry_declared_backend_is_what_the_task_asked_for(): + """A channel's own backend selects it; it never declares the task. + + Reading `Channel.backend` as the task backend made an undeclared task + search anyway. The registry carries the declaration separately so the two + facts stay distinguishable. + """ + channel = FakeChannel(backend="ascend", items=[_hit()]) + undeclared = ChannelRegistry([channel]) + assert undeclared.for_backend(undeclared.declared_backend) == [] + declared = ChannelRegistry([channel], declared_backend="ascend") + assert declared.for_backend(declared.declared_backend) == [channel] + + +def test_cleanup_failure_is_visible_and_does_not_hide_other_channels(): + cleaned = [] + + class FailedCleanup(FakeChannel): + def describe(self, *, request): + def fail(_): + raise OSError("synthetic cleanup failure") + + request.start(object, fail) + request.start(object, lambda _: cleaned.append(True)) + return self._status + + results = search_channels( + ChannelRegistry([FailedCleanup(name="bad"), FakeChannel(name="good", items=[_hit()])]), + "q", backend="ascend", + ) + assert results[0].status.state == "rejected" + assert "cleanup failed" in results[0].status.detail + assert cleaned == [True] + assert results[1].status.state == "ok" + assert results[1].items