broader-vids 0.1.3 → 0.1.5

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.
package/README.md CHANGED
@@ -1,33 +1,31 @@
1
1
  # Broader Vids
2
2
 
3
- Broader Vids provides an alternative recommendation algorithm for YouTube and Bilibili.
4
- It combines your interests, exploration of unfamiliar topics, video quality, and feedback.
3
+ Broader Vids provides an alternative recommendation algorithm for YouTube and Bilibili. It combines your interests, exploration of unfamiliar topics, and video quality.
5
4
 
6
- **The plugin learns from your dashboard ratings and calibrates its internal scoring model weights to your preferences.**
7
- You can manually exclude creators and tags from future rounds.
8
- Each complete round recommends ten videos per selected platform.
5
+ **Your dashboard ratings calibrate the plugin’s internal scoring models to your preferences.**
6
+ You can exclude creators and tags from future rounds. Each complete round recommends ten videos per selected platform.
9
7
 
10
- The plugin runs locally through Codex CLI or Codex in the ChatGPT desktop app.
11
- Recommendations appear in chat. A local dashboard provides ratings, exclusions, and preferences.
8
+ The plugin runs locally through Codex CLI or Codex in the ChatGPT desktop app. Recommendations appear in chat. A local dashboard manages ratings, exclusions, and preferences.
9
+
10
+ ## Requirements
11
+
12
+ Use Windows, PowerShell, Node.js 20 or later with npm, UV, and Codex CLI signed in with ChatGPT. Installation and recommendations require internet access.
12
13
 
13
14
  ## Install the plugin
14
15
 
15
- Requirements: Windows, PowerShell, Node.js 20 or later with npm, UV, and Codex CLI authenticated with ChatGPT.
16
- Installation and recommendations require internet access.
17
- Choose one installation method. Neither method requires a checkout, build, or local folder selection.
16
+ Choose one of these three remote installation routes. You do not need a repository checkout or a local build.
18
17
 
19
- ### From GitHub in the ChatGPT desktop app
18
+ ### ChatGPT desktop app
20
19
 
21
20
  1. Open the plugin marketplace controls in Codex.
22
- 2. Select **Add marketplace** and its repository or Git URL option.
21
+ 2. Select **Add marketplace** and choose its repository or Git URL option.
23
22
  3. Enter `https://github.com/antidemosthenes/broader-vids`.
24
- 4. Add or sync the marketplace.
25
- 5. Select **Broader Vids** and install it.
26
- 6. Start a new conversation.
23
+ 4. Add or sync the marketplace. Then install **Broader Vids**.
24
+ 5. Start a new conversation.
27
25
 
28
- The GitHub repository supplies the catalog. Its plugin entry downloads the complete package from npm.
26
+ The GitHub repository provides the catalog. The catalog downloads the plugin package from npm.
29
27
 
30
- ### From GitHub in Codex CLI
28
+ ### Codex CLI from GitHub
31
29
 
32
30
  Run these commands in PowerShell:
33
31
 
@@ -38,7 +36,7 @@ codex plugin add broader-vids@broader-vids
38
36
 
39
37
  Start a new conversation after installation.
40
38
 
41
- ### From npm
39
+ ### npm
42
40
 
43
41
  Run this command in PowerShell:
44
42
 
@@ -46,88 +44,42 @@ Run this command in PowerShell:
46
44
  npx --yes broader-vids@latest plugin install
