<type>documentation</type>
<domain>ai</domain>
<id>description</id>
<title>AI Coder Tool</title>
<date>$Date: 2006-05-24 22:53:07 -0400 (Wed, 24 May 2006) $</date>
<version>$Revision: 13098 $</version>
<product>pro+</product>

Wing Pro's ``AI Coder`` tool lets you write new code or modify existing code by describing its
intended functionality and design.  This tool will operate on the code that is indicated by
the ``Target`` and any selection in the current editor.  The target may be one of:

* ``Current Selection`` transforms only the current selection, or if there is no selection
  then it will add code at the current insertion point according to your instructions.
  
* ``Current Block`` restricts changes to the current like-or-greater indented
  block of code.
  
* ``Current Scope`` limits code changes to the innermost named scope (a ``class``
  or ``def``) at the current caret position in the editor.
  
* ``Whole File`` allows the AI to change code anywhere in the current file.

The ``Target`` popup menu also includes ``Use Request Config``, which uses the target 
configured in the current saved request configuration, or the most recently used target 
type if the saved xsrequest does not specify one.  See `Saved Requests <ref:ai/requests>`__ 
for more information on setting up and using saved AI requests.

Once you have selected a target and entered your instructions, press ``AI Transform`` to initiate
the process. AI transformation requests may take quite a while to complete, but they are capable of
producing changes that would take far more time to make manually.

You can cancel AI transformation requests by pressing the ``Abort`` button in the ``AI Coder`` tool.
If you do not cancel and the request completes, then Wing will enter the AI-generated code into the
editor, replacing the code in the specified ``Target``, if any. By default code is simply replaced so
that a single ``Undo`` will undo the changes if it turns out that you do not want them.  Other options 
for how AI changes are applied are available in the ``AI Coder`` tool's ``Action`` menu, as described 
below. 

**Context**

By default Wing sends only part or all of the current file with your AI request. If the code you
want the AI to write needs to know about other code in your project, you can ask Wing to include
that by setting up and selecting an AI context from the ``Context`` menu in the ``AI Coder`` tool.
See `AI Request Context <ref:ai/context>`__ for details.

**Action**

The ``Actions`` menu in ``AI Coder`` tool controls how to place transformation results into the
editor when the request completes:

* ``Use Request Config`` uses the ``Result Action`` specified in the current request.

* `` Replace Old Code`` replaces the existing code with the AI transformation of the code, using the
  ``Replace Method`` configured below. This is the default option.
  
* ``Create New File`` creates a new untitled file of the appropriate type and pastes the
  new code into it.
  
When ``Replace Old Code`` is selected, any of the following methods for replacing code may
be used.  This is a preference that applies to all projects and is selected from the 
``Action`` menu in the ``AI Coder`` tool:

* ``Overwrite Old Code`` replaces the old code in the editor without any other changes.  This is
  the default.  A single ``Undo`` will undo the changes and restore the previous version of the code.
  
* ``Comment Out Old Code`` comments out the old code and pastes in the AI generated code after
  the end of the comment.
  
* ``Start Review to Accept (Default=Reject)`` enters into ``Diff/Merge`` mode so that you
  can compare the changes and selectively accept them.  In this mode, changes are rejected
  by default if you end the session without reviewing all of them.  After the review session
  starts, the new version of the code written by AI will be on the left and the initially 
  unaltered target file will be on the right.  You can accept proposed changes with the 
  floating buttons that appear between the highlighted changes in the editors, or also the 
  buttons that appear in the ``AI Coder`` tool or the diff/merge tool group in the top-level toolbar.
  Once you have reviewed all the changes, the review session ends automatically.  You can also
  end the session without reviewing all the changes with the ``Done`` button in the ``AI Coder`` 
  tool or the |mergecancel| icon in the top-level toolbar.
  
* ``Start Review to Reject (Default=Accept)`` works similarly, except that the AI's changes
  will be applied immediately and the review session displays the old version of the code 
  on the left and the new version on the right.  In this mode, changes are accepted by default
  if you end the session without reviewing all of them.
  
.. |mergecancel| image:: icon:wingide-ai-review-done
  :class: inline-image

**Requests**

The ``Requests`` menu in the ``AI Coder`` tool allows you to create, edit, manage, and load
saved requests.  See `Saved Requests <ref:ai/requests>`__ for more information.

**Options**

The ``Options`` menu provides the following:

``Enter Key Executes Transform`` causes Wing to immediately execute the currently entered
transformation request when ``Enter`` is pressed in the entry area. When this is enabled, you can
still enter a newline into the request by pressing ``Ctrl-Enter``.

`History Previous`` and ``History Next`` traverse a history of AI request strings. You can also do
this by pressing ``Ctrl-Up`` and ``Ctrl-Down`` while focus is in the ``AI Coder`` tool's request
entry area. This just traverses the history of request strings and does not change target, context, 
or action.

``Switch to Provider`` and ``Manage AI Providers`` are used to select the AI provider currently
in use by Wing's AI integration.  See `Configuring AI Providers <ref:ai/context>`__ for details.

``Revoke Upload Permission`` revokes earlier permission for Wing to upload content to the 
AI provider, so that no content of any kind will be uploaded until permissions is once again
granted for Wing to do so.

``Reset Costs`` resets the stored AI request costs that are shown at the bottom of the ``AI Coder`` tool
for the most recent request and all requests made so far.  The accuracy of the costs displayed relies
on the correctness of model pricing in the AI provider configuration.

``Show Console`` shows a diagnostic console in the ``AI`` tool, which can be used
to inspect the AI requests that are made and their results.  This should only be
needed when there are problems with the AI integration or if you want to see what
data is being sent to the AI provider.

``Show Documentation`` displays this documentation.

**Key Binding**

If you prefer a different key binding for this feature, you can bind the command
``ai-coder`` to any key sequence with the `User Interface > Keyboard > Custom Key
Bindings <script:show_preferences_gui#prefname="gui.keymap-override">`__ preference.

