docs(onboard): BDD scenarios + architecture for the ADR-028 burst
- connect_account.feature: refine the burst scenario to "best recent" (likely-good selection, skips too-short/too-long) and add a scenario for the stronger model. - scenario_coverage: remap to TestOnboardBurstVideoIDs + add the model scenario (the old NewestUnsummarizedVideoIDs test was removed). - architecture.md: new "Connect-time onboarding burst" subsection — junk-avoiding selection over persisted duration, the burst-only stronger-model chain, and why has-captions/cached-first are not selection signals.
This commit is contained in:
@@ -250,6 +250,32 @@ After (newest-first): `[chanB-new, chanA-mid, chanA-old, chanB-null]`
|
|||||||
The set of *processed* videos now also excludes auto-mode back-catalogue beyond the recency
|
The set of *processed* videos now also excludes auto-mode back-catalogue beyond the recency
|
||||||
window (those stay listed, summarised on demand); within the processed set, only order changes.
|
window (those stay listed, summarised on demand); within the processed set, only order changes.
|
||||||
|
|
||||||
|
### Connect-time onboarding burst (ADR-018 → ADR-028)
|
||||||
|
|
||||||
|
On a successful YouTube connect, `ConnectHandler` enqueues a connect-triggered discovery pass;
|
||||||
|
the `discoveryTrigger` runs that pass and then fires the **onboarding burst** — a third entry path
|
||||||
|
that summarises up to `TAPIR_ONBOARD_SUMMARIZE_COUNT` (default 3, hard-capped) of the new user's
|
||||||
|
videos so the first session is not empty. The burst still flows through `globalFetchGate` (it is
|
||||||
|
not a throughput change); ADR-028 sharpened *which* videos and *which model*:
|
||||||
|
|
||||||
|
- **Selection** is `OnboardBurstVideoIDs`, not pure newest-first. It keeps newest-first order but
|
||||||
|
excludes a video whose **known** duration is outside `[TAPIR_MIN_VIDEO_SECONDS,
|
||||||
|
TAPIR_ONBOARD_MAX_VIDEO_SECONDS]` (drops Shorts and multi-hour livestream VODs). An unknown
|
||||||
|
(NULL) duration is degrade-open — kept, but ranked after known-good rows. The connect-triggered
|
||||||
|
discovery pass runs *before* the burst, and ADR-023's `videos.list` enrichment now **persists**
|
||||||
|
`duration_s` (instead of discarding it after the Shorts filter), so a fresh user's candidates
|
||||||
|
carry a duration in time for selection.
|
||||||
|
- **Model**: the burst runs through a dedicated summarizer chain led by
|
||||||
|
`TAPIR_ONBOARD_SUMMARIZER_MODEL` (default `iguana/gemma4-26b`, the stronger local model), with
|
||||||
|
the standard ADR-022 chain following as fallback. This is a wiring choice — a second
|
||||||
|
`engineProcessor` over the same store / transcript cache / sink; the engine and ports are
|
||||||
|
unchanged. Empty / equal-to-primary collapses it back onto the shared processor.
|
||||||
|
|
||||||
|
`has-captions` is deliberately **not** a selection signal — it is only knowable after a gate fetch
|
||||||
|
(or a ~0-probability cache hit at pilot scale), so the burst can avoid known-junk but cannot
|
||||||
|
promise captions. Cached-transcript-first selection was investigated and rejected (ADR-028:
|
||||||
|
~3% cross-user overlap).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Sequence — core use case: new video summarized
|
## Sequence — core use case: new video summarized
|
||||||
|
|||||||
@@ -24,12 +24,19 @@ Feature: Connect and manage video accounts
|
|||||||
Then a discovery pass for my account is triggered right away
|
Then a discovery pass for my account is triggered right away
|
||||||
And I do not have to wait for the next scheduled pass to see my videos
|
And I do not have to wait for the next scheduled pass to see my videos
|
||||||
|
|
||||||
Scenario: Connecting summarizes my newest videos right away
|
Scenario: Connecting summarizes my best recent videos right away
|
||||||
Given I have no connected video accounts
|
Given I have no connected video accounts
|
||||||
When I connect my YouTube account
|
When I connect my YouTube account
|
||||||
Then up to the onboarding cap of my newest videos are summarized through the rate gate
|
Then up to the onboarding cap of my newest likely-good videos are summarized through the rate gate
|
||||||
|
And videos whose known duration is too short or too long are skipped
|
||||||
And the rest are left to the scheduled recency-bounded pass
|
And the rest are left to the scheduled recency-bounded pass
|
||||||
|
|
||||||
|
Scenario: The onboarding burst summarizes with a stronger model
|
||||||
|
Given I have no connected video accounts
|
||||||
|
When I connect my YouTube account
|
||||||
|
Then the burst summarizes with the stronger onboarding model first
|
||||||
|
And the standard summarizer chain still follows as a fallback
|
||||||
|
|
||||||
Scenario: Tokens are never stored in the clear
|
Scenario: Tokens are never stored in the clear
|
||||||
When I connect any video account
|
When I connect any video account
|
||||||
Then no OAuth token value is stored in the database
|
Then no OAuth token value is stored in the database
|
||||||
|
|||||||
@@ -40,7 +40,8 @@ var scenarioCoverage = map[string]string{
|
|||||||
// connect_account.feature
|
// connect_account.feature
|
||||||
"Connect a YouTube account": "TestCallbackExchangesAndRecordsConnection",
|
"Connect a YouTube account": "TestCallbackExchangesAndRecordsConnection",
|
||||||
"Connecting an account discovers videos immediately": "TestCallbackTriggersDiscovery",
|
"Connecting an account discovers videos immediately": "TestCallbackTriggersDiscovery",
|
||||||
"Connecting summarizes my newest videos right away": "TestNewestUnsummarizedVideoIDs",
|
"Connecting summarizes my best recent videos right away": "TestOnboardBurstVideoIDs",
|
||||||
|
"The onboarding burst summarizes with a stronger model": "TestBurstChainModelsLeadsWithOnboardModel",
|
||||||
"Tokens are never stored in the clear": "TestCallbackExchangesAndRecordsConnection",
|
"Tokens are never stored in the clear": "TestCallbackExchangesAndRecordsConnection",
|
||||||
|
|
||||||
// paste_url.feature
|
// paste_url.feature
|
||||||
|
|||||||
Reference in New Issue
Block a user