1. Scopo e confini

Il synthesizer è il componente che trasforma un fallimento motivato in un neurone candidato. È una pipeline a 7 stadi con retry massimo 3 e un gate umano non bypassabile allo stadio 6. Quello che produce è una directory-neurone pronta per essere firmata.

Cosa copre

• Trigger: dal fallimento del reasoning loop alla decisione "sintesi sì/no".
• Ogni stadio della pipeline: input, output, criteri di successo.
• Gate: analisi statica, test sandbox, approvazione umana.
• Retry policy e condizione di abbandono.

Cosa non copre

• Anatomia del neurone risultante → neuron.html.
• Come si misura utilità e fitness dopo la nascita → synapse.html.
• La sandbox che esegue test e bozza → sandbox.html.
• La UX di approvazione (batching, revoca) → approval_ux.html.

2. I sette stadi

3. Trigger: quando parte la sintesi

Il synthesizer non decide da solo: il agent_runtime emette una SynthesisRequest quando almeno uno dei seguenti è vero, e nessun veto della policy è attivo:

Trigger esterno (reattivo)

• Il reasoning loop ha esaurito i tool disponibili senza raggiungere lo scopo.
• Il modello ha proposto ripetutamente la stessa sequenza fallita (detector di bucle).
• L'utente non ha autorizzato "abbandona".
• Il budget (§ cost tiering) consente almeno una chiamata frontier.

Trigger interno (proattivo, presidiato)

• Negli ultimi 30 giorni, pattern di fallimento ricorrente (≥ M volte su task simili).
• Proposta emessa come InternalProposal, visibile nel digest notturno.
• Richiede due approvazioni: prima la direzione, poi il neurone. Vedi Neuroni+Memoria §4.

4. Stadio 2 — Spec

Una chiamata LLM frontier (purpose design-neuron-spec) produce uno NeuronSpec strutturato. Il prompt include: la trace fallita, i tool già tentati, il catalogo delle capability disponibili, lo stile degli spec precedenti (few-shot).

@dataclass(frozen=True)
class NeuronSpec:
    proposed_name: str
    purpose: str                   # 1-4 frasi NL
    input_schema: dict             # JSON Schema
    output_schema: dict
    capabilities_requested: list[str]
    rationale: str                 # perché serve, cosa non bastava
    may_call: list[str]            # tool/neuroni attesi

La spec passa un pre-check di policy: se richiede capability forbidden (es. shell:* fuori dalla whitelist), viene rigettata subito senza consumare la quota di retry.

5. Stadio 3 — Bozza

Seconda chiamata LLM frontier (purpose write-neuron-code). Input: lo NeuronSpec, il template skeleton del corpo, l'API di NeuronContext, esempi di neuroni esistenti ad alta fitness (few-shot). Output: tre file (body.py, test_birth.py, manifest.yaml).

Vincoli imposti nel prompt

• Solo import da stdlib e myclaw.runtime.
• test_birth.py contiene almeno 3 casi: uno positivo, uno edge, uno negativo.
• Il manifest deve dichiarare le stesse capability dello spec (non di più, non di meno).
• Nessun codice di rete a meno che network non sia tra le capability.

6. Stadio 4 — Analisi statica

Lanciata in locale, senza sandbox (sta analizzando testo, non eseguendo). Tre check in cascata:

1. Lint: ruff check su body.py e test_birth.py. Errore = rigetto.
2. Security lint: bandit con profilo strict.
3. AST whitelist: parsing AST, verifica che solo gli import ammessi siano presenti e che non ci siano chiamate a eval, exec, compile, __import__, open (deve passare da ctx.open).
4. Coerenza capability: le capability in manifest.yaml devono coprire tutte le chiamate che il body effettivamente fa (es. ctx.open("~/logs", ...) richiede fs-read:~/logs).

7. Stadio 5 — Test in sandbox

test_birth.py viene eseguito dentro un profilo bwrap tight (vedi sandbox §3):

• Filesystem: solo una tmpfs di lavoro + eventuale bind read-only delle path richieste.
• Rete: disabilitata per default (salvo capability esplicita).
• Limiti: 30 s wall, 256 MB ram, 512 KB stdout, 10 CPU-s.
• Variabili di ambiente scrubbed.

Output: SandboxReport con esito per ciascun test, wall-clock, ram peak, stdout/stderr troncati.

7.1 Synthetic reward composito R

Dopo il SandboxReport lo stadio 5 non produce un verdetto binario ma uno score continuo R ∈ [0, 1]. La formula è canonizzata in rl_offline §5 (Esperimento B):

R = 0.40 · det_pass_rate       # frazione test deterministici verdi
  + 0.25 · judge_score         # LLM-as-judge (local-fast) su rubrica costituzionale
  + 0.15 · cost_ratio          # clip(1 − cost_sandbox_effettivo / stima, 0, 1)
  − 0.10 · similarity_penalty  # cosine-sim embedding con neuroni esistenti > 0.85
  + 0.10 · coverage_bonus      # bonus se copre effect_class non coperto

gate_threshold = 0.65          # DECISIONE v1

8. Stadio 6 — Approvazione umana