47
45
  ```
48
46
 
49
- This command registers an npm-backed marketplace and installs the plugin through Codex.
50
- It installs the skills and dashboard, not only the terminal launcher.
51
- It does not require the GitHub catalog.
52
- Restart the desktop app or start a new Codex CLI conversation after installation.
47
+ This command registers an npm backed marketplace and installs the plugin skills and dashboard. Start a new conversation after installation.
53
48
 
54
- The app's Add marketplace field accepts repository URLs, not npm package names.
55
- Use the npm command above for that installation route.
56
- See the [official packaging guide](https://developers.openai.com/plugins/build/plugins) for supported plugin sources.
49
+ The desktop app accepts repository URLs in **Add marketplace**. Use the npm command for npm installation. See the [plugin packaging guide](https://developers.openai.com/plugins/build/plugins) for supported sources.
57
50
 
58
51
  ## Update the plugin
59
52
 
60
- For a GitHub installation, refresh its marketplace and install the current release:
61
-
62
- ```powershell
63
- codex plugin marketplace upgrade broader-vids
64
- codex plugin add broader-vids@broader-vids
65
- ```
66
-
67
- For an npm installation, repeat the installation command:
68
-
69
- ```powershell
70
- npx --yes broader-vids@latest plugin install
71
- ```
72
-
73
- In the desktop app, refresh the marketplace and select the current Broader Vids release.
74
- If the app provides no update action, use the terminal commands for your installation method.
75
- Start a new conversation and run setup after an update.
76
- Setup installs the matching engine and preserves your saved profile.
77
- Finish active recommendations and close the dashboard before updating.
78
-
79
- ## Set up and request recommendations
80
-
81
- Use this procedure for either platform or both:
53
+ Follow [Update an installed plugin](docs/REFERENCE.md#update-an-installed-plugin) for update steps.
82
54
 
83
- 1. Start a new conversation. Invoke the setup skill from the table below.
84
- 2. Choose YouTube, Bilibili, or both.
85
- 3. Choose calibrated starter preferences, enter your interests, or import a preference file.
86
- 4. Complete the dependency and access checks. Setup gives repair steps for required failures.
87
- 5. Invoke the recommendation skill. Review the links and summaries in chat.
88
- 6. Open the dashboard to mark watched videos and rate their topic, subject, depth, and quality.
89
- 7. Request another round when you want more recommendations.
55
+ ## Set up and use Broader Vids
90
56
 
91
- Existing profiles can keep their saved preferences during setup.
92
- Saving ratings updates the local preference and quality models.
93
- Their learned weights affect screening and final ranking in later rounds.
94
- Creator and tag exclusions apply to the next new round.
95
- The dashboard **Preferences** page lets you edit interests and import or export preferences and learned weights.
96
- Before a new round, incomplete feedback prompts you to open the dashboard or continue.
57
+ Start a new conversation and invoke the setup skill. Choose YouTube, Bilibili, or both. Then choose starter preferences, enter interests, or import a preference file. Setup checks dependencies and access. It gives repair steps when a required check fails.
97
58
 
98
- Both platforms support manual creator and tag exclusions.
99
- YouTube tag rules match available creator-supplied keyword tags, which differ from visible hashtags.
100
- Bilibili rules match its video tags.
101
- Search queries use English for YouTube and Simplified Chinese for Bilibili.
59
+ Invoke the recommendation skill to request a round. Review recommendations in chat. Open the dashboard to mark videos as watched and rate topic, subject, depth, and quality. Ratings update local preference and quality models. Their learned weights affect later rounds. Creator and tag exclusions apply to the next new round.
102
60
 
103
61
  | Action | Skill command | Purpose |
104
62
  | --- | --- | --- |
105
- | Setup | `$broader-vids-setup` | Choose platforms and preferences, install required tools, and check access. |
106
- | Recommendations | `$broader-vids` | Request a round for your saved platforms. |
107
- | Dashboard | `$broader-vids-dashboard` | Rate videos, manage exclusions, and edit preferences. |
108
- | Reset | `$broader-vids-reset` | Preview removal of preferences, weights, ratings, and histories while keeping tools and sign-in. |
109
- | Clean | `$broader-vids-clean` | Preview removal of all managed local data, including tools and sign-in. |
110
-
111
- Use the command names shown by your host's skill menu.
112
- Some hosts add the plugin namespace, such as `$broader-vids:broader-vids-dashboard`.
113
- You can also ask: “Use Broader Vids to recommend videos” or “Use Broader Vids to open my dashboard.”
63
+ | Setup | `$broader-vids-setup` | Choose platforms and preferences. Install tools and check access. |
64
+ | Recommendations | `$broader-vids` | Request videos for your saved platforms. |
65
+ | Dashboard | `$broader-vids-dashboard` | Rate videos. Manage exclusions and preferences. |
66
+ | Reset | `$broader-vids-reset` | Preview removal of preferences, weights, ratings, and histories. Keep tools and sign-in. |
67
+ | Clean | `$broader-vids-clean` | Preview removal of all managed data, including tools and sign-in. |
68
+
69
+ Use the skill commands shown in your host's skill menu. Some hosts add the plugin namespace, such as `$broader-vids:broader-vids-dashboard`. You can also ask Broader Vids to recommend videos or open the dashboard.
70
+
114
71
  Reset and Clean require confirmation. Neither action uninstalls the plugin.
115
72
 
116
73
  ## Bilibili access and exclusions
117
74
 
118
- Bilibili requires manual sign-in for full-video evidence.
119
- Setup opens a separate browser window.
120
- Keep that window open after sign-in and return to chat to report completion.
121
- The plugin verifies the session and closes the window.
122
- You can switch accounts later from the dashboard.
75
+ Bilibili needs manual sign-in for full video evidence. Setup opens a separate browser. Keep it open after sign-in, then report completion in chat. Broader Vids checks the session and closes the browser. You can switch accounts from the dashboard.
76
+
77
+ Broader Vids imports your account blacklist after sign-in checks and before new rounds. Imported creator exclusions combine with your manual exclusions. A failed sync keeps the last complete copy. Use **Sync blacklist** in the dashboard to retry.
78
+
79
+ ## Architecture and guides
123
80
 
124
- Bilibili imports your account blacklist after verified sign-in and before new rounds.
125
- Imported creator exclusions combine with your manual exclusions.
126
- A failed sync preserves the last complete copy.
127
- Use **Sync blacklist** in the dashboard to retry.
81
+ The Node launcher manages a versioned local Python engine, which stores profile data locally and serves the dashboard.
128
82
 
129
- See the [workflow](docs/WORKFLOW.md) for recommendation steps and the [scoring guide](docs/SCORING.md) for ranking and learning.
130
- The [reference](docs/REFERENCE.md) covers terminal commands, troubleshooting, local builds, and maintenance.
131
- The [architecture](docs/ARCHITECTURE.md) describes the launcher, engine, and local storage.
83
+ Read the [workflow](docs/WORKFLOW.md) for recommendation steps. Read the [scoring guide](docs/SCORING.md) for ranking and learning. The [reference](docs/REFERENCE.md) covers commands, troubleshooting, updates, and maintenance. The [architecture guide](docs/ARCHITECTURE.md) describes the launcher, engine, and local storage.
132
84
 
133
85
  License: [MIT](LICENSE).
@@ -101,6 +101,21 @@ function commandIndex(args) {
101
101
  return -1;
102
102
  }
103
103
 
104
+ function validateSetupArguments(args, index) {
105
+ for (let item = index + 1; item < args.length; item += 1) {
106
+ const value = args[item];
107
+ if (value === "--asr" || value === "--evidence") continue;
108
+ if (value === "--data-dir") {
109
+ item += 1;
110
+ continue;
111
+ }
112
+ if (value.startsWith("--data-dir=")) continue;
113
+ throw new Error(
114
+ "Use setup with optional --evidence, --asr, and --data-dir PATH.",
115
+ );
116
+ }
117
+ }
118
+
104
119
  function invoke(command, args) {
105
120
  const result = spawnSync(command, args, {
106
121
  stdio: "inherit",
@@ -306,7 +321,8 @@ function main(args = process.argv.slice(2)) {
306
321
  if (result.status === "partial") process.exitCode = 2;
307
322
  return;
308
323
  }
309
- if (args[commandIndex(args)] === "setup") {
324
+ if (args[index] === "setup") {
325
+ validateSetupArguments(args, index);
310
326
  const sourceWheel = bundledWheel(packageRoot, manifest.version);
311
327
  const wheelRoot = path.dirname(sourceWheel);
312
328
  return withSetup(root, () => {
@@ -68,6 +68,7 @@ broader-vids/
68
68
  asr-requirements.txt Locked transcription dependencies
69
69
  *.whl Generated engine package, excluded from Git
70
70
  scripts/
71
+ release.py Build, verify, and synchronize release artifacts
71
72
  release_ci.py Patch planning, publication checks, and GitHub assets
72
73
  versioning.py Validated release metadata synchronization
73
74
  test.py Isolated parallel regression runner
@@ -174,6 +175,7 @@ Refresh requests carry a read version and a mutation generation.
174
175
  Only one refresh group runs at a time.
175
176
  A refresh requested during an active read waits until that read finishes.
176
177
  Old video records stay in browser memory only while the server returns them, an earlier list uses them, or they have an unsaved rating draft.
178
+ The interface removes saved-status notes and inspector positions when their videos leave all retained lists and drafts.
177
179
  The interface rejects responses from before a newer mutation.
178
180
  It pauses background refresh while the tab is hidden or a write is active.
179
181
  Refresh preserves active controls and pane positions.
@@ -261,7 +263,8 @@ Preference transfer accepts format 4 with learning model version 8 and feature v
261
263
  Manual creator rules transfer separately from learning parameters and replace the manual lists transactionally on import.
262
264
  The export omits account-specific blacklist copies and sign-in data.
263
265
  It includes a bounded exploration summary with at most 1,024 nodes and aggregate counts and round ages.
264
- It excludes individual video history.
266
+ It includes watched video IDs without titles, ratings, or recommendation records.
267
+ Import adds their watched state without clearing local video states.
265
268
  It does not change SQLite schema 12.
266
269
  A completed `preference_import` job stores the imported parameter baseline and local feedback cutoff.
267
270
  Fitting combines that baseline with active ratings saved after the cutoff.
@@ -275,11 +278,11 @@ Input validation runs once per terminal or HTTP request.
275
278
  Failed imports remove unused recovery files.
276
279
  Import also removes obsolete model caches while preserving models referenced by recommendations or frozen evaluations.
277
280
  An uncertain commit retains its recovery file.
278
- Parameter-only recovery files reside in `backups/`.
281
+ Preference recovery files reside in `backups/` and include prior watched IDs and manual creator rules.
279
282
  The dashboard uses authenticated local POST operations for export, preview, and import.
280
283
  The transfer dialog preserves rating drafts and blocks stale polling responses during an operation.
281
284
 
282
- Evidence corrections add derived records.
285
+ Evidence corrections add derived records, including the current missing-caption deduction.
283
286
  They do not overwrite original scorecards or user ratings.
284
287
 
285
288
  The Preferences page uses `preferences.js` to coordinate `/api/interests` and the preference-transfer endpoints.
package/docs/REFERENCE.md CHANGED
@@ -807,6 +807,10 @@ Dashboard browser tests require Playwright and a supported local browser.
807
807
  Local Windows browser tests use installed Edge by default.
808
808
  CI installs the Playwright Chromium headless shell on both operating systems.
809
809
  Set `BROADER_VIDS_TEST_BROWSER=chromium` to use that browser locally.
810
+ Windows CI first installs the headless browser without changing system components.
811
+ If installation fails, it retries with the required system dependencies.
812
+ Linux CI installs those dependencies before tests.
813
+ Both paths retain browser validation and the full test suite.
810
814
  Linux tests use Playwright Chromium. Install its browser and system dependencies before running tests:
811
815
 
812
816
  ```bash
