elementus-ai 1.1.0 → 1.1.1

package/README.md

@@ -27,9 +27,9 @@ I just installed the npm package "elementus-ai" — a self-healing element resol
    - If none found, tell me you can't detect a supported framework and stop
 
 2. CHOOSE THE LLM PROVIDER
-   - Ask me: "Do you want to use a local LLM (LM Studio, free, private) or Google Gemini (cloud, fast, ~$0.01/500 tests)?"
+   - Ask me: "Do you want to use a local LLM (LM Studio, free, private) or Google Gemini (cloud, fast, ~$0.001 per AI-healed selector on gemini-3.5-flash; selectors that still work cost nothing)?"
    - If Gemini: ask for API key or check for GEMINI_API_KEY env var
-   - If LM Studio: use defaults (localhost:1234, gemma model)
+   - If LM Studio: use defaults (localhost:1234) with a vision/grounding model loaded (recommended: holo-3.1-9b)
 
 3. INTEGRATE BASED ON MY FRAMEWORK
 
@@ -95,19 +95,19 @@ await p.locator('#stable-element').click()
 ### Option A: Local LLM via LM Studio (free, private)
 
 1. Download [LM Studio](https://lmstudio.ai)
-2. Load a vision-capable model (e.g., `gemma-4-26b-a4b-it`)
+2. Load a vision-capable model. Recommended: **`holo-3.1-9b`** — a GUI-grounding model that locates on-screen elements far better than general chat VLMs, and it's small (9B). Any vision model works, but grounding models earn their keep on the vision-fallback path.
 3. Start the local server (default: `http://localhost:1234`)
 
 ```javascript
 const el = createElementus({
   provider: 'lmstudio',
   lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
-  model: 'gemma-4-26b-a4b-it',
+  model: 'holo-3.1-9b',
 })
 ```
 
 Tips for the local setup:
-- **Vision accuracy:** a dedicated GUI-grounding model (e.g. `Holo2-8B`, Apache-2.0 GGUF on Hugging Face) typically grounds screen coordinates better than general chat VLMs — benchmark numbers are vendor-reported (Nov 2025), verify it loads in your LM Studio version before switching.
+- **Context length:** set it to 16k+ in LM Studio — the ARIA-snapshot grounding step can send large prompts, and the default 4k will silently truncate.
 - **Semantic matching:** load an embedding model (e.g. `text-embedding-nomic-embed-text-v1.5`) and set `embeddingModel` to let paraphrased descriptions ("sign in" vs "log in") resolve without vision.
 
 ### Option B: Google Gemini API (cloud, fast, better vision)
@@ -243,7 +243,7 @@ createElementus({
 
   // LM Studio
   lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
-  model: 'gemma-4-26b-a4b-it',
+  model: 'holo-3.1-9b',
 
   // Gemini
   geminiApiKey: null,       // or GEMINI_API_KEY env var

package/elementus.js

@@ -20,13 +20,13 @@
  *
  * Option A — Local LLM via LM Studio (free, private, no API key):
  *   1. Download LM Studio from https://lmstudio.ai
- *   2. Load a vision-capable model (e.g., gemma-4-26b-a4b-it)
+ *   2. Load a vision-capable model (recommended: holo-3.1-9b, a GUI-grounding model)
  *   3. Start the local server (default: http://localhost:1234)
  *   4. Configure:
  *        const el = createElementus({
  *          provider: 'lmstudio',
  *          lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
- *          model: 'gemma-4-26b-a4b-it',
+ *          model: 'holo-3.1-9b',
  *        })
  *
  * Option B — Google Gemini API (cloud, fast, better vision):
@@ -158,7 +158,7 @@
  *
  *   // LM Studio (when provider = 'lmstudio')
  *   lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
- *   model: 'gemma-4-26b-a4b-it',
+ *   model: 'holo-3.1-9b',
  *
  *   // Gemini (when provider = 'gemini')
  *   geminiApiKey: null,       // or GEMINI_API_KEY env var
@@ -287,7 +287,7 @@ const path = require('path')
 const DEFAULTS = {
   provider: 'lmstudio',
   lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
-  model: 'gemma-4-26b-a4b-it',
+  model: 'holo-3.1-9b',
   geminiApiKey: null,
   geminiModel: 'gemini-3.5-flash',
   maxCandidates: 20,
@@ -367,7 +367,7 @@ const REGION_LABELS = [
  * @param {Object} userConfig
  * @param {'lmstudio'|'gemini'} [userConfig.provider='lmstudio'] - LLM provider
  * @param {string} [userConfig.lmStudioUrl='http://localhost:1234/v1/chat/completions'] - LM Studio endpoint
- * @param {string} [userConfig.model='gemma-4-26b-a4b-it'] - LM Studio model name
+ * @param {string} [userConfig.model='holo-3.1-9b'] - LM Studio model name
  * @param {string|null} [userConfig.geminiApiKey=null] - Google Gemini API key (or GEMINI_API_KEY env var)
  * @param {string} [userConfig.geminiModel='gemini-3.5-flash'] - Gemini model ID
  * @param {number} [userConfig.maxCandidates=20] - max elements sent to LLM for disambiguation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elementus-ai",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Self-healing element resolution for Playwright, WDIO & Appium. AI-powered fallback when selectors break.",
   "main": "elementus.js",
   "scripts": {