---
title: Obsidian Daily Chat LLM
emoji: 🧠
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false
---

# 🧠 Obsidian Daily Chat - Hugging Face LLM Space

This Space provides a **100% free, limitless, OpenAI-compatible API** running a lightweight quantized Large Language Model (LLM). It is designed to act as a drop-in replacement API for your **Obsidian AI Daily Chat** and runs flawlessly on mobile (Android/iOS) and desktop.

---

## 🚀 Deployment Instructions

### 1. File Setup
Ensure the following three files are in the root of your Hugging Face Space repository:

1. **`README.md`**: Contains the YAML header above (defines this Space as a Docker space) and this documentation.
2. **`Dockerfile`**: Defines the environment and sets up the server.
3. **`app.py`**: The launcher script that handles dynamic model downloading and runs the server.

---

## 🎭 Multi-Space Setup: One Role, One Model, Per Space

If you deploy this same repo as **three separate Spaces**, give each one a role instead of
manually picking a model for it. Set a single environment variable per Space:

- **`SPACE_ROLE`**: one of `reasoning`, `uncensored`, `general`.

On boot, the Space automatically loads the curated model for that role — no `MODEL_ID` needed:

| Role | Curated model | Good for |
| :--- | :--- | :--- |
| `reasoning` | DeepSeek-R1-Distill Qwen 7B | logic, math, coding |
| `uncensored` | Dolphin 2.9.4 Llama 3.1 8B | unfiltered instruction-following |
| `general` | Qwen 2.5 7B Instruct | everyday all-rounder |

Rename each Space (Settings → **Rename this space**) to match, e.g.
`obsidian-daily-chat-reasoning`, `obsidian-daily-chat-uncensored`, `obsidian-daily-chat-general`,
so the role is visible in the Space's name/URL, not just its config.

### 🔄 "Update Models" button
Curated picks go stale — better models release every few months. Hit this endpoint on a
Space whenever you want it to re-check the Hub and upgrade itself, without you having to
pick a new model by hand:

```
POST https://<space-url>/jolly/refresh-model
```

It searches the Hub for the most-downloaded GGUF model matching that Space's role, verifies
a compatible quantized file exists, and hot-swaps to it. If nothing suitable turns up, it
leaves the currently running model untouched and reports `"status": "no_change"`. Check
`GET /jolly/info` afterwards — `model_source` tells you `"fallback"` (curated pick) vs.
`"hub-discovered"` (auto-found), and `last_refreshed` has the timestamp.

## 🛠️ Manually Picking a Model (Advanced Override)

You don't have to use roles — you can still pick an exact model yourself via **Environment Variables** in Space Settings, which take priority over `SPACE_ROLE`.

### How to Change the Model:
1. Go to your **Space Settings** page on Hugging Face.
2. Scroll down to **Variables and Secrets**.
3. Define the following two environment variables:
   - **`MODEL_REPO`**: The Hugging Face repo ID (e.g. `Qwen/Qwen2.5-1.5B-Instruct-GGUF` or `unsloth/Llama-3.2-3B-Instruct-GGUF`).
   - **`MODEL_FILE`**: The exact GGUF filename or a glob pattern (e.g. `*q4_k_m.gguf` or `Llama-3.2-3B-Instruct-Q4_K_M.gguf`).
4. Re-run or restart your Space. It will automatically download the new model and load it!

### 🌐 Synchronizing Multiple Spaces (Cluster Config)
If you have multiple Spaces deployed for Load Balancing and want them to use the same model without changing settings on all of them manually:
1. Create a public or secret GitHub Gist containing a `config.json` with the model definition, for example:
   ```json
   {
     "MODEL_REPO": "unsloth/Llama-3.2-3B-Instruct-GGUF",
     "MODEL_FILE": "*Q4_K_M.gguf"
   }
   ```
2. Click the **"Raw"** button on your Gist and copy the raw file URL.
3. On all of your Spaces, go to **Settings** > **Variables and Secrets** and add a variable named **`CONFIG_URL`** set to that raw Gist URL.
4. Restart your Spaces. They will all automatically fetch your central Gist config and load the exact same model!

---

### 💡 Recommended Models for Free CPU Basic (16GB RAM):

| Model Repository | Model Filename Pattern | RAM Usage | Performance | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`Qwen/Qwen2.5-1.5B-Instruct-GGUF`** *(Default)* | `*q4_k_m.gguf` | ~1.2 GB | **Extremely Fast** | Smartest micro model; highly multilingual. |
| **`unsloth/Llama-3.2-3B-Instruct-GGUF`** | `*Q4_K_M.gguf` | ~2.2 GB | **Fast & Capable** | Exceptional reasoning and style. Highly recommended! |
| **`Qwen/Qwen2.5-7B-Instruct-GGUF`** | `*q4_k_m.gguf` | ~4.8 GB | **Medium/Slow** | High intelligence; slower generation speed on CPU. |

---

## 🔌 Connecting to Obsidian

Once your Space status shows as **Running**, you can configure your Obsidian AI Daily Chat to use it as a standard OpenAI endpoint.

1. **API URL / Endpoint**: `https://<YOUR_HF_USERNAME>-<YOUR_SPACE_NAME>.hf.space/v1`
2. **API Key**: Create a **Read-only Hugging Face User Access Token** in your Hugging Face Account Settings. Put this token (`hf_...`) as the API key.
3. **Model Name**: Put `huggingface` (or any string, as the server accepts any name).