Travailler avec autoresearch

Autoresearch répond à une question récurrente par modèle : qui dans une population fera une action cible dans un horizon donné ? Par exemple, « quels utilisateurs actifs ouvriront un rapport dans les 7 prochains jours ? ».

1. L'utilisateur nomme une cible (un événement ou une action PostHog), une population et un horizon en jours.
2. Un agent d'entraînement s'exécute dans un sandbox PostHog. Il écrit du SQL de feature et un modèle, évalue chaque expérience sur un ensemble de validation, conserve ce qui améliore l'AUC de validation et rejette le reste.
3. Le serveur choisit le champion parmi les expériences conservées. L'agent propose ; le backend décide.
4. À chaque cadence (quotidiennement par défaut, à 02:00 UTC), le champion score la population d'inférence. Chaque personne scorée reçoit un événement autoresearch_prediction avec sa probabilité. Une personne qui se résout à un ID distinct actuel reçoit également la propriété personne du modèle, par exemple predicted_p_adopt_insights_14d.
5. Quand l'horizon d'une date de prédiction est passé, la validation en ligne vérifie les scores par rapport à ce qui s'est réellement passé et enregistre l'AUC réalisé.

Dans l'interface PostHog, l'entité s'appelle un modèle. L'API et les outils l'appellent un pipeline. Utilisez « modèle » quand vous parlez aux gens.

Autoresearch est derrière le feature flag autoresearch. L'entraînement s'exécute dans un sandbox cloud, il a donc aussi besoin d'accès à PostHog Desktop. Si les outils autoresearch-* manquent, le projet n'a probablement pas encore accès.

Choisir le travail

Créer, entraîner, scorer

Le chemin habituel est court. La description de chaque outil nomme ses prérequis et refus, donc lisez-la avec info avant le premier appel.

1. Résoudre ou définir. Les templates couvrent les questions courantes (activité, risque d'inactivité, retour après première utilisation, adoption de feature, comportement répété). Une définition personnalisée fonctionne quand aucun template ne convient. Voir defining-a-question.md.
2. Valider. posthog:autoresearch-validate-create avec la même cible, horizon, lookback et populations que ceux avec lesquels vous créerez. Il retourne le taux de base, les comptages positifs et négatifs, et des avertissements. Corrigez tout ce qui met can_proceed à false, et informez l'utilisateur des avertissements sans blocage.
3. Créer. posthog:autoresearch-create. Le nouveau modèle est un draft jusqu'à ce que l'entraînement commence.
4. Entraîner. posthog:autoresearch-train-create lance une exécution d'agent qui prend du temps (souvent des dizaines de minutes). Cela coûte du sandbox et du temps LLM réels, donc confirmez auprès de l'utilisateur avant d'en lancer un, et ne lancez jamais une deuxième exécution pendant qu'une est en cours. Un 403 signifie soit que l'appel venait de l'intérieur d'un sandbox (demandez à l'utilisateur de cliquer sur Start training sur la page du modèle), soit que l'utilisateur n'a pas accès à PostHog Desktop (la page refusera aussi). Lisez le message d'erreur pour les distinguer.
5. Attendre. Interrogez posthog:autoresearch-training-runs-list à un rythme détendu. Pendant que la première exécution est en cours, le modèle est en bootstrapping, et l'absence de champion est normale.
6. Scorer. Après qu'un champion soit promu, le prochain balayage quotidien score la population. posthog:autoresearch-score-create score aujourd'hui maintenant ; appelez-le une fois, puis interrogez posthog:autoresearch-runs-list. Un deuxième score manuel pour la même date peut dupliquer les prédictions.

Pause, reprise et suppression ne se trouvent que dans le menu du modèle dans l'interface utilisateur. La pause arrête le scoring et les nouvelles exécutions d'entraînement. Une exécution d'entraînement déjà en cours continue à s'exécuter, et elle peut toujours promouvoir un champion.

État du modèle

Les iteration_count et best_holdout_score de l'exécution d'entraînement sont écrits seulement quand l'exécution se termine. Une exécution saine peut afficher 0 itérations alors que ses expériences sont déjà enregistrées, donc ne déclarez pas une exécution bloquée juste sur le compteur.

Comment parler des résultats

• Holdout AUC est le score sur les données d'entraînement retenues. Il indique à quel point le modèle a bien classé les gens dans le passé. Traitez-le comme une promesse.
• Realized AUC est le score par rapport aux résultats réels après le passage de l'horizon. Traitez-le comme la preuve. Il l'emporte sur l'holdout AUC chaque fois qu'il existe.
• L'interface label la qualité comme Strong à 0,8 AUC et plus, Fair à 0,7 et plus, et Weak en dessous, et dit si le label vient du test seul ou est confirmé par des résultats réels. Utilisez les mêmes mots pour que l'agent et l'interface s'accordent.
• Lift at 10% est le titre en langage clair : « les 10 % du haut sont 3,2× plus susceptibles de faire X que la moyenne ».
• Le score est une probabilité, mais sur une cible rare, il se lit souvent mieux comme un classement. Dites-le quand le taux de base est en dessous de quelques pourcent.

reading-model-quality.md couvre l'étalonnage, les segments de vraisemblance, la couverture et quoi dire quand les nombres ne concordent pas.

Garde-fous à garder en tête

• Changer la question signifie un nouveau modèle. Les champs sur lesquels un modèle a été entraîné (cible, horizon, populations) sont figés une fois qu'un modèle existe. Créez un nouveau modèle plutôt que d'en éditer un.
• Autoresearch entraîne seulement sur les utilisateurs identifiés. Le trafic anonyme ne compte pas vers les données d'entraînement, donc le volume d'événement brut peut surévaluer ce qui est disponible. Fiez-vous aux comptages de validation.
• Les scores sont indexés sur la personne. Un modèle dont les scores sont presque tous la même valeur a généralement un problème d'identifiant, pas un signal faible. Voir troubleshooting-and-steering.md.
• Lisez le nom de la propriété de sortie, ne le deviné pas. Prenez output_person_property dans posthog:autoresearch-retrieve. Un nom dérivé inclut la cible et l'horizon (predicted_p_<target>_<horizon>d), et les templates utilisent leur propre préfixe, donc deux modèles sur une cible ne s'écrasent pas mutuellement.
• Un modèle coûte de l'argent à entraîner et à interroger pour scorer. Une population très large score en lots roulants (environ 45 000 personnes par exécution), donc tout le monde ne reçoit pas un score frais chaque jour. La validation vous dit combien d'exécutions un rescore complet prend.

Apportez votre propre agent

Un agent en dehors de PostHog (sur un ordinateur portable, par exemple) peut entraîner un modèle pour un pipeline existant. Il ouvre une exécution avec posthog:autoresearch-training-runs-create, enregistre chaque expérience avec posthog:autoresearch-training-runs-iterations-create, télécharge son bundle avec posthog:autoresearch-training-runs-artifacts-upload-create, et termine avec posthog:autoresearch-training-runs-complete-create. Il tire les données d'entraînement avec posthog:execute-sql, parce que posthog:autoresearch-materialize-features écrit seulement dans un sandbox PostHog. Lisez d'abord posthog:autoresearch-training-runs-history pour réutiliser ce que les exécutions antérieures sur la même cible ont appris. La description de l'outil d'itération est le contrat pour du SQL de feature valide : lisez-la en entier avant la première itération.