Overview
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.
2.4+watsonx Code Assistant provides an optional opt-in Chat Experience for Code Explanation
in VS Code. Opting-in means that you can initiate
an 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.
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 what the code is doing 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 and accelerate their productivity and well-documented applications for future maintainability.
- Make informed modernization decisions: With real-time explanations of their code logic in the Refactor and Transform phases, developers can form a more comprehensive understanding of their applications during a modernization project.
How does code explanation work?
- Simple explanation: gives you an overview and summary of the code.
- Detailed explanation: gives you an overview, information about the inputs and outputs of the code and a functional summary of the code.
- Guided explanation (COBOL and PL/I): gives you an overview and walk through 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. Referenced files, such as copybooks in COBOL code or Include files in JCL, are not sent in the request. The AI model processes the request and outputs the explanation. The service returns the response to the IDE.
Does Code Explanation work on different versions and variations of COBOL?
Although IBM® tested code explanation against Enterprise COBOL for z/OS V6, the model is trained on documentation from all versions of the Enterprise COBOL language. The language has evolved mainly through adding new commands, keywords, and syntax options, so you can explain code on previous versions of Enterprise COBOL. You can even try other variants such as MicroFocus COBOL or GnuCOBOL. COBOL is a standard; and therefore, the explanation is likely to be fairly accurate for other variants even where there are differences in the syntax.
How does chat experience for code explanation work?
2.4+
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 2 shows the process of how the chat experience for code explanation works.
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.
- 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?.
- 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 two other data sources (IBM ADDI and CICS CSD). The explain
agent communicates with the existing granite-20b-code-z-xplain-v1 model to provide an explanation
of the code. It also takes in follow up questions from a user, and talks to the
granite-3-8b-instruct
model to provide an answer. This answer is then sent to the orchestrator agent. - What is the ADDI agent?
- The ADDI 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 ADDI agent returns no answer to the orchestrator agent.
- What is the CICS® agent?
- The CICS agent uses a CICS System Definition data set (CSD) file as a data source to provide a response on how the resources in the CSD impact the supplied code. You provide the CSD file that you want the CICS agent to use. The CICS agent uses a knowledge base that includes some of the CICS documentation, for example the API Reference and Resource Definition Guide, to provide additional context.
For information on how to get started with the chat interface, see Enabling the chat interface.