@@ -970,6 +974,10 @@ Publication jobs accept the intentionally skipped duplicate checks on automatic
970
974
  They still require successful preparation and stop after cancellation. GitHub assets also require successful npm publication.
971
975
  Tag creation and GitHub release assets use separate jobs with `contents: write` permission.
972
976
  The workflow publishes the verified archive under `latest`, then checks public registry integrity.
977
+ Registry verification allows up to five minutes for npm processing and tag propagation.
978
+ The wait uses bounded requests and reports progress.
979
+ A verification timeout can occur after npm accepts the package.
980
+ Check the public version before retrying. Rerun failed jobs to reuse a matching published archive and finish the GitHub release.
973
981
  It creates a GitHub release with the archives, manifest, and checksums after npm publication succeeds.
974
982
  It retains workflow artifacts for seven days.
975
983
 
@@ -1076,6 +1084,7 @@ Its `installed` status does not mean onboarding is complete.
1076
1084
  Use the guided setup skill to configure interests, choose platforms, and check access.
1077
1085
  `setup --evidence` also installs browser and media tools.
1078
1086
  `setup --asr` includes those tools and transcription dependencies.
1087
+ Setup rejects unsupported options before it changes the profile or runtime.
1079
1088
  The receipt records `core`, `evidence`, and `asr` only when setup installed those groups, with each group's requirements-file digest.
