feat: Auto-enable the help-agent

[kgilpin]

Currently, the default @explain mode fetches a mixture of code context and help docs to try and address any question.

For purposes of answering help questions, providing Navie with a lot of code context appears to be quite confusing to her. For example:

• When provided with a file like Jest config, she will hallucinate that Jest config changes are necessary to make AppMap data.
• She often echos appmap.yml or proposes changes to appmap.yml when none are necessary.
• Her obsession with the code details (she is trained to code, after all), obscures the higher-level guidance that new users actually need.

So in this PR, the following changes are made:

• @explain mode does not fetch help docs any more. Just code context and AppMap data.
• Detailed help-related prompts are moved from @explain to @help.
• @help mode is activated automatically if the user's question is classified as help-with-appmap.
• @help mode tries to infer the user's language and tech stack from the question. If it is unable to do so, the user is required to provide this information before @help will continue.
• @help mode is instructed to minimize the emission of code. Rather, the @help response should summarize relevant documentation, and provide links to docs.
• The full docs have been restored to Navie.
• @help prompt tells Navie how each appmap language agent is installed. Navie usually insists on describing how to do this, so she may as well give the right answer (e.g. appmap-node, pip install appmap, etc).

Risks

• We may miss having the default @explain mode provide some AppMap documentation help. But we won't miss the hallucination of install commands.
• @help mode does not perform code context lookup because it skews the Navie output aggressively towards outputting unwanted code snippets. Therefore, the help that's provided is based solely on the conversation, and not on the project context. Most AppMap help is actually usage information (e.g. how to use the IDE, what commands to run), so code context provides really limited utility anyway and is mostly false positives (e.g. code snippets of the actual project source code that are totally unrelated to making AppMap data).
• If a user's question is not classified as help-with-appmap, they won't get help based on our docs. So the classifier needs to be accurate. From my review of Navie's logs, it does appear to be pretty accurate. Sometimes users asks for "diagrams" and they mean AppMap diagrams, but Navie will just tell them generically about making diagrams and even emit some diagrams based on static analysis. We can evaluate whether generate-diagram classification should trigger Naive help in the future.

Examples

@help mode triggered

Make appmaps of my node server

To create AppMaps for your Node.js server, you can use the AppMap extension in Visual Studio Code. Here are the steps:

1. Install the appmap-node package: First, you need to add the appmap-node package to your project. You can do this using npm or yarn.

   npm install --save-dev appmap-node

   or

   yarn add --dev appmap-node

2. Generate AppMaps by running your server: Use the appmap-node command to run your server and generate AppMaps. For example, if you normally start your server with npm run dev, you would run:

   npx appmap-node npm run dev

   This command wraps your existing application launch command and records the behavior of your application, saving the AppMap data to the tmp/appmap directory.

3. Interact with your application: Once the server is running, interact with your application through its UI or API. Each interaction will generate an AppMap recording.

4. View AppMap diagrams in VSCode: Open the AppMap panel in VSCode to view the AppMap diagrams. The AppMap data files will be saved in the tmp/appmap directory, and you can view them directly from the extension.

For more detailed information, refer to the official documentation:

• Node.js AppMap Documentation: AppMap Node.js Reference
• VSCode AppMap Documentation: AppMap for Visual Studio Code

By following these steps, you can generate and view AppMaps for your Node.js server, helping you to better understand and improve your codebase.

@help mode not triggered

how to create a visual representation of one of my files

To create a visual representation of one of your files, AppMap can help you generate interactive sequence diagrams. These diagrams provide insights into function calls, HTTP requests, database queries, and other events within your codebase.

Here is how you can generate and visualize AppMaps for your code:

1. Identify the file/module/component for which you want to create a visual representation. For instance, let's take BookingStatusLineChart.tsx.

2. Record an AppMap:

   • Run your application or tests with AppMap recording enabled. This will capture all the runtime actions and interactions. Ensure you navigate through or test the specific components you want to visualize.

3. Generate AppMaps:

   • The recorded AppMap data will be stored typically in the appmap directory of your project.

4. Visualize the AppMap:

   • Open the AppMap extension in your code editor (VSCode). You can find it in the Activity Bar.
   • Browse and open the .appmap.json files generated based on your recordings.
   • The AppMap extension will display an interactive sequence diagram of the recorded interactions.

Since AppMap sequence diagrams require runtime data, ensure you have some AppMaps generated through your test runs or by manually recording interactions.

For now, let me provide a brief Markdown overview of how the BookingStatusLineChart.tsx flows:

BookingStatusLineChart Component Overview

graph TD
    A[BookingStatusLineChart] -->|useLocale| B(useFilterContext)
    A -->|trpc.viewer.insights.bookingStatus.useQuery| C[Query Execution]
    C -->|data| D[Render Chart]

    subgraph Chart Rendering
        D -->|isPending| E[LoadingInsight]
        D -->|isSuccess| F[CardInsights]
        F --> G[Title]
        F --> H[LineChart]
    end

1. Initialization: The BookingStatusLineChart component initializes by invoking hooks such as useLocale, useFilterContext, and fetches data using trpc.viewer.insights.bookingStatus.useQuery.

2. Rendering Conditional Elements:

   • If data fetch is pending (isPending), it displays a loading component.
   • If data fetch is successful (isSuccess), it displays a CardInsights component which encompasses Title and LineChart components to visualize the booking status trends.

This approach condenses the flow into a simple graph. The actual AppMap will provide much more detailed interactions and dependencies based on the runtime data.

If you need more detailed visualizations or assistance on generating specific AppMaps, please run some tests or interactions with AppMap recording enabled and provide the .appmap.json file generated for deeper analysis.

[dustinbyrne]

The code looks good, I'm working on testing this in the backend

[kgilpin]

Thanks for trying it out!

[appland-release]

:tada: This PR is included in version @appland/navie-v1.13.0 :tada:

The release is available on:

• @appland/navie-v1.13.0
• GitHub release
• @appland/navie-v1.13.0

Your semantic-release bot :package::rocket:

[appland-release]

:tada: This PR is included in version @appland/appmap-v3.147.0 :tada:

The release is available on:

• @appland/appmap-v3.147.0
• GitHub release
• @appland/appmap-v3.147.0

Your semantic-release bot :package::rocket: