broader-vids 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "broader-vids",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "description": "Curated YouTube and Bilibili recommendations for Claude Code",
5
5
  "author": {
6
6
  "name": "Broader Vids contributors"
@@ -4,6 +4,7 @@
4
4
  const fs = require("node:fs");
5
5
  const os = require("node:os");
6
6
  const path = require("node:path");
7
+ const { pathToFileURL } = require("node:url");
7
8
  const { createHash, randomUUID } = require("node:crypto");
8
9
  const {
9
10
  withRuntimeUse,
@@ -132,23 +133,233 @@ function commandIndex(args) {
132
133
  function validateSetupArguments(args, index) {
133
134
  for (let item = index + 1; item < args.length; item += 1) {
134
135
  const value = args[item];
135
- if (value === "--asr" || value === "--evidence") continue;
136
+ if (["--asr", "--evidence", "--check"].includes(value)) continue;
136
137
  if (value === "--data-dir") {
137
138
  item += 1;
138
139
  continue;
139
140
  }
140
141
  if (value.startsWith("--data-dir=")) continue;
141
142
  throw new Error(
142
- "Use setup with optional --evidence, --asr, and --data-dir PATH.",
143
+ "Use setup with optional --evidence, --asr, --check, and --data-dir PATH.",
143
144
  );
144
145
  }
145
146
  }
146
147
 
147
- function invoke(command, args) {
148
+ function runtimeEnvironment() {
149
+ return Object.fromEntries(
150
+ Object.entries(process.env).filter(
151
+ ([name]) =>
152
+ ![
153
+ "PYTHONHOME",
154
+ "PYTHONPATH",
155
+ "__PYVENV_LAUNCHER__",
156
+ "UV_INTERNAL__PYTHONHOME",
157
+ ].includes(name.toUpperCase()),
158
+ ),
159
+ );
160
+ }
161
+
162
+ function environmentArguments(
163
+ runtime,
164
+ platform = process.platform,
165
+ linked = false,
166
+ ) {
167
+ if (platform === "win32" && runtime.includes(";"))
168
+ throw new Error(
169
+ "Python venv cannot use a Windows data path with a semicolon. Select a path without semicolons before setup.",
170
+ );
171
+ return platform === "win32"
172
+ ? [
173
+ "run",
174
+ "--no-project",
175
+ "--python",
176
+ ">=3.12",
177
+ "python",
178
+ "-m",
179
+ "venv",
180
+ "--without-pip",
181
+ linked ? "--symlinks" : "--copies",
182
+ runtime,
183
+ ]
184
+ : ["venv", "--allow-existing", "--python", ">=3.12", runtime];
185
+ }
186
+
187
+ function clearInterpreterEntries(runtime) {
188
+ for (const directory of [path.dirname(runtime), runtime]) {
189
+ try {
190
+ if (fs.lstatSync(directory).isSymbolicLink())
191
+ throw new Error(
192
+ "The managed runtime directory is a link. Setup stopped before removing interpreter entries.",
193
+ );
194
+ } catch (error) {
195
+ if (error.code !== "ENOENT") throw error;
196
+ }
197
+ }
198
+ if (!fs.existsSync(runtime)) return;
199
+ const config = fs
200
+ .readdirSync(runtime, { withFileTypes: true })
201
+ .find((entry) => entry.name.toLowerCase() === "pyvenv.cfg");
202
+ if (config?.isSymbolicLink())
203
+ throw new Error(
204
+ "The runtime configuration is a link. Setup left it unchanged.",
205
+ );
206
+ const scripts = path.join(runtime, "Scripts");
207
+ if (!fs.existsSync(scripts)) return;
208
+ const target = fs.realpathSync(scripts);
209
+ const relative = path.relative(fs.realpathSync(runtime), target);
210
+ if (relative.toLowerCase() !== "scripts")
211
+ throw new Error(
212
+ "The runtime Scripts directory resolves outside its managed location. Setup stopped before removing interpreter entries.",
213
+ );
214
+ for (const entry of fs.readdirSync(scripts, { withFileTypes: true })) {
215
+ if (
216
+ !entry.isDirectory() &&
217
+ /^(?:python[\dw]*\.(?:exe|dll)|vcruntime\d+(?:_\d+)?\.dll)$/i.test(
218
+ entry.name,
219
+ )
220
+ )
221
+ fs.unlinkSync(path.join(scripts, entry.name));
222
+ }
223
+ }
224
+
225
+ function checkRuntime(runtime, executable) {
226
+ const report = {
227
+ version: 1,
228
+ runtime,
229
+ executable,
230
+ creation_backend: process.platform === "win32" ? "stdlib-venv" : "uv-venv",
231
+ executable_linked: false,
232
+ status: "unverified",
233
+ reason: "",
234
+ };
235
+ let expectedIdentity;
236
+ try {
237
+ report.executable_linked = fs.lstatSync(executable).isSymbolicLink();
238
+ fs.statSync(path.join(runtime, "pyvenv.cfg"));
239
+ const entry = fs.statSync(runtime, { bigint: true });
240
+ expectedIdentity = [entry.dev.toString(), entry.ino.toString()];
241
+ } catch (error) {
242
+ if (error.code === "ENOENT")
243
+ return {
244
+ ...report,
245
+ status: "missing",
246
+ reason: "The interpreter or pyvenv.cfg is missing.",
247
+ };
248
+ return {
249
+ ...report,
250
+ status: "unusable",
251
+ reason: `The host cannot inspect the selected runtime (${error.code}). Request access to this same directory.`,
252
+ };
253
+ }
254
+ const result = spawnSync(
255
+ executable,
256
+ [
257
+ "-I",
258
+ "-B",
259
+ "-c",
260
+ [
261
+ "import json,sys,pathlib,os",
262
+ 'result={"prefix":sys.prefix,"base_prefix":sys.base_prefix,"interpreter_executable":sys.executable,"python_version":list(sys.version_info[:2])}',
263
+ "environment=pathlib.Path(sys.executable).parent.parent",
264
+ "try:",
265
+ ' environment.joinpath("pyvenv.cfg").read_bytes()',
266
+ ' result["configuration_readable"]=True',
267
+ " entry=os.stat(sys.prefix)",
268
+ ' result["root_identity"]=[str(entry.st_dev & 0xffffffff if os.name=="nt" else entry.st_dev),str(entry.st_ino)]',
269
+ ' result["environment_matches_executable"]=os.path.samestat(entry,os.stat(environment))',
270
+ ' result["isolated"]=os.path.normcase(os.path.abspath(sys.prefix))!=os.path.normcase(os.path.abspath(sys.base_prefix))',
271
+ "except OSError as error:",
272
+ ' result.setdefault("configuration_readable",False)',
273
+ ' key="identity_error" if result["configuration_readable"] else "configuration_error"',
274
+ ' result[key]={"message":str(error),"errno":error.errno,"winerror":getattr(error,"winerror",None)}',
275
+ "print(json.dumps(result))",
276
+ ].join("\n"),
277
+ ],
278
+ {
279
+ encoding: "utf8",
280
+ timeout: 15000,
281
+ windowsHide: true,
282
+ env: runtimeEnvironment(),
283
+ },
284
+ );
285
+ if (result.error || result.status !== 0)
286
+ return {
287
+ ...report,
288
+ status: "unusable",
289
+ reason:
290
+ result.error?.code ||
291
+ result.stderr?.trim().slice(0, 1500) ||
292
+ "The interpreter did not complete its check.",
293
+ };
294
+ try {
295
+ const value = JSON.parse(result.stdout);
296
+ const version = value.python_version;
297
+ Object.assign(report, {
298
+ prefix: value.prefix,
299
+ base_prefix: value.base_prefix,
300
+ python_version: version,
301
+ interpreter_executable: value.interpreter_executable,
302
+ environment_matches_executable: value.environment_matches_executable,
303
+ isolated: value.isolated,
304
+ root_identity: value.root_identity,
305
+ expected_identity: expectedIdentity,
306
+ identity_error: value.identity_error,
307
+ configuration_readable: value.configuration_readable,
308
+ configuration_error: value.configuration_error,
309
+ });
310
+ if (value.configuration_readable === false)
311
+ return {
312
+ ...report,
313
+ status: "unusable",
314
+ reason:
315
+ "The Python process cannot read its own pyvenv.cfg in this host context. Setup stopped before dependency installation.",
316
+ };
317
+ if (
318
+ value.environment_matches_executable !== true ||
319
+ value.isolated !== true ||
320
+ !Array.isArray(value.root_identity) ||
321
+ value.root_identity.length !== 2 ||
322
+ value.root_identity.some(
323
+ (part, index) => part !== expectedIdentity[index],
324
+ )
325
+ )
326
+ return {
327
+ ...report,
328
+ status: "unusable",
329
+ reason:
330
+ "The interpreter prefix does not identify the selected virtual environment.",
331
+ };
332
+ if (
333
+ !Array.isArray(version) ||
334
+ version.length !== 2 ||
335
+ !version.every(Number.isInteger) ||
336
+ version[0] !== 3 ||
337
+ version[1] < 12
338
+ )
339
+ return {
340
+ ...report,
341
+ status: "unusable",
342
+ reason: "The runtime requires Python 3.12 or later.",
343
+ };
344
+ return {
345
+ ...report,
346
+ status: "ready",
347
+ reason: "The selected Python environment is isolated.",
348
+ };
349
+ } catch {
350
+ return {
351
+ ...report,
352
+ status: "unverified",
353
+ reason: "The interpreter returned an invalid identity report.",
354
+ };
355
+ }
356
+ }
357
+
358
+ function invoke(command, args, env = process.env) {
148
359
  const result = spawnSync(command, args, {
149
360
  stdio: "inherit",
150
361
  shell: false,
151
- env: { ...process.env, BROADER_VIDS_LAUNCHER: __filename },
362
+ env: { ...env, BROADER_VIDS_LAUNCHER: __filename },
152
363
  });
153
364
  if (result.error)
154
365
  throw new Error(
@@ -184,6 +395,27 @@ function cacheWheel(source, root) {
184
395
  return destination;
185
396
  }
186
397
 
398
+ function withWheelSource(wheel, action) {
399
+ const unsafe = (value) => /[#%?]/.test(value);
400
+ if (!unsafe(wheel)) return action(pathToFileURL(wheel).href);
401
+ const temporaryRoot = os.tmpdir();
402
+ if (unsafe(temporaryRoot))
403
+ throw new Error(
404
+ "UV cannot install this wheel from the selected paths. Set TEMP and TMP to a directory without #, %, or ?, then repeat setup.",
405
+ );
406
+ const directory = fs.mkdtempSync(
407
+ path.join(temporaryRoot, "broader-vids-wheel-"),
408
+ );
409
+ const temporary = path.join(directory, path.basename(wheel));
410
+ try {
411
+ fs.copyFileSync(wheel, temporary);
412
+ return action(pathToFileURL(temporary).href);
413
+ } finally {
414
+ if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
415
+ fs.rmdirSync(directory);
416
+ }
417
+ }
418
+
187
419
  function bundledWheel(packageRoot, version) {
188
420
  const prefix = `broader_vids-${version.replace("-alpha.", "a")}-`;
189
421
  const folder = path.join(packageRoot, "python");
@@ -370,31 +602,65 @@ function main(args = process.argv.slice(2)) {
370
602
  }
371
603
  if (args[index] === "setup") {
372
604
  validateSetupArguments(args, index);
605
+ if (args.includes("--check")) {
606
+ const report = withRuntimeUse(root, () =>
607
+ checkRuntime(runtime, executable),
608
+ );
609
+ console.log(JSON.stringify({ data_directory: root, ...report }, null, 2));
610
+ if (report.status !== "ready") process.exitCode = 2;
611
+ return;
612
+ }
613
+ const creationArguments = environmentArguments(runtime);
373
614
  const sourceWheel = bundledWheel(packageRoot, manifest.version);
374
615
  const wheelRoot = path.dirname(sourceWheel);
375
616
  return withSetup(root, () => {
376
617
  require("./profile-data.cjs").ensureMarker(root);
377
618
  const receipt = path.join(runtime, "broader-vids-build.json");
378
619
  if (fs.existsSync(receipt)) fs.unlinkSync(receipt);
379
- if (!fs.existsSync(executable))
380
- invoke("uv", [
381
- "venv",
382
- "--allow-existing",
383
- "--python",
384
- ">=3.12",
385
- runtime,
386
- ]);
620
+ const environment = runtimeEnvironment();
621
+ let runtimeCheck = checkRuntime(runtime, executable);
622
+ if (runtimeCheck.status !== "ready") {
623
+ if (process.platform === "win32") clearInterpreterEntries(runtime);
624
+ invoke("uv", creationArguments, environment);
625
+ runtimeCheck = checkRuntime(runtime, executable);
626
+ if (runtimeCheck.status !== "ready" && process.platform === "win32") {
627
+ clearInterpreterEntries(runtime);
628
+ invoke(
629
+ "uv",
630
+ environmentArguments(runtime, "win32", true),
631
+ environment,
632
+ );
633
+ runtimeCheck = checkRuntime(runtime, executable);
634
+ runtimeCheck.link_fallback = runtimeCheck.executable_linked
635
+ ? "created"
636
+ : "unavailable";
637
+ }
638
+ if (runtimeCheck.status !== "ready") {
639
+ const error = new Error(
640
+ `The Python runtime is not an isolated environment. ${runtimeCheck.reason}`,
641
+ );
642
+ error.code = "RUNTIME_NOT_ISOLATED";
643
+ error.report = { data_directory: root, ...runtimeCheck };
644
+ throw error;
645
+ }
646
+ }
387
647
  const wheel = cacheWheel(sourceWheel, root);
388
- invoke("uv", [
389
- "pip",
390
- "install",
391
- "--python",
392
- executable,
393
- "--reinstall",
394
- "--no-index",
395
- "--no-deps",
396
- wheel,
397
- ]);
648
+ withWheelSource(wheel, (url) =>
649
+ invoke(
650
+ "uv",
651
+ [
652
+ "pip",
653
+ "install",
654
+ "--python",
655
+ executable,
656
+ "--reinstall",
657
+ "--no-index",
658
+ "--no-deps",
659
+ url,
660
+ ],
661
+ environment,
662
+ ),
663
+ );
398
664
  const extras = args.includes("--asr")
399
665
  ? ["evidence", "asr"]
400
666
  : args.includes("--evidence")
@@ -402,15 +668,19 @@ function main(args = process.argv.slice(2)) {
402
668
  : [];
403
669
  const groups = ["core", ...extras];
404
670
  for (const extra of groups) {
405
- invoke("uv", [
406
- "pip",
407
- "install",
408
- "--python",
409
- executable,
410
- "--require-hashes",
411
- "-r",
412
- path.join(wheelRoot, `${extra}-requirements.txt`),
413
- ]);
671
+ invoke(
672
+ "uv",
673
+ [
674
+ "pip",
675
+ "install",
676
+ "--python",
677
+ executable,
678
+ "--require-hashes",
679
+ "-r",
680
+ path.join(wheelRoot, `${extra}-requirements.txt`),
681
+ ],
682
+ environment,
683
+ );
414
684
  }
415
685
  recordRuntimeBuild(runtime, wheelDigest(wheel), packageRoot, groups);
416
686
  console.log(
@@ -492,19 +762,18 @@ function main(args = process.argv.slice(2)) {
492
762
  ...(selectedHost.explicit ? ["--host", host] : []),
493
763
  ...args.slice(index),
494
764
  ];
495
- return invoke(executable, [
496
- "-m",
497
- "broader_vids",
498
- "--data-dir",
499
- root,
500
- ...engineArgs,
501
- ]);
765
+ return invoke(
766
+ executable,
767
+ ["-m", "broader_vids", "--data-dir", root, ...engineArgs],
768
+ runtimeEnvironment(),
769
+ );
502
770
  });
503
771
  }
504
772
 
505
773
  module.exports = {
506
774
  defaultRoot,
507
775
  dataRoot,
776
+ environmentArguments,
508
777
  commandIndex,
509
778
  parseHost,
510
779
  cacheWheel,
@@ -531,6 +800,8 @@ if (require.main === module) {
531
800
  2,
532
801
  ),
533
802
  );
803
+ else if (error.code === "RUNTIME_NOT_ISOLATED")
804
+ console.log(JSON.stringify(error.report, null, 2));
534
805
  else if (error.code === "RUNTIME_BUILD_MISMATCH")
535
806
  console.log(
536
807
  JSON.stringify(
@@ -206,12 +206,13 @@ Preference import and export do not transfer usage history.
206
206
  | Area | Main files | Responsibility |
207
207
  | --- | --- | --- |
208
208
  | Discovery | `queries.py`, `languages.py`, `sources.py`, `state.py`, `service.py` | Build searches, check keyword scripts, parse results, and retain discovery progress |
209
- | Exploration | `domains.py`, `coverage.py`, `rotation.py`, `proposals.py`, `planning.py` | Select underused leaf topics, coordinate reservations, and plan queries |
209
+ | Exploration | `domains.py`, `coverage.py`, `allocation.py`, `rotation.py`, `proposals.py`, `planning.py` | Allocate per-platform topics by broad-root use, select branches, and plan queries |
210
210
  | Evidence | `service.py`, `media.py`, `downloader.py`, `captions.py`, `browser.py` | Resolve playable videos and collect bounded evidence |
211
211
  | Evidence workers | `preparation_worker.py`, `asr_worker.py` | Separate media preparation and optional transcription processes |
212
212
  | Assessment | `assessment.py`, `worker_instructions.txt`, `reports.py`, `retention.py` | Check model output, report evidence limits, and remove completed media |
213
213
  | Recommendations | `service.py`, `batch.py`, `parallel.py`, `timing.py` | Coordinate platform jobs, worker limits, and recovery |
214
214
  | Ranking | `engagement.py`, `metadata.py`, `originality.py`, `quality.py`, `ranking.py`, `diversity.py`, `personalization.py` | Screen candidates and select the final list |
215
+ | Interest alignment | `learning/alignment.py`, `learning/features.py`, `learning/scoped.py` | Map assessed labels to saved interests and build learning features |
215
216
  | Learning | `features.py`, `topic_labels.py`, `inference.py`, `scoped.py`, `depth.py`, `service.py` | Capture predictors, fit models, and calculate predictions |
216
217
  | Preference transfer | `learning/transfer.py`, `learning/posterior.py`, `learning/baseline.py`, `web/static/preferences.js` | Transfer learned parameters without video records |
217
218
  | Feedback | `feedback.py`, `calibration.py`, `evaluation.py`, `evidence.py`, `annotations.py` | Store judgments, reserve test videos, and record evidence corrections |
@@ -270,7 +271,7 @@ Frozen evaluation records retain the tested model identity.
270
271
  Preference transfer accepts format 4 with learning model version 8 and feature version 1.
271
272
  Manual creator rules transfer separately from learning parameters and replace the manual lists transactionally on import.
272
273
  The export omits account-specific blacklist copies and sign-in data.
273
- It includes a bounded exploration summary with at most 1,024 nodes and aggregate counts and round ages.
274
+ It includes aggregate coverage counters, including per-platform and broad-root use.
274
275
  It includes watched video IDs without titles, ratings, or recommendation records.
275
276
  Import adds their watched state without clearing local video states.
276
277
  It does not change SQLite schema 12.
package/docs/REFERENCE.md CHANGED
@@ -146,8 +146,8 @@ Repeat `--interest` for every subject you want to retain.
146
146
  It does not infer interests from your watch history.
147
147
  The starter preset command previews its changes by default.
148
148
  Add `--apply` to import the preset and create the import backup.
149
- The preset includes sanitized interests, parameters, and parameter uncertainty.
150
- It excludes watched IDs, individual history, topic coverage, and creator exclusions.
149
+ The preset includes interests, parameters, and parameter uncertainty from the supplied export.
150
+ It clears watched IDs, creator exclusions, and exploration progress.
151
151
 
152
152
  ## Export or import learned preferences
153
153
 
@@ -175,11 +175,17 @@ Import checks the scoring version, checksum, and parameter uncertainty.
175
175
  It rejects incompatible or invalid files before changing preferences.
176
176
 
177
177
  Format 4 uses learning model version 8 and feature version 1.
178
- It transfers interests, learned parameters and their uncertainty, watched video IDs, a bounded exploration summary, and manual creator exclusions.
178
+ It transfers interests, learned parameters and uncertainty, watched IDs, aggregate exploration coverage, and manual creator exclusions.
179
179
  Imports mark matching IDs as watched to prevent exact video repeats.
180
180
  Imports of other formats or model versions fail before they change preferences.
181
- The exploration summary contains at most 1,024 hierarchy nodes, aggregate counts, and relative round ages.
181
+ Preference file format 4 remains unchanged.
182
+
183
+ Use an updated plugin to read and write coverage summary version 2.
184
+ Coverage summary version 2 contains at most 1,024 hierarchy nodes and aggregate counts.
185
+ It includes overall, per-platform, and broad-root use counters.
182
186
  It contains no individual video history.
187
+ Imports accept version 1 summaries. They start new counters at zero and preserve old aggregate counts.
188
+ Merges use maximum counter values, so repeated imports do not add duplicate use.
183
189
  Files exclude titles, individual ratings, calibration examples, and recommendation history.
184
190
  They exclude tag rules, account-specific blacklist copies, account data, cookies, media, and dashboard settings.
185
191
  Manual creator rules use platform-specific stable IDs and names, with at most 10,000 rules per file.
@@ -419,6 +425,9 @@ uv run --no-sync broader-vids publish RUN_ID --allow-incomplete
419
425
 
420
426
  Use `--allow-incomplete` only when you want a partial list from the assessed subset.
421
427
  The report identifies that result as partial.
428
+ Manual publication uses the same content-alignment step as automatic publication.
429
+ It retains the round's saved model settings and remaining allowances.
430
+ If alignment cannot finish, the report shows unresolved mappings and uses exact matches.
422
431
 
423
432
  ## Review and rate videos
424
433
 
@@ -597,6 +606,9 @@ Closing the dashboard server cancels a sign-in that has not reached activation.
597
606
  Select Token usage in the dashboard to inspect a saved recommendation round.
598
607
  The report remains available before publication and after a pause or failure.
599
608
  It shows input tokens, output tokens, cached input, and each step's share of reported tokens.
609
+
610
+ Broad-interest alignment appears as its own model-usage stage.
611
+ The stage reports alignment calls separately from quality assessment.
600
612
  Reported tokens equal input plus output. Input totals include cached input.
601
613
  Local search, screening, evidence preparation, and scoring do not use model tokens.
602
614
  Quality assessment combines caption and frame input in the same model call.
@@ -909,6 +921,8 @@ codex plugin add broader-vids@broader-vids-local
909
921
 
910
922
  The command builds the Python wheel, packs and verifies the npm archive, builds the plugin ZIP and local marketplace, and writes `dist/release.json` and `dist/SHA256SUMS`.
911
923
  The generated local marketplace contains the installable plugin payload.
924
+ Use `dist/local-marketplace` to test unpublished source changes.
925
+ The repository-root marketplace uses npm, even when you add that folder locally.
912
926
  These commands install locally and do not publish anything.
913
927
 
914
928
  Open a new desktop or CLI conversation after installation.
@@ -1123,6 +1137,7 @@ From an unpacked package, install its external engine:
1123
1137
 
1124
1138
  ```powershell
1125
1139
  node bin/broader-vids.cjs setup --evidence
1140
+ node bin/broader-vids.cjs setup --check
1126
1141
  node bin/broader-vids.cjs doctor
1127
1142
  ```
1128
1143
 
@@ -1132,6 +1147,39 @@ A missing, older, or mismatched build receipt requires one `setup --evidence` re
1132
1147
  This also applies to a rebuilt package with the same version.
1133
1148
  The refresh preserves profile data and sign-in. `dashboard stop` remains available during repair.
1134
1149
  Normal commands do not reinstall dependencies.
1150
+ Setup verifies the virtual environment before it installs packages.
1151
+ On Windows, UV selects Python and invokes its standard `venv` module with executable copies and no pip seed.
1152
+ This avoids UV's custom Windows interpreter launcher.
1153
+ Windows runtime paths cannot contain semicolons because Python venv rejects this character.
1154
+ See the [upstream Windows launcher change](https://github.com/astral-sh/uv/pull/19199) for the old `PYTHONHOME` behavior.
1155
+ UV still installs the engine and locked dependencies.
1156
+ If copied Windows launchers cannot initialize, setup tries one standard symlink-based environment in the same directory.
1157
+ This reuses the installed Python executable. Configuration, packages, and profile data stay in the selected sandbox.
1158
+ The host must permit executable symlinks. Setup does not enable Developer Mode or change Windows permissions.
1159
+ A failed fallback stops before dependency installation.
1160
+ Other platforms retain `uv venv`.
1161
+ It checks `pyvenv.cfg`, Python 3.12 or later, and the native identity of the selected environment.
1162
+ Python checks its own environment in its active filesystem namespace.
1163
+ Node compares directory identities rather than logical and physical sandbox path strings.
1164
+ The base Python directory does not need a separate filesystem lookup.
1165
+ An incomplete environment receives a repair before dependency installation.
1166
+ If verification still fails, setup stops without a success receipt.
1167
+ Inherited `PYTHONHOME`, `PYTHONPATH`, `__PYVENV_LAUNCHER__`, and `UV_INTERNAL__PYTHONHOME` values do not redirect the managed runtime.
1168
+ The launcher retains UV's protection for externally managed Python installations.
1169
+ Some UV versions misread local wheel paths that contain `#`, `%`, or `?`.
1170
+ The launcher copies the immutable cached wheel to a temporary directory when its path contains these characters.
1171
+ It removes the temporary copy after installation or failure.
1172
+ The temporary directory must also avoid these characters.
1173
+ The profile and runtime stay in the selected data directory.
1174
+
1175
+ `setup --check` returns runtime identity and access diagnostics without installing packages or changing profile data.
1176
+ It uses a temporary launcher lease to prevent concurrent runtime repair. The launcher directory can remain afterward.
1177
+ Run it in the host conversation where setup failed, with the same directory and permissions.
1178
+ It reports the selected path, configured backend, executable-link status, resolved prefixes, and configuration access errors.
1179
+ A runtime check does not verify dependencies or complete onboarding.
1180
+ If the host reports `EPERM` or `EACCES`, request its normal access to that path and retry there.
1181
+ Do not disable sandboxing, change ACLs, or move the profile automatically.
1182
+
1135
1183
  Finish active recommendations and Bilibili browser operations before setup.
1136
1184
  Concurrent setup or runtime use returns a busy result instead of changing active files.
1137
1185
  A failed child command releases its installation lock.
package/docs/SCORING.md CHANGED
@@ -27,6 +27,10 @@ The engine requires a verified playable duration greater than sixty seconds and
27
27
  The saved evidence quality must reach 60 points out of 100.
28
28
  For new assessments without a usable transcript, subtract ten points from quality after adding the duration prior, with a floor of zero.
29
29
  The same deduction applies to the learned quality component during ranking.
30
+ After the learned final score, subtract 10 × clamp((300 − t) / 240, 0, 1), where t is seconds.
31
+ This deduction is 7.5 at two minutes, 5 at three, 2.5 at four, and 0 at five minutes.
32
+ Clamp the adjusted score at zero.
33
+ The existing evidence quality gate and screening rules do not change.
30
34
  Audio quality is not a criterion.
31
35
  Captions and frames support the four existing content criteria.
32
36
  Only rubric-5 evidence is eligible for reuse or new recommendation work.
@@ -158,6 +162,11 @@ Length contributes at most five points.
158
162
  The contribution rises to one hour and then remains constant.
159
163
  These initial weights express a design choice, not a fitted optimum.
160
164
  The saved holistic evidence score remains a separate historical observation.
165
+ After assessment, a separate text-only call aligns up to 35 videos with saved interests.
166
+ It uses the assessed title, specific and broad labels, and summary.
167
+ It ignores retrieval origin and accepts only medium- or high-confidence matches.
168
+ Accepted matches supply canonical broad-root features for learned lookup.
169
+ Assessed topic labels remain unchanged.
161
170
 
162
171
  The initial interest probability \(I_0\) is 0.75 for a domain related to the user's stated interests.
163
172
  It is 0.35 for a known unrelated domain and 0.50 when domains are unknown.
@@ -285,7 +294,17 @@ An explicit onboarding change can change the prior.
285
294
  A new dislike cannot move the prior by changing the parent association.
286
295
 
287
296
  A topic judgment does not update parent, sibling, global, or creator dislikes.
288
- A matching specific-topic posterior takes precedence over a broad-subject posterior.
297
+
298
+ Canonical alignment contributes to broad-domain lookup. It does not replace assessed specific or broad labels.
299
+ Lookup also retains raw broad labels so existing subject ratings and learned coefficients remain usable.
300
+ New rounds do not inherit final interest membership from retrieval domains when content labels are missing.
301
+
302
+ Manual per-video topic and domain feedback contributes at its own scope.
303
+ Matching specific-topic scores take precedence over broad-root scores.
304
+
305
+ Depth feedback then adjusts interest for the assessed topic and audience level.
306
+ Direct feedback for that level takes precedence over transferred depth fit.
307
+
289
308
  Several matching topic scores use an average.
290
309
  Custom topic labels transfer only to matching normalized labels.
291
310
 
@@ -398,10 +417,15 @@ Maintenance uses retained frames and captions without downloading replacement me
398
417
 
399
418
  ## 8. Transfer of learned parameters
400
419
 
420
+ Preference file format 4 remains unchanged. Coverage summary version 2 requires an updated plugin.
421
+
401
422
  Preference format 4 transfers interests, model version 8 parameters, watched video IDs, a bounded exploration summary, and manual creator exclusions.
423
+
402
424
  The engine rejects other preference formats before import changes the profile.
403
- The included starter preset provides sanitized interests, parameters, and parameter uncertainty from the owner's export.
404
- The preset excludes watched IDs, individual history, topic coverage, and creator exclusions.
425
+
426
+
427
+ The included starter preset preserves interests, parameters, and parameter uncertainty from the supplied export.
428
+ It clears watched IDs, creator exclusions, and exploration progress.
405
429
  Import replaces manual creator lists independently of learned parameters. These rules never create negative ratings.
406
430
  Blacklist sync combines the account-specific blacklist with the current manual rules.
407
431
  The exploration summary contains at most 1,024 hierarchy nodes, aggregate counts, and relative round ages.
@@ -412,7 +436,12 @@ Categorical groups retain Dirichlet concentration parameters and aggregate obser
412
436
  Depth models retain their posterior summaries and a three-by-three table of level/response counts per topic.
413
437
  These counts are sufficient statistics for the implemented depth likelihood. They contain no video identities or chronology.
414
438
  The watched-video ID list contains no titles, ratings, or recommendation records.
415
- The exploration summary preserves portable topic coverage without video identities or per-video history.
439
+ Coverage summary version 2 adds aggregate, per-platform, and broad-root use counters.
440
+
441
+
442
+ The new plugin accepts version 1 summaries. Older plugin releases do not read version 2 summaries.
443
+ A version 1 import starts new counters at zero and preserves old aggregate counts.
444
+ Merge uses maximum counter values, so repeated imports do not add duplicate use.
416
445
  Import merges those IDs into the target profile's watched state to prevent exact repeats.
417
446
  The target profile keeps its local ratings, video lists, tag rules, and account-specific blacklist copies.
418
447
  Quality calibration retains both continuation-stage models.
package/docs/WORKFLOW.md CHANGED
@@ -15,8 +15,8 @@ Setup preserves the existing profile unless you explicitly request Reset or Clea
15
15
 
16
16
  First-time setup introduces chat recommendations and the local dashboard.
17
17
  Choose the included starter preset, enter interests manually, or import preferences.
18
- The starter preset uses sanitized interests, model parameters, and uncertainty from the owner's export.
19
- It contains no watched IDs, video history, topic coverage, or creator exclusions.
18
+ The preset uses a sanitized copy of a read-only export validated for preference format 4, model 8, and feature 1.
19
+ Setup does not change the source export. Selecting the starter preset does not require Reset.
20
20
  An import asks for the full local JSON file path.
21
21
  For an existing profile, choose whether to keep or change its preferences.
22
22
  Keep preserves the saved preferences and sources. It skips source selection.
@@ -82,15 +82,26 @@ For example, mathematics can contain algebra, which can contain algebraic geomet
82
82
  The hierarchy describes search coverage.
83
83
  It does not prove that you like every child topic.
84
84
 
85
- Each new recommendation round targets twelve existing leaf topics and five new topics.
86
- The program selects existing topics before AI query writing.
87
- It favors underused branches and familiar topics.
88
- When alternatives exist, it skips narrow topics that appeared in recommendations during the last three rounds.
89
- Both platforms in one recommendation batch share topic reservations.
90
- The engine records when it relaxes a reservation or cooldown because it finds few alternatives.
91
- On a cold start, the AI can first propose subdivisions for selected topics.
92
- The AI then writes paired queries for selected concepts: English for YouTube and Simplified Chinese for Bilibili.
93
- The plan uses at most two calls for subdivision and query writing.
85
+ Each platform allocates twelve existing-topic slots and five new-topic slots per round.
86
+ The first six allocation slots use familiar broad roots when those roots exist.
87
+
88
+ For later slots, the engine chooses the familiar or unrelated lane by eligible-root counts.
89
+ The familiar lane weight is three times its eligible-root count.
90
+ The unrelated lane weight equals its eligible-root count.
91
+ The engine chooses a least-served root in the selected lane and breaks ties at random.
92
+
93
+ The engine selects branches after root allocation.
94
+ Optional subdivisions do not increase the topic allocation.
95
+ A capacity limit can reduce the allocation. The report shows each reduction.
96
+
97
+ Platforms track topic use independently, so their rounds can overlap.
98
+ A branch cooldown covers the last three rounds for that platform.
99
+ YouTube-only rounds do not age the Bilibili cooldown.
100
+ A shared batch deduplicates new topic proposals across platforms at its baseline.
101
+ It does not force the platforms to choose different topics.
102
+
103
+ Legacy rounds retain their saved policies when they resume.
104
+ New rounds use rotation version 2 and ranking policy 2.
94
105
  The language rule changes search text, not interest labels or hierarchy levels.
95
106
  Existing topic labels and aliases stay stable as the hierarchy grows.
96
107
  The engine converts Traditional Chinese keywords to Simplified Chinese and rejects incompatible scripts before a keyword search.
@@ -167,7 +178,8 @@ flowchart TD
167
178
  K -- "Access challenge or exhausted run allowance" --> P
168
179
  K -- "Candidate failure: continue other inspections" --> K
169
180
  K --> L["Recheck duration and exclusions and require assessed quality of at least 60"]
170
- L --> M["Prefer distinct narrow topics and search queries; rank eligible choices by the calibrated full score"]
181
+ L --> LA["Align assessed labels and summary with saved interests in a text-only batch"]
182
+ LA --> M["Prefer the lowest topic and query overlap; compare full scores after duration adjustment"]
171
183
  M --> N["Publish up to 10 recommendations for this platform"]
172
184
  P --> O["Show a provisional preview when eligible assessments exist"]
173
185
  ```
@@ -319,7 +331,23 @@ The ranking combines quality, interest, community response, recency, and creator
319
331
  Feedback can change the learned ranking.
320
332
  The [scoring document](SCORING.md) explains the formulas and limits.
321
333
 
322
- The engine selects the final ten by the full recommendation score after quality assessment.
334
+ After quality assessment, the engine aligns assessed labels and summaries with saved interests.
335
+
336
+ Selection strictly minimizes topic and query overlap before it compares scores.
337
+ This favors distinct videos. Repeats remain possible when all remaining videos overlap.
338
+ This text-only batch contains at most thirty-five candidates.
339
+ It matches medium- or high-confidence canonical topics.
340
+ The alignment uses assessed content, not query origin.
341
+ It preserves existing labels, manual narrow-topic feedback, and depth feedback.
342
+ An interest edit does not trigger a full reassessment.
343
+
344
+ If alignment fails, the engine retries three times after the initial call.
345
+ It then uses exact matches and reports the fallback.
346
+
347
+ The engine applies a duration deduction after the learned final score: 10 × clamp((300 − t) / 240, 0, 1).
348
+ The deduction is 7.5 at two minutes, 5 at three, 2.5 at four, and 0 at five minutes.
349
+ The adjusted score has a floor of zero.
350
+ The existing evidence quality gate and screening rules remain unchanged.
323
351
  It applies no unrelated-topic quota.
324
352
  Unwatched recommendations can appear again.
325
353
  Their history remains saved even when they are outside the current list.
@@ -419,7 +447,7 @@ Open **Preferences** in the dashboard.
419
447
  Broader interests and import/export share one page.
420
448
  After import, edit the imported interests in place and select Save if needed.
421
449
  Save interest edits before exporting.
422
- Export saves your interests, learned weights, parameter uncertainty, watched video IDs, a bounded topic-coverage summary, and manual creator exclusions.
450
+ Export saves interests, learned weights and uncertainty, watched IDs, aggregate coverage, and manual creator exclusions.
423
451
  Import previews a format 4 file before replacing those parameters.
424
452
  Broader Vids saves the earlier parameters in a local recovery file first.
425
453
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "broader-vids",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "description": "Codex and experimental Claude Code skills for local YouTube/Bilibili recommendations",
5
5
  "license": "MIT",
6
6
  "engines": {
@@ -11,7 +11,7 @@
11
11
  },
12
12
  "files": [
13
13
  "bin/",
14
- "python/broader_vids-0.1.8-*.whl",
14
+ "python/broader_vids-0.1.10-*.whl",
15
15
  "python/core-requirements.txt",
16
16
  "python/evidence-requirements.txt",
17
17
  "python/asr-requirements.txt",
@@ -48,6 +48,6 @@
48
48
  "tag": "latest"
49
49
  },
50
50
  "broaderVidsRelease": {
51
- "sourceCommit": "af4569e77bbf198387ee0fd2fda88cfa2ef74964"
51
+ "sourceCommit": "b089281c8f32dadab8fdd8364d9015cc70ea5cfa"
52
52
  }
53
53
  }
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "broader-vids",
4
- "version": "0.1.8",
4
+ "version": "0.1.10",
5
5
  "description": "Curated YouTube and Bilibili recommendations with bounded quality evidence and local watched/feedback state.",
6
6
  "license": "MIT",
7
7
  "extensions": {
@@ -98,6 +98,18 @@ Do not repeat the introduction for a completed profile during routine checks.
98
98
  Check Node.js 20 or later, UV, and Codex CLI availability.
99
99
  Report exact repair steps for missing system tools.
100
100
  Run `setup --evidence` to install the external runtime and evidence dependencies when needed.
101
+ Setup creates the runtime directory before platform or interest configuration.
102
+ On Windows, it uses UV to select Python and Python's standard module to create the virtual environment.
103
+ If copied Windows launchers cannot initialize, setup tries an executable-link environment in the same directory once.
104
+ It verifies isolation before installing packages. Do not disable the check or move data to make it pass.
105
+ If the host denies file access, request its normal permission for the same data directory before retrying.
106
+ If access was already granted in this session, do not repeat the same permission request or installation without a changed condition.
107
+ If isolation verification fails, run `setup --check` in this same host conversation and permission context.
108
+ Show its reason, prefix, base prefix, and access error. This command does not install packages or change profile data.
109
+ It briefly holds a launcher lease and releases that lease after the check.
110
+ Do not compare physical sandbox paths from an external terminal to diagnose this check.
111
+ Do not move the profile or select another directory unless the user requests that change.
112
+ Do not disable UV's protection for externally managed Python installations.
101
113
  Install optional transcription with `setup --asr` only when requested.
102
114
  Do not reinstall a working runtime during normal recommendation requests.
103
115
  If the launcher reports a missing or mismatched build receipt, refresh the runtime with `setup --evidence`.