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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions docs/apps-module-migrations.json
Original file line number Diff line number Diff line change
Expand Up @@ -333,6 +333,7 @@
],
"consumers": [
"src/inferrsi/apps/cli/__init__.py",
"src/inferrsi/apps/integrations/cannbot/round_knowledge.py",
"tests/check_installed.py",
"tests/test_apps_module_migrations.py"
],
Expand Down Expand Up @@ -360,10 +361,14 @@
"disable"
],
"consumers": [
"src/inferrsi/apps/cli/arguments.py",
"src/inferrsi/apps/integrations/cannbot/__init__.py",
"src/inferrsi/apps/integrations/cannbot/round_knowledge.py",
"tests/check_installed.py",
"tests/test_apps_module_migrations.py",
"tests/test_cannbot_boundaries.py"
"tests/test_cannbot_boundaries.py",
"tests/test_optimization_session.py",
"tests/test_project_optimization.py"
]
},
{
Expand All @@ -378,9 +383,11 @@
],
"consumers": [
"src/inferrsi/apps/integrations/cannbot/project.py",
"src/inferrsi/apps/integrations/cannbot/round_knowledge.py",
"tests/check_installed.py",
"tests/test_apps_module_migrations.py",
"tests/test_cannbot_boundaries.py"
"tests/test_cannbot_boundaries.py",
"tests/test_project_optimization.py"
]
}
]
57 changes: 54 additions & 3 deletions docs/examples/dashboard-profile-review.html
Original file line number Diff line number Diff line change
Expand Up @@ -875,6 +875,47 @@ <h2 class="panel-heading" aria-labelledby="chart-title"></h2>
}
function item(box,title){const a=el('article',null,'rd-item');a.append(el('h4',title));box.append(a);return a;}
function stage(grid,index,en,zh){const section=el('section',null,'rd-stage');section.dataset.rdStage=String(index);const h=el('h3');h.append(el('span',String(index).padStart(2,'0'),'rd-number'),document.createTextNode(' '+tr(en,zh)));section.append(h);grid.append(section);return section;}
function managedRetrieval(stage, record){
const box=item(stage,tr('Round knowledge query','本轮知识查询'));
field(box,tr('Query','查询'),record.query);
const local=item(box,tr('Local knowledge','本地知识'));
field(local,tr('Returned items','返回条目'),record.items.length);
for(const entry of record.items){
const card=item(local,entry.title||entry.ref);
field(card,tr('Reference','引用'),entry.ref);
field(card,tr('Delivery','交付'),entry.delivered?tr('Context prepared','已装配上下文'):tr('Context omitted','未装配上下文'));
}
const result=record.external;
if(!result)return;
const external=item(box,'CANNBot · '+result.platform);
field(external,tr('Channel state','通道状态'),result.state==='ok'&&result.count===0?tr('No hits','无命中'):result.state);
field(external,tr('Returned items','返回条目'),result.count);
if(result.count>result.items.length)p(external,tr('Some hits lack retainable identifiers.','部分命中缺少可留存的标识。'),'rd-note');
if(result.revision)field(external,tr('Source revision','来源版本'),result.revision);
if(result.score_scale)field(external,tr('Score scale','打分体系'),result.score_scale);
for(const hit of result.items){
const card=item(external,hit.locator),pages=result.reads.filter(r=>r.locator===hit.locator).map(r=>r.page);
field(card,tr('Search score','检索分数'),hit.score);
field(card,tr('Read receipts','读取凭据'),pages.length?tr('Pages ','页码 ')+[...new Set(pages)].join(', '):null);
detail(card,tr('Card identity','知识卡标识'),'managed:'+result.path+':'+hit.locator,b=>field(b,'SHA-256',hit.card_sha256));
}
}
function knowledgeUses(box,candidate,hasQueries){
const citations=candidate.knowledge_uses;
if(!citations||(!citations.length&&!hasQueries))return;
const name=tr('Agent-declared knowledge use','Agent 声明采用的知识');
if(!citations.length)field(box,name,null);
for(const [index,citation] of citations.entries()){
const source=citation.source==='local'?tr('Local','本地'):citation.source;
const origin=citation.retrieval_round?tr('Round ','第 ')+citation.retrieval_round+tr('',' 轮'):null;
const page=citation.page?tr('Page ','页码 ')+citation.page:null;
field(box,name,[source,citation.ref,origin,page].filter(Boolean).join(' · '));
if(citation.revision)detail(box,tr('Source identity','来源标识'),'citation:'+identity(candidate)+':'+index,b=>{
field(b,tr('Source revision','来源版本'),citation.revision);
if(citation.card_sha256)field(b,'SHA-256',citation.card_sha256);
});
}
}
function render(){
const root=document.getElementById('round-decisions');if(!root)return;
const focus=root.contains(document.activeElement)?document.activeElement.dataset.rdFocus:null;
Expand All @@ -884,7 +925,9 @@ <h2 class="panel-heading" aria-labelledby="chart-title"></h2>
p(root,tr('Retrieval results → Alternatives → Final selection → Execution results','检索结果 → 备选方案 → 最终选择 → 执行结果'),'rd-note');
const data=getData(),rows=data.candidates||[],story=data.story||{},knowledge=data.knowledge_trace||{};
const iterations=story.iterations||[],searches=knowledge.searches||[],captures=knowledge.retrievals||[];
const numbers=[...new Set([...rows.map(r=>r.round),...iterations.map(i=>i.round),...searches.map(s=>s.round)].filter(validRound))].sort((a,b)=>a-b);
const managed=data.managed_retrievals||[];
const pending=data.pending_candidate;
const numbers=[...new Set([...rows,...iterations,...searches,...managed,...(pending?[pending]:[])].map(r=>r.round).filter(validRound))].sort((a,b)=>a-b);
const choices=numbers.map(String);if(rows.some(r=>!validRound(r.round)))choices.push('unassigned');
if(!choices.length)choices.push('unassigned');
if(!choices.includes(selected))selected=choices[0];
Expand All @@ -902,7 +945,9 @@ <h2 class="panel-heading" aria-labelledby="chart-title"></h2>
const contextIds=new Set(roundIterations.flatMap(i=>i.context_ids||[]));
roundSearches.filter(s=>s.state==='recorded').forEach(s=>(s.context_ids||[]).forEach(id=>contextIds.add(id)));
captures.filter(c=>number!==null&&c.links?.some(l=>l.round===number)).forEach(c=>contextIds.add(c.context_id));
if(!contextIds.size)p(retrieved,tr('No retrieval snapshot linked to this round. This does not mean no search occurred.','本轮未关联检索快照,不代表没有发生检索。'),'rd-note');
const managedQueries=managed.filter(inRound);
for(const query of managedQueries)managedRetrieval(retrieved,query);
if(!contextIds.size&&!managedQueries.length)p(retrieved,tr('No retrieval snapshot linked to this round. This does not mean no search occurred.','本轮未关联检索快照,不代表没有发生检索。'),'rd-note');
for(const id of contextIds){
const c=captures.find(c=>c.context_id===id),box=item(retrieved,id);
if(!c||c.state!=='verified'){p(box,label(c?.state),'rd-warning');continue;}
Expand Down Expand Up @@ -996,12 +1041,18 @@ <h2 class="panel-heading" aria-labelledby="chart-title"></h2>
p(selection,tr('Choice and selection rationale not recorded.','选中方案及选择理由未记录。'),'rd-note');
for(const row of roundRows){const box=item(selection,row.candidate_id);p(box,tr('Registered candidate; registration alone is not selection evidence.','已登记候选;登记本身不证明选择依据。'),'rd-note');field(box,tr('Submitted hypothesis','提交的假设'),row.optimization?.hypothesis,true);}
}
if(!roundRows.length)p(results,tr('No candidate execution linked to this round.','本轮未关联候选执行记录。'),'rd-note');
if(pending&&inRound(pending)){
const box=item(results,pending.candidate_id);
p(box,tr('Awaiting assessment','等待评测结果'),'rd-note');
knowledgeUses(box,pending,managedQueries.length);
}else if(!roundRows.length)p(results,tr('No candidate execution linked to this round.','本轮未关联候选执行记录。'),'rd-note');
for(const row of roundRows){
const key=identity(row),box=item(results,[row.candidate_id,row.run_id||unknown()].join(' · '));
p(box,label(row.verdict),'rd-badge');field(box,tr('Quality','质量'),label(row.quality));
const metric=v=>Number.isFinite(v)?String(v)+' '+(row.metric_unit||''):'—';
field(box,tr('Baseline → candidate','基线 → 候选'),metric(row.baseline_median)+' → '+metric(row.candidate_median));
if(Number.isFinite(row.measured_score))field(box,tr('Measured score','实测成绩'),row.measured_score+' · '+row.metric_key);
knowledgeUses(box,row,managedQueries.length);
field(box,tr('Recorded improvement','记录的改进幅度'),Number.isFinite(row.improvement_pct)?row.improvement_pct+'%':null);
field(box,tr('Post-validation decision (record)','验证后决定(记录)'),label(row.decision));
const matches=rows.filter(r=>identity(r)===key);
Expand Down
11 changes: 7 additions & 4 deletions docs/external-channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,10 +198,12 @@ An external result is **not locally verified**. Cite it as
`cannbot-knowledge @ <revision>` and say so. It does not participate in a `PASS`
verdict.

When a receipt is added (not in this release), it will hold the locator, the
card's `card_sha256` and the index revision — never card text, never
`frontmatter`, never a `local_path`. A digest proves which card was cited without
redistributing it.
[Managed round retrieval](optimization-benchmarks.md#include-cannbot-in-the-round)
records CANNBot search metadata and pinned read receipts. A receipt identifies
the search, locator, index revision, card SHA-256 and requested page. The
authorized read returns text directly to the caller. The campaign retains
metadata only. Candidate attribution requires an explicit citation when
submitting a round.

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
Expand All @@ -213,6 +215,7 @@ conclusion.
| --- | --- |
| `cannbot enable / disable / describe / search / read` | implemented |
| `find` integration with gating, budgets, per-channel states | implemented |
| Managed benchmark and AB/BA round query, read and Dashboard attribution | 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 |
Expand Down
1 change: 1 addition & 0 deletions docs/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Effect classes used below:
| Inspect the package catalog | CLI `knowledge search` / `knowledge show`; catalog API | Read-only | Filtered inventory and existing catalog scripts. Uses the installed package's tier/repo/backend/scenario filters and IDs |
| Prepare model-aware engine research | CLI `knowledge research`; Python `research_knowledge` | Read-only | Independent model/framework/task/modality/mechanism queries over the same package catalog; source-grounded known profiles, deduplicated matches and explicit target annotations; no engine/hardware qualification |
| Enter an inference task or discover/read skills | CLI `skills enter` / `list` / `show` / `resource` / `reference` | Read-only | `enter` loads one primary owner's complete procedure before evidence search. `list`/ `show` inspect skill metadata and instructions. `resource`/`reference` resolve paths for your file reader. |
| Retrieve and cite external round knowledge | CLI `benchmarks session knowledge / knowledge-read`, AB/BA `campaign knowledge / knowledge-read` | Local evidence-writing | Requires an explicit `--cannbot-platform` at start and an approved project grant. Retains search and read metadata. Cite a delivered receipt with `round --knowledge-ref`. See [round retrieval](optimization-benchmarks.md#include-cannbot-in-the-round) |
| Collect selected knowledge | CLI `collect`; Python `KnowledgeReader.collect` | Read-only | Batch selection and budgeted assembly by query or exact IDs, with revisions and omissions. The only accepted explicit `--relevance-method` value is `find-lexical-v1` |
| Read exact material/resources | CLI `read` / `resource`; Python `KnowledgeReader.read` / `KnowledgeReader.resource` | Read-only | Returns the requested revision or an explicit unavailable/stale error; never substitutes newer bytes |
| Export legacy cited material | CLI `context` | Read-only | Cited package export for manual use with a coding agent; not a conversation store and not a full Collect equivalent |
Expand Down
37 changes: 37 additions & 0 deletions docs/optimization-benchmarks.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,43 @@ selection method and the external Agent configuration are caller-controlled
variables. A retained delivery establishes what was supplied. Model consumption
and access to material outside this session require their own observation.

### Include CANNBot in the round

Run from the project with an [approved CANNBot grant](external-channels.md).
Add `--cannbot-platform <platform>` at `benchmarks session start` or AB/BA
`campaign start` to freeze the external source and an explicit Ascend
platform. Omit the option for a local-only session. The paired
`benchmarks compare` conditions keep their existing behavior.

`knowledge` queries both sources for the next round. It returns the local
context and a separate `external` result, with its own ranking, channel state
and `reference.path`. A CANNBot timeout still returns the local result. The
external request and worker cleanup use the remaining search budget before the
final reserve. Use task keywords and keep private details out.
InferRSI applies its standard evidence redaction to the combined query before
searching and retaining it. Use a locator from this round's external result:

```bash
inferrsi benchmarks session knowledge-read --session <session-dir> \
--search-ref <external.reference.path> --locator <card-locator> --page 1
```

The read verifies the revision and digest recorded by the search. Card text
returns to the authorized CLI caller. The session retains only the source,
locator, revision, digest, page and search reference. Read additional pages
with `--page`. Use the equivalent `campaign knowledge-read` command for AB/BA.

At candidate submission, repeat `--knowledge-ref` for each delivery you used.
Pass the read's `reference.path` for an external card page, or
`<local-reference.path>#<item-ref>` for a local item with delivered resources.
A local capture path alone cites the whole delivery. You can cite an earlier
delivery from the same session. Search result paths are ineligible for citation.

Open [Dashboard](dashboard.md) → **Round decisions** to see the queries and
channel states before submitting a candidate. Completed attempts show the
agent's explicit citations alongside the candidate ID, verdict and measured
score. A search hit or read receipt alone does not record a citation.

## Submit a round and use its feedback

```bash
Expand Down
35 changes: 21 additions & 14 deletions src/inferrsi/apps/cli/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,25 @@ def _print(value: object) -> None:
print(json.dumps(value, ensure_ascii=False, indent=2, allow_nan=False))


def _optimization_session(args, *, task_source=None):
from ...harness.optimization_session import session_command

settings = None
provider = None
if getattr(args, "cannbot_platform", None):
settings = {"channel": "cannbot-knowledge", "backend": "ascend",
"platform": args.cannbot_platform}
if args.session_action in ("knowledge", "knowledge-read"):
from ..integrations.cannbot.round_knowledge import CannbotRoundKnowledge

provider = CannbotRoundKnowledge()
return session_command(
args, task_source=task_source, retain_context=capture_context,
knowledge_reader=KnowledgeReader() if args.session_action == "knowledge" else None,
external_knowledge=settings, external_provider=provider,
)


def _fixed_attempt_command(args) -> int:
from ...harness.errors import PublicError
from ..api import read_attempt_view
Expand Down Expand Up @@ -356,20 +375,14 @@ def main(argv: list[str] | None = None) -> int:
_print(compare_command(args))
return 0
if args.benchmark_action == "session":
from ...harness.optimization_session import session_command
from ..delivery import after_final

task_source = None
if args.session_action == "start":
from ...benchmark.registry import task_resources

task_source = Path(str(task_resources(args.task)))
result = session_command(
args, task_source=task_source,
retain_context=capture_context,
knowledge_reader=(KnowledgeReader()
if args.session_action == "knowledge" else None),
)
result = _optimization_session(args, task_source=task_source)
_print(after_final(args, result))
return 2 if result.get("state") == "blocked" else 0
if args.benchmark_action == "run":
Expand Down Expand Up @@ -628,15 +641,9 @@ def main(argv: list[str] | None = None) -> int:
_print({"context_directory": str(path), "reviewed_by_caller": False})
return 0
if getattr(args, "session_action", None) is not None:
from ...harness.optimization_session import session_command
from ..delivery import after_final

result = session_command(
args,
retain_context=capture_context,
knowledge_reader=(KnowledgeReader()
if args.session_action == "knowledge" else None),
)
result = _optimization_session(args)
_print(after_final(args, result))
if "exit_code" in result:
return result["exit_code"]
Expand Down
12 changes: 10 additions & 2 deletions src/inferrsi/apps/cli/arguments.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,13 @@ def _optimization_actions(stages, *, project=False):
start.add_argument("--condition", default="current-agent" if project else None,
required=not project)
start.add_argument("--knowledge", choices=("on", "off"), default="on")
from ..integrations.cannbot.project import PLATFORMS

start.add_argument("--cannbot-platform", choices=PLATFORMS,
help="Opt into CANNBot retrieval on the declared Ascend platform")
start.add_argument("--evaluation-prefix", default="", help="Quoted allocator argv prefix")
start.add_argument("--python", default=sys.executable)
actions = ("status", "diagnose", "round", "final", "recover", "knowledge")
actions = ("status", "diagnose", "round", "final", "recover", "knowledge", "knowledge-read")
if project:
actions += ("baseline", "refresh-references", "resume", "profile")
for name in actions:
Expand All @@ -120,7 +124,7 @@ def _optimization_actions(stages, *, project=False):
stage.add_argument("--hypothesis", required=True)
stage.add_argument("--strategy", help="Agent-declared optimization strategy")
stage.add_argument("--knowledge-ref", action="append",
help="Delivered context path cited by this round; repeatable")
help="Delivered path, path#item-ref, or CANNBot receipt; repeatable")
if name == "final":
stage.add_argument("--reason", help="Why the caller stopped an up-to-budget search")
if name in ("round", "final"):
Expand All @@ -146,6 +150,10 @@ def _optimization_actions(stages, *, project=False):
type=Path,
help="Investigation receipt proving interrupted resources were cleaned",
)
if name == "knowledge-read":
stage.add_argument("--search-ref", required=True, help="Recorded CANNBot search path")
stage.add_argument("--locator", required=True)
stage.add_argument("--page", type=int, default=1)
if name == "knowledge":
stage.add_argument("--query", required=True)
stage.add_argument(
Expand Down
Loading
Loading