phishell

𝛗 shell

Phi Shell is a command-line application designed to serve as a command processor with enhanced capabilities for integrating external tool providers and interacting with Large Language Models (LLMs). These tool providers are standalone programs created by users. Providers can be implemented in any programming language, taking advantage of thousands of libraries to enable features ranging from integrations with external systems to the implementation of sophisticated business logic. The host program communicates with tool providers through their Stdin and Stdout, reducing the need for extensive boilerplate code.

Phi Shell offers two distinct modes of operation:

• Basic Shell: This mode replicates the basic features of traditional shells while enabling users to integrate external programs (tool providers) with the host program. Additionally, the output generated by console commands can be added to the chat history, facilitating inference and interaction with LLMs.
• Chat: Interacts with LLMs directly to perform inference and leverages attached tools for enhanced functionality during LLM interactions.

The modes can be switched between using the Tab key.

[!TIP] Explore custom GPT to get personalized guidance on configuring Phi Shell and building tools.

Configuration

Phi Shell uses two YAML files as a source of configuration:

• Global: .phishell.yaml file in the user's home directory;
• Local: .phishell.yaml file in the current directory. This directory can be changed at the time of running Phi Shell (see the -dir argument for details).

Both files are not mandatory, but at least one of them must exist in order to run Phi Shell. The local configuration file takes precedence over the global one. The configuration file specifies profiles, which are basically the configuration of the LLM client and few other options that affect the interaction, and the name of default profile. On a high level the configuration YAML is defined as follows:

profiles:
  profileA:
    # configuration of profile A
  profileB:
    # configuration of profile B

default: profileB

Each of the profiles specify the following data:

Configuration example:

profiles:
  qwen2.5:
    preset: ollama
    model: qwen2.5:14b

  openai: {}

default: qwen2.5

Arguments

The following command line arguments are supported when running Phi Shell:

Commands

The Basic Shell mode supports the following built-in commands:

These commands cannot be combined with other commands, either built-in or external, by using the pipe operator, and their output is not considered for push into the chat history.

Providers

Developing custom tools for the Phi Shell involves creating a standalone program, referred to as the provider. This provider communicates with the Phi Shell, which acts as the tool host, using Stdin and Stdout. Any diagnostic output generated by the provider must be directed to Stderr, ensuring the Phi Shell can distinguish useful payload from diagnostic output.

To establish communication between the Phi Shell and the provider, the provider must follow a defined protocol. The steps in this protocol are:

1. Listing Supported Tools: The provider must print a list of the supported tools in JSON format, with each tool definition appearing on a separate line.

2. Signaling Readiness: After listing the tools, the provider must print an empty line to indicate that it is ready to process tool calls.

3. Processing Tool Calls: The provider must read input from Stdin, one line at a time, where each line represents a tool call. Once the tool call is processed, the provider must print the response to Stdout, with each response appearing on a separate line and preserving the call ID to ensure matching of requests and responses.

Tool calls may be processed concurrently, and responses can be returned out of order. The Phi Shell applies timeouts while waiting for responses from the provider.

TypeScript Support

Phi Shell enables the development of tool providers as Node.js packages. Functions should be exported from the package's index.js file and include type definitions specified in the types field of the package.json. The host application automatically extracts function schemas from these type definitions for seamless integration with LLM calls. When a tool is called, the tool is executed using the current working directory of the user.

To run a TypeScript package as a tools provider, use the command attach js [path]. If a path is not provided, the host will try to find the package in the current directory.

Schemas

The communication contracts between the host and provider processes are outlined below as JSON schemas in the order of their typical usage by provider. The types can be converted to language-specific type definitions using variety of tools or by using LLMs.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "The type of the tool. Currently, only `function` is supported.",
      "enum": ["function"]
    },
    "function": {
      "$ref": "#/definitions/ToolFunction",
      "description": "Description of the function."
    }
  },
  "required": ["type"],
  "definitions": {
    "ToolFunction": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.",
          "pattern": "^[a-zA-Z0-9_-]{1,64}$"
        },
        "description": {
          "type": "string",
          "description": "A description of what the function does, used by the model to choose when and how to call the function."
        },
        "parameters": {
          "type": "object",
          "additionalProperties": true,
          "description": "The parameters the functions accepts, described as a JSON Schema object."
        }
      },
      "required": ["name", "parameters"]
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "Correlation ID of the tool call."
    },
    "function": {
      "$ref": "#/definitions/ToolRequestFunction",
      "description": "The function that the model called."
    },
    "context": {
      "$ref": "#/definitions/ToolRequestContext",
      "description": "Context of the tool call request."
    }
  },
  "required": ["call_id", "function", "context"],
  "definitions": {
    "ToolRequestFunction": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the function to call."
        },
        "arguments": {
          "type": "string",
          "description": "Arguments to call the function with, as generated by the model in JSON format."
        }
      },
      "required": ["name", "arguments"]
    },
    "ToolRequestContext": {
      "type": "object",
      "properties": {
        "dir": {
          "type": "string",
          "description": "Full path to the current directory."
        }
      },
      "required": ["dir"]
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "ID of the tool call that this message is responding to."
    },
    "content": {
      "type": "object",
      "description": "The contents of the tool response."
    }
  },
  "required": ["call_id"]
}

Built-In Tools

Phi Shell offers several basic tools to use with daily tasks. These tools are available immediately upon the startup.

License

Phi Shell is licensed under the MIT License. See the LICENSE.txt file for details.