1080
1089
  Setup requires Node.js 20 or later and UV.
1081
1090
  It does not use an npm postinstall script.
@@ -1214,7 +1223,14 @@ Continue only after you restore access.
1214
1223
  Browser sign-in is not imported automatically. Increasing the request cap does not repair an access challenge.
1215
1224
  They share one request counter and retain the existing access checks.
1216
1225
  Video downloads omit audio unless transcription requires it.
1217
- Exact or estimated selected-stream sizes support a check before transfer.
1226
+ The engine checks selected-stream sizes before transfer.
1227
+ It uses reported exact sizes, reported estimates, or duration multiplied by bitrate, in that order.
1228
+ Transcription downloads include both video and audio in this check.
1229
+ If the estimate exceeds the remaining allowance, the engine tries a smaller offered format within the existing resolution and audio rules.
1230
+ When partial media exists, continuation resolves saved format IDs against fresh metadata and checks their codecs and resolution.
1231
+ If the original selection is unavailable, the engine skips the candidate and removes its owned partial files.
1232
+ Cumulative download charges remain unchanged.
1233
+ Unknown sizes still use the transfer byte limit.
1218
1234
  Transfer checkpoints record observed bytes and bound unreported bytes after interruption.
1219
1235
  Reports identify conservative byte charges as upper bounds.
