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.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
Free Brush Lab AI out of the box, plus easy local models
islandmed9f5ec83ab7bf
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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### Sculptingdiff --git a/README.md b/README.mdindex 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, nevercode), 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 meshsculptforge-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 1024x1024diff --git a/docs/ai-services.md b/docs/ai-services.mdindex 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, ScuKeys are stored in your local settings file (`ai.json`, owner-only permissions) or read fromenvironment 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 modelsThe free option runs each model author's **own public demo** on Hugging Face's shared ZeroGPUdiff --git a/docs/local-ai.md b/docs/local-ai.mdnew file mode 100644index 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.cppindex 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.cppindex 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::sreturn 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.hindex 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 environmentstd::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.cppindex 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.hindex 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 3Ddiff --git a/tests/test_core.cpp b/tests/test_core.cppindex 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.htmlindex 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 noservers, 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