Documentation

Présentation

Guarani AI donne à chaque version un verdict unique et expliqué. La plateforme compte trois modules, utilisables seuls ou ensemble.

Verify

Revue de code IA et conformité d'architecture sur chaque pull request : revue sémantique, budgets de performance, contrôle des contrats d'API et tests générés.

Mesh

Une passerelle compatible OpenAI devant Azure OpenAI, Amazon Bedrock, Google Vertex AI et des modèles open-weight sur GPU dédiés, avec règles de routage, bascule, cache et budgets par équipe.

Mobile CI

Des suites d'interface et de non-régression de bout en bout sur de vrais appareils Android et iOS, lancées depuis vos pipelines existants.

Concepts

Espace de travail

Le tenant de votre organisation : membres, jetons d'accès, règles, région des données et durée de conservation.

Projet

Un dépôt relié à un espace de travail, configuré par son fichier guarani.yml.

Profil

Un ensemble nommé de contrôles et de seuils, par exemple pull-request ou release.

Exécution

Une exécution d'un profil, d'une requête Mesh ou d'une suite mobile, avec ses logs et ses artefacts.

Verdict

Le résultat d'une exécution : pass, advisory ou fail, avec les constats qui l'expliquent.

Démarrage rapide

Trois commandes suffisent pour obtenir un premier verdict sur un dépôt. Il vous faut un jeton d'accès, délivré lors du provisionnement de votre espace d'essai.

npm i -g @guarani-ai/cli
guarani login
guarani verify --repo acme/core-api --profile pull-request

guarani login enregistre le jeton dans le trousseau de clés de votre système. En CI, définissez plutôt GUARANI_TOKEN.

Installer la CLI

La CLI est distribuée sur npm sous le nom @guarani-ai/cli. Elle nécessite Node.js 20 ou une version ultérieure et fonctionne sous Linux, macOS et Windows.

npm i -g @guarani-ai/cli
guarani --version

Configuration

guarani init crée guarani.yml à la racine du dépôt. Ce fichier déclare les profils, les budgets de performance, la règle et les fournisseurs Mesh, ainsi que les suites et appareils mobiles.

# guarani.yml
version: 1
project: acme/core-api

profiles:
  pull-request:
    checks: [architecture, contracts, performance]
    tests: generate-missing
    block_on: [fail]
  release:
    checks: [architecture, contracts, performance, tests]
    mobile: checkout
    block_on: [fail, advisory]

budgets:
  latency_p95_ms: 450
  memory_mb: 512

mesh:
  policy: balanced  # latency | balanced | cost
  providers: [azure-openai, amazon-bedrock, google-vertex-ai, gpu-open-weight]
  residency: us     # us | eu
  daily_budget_usd:
    payments: 66
    search: 60

mobile:
  suites:
    checkout:
      framework: maestro
      path: e2e/checkout
  devices: [pixel-8, iphone-15, galaxy-s24]
  retries: 1

Le profil se choisit avec --profile. block_on indique quels verdicts font échouer le contrôle dans votre pipeline.

Référence de la CLI

Chaque commande accepte --help. Les commandes se terminent avec le code 1 lorsque le verdict figure dans la liste block_on du profil.

# Install the CLI (Node.js 20 or later)
npm i -g @guarani-ai/cli

# Authenticate with your workspace access token
guarani login

# Create guarani.yml for this repository
guarani init

# Run the release profile and print a JSON report
guarani verify --repo acme/core-api --profile release --json

GitHub Actions

Ajoutez un workflow déclenché sur pull_request. Enregistrez le jeton de l'espace de travail dans le secret de dépôt GUARANI_TOKEN. La permission checks: write permet à la CLI de publier le verdict sous forme de check.

name: guarani
on: pull_request

permissions:
  contents: read
  checks: write
  pull-requests: write

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm i -g @guarani-ai/cli
      - run: guarani verify --profile pull-request --report github
        env:
          GUARANI_TOKEN: ${{ secrets.GUARANI_TOKEN }}

GitLab CI

Ajoutez un job exécuté sur les pipelines de merge request. Enregistrez le jeton dans une variable CI/CD masquée nommée GUARANI_TOKEN.

