# YouTube Manual Analytics CSV Import

This project uses **YouTube upload-only OAuth**. JARVIS must not use YouTube Analytics API, YouTube read scopes, or comment endpoints.

## Source in YouTube Studio

Export analytics manually from YouTube Studio for the relevant Shorts/videos. Use aggregated video metrics only. Recommended snapshots:

- 24h after publish
- 72h after publish
- 7d after publish
- optional later snapshots for long-tail review

Fill or map the exported data into:

`data/templates/youtube_analytics_manual_import_template.csv`

## Allowed columns

Only these columns may be imported:

- `video_id`
- `candidate_id`
- `title`
- `publish_date`
- `snapshot_time`
- `days_since_publish`
- `views`
- `engaged_views`
- `shown_in_feed`
- `viewed_vs_swiped_away`
- `average_view_duration`
- `average_percentage_viewed`
- `likes`
- `shares`
- `comments_count`
- `subscribers_gained`
- `traffic_source`
- `impressions`
- `click_through_rate`
- `notes_by_user`

`comments_count` is allowed because it is aggregated. Comment texts, comment IDs, authors, and links are not allowed.

## Forbidden columns

These columns block the import:

- `comment`
- `comments_text`
- `comment_text`
- `message`
- `body`
- `reply`
- `author`
- `username`
- `channel_name`
- `profile`
- `email`
- `url`
- `link`
- `raw_text`
- `external_text`

Unknown columns are blocked as well. This prevents accidental raw viewer text or external instructions from entering the system.

## Snapshot timing

Use `snapshot_time` as an ISO-style timestamp with local timezone when possible, for example:

- `2026-05-28T09:00:00+02:00` for 24h
- `2026-05-30T09:00:00+02:00` for 72h
- `2026-06-03T09:00:00+02:00` for 7d

Set `days_since_publish` to `1`, `3`, or `7` accordingly.

## Safe `notes_by_user`

`notes_by_user` is only for your own manual summary, not raw viewer comments.

Allowed examples:

- `Strong thumbnail, weak retention after 8s.`
- `Shares high; topic likely family-relevant.`
- `Hook clear, first frame could be stronger.`

Forbidden examples:

- copying viewer comments
- usernames
- commenter links
- URLs
- e-mail addresses
- raw external text
- instructions from comments or descriptions

The importer caps `notes_by_user` at 300 characters.

## Commands

Import sanitized CSV:

```bash
python -m autoshorts.cli.import_youtube_analytics_csv data/templates/youtube_analytics_manual_import_template.csv
```

Build learning report:

```bash
python -m autoshorts.cli.youtube_learning_report_from_csv --input data/templates/youtube_analytics_manual_import_template.csv
```

Both commands are local-only and must not call YouTube APIs.