# Sneknim

retoor <retoor@molodetz.nl>

Snek chat bot written in Nim. Connects to the Snek platform via WebSocket, uses DeepSeek for LLM responses, supports tool calling with web search and deep research capabilities.

## Requirements

- Nim >= 2.0.0
- `DEEPSEEK_API_KEY` environment variable

## Build

```sh
nimble install
nimble build
```

## Configuration

Copy `config.json.example` to `config.json` and fill in your Snek credentials:

```json
{
  "username": "botname",
  "password": "botpassword",
  "system_message": "You are a helpful assistant."
}
```

## Usage

```sh
export DEEPSEEK_API_KEY=your_key_here
./sneknim config.json
```

Or with the `--config` flag:

```sh
./sneknim --config config.json
```

## Features

- WebSocket RPC connection with automatic reconnection and exponential backoff
- DeepSeek LLM integration with tool calling support
- Per-channel conversation context with token budgeting
- Web search via rsearch API
- Deep research with iterative search, synthesis, and validation
- Live progress updates via streaming messages
- Typing indicators with random bright colors
- Bot name sanitization to prevent cross-triggering
- Ping/pong auto-response
- Channel join/leave commands via mentions

## Architecture

Single-threaded async via `std/asyncdispatch`. Each incoming message is handled concurrently across channels. Per-channel conversation contexts are stored in a table and trimmed to fit within the 120K token budget.

## Project Structure

```
src/
├── sneknim.nim              Entry point, message handling loop
└── sneknim/
    ├── constants.nim        Protocol and timing constants
    ├── types.nim            Shared type definitions
    ├── config.nim           JSON config loading
    ├── color.nim            HSL bright color generation
    ├── rpc.nim              Snek WebSocket RPC client
    ├── router.nim           Message classification and dispatch
    ├── deepseek.nim         DeepSeek API client
    ├── context.nim          Conversation context management
    ├── tools.nim            Tool registry and execution
    ├── research.nim         Deep research state machine
    └── search.nim           rsearch API client
```