.. _Reference_AI:

Reference
=========


List of Commands
~~~~~~~~~~~~~~~~

AI Assistant provides a list of commands that you can quickly invoke using Quick Access (:kbd:`Ctrl+3`) in Eclipse and Command Palette (:kbd:`Ctrl+Shift+P`) in VS Code.

Some of these commands can also be invoked from the editor's context menu or using the buttons available in the chat view. In general, the commands are filtered based on the context in which the action is possible.

Commands for built-in blueprints appear in the list prefixed with **DVT AI Blueprint.** The rest of the commands are prefixed with **DVT AI.**

**Show All Commands**

- Lists all AI Assistant specific commands.

**Stop Generation**

-  Stop LLM reply generation.

**Set Language Model**

-  Set the default LLM that will be used from now on for new sessions.

**Start a New Session from Blueprint**

-  List all the built-in and custom blueprints.
-  The selected blueprint will start a new session.

**Start a New Chat Session**

-  Start an empty chat session.

**Run Last Session in Chat**

-  Rerun the last session only in chat, regardless of where it ran previously.

**Open Protect File**

-  Open the AI protect file.

**Send File to Prompt**

-  Focus the AI chat prompt and insert the current file as a symbol (e.g. #file:<filename>).

**Send Selected Lines to Prompt as Anchor**

-  Focus the AI chat prompt and insert the currently selected lines.
-  The selected lines will be inserted as a symbol (e.g. #file:<filename>:<startLine>-<endLine>).
-  If the file content changes from the command invocation until the prompt is sent to the LLM, the symbol expansion will include the updated content.

**Send Selected Lines to Prompt as Code Block**

-  Focus the AI chat prompt and insert the currently selected lines.
-  The selected lines will be inserted as a code block surrounded by ``````` delimiters.

**Edit Code Completion Blueprint**

- Create a custom Code Completion blueprint, offering the ability to customize the prompt that is sent to the LLM.

**Edit Predefined Blueprint**

- Customize the behavior of a predefined blueprint.

**Edit Predefined Snippet**

- Customize the behavior of a predefined snippet.

**Trigger Code Completion**

- Trigger the AI Code Completion. 

**Create New Profile**

- Create a profile from scratch.

**Create New Blueprint**

- Create a blueprint from scratch.

**Create New Problem Auto-correct Blueprint**

- Create a new problem auto-correct blueprint from scratch.

**Create New Snippet**

- Create a snippet from scratch.


Predefined Profiles
~~~~~~~~~~~~~~~~~~~

AI Assistant comes with a set of built-in profiles for common workflows:

**Basic**

- Uses default system prompt
- No tool access enabled

**Context-Aware**

- System prompt enhanced with project-specific information (@auto context)
- No tool access enabled

**Agentic**

- System prompt includes project information (@auto context) and task-specific instructions
- Full access to all tools from DVT

.. _Custom Profiles:

Custom Profiles
~~~~~~~~~~~~~~~

AI Assistant allows you to define custom profiles. The easiest way to create a custom profile is by triggering the **Create New Profile** command.

A profile file has the following format:

.. code-block:: ts

 import { ChatSessionBlueprint } from "../@api/v6"  
 export default {
     // API version
     version: 6,

     // Unique name used to identify the profile and to overwrite a built-in or custom profile
     name: 'Agentic',

     // A human-readable string which is rendered in the UI
     description: 'Edit files and access DVT compilation insights through tools.',

     // System-level instructions that are sent to the model once at the start of a session.
     // If omitted, the model receives no explicit system prompt.
     systemPrompt: 'You are an expert HDL engineer skilled in Verilog, SystemVerilog, VHDL, e Specman, RTL design, and design verification. Provide precise, concise, and technically accurate answers. When discussing hardware behavior, be explicit about timing, resets, clocks, and synthesis implications. When giving code, ensure it is synthesizable unless otherwise requested, and follow best practices for style, linting, assertions, and verification methodology (UVM/SystemVerilog). Always clarify assumptions and highlight potential hardware or simulation pitfalls.',

     // A collection of tool identifiers that are *exposed* to the model when this profile is active.
     //
     // The value can be:
     //   * a single glob string,
     //   * an array of glob strings,
     //   * or an asynchronous function that resolves to either of the above.
     //
     // Glob syntax ('*' and '?') is supported.
     toolSet: '*'
 } satisfies Profile;

The profile must be a valid **TypeScript** file with the **.ts** extension.

AI Assistant looks for the profile files in these locations:

-  **$DVT_HOME/config/ai/profiles/*.ts**
-  **$DVT_AI_DIR/profiles/*.ts**
-  **$HOME/.dvt/ai/profiles/*.ts**
-  **<project>/.dvt/ai/profiles/*.ts**


.. _Predefined Blueprints:

Predefined Blueprints
~~~~~~~~~~~~~~~~~~~~~

AI Assistant comes with a set of built-in blueprints for common tasks:

**Explain the selected code (chat)**

-  Instructs the LLM to explain the selected code in a concise manner.
-  The user request defined by the blueprint and the LLM reply appear in the chat. You can change the request, regenerate the reply or continue the conversation.

**Explain problem (chat)**

-  Asks the LLM to explain the compilation problem.
-  The user request defined by the blueprint and the LLM reply appear in the chat. You can change the request, regenerate the reply or continue the conversation.

**Summarize remote changes ahead of current commit (chat)**

-  Asks the LLM to summarize the remote changes ahead of the local HEAD.
-  The user request defined by the blueprint and the LLM reply appear in the chat. You can change the request, regenerate the reply or continue the conversation.   

**Code review uncommitted changes (chat)**

-  Asks the LLM to code review all of your **tracked**.
-  The user request defined by the blueprint and the LLM reply appear in the chat. You can change the request, regenerate the reply or continue the conversation.
  
**Generate commit message (chat)**

-  Asks the LLM to generate an adequate commit message for the currently staged changes.
-  The user request defined by the blueprint and the LLM reply appear in the chat. You can change the request, regenerate the reply or continue the conversation.

**Add comment to the selected code (editor)**

-  Instructs the LLM to add comments for an element (e.g. module, class) or a section of code.
-  Changes appear in the editor. You can review and accept or revert the generated description.

**Improve the selected code (editor)**

-  Instructs the LLM to suggest and apply improvements for the selected code.
-  Changes appear in the editor. You can review and accept or revert the generated code.

**Analyze and fix the selected code (editor)**

-  Instructs the LLM to find and fix any problems identified in the selected code.
-  Changes appear in the editor. You can review and accept or revert the generated code.

**Generate coverage for the current class (editor)**

-  Instructs the LLM to generate coverage in the form of covergroups in the class at the current cursor position.
-  Changes appear in the editor. You can review and accept or revert the generated code.

**Generate convert2string for the current class (editor)**

-  Instructs the LLM to generate the convert2string function in the class at the current cursor position.
-  Changes appear in the editor. You can review and accept or revert the generated code.

**Add logging to the selected code (editor)**

-  Instructs the LLM to add logging statements to the selected code.
-  Changes appear in the editor. You can review and accept or revert the generated code.

**Insert git commit message (git-source-control)**

-  Asks the LLM to generate an adequate commit message for the currently staged changes.
-  The LLM reply is inserted in the commit message box.

.. note:: 

 All built-in blueprints provide additional context to the LLM (e.g. the whole file containing the selection).


.. _Custom Blueprints:

Custom Blueprints
~~~~~~~~~~~~~~~~~

AI Assistant allows you to define custom blueprints. The easiest way to create a custom blueprint is by:

-  Triggering the **Create New Blueprint** command
-  Saving a chat request using the **Save Message as Blueprint** button
-  Saving a chat session using the **Save Chat Session as Blueprint** button

A blueprint file has the following format:

-  **Chat Blueprint**

.. code-block:: ts

 import { ChatSessionBlueprint } from "../@api/v6"  
 export default {
     // API version
     version: 6,

     // Unique name used to identify the blueprint and to overwrite a built-in or custom blueprint
     name: 'Write a 4-bit counter',

     // The canonical name or id of the used profile. If the specified profile is not found, a default one will be used.
     profile: 'Agentic',

     // The assistant's reply to the blueprint's messages will target the chat
     target: 'chat',

     // The messages (requests and replies) used to create the new session:
     // - At least one message must be present
     // - Sessions started from this blueprint will automatically pull a reply from the LLM when the last message is a user message
     messages: [{
         // Roles can be 'user', 'assistant' or 'tool'
         role: 'user',
         text: `Write a 4-bit counter in @language.`
     }]
 } satisfies ChatSessionBlueprint

-  **Editor Blueprint**

.. code-block:: ts

 import { EditorSessionBlueprint } from "../@api/v6"  
 export default {
     // API version
     version: 6,

     // Unique name used to identify the blueprint and to overwrite a built-in or custom blueprint
     name: 'Write a 4-bit counter',

     // The canonical name or id of the used profile. If the specified profile is not found, a default one will be used.
     profile: 'Agentic',

     // The assistant's reply to the blueprint's messages will target the editor
     target: 'editor',

     // Editor action
     // ('replace' | 'insert' | 'insert-before-selection' | 'insert-after-selection')
     action: 'replace',

     // The messages (requests and replies) used to create the new session:
     // - At least one message must be present
     // - Sessions started from this blueprint will automatically pull a reply from the LLM when the last message is a user message
     // - When targeting the editor, the last blueprint message must be a user message to which the LLM will reply in the editor
     messages: [{
         // Roles can be 'user', or 'assistant'
         role: 'user',
         text: `Write a 4-bit counter in @language.`
     }]
 } satisfies EditorSessionBlueprint

The blueprint must be a valid **TypeScript** file with the **.ts** extension.

AI Assistant looks for the blueprint files in these locations:

-  **$DVT_HOME/config/ai/blueprints/*.ts**
-  **$DVT_AI_DIR/blueprints/*.ts**
-  **$HOME/.dvt/ai/blueprints/*.ts**
-  **<project>/.dvt/ai/blueprints/*.ts**


.. _AI Predefined Snippets:

Predefined Snippets
~~~~~~~~~~~~~~~~~~~

AI Assistant provides a library of prompt snippets with different intents:

-  Structured information from DVT's database.
-  Specific code sections from your project.
-  Reusable instructions for the LLM.

Snippets are presented with their full syntax and options. Snippet parts starting with a vertical bar '|' are optional.

**@language**

-  Languages used in the code selection or in the project (e.g. SystemVerilog, VHDL).

**@selected <type:...> | wrap between <prefix:string> <suffix:string> | indicate cursor position**

-  Type options: code, file, container, element, action_block, method, port_list, class, module, interface, unit, struct, package, entity, architecture, configuration.
-  Code sections based on the editor selection or cursor position.
-  The selection will be adjusted to represent the specified type (e.g. the method where the cursor is placed, the entire class or module or the full content of the file).
-  When **indicate cursor position** is used, a comment (*[[CURSOR IS HERE]]*) is added at the end of the line that contains the cursor.

**@usages of selected element | show <lines:number> surrounding lines | limit to <max:number> | separate with <separator:string> | wrap between <prefix:string> <suffix:string>**

**@usages of <sym:symbol> | show <lines:number> surrounding lines | limit to <max:number> | separate with <separator:string> | wrap between <prefix:string> <suffix:string>**

-  Usages of the selected element or specified #symbol throughout your project.
-  By default, the entire scope of the usage will be attached. Use **show <lines:number> surrounding lines** to show the line that contains the usage and **lines** lines before and after. 
-  By default, 5 usages will be collected from your project, use **limit to <max:number>** to change this number.
-  Wildcards (``*``) can be used in the name of the symbol.

**@filename of selected file**

**@filename of <symbol:symbol> | separate with <separator:string>**

- The file name (last segment in file path) of the active editor or the file name of the specified #symbol's definition.
- Wildcards (``*``) can be used in the name of the symbol.

**@examples of <type:...> | limit to <max:number> | separate with <separator:string> | wrap between <prefix:string> <suffix:string>**

-  Type options: uvm_agent, uvm_component, uvm_driver, uvm_env, uvm_mem, uvm_monitor, uvm_object, uvm_reg, uvm_reg_adapter, uvm_reg_backdoor, uvm_reg_block, uvm_reg_field, uvm_reg_fifo, uvm_reg_file, uvm_reg_frontdoor, uvm_reg_map, uvm_reg_predictor, uvm_reg_sequence, uvm_scoreboard, uvm_sequence, uvm_sequence_item, uvm_sequencer, uvm_test.
-  Code sections with classes implementing the specified UVM component.
-  By default, 5 examples will be collected from your project, use **limit to <max:number>** to change this number.

**@execute command <command:string> | limit to <max:number> chars | timeout <timeout:number> seconds | allow non zero exit code**

-  Expands to the output of the provided command.
-  When executing the command, the current working directory is consider to be the project root.
-  By default, the output will be truncated to less than 250KB, use **fit into <max:number> chars** to change this number.
-  By default, the command times out after 5 seconds, use **timeout <timeout:number> seconds** to change this number.
-  By default, an error is thrown when the process ends with a non zero exit code, use **allow non zero exit code** to change this behavior and capture output anyway. In this case stderr will be included in the final expansion.

**@outline of selected <type:...> | wrap between <prefix:string> <suffix:string>**

**@outline of <symbol:symbol> | wrap between <prefix:string> <suffix:string> | separate with <separator:string>**

-  Type options: file, container.
-  Tree structured outline of the selected file/container (based on the editor selection or cursor position) or of the specified #symbol.
-  Wildcards (``*``) can be used in the name of the symbol.
-  Useful for providing summarized information about specific parts of the project without sending the full source code.

**@symbol <sym:symbol> | limit to <max:number> | separate with <separator:string> | wrap between <prefix:string> <suffix:string>**

-  Symbols from the current project that match a specific query.
-  An alternative for #symbols that offers control over the number of results and the way they are wrapped before being sent to the LLM.
-  Wildcards (``*``) can be used in the name of the symbol.

**@recent code sections | limit to <max:number> | separate with <separator:string> | wrap between <prefix:string> <suffix:string> | exclude active editor**

**@recent code sections from open editors | limit to <max:number> | separate with <separator:string> | wrap between <prefix:string> <suffix:string> | exclude active editor**

-  Recently visited code sections from any file or restricted to the currently opened editors.
-  Useful for providing information about the current task based on the code sections recently visited.
-  By default, the last 5 code sections will be provided, use **limit to <max:number>** to change this number.
-  If **exclude active editor** is used, code sections from the active editor will not be included in the output of the snippet.

**@design hierarchy | expand up <up_levels:number> | expand down <down_levels:number>**

**@verification hierarchy | expand up <up_levels:number> | expand down <down_levels:number>**

-  Tree structure representation of the design or verification hierarchy starting from the current editor scope.

**@problems from selected <type:...> | limit to <max:number> | filter by severity <severity:...> | exclude problematic code**

-  Type options: code, container, file.
-  Severity options: error, warning.
-  Compilation problems reported by DVT inside the selected code, container or file.
-  By default, the problematic code/file will be included as well. To prevent this, use **exclude problematic code**.

**@dependencies of selected <type:...> | show as <show_as:...> | fit into <max:number> chars | separate with <separator:string> | wrap between <prefix:string> <suffix:string>**

**@dependencies of <sym:symbol> | show as <show_as:...> | fit into <max:number> chars | separate with <separator:string> | wrap between <prefix:string> <suffix:string>**

-  Type options: container, file.
-  Type and macro dependencies used inside the selected container/file or inside the specified #symbol. Only the types of declared elements are collected along with definition of used macros.
-  Wildcards (``*``) can be used in the name of the symbol.
-  **fit into <max:number> chars**: used to limit the size of the entire snippet expansion.
-  **show as <show_as:...>** options: outline, code.

**@replicate selected pattern <N:number> times**

-  Reusable task asking the LLM to replicate the currently selected code pattern N times.
-  Useful for generating repetitive sections of code that follow a pattern (e.g. 1 2 3 ...).

**@reply only with code**

-  Reusable instruction asking the LLM to reply only with valid code in the language of current code selection or project. It also forbids the LLM to use markdown to format its reply.
-  Useful in editor sessions that redirect the replies to the editor.

**@kind of selected container**

-  Kind of the container  (e.g. class, module) within the current editor selection or cursor position.

**@name of selected container**

-  Name of the container within the current editor selection or cursor position.

**@auto context | extended format**

- Project information and additional code snippets that are relevant for the current task.

**@comments of <elementType:...> | format <formatType:...>**

- ElementType options: class, module, interface, entity, element.
- FormatType options: Markdown, Javadoc, NaturalDocs, Autodetect, Verbatim.
- Predefined comments examples for the given element type in the given format.

.. note::

    In the snippets above, the term 'container' refers to the enclosing scope (such as a class, module, or function) that surrounds the current cursor position.

.. _Custom Snippets:

Custom Snippets
~~~~~~~~~~~~~~~

AI Assistant allows you to define custom snippets. The easiest way to create a custom snippet is by saving a chat request using the **“Save Message as Snippet”** button.

A snippet file has the following format:

.. code-block:: ts

 import { PromptSnippet } from "../@api/v6";
 export default {
     // API version
     version: 6,

     // Unique name used to identify the snippet and to overwrite a built-in or custom snippet
     name: 'Intro',

     // Snippet signature used to refer to this snippet
     signature: '@intro',

     // Whether to expand snippets and symbols nested in the prompt string
     expand: true,

     // The prompt string (snippet expansion)
     prompt: 'Act as a @language engineer.'
 } satisfies PromptSnippet

The snippet must be a valid **TypeScript** file with the **.ts** extension.

AI Assistant looks for the snippet files in these locations:

-  **$DVT_HOME/config/ai/snippets/*.ts**
-  **$DVT_AI_DIR/snippets/*.ts**
-  **$HOME/.dvt/ai/snippets/*.ts**
-  **<project>/.dvt/ai/snippets/*.ts**

Watermarking AI Generated Code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AI Assistant can automatically label code produced by LLMs. It wraps such code with the comments ``@AI_GENERATED_CODE_BEGIN`` and ``@AI_GENERATED_CODE_END``.

This watermark is applied to:

-  **Code blocks** generated in the chat view.
-  Code that is inserted directly into the editor via **Editor Blueprints**.

To enable / disable AI generated code:

- Open VS Code Settings using :kbd:`Ctrl+,` and check / uncheck :menuselection:`DVT --> AI --> Add Generated Code Watermark --> Enabled`
- Open Eclipse Preferences using :menuselection:`Window --> Preferences` and check / uncheck :menuselection:`DVT --> AI Assistant --> Add Generated Code Watermark`
