Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

Free Brush Lab AI out of the box, plus easy local models

islandmed9f5ec83ab7bf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6362c509..e1ea1b78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,17 @@ All notable changes to SculptForge are listed here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
[Semantic Versioning](https://semver.org/).
+## [Unreleased]
+
+### AI
+- Brush Lab is free out of the box: the new default **Free** provider uses an open model hosted by
+ Pollinations.ai with no account or key, and falls back to a running local Ollama. Key-less Anthropic
+ settings from earlier versions switch to Free automatically.
+- Local models made easy: Ollama and LM Studio presets, **Find models** (checks the connection and lists
+ installed models), and setup steps for your OS in the AI provider panel. New guide:
+ [Run AI on your own computer](docs/local-ai.md). The default local model is now `qwen3:4b-instruct`.
+- Switching the Brush Lab provider no longer resets your image-to-3D settings.
+
## [0.2.0] - 2026-10-21
### Sculpting
diff --git a/README.md b/README.md
index 5775aa5d..f9021806 100644
--- a/README.md
+++ b/README.md
@@ -78,8 +78,10 @@ keep polygroups, mask and polypaint) or as OBJ, FBX or GLB.
**Free built-in AI: Brush Lab (describe a brush, AI builds it)**
- "Dry cracked mud", "overlapping dragon scales", then "make it sharper". Brushes are recipes (data, never
code), with every value exposed as a slider. Share them as `.sfbrush` files.
-- Works with Claude (Anthropic API) or any OpenAI-compatible endpoint, including **local models through
- Ollama or LM Studio**.
+- **Free out of the box**: no account or key. It uses an open model (GPT-OSS 20B) hosted by Pollinations.ai,
+ and falls back to a local Ollama when you're offline.
+- Or bring your own: Claude (Anthropic API) or any OpenAI-compatible endpoint, including **private local
+ models through Ollama or LM Studio** ([5-minute setup for Windows, macOS and Linux](docs/local-ai.md)).
**Free built-in AI: Generate 3D from an image or text**
- A sketch, a piece of concept art or a description becomes a full 3D model (limbs, back and all), then gets
@@ -184,8 +186,11 @@ sculptforge-cli -c 'open path=statue.obj; unreal_send destination=/Game/Props he
# Phone capture -> watertight base mesh
sculptforge-cli -c 'open path=scan.ply; splat_transform rotate_x=180 fit=true; splat_clean; splat_to_mesh resolution=256; export_glb path=base.glb'
-# Design a brush with a local model and save it for the team
-sculptforge-cli -c 'brush_ai prompt="weathered stone edges" provider=openai-compatible model=qwen3:4b-instruct; brush_save path=stone.sfbrush'
+# Design a brush (free, no key) and save it for the team
+sculptforge-cli -c 'brush_ai prompt="weathered stone edges"; brush_save path=stone.sfbrush'
+
+# ...or with a private local model
+sculptforge-cli -c 'brush_ai prompt="weathered stone edges" provider=openai-compatible model=qwen3:4b-instruct'
# Review-sheet turntable (8 frames)
sculptforge model.glb --render review/model.png --turntable 8 --size 1024x1024
diff --git a/docs/ai-services.md b/docs/ai-services.md
index dd5ee75f..e20cb36c 100644
--- a/docs/ai-services.md
+++ b/docs/ai-services.md
@@ -8,7 +8,7 @@ telemetry, no account and no servers of its own. When you use an AI feature, Scu
| Feature | Service (your choice) | What is sent | Key |
|---|---|---|---|
-| Brush Lab | Anthropic (Claude), or any OpenAI-compatible endpoint such as a local Ollama / LM Studio | Your brush description and the current brush settings (text only) | Your API key; none for local models |
+| Brush Lab | Free (default): Pollinations.ai's hosted open models, falling back to a running local Ollama. Or Anthropic (Claude), or any OpenAI-compatible endpoint such as a local Ollama / LM Studio | Your brush description and the current brush settings (text only) | None for Free and local models; your API key otherwise |
| Generate 3D (image) | Hugging Face Spaces (free), fal.ai, Meshy, or your own command | The image you chose, cropped and resized to at most 1024 px | Optional HF token; your fal.ai / Meshy key |
| Generate 3D (text) | Hugging Face Spaces (free), fal.ai, Meshy | Your text description | As above |
| Send to Unreal | Your own Unreal Editor (local network) | The exported FBX | None |
@@ -16,6 +16,16 @@ telemetry, no account and no servers of its own. When you use an AI feature, Scu
Keys are stored in your local settings file (`ai.json`, owner-only permissions) or read from
environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `HF_TOKEN`, `FAL_KEY`, `MESHY_API_KEY`).
+## The free Brush Lab model
+
+The **Free** provider sends your brush request to [Pollinations.ai](https://pollinations.ai)'s
+anonymous, OpenAI-compatible text endpoint (currently GPT-OSS 20B, an Apache-2.0 open model). There's
+no sign-up and no key, and it only ever receives text: your description and the brush values. The
+anonymous tier allows about one request every few seconds, which is plenty for a chat. If the service
+can't be reached and Ollama is running on your machine, SculptForge uses your first local model
+instead. For fully private use, pick **OpenAI-compatible** and point it at Ollama or LM Studio:
+see [Run AI on your own computer](local-ai.md) for step-by-step setup on Windows, macOS and Linux.
+
## The free image-to-3D and text-to-3D models
The free option runs each model author's **own public demo** on Hugging Face's shared ZeroGPU
diff --git a/docs/local-ai.md b/docs/local-ai.md
new file mode 100644
index 00000000..b6f8d378
--- /dev/null
+++ b/docs/local-ai.md
@@ -0,0 +1,174 @@
+# Run AI on your own computer
+
+Brush Lab works free out of the box with a hosted model. If you'd rather keep everything on your
+machine (private, offline, no rate limits), run a local model with [Ollama](https://ollama.com) or
+[LM Studio](https://lmstudio.ai). Both are free, and both work on Windows, macOS and Linux.
+
+It takes about five minutes: install, download one model (2.5 GB), and point SculptForge at it.
+
+## What you need
+
+| | Minimum | Comfortable |
+|---|---|---|
+| Memory (RAM) | 8 GB | 16 GB or more |
+| Disk space | 3 GB for the model | |
+| Graphics card | Not required | Any recent NVIDIA, AMD or Apple Silicon GPU |
+| Time per brush | 10-20 s on a laptop CPU | 2-5 s with a GPU |
+
+The model we recommend is **`qwen3:4b-instruct`** (2.5 GB). It's the one we test Brush Lab with,
+and it reliably produces brush recipes. With 16 GB or more you can try a larger model such as
+`qwen3:8b` for more inventive brushes. On a machine with less than 8 GB, stick with the free hosted
+provider.
+
+## 1. Install Ollama
+
+### Windows (10 or 11)
+
+1. Download **OllamaSetup.exe** from [ollama.com/download](https://ollama.com/download) and run it.
+ No administrator rights are needed.
+
+ Or install it from PowerShell, using either of these:
+
+ ```powershell
+ winget install Ollama.Ollama
+ irm https://ollama.com/install.ps1 | iex
+ ```
+
+2. Ollama starts by itself and shows a llama icon in the system tray (bottom-right, near the clock).
+ It starts automatically when you sign in.
+3. Open **PowerShell** or **Terminal** from the Start menu and download the model:
+
+ ```powershell
+ ollama pull qwen3:4b-instruct
+ ```
+
+NVIDIA and AMD Radeon GPUs are used automatically. Keep your graphics driver up to date.
+
+### macOS (Apple Silicon or Intel)
+
+1. Download **Ollama.dmg** from [ollama.com/download](https://ollama.com/download), open it and drag
+ Ollama into **Applications**. Open it once; it lives in the menu bar (top-right).
+
+ Or, with [Homebrew](https://brew.sh):
+
+ ```sh
+ brew install --cask ollama # the app (starts at login)
+ # or: brew install ollama && brew services start ollama (command-line only)
+ ```
+
+2. Open **Terminal** (Applications → Utilities) and download the model:
+
+ ```sh
+ ollama pull qwen3:4b-instruct
+ ```
+
+Apple Silicon Macs (M1 and later) use the GPU automatically and are fast. Intel Macs run on the CPU.
+
+### Linux
+
+1. Install with the official script (it sets up a `systemd` service and detects NVIDIA/AMD GPUs):
+
+ ```sh
+ curl -fsSL https://ollama.com/install.sh | sh
+ ```
+
+ Or use your distribution's package:
+
+ | Distribution | Command |
+ |---|---|
+ | Arch / Manjaro | `sudo pacman -S ollama` (or `ollama-cuda` for NVIDIA, `ollama-rocm` for AMD) |
+ | NixOS | add `services.ollama.enable = true;` to your configuration |
+
+2. Make sure the service is running. The script starts it for you; distribution packages may not:
+
+ ```sh
+ sudo systemctl enable --now ollama
+ systemctl status ollama # should say "active (running)"
+ ```
+
+ No systemd? Run `ollama serve` in a terminal and leave it open.
+
+3. Download the model:
+
+ ```sh
+ ollama pull qwen3:4b-instruct
+ ```
+
+## 2. Check that it's running
+
+In any terminal (PowerShell on Windows):
+
+```sh
+ollama list # shows qwen3:4b-instruct
+ollama run qwen3:4b-instruct "Say hi"
+```
+
+Ollama listens on `http://localhost:11434`. Opening that address in a browser should show
+"Ollama is running".
+
+## 3. Connect SculptForge
+
+1. Open **Brush Lab** and expand **AI provider**.
+2. Choose **OpenAI-compatible**.
+3. Click **Ollama** to fill in the address, then **Find models**. You should see
+ "Connected - 1 model installed", and the model appears in the **Model** list.
+4. Click **Save settings**, then describe a brush: "dry cracked mud".
+
+Leave **API key** empty. Local servers don't need one.
+
+From the command line:
+
+```sh
+sculptforge-cli -c 'brush_ai prompt="dry cracked mud" provider=openai-compatible model=qwen3:4b-instruct; brush_save path=mud.sfbrush'
+```
+
+Even if you stay on the **Free** provider, SculptForge uses your local Ollama automatically whenever
+the hosted model can't be reached (for example, when you're offline). It picks your smallest
+installed model.
+
+## Using LM Studio instead
+
+[LM Studio](https://lmstudio.ai) is a point-and-click app for Windows, macOS and Linux (AppImage),
+if you'd rather not use a terminal.
+
+1. Install LM Studio and open it.
+2. Search for **Qwen3 4B Instruct** in the **Discover** tab and download it.
+3. Open the **Developer** tab, load the model and switch the server **on** (it serves on port 1234).
+4. In SculptForge choose **OpenAI-compatible → LM Studio → Find models**.
+
+## Running the model on another computer
+
+You can run Ollama on a stronger machine (say, a desktop with a GPU) and sculpt on a laptop. On the
+machine running Ollama, set `OLLAMA_HOST=0.0.0.0:11434` and restart Ollama:
+
+- **Windows:** quit Ollama from the tray, add `OLLAMA_HOST` under *Edit environment variables for
+ your account*, then start Ollama again.
+- **macOS:** `launchctl setenv OLLAMA_HOST "0.0.0.0:11434"`, then quit and reopen Ollama.
+- **Linux:** run `sudo systemctl edit ollama`, add these lines, then run
+ `sudo systemctl restart ollama`:
+
+ ```ini
+ [Service]
+ Environment="OLLAMA_HOST=0.0.0.0:11434"
+ ```
+
+In SculptForge, set the endpoint to `http://<that-computer's-IP>:11434/v1/chat/completions`. Only
+do this on a network you trust, because anyone on it can then use your model.
+
+## Troubleshooting
+
+| You see | Fix |
+|---|---|
+| "Nothing is answering at http://localhost:11434..." | Ollama isn't running. Windows/macOS: start the Ollama app. Linux: `sudo systemctl start ollama`, or run `ollama serve`. |
+| "The server is running but has no models yet" | Run `ollama pull qwen3:4b-instruct`. |
+| "HTTP 404 ... model not found" | The model name in settings doesn't match `ollama list`. Click **Find models** and pick it from the list. |
+| "The model did not return a brush recipe" | Very small models (1B and under) sometimes ignore the format. Use `qwen3:4b-instruct` or larger, or try again. |
+| The first brush takes much longer | The model loads into memory on first use. Later requests are faster. Ollama unloads it after 5 idle minutes. |
+| It's very slow | You're running on the CPU. That's fine for Brush Lab (one short reply per brush), but a GPU or Apple Silicon is much faster. Close other heavy apps to free memory. |
+| Port 11434 already in use (Linux) | The service is already running, so you don't need `ollama serve`. |
+
+## Privacy
+
+With a local model, nothing about your brush requests leaves your computer. Ollama and LM Studio
+download models once, then work fully offline. See [AI services & privacy](ai-services.md) for what
+each provider receives.
diff --git a/src/ai/AiCommands.cpp b/src/ai/AiCommands.cpp
index f252594c..412144bd 100644
--- a/src/ai/AiCommands.cpp
+++ b/src/ai/AiCommands.cpp
@@ -16,18 +16,17 @@ namespace sf::ai {
void registerAiCommands(CommandRegistry& registry, std::function<AiSettings()> settings) {
using T = ParamSpec::Type;
registry.add({"brush_ai",
- "Design a brush from a description using your configured AI provider "
- "(ANTHROPIC_API_KEY, or provider=openai-compatible endpoint=... model=... for Ollama etc.).",
+ "Design a brush from a description. Free by default (a hosted open model, no key); or "
+ "provider=anthropic (ANTHROPIC_API_KEY), or provider=openai-compatible endpoint=... model=... "
+ "for OpenAI, Ollama, LM Studio etc.",
{{"prompt", T::String, "What the brush should do, in an artist's words.", true},
- {"provider", T::String, "'anthropic' or 'openai-compatible' (default: your saved settings).", false},
+ {"provider", T::String, "'free', 'anthropic' or 'openai-compatible' (default: your saved settings).", false},
{"endpoint", T::String, "Override the API endpoint URL.", false},
{"model", T::String, "Override the model name.", false}},
[settings](Document& doc, const Args& a) -> CommandResult {
AiSettings s = settings();
if (a.contains("provider"))
- s = AiSettings::defaults(argString(a, "provider") == "openai-compatible"
- ? AiSettings::Provider::OpenAICompatible
- : AiSettings::Provider::Anthropic);
+ s = AiSettings::defaults(AiSettings::providerFromName(argString(a, "provider")));
if (a.contains("endpoint")) s.endpoint = argString(a, "endpoint");
if (a.contains("model")) s.model = argString(a, "model");
std::vector<ChatMessage> history = {composeUserMessage(argString(a, "prompt"), nullptr)};
diff --git a/src/ai/BrushAssistant.cpp b/src/ai/BrushAssistant.cpp
index 81043e07..e4c4fd17 100644
--- a/src/ai/BrushAssistant.cpp
+++ b/src/ai/BrushAssistant.cpp
@@ -7,7 +7,9 @@
#include <cstdlib>
#include <filesystem>
#include <fstream>
+#include <chrono>
#include <iterator>
+#include <thread>
namespace sf::ai {
@@ -16,7 +18,10 @@ namespace {
constexpr const char* kAnthropicUrl = "https://api.anthropic.com/v1/messages";
constexpr const char* kAnthropicModel = "claude-opus-5-5";
constexpr const char* kOllamaUrl = "http://localhost:11434/v1/chat/completions";
-constexpr const char* kOllamaModel = "llama3.1";
+constexpr const char* kOllamaModel = "qwen3:4b-instruct"; // 2.5 GB, fine on CPU; see docs/local-ai.md
+// Free tier: anonymous, rate limited to roughly one request every few seconds per IP.
+constexpr const char* kFreeUrl = "https://text.pollinations.ai/openai";
+constexpr const char* kFreeModel = "openai";
std::filesystem::path utf8Path(const std::string& s) { return std::filesystem::path(std::u8string(s.begin(), s.end())); }
@@ -65,7 +70,10 @@ std::string apiErrorMessage(const Json& j) {
AiSettings AiSettings::defaults(Provider provider) {
AiSettings s;
s.provider = provider;
- if (provider == Provider::Anthropic) {
+ if (provider == Provider::Free) {
+ s.endpoint = kFreeUrl;
+ s.model = kFreeModel;
+ } else if (provider == Provider::Anthropic) {
s.endpoint = kAnthropicUrl;
s.model = kAnthropicModel;
} else {
@@ -75,7 +83,20 @@ AiSettings AiSettings::defaults(Provider provider) {
return s;
}
+AiSettings::Provider AiSettings::providerFromName(const std::string& name) {
+ if (name == "anthropic") return Provider::Anthropic;
+ if (name == "openai-compatible") return Provider::OpenAICompatible;
+ return Provider::Free;
+}
+
+const char* AiSettings::providerName(Provider provider) {
+ return provider == Provider::Anthropic ? "anthropic"
+ : provider == Provider::OpenAICompatible ? "openai-compatible"
+ : "free";
+}
+
std::string AiSettings::resolvedKey() const {
+ if (provider == Provider::Free) return {};
if (!apiKey.empty()) return apiKey;
const char* env = std::getenv(provider == Provider::Anthropic ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY");
return env ? env : "";
@@ -102,7 +123,7 @@ std::string AiSettings::resolvedMeshyKey() const {
Json AiSettings::toJson() const {
Json j = Json::object();
- j.set("provider", provider == Provider::Anthropic ? "anthropic" : "openai-compatible");
+ j.set("provider", providerName(provider));
j.set("endpoint", endpoint);
j.set("model", model);
j.set("apiKey", apiKey);
@@ -121,10 +142,16 @@ Json AiSettings::toJson() const {
}
AiSettings AiSettings::fromJson(const Json& j) {
- Provider p = j["provider"].asString() == "openai-compatible" ? Provider::OpenAICompatible : Provider::Anthropic;
+ // Settings saved before the free tier existed defaulted to Anthropic; without
+ // a key they never worked, so those move to Free.
+ Provider p = providerFromName(j["provider"].asString());
+ if (p == Provider::Anthropic && j["apiKey"].asString().empty() && !std::getenv("ANTHROPIC_API_KEY") &&
+ j["endpoint"].asString() == kAnthropicUrl)
+ p = Provider::Free;
AiSettings s = defaults(p);
- if (!j["endpoint"].asString().empty()) s.endpoint = j["endpoint"].asString();
- if (!j["model"].asString().empty()) s.model = j["model"].asString();
+ const bool keepEndpoint = p == providerFromName(j["provider"].asString());
+ if (keepEndpoint && !j["endpoint"].asString().empty()) s.endpoint = j["endpoint"].asString();
+ if (keepEndpoint && !j["model"].asString().empty()) s.model = j["model"].asString();
s.apiKey = j["apiKey"].asString();
if (!j["effort"].asString().empty()) s.effort = j["effort"].asString();
s.generatorCommand = j["generatorCommand"].asString();
@@ -172,11 +199,11 @@ AiSettings AiSettings::load(const std::string& path) {
}
}
std::ifstream f(utf8Path(path), std::ios::binary);
- if (!f) return defaults(Provider::Anthropic);
+ if (!f) return defaults(Provider::Free);
std::string text((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
Json j;
std::string err;
- if (!Json::parse(text, j, err)) return defaults(Provider::Anthropic);
+ if (!Json::parse(text, j, err)) return defaults(Provider::Free);
return fromJson(j);
}
@@ -267,6 +294,12 @@ std::string buildRequestBody(const AiSettings& s, const std::vector<ChatMessage>
outputConfig.set("format", format);
body.set("output_config", outputConfig);
} else {
+ if (s.provider == AiSettings::Provider::Free) {
+ Json format = Json::object();
+ format.set("type", "json_object");
+ body.set("response_format", format);
+ body.set("referrer", "sculptforge");
+ }
Json sys = Json::object();
sys.set("role", "system");
sys.set("content", brushSystemPrompt());
@@ -329,14 +362,82 @@ BrushSuggestion parseResponse(const AiSettings& s, long httpStatus, const std::s
return out;
}
+std::string modelsUrl(const std::string& chatEndpoint) {
+ std::string base = chatEndpoint;
+ const std::string suffix = "/chat/completions";
+ if (base.size() >= suffix.size() && base.compare(base.size() - suffix.size(), suffix.size(), suffix) == 0)
+ base.resize(base.size() - suffix.size());
+ while (!base.empty() && base.back() == '/') base.pop_back();
+ return base + "/models";
+}
+
+std::vector<std::string> listModels(const AiSettings& s, std::string& error) {
+ std::vector<std::string> out;
+ HttpResponse r = httpRequest("GET", modelsUrl(s.endpoint), requestHeaders(s), {}, 5);
+ if (!r.error.empty()) {
+ error = "Nothing is answering at " + s.endpoint + " - is Ollama or LM Studio running? (" + r.error + ")";
+ return out;
+ }
+ Json j;
+ if (r.status != 200 || !Json::parse(r.body, j, error)) {
+ error = "HTTP " + std::to_string(r.status) + " from " + modelsUrl(s.endpoint);
+ return out;
+ }
+ for (const auto& m : j["data"].items())
+ if (m["id"].isString()) out.push_back(m["id"].asString());
+ if (out.empty()) error = "The server is running but has no models yet - try: ollama pull " + std::string(kOllamaModel);
+ return out;
+}
+
+std::string smallestOllamaModel(std::string& error) {
+ HttpResponse r = httpRequest("GET", "http://localhost:11434/api/tags", {}, {}, 2);
+ Json j;
+ if (r.status != 200 || !Json::parse(r.body, j, error)) return {};
+ std::string best;
+ double bestSize = 0;
+ for (const auto& m : j["models"].items()) {
+ const double size = m["size"].asNumber();
+ if (m["name"].isString() && (best.empty() || size < bestSize)) {
+ best = m["name"].asString();
+ bestSize = size;
+ }
+ }
+ return best;
+}
+
BrushSuggestion requestBrush(const AiSettings& s, const std::vector<ChatMessage>& history,
std::string* rawAssistantJson) {
if (s.provider == AiSettings::Provider::Anthropic && s.resolvedKey().empty()) {
BrushSuggestion out;
- out.error = "No Anthropic API key - add one in AI settings or set ANTHROPIC_API_KEY.";
+ out.error = "No Anthropic API key - add one in AI settings or set ANTHROPIC_API_KEY, or switch to Free.";
+ return out;
+ }
+ const std::string body = buildRequestBody(s, history);
+ HttpResponse r = httpPostJson(requestUrl(s), requestHeaders(s), body);
+ if (s.provider == AiSettings::Provider::Free) {
+ // The anonymous tier allows a request every few seconds; one patient retry covers a quick second ask.
+ if (r.status == 429) {
+ std::this_thread::sleep_for(std::chrono::seconds(6));
+ r = httpPostJson(requestUrl(s), requestHeaders(s), body);
+ }
+ BrushSuggestion out = r.error.empty() ? parseResponse(s, r.status, r.body, rawAssistantJson) : BrushSuggestion{};
+ if (out.ok) return out;
+ // Offline or the free service is down: use a local Ollama if one is running.
+ std::string err;
+ const std::string localModel = smallestOllamaModel(err);
+ if (!localModel.empty()) {
+ AiSettings local = AiSettings::defaults(AiSettings::Provider::OpenAICompatible);
+ local.model = localModel;
+ HttpResponse lr = httpPostJson(requestUrl(local), requestHeaders(local), buildRequestBody(local, history));
+ if (lr.error.empty()) {
+ BrushSuggestion localOut = parseResponse(local, lr.status, lr.body, rawAssistantJson);
+ if (localOut.ok) return localOut;
+ }
+ }
+ if (!r.error.empty()) out.error = "Could not reach the free AI service: " + r.error;
+ out.error += " (Free tier: try again in a moment, run Ollama locally, or add your own provider.)";
return out;
}
- HttpResponse r = httpPostJson(requestUrl(s), requestHeaders(s), buildRequestBody(s, history));
if (!r.error.empty()) {
BrushSuggestion out;
out.error = "Could not reach " + s.endpoint + ": " + r.error;
diff --git a/src/ai/BrushAssistant.h b/src/ai/BrushAssistant.h
index ec769074..1122e47a 100644
--- a/src/ai/BrushAssistant.h
+++ b/src/ai/BrushAssistant.h
@@ -2,7 +2,8 @@
// SPDX-License-Identifier: GPL-3.0-or-later
//
// Bring-your-own-AI brush designer: turns an artist's description ("sharp
-// wrinkles that fade out", "make it grittier") into a BrushRecipe. Works with
+// wrinkles that fade out", "make it grittier") into a BrushRecipe. Free out of
+// the box (a hosted open model, no account or key), or bring your own:
// Anthropic's API or any OpenAI-compatible endpoint (OpenAI, Ollama, LM
// Studio, OpenRouter, ...). The model only ever returns recipe data.
#pragma once
@@ -15,11 +16,13 @@
namespace sf::ai {
struct AiSettings {
- enum class Provider { Anthropic, OpenAICompatible };
- Provider provider = Provider::Anthropic;
+ // Free: Pollinations' anonymous OpenAI-compatible endpoint (open models, no
+ // key), falling back to a local Ollama if it is running.
+ enum class Provider { Free, Anthropic, OpenAICompatible };
+ Provider provider = Provider::Free;
std::string endpoint;
std::string model;
- std::string apiKey; // empty = use ANTHROPIC_API_KEY / OPENAI_API_KEY from the environment
+ std::string apiKey; // Free: unused; empty = use ANTHROPIC_API_KEY / OPENAI_API_KEY from the environment
std::string effort = "low";
// Image to 3D. service: "huggingface" (free Spaces), "fal", "meshy",
// "command" (generatorCommand with {input}/{output}) or "inflate" (offline).
@@ -38,6 +41,8 @@ struct AiSettings {
std::string resolvedMeshyKey() const;
static AiSettings defaults(Provider provider);
+ static Provider providerFromName(const std::string& name); // "free", "anthropic", "openai-compatible"
+ static const char* providerName(Provider provider);
std::string resolvedKey() const;
Json toJson() const;
@@ -75,6 +80,13 @@ std::string buildRequestBody(const AiSettings& s, const std::vector<ChatMessage>
BrushSuggestion parseResponse(const AiSettings& s, long httpStatus, const std::string& body,
std::string* rawAssistantJson = nullptr);
+// Local model servers (blocking). `chatEndpoint` is an OpenAI-compatible
+// .../v1/chat/completions URL; the model list comes from .../v1/models.
+std::string modelsUrl(const std::string& chatEndpoint);
+std::vector<std::string> listModels(const AiSettings& s, std::string& error);
+// The smallest model a local Ollama has installed, or empty if none is running.
+std::string smallestOllamaModel(std::string& error);
+
// Blocking (run on a worker thread): sends the conversation, whose last
// message must be the user's, and returns a recipe.
BrushSuggestion requestBrush(const AiSettings& s, const std::vector<ChatMessage>& history,
diff --git a/src/app/App.cpp b/src/app/App.cpp
index 77f9d779..2f234448 100644
--- a/src/app/App.cpp
+++ b/src/app/App.cpp
@@ -1296,13 +1296,16 @@ void App::drawRecipeEditor(BrushRecipe& recipe) {
void App::drawAiSettings() {
using P = ai::AiSettings::Provider;
- const char* providers[] = {"Anthropic (Claude)", "OpenAI-compatible (OpenAI, Ollama, LM Studio...)"};
+ const char* providers[] = {"Free - no account or key", "Anthropic (Claude) - your key",
+ "OpenAI-compatible (OpenAI, Ollama, LM Studio...)"};
int provider = int(aiSettings_.provider);
ImGui::SetNextItemWidth(-1);
- if (ImGui::Combo("##provider", &provider, providers, 2)) {
- std::string key = aiSettings_.apiKey;
- aiSettings_ = ai::AiSettings::defaults(P(provider));
- aiSettings_.apiKey = key;
+ if (ImGui::Combo("##provider", &provider, providers, 3)) {
+ // Only the brush provider changes; the image-to-3D settings stay.
+ const ai::AiSettings d = ai::AiSettings::defaults(P(provider));
+ aiSettings_.provider = d.provider;
+ aiSettings_.endpoint = d.endpoint;
+ aiSettings_.model = d.model;
}
auto textField = [](const char* label, std::string& value, ImGuiInputTextFlags flags = 0) {
char buf[512];
@@ -1310,9 +1313,84 @@ void App::drawAiSettings() {
ImGui::SetNextItemWidth(-ImGui::CalcTextSize("Endpoint").x - ImGui::GetStyle().ItemInnerSpacing.x);
if (ImGui::InputText(label, buf, sizeof buf, flags)) value = buf;
};
- textField("Endpoint", aiSettings_.endpoint);
- textField("Model", aiSettings_.model);
- textField("API key", aiSettings_.apiKey, ImGuiInputTextFlags_Password);
+ if (aiSettings_.provider == P::OpenAICompatible) {
+ // One-click presets for the two common local servers.
+ const float third = (ImGui::GetContentRegionAvail().x - 2 * ImGui::GetStyle().ItemSpacing.x) / 3;
+ if (ImGui::Button("Ollama", ImVec2(third, 0))) {
+ aiSettings_.endpoint = "http://localhost:11434/v1/chat/completions";
+ modelsChecked_ = false;
+ }
+ ImGui::SameLine();
+ if (ImGui::Button("LM Studio", ImVec2(third, 0))) {
+ aiSettings_.endpoint = "http://localhost:1234/v1/chat/completions";
+ modelsChecked_ = false;
+ }
+ ImGui::SameLine();
+ ImGui::BeginDisabled(pendingModels_.valid());
+ if (ImGui::Button(pendingModels_.valid() ? "Checking..." : "Find models", ImVec2(third, 0))) {
+ auto promise = std::make_shared<std::promise<ModelList>>();
+ pendingModels_ = promise->get_future();
+ std::thread([promise, settings = aiSettings_] {
+ ModelList list;
+ list.models = ai::listModels(settings, list.error);
+ promise->set_value(std::move(list));
+ }).detach();
+ }
+ ImGui::EndDisabled();
+ if (pendingModels_.valid() && pendingModels_.wait_for(std::chrono::seconds(0)) == std::future_status::ready) {
+ localModels_ = pendingModels_.get();
+ modelsChecked_ = true;
+ if (!localModels_.models.empty() &&
+ std::find(localModels_.models.begin(), localModels_.models.end(), aiSettings_.model) ==
+ localModels_.models.end())
+ aiSettings_.model = localModels_.models.front();
+ }
+ }
+ if (aiSettings_.provider != P::Free) {
+ textField("Endpoint", aiSettings_.endpoint);
+ if (aiSettings_.provider == P::OpenAICompatible && modelsChecked_ && !localModels_.models.empty()) {
+ ImGui::SetNextItemWidth(-ImGui::CalcTextSize("Endpoint").x - ImGui::GetStyle().ItemInnerSpacing.x);
+ if (ImGui::BeginCombo("Model", aiSettings_.model.c_str())) {
+ for (const auto& m : localModels_.models)
+ if (ImGui::Selectable(m.c_str(), m == aiSettings_.model)) aiSettings_.model = m;
+ ImGui::EndCombo();
+ }
+ } else {
+ textField("Model", aiSettings_.model);
+ }
+ textField("API key", aiSettings_.apiKey, ImGuiInputTextFlags_Password);
+ }
+ if (aiSettings_.provider == P::OpenAICompatible && modelsChecked_) {
+ if (localModels_.error.empty())
+ ImGui::TextColored(ImVec4(0.45f, 0.8f, 0.5f, 1), "Connected - %d model%s installed",
+ int(localModels_.models.size()), localModels_.models.size() == 1 ? "" : "s");
+ else
+ ImGui::TextColored(ImVec4(0.95f, 0.6f, 0.4f, 1), "%s", localModels_.error.c_str());
+ }
+ if (aiSettings_.provider == P::OpenAICompatible && ImGui::TreeNode("Run a model on this computer")) {
+ // Steps for the platform we're on; the guide covers the others.
+#if defined(_WIN32)
+ ImGui::TextWrapped("1. Install Ollama: download it from ollama.com/download, or in PowerShell run\n"
+ " winget install Ollama.Ollama\n"
+ "2. In a terminal, run: ollama pull qwen3:4b-instruct\n"
+ "3. Ollama runs in the system tray. Click Ollama above, then Find models.");
+#elif defined(__APPLE__)
+ ImGui::TextWrapped("1. Install Ollama: download it from ollama.com/download and drag it to Applications.\n"
+ "2. In Terminal, run: ollama pull qwen3:4b-instruct\n"
+ "3. Ollama runs in the menu bar. Click Ollama above, then Find models.");
+#else
+ ImGui::TextWrapped("1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh\n"
+ " (or your package manager, e.g. sudo pacman -S ollama)\n"
+ "2. Start it if needed: sudo systemctl enable --now ollama\n"
+ "3. Run: ollama pull qwen3:4b-instruct\n"
+ "4. Click Ollama above, then Find models.");
+#endif
+ ImGui::TextWrapped("The 2.5 GB model needs about 4 GB of free memory and works without a graphics card "
+ "(10-20 s per brush on a laptop CPU, a few seconds with a GPU).");
+ if (ImGui::SmallButton("Full guide: Windows, macOS, Linux, LM Studio"))
+ SDL_OpenURL("https://github.com/islandmed/SculptForge/blob/main/docs/local-ai.md");
+ ImGui::TreePop();
+ }
if (aiSettings_.provider == P::Anthropic) {
const char* efforts[] = {"low", "medium", "high"};
int e = aiSettings_.effort == "high" ? 2 : aiSettings_.effort == "medium" ? 1 : 0;
@@ -1325,9 +1403,14 @@ void App::drawAiSettings() {
: "AI settings saved";
}
ImGui::PushStyleColor(ImGuiCol_Text, ImGui::GetStyleColorVec4(ImGuiCol_TextDisabled));
- ImGui::TextWrapped("Opt-in and private: requests go only to the endpoint above. Keys are stored on this "
- "computer only (owner-readable ai.json); leave empty to use ANTHROPIC_API_KEY / "
- "OPENAI_API_KEY. For free, offline use, run Ollama and pick OpenAI-compatible.");
+ if (aiSettings_.provider == P::Free)
+ ImGui::TextWrapped("Free: an open model (GPT-OSS 20B) hosted by Pollinations.ai, no sign-up. Only your "
+ "brush description and settings are sent. Rate limited to a request every few seconds; "
+ "if it can't be reached, a running Ollama is used instead.");
+ else
+ ImGui::TextWrapped("Requests go only to the endpoint above. Keys are stored on this computer only "
+ "(owner-readable ai.json); leave empty to use ANTHROPIC_API_KEY / OPENAI_API_KEY. "
+ "For private, offline use, run Ollama and pick OpenAI-compatible.");
ImGui::PopStyleColor();
}
diff --git a/src/app/App.h b/src/app/App.h
index 14c92071..1f6e3de7 100644
--- a/src/app/App.h
+++ b/src/app/App.h
@@ -183,6 +183,13 @@ private:
std::string raw;
};
std::future<BrushReply> pendingBrush_;
+ struct ModelList {
+ std::vector<std::string> models;
+ std::string error;
+ };
+ std::future<ModelList> pendingModels_; // "Find models" on a local server
+ ModelList localModels_;
+ bool modelsChecked_ = false;
float busyTime_ = 0.0f;
bool scrollChat_ = false;
// Image to 3D
diff --git a/tests/test_core.cpp b/tests/test_core.cpp
index 8d7fc25b..5dfdd0ae 100644
--- a/tests/test_core.cpp
+++ b/tests/test_core.cpp
@@ -509,6 +509,41 @@ TEST(ai_request_and_response_parsing) {
CHECK(s2.ok && s2.recipe.name == "Grit" && s2.recipe.pattern == BrushRecipe::Pattern::Noise);
}
+TEST(ai_free_provider_is_the_default) {
+ using namespace sf::ai;
+ AiSettings s;
+ CHECK(s.provider == AiSettings::Provider::Free);
+ AiSettings free = AiSettings::defaults(AiSettings::Provider::Free);
+ free.apiKey = "ignored";
+ CHECK(free.endpoint.find("pollinations") != std::string::npos);
+ auto headers = requestHeaders(free);
+ CHECK(headers.size() == 1); // no key is ever sent
+ Json req;
+ std::string err;
+ CHECK(Json::parse(buildRequestBody(free, {composeUserMessage("dry cracked mud", nullptr)}), req, err));
+ CHECK(req["response_format"]["type"].asString() == "json_object");
+ CHECK(req["messages"][0]["role"].asString() == "system");
+
+ // Saved settings round-trip; key-less Anthropic settings from older versions become Free.
+ CHECK(AiSettings::fromJson(free.toJson()).provider == AiSettings::Provider::Free);
+ Json missing = Json::object();
+ CHECK(AiSettings::fromJson(missing).provider == AiSettings::Provider::Free);
+ if (!std::getenv("ANTHROPIC_API_KEY")) {
+ AiSettings old = AiSettings::defaults(AiSettings::Provider::Anthropic);
+ AiSettings migrated = AiSettings::fromJson(old.toJson());
+ CHECK(migrated.provider == AiSettings::Provider::Free && migrated.model == "openai");
+ }
+ AiSettings keyed = AiSettings::defaults(AiSettings::Provider::Anthropic);
+ keyed.apiKey = "k";
+ CHECK(AiSettings::fromJson(keyed.toJson()).provider == AiSettings::Provider::Anthropic);
+ AiSettings ollama = AiSettings::defaults(AiSettings::Provider::OpenAICompatible);
+ ollama.model = "qwen3:4b-instruct";
+ AiSettings back = AiSettings::fromJson(ollama.toJson());
+ CHECK(back.provider == AiSettings::Provider::OpenAICompatible && back.model == "qwen3:4b-instruct");
+ CHECK(modelsUrl("http://localhost:11434/v1/chat/completions") == "http://localhost:11434/v1/models");
+ CHECK(modelsUrl("http://localhost:1234/v1/") == "http://localhost:1234/v1/models");
+}
+
namespace {
Image makeImage(int w, int h, const std::function<glm::vec4(float, float)>& f) {
diff --git a/website/index.html b/website/index.html
index 4241c6dc..4503c54e 100644
--- a/website/index.html
+++ b/website/index.html
@@ -99,7 +99,7 @@
<article class="card">
<h3>Brush Lab: describe a brush</h3>
<p>"Dry cracked mud." "Overlapping dragon scales." An AI turns words into a brush recipe you can tweak
- with sliders. Works with Claude or any OpenAI-compatible endpoint, including local Ollama.</p>
+ with sliders. Free with no key, or use Claude, OpenAI or a private local model.</p>
</article>
<article class="card">
<h3>Generate 3D from an image or text</h3>
@@ -188,13 +188,13 @@
<div class="wrap two-col">
<div>
<h2>Free AI built in, or bring your own</h2>
- <p>AI works out of the box at no cost: free models for image and text to 3D, and local models for brush
- design. Every AI feature is optional and talks directly to the service you pick. SculptForge has no
+ <p>AI works out of the box at no cost and with no sign-up: free hosted models for image and text to 3D and
+ for brush design. Every AI feature is optional and talks directly to the service you pick. SculptForge has no
servers, no account and no telemetry.</p>
<ul class="checks">
+ <li><strong>Free, built in:</strong> Hunyuan3D, TRELLIS.2 and Stable Fast 3D on Hugging Face for image and text to 3D, and an open model on Pollinations.ai for brush design. No key needed.</li>
<li><strong>Local models</strong> (Ollama, LM Studio) for brush design. They're free, private and
- work offline.</li>
- <li><strong>Free, built in:</strong> Hunyuan3D, TRELLIS.2 and Stable Fast 3D on Hugging Face for image and text to 3D, with no key needed.</li>
+ work offline. <a href="https://github.com/islandmed/SculptForge/blob/main/docs/local-ai.md">Set one up in five minutes</a> on Windows, macOS or Linux.</li>
<li><strong>Bring your own</strong> Claude, fal.ai or Meshy key when you want more speed or capacity.</li>
</ul>
<p class="fine">Each model has its own licence. For example, Tencent's Hunyuan3D isn't licensed for use