Provider AI

A cosa serve

Il provider AI produce una rappresentazione candidata di Issue Content JSON a partire da un contesto editoriale accettato.

Componenti che lo usano

Il job di generazione D1, la Queue ISSUE_GENERATION_QUEUE, il prompt composer, l'adapter OpenAI e l'orchestratore di validazione/persistenza.

Dati e artefatti scambiati

L'API compone istruzioni e contesto da Topic e Knowledge Asset accettati. Il provider restituisce testo JSON candidato. L'orchestratore parsea, normalizza, valida schema e quality gate prima di salvare un draft in D1.

Autenticazione e autorizzazione

La chiave provider è un secret Worker. L'Admin richiede issue:generate; il consumer riceve un comando bounded con job e Topic. Il provider non riceve permessi editoriali, Access session o autorità di pubblicazione.

Cosa possiede il provider

Il provider possiede esecuzione del modello, disponibilità API e risposta generata. Il modello è selezionato tramite configurazione repository/runtime.

Cosa possiede Architecture Coffee

Architecture Coffee possiede prompt, Skill, Issue Content schema, normalizzazione, attempt limit, quality gate, stato job, persistenza D1 e revisione umana. Il JSON provider non è canonico finché non supera questi gate.

Operazioni automatiche, manuali e protette

L'Admin crea manualmente un job; la Queue esegue e può rideliverare secondo il contratto. L'orchestratore prova candidate bounded per invalidità di contenuto. Review, approvazione e pubblicazione sono azioni umane separate.

Fallimenti e comportamento fail-closed

Provider non configurato, rete, risposta non JSON, schema invalido o qualità insufficiente terminano il job con codice sicuro. Output invalido non viene salvato come Issue e non viene pubblicato. Redelivery è idempotente sui job terminali.

Verifiche operative

Topic accettato e coperto da Knowledge Asset accettati;
job queued/running/terminal in D1;
numero massimo di tentativi;
schema e quality gate;
draft creato in pending_review;
assenza di prompt, chiave e risposta grezza nell'audit.

Valutazione locale dei modelli

Il comando repository-owned npm run evaluate:issue-models confronta modelli solo su input espliciti sotto tmp/model-eval/, area ignorata da Git. Riusa il prompt composer, la richiesta Responses API e i gate deterministici di produzione, ma non costruisce job, non usa Queue e non persiste in D1.

Una valutazione live richiede un'autorizzazione separata e parametri espliciti:

Il manifest locale ha version: 1 e una lista bounded di input compatibili con IssueDraftGenerationInput. Ogni elemento ha un identificatore locale stabile, il numero Issue da usare per la normalizzazione, il Topic e almeno un Knowledge Asset. Può includere anche i referenceCandidates del Topic:

{
  "version": 1,
  "inputs": [
    {
      "id": "synthetic-example",
      "input": {
        "slug": "bounded-evaluation",
        "issueNumber": 1,
        "topic": {
          "id": "TOPIC-001",
          "title": "Bounded evaluation",
          "category": "Architecture",
          "learningObjective": "Compare candidate drafts.",
          "rationale": "Evidence precedes a model decision.",
          "tags": ["evaluation"]
        },
        "knowledgeAssets": [
          {
            "id": "KA-001",
            "title": "Evaluation evidence",
            "type": "practice",
            "summary": "Compare on a stable workload.",
            "body": "Keep provider and validation outcomes separate.",
            "tags": ["evaluation"]
          }
        ]
      }
    }
  ]
}

npm run evaluate:issue-models -- run \
  --manifest tmp/model-eval/inputs.json \
  --models model-a,model-b \
  --reasoning-effort none \
  --output tmp/model-eval/run-name

Il comando esegue una richiesta alla volta e produce artefatti separati:

blind-review.json, con etichette cieche e campi di score 1–5;
model-mapping.json, mappa riservata da input_id ed etichetta a modello e reasoning effort;
provider-evidence.json, con soli usage, latenza e risultati dei gate;
report.json, aggregato iniziale senza review umana.

Le etichette Candidate A, Candidate B, ecc. vengono riassegnate con uno shuffle indipendente per ogni input. Ogni input contiene una volta ciascun modello e ciascuna etichetta, senza esporre l'identità nel file di review.

Al reviewer viene consegnato solo blind-review.json. Mapping, evidence e report restano separati e non vengono rivelati finché gli score non sono completi.

Dopo la compilazione del file cieco, il report con gli score si genera in una nuova destinazione locale esplicita:

npm run evaluate:issue-models -- report \
  --run-dir tmp/model-eval/run-name \
  --review tmp/model-eval/run-name/blind-review.json \
  --output tmp/model-eval/run-name/report-reviewed.json

Input, output, mapping e report restano evidenza locale temporanea: non sono Issue Content canonico e non entrano nel lifecycle editoriale. Prezzi e costi non sono incorporati nel comando o nel repository. I rate di parsing, schema e quality usano come denominatore solo le candidate arrivate allo stage; i failure provider e i dati di review mancanti restano conteggi separati.