This repository provides hands-on examples for testing and exploring CodeScribe — a code translation and generation framework that leverages LLMs for scientific computing applications.

This tutorial demonstrates three key CodeScribe capabilities:

1. Code Translation — Convert Fortran source files into interoperable C++ equivalents.
2. Code Generation — Generate new source files or small applications from natural-language prompts.
3. Code Update — Modify or extend existing source files using an instruction file.

Each section below includes the exact command-line instructions for testing these capabilities.

Before running the examples, make sure you have:

• Installed CodeScribe and its dependencies
  (see CodeScribe Installation Guide)
• Access to a configured model such as argo-gpt4o. Argo models are available on Argonne network by setting ARGO_USER and ARGO_API_ENDPOINT environment variables.
• Cloned this tutorial repository:

  git clone https://github.com/akashdhruv/codescribe-tutorial.git
  cd codescribe-tutorial

Use CodeScribe to translate Fortran source files (e.g., Initialize.F90) into interoperable C++ files.

cd codescribe-tutorial/src

# Step 1: Index all files in the current directory
code-scribe index .

# Step 2: Run the translation process
code-scribe translate Initialize.F90 -p ../prompts/code_translation.toml -m argo-gpt4o

This will generate the following files to replace Initialize.F90:

Initialize.hpp
Initialize.cpp
Initialize_fi.F90

These can be directly integrated with the rest of the source code.

Use CodeScribe to generate new application files based on a TOML prompt.

cd codescribe-tutorial
code-scribe generate prompts/code_generation.toml -m argo-gpt4o

Generate command can also be executed using single line prompts instead of a seed prompt file. See example below.

This will generate a complete application inside the generated-src/ directory.

generated-src/
├── main.cpp
├── message.cpp
├── message.h
└── Makefile

Use CodeScribe to update existing source files (e.g., after modifying design or structure).

code-scribe update generated-src/main.cpp  generated-src/Makefile -p prompts/code_update.toml -m argo-gpt4o

Similar to generate command single line prompts can be used in place of a prompt file. See example below.

This updates the specified files (main.cpp and Makefile) according to the update logic in prompts/code_update.toml.

• The -m flag specifies the model to use. Replace argo-gpt4o with another model if needed.
• All prompts are located in the prompts/ directory.
• The generated files can be rebuilt or re-generated by re-running the same commands.

codescribe-tutorial/
├── src/                         # Sample source files for translation
├── prompts/                     # TOML prompt files for each task
├── generated-src/               # Output directory for generated code
├── include/                     # Include directory for hpp files
└── README.md                    # This file

# 1. Translate a Fortran source file
cd codescribe-tutorials/src
code-scribe index .
code-scribe translate Initialize.F90 -p ../prompts/code_translation.toml -m argo-gpt4o


# 2. Generate a new example application
cd codescribe-tutorials
code-scribe generate prompts/code_generation.toml -m argo-gpt4o


# 3. Generate using single line query
cd codescribe-tutorials
code-scribe generate "Write complicated.toml file to generate a more complicated application in generated-src" \
                     -r prompts/code_generation.toml \
                     -m argo-gpt4o

code-scribe generate complicated.toml -m argo-gpt4o


# 4. Update existing generated files
code-scribe update generated-src/main.cpp generated-src/Makefile -p  prompts/code_update.toml -m argo-gpt4o


# 5. Update files using single line query
code-scribe update src/main.cpp src/Solver.F90 src/Initialize.F90 \
                   -q "Write a detailed documentation in the comment section of these files" \
                   -m argo-gpt4o

If you intend to use code-scribe like git, it would be good to set the environment variable

export CODESCRIBE_MODEL="argo-gpt4o"

to avoid supplying -m flag all the time. You can set the environment variable to the model of your choice or path to a local model.

• Main CodeScribe Repository: https://github.com/akashdhruv/CodeScribe
• License: Apache License

Happy coding with CodeScribe!