Questo stadio è non bypassabile in ogni livello di autonomy. È la valvola di non-ritorno prescritta dalla Legge 2: un agente non si auto-modifica senza consenso informato.

Cosa vede Roberto

• Contesto: la trace originale che ha innescato la sintesi (collapse-by-default, espandibile).
• Purpose del neurone in NL.
• Capability richieste, con riferimento alla policy (es. "questo tocca fs-read:~/logs che non era già concesso").
• Diff del body con syntax highlighting.
• Esito test: verde/rosso, tempi, consumo risorse.
• Score R con breakdown: le 5 componenti (det_pass_rate, judge_score, cost_ratio, similarity_penalty, coverage_bonus) in tabella + il totale. Vedi §7.1.
• Giudizio testuale del judge: le 2-3 righe di motivazione prodotte dal tier local-fast. Se il judge ha segnalato una Legge borderline, è evidenziato in arancione.
• Costo di sintesi finora (centesimi).

Azioni possibili

La UX concreta (CLI, Telegram, batching) è in approval_ux.

9. Stadio 7 — Firma e attivazione

1. Normalizzazione dei tre file: rimozione trailing whitespace, line endings LF.
2. Calcolo HMAC-SHA256 secondo il contratto di neuron §5.
3. Scrittura di signature.hmac.
4. Bootstrap TrustScore: scrittura in TrustStore (rl_offline §7) di un record iniziale per il subject ("neuron:<name>", "invoke") con score = R (dallo stadio 5), n_samples = 1, componente human_approval_rate = 1.0 (è appena stato approvato). Il neurone parte con fiducia parziale proporzionale alla qualità della nascita.
5. Notifica al loader tramite il watcher: viene ricaricato, stato iniziale neonato.
6. Audit event neuron.born con nome, versione, trace_id originale, hash del body, R finale.

10. Retry e abbandono

• Max 3 retry per SynthesisRequest. Contano sia i rigetti automatici (stadi 4/5) sia quelli umani (stadio 6 "rivedi").
• Quando lo stadio 5 produce R < 0.65, il sintetizzatore non si ferma: costruisce un feedback in-context con il breakdown delle componenti e una frase esplicativa per ogni metrica sotto soglia (es. "det_pass_rate=0.50: 2 test falliti su 4 — considera edge case di input vuoto"). Torna a stadio 2 o 3 a seconda del tipo di fallimento. Questo è rejection sampling con feedback testuale (rl_offline §5), non gradient training.
• Al quarto tentativo il synthesizer abbandona: chiude con outcome abandoned, scrive l'episode in memory, non ritenta sullo stesso scopo per 24 h.
• Se il budget frontier è esaurito a metà pipeline, abbandono prematuro.
• Il trigger interno aggiunge un ulteriore gate di direzione (stadio 0): rifiuto di direzione → marca il pattern e non riprova per 30 giorni.

11. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass

SynthesisOutcome = Literal["born", "abandoned", "rejected_direction"]

@dataclass
class SynthesisRequest:
    goal: str                       # scopo in NL
    trace_id: str                   # trace originale che ha fallito
    mode: Literal["external", "internal"]
    capability_hint: list[str]      # ipotesi iniziali
    budget_cents: float             # tetto frontier spendibile

@dataclass
class RewardBreakdown:
    """Score composito R dello stadio 5 (vedi §7.1). Reso visibile a Roberto
    nel dossier di stadio 6 e al sintetizzatore come feedback in-context
    quando R < gate. Formula canonica in rl_offline §5."""
    det_pass_rate: float       # [0,1]
    judge_score: float         # [0,1] dal tier local-fast
    judge_reasoning: str       # 2-3 righe di motivazione
    cost_ratio: float          # [0,1]
    similarity_penalty: float  # [0,1] (con segno negativo nella formula)
    coverage_bonus: float      # [0,1]
    total: float               # R aggregato

@dataclass
class SynthesisResult:
    outcome: SynthesisOutcome
    neuron_name: str | None
    neuron_path: str | None
    retries_used: int
    cost_cents: float
    rejection_reason: str | None
    final_reward: RewardBreakdown | None = None   # popolato se arriva a stadio 5

class Synthesizer(Protocol):
    async def synthesize(self, req: SynthesisRequest) -> SynthesisResult:
        """Esegue la pipeline a 7 stadi. Non solleva: ritorna sempre un
        SynthesisResult, anche su abbandono."""
        ...

    async def revise(
        self, request_id: str, feedback: str,
        target_stage: Literal["spec", "draft"],
    ) -> SynthesisResult:
        """Riprende una request in pausa dopo rifiuto utente allo stadio 6."""
        ...

# Errori interni (non propagati; registrati e trasformati in outcome)
class StaticAnalysisError(Exception): ...
class SandboxTestError(Exception): ...
class PolicyVetoError(Exception): ...
class BudgetExceededError(Exception): ...

12. Alternative considerate

13. Test di conformità

14. Riferimenti

Continua a leggere

myclaw — synthesizer microprogettazione v1.0 — 2026-04-22
Secondo doc dell'estensione neuroni. Prossimo: synapse.html.