# YouTube Deterministic Orchestration Agent

A deterministic, tool-based Python CLI agent for autonomous AI execution.

## What It Does

- Searches YouTube with stable ranked results (`top 10` by default).
- Selects videos deterministically (top-N or explicit video IDs).
- Validates canonical metadata before processing.
- Retrieves official YouTube captions first (manual captions preferred over auto captions).
- Falls back to audio transcription only when captions are verified unavailable.
- Writes structured Markdown outputs with strict integrity validation.
- Avoids duplicate work using file integrity checks and idempotent rerun behavior.

## CLI Usage

```bash
.venv/bin/youtube-agent "Search query" \
  --limit 10 \
  --select-count 1 \
  --output-dir transcripts \
  --audio-cache-dir .cache/audio
```

Fallback transcription uses the `whisper` CLI when official captions are unavailable.
If `whisper` is missing, execution terminates with a structured error (`TRANSCRIPTION_ENGINE_MISSING`).

Deterministic explicit selection:

```bash
.venv/bin/youtube-agent "Webflow automation" --video-ids aKd_F_7Dv1g
```

## Markdown Output Contract

Each transcript file is saved as:

```text
{normalized-video-title}__{normalized-channel-name}.md
```

Normalization rules are deterministic:

- Lowercase
- Spaces -> hyphens
- Illegal characters removed
- Repeated hyphens collapsed
- Safe max length with non-empty fallback

Each file contains:

- H1 title
- Channel
- Video URL
- Publish date
- Duration
- Description
- Transcript
- Transcript source
- Generation timestamp

## Architecture

`src/youtube_cli_agent/tools/`

- `search.py` - `YouTubeSearchTool`
- `metadata_validation.py` - `MetadataValidationTool`
- `caption_retrieval.py` - `CaptionRetrievalTool`
- `audio_download.py` - `AudioDownloadTool`
- `transcription.py` - `TranscriptionTool`
- `markdown_persistence.py` - `MarkdownPersistenceTool`
- `dedupe.py` - `DuplicateCheckerTool`

`src/youtube_cli_agent/orchestrator.py` provides strict stage sequencing and validation gates.
`src/youtube_cli_agent/markdown_logger.py` produces clean Markdown CLI logs.

## Validation Gates

After each stage the orchestrator verifies:

- Required fields are present
- Transcript is non-empty and above threshold
- File integrity after write
- No silent truncation

On failure, execution stops immediately with:

- Stage
- Error code
- Reason

## Idempotency

Rerunning with the same command does not duplicate work:

- Existing valid transcripts are skipped
- Existing audio cache is reused
- Corrupt transcript files are detected and replaced

## Tests

Run all tests:

```bash
.venv/bin/pytest
```

Tool-by-tool deterministic tests are included for:

- Search
- Metadata validation
- Caption retrieval
- Audio download
- Transcription
- Markdown persistence
- Duplicate checker
- Full pipeline orchestration
