Entités Doctrine

Synapse Core utilise des entités Doctrine MappedSuperclass que vous étendez dans votre application pour activer la persistance.

Entités à étendre (obligatoires pour la persistance)

SynapseConversation : Stocke les métadonnées de la discussion (titre, propriétaire, date, statut).
SynapseMessage : Stocke le contenu des échanges (rôle, contenu texte, calls outils).

Entités de configuration

SynapseModelPreset : Configuration technique d'un modèle (température, streaming, max_tokens, options provider, etc.). Supporte le pattern sandbox.
SynapseProvider : Credentials chiffrés pour les fournisseurs (Gemini, OpenAI, OVH, etc.).
SynapseModel : Métadonnées et tarification des modèles LLM.
SynapseAgent : Configuration d'agent (system prompt, preset, ton, outils autorisés, sources RAG, accès contrôlé). Supporte le pattern sandbox.
SynapseTone : Styles de réponse (emoji, instructions de ton).
SynapseConfig : Paramètres globaux (rétention, langue, chunking, vector store actif).

Entités Workflow

`SynapseWorkflow`

Définition d'un pipeline multi-agents. Supporte le pattern sandbox.

La définition JSON suit le format pivot :

{
  "version": 1,
  "steps": [
    {
      "name": "step1",
      "agent_name": "mon_agent",
      "input_mapping": {},
      "output_key": "resultat"
    }
  ],
  "outputs": {
    "final": "$.steps.step1.output.answer"
  }
}

Toute modification du champ definition incrémente automatiquement version, garantissant la traçabilité historique.

`SynapseWorkflowRun`

Instance d'exécution d'un SynapseWorkflow. Un run est mutable pendant son exécution (statut, step courant, timings) et devient immuable une fois terminé.

Colonne	Type	Description
`workflowRunId`	`string(36)`	UUID logique propagé dans `AgentContext` et référencé par les `SynapseDebugLog`
`workflowKey`	`string(100)`	Clé dénormalisée pour survivre à la suppression de la définition
`workflowVersion`	`integer`	Version de la définition au moment du run
`status`	`enum`	`running`, `completed`, `failed`
`currentStepIndex`	`integer`	Index de la dernière étape exécutée
`stepsCount`	`integer`	Nombre total d'étapes
`input`	`json`	Données d'entrée
`output`	`json`	Sorties produites
`errorMessage`	`text`	Message d'erreur si `failed`
`totalTokens`	`integer`	Tokens totaux consommés
`durationSeconds`	`float`	Durée en secondes
`startedAt`	`datetime_immutable`	Début
`completedAt`	`datetime_immutable`	Fin (nullable si encore en cours)

La relation vers SynapseWorkflow est nullable avec onDelete: SET NULL : les runs historiques survivent à la suppression de la définition grâce au champ workflowKey dénormalisé.

Pattern Sandbox

Le pattern sandbox est utilisé par les outils MCP pour créer des entités temporaires de test.

Entités concernées

SynapseAgent — champ isSandbox boolean DEFAULT false
SynapseWorkflow — champ isSandbox boolean DEFAULT false
SynapseModelPreset — champ isSandbox boolean DEFAULT false

Règles de filtrage

Méthode	Filtre sandbox
`findAllActive()`	`isSandbox = false` — exclut les sandbox
`findAllOrdered()`	`isSandbox = false` — exclut les sandbox
`findAllPresets()`	`isSandbox = false` — exclut les sandbox
`findByKey($key)`	Aucun filtre — inclut les sandbox
`findActive()`	Aucun filtre — inclut les sandbox
`findActiveByKey($key)`	Aucun filtre — inclut les sandbox
`findSandbox()`	`isSandbox = true` — retourne uniquement les sandbox

Les entités sandbox sont invisibles dans l'admin et le chat (les listings utilisent findAllActive/Ordered/Presets) mais résolvables pour l'exécution (le moteur utilise findByKey / findActiveByKey).

