Sodalis

A local AI companion and system assistant powered by Ollama. Run a fully offline, customizable AI from your terminal.

---

Features

• CLI-first — send messages directly from your terminal
• Companion profiles — swap between different AI personas via YAML config
• Custom system prompts — define your companion's behavior with plain text files
• Ollama backend — runs models locally via the Ollama API

---

Requirements

• Python 3.11+
• Ollama running locally (or via Docker)
• An Ollama-compatible model pulled

---

Installation

git clone https://github.com/Joshua92500/sodalis.git
cd sodalis
pip install -e .

This installs the sodalis CLI command.

---

Running Ollama

You can run Ollama locally, or use the included Docker Compose file (requires NVIDIA GPU):

docker compose up -d

Then pull a model:

docker exec -it sodalis-ollama ollama pull qwen3:8b

---

Configuration

Sodalis looks for companion profiles and system prompts in ~/.config/sodalis/.

Copy the defaults to get started:

mkdir -p ~/.config/sodalis/companions ~/.config/sodalis/prompts
cp config/companions/default.yaml ~/.config/sodalis/companions/
cp config/prompts/system_prompt.txt ~/.config/sodalis/prompts/

Companion profile (companions/default.yaml)

name: Default
model: qwen3:8b
system_prompt: system_prompt.txt
temperature: 0.7

Field	Description
name	Display name for the companion
model	Ollama model to use
system_prompt	Filename of the system prompt in ~/.config/sodalis/prompts/
temperature	Sampling temperature (0.0–1.0)

System prompt (prompts/system_prompt.txt)

Plain text file that sets the personality and behavior of the companion.

---

Usage

sodalis --chat

Use a specific companion profile:

sodalis --chat --companion="MyCompanion"

---

Project Structure

sodalis/
├── config/
│   ├── companions/       # Default companion profiles
│   └── prompts/          # Default system prompts
├── src/sodalis/
│   ├── cli.py            # Entry point and argument parsing
│   ├── config.py         # Companion config loader
│   ├── db.py             # SQLite database client
│   ├── history.py        # Chat history handling
│   ├── llm.py            # Ollama API client
│   └── paths.py          # XDG-style path helpers
├── docker-compose.yml    # Ollama service with GPU support
└── pyproject.toml        # Project metadata and dependencies

---

Runtime Directories

Sodalis follows XDG conventions:

Purpose	Path
Config & companions	~/.config/sodalis/
Data (memory DB)	~/.local/share/sodalis/