Tools für Stichprobenstrategien — MCP-Tool-Referenz
Die Tools für Stichprobenstrategien legen demografische Zielverteilungen fest, um repräsentative Stichproben von Befragten zu bilden. Eine Strategie beschreibt eine Grundgesamtheit: ihre Faktoren – demografische Dimensionen mit Zielanteilen – und wie die Übereinstimmung damit bewertet wird (quality_metric, aggregation_method). Die Pool-Erzeugung nutzt diese Faktoren, um Befragte auszuwählen, die zu Ihrem Stichprobendesign passen.
Eine Strategie enthält nur Faktoren der Befragten – Attribute, die bekannt sind, bevor jemand antwortet. Ein Ziel für eine Umfrageantwort (zum Beispiel ein Benchmark aus Wahlergebnissen oder einer Volkszählung) gehört in das Bundle, das die Antworten enthält, und zwar als reines Benchmark-Kalibrierungsziel: siehe set_calibration_targets.
list_sampling_strategies
Abschnitt betitelt „list_sampling_strategies“Listet alle Stichprobenstrategien auf, optional nach Projekt oder Namen gefiltert.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
project_id |
string |
Nein | — | Nach Projekt-ID filtern |
name |
string |
Nein | — | Teilzeichenfolgen-Filter ohne Berücksichtigung der Groß- und Kleinschreibung |
limit |
integer |
Nein | 100 |
Maximale Anzahl an Ergebnissen |
Rückgabe: { data: [...], count, limit }. Jeder Eintrag enthält id, name, description, project_id, factor_count, quality_metric, created_at.
get_sampling_strategy
Abschnitt betitelt „get_sampling_strategy“Ruft eine Stichprobenstrategie anhand ihrer ID ab, einschließlich der vollständigen Faktordefinitionen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
strategy_id |
string |
Ja | — | UUID der Strategie |
Rückgabe: Das vollständige Strategieobjekt: id, name, description, project_id, factors, quality_metric, aggregation_method, is_default, created_at, modified_at.
create_sampling_strategy
Abschnitt betitelt „create_sampling_strategy“Legt eine Stichprobenstrategie mit Faktoren für demografische Verteilungen an.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Ja | — | Name der Strategie |
project_id |
string |
Nein | — | ID des übergeordneten Projekts |
factors |
object[] |
Nein | — | Definitionen der Verteilungsfaktoren (siehe unten) |
quality_metric |
string |
Nein | "rmse" |
"rmse", "mae", "chi_square" oder "max_deviation"; jeder andere Wert wird abgelehnt, und es wird nichts angelegt |
description |
string |
Nein | — | Beschreibung der Strategie |
Rückgabe: Das vollständige Strategieobjekt (wie bei get_sampling_strategy).
Faktorschema
Abschnitt betitelt „Faktorschema“Jeder Faktor im Array factors definiert eine Dimension der Befragten. Ein Schlüssel, den das folgende Schema nicht aufführt, wird als Validierungsfehler abgelehnt (REST 422). Ein Faktor, der noch das ausgemusterte Feld source trägt, schlägt also fehl, statt stillschweigend verworfen zu werden:
| Feld | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Ja | — | Anzeigename (z. B. "Gender") |
attribute_path |
string |
Ja | — | Attribut der Befragten (z. B. "gender" oder ein benutzerdefiniertes Attribut) |
target_distribution |
object |
Ja | — | Zuordnung Kategorie → Anteil. Muss sich zu 1.0 summieren (Toleranz ±0.01) |
factor_type |
string |
Nein | "discrete" |
"discrete", "bucketed" oder "geographic" |
bucket_ranges |
array |
Nein | — | Für den Typ bucketed: Liste von [min, max, label]-Tupeln |
weight |
float |
Nein | 1.0 |
Gewicht für die Bedeutung dieses Faktors |
Beispiel:
{ "name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}, "factor_type": "discrete", "weight": 1.0}create_default_strategy
Abschnitt betitelt „create_default_strategy“Legt eine Strategie mit den Standardfaktoren für Geschlechts- und Altersverteilung an.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Ja | — | Name der Strategie |
project_id |
string |
Nein | — | ID des übergeordneten Projekts |
Rückgabe: Das vollständige Strategieobjekt (wie bei get_sampling_strategy).
Standardfaktoren:
- Geschlecht: männlich 48 %, weiblich 50 %, divers 2 %
- Altersgruppe: 18–24 (15 %), 25–34 (20 %), 35–44 (20 %), 45–54 (18 %), 55–64 (15 %), 65+ (12 %)
update_sampling_strategy
Abschnitt betitelt „update_sampling_strategy“Aktualisiert eine bestehende Stichprobenstrategie (partielle Aktualisierung – nur die übergebenen Felder ändern sich).
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
strategy_id |
string |
Ja | — | UUID der Strategie |
name |
string |
Nein | — | Neuer Name |
description |
string |
Nein | — | Neue Beschreibung |
factors |
object[] |
Nein | — | Alle Faktoren ersetzen (nicht zusammenführen) |
quality_metric |
string |
Nein | — | Neue Qualitätsmetrik, eine der vier oben genannten; jeder andere Wert wird abgelehnt, und es ändert sich nichts |
Rückgabe: Das vollständige Strategieobjekt (wie bei get_sampling_strategy).
Eine Aktualisierung der Strategie ändert nie einen bereits daraus gezogenen Pool: Jeder Pool behält die Ziehungseinstellungen, mit denen er erzeugt wurde, und eine Aktualisierung des Pools zieht anhand der aktuellen Faktoren der Strategie in der Größe neu, die der Pool selbst gespeichert hat.
delete_sampling_strategy
Abschnitt betitelt „delete_sampling_strategy“Löscht eine Stichprobenstrategie. Geschützt, wenn die Strategie die Standardstrategie ist oder verknüpfte Pools hat.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
strategy_id |
string |
Ja | — | UUID der Strategie |
Rückgabe: { strategy_id, deleted }
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Validierung der Faktoren
Abschnitt betitelt „Validierung der Faktoren“| Situation | Antwort |
|---|---|
| Pflichtfeld fehlt | {"error": "Each factor must have 'name', 'attribute_path', and 'target_distribution'"} |
| Verteilung summiert sich nicht zu 1.0 | {"error": "Factor '{name}' target_distribution must sum to 1.0 (got {sum:.3f})"} |
Ein Schlüssel, den das Faktorschema nicht deklariert (z. B. source) |
validation_error (REST 422) mit Nennung des zusätzlichen Felds |
Die Validierung der Faktoren gilt sowohl für create_sampling_strategy als auch für update_sampling_strategy.
Schutz der Standardstrategie
Abschnitt betitelt „Schutz der Standardstrategie“| Situation | Antwort |
|---|---|
| Standardstrategie ändern | {"error": "Cannot modify the default sampling strategy"} |
| Standardstrategie löschen | {"error": "Cannot delete the default sampling strategy"} |
Schutz verknüpfter Pools
Abschnitt betitelt „Schutz verknüpfter Pools“| Situation | Antwort |
|---|---|
| Strategie mit Pools löschen | {"error": "Cannot delete strategy: {count} pool(s) are linked to it"} |
Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Situation | Antwort |
|---|---|
| Strategie nicht gefunden | {"error": "Strategy {id} not found"} |
| Kein Eigentümer des Projekts der Strategie | {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"} |