=== AI Support Assistant ===
Contributors: Devumar
Tags: rag, chatbot, support, gemini, openai
Requires at least: 6.2
Tested up to: 7.1
Stable tag: 1.0.0
Requires PHP: 8.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add an AI support chatbot that answers customer questions using your uploaded documents (PDF, DOCX, TXT). Powered by Google Gemini or OpenAI.

== Description ==

**AI Support Assistant** lets you build an on-site chatbot that answers questions based on your **actual documentation, product manuals, and guides**.

Most AI chatbots either hallucinate or require you to pay monthly subscription fees for external vector databases like Pinecone, Qdrant, or Milvus. This plugin takes a different approach: it stores embeddings and runs similarity queries **directly inside your existing WordPress MySQL database**.

When a visitor types a question in the chat widget:
1. The plugin converts the question into an **embedding vector**.
2. It runs a **cosine similarity search** across your document chunks in MySQL.
3. It sends the best matching excerpts to your chosen AI model (**Gemini** or **OpenAI**).
4. The assistant replies using your content and shows **which documents it referenced**.

If the answer is not in your documents, you can set a **fallback response** so the bot does not make things up.

= Main Highlights =

* **Self-contained vector search:** Embeddings are saved directly in your WordPress database. You do **not** need any external vector database accounts or recurring SaaS fees.
* **Works with Google Gemini and OpenAI:** Use Gemini models (like Gemini 3.1 Flash Lite or 1.5 Flash) or OpenAI (like GPT-4o or GPT-4o-mini).
* **WordPress AI Connectors support:** Ready for WordPress core AI Client and Connectors API.
* **File uploads:** Upload PDF, Word (.docx), or plain text (.txt) files from your admin area. The plugin splits documents into searchable text chunks automatically.
* **Document citations:** Responses can display badges showing which uploaded file provided the answer.
* **Customizable widget:** Choose between Light, Dark, or Glass themes. Adjust widget height, width, title, and initial greeting.
* **Usage insights and query logs:** Review visitor questions, token usage, and response logs from the admin dashboard, with an option to export logs to CSV.

= Quick Demo =

