=== Smart Local AI – Browser-Based Private AI Tools ===
Contributors: hasanazizul
Tags: machine learning, alt text, related posts, AI, personalized recommendations
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Privacy-first browser ML suite. Client-side AI for content recommendations, personalized suggestions, and image alt text — no cloud APIs needed.

== Description ==

Smart Local AI brings machine learning directly to the browser. Every ML model runs on-device in the visitor's or editor's browser using [Transformers.js](https://huggingface.co/docs/transformers.js) and WebGPU/WASM. No data is ever sent to external servers, no cloud API keys are needed, and there are zero recurring costs.

= Modules =

**RelevantFlow — Semantic Content Recommendations**

Traditional related-posts plugins match by shared tags or categories. RelevantFlow uses a sentence-transformer model (all-MiniLM-L6-v2) to understand the *meaning* of your content and recommend posts that are genuinely related — even when they share no tags at all.

* Understands synonyms and concepts (e.g. "Salah" and "Islamic Prayer" match)
* Works with any content type — Posts, Pages, WooCommerce Products, or custom post types
* Displays a responsive card widget below your content
* Three layout templates: cards, list, and grid
* Custom placement via CSS selector or shortcode `[atlas_ai_relevantflow]`
* Theme customization with presets (Default, Light, Dark, Minimal) and custom colors
* Embedding index built in-browser by editors — zero server load
* Nightly cron flags new/updated content for re-indexing

**PersonaFlow — Personalized Content Recommendations**

PersonaFlow delivers personalized content recommendations based on visitor behavior — like Netflix for your WordPress site. It tracks 30 behavioral signals (scroll depth, reading time, click patterns, etc.) and computes a per-visitor taste vector to surface the most relevant content for each individual visitor.

* Personalized recommendations powered by real-time behavioral tracking
* 30 behavioral signals including scroll depth, reading time, and engagement patterns
* Per-visitor taste profile computed entirely in the browser — no server-side tracking
* WooCommerce integration for product recommendations
* Three layout templates: cards, list, and grid
* Custom placement via CSS selector or shortcode `[atlas_ai_personaflow]`
* Theme customization with presets and custom colors
* All tracking data stays on the visitor's device — fully GDPR compliant
* Automatic taste decay ensures recommendations stay fresh and relevant

**AltGenius — Automatic Alt Text Generation**

Missing alt text hurts SEO rankings and violates ADA/WCAG accessibility guidelines. AltGenius generates descriptive alt text for every image in your media library — entirely in the browser.

* Two AI models: ViT-GPT2 (fast) and Florence-2 (detailed)
* Bulk Scan to audit and fix your entire media library at once
* Auto-generate on media upload
* Editor sidebar panel for per-image control with prefix/suffix
* No per-image fees, no cloud processing

= Key Features =

* **Zero Cost** — No API keys, no subscriptions, no per-request fees
* **Privacy by Architecture** — All ML inference runs in the browser; data never leaves the device
* **GDPR Compliant** — No external data transmission means no DPA required
* **Shared Hosting Compatible** — No server-side ML dependencies; works anywhere WordPress runs
* **WebGPU + WASM** — Hardware-accelerated inference with automatic fallback
* **Modular** — Enable only the modules you need; each can work standalone
* **Cached Models** — ML models are cached in IndexedDB after first download for instant reuse
* **Themeable** — Built-in theme presets and custom color options to match any WordPress theme

= Upgrade to Pro =

Get more powerful AI modules and premium features with [Smart Local AI Pro](https://atlasaidev.com/smart-local-ai-pro/).

Have questions or need support? [Contact us](https://atlasaidev.com/contact-us/).

= How It Works =

All AI processing runs in your browser. No server-side ML is required. On first use, models are downloaded from Hugging Face and cached in the browser's IndexedDB — this one-time download may take 1–2 minutes depending on your connection. After that, models load instantly.

**RelevantFlow (Related Posts)**

1. Go to **Smart Local AI > Dashboard** and enable the RelevantFlow module (or follow the setup wizard after activation)
2. Select which content type to index from the **Content Type** selector on the Dashboard (defaults to Posts)
3. Go to the **RelevantFlow** tab and click **Build Index** — this downloads the MiniLM model (~23 MB) and generates an embedding for each published item of the selected content type
4. You need at least **2 published items** of the selected content type for recommendations to appear
5. Visit any item on the frontend — a "You Might Also Enjoy" section will appear below the content showing semantically related items

**PersonaFlow (Personalized Recommendations)**

1. Go to **Smart Local AI > Dashboard** and enable the PersonaFlow module
2. Go to the **PersonaFlow** tab to configure display settings (number of recommendations, layout template, appearance)
3. Visit posts on the frontend — PersonaFlow will track reading behavior and build a taste profile
4. After a few page views, personalized recommendations will appear below the content based on the visitor's interests
5. Use the shortcode `[atlas_ai_personaflow]` to place recommendations anywhere in your theme

**AltGenius (Image Alt Text)**

1. Go to **Smart Local AI > Dashboard** and enable the AltGenius module
2. Upload an image via **Media > Add New Media File** — the model downloads on first use (~300 MB for ViT-GPT2) and alt text is generated automatically
3. Or go to **Smart Local AI > Bulk Alt Text** and click **Start Bulk Scan** to generate alt text for all existing images missing it
4. Or edit any post with images in the Block Editor — the AltGenius sidebar panel shows each image with a **Generate Alt Text** button

== Installation ==

= From the WordPress Plugin Directory =

1. Go to **Plugins > Add New** in your WordPress admin
2. Search for "Smart Local AI"
3. Click **Install Now**, then **Activate**

= Manual Installation =

1. Download the plugin zip file
2. Go to **Plugins > Add New > Upload Plugin**
3. Upload the zip file and click **Install Now**
4. Activate the plugin

= After Activation =

After activation, you will be automatically redirected to the Smart Local AI dashboard where a guided setup wizard walks you through the initial configuration:

1. **Enable RelevantFlow** — Turn on the AI recommendation engine
2. **Select Content Type** — Choose which content type to index (Posts, Pages, Products, or any custom post type)
3. **Build Embedding Index** — Index your content so the AI can find similarities between posts
4. **Enable PersonaFlow** — Optionally enable personalized recommendations based on visitor behavior
5. **Preview Recommendations** — Visit a published post to see AI recommendations in action

You can skip the wizard at any time and configure modules manually from the Dashboard. To re-run the wizard later, click the **Run Setup Wizard** button on the Dashboard.

**To test AltGenius**: Go to the **AltGenius** tab and choose your model (ViT-GPT2 is recommended). Then either upload a new image via **Media > Add New Media File** (alt text generates automatically), or go to **Smart Local AI > Bulk Alt Text** to scan existing images. The model downloads on first use (~300 MB) — please wait for it to complete.

**Important**: The first time you use each module, the AI model must download to your browser. This is a one-time download. Please allow 1–2 minutes for the download to complete. A progress indicator is shown during the download. After caching, subsequent uses load instantly.

= Requirements =

* WordPress 6.0 or higher
* PHP 7.4 or higher
* A modern browser with WebAssembly support (Chrome 80+, Firefox 78+, Safari 15+, Edge 80+)
* For best performance: a browser with WebGPU support (Chrome 113+, Edge 113+)

== Frequently Asked Questions ==

= Does Smart Local AI send any data to external servers? =

No. All machine learning inference runs entirely in the visitor's or editor's browser. Your content and images never leave the device. The only external requests are the one-time model downloads from Hugging Face (see "External Services" below), which are cached in the browser's IndexedDB for reuse.

= Do I need an API key? =

No. Smart Local AI does not use any cloud APIs. There are no API keys to configure and no recurring costs.

= Will this slow down my website? =

No. ML processing happens in Web Workers, which run in a separate thread and do not block the main page. The recommendation widget loads asynchronously after the page content. Server-side performance is unaffected because all computation happens in the browser.

= How many posts or images can Smart Local AI handle? =

There is no hard limit. RelevantFlow stores lightweight embedding vectors (a few KB per post) in a custom database table. AltGenius processes images one at a time in the browser. Sites with thousands of posts and images work fine.

= Does it work with custom post types? =

Yes. RelevantFlow supports any public post type — Posts, Pages, WooCommerce Products, or any custom post type registered on your site. Select your preferred content type from the Content Type selector on the Dashboard or during the setup wizard. The free version supports one content type at a time; Pro supports unlimited types.

= What happens if JavaScript is disabled? =

The recommendation widget and alt text generator simply will not appear. Your site continues to function normally with no errors or broken layouts.

= Is Smart Local AI compatible with caching plugins? =

Yes. Since Smart Local AI runs in the browser, it works alongside any server-side caching plugin (WP Super Cache, W3 Total Cache, LiteSpeed Cache, etc.).

= Can I use individual modules as standalone plugins? =

The architecture supports it, but currently modules are distributed as part of Smart Local AI. Standalone module plugins are planned for the future.

= How does PersonaFlow personalization work? =

PersonaFlow tracks 30 behavioral signals (such as scroll depth, reading time, and click patterns) entirely in the visitor's browser using localStorage. It computes a per-visitor taste vector and scores your published posts against it to surface the most relevant recommendations. No data is sent to any server — the entire process is client-side.

= Does PersonaFlow require user consent or cookies? =

PersonaFlow stores behavioral data in the visitor's browser localStorage — it does not use cookies and does not transmit any data to external servers. Since all data stays on the visitor's device, it is fully GDPR compliant. However, we recommend mentioning localStorage usage in your privacy policy for full transparency.

= Can I customize the appearance of recommendations? =

Yes. Both RelevantFlow and PersonaFlow offer built-in theme presets (Default, Light, Dark, Minimal) and custom color options for background, card background, text, headings, accent color, and border color. You can also customize the border radius. All settings are available in the module settings page under the Appearance section.

= Can I place recommendations anywhere on my page? =

Yes. You can use the shortcodes `[atlas_ai_relevantflow]` and `[atlas_ai_personaflow]` to place recommendations anywhere in your posts, pages, or theme templates. You can also set a custom CSS selector in the module settings to target a specific container on your page.

= Does PersonaFlow work with WooCommerce? =

Yes. PersonaFlow includes built-in WooCommerce integration. It tracks product viewing behavior and can recommend products based on individual shopping patterns — all without any cloud-based tracking.

= Is there a Pro version? =

Yes! [Smart Local AI Pro](https://atlasaidev.com/smart-local-ai-pro/) includes additional AI modules and premium features. [Contact us](https://atlasaidev.com/contact-us/) if you have questions.

== Screenshots ==

1. Smart Local AI Dashboard — Enable modules, select content type, and manage settings from a central dashboard with guided setup wizard
2. RelevantFlow Settings — Configure recommendation display, build embedding index, customize appearance
3. RelevantFlow Widget — Semantic content recommendations displayed below posts
4. PersonaFlow Settings — Configure personalized recommendations and behavioral tracking
5. PersonaFlow Widget — Personalized content recommendations based on visitor behavior
6. AltGenius Settings — Choose AI model, configure prefix/suffix for alt text
7. AltGenius Bulk Scan — Audit and fix alt text across your entire media library
8. AltGenius Editor Panel — Per-image alt text generation in the block editor


== External Services ==

This plugin connects to the following external services. No user data or site content is transmitted to these services — only the ML model files are downloaded.

= Hugging Face Model Hub =

ML models are downloaded from the Hugging Face Model Hub (`https://huggingface.co/`) on first use and cached in the browser's IndexedDB. The following models are used:

* **RelevantFlow**: `Xenova/all-MiniLM-L6-v2` (~23 MB) — Sentence transformer for content embeddings
* **AltGenius (ViT-GPT2)**: `Xenova/vit-gpt2-image-captioning` (~300 MB) — Image captioning model
* **AltGenius (Florence-2)**: `onnx-community/Florence-2-base-ft` (~460 MB) — Advanced image captioning model

These models are open-source and licensed under Apache 2.0 or MIT. No user content, images, or site data is uploaded to Hugging Face — the connection is download-only.

* [Hugging Face Terms of Service](https://huggingface.co/terms-of-service)
* [Hugging Face Privacy Policy](https://huggingface.co/privacy)

== Changelog ==

= 1.0.5 =
* New: Content type selection — choose which post type (Posts, Pages, Products, or any custom type) RelevantFlow indexes and recommends
* New: Setup wizard — guided 5-step onboarding walks you through enabling modules, selecting content type, building the index, and previewing recommendations
* New: Automatic redirect to the plugin dashboard after activation so you can start setup immediately
* New: Content Type selector card on the Dashboard for quick post type switching
* New: Upgrade & Support banner on the Dashboard with links to Pro and contact
* Improvement: RelevantFlow now fully supports custom post types across all queries (embeddings, stats, indexing, cron, similar posts, and frontend display)
* Improvement: Setup wizard includes post preview on the finish screen
* Improvement: PersonaFlow step in the wizard works as a toggle — enable or disable and proceed
* Improvement: Developer Tools description updated to reflect all data cleared on reset
* Fix: AltGenius Bulk Scan Pro upgrade link pointed to wrong URL

= 1.0.4 =
* Fix: Similar posts table fails to create on SQLite/WordPress Playground — `rank` column renamed to `sort_rank` (reserved keyword)
* Fix: RelevantFlow similar posts table now lazily created on first use if activation fails
* Improvement: Full SQLite and MySQL compatibility for all database operations
* Improvement: Existing MySQL installs with old `rank` column automatically migrated on upgrade

= 1.0.3 =
* Fix: Admin dashboard crash on WordPress Playground — wp.apiFetch not loaded (missing wp-api-fetch dependency)
* Fix: AltGenius editor panel and media upload scripts missing WordPress script dependencies
* Improvement: All admin script enqueues now explicitly declare required WordPress globals alongside build-generated dependencies

= 1.0.2 =
* Fix: Admin UI failed to load on WordPress Playground and older WP versions (wp-element dependency missing)
* Fix: Plugin activation crash when AtlasAiDev library files were missing
* Fix: Fatal error from hardcoded text-to-audio constant in AtlasAiDev Insights library
* Improvement: WordPress Playground blueprint now creates demo content with 10 posts across 2 categories
* Improvement: Blueprint uses MU plugin approach for reliable demo setup
* Improvement: Opt-in telemetry now collects plugin-specific usage metrics (module enablement, settings, content counts)

= 1.0.0 =
* Initial release with RelevantFlow, PersonaFlow, and AltGenius modules

== Upgrade Notice ==

= 1.0.5 =
Content type selection for RelevantFlow — index Posts, Pages, Products, or any custom post type. New guided setup wizard after activation. Fixes AltGenius Pro link.

= 1.0.4 =
Full SQLite compatibility — similar posts table now works on WordPress Playground and SQLite-based environments. Existing MySQL installs auto-migrated.

= 1.0.3 =
Fixes JavaScript errors on WordPress Playground and missing script dependencies for AltGenius editor/media upload.

= 1.0.2 =
Fixes admin UI loading issue on WordPress Playground and older WordPress versions.
