Crée de façon idempotente une étude temporaire pour un traitement long : extraction de document ou analyse PPA. Retourne un reçu opaque, un statut et une expiration ; utilisez get_analysis_study pour suivre le traitement. L’entrée brute est supprimée à la fin du job et le résultat expire sous 24 heures. Cette opération crée un état temporaire mais n’agit jamais auprès d’un fournisseur ni d’un compte client.
View input schema
{
"type": "object",
"properties": {
"idempotency_key": {
"type": "string",
"minLength": 16,
"maxLength": 200,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Valeur opaque stable (ex. UUID) pour réessayer la même création."
},
"capability_id": {
"description": "Identifiant exact retourné par list_capabilities, pas un texte libre.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"target_tool": {
"type": "string",
"enum": [
"extract_energy_document",
"assess_ppa"
],
"description": "Traitement long à exécuter."
},
"arguments": {
"anyOf": [
{
"type": "object",
"properties": {
"document_kind": {
"type": "string",
"enum": [
"bill",
"contract"
],
"description": "Type de document."
},
"segment": {
"type": "string",
"enum": [
"residentiel",
"professionnel"
],
"description": "Audience du document ; ne fixe ni le profil Enedis ni la classe C4/C5."
},
"evaluation_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Date d’évaluation YYYY-MM-DD, pas la date d’effet du contrat."
},
"document_base64": {
"description": "PDF en base64, 10 Mo max ; une seule représentation du document.",
"type": "string",
"minLength": 1,
"maxLength": 14100000
},
"document_text": {
"description": "Texte déjà extrait ; une seule représentation du document.",
"type": "string",
"minLength": 1,
"maxLength": 100000
},
"document_file": {
"description": "PDF temporaire ChatGPT ; une seule représentation du document.",
"type": "object",
"properties": {
"download_url": {
"type": "string",
"format": "uri",
"description": "URL HTTPS temporaire du PDF, soumise aux restrictions SSRF."
},
"file_id": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Identifiant opaque du fichier temporaire."
},
"mime_type": {
"description": "Type MIME, application/pdf.",
"type": "string",
"maxLength": 200
},
"file_name": {
"description": "Nom du fichier.",
"type": "string",
"maxLength": 500
}
},
"required": [
"download_url",
"file_id"
],
"additionalProperties": false
}
},
"required": [
"document_kind",
"segment",
"evaluation_date"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"customer": {
"type": "object",
"properties": {
"requested": {
"description": "Le client demande explicitement une évaluation PPA.",
"type": "boolean"
},
"useUploadedProductionForPpa": {
"description": "Utiliser la production fournie pour le scénario PPA uniquement si explicitement autorisé.",
"type": "boolean"
},
"productionAllocationPct": {
"description": "Pourcentage de la production affecté au PPA, de 0 à 100.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"role": {
"description": "Rôle du client : acheteur, producteur ou les deux (prosumer).",
"type": "string",
"enum": [
"buyer",
"producer",
"prosumer"
]
},
"structure": {
"description": "Structure du PPA : physique, avec intermédiaire, sur site ou virtuelle ; unknown si non documentée.",
"type": "string",
"enum": [
"physical",
"sleeved",
"onsite",
"virtual"
]
},
"volumeBasis": {
"description": "Mode d’allocation du volume PPA explicitement déclaré.",
"type": "string",
"enum": [
"pay_as_produced",
"baseload",
"pay_as_consumed",
"fixed_volume"
]
},
"annualVolumeMwh": {
"description": "Volume annuel PPA en MWh.",
"type": "number",
"exclusiveMinimum": 0
},
"annualConsumptionMwh": {
"description": "Consommation annuelle du client en MWh.",
"type": "number",
"exclusiveMinimum": 0
},
"annualProductionMwh": {
"description": "Production annuelle du client en MWh.",
"type": "number",
"exclusiveMinimum": 0
},
"strikeEurMwh": {
"description": "Prix PPA contractuel ou de scénario en €/MWh, jamais une prévision.",
"type": "number"
},
"termYears": {
"description": "Durée contractuelle envisagée en années.",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 60
},
"discountRatePct": {
"description": "Taux d’actualisation annuel déclaré en pourcentage.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"annualFeesEur": {
"description": "Frais annuels du scénario PPA en euros.",
"type": "number",
"minimum": 0
},
"upfrontCostEur": {
"description": "Coût initial du scénario PPA en euros.",
"type": "number",
"minimum": 0
},
"collateralEur": {
"description": "Garantie financière immobilisée en euros.",
"type": "number",
"minimum": 0
},
"liquidityBudgetEur": {
"description": "Trésorerie disponible déclarée en euros.",
"type": "number",
"minimum": 0
},
"commitmentHorizonYears": {
"description": "Horizon d’engagement acceptable déclaré en années.",
"type": "number",
"exclusiveMinimum": 0
},
"goRequired": {
"description": "Le client exige les garanties d’origine.",
"type": "boolean"
},
"goTransferred": {
"description": "Le contrat prévoit le transfert des garanties d’origine.",
"type": "boolean"
},
"supportScheme": {
"description": "Régime de soutien public déclaré pour le scénario.",
"type": "string"
},
"accountingStandard": {
"description": "Référentiel comptable applicable déclaré.",
"type": "string",
"enum": [
"french_gaap",
"ifrs",
"unknown"
]
},
"scenarios": {
"description": "Scénarios de prix et de volumes fournis par le client ; jamais des prévisions.",
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Nom du scénario ou de l’alternative fournie."
},
"marketPriceEurMwh": {
"type": "number",
"description": "Prix de marché de scénario en €/MWh, explicitement fourni."
},
"settlementPriceEurMwh": {
"description": "Prix de règlement de scénario en €/MWh, explicitement fourni.",
"type": "number"
},
"productionChangePct": {
"description": "Variation de production du scénario en pourcentage.",
"type": "number",
"minimum": -100,
"maximum": 300
},
"consumptionChangePct": {
"description": "Variation de consommation du scénario en pourcentage.",
"type": "number",
"minimum": -100,
"maximum": 300
}
},
"required": [
"name",
"marketPriceEurMwh"
]
}
},
"alternatives": {
"description": "Alternatives explicitement fournies, évaluées sur le même périmètre et la même période.",
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Nom du scénario ou de l’alternative fournie."
},
"annualNetEur": {
"type": "number",
"description": "Coût net annuel acheteur ou revenu net annuel producteur en euros."
},
"role": {
"type": "string",
"enum": [
"buyer",
"producer"
],
"description": "Rôle du client : acheteur, producteur ou les deux (prosumer)."
},
"comparable": {
"type": "boolean",
"description": "Même période, volume et périmètre de coût explicitement confirmés."
},
"basis": {
"type": "string",
"minLength": 1,
"description": "Périmètre explicite de comparaison de l’alternative PPA."
}
},
"required": [
"name",
"annualNetEur",
"role",
"comparable",
"basis"
]
}
},
"fixedPriceConfirmed": {
"description": "Prix fixe explicitement confirmé par les preuves.",
"type": "boolean"
},
"costPerimeterComplete": {
"description": "Périmètre de coûts complet explicitement confirmé.",
"type": "boolean"
},
"operationalReadinessConfirmed": {
"description": "Préparation opérationnelle explicitement confirmée.",
"type": "boolean"
},
"legalTaxReviewConfirmed": {
"description": "Revue juridique et fiscale explicitement confirmée.",
"type": "boolean"
}
},
"additionalProperties": false,
"description": "Situation PPA déclarée ou extraite avec preuve."
},
"contracts": {
"default": [],
"description": "Contrats PPA structurés ; aucun document brut.",
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Identifiant fourni par l’appelant."
},
"reference": {
"description": "Référence documentaire, si connue.",
"type": "string",
"minLength": 1,
"maxLength": 300
},
"ppa": {
"description": "Termes PPA retournés par extract_energy_document ; null si absents.",
"anyOf": [
{
"type": "object",
"properties": {
"is_ppa": {
"type": "boolean",
"description": "Le document est-il explicitement un PPA ?"
},
"structure": {
"type": "string",
"enum": [
"physical",
"sleeved",
"onsite",
"virtual",
"unknown"
],
"description": "Structure du PPA : physique, avec intermédiaire, sur site ou virtuelle ; unknown si non documentée."
},
"volume_basis": {
"type": "string",
"enum": [
"pay_as_produced",
"baseload",
"pay_as_consumed",
"fixed_volume",
"unknown"
],
"description": "Mode contractuel d’allocation du volume PPA."
},
"buyer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Acheteur nommé au contrat ; null si absent ou masqué."
},
"producer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Producteur nommé au contrat ; null si absent ou masqué."
},
"asset": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Installation identifiée au contrat ; null si inconnue."
},
"technology": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Technologie de production documentée ; null si inconnue."
},
"jurisdiction": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Droit ou juridiction applicable documenté ; null si inconnu."
},
"annual_volume_mwh": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Volume annuel PPA en MWh ; null si inconnu."
},
"strike_eur_mwh": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Prix contractuel PPA en €/MWh ; null si inconnu."
},
"go_transferred": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Transfert contractuel des garanties d’origine ; null si inconnu."
},
"support_scheme": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Régime de soutien public documenté ; null si inconnu."
}
},
"required": [
"is_ppa",
"structure",
"volume_basis",
"buyer",
"producer",
"asset",
"technology",
"jurisdiction",
"annual_volume_mwh",
"strike_eur_mwh",
"go_transferred",
"support_scheme"
]
},
{
"type": "null"
}
]
},
"reading_coverage": {
"description": "Couverture de lecture retournée par extract_energy_document.",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"text_read",
"needs_review"
],
"description": "Statut de couverture de lecture : texte lu ou revue nécessaire."
},
"total_characters": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Nombre total de caractères du texte extrait."
},
"processed_characters": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Nombre de caractères effectivement lus."
},
"chunks": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Nombre de blocs de texte traités."
},
"conflict_paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Chemins des champs dont les preuves se contredisent."
},
"rejected_evidence_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Nombre d’extraits rejetés par la validation littérale."
},
"source_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Empreinte SHA-256 hexadécimale du document source."
},
"pages_without_text": {
"description": "Numéros des pages sans texte exploitable, à partir de 1.",
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"page_provenance_available": {
"description": "La provenance des extraits a-t-elle été vérifiée par page ?",
"type": "boolean"
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"topic": {
"type": "string",
"enum": [
"parties",
"asset",
"term",
"price",
"volume",
"delivery",
"balancing",
"negative_prices",
"curtailment",
"availability",
"commissioning",
"credit",
"collateral",
"termination",
"force_majeure",
"change_in_law",
"assignment",
"disputes",
"tax",
"administration",
"guarantees_of_origin",
"public_support",
"reporting",
"other"
],
"description": "Famille canonique de la clause contractuelle."
},
"title": {
"type": "string",
"description": "Titre de la clause extrait du document."
},
"summary": {
"type": "string",
"description": "Résumé de la clause appuyé par l’extrait fourni."
},
"consequence": {
"type": "string",
"description": "Conséquence documentée de la clause pour le client."
},
"beneficiary": {
"type": "string",
"enum": [
"buyer",
"producer",
"both",
"unknown"
],
"description": "Partie bénéficiaire de la clause, ou unknown si indéterminée."
},
"obligation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Obligation contractuelle extraite ; null si absente."
},
"deadline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Échéance littérale de la clause ; null si absente."
},
"risk": {
"type": "string",
"enum": [
"high",
"medium",
"low",
"unknown"
],
"description": "Niveau de risque documenté, ou unknown si indéterminé."
},
"negotiation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Point de négociation étayé ; null si absent."
},
"excerpt": {
"type": "string",
"description": "Extrait verbatim du document prouvant la clause."
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Score de confiance de l’extraction entre 0 et 1 ; ne garantit pas une conclusion."
},
"start": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Offset de début dans le texte extrait, en caractères ; ce n’est pas un numéro de page."
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Offset exclusif de fin dans le texte extrait, en caractères."
},
"verified_pages": {
"description": "Pages vérifiées contenant l’extrait, à partir de 1.",
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
},
"required": [
"topic",
"title",
"summary",
"consequence",
"beneficiary",
"obligation",
"deadline",
"risk",
"negotiation",
"excerpt",
"confidence",
"start",
"end"
]
},
"description": "Extraits avec offsets textuels validés ; les offsets ne sont pas des numéros de page."
},
"limitation": {
"type": "string",
"description": "Limite explicite de la lecture du document."
}
},
"required": [
"status",
"total_characters",
"processed_characters",
"chunks",
"conflict_paths",
"rejected_evidence_count",
"source_sha256",
"evidence",
"limitation"
],
"additionalProperties": false
}
},
"required": [
"id"
],
"additionalProperties": false
}
},
"matched_profile": {
"description": "Consommation et production PPA mesurées ou simulées, mêmes pas et même période.",
"type": "object",
"properties": {
"consumption_kwh": {
"minItems": 1,
"maxItems": 35136,
"type": "array",
"items": {
"type": "number",
"minimum": 0
},
"description": "kWh consommés par pas, alignés sur ppa_generation_kwh."
},
"ppa_generation_kwh": {
"minItems": 1,
"maxItems": 35136,
"type": "array",
"items": {
"type": "number",
"minimum": 0
},
"description": "kWh PPA produits par pas, alignés sur consumption_kwh."
},
"interval_minutes": {
"anyOf": [
{
"type": "number",
"const": 15
},
{
"type": "number",
"const": 30
},
{
"type": "number",
"const": 60
}
],
"description": "Durée d’un pas en minutes."
},
"start": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Début ISO 8601 avec fuseau."
},
"end": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Fin ISO 8601 avec fuseau, égale au début plus les pas."
}
},
"required": [
"consumption_kwh",
"ppa_generation_kwh",
"interval_minutes",
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"customer"
],
"additionalProperties": false
}
],
"description": "Arguments du target_tool : ceux de extract_energy_document ou de assess_ppa."
},
"document_file": {
"description": "PDF temporaire ChatGPT, seulement pour extract_energy_document.",
"type": "object",
"properties": {
"download_url": {
"type": "string",
"format": "uri",
"description": "URL HTTPS temporaire du PDF, soumise aux restrictions SSRF."
},
"file_id": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Identifiant opaque du fichier temporaire."
},
"mime_type": {
"description": "Type MIME, application/pdf.",
"type": "string",
"maxLength": 200
},
"file_name": {
"description": "Nom du fichier.",
"type": "string",
"maxLength": 500
}
},
"required": [
"download_url",
"file_id"
],
"additionalProperties": false
}
},
"required": [
"idempotency_key",
"target_tool",
"arguments"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}