Files

Davide Grilli 9a0a170799 feat(skills): add local python-to-c-efficiency skill with modular C scaffold

add local Codex skill for Python->C performance-focused translation

define modular C architecture and benchmark/correctness gates

add references for patterns, profiling, and module design

add scaffold_c_module.py to generate include/src/tests/bench skeleton

update agent default prompt for benchmark-backed optimizations

2026-03-30 00:08:14 +02:00

3.7 KiB

Raw Blame History

name, description

name	description
python-to-c-efficiency	Tradurre codice Python in C ad alte prestazioni con focus su modularizzazione, riduzione overhead e benchmarking ripetibile. Usare quando Codex deve convertire `.py` in moduli `.c/.h`, isolare hot-path CPU o memoria, progettare API C stabili e consegnare implementazioni validate con test di equivalenza e misure performance prima/dopo.

Python to C Efficiency

Obiettivo

Convertire sezioni critiche Python in C con tre vincoli obbligatori:

Mantenere comportamento osservabile equivalente.
Consegnare codice modulare e manutenibile.
Dimostrare miglioramento con benchmark ripetibile.

Workflow Decisionale

Misurare prima di tradurre. Profilare Python e identificare i veri hotspot. Evitare conversioni "a tappeto".
Delimitare il confine C. Tradurre kernel computazionali e lasciare in Python orchestrazione, I/O e glue code quando non critici.
Disegnare il modulo C. Definire API, ownership memoria, error handling e formato dati prima dell'implementazione.
Implementare versione corretta. Portare la logica Python in C senza ottimizzazioni premature.
Ottimizzare solo hotspot confermati. Applicare tecniche CPU/cache/memoria su funzioni misurate come dominanti.
Validare correttezza e performance. Confrontare output Python/C e pubblicare metriche prima/dopo con stesso dataset.

Architettura Modulare Obbligatoria

Usare struttura per modulo:

<feature>/
  include/<feature>.h
  src/<feature>.c
  src/<feature>_internal.h   # opzionale
  tests/test_<feature>.c
  bench/bench_<feature>.c

Applicare queste regole:

Esporre nel .h solo API pubbliche, tipi pubblici minimi e codici errore.
Nascondere dettagli interni in _internal.h o nel .c.
Passare buffer con puntatore + lunghezza (ptr, size_t n).
Dichiarare const e restrict quando semanticamente corretti.
Evitare stato globale mutabile nel percorso caldo.

Per bootstrap rapido della struttura usare:

python3 scripts/scaffold_c_module.py --name my_kernel --out-dir /path/progetto

Regole di Implementazione ad Alte Prestazioni

Rendere i tipi espliciti (int32_t, uint64_t, size_t, float, double).
Preallocare e riusare memoria nei loop intensivi.
Favorire layout contigui e accesso sequenziale cache-friendly.
Ridurre branch imprevedibili nel hot-path.
Ridurre indirezioni e dispatch dinamico dove non necessario.
Applicare static inline solo dove il profiler giustifica il beneficio.
Usare algoritmo migliore prima di micro-ottimizzare il codice.

Contratto di Correttezza

Prima di dichiarare completata la traduzione, eseguire sempre:

Test di regressione su casi nominali e edge case.
Confronto output Python vs C su dataset condiviso.
Build debug con sanitizer e assenza di errori runtime.

Contratto di Performance

Misurare e riportare sempre:

Tempo wall e CPU.
Memoria massima.
Throughput o latenza per input unitario.

Accettare il risultato solo se:

Esiste speedup reale su workload target.
Il miglioramento è ripetibile su più run.
Eventuali regressioni secondarie sono documentate.

Output Richiesto

Produrre sempre:

File .c/.h modulari con API chiara.
Nota breve di mapping Python→C per le parti critiche.
Comandi build debug/release usati.
Tabella compatta benchmark prima/dopo.
Rischi residui o tradeoff aperti.

Riferimenti

Caricare in base al task:

Mapping costrutti e pattern: references/patterns-python-c.md
Build, profiler e benchmark: references/compiler-and-profiling.md
Design modulare C: references/modular-c-architecture.md

3.7 KiB Raw Blame History