Méthode de cleanup

SynapseWorkflowRunRepository::deleteByWorkflowKeys(array $keys): int supprime en lot les runs associés à une liste de workflow keys — utilisé par cleanup_sandbox avant de supprimer les workflows eux-mêmes.

Entités de suivi & comptabilité

`SynapseLlmCall`

Enregistrement atomique d'un appel LLM. Table centrale du token accounting.

Chaque appel LLM — qu'il provienne du chat, d'une génération de titre, d'une tâche automatisée ou d'un agent — produit une ligne dans cette table. Les tables synapse_conversation et synapse_message référencent synapse_llm_call via llm_call_id.

Colonne	Type	Description
`callId`	`string(36)`	UUID v4 unique de l'appel
`module`	`string`	Module source (ex: `chat`, `title`, `rag`)
`model`	`string`	Identifiant du modèle utilisé
`provider`	`string`	Provider utilisé (ex: `gemini`)
`promptTokens`	`integer`	Tokens en entrée
`completionTokens`	`integer`	Tokens générés
`totalTokens`	`integer`	Total tokens
`costModel`	`float`	Coût calculé dans la devise du provider
`costReference`	`float`	Coût converti en devise de référence
`presetId`	`?integer`	ID du preset utilisé
`agentId`	`?integer`	ID de l'agent utilisé
`userId`	`?string`	Identifiant de l'utilisateur
`conversationId`	`?string`	ULID de la conversation
`createdAt`	`datetime_immutable`	Date de l'appel

`SynapseSpendingLimit`

Plafonds de dépense par utilisateur, agent ou preset.

`SynapseSpendingLimitLog`

Historique des dépassements de limite de dépense.

Colonne	Type	Description
`userId`	`string(255)`	Utilisateur qui a déclenché le dépassement
`scope`	`enum`	`user`, `preset`, `agent`
`scopeId`	`string(255)`	Identifiant de la ressource
`period`	`enum`	`calendar_day`, `calendar_month`, `sliding_day`, `sliding_month`
`limitAmount`	`float`	Montant du plafond
`consumption`	`float`	Consommation avant l'appel dépassant
`estimatedCost`	`float`	Coût estimé de l'appel déclencheur
`overrunAmount`	`float`	Montant du dépassement
`currency`	`string(3)`	Devise (EUR, USD, etc.)
`exceededAt`	`datetime_immutable`	Date/heure du dépassement

Entités RAG & Mémoire Sémantique

`SynapseRagSource`

Représente une source de documents indexés (Google Drive, Notion, fichiers locaux, etc.).

Colonne	Type	Description
`slug`	`string(255)`	Identifiant unique (ex: `lycee_intranet`)
`name`	`string(255)`	Nom d'affichage
`description`	`text`	Description longue
`isActive`	`boolean`	Activé ou désactivé
`documentCount`	`integer`	Nombre total de documents indexés
`lastIndexedAt`	`datetime_immutable`	Dernière réindexation complète
`indexingStatus`	`string(50)`	`pending`, `indexing`, `done`, `failed`
`lastError`	`text`	Message d'erreur si indexation échouée
`totalFiles`	`integer`	Nombre total de fichiers traités
`processedFiles`	`integer`	Fichiers traités avec succès (suivi progression)

`SynapseRagDocument`

Chunk vectorisé d'un document RAG.

Colonne	Type	Description
`source`	FK	Lien vers `SynapseRagSource` (CASCADE DELETE)
`content`	`text`	Contenu du chunk
`embedding`	`json`	Vecteur numérique d'embedding (float array)
`metadata`	`json`	Métadonnées : `source_name`, `file_path`, `page_number`, etc.
`chunkIndex`	`integer`	Numéro du chunk dans le document original
`totalChunks`	`integer`	Nombre total de chunks du document
`sourceIdentifier`	`string(255)`	Identifiant unique dans la source (ex: Google Drive file ID)

