PRA-MEN 223M · neural decompiler for Windows and MS-DOS

Pramen (Czech for source, spring) turns the assembly of a single function back into C. It targets the toolchains of the Windows / DOS world rather than Linux/GCC:

Larger model: radix16/pramen-498m (1.3) is more accurate (HumanEval-C best of 8: 57.3 % vs 53.6 %) and adds 32-bit DOS (Open Watcom, DOS/4GW), Microsoft C 5.1 and Digital Mars. This 223M model is smaller and faster on CPU. Release 1.2 of this repository is tagged v1.2.

variant target
msvc-x64-Od / msvc-x64-O2 / msvc-x64-O1 Windows x64, MSVC, no optimization / /O2 / /O1
msvc-x86-Od / msvc-x86-O2 / msvc-x86-O1 Windows x86 (32-bit cdecl), MSVC
dos16-small-od / dos16-small-ox MS-DOS 16-bit real mode, small model, Open Watcom, no optimization / -ox
dos16-large-ox / dos16-large-os MS-DOS 16-bit real mode, large model (far calls), Open Watcom -ox / -os

It is a 223 M parameter decoder-only transformer (GPT-2 style) trained from scratch – no natural language, just assembly and C, with its own 16 384-token tokenizer.

The output is a proposal. It usually compiles and often has the right structure, but names are invented (they are not in the binary), types are guessed and the logic has to be checked.

What's new in 1.2

  • Declarations as input (--context): a binary has no struct layouts, typedefs or types of globals, so the model only sees offsets like [RCX + 0x18] and has to guess. You can now give it the declarations the function uses (from headers or your Ghidra project) and it writes the function against them. On held-out functions the share that recompiles to exactly the input assembly goes from 26 % to 35 %, and the share that compiles at all from 47 % to 64 %. A Ghidra script that exports them is included (pramen/ghidra/PramenContext.py).
  • Trained on its own verified outputs: the model wrote 8 candidates for 54 k unseen function × variant pairs; the ones that recompile to exactly the input assembly were used for further training. Better without declarations too.
  • Same size (223 M), same tokenizer and prompt format – without declarations it is used exactly as 1.1.

Earlier (1.1): --candidates 8 (pick the best of 8 by recompiling), KV cache and --quantize int8 for CPU, ten compiler variants.

Results

HumanEval-C from LLM4Binary/decompile-eval (CC0), recompiled with the same toolchains as the training data – 205 tasks (196–203 per variant). A task counts as solved when the decompiled C compiles (as C17 with the standard headers) and passes the original tests (re-executability). Max 600 new tokens. These are small self-contained functions without structs, so declarations do not matter here.

variant 1.1 greedy 1.2 greedy 1.1 --candidates 8 1.2 --candidates 8 1.2 greedy, int8
msvc-x64-Od 53.2 % 57.1 % 70.9 % 72.9 % 53.7 %
msvc-x64-O2 29.2 % 29.2 % 35.6 % 39.1 % 25.2 %
msvc-x86-Od 53.7 % 56.7 % 68.5 % 70.0 % 51.2 %
dos16-small-od 39.8 % 41.8 % 51.0 % 55.1 % 39.3 %
dos16-large-ox 19.8 % 22.3 % 28.9 % 31.0 % 18.8 %
average 39.1 % 41.4 % 51.0 % 53.6 % 37.6 %

With --candidates 8, 1.2 solves 62 tasks that 1.1 does not and loses 36 (p ≈ 0.01). The int8 copy costs about 4 points; it is meant for machines without a GPU.

Held-out ExeBench functions (1 431 function × variant pairs of functions never used in training, compiled with their real dependencies): how often the greedy output recompiles to exactly the input assembly, and how often it compiles at all.

exact match compiles
1.1, no declarations 22.9 % 44.7 %
1.2, no declarations 26.3 % 46.5 %
1.2, with the function's declarations 34.7 % 63.7 %

Prototypes of the called functions alone barely help; struct and type definitions are what matters.

