alantech/marsha

Marsha – an LLM‑driven “programming language”

What it is – Marsha lets you write a tiny, markdown‑style description of a data‑processing task. You declare the input and output “types”, write a short natural‑language description, and give a handful of input‑output examples. The Marsha compiler then sends this specification to an LLM (by default OpenAI’s API, but any compatible endpoint works) which generates Python code, runs the examples as tests, and returns a working script.

Key ideas

• Declarative syntax – .mrsh files look like markdown. Types are defined with CSV‑style tables, functions are declared with a # func … heading, followed by a description and an example block.
• Example‑driven testing – The examples you provide become a test suite that the compiler uses to verify the generated code, reducing the chance of broken output.
• LLM as the backend compiler – The heavy lifting (turning the spec into Python) is done by an LLM. You can choose the model via config, command‑line flags, or environment variables.
• Ready‑to‑run output – The generated Python includes a tiny CLI wrapper (or a simple REST server) so you can call the compiled function directly from the terminal.

How to use it

1. Install the package from the repo:

   uv pip install git+https://github.com/alantech/marsha
   

2. Write a file my_task.mrsh using the Marsha syntax (type definitions, a # func … block, description, and examples).
3. Compile it:

   python -m marsha my_task.mrsh
   

   The command contacts the configured LLM, generates Python, runs the tests, and writes the resulting script.
4. Run the produced script either as a CLI tool or as a tiny web service:

   python -m my_task --help          # see generated CLI options
   python -m my_task -s 8080         # start a REST server
   

Configuration – Marsha reads a JSON config file from the standard OS location (~/.config/marsha/config.json on Linux, etc.). You can set api_base, api_key, model, and model_strong. Environment variables (OPENAI_ORG, OPENAI_SECRET_KEY/OPENAI_API_KEY) work for the default OpenAI backend. The --api-base and --model flags override these settings on the command line.

Command‑line options (selected highlights):

• -q – generate code only, skip the correction stages (cheaper, less reliable).
• -a N – try up to N compilation attempts, retrying on failure.
• -n N – run N parallel LLM “thought” paths per attempt; the first successful path wins.
• --exclude-main-helper – omit the auto‑generated CLI wrapper.
• --exclude-sanity-check – skip the initial consistency check of the Marsha definition.
• -s – write compilation statistics to a file.

Roadmap highlights

• Push average correctness above 90 %.
• Add syntax‑highlighting plugins for editors.
• Support additional target languages beyond Python.
• Introduce a module system and a “decompiler” that can turn existing Python back into Marsha syntax.
• Build a visual GUI editor and richer debugging helpers.

Who it’s for – Developers who want a higher‑level, example‑driven way to generate small data‑processing scripts (e.g., pandas pipelines) without hand‑coding every line, and who are comfortable letting an LLM produce the implementation under test‑driven supervision.