Dark-Alex-17/loki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Wrote migration documentation for users coming from AIChat

Browse Source
This commit is contained in:
Alex Clarke
2025-11-07 13:49:02 -07:00
parent c9858ce615
commit 0d9927bb99
1 changed files with 211 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AICHAT-MIGRATION.md
+211
View File
@@ -0,0 +1,211 @@
# AIChat to Loki Migration Guide
Loki originally started as a fork of AIChat but has since evolved into its own separate project with separate goals.
As a result, there's some changes you'll need to make to your AIChat configuration to be able to use Loki.
Be sure you've followed the [first-time setup steps](../README.md#first-time-setup) so that the Loki configuration
directory and subdirectories exist and is populated with the built-in defaults.
## Global Configuration File
You should be able to copy/paste your AIChat configuration file into your Loki configuration directory. Since the
location of the Loki configuration directory varies between systems, you can use the following command to locate your
config directory:
```shell
loki --info | grep 'config_dir' | awk '{print $2}'
```
Then, you'll need to make the following changes:
* `function_calling` -> `function_calling_support`
* `use_tools` -> `enabled_tools`
* `agent_prelude` -> `agent_session`
* `compress_threshold` -> `compression_threshold`
* `summarize_prompt` -> `summarization_prompt`
* `summary_prompt` -> `summary_context_prompt`
## Roles
Locate your `roles` directory using the following command:
```shell
loki --info | grep 'roles_dir' | awk '{print $2}'
```
Update any roles that have `use_tools` to `enabled_tools`.
## Sessions
Locate your `sessions` directory using the following command:
```shell
loki --info | grep 'sessions_dir' | awk '{print $2}'
```
Update the following settings:
* `use_tools` -> `enabled_tools`
* `compress_threshold` -> `compression_threshold`
* `summarize_prompt` -> `summarization_prompt`
* `summary_prompt` -> `summary_context_prompt`
---
# LLM Functions Changes
Probably the most significant difference between AIChat and Loki is how tools are handled. So if you cloned the
[llm-functions](https://github.com/sigoden/llm-functions) repo, you'll need to make the following changes.
**Note: JavaScript functions are not supported in Loki.**
The following guide assumes you're using the `llm-functions` repository as your base for custom functions, and thus
follows that directory structure.
## Agents
Agents are now all handled in one place: the `agents` directory (`<loki-config-dir>/agents`):
```shell
loki --info | grep 'agents_dir' | awk '{print $2}'
```
And instead of separate `index.yaml` and `config.yaml` files, they're now both in a single `config.yaml` file.
So now for all of your agents, copy all the contents of those directories to the corresponding directory in the Loki
`agents` directory. Then make the following changes:
* Copy the contents of your `<aichat-config-dir>/functions/agents` directory into `<loki-config-dir/agents`
* Merge `index.yaml` into `config.yaml`
* If you never created a custom `config.yaml` file, then simply rename `index.yaml` to `config.yaml`
* If you've defined an `agent_prelude`, rename that field to `agent_session`
* Convert all JavaScript tools to either Python or Bash
* For Bash `tools.sh`: Remove the following line:
```bash
eval "$(argc --argc-eval "$0" "$@")"
```
* Any `tools.txt` files you have that define what global functions the agent uses is now replaced by the `global_tools`
field in the agent's `config.yaml`. So for example: If your `tools.txt` looks like this:
```text
fs_mkdir.sh
fs_ls.sh
fs_patch.sh
fs_cat.sh
```
then you need to add the following to your agent's `config.yaml`:
```yaml
global_tools:
- fs_mkdir.sh
- fs_ls.sh
- fs_patch.sh
- fs_cat.sh
```
* If you have any bash `tools.sh` that depend on the utility scripts in the `llm-functions` repository, they've been
replaced by built-in utility scripts. So use the following to replace any matching lines in your `tools.sh` files:
```bash
##################
## Scripts file ##
##################
ROOT_DIR="${LLM_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
# replace with
source "$LLM_PROMPT_UTILS_FILE"
#######################
## guard_path script ##
#######################
"$ROOT_DIR/utils/guard_path.sh"
# replace with
guard_path
############################
## guard_operation script ##
############################
"$ROOT_DIR/utils/guard_operation.sh"
# replace with
guard_operation
######################
## patch.awk script ##
######################
awk -f "$ROOT_DIR/utils/patch.awk"
# replace with
patch_file
```
When you're done with this migration, you should have the following:
* No more `functions/agents` directory
* No `functions/agents.txt` file (Loki assumes that if the agent directory exists, it is loadable)
* No `<loki-config-dir>/agents/<agent-name>/tools.txt`
* No `<loki-config-dir>/agents/<agent-name>/index.yaml`
## Functions
Loki consolidates much of the `llm-functions` repo functionality into one binary. So this means
* There's no need to have `argc` installed anymore
* No separate repository to manage
* No `tools.txt`
* No `functions.json`
* No `functions/mcp` directory at all
* No `functions/scripts`
Here's how to migrate your functions over to Loki from the `llm-functions` repository.
* Copy your AIChat `<aichat-config-dir>/functions` directory into your Loki config directory
* Delete the following files and directories from your `<loki-config-dir>/functions` directory:
* `scripts/`
* `agents.txt`
* `functions.json`
* `Argcfile.sh`
* `README.md` (irrelevant now)
* `LICENSE` (irrelevant now)
* `utils/guard_operation.sh`
* `utils/guard_path.sh`
* `utils/patch.awk`
* Everything in `tools.txt` now lives in the global config file under the `visible_tools` setting:
```text
get_current_weather.sh
execute_command.sh
web_search.sh
#execute_py_code.py
query_jira_issues.sh
```
becomes the following in your `<loki-config-dir>/config.yaml`
```yaml
visible_tools:
- get_current_weather.sh
- execute_command.sh
- web_search.sh
# - web_search.sh
- query_jira_issues.sh
```
* If you've defined a `functions/mcp.json` file, you can leave it alone.
* Similarly to agents, if you have any bash `tools.sh` that depend on the utility scripts in the `llm-functions`
repository, they've been replaced by built-in utility scripts. So use the following to replace any matching lines in
your `tools.sh` files:
```bash
##################
## Scripts file ##
##################
ROOT_DIR="${LLM_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
# replace with
source "$LLM_PROMPT_UTILS_FILE"
#######################
## guard_path script ##
#######################
"$ROOT_DIR/utils/guard_path.sh"
# replace with
guard_path
############################
## guard_operation script ##
############################
"$ROOT_DIR/utils/guard_operation.sh"
# replace with
guard_operation
######################
## patch.awk script ##
######################
awk -f "$ROOT_DIR/utils/patch.awk"
# replace with
patch_file
```
Refer to the [custom bash tools docs](./function-calling/CUSTOM-BASH-TOOLS.md) to learn how to compile and test bash
tools in Loki without needing to use `argc`.