@appland/appmap 3.142.1 → 3.144.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@appland/appmap-v3.144.0](https://github.com/getappmap/appmap-js/compare/@appland/appmap-v3.143.0...@appland/appmap-v3.144.0) (2024-05-19)
+
+
+### Features
+
+* Sync only high level docs ([5186e4e](https://github.com/getappmap/appmap-js/commit/5186e4e0c896324b808e5341878b02da6df41e3a))
+
+# [@appland/appmap-v3.143.0](https://github.com/getappmap/appmap-js/compare/@appland/appmap-v3.142.1...@appland/appmap-v3.143.0) (2024-05-17)
+
+
+### Features
+
+* Emit agent and classification events ([a73bcaa](https://github.com/getappmap/appmap-js/commit/a73bcaa276835b8def2d56c270aab358ca35443f))
+
 # [@appland/appmap-v3.142.1](https://github.com/getappmap/appmap-js/compare/@appland/appmap-v3.142.0...@appland/appmap-v3.142.1) (2024-05-17)
 
 

package/built/docs/get-started-with-appmap/navie-ai-quickstart.md

@@ -31,11 +31,7 @@ By default, Navie will utilize an OpenAI service hosted by AppMap. If, for data
 
 When you ask a question to Navie, it will search through all your AppMap Diagrams (if they exist) for your project to pull in relevant traces, sequence diagrams, and code snippets for analysis. It will then send these code snippets and runtime code sequence diagrams to the Generative AI service along with your question. 
 
-You can ask free-form questions, or start your question with one of these commands:
-
-- `@explain`: (Default) Help you understand your project. This mode is used when there is no prefix.
-- `@help`: Get assistance with configuring and using AppMap.
-- `@generate`: Optimizes the answer to focus on new code generation.
+Refer to the [Using Navie docs](/docs/navie/using-navie) to learn more about the advanced Navie chat commands you can use with your question. 
 
 After asking Navie a question, Navie will search through your application source code, finding any relevant code snippets. It will include relevant AppMap Data like sequence diagrams and data flows if they exist for your project. You will see on the right hand side of the Navie window the relevant context from your code included with the question. 
 

package/built/docs/navie/bring-your-own-model.md

@@ -2,7 +2,7 @@
 layout: docs
 title: Docs - Navie
 name: Bring Your Own LLM Model
-step: 3
+step: 4
 navie: true
 toc: true
 description: Use AppMap Navie with your own OpenAI account or OpenAI-compatible LLM running either locally or remotely.
@@ -15,26 +15,63 @@ By default, when asking a question to Navie, your code editor will interact with
 - [Navie AI Recommended Models](#navie-ai-recommended-models)
 - [Bring Your Own OpenAI API Key (BYOK)](#bring-your-own-openai-api-key-byok)
   - [Configuring Your OpenAI Key](#configuring-your-openai-key)
+    - [Modify which OpenAI Model to use](#modify-which-openai-model-to-use)
   - [Reset Navie AI to use Default Navie Backend](#reset-navie-ai-to-use-default-navie-backend)
 - [Bring Your Own Model (BYOM)](#bring-your-own-model-byom)
   - [Configuration](#configuration)
   - [Configuring in JetBrains](#configuring-in-jetbrains)
   - [Configuring in VS Code](#configuring-in-vs-code)
 - [Examples](#examples)
-  - [OpenAI](#openai)
-  - [Azure OpenAI](#azure-openai)
-  - [AnyScale Endpoints](#anyscale-endpoints)
-  - [Ollama](#ollama)
-  - [LM Studio](#lm-studio)
 
 ## Navie AI Recommended Models
 
 <p class="alert alert-danger">
 AppMap Navie AI recommends avoiding models that do not support chat mode.
 </p>
-<!-- This doc is located at https://docs.google.com/presentation/d/145gzoYVsgJ3J4jGh_2Or8ClZ0drqoC-GTjI1UqkyF_o/edit#slide=id.g1ff63dc2dd6_0_0 -->
 
-![Navie Recommended Models](/assets/img/product/navie-model-recommendations.svg)
+<table class="table table-striped table-bordered black-white-table">
+  <tr>
+    <tr>
+      <th class="large-header">Navie AI Backend LLM</th>
+      <th class="large-header">Ease of Setup</th>
+      <th class="large-header">Quality of Responses</th>
+  </tr>
+  <tr>
+    <tr>
+      <td>AppMap OpenAI Proxy (default)</td>
+      <td>⭐⭐⭐⭐⭐</td>
+      <td>⭐⭐⭐⭐⭐</td>
+  </tr>
+  <tr>
+    <tr>
+      <td>Self Managed OpenAI API Key</td>
+      <td>⭐⭐⭐⭐</td>
+      <td>⭐⭐⭐⭐⭐</td>
+  </tr>
+      <tr>
+      <td>Azure Hosted OpenAI</td>
+      <td>⭐⭐⭐</td>
+      <td>⭐⭐⭐⭐⭐</td>
+  </tr>
+  </tr>
+      <tr>
+      <td>Anyscale Hosted Mixtral-8x7B</td>
+      <td>⭐⭐⭐</td>
+      <td>⭐⭐⭐</td>
+  </tr>
+  </tr>
+      <tr>
+      <td>Locally Hosted Mixtral-8x7B-Instruct-v0.1</td>
+      <td>⭐⭐</td>
+      <td>⭐⭐⭐</td>
+  </tr>
+  </tr>
+      <tr>
+      <td>Codellama/Codeqwen</td>
+      <td>❌ Not Supported</td>
+      <td>❌ Not Supported</td>
+  </tr>
+</table>
 
 ## Bring Your Own OpenAI API Key (BYOK)
 
@@ -44,19 +81,33 @@ Navie AI uses the AppMap hosted proxy with an AppMap managed OpenAI API key. If
 
 In your code editor, open the Navie Chat window. If the model displays `(default)`, this means that Navie is configured to use the AppMap hosted OpenAI proxy.  Click on the gear icon in the top of the Navie Chat window to change the model. 
 
-![Navie Recommended Models](/assets/img/product/navie-default-model.webp)
+![Navie configuration gear](/assets/img/product/navie-default-model.webp)
 
 In the modal, select the option to `Use your own OpenAI API key`
 
-![Navie Recommended Models](/assets/img/product/navie-byok-openai-1.webp)
+![Use your own key modal](/assets/img/product/navie-byok-openai-1.webp)
 
 After you enter your OpenAI API Key in the menu option, hit `enter` and your code editor will be prompted to reload.
 
-![Navie Recommended Models](/assets/img/product/navie-byok-openai-2.webp)
+**In VS Code:**
+![VS Code popup to store API Key](/assets/img/product/navie-byok-openai-2.webp)
+
+**In JetBrains:**
+![JetBrains popup to store API Key](/assets/img/product/navie-byok-jetbrains.webp)
+
+**NOTE:** You can also use the environment variable in the [configuration](#configuration) section to store your API key as an environment variable instead of using the `gear` icon in the Navie chat window. 
 
 After your code editor reloads, you can confirm your requests are being routed to OpenAI directly in the Navie Chat window. It will list the model `OpenAI` and the location, in this case `via OpenAI`.
 
-![Navie Recommended Models](/assets/img/product/navie-byok-openai-3.webp)
+![OpenAI location](/assets/img/product/navie-byok-openai-3.webp)
+
+#### Modify which OpenAI Model to use
+
+AppMap generally uses the latest OpenAI models as the default, but if you want to use an alternative model like `gpt-3.5` or a preview model like `gpt-4-vision-preview` you can modify the `APPMAP_NAVIE_MODEL` environment variable after configuring your own OpenAI API key to use other OpenAI models.  
+
+After setting your `APPMAP_NAVIE_MODEL` with your chosen model reload/restart your code editor and then confirm it's configuration by opening a new Navie chat window. In this example i've configured my model to be `gpt-4o` with my personal OpenAI API Key. 
+
+![JetBrains OpenAI key modal](/assets/img/product/custom-model.webp)
 
 ### Reset Navie AI to use Default Navie Backend
 
@@ -124,8 +175,6 @@ After reloading you can confirm the model is configured correctly in the Navie C
 
 #### Editing AppMap services environment <!-- omit in toc -->
 
-**Note**: To store the API key securely with VS Code secret storage, follow [the instructions below](#add-a-new-openai-key).
-
 In VS Code, go to settings.
 
 <img class="video-screenshot" src="/assets/img/docs/goto-vscode-settings.webp" alt="a screenshot of the Visual Studio Code menu"/>
@@ -140,136 +189,10 @@ Use *Add Item* to define the relevant environment variables according to the [BY
 
 Reload your VS Code for the changes to take effect.  
 
-**NOTE:** Please follow the instructions below to set `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` securely.
-
 After reloading you can confirm the model is configured correctly in the Navie Chat window.
 
 <img class="video-screenshot" src="/assets/img/product/navie-confirm-ui-vscode.webp"/>
 
-#### Add a new OpenAI Key <!-- omit in toc -->
-
-In VS Code, open the Command Palette.
-
-You can use a hotkey to open the VS Code Command Palette
-   - Mac: `Cmd + Shift + P`
-   - Windows/Linux: `Ctrl + Shift + P`
-
-Or you can select `View` -> `Command Palette`
-
-<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
-
-Search for `AppMap Set OpenAPI Key`
-
-<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
-
-Paste your key into the new field and hit enter.
-
-You'll get a notification in VS Code that your key is set. 
-
-**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
-
-<img class="video-screenshot" src="/assets/img/product/byok-key-set.webp"/> 
-
-#### Delete a configured OpenAI Key <!-- omit in toc -->
-
-To delete your key, simply open the Command Palette
-
-You can use a hotkey to open
-   - Mac: `Cmd + Shift + P`
-   - Windows/Linux: `Ctrl + Shift + P`
-
-Or you can select `View` -> `Command Palette`
-
-<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
-
-Search for `AppMap Set OpenAPI Key`
-
-<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
-
-And simply hit enter with the field blank.  VS Code will notify you that the key has been unset.
-
-**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
-
-<img class="video-screenshot" src="/assets/img/product/byok-key-erased.webp"/> 
-
-#### How is my API key saved securely? <!-- omit in toc -->
-
-For secure storage of API key secrets within AppMap, we use the default VS Code secret storage which leverages  Electron's safeStorage API to ensure the confidentiality of sensitive information. Upon encryption, secrets are stored within the user data directory in a SQLite database, alongside other VS Code state information. This encryption process involves generating a unique encryption key, which, on macOS, is securely stored within `Keychain Access` under "Code Safe Storage" or "Code - Insiders Safe Storage," depending on the version. This method provides a robust layer of protection, preventing unauthorized access by other applications or users with full disk access. The safeStorage API, accessible in the main process, supports operations such as checking encryption availability, encrypting and decrypting strings, and selecting storage backends on Linux. This approach ensures that your secrets are securely encrypted and stored, safeguarding them from potential threats while maintaining application integrity.
-
 ## Examples
 
-### OpenAI
-
-**Note:** We recommend configuring your OpenAI key using the code editor extension. Follow the [Bring Your Own Key](/docs/navie/bring-your-own-model.html#configuring-your-openai-key) docs for instructions.  
-
-Only `OPENAI_API_KEY` needs to be set, other settings can stay default:
-
-| `OPENAI_API_KEY`| `sk-9spQsnE3X7myFHnjgNKKgIcGAdaIG78I3HZB4DFDWQGM` |
-
-### Azure OpenAI
-
-Assuming you [created](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource) a `navie` GPT-4 deployment on `contoso.openai.azure.com` OpenAI instance:
-
-| `AZURE_OPENAI_API_KEY` | `e50edc22e83f01802893d654c4268c4f` |
-| `AZURE_OPENAI_API_VERSION` | `2024-02-01` |
-| `AZURE_OPENAI_API_INSTANCE_NAME` | `contoso` |
-| `AZURE_OPENAI_API_DEPLOYMENT_NAME` | `navie` |
-
-### AnyScale Endpoints
-
-[AnyScale Endpoints](https://www.anyscale.com/endpoints) allows querying a
-selection of open-source LLMs. After you create an account you can use it by
-setting:
-
-| `OPENAI_API_KEY` | `esecret_myxfwgl1iinbz9q5hkexemk8f4xhcou8` |
-| `OPENAI_BASE_URL` | `https://api.endpoints.anyscale.com/v1` |
-| `APPMAP_NAVIE_MODEL` | `mistralai/Mixtral-8x7B-Instruct-v0.1` |
-
-Consult [AnyScale documentation](https://docs.endpoints.anyscale.com/) for model
-names. Note we recommend using Mixtral models with Navie.
-
-### Ollama
-
-You can use [Ollama](https://ollama.com/) to run Navie with local models; after
-you've successfully ran a model with `ollama run` command, you can configure
-Navie to use it:
-
-| `OPENAI_API_KEY` | `dummy` |
-| `OPENAI_BASE_URL` | `http://127.0.0.1:11434/v1` |
-| `APPMAP_NAVIE_MODEL` | `mixtral` |
-
-**Note:** Even though it's running locally a dummy placeholder API key is still required.
-
-### LM Studio
-
-You can use [LM Studio](https://lmstudio.ai/) to run Navie with local models. 
-
-After downloading a model to run, select the option to run a local server.
-
-<img class="video-screenshot" src="/assets/img/product/lmstudio-run-local-server.webp"/> 
-
-In the next window, select which model you want to load into the local inference server.
-
-<img class="video-screenshot" src="/assets/img/product/lmstudio-load-model.webp"/> 
-
-After loading your model, you can confirm it's successfully running in the logs.  
-
-*NOTE*: Save the URL it's running under to use for `OPENAI_BASE_URL` environment variable.
-
-For example: `http://localhost:1234/v1`
-
-<img class="video-screenshot" src="/assets/img/product/lmstudio-confirm-running.webp"/>
-
-In the `Model Inspector` copy the name of the model and use this for the `APPMAP_NAVIE_MODEL` environment variable.
-
-For example: `Meta-Llama-3-8B-Instruct-imatrix`
-
-<img class="video-screenshot" src="/assets/img/product/lmstudio-model-inspector.webp"/>
-
-Continue to configure your local environment with the following environment variables based on your LM Studio configuration.  Refer to the [documentation above](#bring-your-own-model-byom) for steps specific to your code editor.
-
-| `OPENAI_API_KEY` | `dummy` |
-| `OPENAI_BASE_URL` | `http://localhost:1234/v1` |
-| `APPMAP_NAVIE_MODEL` | `Meta-Llama-3-8B-Instruct-imatrix` |
-
-**Note:** Even though it's running locally a dummy placeholder API key is still required.
+Refer to the [Navie Reference Guide](/docs/reference/navie) for detailed examples of using Navie with your own LLM backend.

package/built/docs/navie/how-to-open-navie.md

@@ -1,7 +1,7 @@
 ---
 layout: docs
 title: Docs - AppMap Navie
-description: "Learn how to use AppMap Navie to provide personalized code analysis. Generate AppMap Data, ask Navie questions, analyze code, and iterate for optimal results."
+description: "Learn how to open AppMap Navie in your code editor. Open Navie in your VS Code or JetBrains code editor to start working with Navie AI"
 name: How to Open Navie
 step: 2
 navie: true

package/built/docs/navie/index.md

@@ -14,6 +14,7 @@ That means you're not just working with static analysis anymore, and you're not
 
 - [How Navie Works](/docs/navie/how-navie-works)
 - [How to Open Navie](/docs/navie/how-to-open-navie)
+- [Using Navie](/docs/navie/using-navie)
 - [Bring Your Own LLM Model](/docs/navie/bring-your-own-model)
 
 **Install AppMap for your preferred code editor to get started.**

package/built/docs/{guides/navie-best-practices.md → navie/using-navie.md}

@@ -1,16 +1,51 @@
 ---
 layout: docs
-title: Docs - Guides
+title: Docs - AppMap Navie
 description: "Learn how to use AppMap Navie to provide personalized code analysis. Generate AppMap Data, ask Navie questions, analyze code, and iterate for optimal results."
-guides: true
-name: Navie Best Practices
-step: 1
-redirect_from: [/docs/navie/using-navie]
+name: Using Navie
+step: 3
+navie: true
+toc: true
+redirect_from: [/docs/guides/navie-best-practices]
 ---
+# Using Navie
 
-# Navie Best Practices
+- [User Interface](#user-interface)
+- [Basic Layout](#basic-layout)
+- [Navie Best Practices](#navie-best-practices)
+  - [Create AppMap Data](#create-appmap-data)
+  - [Ask Navie](#ask-navie)
+  - [Implement Generated Code](#implement-generated-code)
+  - [Repeat](#repeat)
 
-When you ask a question to Navie, it will search through all your AppMap Diagrams created for your project to pull in relevant traces, sequence diagrams, and code snippets for analysis.  It will then send these code snippets and runtime code sequence diagrams to the Generative AI service along with your question.  By sending this valuable context to the AI interface, your answers will be much more personal and specific to your codebase, files, and functions. Additionally, the Generative AI will be able to understand how your code works at runtime and will be able to make architectural level recommendations across your entire application. 
+When you ask a question to Navie, it will search through all your AppMap Diagrams (if they exist) and your static source code for your project to pull in relevant traces, sequence diagrams, and code snippets for analysis.  It will then send these code snippets and runtime code sequence diagrams to the Generative AI service along with your question.  By sending this valuable context to the AI interface, your answers will be much more personal and specific to your codebase, files, and functions. 
+
+## User Interface
+AppMap Navie AI is an AI assistant that enables you to ask architectural level questions about your code base. Navie is also able to help you generate new code that can span across your entire project. The primary user interface for Navie is within your VS Code or JetBrains code editor.  Refer to the Navie docs to [learn how to open Navie](/docs/navie/how-to-open-navie) for your code editor. 
+
+![Navie User Interface](/assets/img/docs/appmap-navie-user-interface.webp)
+
+## Basic Layout
+
+The Navie user interface consists of 5 key areas. 
+
+<ol type="A">
+  <b><li>AppMap Data Status Panel</li></b>
+  This panel will list the current status of the AppMap Data that has been created for your project.  AppMap Data are your application runtime traces which include things like HTTP and SQL requests, data flows, class and function level instrumentation, and more. Without AppMap Data created for your project, Navie can search through your static source code in your workspace for relevant code snippets. 
+  <b><li>Navie Context Window</li></b>
+  Upon asking a question to Navie it will search through your AppMap Data (if exists) and the source code in your open workspace to locate all the relevant context for your question. This area will reflect the information that Navie is aware of when answering. You can use this information to better understand how Navie is responding.
+  <b><li>LLM Model Config Button</li></b>
+  You can configure Navie to use your own OpenAI API key or bring your own LLM model running locally or within another provider. Clicking the gear icon will open the configuration modal for the bring your own model settings.  <a href="/docs/navie/bring-your-own-model">Refer to the AppMap docs for more details</a>
+ about how to configure Navie to use your own LLM models. 
+  <b><li>Active LLM Model</li></b>
+  This panel will display the currently configured LLM model in use with Navie.  The LLM details are displayed in the following format: <code>Model: &lt;Model Name&gt; (&lt;location&gt;)</code>.  When using the default Navie backend, the location will be listed as <code>default</code>. When using your own OpenAI API key the location will be listed as <code>via OpenAI</code>.  When using <a href="/docs/navie/bring-your-own-model.html#configuration">Navie Bring Your Own Model</a>
+, the location will be the value of the <code>OPENAI_BASE_URL</code> environment variable, for example <code>via localhost</code> when using <a href="/docs/navie/bring-your-own-model.html#ollama">Ollama</a> or <a href="/docs/navie/bring-your-own-model.html#lm-studio">LM Studio</a>. 
+  <b><li>Navie Chat Window</li></b>
+  This is your primary location for interacting with Navie.  Here you can ask Navie questions about how your application works, ask Navie to generate code or test cases, and you can even have Navie create a pull request based on your changes. For more advanced usage of Navie refer to the <a href="#advanced-navie-commands">Advanced Navie Commands</a>
+ section.  
+</ol>
+
+## Navie Best Practices
 
 To generate the highest quality responses from Navie, we recommend the following approach. 
 
@@ -19,7 +54,7 @@ To generate the highest quality responses from Navie, we recommend the following
 - [Write Code](#write-code)
 - [Repeat](#repeat)
 
-## Create AppMap Data
+### Create AppMap Data
 
 We recommend creating maps that are most relevant to the question or area of the application you are going to be working with. For example, if i wanted to understand how my new user registration flow worked I could [create a remote recording](/docs/get-started-with-appmap/making-appmap-data.html#with-remote-application-recording) of a new user registration flow. Alternatively, I could [run all the test cases](/docs/get-started-with-appmap/making-appmap-data.html#with-test-case-recording) related to new user creation, registration, and adjacent areas. 
 
@@ -37,17 +72,13 @@ Depending on your language and framework there [are up to 5 different ways](/doc
 
 Each of these methods generates AppMap Data in JSON format, which are then visualized through interactive diagrams in your code editor. This visualization supports a deep understanding of your application's architecture, dependencies, and runtime behavior, facilitating enhanced code quality and performance optimization.
 
-## Ask Navie
+### Ask Navie
 
 Navie, can address a wide range of questions about your application, extending beyond what static analysis AI assistants can provide, to understand dynamic interactions, dependencies, and performance bottlenecks to help your developers design and deliver solutions faster for a host of complex issues.
 
 If you are not able to use the AppMap OpenAI proxy, you can bring your own OpenAI API key, or use an entirely different AI Model, [hosted in your environment](/docs/navie/bring-your-own-model.html#azure-openai) or [hosted locally](/docs/navie/bring-your-own-model.html#ollama). 
 
-You can ask free formed questions, or start your question with one of these commands:
-
-- `@explain`: (Default) Navie will help you understand your project. This mode is used when there is no prefix.
-- `@help`: Navie will help you setup AppMap, including generating AppMap recordings and diagrams.
-- `@generate`: Navie will help you generate new code.
+You can ask free formed questions, or refer to the [Navie Reference docs](/docs/reference/navie) to learn more about the advanced Navie chat commands you can use with your question. 
 
 **Examples of good questions to ask Navie.**
 
@@ -60,7 +91,7 @@ You can ask free formed questions, or start your question with one of these comm
 * Explain what functions or files are involved when a user logs into my service. 
 * Loading the "products" view page is slow in production, provide suggested guidance with relevant code changes I can make to improve the speed.
 
-## Implement Generated Code
+### Implement Generated Code
 
 Navie can do more than just provide code implementation details, you can talk to Navie about a variety of other topics as you are updating your application based on it's recommendations. 
 
@@ -74,6 +105,6 @@ Navie can do more than just provide code implementation details, you can talk to
 
 5. **Custom Queries**: Tailor your questions to fit unique development needs—whether you're troubleshooting a specific error, seeking optimization opportunities, or curious about the interactions between various components of your application.
 
-## Repeat
+### Repeat
 
 Continue to ask follow-up question to Navie as you are making code changes or when you need additional details or more specific advice.  Additionally, as you make changes to your application, continue creating AppMap recordings of the updated code interactions and start new conversations with Navie to dive deeper into your feature implementation.