Agent Mesh for Software Engineering - Code Understanding

Contents

• Overview
• Required Software / Tested with
• Installing the Code Understanding Workflow
  • Integrating the Models
  • Preparing the Environment
  • (Optional) Building the Container Images
  • Installing via Makefile
• Running the Code Understanding Workflow
• Running Adhoc Queries
• Integrating with other tools
• More About the Code Understanding Workflow
  • 1. Data Generation
  • 2. Data Indexing
  • 3. Data Analysis

🧭 Overview

This demonstrates the Code Understanding phase of the Agent Mesh for Software Engineering, a framework pattern for continuous legacy code which uses a federated, multi-harness, multi-agent system (MAS) to support iterative agent-driven development for brownfield applications.

(NOTE: The Agent Mesh consists of two main workflows: Code Understanding and Code Migration. This repository demonstrates the Code Understanding workflow.)

Required Software / Tested with

• Red Hat OpenShift 4.18+
• Red Hat OpenShift AI 2.22+
• 1X NVIDIA H200 GPU, 1X NVIDIA H100 GPU, 1X NVIDIA L40S GPU
• 8+ vCPUs / 24+ GiB RAM
• MLflow (assumes Openshift AI 3.4+) Installation
• Openshift AI Model Registry Installation
• Openshift AI Model Catalog Installation
• Openshift AI Pipelines Installation
• OpenShift CLI (oc)
• Helm CLI (helm)
• Make (make)

Installing the Code Understanding Workflow

Integrating the Models

Ensure that you have access to OpenAI-compatible endpoints for the following models:

1. GraphRAG "chat" model (see docs). Candidate models:

• gpt-oss-120b (see: https://huggingface.co/RedHatAI/gpt-oss-120b)

#################################
# Sample vLLM Deployment on H100:
#################################
export HF_TOKEN=<your-huggingface-token>
export VLLM_ALLOW_LONG_MAX_MODEL_LEN=1
pip install vllm==0.19.0 mistral-common==1.9.1 tqdm==4.67.3 jupyter==1.1.1 hf_transfer==0.1.9 transformers==4.55.2
nohup python3 -m vllm.entrypoints.openai.api_server \
    --model RedHatAI/gpt-oss-120b \ 
    --enable-auto-tool-choice \
    --tool-call-parser openai \                                                                                    
    --max-model-len 128000 \
    > vllm.log 2>&1 &

2. GraphRAG "embedding" model (see docs). Candidate models:

• e5-mistral-7b-instruct (see: https://huggingface.co/intfloat/e5-mistral-7b-instruct)

#################################
# Sample vLLM Deployment on L40S:
#################################
export HF_TOKEN=<your-huggingface-token>
pip install vllm==0.19.0 mistral-common==1.9.1 tqdm==4.67.3 jupyter==1.1.1 hf_transfer==0.1.9 transformers==4.55.2
nohup python -m vllm.entrypoints.openai.api_server \
--model=intfloat/e5-mistral-7b-instruct \                                                                  
--runner pooling \  # or --task=embed for older vllm                                                                                       
--dtype float16 
> vllm.log 2>&1 &

3. Coding agent model (for invoking skills). Candidate models:

• Gemma-4-31B-it (see: https://huggingface.co/RedHatAI/gemma-4-31B-it-NVFP4)

#################################
# Sample vLLM Deployment on H200:
#################################
pip install vllm==0.19.0 tqdm==4.67.3 jupyter==1.1.1 hf_transfer==0.1.9 huggingface-hub "transformers<5.0.0,>=4.56.0"
pip install huggingface-hub==1.14.0 transformers==5.8.0
wget https://huggingface.co/RedHatAI/gemma-4-31B-it-NVFP4/blob/main/chat_template.jinja
nohup python3 -m vllm.entrypoints.openai.api_server \
     --model RedHatAI/gemma-4-31B-it-NVFP4 \
     --quantization fp8 \
     --kv-cache-dtype fp8 \
     --enable-auto-tool-choice \
     --reasoning-parser gemma4 \
     --tool-call-parser gemma4 \
     --chat-template chat_template.jinja \
     --gpu-memory-utilization 0.90 \
     --max-model-len 262144 \
      > vllm.log 2>&1 &

• gpt-oss-120b (see: (a) above)

Preparing the Environment

1. Create an environment variables file .env using .env.template as a guide.

(Optional) Building the Container Images

1. To build the container images, run the following: make build-images

Installing via Makefile

1. Run the Makefile: make install

Running the Code Understanding Workflow

1. To run the Code Understanding pipeline for a single repository, run: make run-pipelines ARGS="--single-repo"

   To specify the target repository or branch:

   • Update GIT_REPO and GIT_BRANCH in .env to the desired repository and branch.
   • Run the following command to update the environment variables: make apply-secrets
   • Run the following command: make run-pipelines ARGS="--single-repo"

   Or without modifying .env: make run-pipelines ARGS="--single-repo" PIPELINE_GIT_REPO=https://github.com/org/repo PIPELINE_GIT_BRANCH=main

2. To run the Code Understanding pipeline for multiple repositories:

   • Update workflows/examples/code_understanding/assets/repos/repo_list.json with the list of repositories to be processed.
   • Run the following command: make run-pipelines ARGS="--multi-repo"

Running Adhoc Queries

1. To run adhoc queries about the indexed code, run the following: wrappers/adhoc.sh <query>
   • For example:
     • wrappers/adhoc.sh "What migration order would be recommended when refactoring to reduce breaking changes?."
     • wrappers/adhoc.sh "Which modules or components would be riskiest to refactor first?" --git-repo https://github.com/org/repo
     • wrappers/adhoc.sh "What are the data stores in this codebase?" --git-repo https://github.com/org/repo --git-branch develop

Integrating with other tools

External tools — such as vulnerability scanners, dependency analysers, static code parsers, etc. — can contribute metadata to the data-generation workflow by writing their output as JSON file(s) into a .code_metadata directory at the root of the repository being analysed. Any files present there are automatically picked up and merged into the generated dataset before indexing. Each JSON file must conform to the code metadata schema at workflows/examples/code_understanding/assets/schemas/code_metadata_schema.json; fields not relevant to a given tool can be omitted.

More About the Code Understanding Workflow

The Code Understanding workflow is the initial iteration in the AI software modernization process. It is a tool-driven workflow which generates artifacts for the refactoring catalog. These artifacts are optionally combined with other tools (organizational vulnerability scanners, static rules engines, etc) to build the migration plan for the Code Migration workflow.

There are three main sub-workflows in the Code Understanding workflow:

1. Data Generation

The Data Generation sub-workflow is used to generate metadata that will be used for GraphRAG-based indexing. For each relevant file in the original codebase, it will generate a .txt version of the file and a new metadata file. This enriched fileset will then be passed as input to the Data Indexing workbench in the next step.

2. Data Indexing

The Data Indexing sub-workflow is used to index the fileset from the Data Generation step using GraphRAG. It will generate a graph-based representation of the codebase that can be used for querying.

3. Data Analysis

The Data Analysis sub-workflow is used to query the generated GraphRAG index using the GraphRAG SDK. It includes both canned and adhoc queries that can be used to explore the code and generate assets for the refactoring catalog, including a migration plan.