Barrel
EN GitHub

Une branche par exécution d’agent

Créez une branche de la base avant l’exécution d’un agent, laissez l’agent écrire dans la copie, relisez ce qui a changé, puis fusionnez-la ou jetez-la. Créez une branche d’un instant passé pour récupérer ce qu’une exécution a cassé.

Construit avec la timeline de barrel : barrel:branch/3, merge/1 et delete/1, les mêmes opérations en REST et sous forme des outils MCP branch_create et merge.

Le problème

Laisser un agent modifier des données en production est risqué, et copier une base pour lui donner un bac à sable est lent et vous laisse retrouver les différences à la main. Quand une exécution tourne mal, vous voulez les données telles qu’elles étaient avant son début.

Comment les pièces s’assemblent

  1. Votre orchestrateur

    • Avant l’exécution branch/3, une branche en temps constant
    • L’agent n’écrit que dans la branche
  2. branch/3
  3. Barrel

    • main données de production, intactes pendant l’exécution
    • run_42 la branche : une base ordinaire
  4. changes, puis merge
  5. Relecture

    • Changements depuis la branche ce qu’a fait l’exécution
    • merge/1 ou delete/1 la garder ou la jeter

La branche partage ses fichiers avec main en copie à l’écriture, jusqu’à ce que l’un des deux côtés compacte. Ses écritures portent leur propre identifiant de source, ce qui permet à une fusion de distinguer ce que la branche a fait de ce dont elle a hérité.

Le construire

Cinq étapes. Les exemples REST et MCP utilisent une base nommée demo et une branche demo-exp, comme dans l’exécution enregistrée.

  1. Créer une branche avant l’exécution

    Une branche est un point de contrôle des stockages par liens physiques : la créer coûte autant quelle que soit la taille. Une branche en mode enregistrement reçoit son propre stockage vectoriel, reconstruit à partir des embeddings déjà stockés dans les documents.

    {ok, Run} = barrel:branch(Db, run_42,
        #{vectordb => #{db_path => "data/run_42_vec"}}).
    Réponse REST, d’après une exécution enregistrée
    HTTP/1.1 201 Created
    {"ok":true,"parent":"demo","fork_hlc":"AAABobh22gAAAAAA",
     "branch":"demo-exp"}
  2. Laisser l’agent écrire dans la branche

    La branche accepte lectures, écritures, requêtes et recherche comme n’importe quelle base. Donnez son nom à l’agent ; main ne change pas.

    {ok, D} = barrel:get_doc(Run, <<"kb:201">>),
    {ok, _} = barrel:put_doc(Run,
        D#{<<"title">> => <<"Export invoices and credit notes">>}).
  3. Relire ce que l’exécution a changé

    Lisez les changements de la branche depuis l’instant de sa création. fork_hlc est un curseur de changements.

    {ok, #{fork_hlc := Fork}} = barrel:info(Run),
    {ok, Changed, _Last} = barrel:changes(Run, Fork).
  4. La fusionner, ou la jeter

    Une fusion n’envoie que les documents modifiés par la branche. Les modifications faites entre-temps sur main aux mêmes documents deviennent des conflits ordinaires. Une nouvelle fusion plus tard est incrémentale.

    {ok, _Report} = barrel:merge(Run),
    ok = barrel:delete(Run).
    Réponse REST de la fusion, d’après une exécution enregistrée (abrégée)
    {"failed":[],"last_merged":"AAABobh224EAAAAA",
     "docs_read":1,"docs_written":1,"doc_write_failures":0,
     "att_sync":{"atts_written":0, …}, …}
  5. Retrouver un état d’avant l’exécution

    Gardez un curseur de changements avant chaque exécution. Une branche créée avec at sur ce curseur vous donne chaque document tel qu’il était alors, à côté des données d’aujourd’hui, tant que l’instant est dans la fenêtre de rétention (30 jours par défaut). En REST, at_time accepte aussi une date RFC 3339.

    {ok, _, Before} = barrel:changes(Db, first),
    %% ... the run happens ...
    {ok, Then} = barrel:branch(Db, before_run_42,
        #{at => Before,
          vectordb => #{db_path => "data/before_42_vec"}}).

Ce que fait Barrel

  • Crée une branche en temps constant et l’isole entièrement
  • Ne fusionne que ce que la branche a changé, par le mécanisme de réplication
  • Garde comme conflits les modifications concurrentes des deux côtés
  • Restaure un instant passé dans la fenêtre de rétention
  • Reconstruit les vecteurs d’une branche en mode enregistrement à partir des embeddings stockés

Ce que fait votre application

  • Nomme une branche par exécution et y dirige l’agent
  • Décide de ce qu’est une relecture : une personne, une suite de tests ou un autre agent
  • Résout les conflits laissés par une fusion
  • Supprime les branches dont elle n’a plus besoin

Limites

  • La filiation est linéaire : une branche d’une branche est refusée avec cannot_branch_a_branch.
  • Un instant passé antérieur au plancher de l’historique échoue avec pitr_window_exceeded.
  • Une branche d’un instant passé n’est pas refusionnée comme un retour arrière ; ramener main à un instant donné n’est pas encore disponible.
  • Les branches ordinaires (hors mode enregistrement) démarrent avec un stockage vectoriel vide.
  • Sur une branche d’un instant passé, les pièces jointes sont celles du moment de la création de la branche, pas de l’instant choisi.
  • Il n’y a pas de politique de conflit par fusion ; c’est le conflict_resolver du parent qui s’applique. Un jeton de capacité ne peut pas atteindre une branche de son espace ; branch_create et merge demandent des droits d’administration.

Aller plus loin

Haut et bas pour se déplacerEntrée pour ouvrir