guarani-verify:
  stage: test
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - npm i -g @guarani-ai/cli
    - guarani verify --profile pull-request --report gitlab
  # GUARANI_TOKEN is a masked CI/CD variable in the project settings

API REST

URL de base : https://api.guarani-llc.com/v1. Authentification par Authorization: Bearer <token>. Les requêtes et les réponses sont en JSON.

Lancer une vérification

curl https://api.guarani-llc.com/v1/verifications \
  -H "Authorization: Bearer $GUARANI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1d9e2a-1842-release" \
  -d '{"repo": "acme/core-api", "ref": "refs/pull/1842/head", "profile": "release"}'

Réponse 202 Accepted :

{
  "id": "ver_01JB7Q4M2XK8",
  "status": "queued",
  "repo": "acme/core-api",
  "ref": "refs/pull/1842/head",
  "profile": "release",
  "created_at": "2026-10-25T14:02:11Z",
  "links": {
    "self": "https://api.guarani-llc.com/v1/verifications/ver_01JB7Q4M2XK8"
  }
}

Complétions de chat Mesh

L'endpoint Mesh suit le format des complétions de chat d'OpenAI : les bibliothèques clientes OpenAI existantes fonctionnent en changeant l'URL de base pour https://api.guarani-llc.com/v1/mesh. Utilisez "model": "auto" pour laisser la règle choisir, ou indiquez un modèle autorisé dans votre espace. metadata.team impute la dépense au budget d'une équipe.

curl https://api.guarani-llc.com/v1/mesh/chat/completions \
  -H "Authorization: Bearer $GUARANI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Summarize this diff"}], "metadata": {"team": "payments"}}'

Erreurs

Les erreurs utilisent les codes HTTP standard et un corps JSON comprenant un type stable, un message lisible et le request_id à mentionner lorsque vous contactez le support.

{
  "error": {
    "type": "invalid_request",
    "message": "Profile 'release' is not defined in guarani.yml.",
    "request_id": "req_7Q2M9X4K1B"
  }
}

Limites de débit et nouvelles tentatives

Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Une réponse 429 inclut Retry-After en secondes. Envoyez un en-tête Idempotency-Key sur les requêtes POST : une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse d'origine au lieu de lancer une seconde exécution.

Webhooks

Les espaces de travail peuvent s'abonner à verification.completed, mobile.run.completed et mesh.budget.threshold. Chaque envoi est signé en HMAC-SHA256 avec votre secret de webhook, dans l'en-tête Guarani-Signature (t=<timestamp>,v1=<signature>, calculé sur <timestamp>.<corps brut>). Rejetez les envois de plus de cinq minutes.

import hashlib
import hmac

def is_valid(secret: bytes, body: bytes, header: str) -> bool:
    # header looks like: t=1761400931,v1=5f2b...
    parts = dict(item.split("=", 1) for item in header.split(","))
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

SDK

Des SDK typés encapsulent les mêmes endpoints REST et gèrent pour vous les nouvelles tentatives, les clés d'idempotence et la pagination.

TypeScript

npm i @guarani-ai/sdk

import { Guarani } from "@guarani-ai/sdk";

const guarani = new Guarani({ token: process.env.GUARANI_TOKEN });

const run = await guarani.verifications.create({
  repo: "acme/core-api",
  ref: "refs/pull/1842/head",
  profile: "release",
});

// Polls until the verdict is ready
const result = await guarani.verifications.wait(run.id);
console.log(result.verdict, result.findings.length);

Python

pip install guarani-ai

import os
from guarani_ai import Guarani

client = Guarani(token=os.environ["GUARANI_TOKEN"])

run = client.verifications.create(
    repo="acme/core-api",
    ref="refs/pull/1842/head",
    profile="release",
)

# Polls until the verdict is ready
result = client.verifications.wait(run.id)
print(result.verdict, len(result.findings))

Support

Écrivez à sylvain@guarani-llc.com. Indiquez le request_id de toute réponse d'erreur et l'identifiant de l'exécution concernée. Pendant la bêta privée, les espaces provisionnés obtiennent leurs réponses directement de l'ingénieur qui construit le produit.