| --- |
| 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). |
| |