`SynapseMessageAttachment`

Fichiers téléchargés attachés aux messages (images, documents, etc.).

Colonne	Type	Description
`id`	UUID	Clé primaire
`message`	FK	Lien vers `SynapseMessage`
`mimeType`	`string(100)`	Type MIME (ex: `image/png`)
`filePath`	`string(500)`	Chemin disque (ex: `var/uploads/uuid.png`)
`createdAt`	`datetime_immutable`	Date du téléchargement

`SynapseVectorMemory`

Stocke les vecteurs d'embeddings pour la recherche sémantique et la mémoire conversationnelle.

Colonne	Type	Description
`embedding`	`json`	Vecteur numérique généré par le modèle d'embedding
`payload`	`json`	Métadonnées brutes (texte, source, ids)
`content`	`text`	Texte brut dénormalisé (affichage dans le Privacy Dashboard)
`user_id`	`string(255)`	Propriétaire du souvenir — compatible UUID et entier
`scope`	`string(20)`	`user` (permanent) ou `conversation` (éphémère)
`conversation_id`	`string(255)`	Lien vers la conversation d'origine (optionnel)
`source_type`	`string(20)`	`fact`, `document`, `manual`
`created_at`	`datetime_immutable`	Date de création du souvenir

`SynapseDebugLog`

Enregistrement des échanges complets pour le mode debug. Stocke le payload brut des requêtes et réponses API, les timings, les métadonnées du modèle.

Colonne	Type	Description
`debugId`	`string(50)`	Identifiant unique de cet appel LLM
`module`	`string(100)`	Module source (ex: `chat`, `agent`, `rag`) — dénormalisé
`action`	`string(100)`	Action précise (ex: `chat_turn`, `agent_call`) — dénormalisé
`model`	`string(100)`	Modèle utilisé — dénormalisé
`totalTokens`	`integer`	Tokens totaux — dénormalisé
`parentRunId`	`string(36)`	`agentRunId` de l'exécution parente (null = appel racine)
`agentRunId`	`string(36)`	UUID de l'exécution logique de l'agent (partagé si plusieurs appels LLM pour un même agent)
`depth`	`smallint`	Profondeur d'imbrication (0 = racine)
`origin`	`string(20)`	`direct`, `code`, `config`, `ephemeral`, `workflow`
`workflowRunId`	`string(36)`	UUID du workflow englobant (null si hors workflow)
`data`	`json`	Payload complet : `preset_config`, `history`, `usage`, `turns`, `safety_ratings`, `raw_request_body`
`createdAt`	`datetime_immutable`	Date de l'appel

Requêtes racines (`findRoots`)

SynapseDebugLogRepository::findRoots() retourne les entrées de "premier niveau" visibles dans l'admin. Sont considérés comme racines :

Appels sans parent (parentRunId IS NULL) — appels directs (chat, MCP, etc.)
Appels origin = 'workflow' à depth = 1 — étapes de workflow (elles ont un parentRunId mais restent des entrées de premier niveau dans la vue admin)

!!! note "Voir aussi" - Mémoire Sémantique — utilisation de SynapseVectorMemory - Persistance — détails Doctrine pour SynapseConversation / SynapseMessage - Token Accounting — configuration du suivi via SynapseLlmCall

Synapse Core Laravel Package

Entités Doctrine

Entités à étendre (obligatoires pour la persistance)

Entités de configuration

Entités Workflow

SynapseWorkflow

SynapseWorkflowRun

Pattern Sandbox

Entités concernées

Règles de filtrage

Méthode de cleanup

Entités de suivi & comptabilité

SynapseLlmCall

SynapseSpendingLimit

SynapseSpendingLimitLog

Entités RAG & Mémoire Sémantique

SynapseRagSource

SynapseRagDocument

SynapseMessageAttachment

SynapseVectorMemory

SynapseDebugLog

Requêtes racines (findRoots)