# SiteCompanion SiteCompanion is a browser extension that allows you to run AI pipelines on the visible text of any site. > SiteCompanion saves you from copying and pasting to run AI on sites. ## Table of Contents - [Setup](#setup) - [Execution](#execution) - [Model](#model) - [Prompt Building](#prompt-building) - [Extension Popup](#extension-popup) - [Configuration - Pasting Mode](#configuration---pasting-mode) - [Configuration - Confirmation Mode](#configuration---confirmation-mode) - [Normal Mode](#normal-mode) - [Custom Mode](#custom-mode) - [Toolbar](#toolbar) - [Configurations and Terms](#configurations-and-terms) - [Scope and Workspaces](#scope-and-workspaces) - [Configuration Inheritance](#configuration-inheritance) - [Disabling Inherited Configurations](#disabling-inherited-configurations) - [Appearance](#appearance) - [Global-Only Appearance Configurations](#global-only-appearance-configurations) - [API Keys (Global Only)](#api-keys-global-only) - [API Configurations](#api-configurations) - [Advanced Mode](#advanced-mode) - [Environments](#environments) - [Profiles](#profiles) - [Tasks](#tasks) - [Task Defaults](#task-defaults) - [Toolbar Shortcuts](#toolbar-shortcuts) - [Site-Specific Configurations](#site-specific-configurations) - [Selector Patterns](#selector-patterns) - [Planned Features](#planned-features) - [Known Bugs](#known-bugs) - [Disclaimer](#disclaimer) ## Setup 1. Download the code (will be published to the Chrome Store soon) and load the extension code (`sitecompanion/`) as an unpacked extension. 2. Configure your API keys, API endpoints, environments, profiles, and tasks. 3. Go to a site. 4. Choose to either paste in part of the site for structured matching or use the full text of the site. 5. Start running your tasks! ## Execution How `SiteCompanion` works. See [Configurations and Terms](#configurations-and-terms) for details on specific terms. ### Model The execution of `SiteCompanion` strictly follows this model: ``` Extract Site Text -> Build Prompt -> Run (Send Request) -> Receive Output -> Stop ``` ### Prompt Building The prompt will always be built in the following order: ``` System prompt -> Profile -> Task prompt -> Extracted Site Text ``` ### Extension Popup This is the control panel for `SiteCompanion` on sites. The following sections describe the modes of the extension popup. #### Configuration - Pasting Mode This is the mode the popup UI is in when on an unknown site. You can choose to try extracting the minimal enclosing class that contains the pasted text or the full text of the body of the current site. Choosing either will proceed to [Confirmation Mode](#configuration---confirmation-mode). #### Configuration - Confirmation Mode This is the mode to review the extracted text based on your current site's contents and confirm the configuration of the current site including the name, URL match pattern and the workspace it belongs to. This mode has the following buttons: 1. "Retry" button: goes back to [Pasting Mode](#configuration---pasting-mode) without saving any configuration. 2. "Confirm" button: add the current site to the list of known sites and enter [Normal Mode](#normal-mode). See [Site-Specific Configurations](#site-specific-configurations) for configuration details. #### Normal Mode This is the mode where most of the actions happen. The knobs for running a task: - Environment: the environment which used by the task. - Profile: the user profile used by the task. - Task: the task to run. - "Custom" button: enters [Custom Mode](#custom-mode). - "Run" button: run the task with the current environment and profile. And a few buttons for the output buffer: - "Copy" button: copies the contents of the output buffer in text. - "Copy Markdown" button: copies the contents of the output buffer with Markdown formatting. - "Clear" button: clears the contents of the output buffer. #### Custom Mode This is a variant of [Normal Mode](#normal-mode) to allow editing of a custom, task prompt that's not saved to the configuration of the extension. The "Normal" button will go back to [Normal Mode](#normal-mode). *The environment and profile selectors will always be active when in this mode.* ### Toolbar Place predefined shortcuts for environment + profile + task combinations in a floating toolbar. *Note that clicking on the toolbar will open the popup and run the shortcut.* ## Configurations and Terms The full list of configuration options and details about the terms we use. ### Scope and Workspaces Every operable site for `SiteCompanion` is in a workspace. There are three scopes: 1. Global workspace ("global" for short): defines the baseline configurations. 2. User-defined workspace ("workspace" for short): defines the configurations for a class of workflows. Workspaces always inherit the global configurations. 3. Site-specific ("site" for short): defines the configuration for each site. May inherit the global workspace or a user-defined workspace. Must always inherit a workspace. `SiteCompanion` operates on a specific site at a time. ### Configuration Inheritance Each scope may inherit some configurations from its parent, and can **always** override them by shadowing. *Any configuration that can be inherited by a workspace must be inheritable by a site.* If not explicitly mentioned, a configuration is **always** inheritable. #### Disabling Inherited Configurations Any inherited configuration can be disabled in the current scope, and a child may only inherit the enabled configurations of its parent. The state of an inherited configuration is configurable by clicking the toggling buttons in the "Inherited" sections of each individual configuration. ### Appearance `SiteCompanion` comes with the following appearance customization options that can be inherited: 1. Theme: choose the theme of the extension popup and the toolbar. The settings UI will use the global theme. 2. Toolbar Position: choose where the toolbar appears on known sites. 3. Always Use Default Env/Profile: enabling this option will disable the environment and profile selection fields in the popup UI. 4. Empty Toolbar: let the toolbar hide or show a button called "Open SiteCompanion" when the toolbar is empty in the current site. ##### Global-Only Appearance Configurations Some configurations are only applicable globally. 1. Auto-hide toolbar on unknown sites: Turning on this option will hide the toolbar when the current site is not known by `SiteCompanion`. 2. Always show output buffer in popup UI: Turning this off will show the output buffer even when the site is unknown. ### API Keys (Global Only) The keys for authenticating with the AI service provider. ### API Configurations Configures the details of AI service endpoints: 1. API Key: which API key to use. 2. API (Base) URL: what the URL to the AI service endpoint is. 3. Model Name: what model to use. *Workspaces and sites may only inherit API configurations of their parents, and never create their own.* #### Advanced Mode To accommodate different API request formats, `SiteCompanion` offers "Advanced Mode" for a more customizable experience. In "Advanced Mode", you may directly edit the API endpoint URL and the `JSON` template for requests. ### Environments Environments are bundles of API configuration and a system prompt. They define the environment in which a task is running. An environment contains the following components: 1. API configuration: select the API configuration to use for this environment. 2. System prompt: the piece of prompt that defines the profile of the model. ### Profiles User profiles to give more context to the model about **who you are**. ### Tasks Prompts that tell the model **what to do**. #### Task Defaults A task will be associated with a default environment and profile combination for quick access. Of course, you may choose whichever environment and profile you want to use in the popup UI. ### Toolbar Shortcuts Configures the predefined shortcuts that appear on the toolbar. Each shortcut is a combination of environment + profile + task. ### Site-Specific Configurations Some configurations are site-specific. They are there to configure how `SiteCompanion` recognizes a site, the workspace the site belongs to, and how it extracts text. The additional configuration options are: 1. URL Pattern: the globbing pattern to match URLs against for that site configuration. 2. Workspace: the workspace that the site belongs to. 3. Site Text Selector: the configuration for the pattern used by `SiteCompanion` to extract the text from the site. #### Selector Patterns The supported selector patterns are: * `{ kind: "css"; selector: string }` * `{ kind: "cssAll"; selector: string; index: number }` * `{ kind: "textScope"; text: string }` * `{ kind: "anchoredCss"; anchor: { kind: "textScope"; text: string }; selector: string }` ## Planned Features Nothing at the moment! Send a feature request to **Issues** if you'd like to request a new feature! ## Known Bugs Nothing at the moment! Send a bug report to **Issues** if you find one! ## Disclaimer 1. The extension is not responsible for your actions. **YOU** must be responsible for your own actions. 2. `SiteCompanion` is free and will always be free; no party should offer paid services for `SiteCompanion` users. 3. If a branch/fork diverges from the design of `SiteCompanion`, it may not use its branding nor will it be merged into the official version. 4. No donations or other monetization will affect feature requests or bug fix priorities.