Updating README and cleaning up documentation (#286)

README.md

@@ -1,81 +1,83 @@
-# Welcome to Project Mercury
+# AI Shell (a.k.a Project Mercury)
 
-**Project Mercury** contains our latest CLI tool that provides an interactive shell session to chat
-with language models, creating an *AI Shell*. Users can use _agents_ to interact with different AI models, or other
-assistance providers, in a conversational manner. **Project Mercury** also provides a framework for
-creating AI agents.
+Welcome to the **AI Shell** repository! AI Shell is a CLI tool that brings the power of artificial
+intelligence directly to your command line! Designed to help you get command assistance from various
+AI assistants, AI Shell is a versatile tool to help you become more productive in the command line.
+We call these various AI assistant providers _agents_. You can use agents to interact with different
+generative AI models or other AI/ML/assistant providers in a conversational manner. This repo
+contains the code of the AI Shell engine, agents and details on how to create your own agent.
 
-Why the name **Project Mercury**? The name is inspired both by the Roman god of messages and the
-first human spaceflight by the US. This project is our first step into the new world of AI powered
-assistance and focuses on being the connection (or messenger) between the user and the AI model.
+Why the name **Project Mercury**? This was the original code name of the project and was inspired
+both by the Roman god of messages and the first human spaceflight by the US. This project is our
+first step into the new world of AI powered assistance and focuses on being the connection (or
+messenger) between the user and the AI model.
 
-This project is currently in the **alpha** phase. Expect many significant changes to the code as we
-experiment and refine the user experiences of this tool. We appreciate your feedback and patience as
-we continue our development.
+This project is currently in a very early **public preview** state. Expect many significant changes
+to the code as we experiment and refine the user experiences of this tool. We appreciate your
+feedback and patience as we continue our development.
 
-![GIF showing demo of the AI Shell][04]
+## New to AI Shell?
 
-## Installation
+To learn more about AI Shell, we recommend you check out the [overview][19] page of the AI Shell
+documentation.
+
+### Usage
+
+There are two modes to use AI Shell, standalone and a side-by-side, integrated experience with
+PowerShell 7. For more information see,
+- [Get Started with AI Shell in PowerShell][15]
+- [Get Started with AI Shell (standalone)][16]
+
+### AI Shell in PowerShell
+
+![GIF showing demo of the AI Shell in PowerShell][21]
+
+### Standalone experience
+
+![GIF showing demo of the AI Shell standalone][20]
+
+## Getting AI Shell
+
+AI Shell is supported on Windows, MacOS and Linux, however the best experience you can have is with
+Windows, [PowerShell 7][11] and [Windows Terminal][14]. For more information see,
+[Installing AI Shell][13].
+
+## Locally Building AI Shell
 
 Some prerequisites for building an AI Shell:
 
-- Build script requires PowerShell v7.2 or newer versions
-- [PowerShell v7.4][11] is recommended
+- Build script requires [PowerShell v7.4][18] or newer versions
 - [.NET SDK 8][09] is required to build the project
 
 Here are the steps to install and use.
 
 1. Clone this repository, `git clone https://github.com/PowerShell/ProjectMercury`
 2. Import the `build.psm1` module by running `import-module ./build.psm1` 
-3. Run the `Start-Build` command 
+3. Run the `Start-Build` command (You can specify which agents build with the `-AgentsToInclude`
+   parameter)
 4. After the build is complete, you can find the produced executable `aish` in the `out\debug\app`
    folder within the repository's root directory. You can add the location to the `PATH` environment
    variable for easy access. The full path is copied to your clipboard after successful build.
 
 ## AI Agents
 
 Project Mercury provides a framework for creating and registering multiple AI Agents. The agents are
-libraries that you use to interact with different AI models or assistance providers. Currently,
-these are the supported agents:
+libraries that you use to interact with different AI models or assistance providers. AI Shell
+releases with two agents, the `openai-gpt` and `azure` agent. However there are additional ones
+supported if you locally build the project:
 
 Agent README files:
 
-- [`openai-gpt`][08]
+- [`openai-gpt`][08] (shipped with AI Shell)
 - [`ollama`][06]
 - [`interpreter`][07]
+- [`azure`][17] (shipped with AI Shell)
 
 When you run `aish`, you are prompted to choose an agent. For more details about each agent, see the
 README in the each agent folder.
 
 To learn more about how to create an agent for yourself please see, [Creating an Agent][03].
 
-## Usage
-
-To start a chat session with the LLM, run `aish`, which starts a new session in your current window.
-Choose the agent you would like to use. Once you select an agent you can begin your conversation.
-
-We suggest using a split pane approach with the terminal of choice. In Windows Terminal, use the
-following command to start `aish` in a new split pane:
-
-```shell
-wt -w 0 sp aish
-```
-
-You can bind this command to a key like `F3` in your PowerShell session. Add the following code to
-your `$PROFILE` script:
-
-```powershell
-$PSReadLineSplat = @{
-    Chord = 'F3'
-    ScriptBlock = {
-        wt -w 0 sp --tabColor '#345beb'--size 0.4 -p $env:WT_PROFILE_ID --title 'AIShell' <full-path-to-aish.exe>
-    }
-}
-Set-PSReadLineKeyHandler @PSReadLineSplat
-```
-
-Similarly, you can use iTerm2 to get a similiar split pane experience on MacOS. You can split the pane vertically by pressing `Cmd + D` and then run `aish` in one of the panes.
-
 ### Chat commands
 
 By default, `aish` provides a base set of chat `/` commands used to interact with the responses from
@@ -96,14 +98,15 @@ the AI model. To get a list of commands, use the `/help` command in the chat ses
   /retry     Regenerate a new response for the last query.    Core
 ```
 
-Also, agents can implement their own commands. For example, the `openai-gpt` agent register the command `/gpt`
-for managing the GPTs defined for the agent. Some commands, such as `/like` and `/dislike`, are commands that
-sends feedback to the agents. It is up to the agents to consume the feedback.
+Also, agents can implement their own commands. For example, the `openai-gpt` agent register the
+command `/gpt` for managing the GPTs defined for the agent. Some commands, such as `/like` and
+`/dislike`, are commands that sends feedback to the agents. It is up to the agents to consume the
+feedback.
 
 ### Key bindings for commands
 
-AI Shell supports key bindings for the `/code` command.
-They are currently hard-coded, but custom key bindings will be supported in future releases.
+AI Shell supports key bindings for the `/code` command. They are currently hard-coded, but custom
+key bindings will be supported in future releases.
 
 | Key bindings              | Command          | Functionality |
 | ------------------------- | ---------------- | ------------- |
@@ -114,10 +117,12 @@ They are currently hard-coded, but custom key bindings will be supported in futu
 
 ### Configuration
 
-Currently, AI Shell supports very basic configuration. One can creates a file named `config.json` under `~/.aish` to configure AI Shell,
-but it only supports declaring the default agent to use at startup. This way you do not need to select agents everytime you run `aish.exe`
+Currently, AI Shell supports very basic configuration. One can creates a file named `config.json`
+under `~/.aish` to configure AI Shell, but it only supports declaring the default agent to use at
+startup. This way you do not need to select agents every time you run `aish.exe`
 
-Configuration of AI Shell will be improved in future releases to support custom key bindings, color themes and more.
+Configuration of AI Shell will be improved in future releases to support custom key bindings, color
+themes and more.
 
 ```json
 {
@@ -131,14 +136,17 @@ Please see [CONTRIBUTING.md][02] for more details.
 
 ## Privacy
 
-AIShell does not capture, collect, store, or process any personal data or personally identifiable information (PII). All data interactions 
-are limited to the scope of the functionality provided by the tool and do not involve any form of personal data collection.
+AI Shell does not capture, collect, store, or process any personal data or personally identifiable
+information (PII). All data interactions are limited to the scope of the functionality provided by
+the tool and do not involve any form of personal data collection.
 
-Some agents integrated with AIShell may collect telemetry data to improve performance, enhance user experience, or troubleshoot issues. 
-We recommend that you refer to the individual agent’s README or documentation for more information on the telemetry practices and data collection 
-policies for each agent.
+Some agents integrated with AI Shell may collect telemetry data to improve performance, enhance user
+experience, or troubleshoot issues. We recommend that you refer to the individual agent’s README or
+documentation for more information on the telemetry practices and data collection policies for each
+agent.
 
-If you are interested in learning more, see [Microsoft's Privacy Statement](https://www.microsoft.com/en-us/privacy/privacystatement?msockid=1fe60b30e66967f13fb91f29e73f661a).
+If you are interested in learning more, see
+[Microsoft's Privacy Statement](https://www.microsoft.com/en-us/privacy/privacystatement?msockid=1fe60b30e66967f13fb91f29e73f661a).
 
 ## Support
 
@@ -155,7 +163,7 @@ For any security issues, please see our [Security Policy][12].
 ## Feedback
 
 We're still in development and value your feedback! Please file [issues][10] in this repository for
-bugs, suggestions, or feedback.
+bugs, suggestions, or feedback. If you would like to give more candid feedback and sign up for testing future versions and features before they are released, please fill out this [form][22].
 
 <!-- link references -->
 [01]: ./docs/CODE_OF_CONDUCT.md
@@ -165,8 +173,19 @@ bugs, suggestions, or feedback.
 [05]: ./docs/SUPPORT.md
 [06]: ./shell/agents/AIShell.Ollama.Agent/README.md
 [07]: ./shell/agents/AIShell.Interpreter.Agent/README.md
-[08]: ./shell/agents/AIShell.OpenAI.Agent/README.md
+[08]: https://learn.microsoft.com/powershell/utility-modules/aishell/how-to/agent-openai
 [09]: https://dotnet.microsoft.com/en-us/download
 [10]: https://github.com/PowerShell/ProjectMercury/issues
 [11]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell
 [12]: ./docs/SECURITY.md
+[13]: https://learn.microsoft.com/powershell/utility-modules/aishell/install-aishell
+[14]: https://learn.microsoft.com/windows/terminal/
+[15]: https://learn.microsoft.com/powershell/utility-modules/aishell/get-started/aishell-powershell
+[16]:https://learn.microsoft.com/powershell/utility-modules/aishell/get-started/aishell-standalone
+[17]: https://learn.microsoft.com/powershell/utility-modules/aishell/how-to/agent-azure
+[18]: https://github.com/PowerShell/PowerShell/releases/tag/v7.4.6
+[19]: https://learn.microsoft.com/powershell/utility-modules/aishell/overview
+[20]: ./docs/media/standalone-startup.gif
+[21]: ./docs/media/aishellwithPowerShell.gif
+[22]: https://aka.ms/AIShell-Feedback
+[logo]: ./docs/media/AIShellIconSVG.svg

shell/AIShell.Kernel/Shell.cs

@@ -286,7 +286,7 @@ private void LoadAvailableAgents()
             chosenAgent ??= _agents.Count is 1
                 ? _agents[0]
                 : Host.PromptForSelectionAsync(
-                    title: "[orange1]Please select an [Blue]agent[/] to use[/]:\n[grey](You can switch to another agent later by typing [Blue]@<agent name>[/])[/]",
+                    title: "Welcome to AIShell! We’re excited to have you explore our [bold]Public Preview[/]. Documentation is available at [link=https://aka.ms/AIShell-Docs]aka.ms/AIShell-Docs[/], and we’d love to hear your thoughts - share your feedback with us at [link=https://aka.ms/AIShell-Feedback]aka.ms/AIShell-Feedback[/].\n\n[orange1]Please select an AI [Blue]agent[/] to use[/]:\n[grey](You can switch to another agent later by typing [Blue]@<agent name>[/])[/]",
                     choices: _agents,
                     converter: static a => a.Impl.Name)
                 .GetAwaiter().GetResult();