# colingpt9/grand-theft-auto-6-clips-kitty-plugin architecture

> Architecture diagram of the GitHub repository colingpt9/grand-theft-auto-6-clips-kitty-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin
- Repository: https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin

## Overview

This is a Clips Kitty plugin that finds and ranks GTA highlight moments from a stream transcript and host-provided media signals, then returns clip ranges and optional edit suggestions to the host. The workflow runs through the SDK entry point and adapter, which gathers evidence and invokes detection before submitting results. Separate branches cover dialogue review with an optional local model and evaluation tooling. The map follows the README and sampled excerpts; some internal call details and unsampled implementations are not shown, so uncertain links are omitted.

Main entry points: [`src/gta_highlights/adapter.py`](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/adapter.py) (Job adapter), [`src/gta_highlights/detector.py`](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/detector.py) (Highlight detector), [`evaluation/run.py`](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/run.py) (Fixture evaluator), [`src/gta_highlights/dialogue.py`](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/dialogue.py) (Dialogue discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host integration"]
  node_clipskitty["Clips Kitty"]
  node_entry["SDK entry point<br/>[main.py]"]
  node_adapter["Job adapter<br/>[adapter.py]"]
end

subgraph group_detection["Moment detection"]
  node_observations["Evidence collection<br/>[observations.py]"]
  node_evidence["Evidence and scoring<br/>[scoring.py]"]
  node_taxonomy["Event taxonomy<br/>[taxonomy.py]"]
  node_detector["Highlight detector<br/>[detector.py]"]
  node_selection["Candidate selection<br/>[selection.py]"]
end

subgraph group_review["Dialogue review"]
  node_dialogue["Dialogue discovery<br/>[dialogue.py]"]
  node_review_budget[("Review budget and cache<br/>[review.py]")]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Fixture evaluator<br/>[run.py]"]
  node_baseline["Energy baseline<br/>[baseline.py]"]
  node_metrics["Temporal metrics<br/>[metrics.py]"]
end

node_streamer(("Streamer"))
node_vod["Stream VOD"]
node_ollama["Local Ollama model"]

node_streamer -->|"provides"| node_vod
node_vod -->|"adds VOD"| node_clipskitty
node_clipskitty -->|"invokes plugin"| node_entry
node_entry -->|"runs"| node_adapter
node_adapter -->|"collects evidence"| node_observations
node_observations -.->|"creates records"| node_evidence
node_adapter -->|"detects highlights"| node_detector
node_detector -.->|"classifies cues"| node_taxonomy
node_detector -.->|"scores support"| node_evidence
node_adapter -.->|"uses selection"| node_selection
node_adapter -.->|"reviews dialogue"| node_dialogue
node_dialogue -.->|"uses review limits"| node_review_budget
node_dialogue -.->|"requests review"| node_ollama
node_adapter -->|"submits clip ranges"| node_clipskitty
node_eval_runner -->|"evaluates"| node_detector
node_eval_runner -->|"compares baseline"| node_baseline
node_eval_runner -->|"measures results"| node_metrics

click node_entry "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/main.py"
click node_adapter "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/adapter.py"
click node_observations "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/observations.py"
click node_evidence "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/scoring.py"
click node_taxonomy "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/taxonomy.py"
click node_detector "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/detector.py"
click node_selection "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/selection.py"
click node_dialogue "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/dialogue.py"
click node_review_budget "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/review.py"
click node_eval_runner "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/run.py"
click node_baseline "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/baseline.py"
click node_metrics "https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_clipskitty,node_entry,node_adapter toneBlue
class node_observations,node_evidence,node_taxonomy,node_detector,node_selection toneAmber
class node_dialogue,node_review_budget toneMint
class node_eval_runner,node_baseline,node_metrics toneRose
class node_streamer,node_vod,node_ollama toneIndigo
```

## Components

### Host integration

- **Clips Kitty**
- [SDK entry point](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/main.py): `src/main.py`
- [Job adapter](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/adapter.py): `src/gta_highlights/adapter.py`

### Moment detection

- [Evidence collection](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/observations.py): `src/gta_highlights/observations.py`
- [Evidence and scoring](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/scoring.py): `src/gta_highlights/scoring.py`
- [Event taxonomy](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/taxonomy.py): `src/gta_highlights/taxonomy.py`
- [Highlight detector](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/detector.py): `src/gta_highlights/detector.py`
- [Candidate selection](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/selection.py): `src/gta_highlights/selection.py`

### Dialogue review

- [Dialogue discovery](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/dialogue.py): `src/gta_highlights/dialogue.py`
- [Review budget and cache](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/src/gta_highlights/review.py): `src/gta_highlights/review.py`

### Evaluation

- [Fixture evaluator](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/run.py): `evaluation/run.py`
- [Energy baseline](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/baseline.py): `evaluation/baseline.py`
- [Temporal metrics](https://github.com/colingpt9/grand-theft-auto-6-clips-kitty-plugin/blob/main/evaluation/metrics.py): `evaluation/metrics.py`

### Other components

- **Streamer**
- **Stream VOD**
- **Local Ollama model**

## Connections

- Streamer → Stream VOD: provides (evidence: `README.md`)
- Stream VOD → Clips Kitty: adds VOD (evidence: `README.md`)
- Clips Kitty → SDK entry point: invokes plugin (evidence: `src/main.py`)
- SDK entry point → Job adapter: runs (evidence: `src/main.py`)
- Job adapter → Evidence collection: collects evidence (evidence: `src/gta_highlights/adapter.py`)
- Evidence collection → Evidence and scoring: creates records (evidence: `src/gta_highlights/observations.py`)
- Job adapter → Highlight detector: detects highlights (evidence: `src/gta_highlights/adapter.py`)
- Highlight detector → Event taxonomy: classifies cues (evidence: `src/gta_highlights/detector.py`)
- Highlight detector → Evidence and scoring: scores support (evidence: `src/gta_highlights/detector.py`)
- Job adapter → Candidate selection: uses selection (evidence: `src/gta_highlights/adapter.py`)
- Job adapter → Dialogue discovery: reviews dialogue (evidence: `src/gta_highlights/adapter.py`)
- Dialogue discovery → Review budget and cache: uses review limits (evidence: `src/gta_highlights/dialogue.py`)
- Dialogue discovery → Local Ollama model: requests review
- Job adapter → Clips Kitty: submits clip ranges (evidence: `README.md`)
- Fixture evaluator → Highlight detector: evaluates (evidence: `evaluation/run.py`)
- Fixture evaluator → Energy baseline: compares baseline (evidence: `evaluation/run.py`)
- Fixture evaluator → Temporal metrics: measures results (evidence: `evaluation/run.py`)
