---
name: cowork.qualifiziere_assets
description: "Pipeline-Skill (Track-α-2-Folge-5, ADR_0075) fuer strukturfunktionale Qualifizierung des Recherche-Asset-Pools nach Substanz-Recherche. Trigger: 'Qualifiziere Assets fuer Sequenz <id>', 'Qualifiziere Asset-Index <pfad>'. Eingabe: <sequenz>/_asset_index.yaml (asset_index_v1, ADR_0069). Output: <sequenz>/_asset_qualifikation.yaml (asset_qualifikation_v1, proposed). 5-Stages-Pipeline (Dedupe + Embedder + Clusterer + Role-Classifier + Person-Detector). Liefert Topoi-Cluster (funktional aequivalente Bilder) + Unicorns (ikonische Einzelwerke) + didaktische_rolle pro Asset (anker/topos-vertreter/austauschbar/unicorn-leitplanke/differenzierungs-pool/personen-anker). Empfohlen post cowork.recherchiere_substanz / pre cowork.erstelle_sequenz_initial. NICHT triggern fuer Pre-TUV-Briefing (separater Skill cowork.recherchiere_briefing). Modular erweiterbar via QualifierStage-ABC."
schema_pin: substanz_recherche_v1
---

# cowork.qualifiziere_assets

## Zweck

Strukturfunktionale Qualifizierung des Asset-Pools nach Substanz-Recherche.
Beantwortet drei Fragen:
1. **Welche Bilder sind funktional aequivalent?** (Topoi-Cluster)
2. **Welche Bilder sind ikonisch / nicht-ersetzbar?** (Unicorns)
3. **Welche eignen sich als Sequenz-Leitplanke vs Differenzierungs-Pool?** (didaktische Rolle)

Modul-Architektur: 5-Stages-Pipeline (Dedupe → Embedder → Clusterer → Role → Person),
einzeln aktivierbar, erweiterbar via QualifierStage-ABC (siehe ADR_0075 §2.1).

## Trigger

```
Qualifiziere Assets fuer <sequenz_id>
Qualifiziere Assets aus <pfad-zu-asset_index.yaml>
```

## Pflicht-Pre-Bedingung

- `<sequenz>/_asset_index.yaml` muss existieren (Output von `cowork.recherchiere_substanz`)
- Schema-PASS gegen `asset_index_v1.json`

## Workflow

1. **Asset-Index laden**: `<sequenz>/_asset_index.yaml` → list von Asset-Dicts.
2. **Pipeline-Konstruktion** via `core.lib.asset_qualifier.build_default_pipeline()`:
   - Default-Konfig nutzt 5 Stages mit konservativen Schwellwerten
   - Lehrkraft-spezifische Konfig optional (z.B. niedrigerer `distance_threshold` fuer feinere Cluster)
3. **Pipeline-Run** ueber den Asset-Pool. Pro Stage:
   - DedupeStage: erkennt URL-/Title-Duplikate, waehlt canonical-Asset (hoechste Aufloesung × beste Lizenz × Adapter-Prioritaet)
   - EmbedderStage: Char-N-Gram TF-IDF Embedding (Token-frei lokal, ~50ms pro 100 Assets)
   - ClustererStage: scipy.cluster.hierarchy Agglomerative mit distance-threshold (parameter-frei)
   - RoleClassifierStage: heuristische didaktische_rolle pro Asset
   - PersonDetectorStage: Identifikationsfigur-Erkennung (LeMo-Slug + dcCreator + Caption-Heuristik)
4. **Audit-Pre-Commit**: Schema-Validate via `validate_asset_qualifikation.py` (proposed; F1-ABSTAIN bei nicht-konfiguriert)
5. **Persist** als `<sequenz>/_asset_qualifikation.yaml`
6. **Auto-Suggest** am Output-Ende.

## Output-Struktur

```
<project>/<schul-jahr>/<klasse>/<lernbereich>/<sequenz-slug>/
├── substanz_recherche.yaml       # cowork.recherchiere_substanz
├── _asset_index.yaml             # asset_index_v1 (proposed)
└── _asset_qualifikation.yaml     # asset_qualifikation_v1 (proposed, NEU)
```

## Auto-Suggest am Output-Ende

```
✓ Asset-Qualifizierung persistiert (<n> Assets, <k> Topoi-Cluster, <u> Unicorns, <p> Personen):
  Pfad: <output>
  Topoi-Pool (kandidaten fuer Sequenz-Leitplanken):
    - cluster_1 "{label}" (groesse <n>): leitplanken_kandidat <asset_id>
    - cluster_2 "{label}" (groesse <m>): ...
  Unicorns (ikonische Einzelwerke):
    - <asset_id>: "{didaktische_funktion_label}"
  Identifikationsfiguren-Kandidaten:
    - {person} ({person_typ}): <asset_id>

Naechster sinnvoller Schritt: 'Erstelle Sequenz-Initial fuer <fach> <klasse> <lernbereich>' triggert
cowork.erstelle_sequenz_initial — konsumiert _asset_qualifikation.yaml fuer
Leitplanken-Anker + Differenzierungs-Pool.
```

## Stage-Konfiguration (optional)

```python
from core.lib.asset_qualifier import build_default_pipeline

pipeline = build_default_pipeline(
    dedupe={"url_basename_match": True, "title_exact_match": True},
    embedder={"ngram_n": 3, "max_features": 2048},
    clusterer={"method": "average", "distance_threshold": 0.55},
    role_classifier={"unicorn_min_quality": 0.6, "differenzierungs_min_cluster_size": 10},
)
```

## Modularitaet + Erweiterbarkeit

Neue Stages koennen ohne Refactor hinzukommen (ADR_0075 §2.1). Beispiele
fuer zukuenftige Erweiterungen (Re-Visit-Trigger):

- `SchwierigkeitsgradStage` — Cluster-Granularitaet × Caption-Komplexitaet
- `DifferenzierungsAchsenStage` — Hi-/Lo-Road-Pool-Splitting
- `KreuzModalitaetsStage` — Bild + Text + Audio + Video kombinatorisch
- `PerceptualImageHashStage` — phash-basiertes Dedupe via Image-Download
- `SentenceTransformerEmbedderStage` — bessere semantische Cluster (opt-in)

Jede neue Stage subklasst `QualifierStage` mit name/version/requires/run().
Pipeline-Orchestrator (`core/lib/asset_qualifier/pipeline.py`) registriert sie
in beliebiger Reihenfolge solange requires-Reihenfolge respektiert ist.

## Cross-Refs

- `core/lib/asset_qualifier/` — Pipeline + 5 Default-Stages
- `core/state/schemas/asset_qualifikation_v1.json` (proposed)
- `core/tests/test_asset_qualifier.py` — 33 Unit + E2E-Tests
- ADR_0075 — Architektur-Entscheidung
- ADR_0069 — Asset-Indexer (Input-Layer)