diff --git a/Home.md b/Home.md index 54df88e..141647f 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,61 @@ -Welcome to the loki wiki! +# Home + +Welcome to the Loki wiki! + +A helpful way to use this wiki is to create a RAG from it and then ask questions about Loki, with Loki! Here's an example +on how to create a RAG from this wiki and then ask a question about Loki: + +![Loki RAG](images/loki_rag.png) + +--- + +Loki is an all-in-one, batteries-included, LLM CLI tool featuring Shell Assistant, CLI & REPL Mode, RAG, AI Tools & +Agents, and More. + +It is designed to include a number of useful agents, roles, macros, and more so users can get up and running with Loki +in as little time as possible. + +![Agent example](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/agents/sql.gif) + +Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](AICHAT-MIGRATION) to get started. + +## Documentation Index +* [AIChat Migration Guide](AICHAT-MIGRATION): Coming from AIChat? Follow the migration guide to get started. +* [Installation](docs/Installation.md): Install Loki +* [Getting Started](docs/Getting-Started.md): Get started with Loki by doing first-run setup steps, and learn the basics. +* [REPL](REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki. + * [Custom REPL Prompt](REPL-PROMPT): Customize the REPL prompt to provide useful contextual information. +* [Vault](VAULT): Securely store and manage sensitive information such as API keys and credentials. +* [Shell Integrations](SHELL-INTEGRATIONS): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance. +* [Function Calling](TOOLS#Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools + * [Creating Custom Tools](CUSTOM-TOOLS): You can create your own custom tools to enhance Loki's capabilities. + * [Create Custom Python Tools](CUSTOM-TOOLS#custom-python-based-tools) + * [Create Custom TypeScript Tools](CUSTOM-TOOLS#custom-typescript-based-tools) + * [Create Custom Bash Tools](CUSTOM-BASH-TOOLS) + * [Bash Prompt Utilities](BASH-PROMPT-HELPERS) +* [First-Class MCP Server Support](MCP-SERVERS): Easily connect and interact with MCP servers for advanced functionality. +* [Macros](MACROS): Automate repetitive tasks and workflows with Loki "scripts" (macros). +* [RAG](RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation. +* [Sessions](SESSIONS): Manage and persist conversational contexts and settings across multiple interactions. +* [Roles](ROLES): Customize model behavior for specific tasks or domains. +* [Agents](AGENTS): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools. + * [Todo System](TODO-SYSTEM): Built-in task tracking for improved agent reliability with smaller models. +* [Environment Variables](ENVIRONMENT-VARIABLES): Override and customize your Loki configuration at runtime with environment variables. +* [Client Configurations](CLIENTS): Configuration instructions for various LLM providers. + * [Authentication (API Key & OAuth)](CLIENTS#authentication): Authenticate with API keys or OAuth for subscription-based access. + * [Patching API Requests](PATCHES): Learn how to patch API requests for advanced customization. +* [Custom Themes](THEMES): Change the look and feel of Loki to your preferences with custom themes. +* [History](#history): A history of how Loki came to be. + +--- + +## History + +Loki began as a fork of [AIChat CLI](https://github.com/sigoden/aichat) and has since evolved into an independent project. + +See [CREDITS.md](https://github.com/Dark-Alex-17/loki/CREDITS.md) for full attribution and background. + +--- + +## Creator +* [Alex Clarke](https://github.com/Dark-Alex-17) diff --git a/docs/Getting-Started.md b/docs/Getting-Started.md new file mode 100644 index 0000000..ba349fe --- /dev/null +++ b/docs/Getting-Started.md @@ -0,0 +1,91 @@ +# Getting Started + +After installation, you can generate the configuration files and directories by simply running: + +```sh +loki --info +``` + +Then, you need to set up the Loki vault by creating a vault password file. Loki will do this for you automatically and +guide you through the process when you first attempt to access the vault. So, to get started, you can run: + +```sh +loki --list-secrets +``` + +### Authentication +Each client in your configuration needs authentication (with a few exceptions; e.g. ollama). Most clients use an API key +(set via `api_key` in the config or through the [vault](./docs/VAULT.md)). For providers that support OAuth (e.g. Claude Pro/Max +subscribers, Google Gemini), you can authenticate with your existing subscription instead: + +```yaml +# In your config.yaml +clients: + - type: claude + name: my-claude-oauth + auth: oauth # Indicate you want to authenticate with OAuth instead of an API key +``` + +```sh +loki --authenticate my-claude-oauth +# Or via the REPL: .authenticate +``` + +For full details, see the [authentication documentation](./docs/clients/CLIENTS.md#authentication). + +## Configuration +The location of the global Loki configuration varies between systems, so you can use the following command to find your +`config.yaml` file: + +```shell +loki --info | grep 'config_file' | awk '{print $2}' +``` + +The configuration file consists of a number of settings. To see a full example configuration file with every setting +defined, refer to the [example configuration file](./config.example.yaml). + +### Default LLM +The following settings are available to configure the default LLM that is used when you start Loki, and its +hyperparameters: + +| Setting | Description | +|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `model` | The default LLM to use when no model is provided | +| `temperature` | The default `temperature` parameter for all models (0,1); Used unless explicitly overridden | +| `top_p` | The default `top_p` hyperparameter value to use for all models, with a range of (0,1) (or (0,2) for some models);
Used unless explicitly overridden | + +### CLI Behavior +You can use the following settings to modify the behavior of Loki: + +| Setting | Default Value | Description | +|---------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `stream` | `true` | Controls whether to use stream-style APIs when querying for completions from LLM providers | +| `save` | `true` | Controls whether to save each query/response to every model to `messages.md` for posterity; Useful for debugging | +| `keybindings` | `emacs` | Specifies which keybinding schema to use; can either be `emacs` or `vi` | +| `editor` | `null` | What text editor Loki should use to edit the input buffer or session (e.g. `vim`, `emacs`, `nano`, `hx`);
Defaults to `$EDITOR` | +| `wrap` | `no` | Controls whether text is wrapped (can be `no`, `auto`, or some `` | +| `wrap_code` | `false` | Enables or disables the wrapping of code blocks | + +### Preludes +Preludes let you define the default behavior for the different operating modes of Loki. The available settings are +shown below: + +| Setting | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `repl_prelude` | This setting lets you specify a default `session` or `role` to use when starting Loki in [REPL](./docs/REPL.md) mode.
Values can be | +| `cmd_prelude` | This setting lets you specify a default `session` or `role` to use when running one-off queries in Loki via the CLI.
Values can be | +| `agent_session` | This setting is used to specify a default session that all agents should start into, unless otherwise specified in the agent configuration. (e.g. `temp`, `default`) | + +### Appearance +The appearance of Loki can be modified using the following settings: + +| Setting | Default Value | Description | +|---------------|---------------|------------------------------------------------------| +| `highlight` | `true` | This setting enables or disables syntax highlighting | +| `light_theme` | `false` | This setting toggles light mode in Loki | + +### Miscellaneous Settings +| Setting | Default Value | Description | +|----------------------|---------------|------------------------------------------------------------------------------------------------------------------| +| `user_agent` | `null` | The name of the `User-Agent` that should be passed in the `User-Agent` header on all requests to model providers | +| `save_shell_history` | `true` | Enables or disables REPL command history | diff --git a/docs/Installation.md b/docs/Installation.md new file mode 100644 index 0000000..842cd11 --- /dev/null +++ b/docs/Installation.md @@ -0,0 +1,121 @@ +# Installation + +## Prerequisites +Loki requires the following tools to be installed on your system: +* [jq](https://github.com/jqlang/jq) + * `brew install jq` +* [usql](https://github.com/xo/usql) (For the `sql` agent) + * `brew install xo/xo/usql` +* [docker](https://docs.docker.com/engine/install/) +* [uv](https://docs.astral.sh/uv/getting-started/installation/) + * `curl -LsSf https://astral.sh/uv/install.sh | sh` + +These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation, +and they are used within agents and tools. + +## Install + +### Cargo +If you have Cargo installed, then you can install `loki` from Crates.io: + +```shell +cargo install loki-ai # Binary name is `loki` + +# If you encounter issues installing, try installing with '--locked' +cargo install --locked loki-ai +``` + +### Homebrew (Mac/Linux) +To install Loki from Homebrew, install the `loki` tap. Then you'll be able to install `loki`: + +```shell +brew tap Dark-Alex-17/loki +brew install loki + +# If you need to be more specific, use: +brew install Dark-Alex-17/loki/loki +``` + +To upgrade `loki` using Homebrew: + +```shell +brew upgrade loki +``` + +### Scripts +#### Linux/MacOS (`bash`) +You can use the following command to run a bash script that downloads and installs the latest version of `loki` for your +OS (Linux/MacOS) and architecture (x86_64/arm64): + +```shell +curl -fsSL https://raw.githubusercontent.com/Dark-Alex-17/loki/main/install_loki.sh | bash +``` + +#### Windows/Linux/MacOS (`PowerShell`) +You can use the following command to run a PowerShell script that downloads and installs the latest version of `loki` +for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64): + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/Dark-Alex-17/loki/main/scripts/install_loki.ps1 | iex" +``` + +### Manual +Binaries are available on the [releases](https://github.com/Dark-Alex-17/loki/releases) page for the following platforms: + +| Platform | Architecture(s) | +|----------------|-----------------| +| macOS | x86_64, arm64 | +| Linux GNU/MUSL | x86_64, aarch64 | +| Windows | x86_64, aarch64 | + +#### Windows Instructions +To use a binary from the releases page on Windows, do the following: + +1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS. +2. Use 7-Zip or TarTool to unpack the Tar file. +3. Run the executable `loki.exe`! + +#### Linux/MacOS Instructions +To use a binary from the releases page on Linux/MacOS, do the following: + +1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS. +2. `cd` to the directory where you downloaded the binary. +3. Extract the binary with `tar -C /usr/local/bin -xzf loki-.tar.gz` (Note: This may require `sudo`) +4. Now you can run `loki`! + + +## Tab-Completions +You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile: +```shell +# Bash +# (add to: `~/.bashrc`) +source <(COMPLETE=bash loki) + +# Zsh +# (add to: `~/.zshrc`) +source <(COMPLETE=zsh loki) + +# Fish +# (add to: `~/.config/fish/config.fish`) +source <(COMPLETE=fish loki | psub) + +# Elvish +# (add to: `~/.elvish/rc.elv`) +eval (E:COMPLETE=elvish loki | slurp) + +# PowerShell +# (add to: `$PROFILE`) +$env:COMPLETE = "powershell" +loki | Out-String | Invoke-Expression +``` + +## Shell Integration +You can integrate Loki's Shell Assistant into your shell for enhanced command-line assistance. Add the code in the +corresponding [shell integration script](./scripts/shell-integration) to your shell. Then, you can invoke Loki to convert natural language to +shell commands by pressing `Alt-e`. For example: + +```shell +$ find all markdown files +# Will be converted to: +find . -name "*.md" +``` diff --git a/images/loki_rag.png b/images/loki_rag.png new file mode 100644 index 0000000..aac4e38 Binary files /dev/null and b/images/loki_rag.png differ