msvc-x86-O2 and the four newest variants are not benchmarked on HumanEval. Optimized code is much harder. The most common failures are wrong parameter types (pointer vs. integer, float vs. int) and invented helper structures.

examples.json contains 12 classic functions × 6 variants with Pramen's outputs and test results (52 / 72 pass) – they are also shown in the web UI.

Quick start

pip install huggingface_hub
hf download radix16/pramen-223m --local-dir pramen     # or: git clone https://huggingface.co/radix16/pramen-223m
cd pramen
pip install -r requirements.txt                   # torch, tokenizers, safetensors

# command line (model is found in the current folder)
python -m pramen example-count_words-msvc-x64-Od.asm --variant msvc-x64-Od

# with declarations: a function over a struct (without them the output does not even compile)
python -m pramen example-order_total-msvc-x64-Od.asm --variant msvc-x64-Od --context example-order_total.h

# web UI with examples → http://127.0.0.1:8780
python -m pramen.web

GPU: 1–2 s per function. CPU (14 cores): about 50 ms per generated token, 2–4 s for a small function, 1.4 GB RAM; with --quantize int8 about 30 ms per token and 0.85 GB RAM. --candidates 8 takes roughly 5–10× longer.

python -m pramen func.asm --variant msvc-x86-Od --candidates 8     # pick the best of 8 by recompiling
python -m pramen func.asm --variant msvc-x86-Od --quantize int8    # CPU, smaller and faster (uses int8/)
python -m pramen.web --quantize int8

The int8/ folder is a ready-made int8 copy (303 MB: linear layers in int8 with a per-tensor scale, embeddings and LayerNorm in fp32, plain safetensors). --quantize int8 picks it up automatically; it runs on CPU only. If you only want the int8 model, download just that folder: hf download radix16/pramen-223m --include "int8/*" "pramen/*" --local-dir pramen and run with --model int8.

from pramen.normalize import normalize
from pramen.runtime import Pramen

pramen = Pramen(".")                                   # folder with config.json, model.safetensors, tokenizer.json
asm, fmt = normalize(open("func.asm").read(), "auto", "msvc-x86-Od")
print(pramen.decompile(asm, "msvc-x86-Od")["c"])
print(pramen.decompile(asm, "msvc-x86-Od", candidates=8)["c"])   # needs MSVC (vcvars64.bat) or Open Watcom
print(pramen.decompile(asm, "msvc-x86-Od", context=open("types.h").read())["c"])   # with declarations

--candidates looks for Visual Studio 2022 / Build Tools (vcvars64.bat) and Open Watcom in C:\WATCOM; other locations can be set with DECOMP_VCVARS and DECOMP_WATCOM. The training data was built with MSVC 19.36 and Open Watcom V2 – other versions work, but the recompiled assembly may differ slightly.

Getting the assembly

  • MSVC: dumpbin /disasm:nobytes program.obj – copy the block of one function.
  • Open Watcom: wdis -a program.obj.
  • Ghidra: copy instructions from the Listing window (header, XREFs and bytes are dropped). Pramen was trained on numeric stack offsets ([EBP + -0x8]), so turn off Markup Stack Variable References (Edit → Tool Options → Listing Fields → Operands Field).

pramen.normalize converts all of these into the exact form used in training (upper-case mnemonics and registers, 0x hex, LAB_n: labels). Feeding raw text that is formatted differently lowers the quality.

Declarations (--context)

Plain C: struct / union / enum definitions, typedefs, extern globals and prototypes of called functions – only what the function uses (typically 5–40 lines). #include, #pragma, include guards and comments are dropped. With --candidates, the candidates are compiled together with the declarations (first after the standard headers; if nothing compiles that way, without them).

From Ghidra: add the folder pramen/ghidra in Script Manager → Script Directories, put the cursor inside a function and run PramenContext.py (or Tools → Pramen → Export declarations). It prints the types used by the function, its globals and its callees' signatures and copies them to the clipboard – paste them into the web UI or save them as decls.h. The script uses only the standard Ghidra API (Jython or PyGhidra) but has not been tested on many Ghidra versions yet – reports are welcome. Ghidra's own names (undefined4, DWORD) are fine.

