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

Wing always sends at least some of the contents of your current editor to the AI provider as part of
its AI requests. At your discretion, other files, code, or text may be added as additional context
for the request. This can improve the results you receive for your requests, so they are better
tailored to your existing code base.

In general, you should think about whether your request needs anything more than the contents of the
current file and the AI's training set to be answered correctly. If you are asking the AI to write
or rewrite code using only code in the current file, then you do not need to include additional
context. On the other hand, if your request needs to use imported custom modules that won't exist in
the AI's training set, then you will get better results if you first add those imports to your file
and include them as context for your request.  You can also use added context to show the AI an
example of the code you want, to feed it a more detailed specification, and to provide any other
materials that will be useful in processing your request.

Adding context can cause your requests to become more compute intensive and costly, so you will want
to include additional context only when necessary. The more relevant and focused context you
provide, the better results you will obtain at reasonable cost. Poorly selected context may cause
your requests to take longer to complete, cost more, and you may reach rate limits imposed by the AI
provider. Providing irrelevant context may also have a negative impact on the quality of that results
that you receive.

**Selecting Context**

Every AI feature in Wing has the ability to select and use custom context for the requests it makes
to the AI provider. The context used for AI suggest is selected from the ``AI Suggestion Context``
submenu of the ``AI`` menu, while the contexts used for the ``AI Coder`` and ``AI Chat`` tools are
selected from their ``Context`` menus.  All these tools can share the same context, or you can
define multiple contexts and use different contexts in each tool.  Contexts may be saved contexts 
to make building similar requests easier in the future.

*Automatic Context*

For each saved context, you can ask Wing to automatically include certain project files as
context with your AI requests.  These are implemented by the following items in the ``Context``
menus:

* ``Include Imported Project Files`` specifies whether imported project files 
  should automatically be included as request context.
  
* ``Include Open Project Files`` specifies whether open project files that were 
  not imported should automatically be included as request context.
  
* ``Include Other Project Files`` specifies whether other project files that were
  not imported and are not open in an editor should be automatically included as 
  request context.
  
*Manual Context*

Stored contexts can also include other manually specified context items.  These are added with the 
following items in the ``Context`` menus:

* ``Add Current Selection`` adds the current editor selection to the AI request context.  A copy of the
  selection is stored and used in the context with each request.

* ``Add Current Scope`` adds the current Python scope to the AI request context.  This stores the filename
  and scope name and retrieves the current contents of that scope at the time of each request, so that 
  changes made to the code will be tracked in the context over time.
  
* ``Add Current File`` adds the current file to the context.  This stores the filename and retrieves
  the current contents of the file at the time of each request.

Each of these menu items displays a dialog where you can enter a description of the context item's
content and/or purpose. Common examples like "an example of the code I want" and "code to use in the
implementation" and also recently used descriptions are available from the drop down menu to the
right of the ``Description`` text entry area.

If there are any manually added context items, you can select individual items from the ``Context``
menu to edit or remove them, or use ``Clear Manual Context`` to remove them all at once.

**Viewing and Refining Context**

The AI context manager adds context to your AI requests in the following order: (1) your manually
specified context items, (2) any project files that are imported into the current file, (3) any
other project files that are currently open in an editor, and (4) any other files in the project
that were not imported or open in an editor. To increase the chances that the more relevant files
are included, more recently used files are given priority. For imported files, the later imports in
a file are used first, in the hope that they will contain more useful high-level context.

Because generative AI is computationally intensive, often only a subset of all possible context can
actually be included with your request. You can further refine which context items to include by 
using the AI context item selector menus.  

For AI suggest, the AI context item selector menu is accessed by clicking on the |suggestcontext|
icon that appears in the top right of the editor if there is any added context in the current AI
suggest context.

.. |suggestcontext| image:: icon:wingide-ai-context
  :class: inline-image

For ``AI Coder`` and ``AI Chat`` the AI context item selector menu is accessed by clicking on the
|completecontext| icon that appears to the left of the ``Context`` menu in those tools whenever
there is any added context in their current AI context.

.. |completecontext| image:: icon:wingide-context-ready
  :class: inline-image

The menu indicates automatically included context items with a small green dot |autoinclude| next to
the file name. Items that are candidates for inclusion but that exceeded the constraints on context
size are shown further down the list, without any icon next to them.

.. |autoinclude| image:: icon:wingide-context-extra
  :class: inline-image

If you select a context item that is currently automatically being included in request context, that
item will be blocked from being used subsequently in context. This is a good way to exclude large
files or those that may not add much value to your requests. Context items blocked from inclusion
are indicated with a red "do not enter" icon |excluded|. This action may free up some space in the
available context, and thus allow selection of another file for automatic inclusion in request
context. The menu's icons will update accordingly.

.. |excluded| image:: icon:wingide-context-excluded
  :class: inline-image

Selecting an item that is not currently included in the request context will explicitly add it to
the context, and remove the lowest priority automatically added item. Explicitly selected context
items are marked with a green check mark |included|. If too many items are selected for explicit
inclusion, then some may not be able to be included after maximum context size is reached. Those
items will be indicated in the menu with a yellow or orange check mark |surplus|.

.. |included| image:: icon:wingide-context-included
  :class: inline-image
.. |surplus| image:: icon:wingide-context-included-surplus
  :class: inline-image

The context size thresholds used to build AI requests are configured in the AI provider
configuration, under the ``Context`` tab, as described in `Configuring AI Providers
<ref:ai/provider>`__.

*AI Suggest and AI Coder*

For AI suggest and the ``AI Coder`` tool, context is computed when the request is sent to the AI
provider, limited by the configured constraints on request size. In many cases, only a subset of
your selected context can be included. Wing builds this subset in a way that attempts to retain
important code structure, while omitting the details of some parts of the implementation. If a
subset of a file is being included as context for AI suggest and transformation, this is indicated
in the context status popup menu, as described above.

*AI Chat*

For AI chat, Wing instead uploads context items to the AI provider ahead of time, to act as context
for your conversation with the AI assistant. The upload status of context is indicated by the icon to
the left of the ``Context`` menu in the AI Chat tool. You will see this indicator change color and
animate whenever you change focus, if you add or remove imports in a file, or if you take any other
action that changes the set of items to include in your AI request context.

If the icon is not green, then the AI assistant does not have access to all the context items and
you may receive results that reflect their omission. You can see which files have been uploaded,
which are still being uploaded, and which failed to upload in the context status popup menu.

The icons used are:

|waiting| -- An animated version of this icon indicates the context files are being uploaded.

|ready| -- Indicates that all context files have been uploaded and the AI assistant is
ready for requests.

|warning| -- Indicates that one or more files failed to upload but requests can still be
made to the AI assistant.

|error| -- Indicates that a fatal error is preventing requests to the AI assistant. Use
``Show Console`` in the ``Options`` menu to diagnose the problem.

|disallowed| -- Indicates that you have not given Wing permission to upload any data
to an AI provider.  In this case the AI features are entirely disabled.  You will be 
prompted to allow uploads if you try to use any of them.

.. |waiting| image:: icon:wingide-context-waiting-b
  :class: inline-image
.. |ready| image:: icon:wingide-context-ready
  :class: inline-image
.. |warning| image:: icon:wingide-context-warning
  :class: inline-image
.. |error| image:: icon:wingide-context-error
  :class: inline-image
.. |disallowed| image:: icon:wingide-context-disallowed
  :class: inline-image
  
