Welcome to Clan's LLM repository. This repository contains Clan's experiments related to LLMs and how they can be used as an interface to managing your Clan.

Getting Started

Structure

The repository currently contains two main components:

Clan LLM Lib: The library components that power other tools
Clan CLI AI: A subcommand for Clan CLI that enables you conversationally modify your Clan via a TUI.

These components are located in pkgs which roughly follows the same structure as clan-core.

├── checks
│   └── llm                         # Container Tests
└── pkgs
    └── clan-llm
        ├── clan_cli                # Clan CLI Functionality
        │   └── ai                  # AI Subcommand
        └── clan_lib                # Clan LLM Library
            └── llm
                └── container_data  # Container Test Data

Setup

Supported Operating Systems

Linux
macOS

Getting Started with the Development Environment

Let's get your development environment up and running:

Install Nix Package Manager:
- You can install the Nix package manager by either downloading the Nix installer or running this command:
```
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
Install direnv:
- To automatically setup a devshell on entering the directory
```
nix profile install nixpkgs#nix-direnv-flakes nixpkgs#direnv
```
Add direnv to your shell:
- Direnv needs to hook into your shell to work. You can do this by executing following command. The example below will setup direnv for zsh and bash
```
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
```
Allow the devshell
- Run direnv allow to setup the necessary development environment to execute the clan command
Configure Nix for Container Tests
- Container tests require the uid-range system feature in the Nix sandbox. This feature allows Nix to allocate a range of UIDs for containers to use.
- Add the following to your NixOS configuration:
```
nix.settings.experimental-features = [ "auto-allocate-uids" "cgroups" ];
nix.settings.auto-allocate-uids = true;
nix.settings.system-features = [ "uid-range" ];
```
- Or add to your /etc/nix/nix.conf:
```
experimental-features = auto-allocate-uids cgroups
auto-allocate-uids = true
system-features = uid-range
```
- See Clan documentation for more details.
Create a Gitea Account
- Register an account on https://git.clan.lol
- Fork the clan-llm repository
- Clone the repository and navigate to it
- Add a new remote called upstream
```
git remote add upstream gitea@git.clan.lol:clan/clan-llm.git
```
Allow .envrc
- When you enter the directory, you'll receive an error message like this:
```
direnv: error .envrc is blocked. Run `direnv allow` to approve its content
```
- Execute direnv allow to automatically execute the shell script .envrc when entering the directory.
(Optional) Install Git Hooks
- To syntax check your code you can run:
```
nix fmt
```
- To make this automatic install the git hooks
```
./scripts/pre-commit
```

Testing

Unit Tests

Run pytest to execute unit tests:

pytest

Flake Checks

The flake provides several checks to validate your changes:

Run All Checks

nix flake check

Individual Checks

LLM Container Test: Tests the LLM functionality in a NixOS container
```
nix build .#checks.x86_64-linux.llm
```
Format Check: Validates code formatting with treefmt
```
nix build .#checks.x86_64-linux.treefmt
```

Formatting

To format your code:

nix fmt