1220
1236
 
package/docs/SCORING.md CHANGED
@@ -162,10 +162,10 @@ Search-domain labels describe retrieval context.
162
162
  They do not prove the video's semantic topic.
163
163
 
164
164
  New AI topic labels must be short subject names, with at most 120 characters and 12 words.
165
- The validator rejects obvious citations, instructions, control characters, and editing notes in labels.
166
- Invalid new output uses the existing bounded assessment fix workflow.
167
- Read operations omit unusable labels from older scorecards and annotations.
168
- They preserve raw evidence, numeric quality scores, saved ratings, and explicit user targets.
165
+ Fresh assessments and reads of saved scorecards omit unusable topic labels before validation.
166
+ The filter removes obvious citations, instructions, control characters, and editing notes from the label lists.
167
+ The engine retains the raw model response and preserves numeric quality scores, saved ratings, and explicit user targets.
168
+ Remaining schema or evidence errors use the existing bounded assessment fix workflow.
169
169
  This check detects common formatting errors. It does not prove that a topic correctly describes the video.
170
170
 
171
171
  Source links, repost declarations, `中配`, and YouDub disclosures inform originality assessment.
@@ -388,6 +388,7 @@ A new response type requires new holdout coverage.
388
388
  Training on released labels does not replace the earlier test result.
389
389
 
390
390
  Evidence maintenance adds derived feature records after source checks.
391
+ Corrections include the current missing-caption deduction, which replaces any earlier deduction.
391
392
  They preserve original ratings, scorecards, and captured features.
392
393
  Incomplete source metadata can pause quality fitting.
393
394
  Maintenance uses retained frames and captions without downloading replacement media.
package/docs/WORKFLOW.md CHANGED
@@ -6,7 +6,7 @@ See the [terminal reference](REFERENCE.md) for commands.
6
6
 
7
7
  ## 1. Complete setup and check readiness
8
8
 
9
- Use the [README](../README.md#update-the-plugin) to update an installed plugin.
9
+ Use the [update procedure](REFERENCE.md#update-an-installed-plugin) to update an installed plugin.
10
10
  Finish active work before updating. Start a new conversation and run setup to prepare the matching engine.
11
11
  Setup preserves the existing profile unless you explicitly request Reset or Clean.
12
12
 
@@ -131,7 +131,7 @@ The two-platform command runs these paths with shared workers and an optional to
131
131
  ```mermaid
132
132
  flowchart TD
133
133
  S["Recommendation request"] --> T{"Onboarding complete?"}
134
- T -- No --> U["Introduce features; choose platforms; import preferences or enter interests"]
134
+ T -- No --> U["Introduce features; choose platforms; choose a starter, import preferences, or enter interests"]
135
135
  U --> V["Install required tools and check selected platform access"]
136
136
  V -- "Failure: repair and retry" --> V
137
137
  V --> W["Record setup completion"]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "broader-vids",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Codex skill and local YouTube/Bilibili recommendations with quality evidence and feedback",
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.3-*.whl",
14
+ "python/broader_vids-0.1.5-*.whl",
15
15
  "python/core-requirements.txt",
16
16
  "python/evidence-requirements.txt",
17
17
  "python/asr-requirements.txt",
@@ -46,6 +46,6 @@
46
46
  "tag": "latest"
47
47
  },
48
48
  "broaderVidsRelease": {
49
- "sourceCommit": "e46084f800475c5a9aa1a90160ec8e088ed26eee"
49
+ "sourceCommit": "575b8bfeb556af08e68e46a103f441beb5745406"
50
50
  }
51
51
  }
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.3",
4
+ "version": "0.1.5",
5
5
  "description": "Curated YouTube and Bilibili recommendations with bounded quality evidence and local watched/feedback state.",
6
6
  "license": "MIT",
7
7
  "extensions": {