README.md

---
license: apache-2.0
base_model: Qwen/Qwen2.5-Coder-1.5B-Instruct
library_name: transformers
pipeline_tag: text-generation
language:
  - en
tags:
  - decompilation
  - reverse-engineering
  - python
  - bytecode
  - code
  - verified-generation
  - qwen2
---

# PyBytecode v3 — 1.5B

Turns Python 3.12 bytecode back into Python source. Hand it a disassembled code object, get source
code back.

The unusual part: **you can check every answer.** Recompile what the model wrote and compare it
against the bytecode you started with — if they match, that file is exactly right, and you know it
without trusting an accuracy number.

Weights are Apache-2.0. A GGUF build ships alongside for llama.cpp / LM Studio / Ollama.

## Quickstart

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

tok = AutoTokenizer.from_pretrained("BlazingCustoms/pybytecode-v3-1.5b")
model = AutoModelForCausalLM.from_pretrained(
    "BlazingCustoms/pybytecode-v3-1.5b", torch_dtype="bfloat16", device_map="auto")

INSTRUCTION = ("Decompile this Python 3.12 bytecode disassembly back into the original Python "
               "source code. Output only the source code.")

# `disasm` comes from harness/pybytecode_core/rep.py: disassemble_v2(code_object)
msgs = [{"role": "user", "content": f"{INSTRUCTION}\n\n{disasm}"}]
batch = tok.apply_chat_template(msgs, add_generation_prompt=True,
                                return_tensors="pt", return_dict=True).to(model.device)
prediction = tok.decode(model.generate(**batch, max_new_tokens=2048,
                                       do_sample=False)[0][batch["input_ids"].shape[1]:],
                        skip_special_tokens=True)
```

Greedy decoding (temperature 0) for a single shot; temperature ~0.8 when you sample several
candidates.

## Checking the answer

Compile the model's output and compare the resulting code object to the one you were decompiling.
Same code object means same behaviour, so a match tells you *this* answer is correct:

```python
from harness.pybytecode_core.verify import code_fingerprint

def certified(prediction: str, reference_code_object) -> bool:
    got = compile(prediction, "<pred>", "exec", dont_inherit=True, optimize=0)
    return code_fingerprint(got) == code_fingerprint(reference_code_object)
```

Two things follow. A failed check means "not confirmed", not "wrong" — a correct rewrite that
compiles differently (a `while` where the original had a `for`) won't match, so the accuracy
figures below are a floor, not an estimate. And because the check is cheap and reliable, sampling
several answers and keeping the first one that passes is a real gain rather than a nicer guess.

## Results

On the benchmark published with this model:

| | certified |
|---|---|
| **PyBytecode v3, one attempt** | **506 / 600 = 84.33%** |
| **PyBytecode v3, up to 32 tries** | **562 / 600 = 93.67%** |
| `Qwen2.5-Coder-1.5B-Instruct` before fine-tuning, one attempt | 4 / 600 = 0.67% |

The benchmark is `csn-3.12-licensed`: 600 real functions from 117 GitHub repositories, compiled to
3.12 bytecode, shipped with the model. The base model before fine-tuning gets essentially none of
them, so this is not something a general code model can guess its way through.

Full numbers, confidence intervals, method, per-budget curve and the comparison with other
systems: [`EVAL.md`](EVAL.md).

[PyLingual](https://github.com/syssec-utd/pylingual) is another system that does this task, by
symbolic reconstruction rather than generation. On our earlier benchmarks it scores about the same
as we do, and the two miss on different inputs — so running both and keeping whichever answer
passes the check gets you more than either alone. Numbers in [`EVAL.md`](EVAL.md).

## When it works well, and when it doesn't

**It is good on individual functions and gets much worse on long ones.** Size is measured in
*disassembly lines* — how long the input you hand the model is. One line tells you:

```python
from harness.pybytecode_core.rep import disassemble_v2
rep_lines = disassemble_v2(code_object).count("\n")
```

| disassembly lines | rows | one attempt | up to 32 tries |
|---|---|---|---|
| under 100 | 448 | 92.86% | 98.21% |
| 100–199 | 112 | 65.18% | 85.71% |
| 200–399 | 32 | 53.12% | 81.25% |
| 400+ | 8 | 0.00% | 0.00% |

Below ~100 lines it is on home ground. Accuracy starts dropping around 200, and above ~400 lines
nothing certified at all, even with 32 tries. Sampling more buys roughly one bucket of headroom;
it does not remove the limit. For big units, a symbolic decompiler is the better tool. The full
seven-bucket curve is in [`EVAL.md`](EVAL.md).

## Limits

- **Long inputs.** The table above is the honest specification: trained on functions, not modules,
  and it fails above ~400 disassembly lines.
- **Python 3.12 only.** Trained and measured on 3.12; the checker refuses other minor versions by
  design.
- **If the `.pyc` was built with `-O`, compile at the same level or the check will not match.**
  Wrong level collapses to ~24%, so try all three — it costs three compiles. At `-O` and above,
  docstrings aren't in the `.pyc` at all, so docstring recovery can't be confirmed against one.
- **A `.pyc` built by someone else can fail the check even when the answer is right** — about
  0.33% of the time, because CPython patch releases compile the same source differently. It always
  fails in the safe direction: "unknown" about a correct answer, never "confirmed" about a wrong
  one.
- **It has not been shown to work on real malware.** On the one packed sample we tried, the
  entry-point module produced nothing certifiable. Extraction worked; decompiling the actual
  malware logic did not.
- Untested: Python 3.13, Nuitka, non-CPython builds, obfuscated bytecode.

Details on all of these in [`EVAL.md`](EVAL.md) and [`ORACLE-LIMITS.md`](ORACLE-LIMITS.md).

## Model details

Fine-tuned from [`Qwen/Qwen2.5-Coder-1.5B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct)
(Apache-2.0) with LoRA on 48,196 pairs of Python 3.12 disassembly → source, adapter merged. The
corpus was filtered to permissive licences before training and is not redistributed — per-row
attribution was not retained, so shipping it would strip required notices. Lineage:
[`DATA-CARD-training-corpus.md`](DATA-CARD-training-corpus.md). Training settings: [`EVAL.md`](EVAL.md).

## Licence

**Apache-2.0.** See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

Derived from `Qwen/Qwen2.5-Coder-1.5B-Instruct`, which is Apache-2.0. Under Apache-2.0 §4 we ship
the licence, retain attribution, and state our changes (LoRA fine-tune, adapter merged; no
architecture, vocabulary or tokenizer change). The same obligations pass to you if you
redistribute these weights or build derivatives.

Decompilation has obvious dual use. Apache-2.0 imposes no field-of-use restriction and we have not
added one. Complying with the law where you operate is your responsibility.

## Citation

```bibtex
@software{pybytecode2026,
  title  = {PyBytecode: verified neural decompilation for Python 3.12 bytecode},
  author = {Blazing Customs},
  year   = {2026},
  note   = {Fine-tuned from Qwen2.5-Coder-1.5B-Instruct},
  url    = {https://huggingface.co/BlazingCustoms/pybytecode-v3-1.5b}
}
```