README.md

metadata

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:

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