MABELab-RS/porting/README.md

Porting Toolkit (MabeLabRS)

This directory contains scripts and prompts to LLM-assist the C++ → Rust port from MABE2.

Quick start

1. Copy the example config and edit:

   cp porting/CONFIG.example.yml porting/CONFIG.yml
   
   

Choose an LLM backend in CONFIG.yml:

backend: ollama (default: http://localhost:11434 , e.g., qwen2.5-coder:32b)

backend: openai (set OPENAI_API_KEY env var)

Run a translation task (header → Rust traits):

python3 porting/tools/translate_one.py
--mode header-to-traits
--input /path/to/MABE2/include/mabe/something.hpp
--skeleton crates/mabelabrs-core/src/something.rs
--out crates/mabelabrs-core/src/something.rs

Try an impl pass (C++ .cpp → fill the Rust skeleton):

python3 porting/tools/translate_one.py
--mode impl-pass
--input /path/to/MABE2/source/something.cpp
--skeleton crates/mabelabrs-core/src/something.rs
--out crates/mabelabrs-core/src/something.rs

Compile + test the workspace:

python3 porting/tools/compile_test.py

Modes

header-to-traits: Produces Rust traits/structs with signatures + doc comments (no logic).

impl-pass: Fills in function bodies to match C++ semantics.

unit-tests: Generates unit tests (you provide a short spec).

review-fixit: Feed compiler/test failures back to the model for a targeted fix.

Logs & provenance

All LLM prompts/responses are saved under porting/logs/ with timestamps to preserve provenance.

Determinism reminder

Keep RNGs passed explicitly; avoid global state. See DETERMINISM.md and TRANSLATION_GLOSSARY.md at repo root.

Safety

Never commit secrets. API keys only via environment variables.

Generated code must compile and include tests in the same PR.

---