Why not GGUF / llama.cpp / LM Studio

The tokenizer uses its own pre-tokenization (hex literals like 0x10 and identifiers like LAB_2 stay whole). llama.cpp only supports a fixed set of pre-tokenizers; with gpt-2 it splits 0x10 into 0, x, 10 and the model then repeats assembly instead of writing C. The weights themselves work in llama.cpp when fed token IDs, but text prompts do not – so use the Python package here.

Prompt format

<|asm|>{variant}
{normalized assembly}
<|c|>
{declarations, optional – C lines, then a newline}
{C code}<|endoftext|>

Training

  • Data: 8.5 M assembly → C pairs (3.6 B tokens). C functions come from ExeBench (train_synth_compilable, train_real_compilable), each compiled ten ways with MSVC 19.36 (dumpbin) and Open Watcom V2 (wdis), deduplicated (exact + near).
  • Additional C/C++ source code (3.5 B tokens), mixed in so the model learns C syntax and idioms, from permissively licensed GitHub repositories (codeparrot/github-code-clean), The Stack, and several open-source projects (cJSON, fmt, nlohmann/json, and the GPL-2.0 source releases of Doom and Quake I–III).
  • Declarations (1.2): 300 k further pairs from unseen ExeBench functions with their dependencies (structs, typedefs, globals, prototypes) in the prompt – 30 % full, 23 % only callee prototypes, 47 % none – mixed 50:50 with the original pairs so the model does not drift.
  • Own verified outputs (1.2): for 54 k unseen function × variant pairs (6 k functions) the model wrote 8 candidates each; candidates that recompile to exactly the input assembly (plus the original for some functions without one) were used for a final short fine-tune.
  • Architecture: 16 layers, 1 024 hidden, 16 heads, MLP 4 096, context 4 096, learned positions, tied embeddings.

Limitations

  • one function at a time, up to ~3 500 input tokens (roughly 400–600 lines of assembly)
  • without declarations, globals and structs are only visible as addresses and offsets; the model guesses their meaning (with --context it uses yours)
  • variable and function names are invented
  • trained only on code produced by MSVC 19.36 and Open Watcom V2; other compilers (Borland, Turbo C, GCC/MinGW, …) are out of distribution

License and data

Model weights and code: Apache-2.0. The training functions keep the licenses of their original GitHub repositories (as collected by ExeBench); the additional source code includes GPL-2.0 code (Doom, Quake). Use the outputs accordingly – decompiled code of third-party software is still subject to its original license.


Česky

Pramen 223M = menší model; větší a přesnější je pramen-498m. Pramen = zdroj. Neuronový dekompilátor, který z assembleru jedné funkce napíše C. Míří na Windows (MSVC x86/x64) a MS-DOS (Open Watcom 16 bit). Model má 223 M parametrů a je natrénovaný od nuly jen na assembleru a C. Výstup je návrh: obvykle se přeloží a mívá správnou strukturu, ale jména jsou vymyšlená, typy odhadnuté a logiku je potřeba ověřit. Spuštění: pip install -r requirements.txt, pak python -m pramen.web (webové rozhraní s ukázkami na http://127.0.0.1:8780) nebo python -m pramen soubor.asm --variant msvc-x86-Od. S --candidates 8 vybere nejlepší z 8 návrhů podle zpětného překladu (potřebuje MSVC nebo Open Watcom), s --quantize int8 běží rychleji na CPU. Od verze 1.2 umí přijmout deklarace, které funkce používá (--context typy.h, ve webu pole „declarations“) – struktury, typedefy, globální proměnné; z Ghidry je vyexportuje skript pramen/ghidra/PramenContext.py.

Downloads last month
326
Safetensors
Model size
0.2B params
Tensor type
F32
·
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

Collection including radix16/pramen-223m