Overview

Edit online

With the Code Explanation feature of watsonx Code Assistant™ for Z, developers and system programmers can get AI-generated explanations with the click of a button.

These explanations can be used to:

  • Reduce the knowledge gap: With real-time explanation of code, system programmers or developers without deep expertise can quickly learn the code functions or logic to accelerate development or modernization efforts.
  • Free up senior subject matter experts: For advanced modernization work, reduce knowledge bottlenecks in your organization through real-time explanation of code.
  • Increase application knowledge while reducing manual documentation: Code explanation helps to generate documentation faster, saving developers' time to focus on more critical tasks, accelerate their productivity, and develop well-documented applications for future maintainability.
  • Make informed modernization decisions: With real-time explanations of code logic in the Refactor and Transform phases, developers can form a more comprehensive understanding of their applications during a modernization project.

2.4.0+watsonx Code Assistant provides Chat Experience for Code Explanation in VS Code. You can initiate a whole program explanation from a chat window and ask some follow-on questions. In addition, explanations initiated from the context menu are displayed in the chat window. Requesting an explanation from the chat window does a program-level explanation equivalent to the Generate simple explanation menu option.

The watsonx Code Assistant for Z chat service provides chat capabilities in VS Code for your mainframe development environment. With this service, you can work with multiple specialized agents to:
Generate code
Create new code from natural language prompts or modify existing code directly from the chat interface.
Explain code with application insights
Get detailed, AI-generated explanations enriched with additional application-level insights to help you understand programs or code segments.
watsonx Code Assistant for Z chat service provides a chat interface that you can use to:
  • Get an explanation of the program and continue the conversation with follow-on questions.
  • Use the context menu to trigger explanations directly in the chat window.
  • Get application insights alongside explanations to better understand dependencies, business rules, and system context.
2.7.0+ The service is available on prem.

How does code explanation work?

You can select either COBOL or PL/I or REXX, or Assembler code, or a JCL step in your IDE and request an explanation. There are different types of explanation that you can request:
Simple explanation
Provides you an overview and summary of the code.
Detailed explanation
Provides you an overview, information about the inputs and outputs of the code, and a functional summary of the code.
Guided explanation
Provides you an overview and walkthrough of the code step by step.

The code is securely sent to the watsonx Code Assistant for Z service. The selected code is encrypted on the client and then decrypted by the back-end service. The service strips out any comments before creating the prompt, as these comments might be inaccurate and can bias the AI model output.

This process is shown in Figure 1.
Figure 1. Code Explanation overview
Code Explanation overview

Referenced files, such as copybooks in COBOL code are not sent in the request. The AI model processes the request and generates the explanation. The service returns the response to the IDE. 2.7.0+ Copybooks / JCL INCLUDE statements are expanded and sent in the request. This feature is not available in PL/I, REXX, or Assembler code.

Code Explanation architecture for on prem setup

The following diagram depicts the Code Explanation architecture for on prem setup.
Figure 2. Code Explanation on prem setup
Code Explanation on prem setup
Note: Even in the event of an error, the code is not logged or stored on the server. The code is used as in flight data to generate an explanation and is not used to train the large language model.

Does Code Explanation support native languages?

2.5.0+Yes. Code Explanation has native language support and currently, has localization support for French, Spanish, Japanese, Portuguese, and German languages.

2.6.0+ Dutch and Korean languages are also supported.

All these locales are supported on both VS Code and Eclipse based IDEs.

Native language support for Code Explanation is available only in the side panel experience. However, for follow-up questions Code Explanation generates response in English.

How does chat experience for Code Explanation work?

2.4.0+

The chat experience for Code Explanation uses an agentic framework to interpret a question and formulate a plan to answer it. This chat interface is only available when using VS Code and needs to be enabled in the settings of the IBM® watsonx Code Assistant for Z VS Code extension. Figure 3 shows the process of how the chat experience for code explanation works.
Note: To use the chat feature, make sure that you install watsonx Code Assistant VS Code extension.

The AI agents cannot be called directly. When you query a selected code snippet, each agent completes an eligibility check to see whether it can
 answer the question. The steps the agents take are generated based on the question that you ask. The agents generate potential useful information based on the question that you have asked, which is then passed to the large language model (LLM) to form an answer based on a predefined prompt.

Figure 3. Chat experience for code explanation overview
Diagram shows the following steps. 1- Developer asks a question or completes an explain code on VS Code. The orchestrator agent receives the question. 2- The orchestrator agents uses specialized agents to get information (IBM ADDI insight agent, CICS insights agent, and explain agent. 3- The orchestrator agent formulates a response and returns the answer to the chat window on VS Code.
What is an agentic framework?
An agentic framework is a collection of one or more AI agents that work together to interpret a user’s natural language request and formulate a plan to answer it.
What is an AI agent?
An AI agent is a system or program that can perform tasks on behalf of a user or another system. The agent performs these tasks by using a large language model (LLM) and a set of tools to get information. For more information, see What are AI agents?.
A tool is a way for an agent to get information. It might be a web search, dataset access, an API, or a call to a specialized AI agent. A knowledge base is a data store that an AI agent uses to complete its tasks. It can include documentation and data, as well as storing information as it completes tasks and receives feedback to learn over time.
What is the orchestrator agent?
The orchestrator agent is the first point in the agentic framework, taking in requests from the user, and formatting responses from the AI agents. The orchestrator agent uses specialized agents to help answer the question that you ask.
What is the explain agent?
The explain agent provides explanations about selected code through a chat interface, enriching that explanation with information from IBM ADDI data source. The explain agent communicates with the existing large language model to provide an explanation of the code. It also takes in follow up questions from a user, and talks to the large language model to provide an answer. This answer is then sent to the orchestrator agent.
What is the Application insights agent?
The Application insights agent queries the ADDI database using a tool to get information about related programs and data that might be helpful when providing an explanation about code. If the agent does not find any relevant database entries, the Application insights agent returns no answer to the orchestrator agent.
Note: Native language support other than English is not available in chat experience.

For information on how to get started with the chat interface, see Enabling the chat interface.