Watch a walkthrough showing document upload and chat widget setup:
[youtube https://www.youtube.com/watch?v=30vgNLbh6lk]

== Features ==

= Document Management =
* **File formats:** Upload PDF, DOCX, and TXT files from the admin area.
* **Text extraction & chunking:** Automatic parsing with configurable chunk size and overlap.
* **Chunk inspection:** Review chunks or re-index documents whenever you update them.

= AI Providers & Models =
* **Google Gemini:** supports `gemini-3.1-flash-lite`, `gemini-1.5-flash`, `gemini-1.5-pro`, and `text-embedding-004`.
* **OpenAI:** supports `gpt-4o`, `gpt-4o-mini`, and `text-embedding-3-small`.
* **Connectors API:** compatible with core WordPress AI credentials.
* **Custom system prompt:** write your own instructions to control how the bot answers.

= Chat Widget =
* **Floating launcher:** Toggle button with a smooth slide-out chat window.
* **Three built-in themes:** Light, Dark, and Glass.
* **Typewriter effect:** Smooth typing animation for incoming responses.
* **Document citations:** Displays source document tags below answers.
* **Session persistence:** Chat state persists across page navigation within the same session.

= Logs and Analytics =
* **Visual analytics:** Admin graphs showing weekly query volume and token usage.
* **Conversation history:** Filter and search visitor queries and responses.
* **CSV export:** Export chat logs for team analysis or support review.

= Privacy & Security =
* **Permission checks:** Admin actions are protected by nonce verification and `manage_options` capability checks.
* **Safe SQL queries:** Database queries use `$wpdb->prepare()`.
* **Privacy first:** Only the document text needed for an answer and the visitor's question are sent to the AI API. Visitor IPs and personal WordPress user data are never sent.

== External Services ==

This plugin connects to third-party AI APIs to generate embeddings and generate chat responses. Data is sent over HTTPS only when documents are indexed or when a user submits a chat message:

* OpenAI API (https://openai.com): Used for text embeddings and chat answers if OpenAI is selected. See the OpenAI Terms of Use (https://openai.com/policies/terms-of-use/) and Privacy Policy (https://openai.com/policies/privacy-policy/).
* Google Gemini API (https://ai.google.dev): Used for text embeddings and chat answers if Gemini is selected. See Google Terms of Service (https://developers.google.com/terms) and Privacy Policy (https://policies.google.com/privacy).
* WordPress AI Connectors: If enabled on WordPress 7.0+, connections route through credentials defined in your site settings.

No personal user data (like user accounts or IP addresses) is passed to these external services.

== Requirements ==

* WordPress 6.2 or higher
* PHP 8.2 or higher
* MySQL 5.7+ or MariaDB 10.3+
* An API key from Google AI Studio (Gemini) or OpenAI

== Installation ==

= From the WordPress Dashboard =
1. Go to Plugins > Add New.
2. Search for AI Support Assistant.
3. Click Install Now, then Activate.

= Manual Installation =
1. Download the plugin zip file.
2. Go to Plugins > Add New > Upload Plugin and select the zip file.
3. Click Install Now, then activate the plugin.

= Getting Started =
1. Navigate to AI Support Assistant > Settings in your admin menu.
2. Select your AI provider (Google Gemini or OpenAI) and paste your API key.
3. Save your settings.
4. Go to AI Support Assistant > Upload to upload your documents (PDF, DOCX, or TXT). The plugin will extract text and generate embeddings.
5. Place the chat widget on your site using the [ai_support_assistant] shortcode or the AI Support Assistant Widget block in the block editor.

== Shortcode ==

Display the chat box on any page, post, or widget area:

`[ai_support_assistant]`

= Available Attributes =

* **theme:** Visual style. Options: `light` (default), `dark`, `glass`.
* **title:** Header title displayed at the top of the chat box.
* **width:** Widget width, for example `width="400px"`. Default is `360px`.
* **height:** Widget height, for example `height="600px"`. Default is `500px`.
* **provider_override:** Force a specific provider for that widget instance (`gemini` or `openai`).

= Examples =

Default widget:
`[ai_support_assistant]`

Dark theme with custom size and title:
`[ai_support_assistant theme="dark" title="Documentation Help" width="400px" height="600px"]`

Aliases that work the same way:
* `[ai_support]`
* `[support_assistant]`

== Frequently Asked Questions ==

= Do I need a paid vector database subscription? =
No. The plugin stores vector embeddings inside custom tables in your standard WordPress MySQL database and calculates cosine similarity directly. You do not need accounts with Pinecone, Qdrant, or any other vector database host.

= What are the costs to run this? =
The plugin itself is free. You only pay for the API tokens you use through Google Gemini or OpenAI. Both providers offer inexpensive models (such as Gemini Flash Lite or GPT-4o-mini), and Google AI Studio includes a free tier for light usage.

= Which file formats can I upload? =
You can upload PDF (.pdf), Microsoft Word (.docx), and plain text (.txt) files.

= What if a visitor asks something not covered in the documents? =
You can configure a fallback response under Settings (for example: "I do not have information about that in our documentation. Please email support@example.com"). The prompt instructs the model to stick to your reference material rather than guessing.

= Can I customize the colors, title, and initial message? =
Yes. You can edit the widget title, greeting message, input placeholder, and choose between light, dark, and glass styling directly from the settings page.

= Does this work with page builders? =
Yes. Insert the [ai_support_assistant] shortcode inside any shortcode module or text block in Elementor, Divi, Beaver Builder, or the WordPress Block Editor.

= Are visitor conversations stored? =
Yes, conversations are logged locally in your database so you can monitor query quality and check what users are asking. You can disable or review these logs at any time from the admin menu and export them to CSV.

== Screenshots ==

1. Analytics overview showing query counts, token usage, and indexed chunks.
2. Knowledge base document manager with file upload and chunk inspection.
3. Frontend chat widget with citation badges and dark theme.
4. Settings page for API credentials, model choice, and search threshold.
5. Conversation log table with CSV export button.

== Changelog ==

= 1.0.0 =
* Initial release.
* RAG search pipeline using MySQL for vector storage.
* Support for Google Gemini and OpenAI models.
* PDF, DOCX, and TXT file ingestion.
* Frontend chat widget with light, dark, and glass themes.
* Admin dashboard with query metrics and conversation logs.
* Block editor block and shortcode support.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
