=== Razhur Connector for AvalAI ===
Contributors: arashmoradi99
Tags: ai, avalai, gateway, connector, image-generation
Requires at least: 7.0
Tested up to: 7.0
Stable tag: 1.0.12
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Use AvalAI as an AI provider in WordPress: generate text and images with many different models through a single unified gateway.

== Description ==

Razhur Connector for AvalAI adds **AvalAI** (https://avalai.ir) as a selectable AI provider for the WordPress AI system that ships with WordPress 7.0. AvalAI is an AI gateway (similar to OpenRouter) that gives you access to many different AI models — such as GPT, Gemini, Claude, Flux, Imagen and Qwen — through a single unified API.

Once activated and configured with your AvalAI API key, AvalAI appears alongside the other providers on the WordPress AI settings page, and every built-in AI feature simply works through AvalAI. No changes to the core AI plugin are required; this plugin behaves as a drop-in provider, exactly like the official OpenAI and Google connector plugins.

This is an independent, third-party plugin developed by Razhur. It is not affiliated with, endorsed by, or sponsored by AvalAI. "AvalAI" is used only to identify the service this plugin connects to.

= Features =

* **Drop-in AI provider** — registers AvalAI with the WordPress AI system; no core changes needed.
* **Many models** — access a large set of text and image models, fetched live from AvalAI.
* **Per-task model selection** — choose a dedicated model for text generation, image generation and vision (image understanding). Each list shows only the models that support that task, so you can pick a cheaper or faster model and avoid unexpected cost.
* **Default aspect ratio** — set a default image ratio (1:1, 3:2, 2:3, 16:9, 9:16) that is sent with every image request, with an optional prompt-text hint for models that ignore the size parameter.
* **Automatic image optimization** — large AI-generated PNG images are downscaled and converted to WebP on import to keep pages fast, while WordPress still generates all responsive sizes. This is optional and can be turned off.
* **Clean English file names** — generated images are saved with tidy ASCII file names instead of long names derived from the prompt.
* **Selectable API endpoint** — choose between the two AvalAI endpoints, or enter a custom base URL.
* **Secure key handling** — the API key is stored through the WordPress AI settings page and masked in REST responses.
* **Translation ready** — fully internationalized, shipping with English and a complete Persian (fa_IR) translation.

= Supported AI features =

* Content generation
* Article generation
* Content rewriting
* Image generation (including featured images)
* Vision / alt text generation
* Other AI-assisted workflows provided by the WordPress AI system

= API endpoints =

AvalAI provides two equivalent endpoints; either can be selected in the settings:

* https://api.avalai.ir/v1 (primary, default)
* https://api.avalapis.ir/v1 (mirror)

= Requirements =

* WordPress 7.0 or higher (the AI Client SDK is bundled in WordPress 7.0 core).
* PHP 7.4 or higher.
* An AvalAI API key.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/ai-provider-for-avalai/`, or install it from the Plugins screen.
2. Activate the plugin through the "Plugins" menu in WordPress.
3. Go to **Settings -> AvalAI** and select the API base URL (primary or mirror).
4. Go to the WordPress AI settings page (**Settings -> AI**) and enter your AvalAI API key, or define it via the `AVALAI_API_KEY` constant or environment variable. You can obtain a key at https://ava.al/keys.
5. Optionally, use the "Model Selection" and "Image Options" sections on the AvalAI settings page to choose a model and a default aspect ratio per task.

== Frequently Asked Questions ==

= Where do I enter the API key? =

On the WordPress AI settings page, next to the other providers. The key is stored in the `connectors_ai_avalai_api_key` option, or it can be provided via the `AVALAI_API_KEY` constant or environment variable.

= How do I switch between the two AvalAI endpoints? =

Go to Settings -> AvalAI and choose the primary or mirror endpoint, or enter a custom URL. Advanced setups can fix it with the `AVALAI_BASE_URL` constant.

= My API key fails validation when I save it. =

The system validates the key by listing models against the configured base URL. Make sure the correct base URL is selected under Settings -> AvalAI and that your server can reach that endpoint, then save the key again.

= Can I choose which model is used? =

Yes. Under Settings -> AvalAI you can select a dedicated model for text, image and vision tasks. Each list only shows models that support that task.

= Will generated images slow down my site? =

No. AI-generated images are automatically downscaled and converted to WebP on import (this can be disabled in settings), while WordPress still generates all responsive image sizes.

= Does optimization affect normal media uploads? =

No. Image optimization only applies to images created through the WordPress AI system, not to regular media uploads.

== External services ==

This plugin connects to the external service **AvalAI** to provide its AI features. Without connecting to this service, the plugin does nothing.

* **What is sent:** when you (or an AI feature) run a generation request, your prompt content — and, where relevant, images — together with your API key are sent to AvalAI. A request is also made to list the available models and to validate the API key.
* **When it is sent:** only when an AI request is performed, and when listing/validating models on the settings page.
* **Where it is sent:** to the AvalAI API at `https://api.avalai.ir/v1` or `https://api.avalapis.ir/v1` (selectable in settings).
* The plugin adds no front-end output and no external links on the public site.

Use of this service is subject to AvalAI's terms and privacy policy:

* Website: https://avalai.ir
* Documentation and privacy policy: https://docs.avalai.ir/en/

Using this plugin requires an AvalAI account and API key.

== Screenshots ==

1. AvalAI connected as a provider on the WordPress AI settings page.
2. Settings -> AvalAI: API endpoint and per-task model selection.
3. Per-task model selection (text, image, vision) and image optimization.
4. Image Options: optimization and a default aspect ratio.

== Changelog ==

= 1.0.12 =
* Replaced generic prefixes with a distinct plugin-specific prefix to avoid conflicts: the namespace is now Razhur\AvalAiConnector, and all option names and filter hooks use the razhur_avalai_ prefix.

= 1.0.11 =
* Renamed the plugin to "Razhur Connector for AvalAI" with a distinctive, non-affiliated name and added a non-affiliation notice. Improved boolean setting sanitization (rest_sanitize_boolean) and corrected the contributor username.

= 1.0.10 =
* Compliance fixes for the WordPress.org Plugin Directory: escape exception output, remove the discouraged load_plugin_textdomain() call (translations are loaded automatically), add direct-file-access protection to the autoloader, and rewrite the readme in English.

= 1.0.9 =
* Removed the duplicate Plugin URI header (it matched the Author URI) and prepared the plugin for submission, including an "External services" disclosure section.

= 1.0.8 =
* Updated the plugin descriptions so AvalAI is correctly presented as a gateway to many different AI models.

= 1.0.7 =
* Fixed: saving the plugin settings no longer clears the connector API key (settings now use a dedicated settings group).
* Improved model classification using the "mode" field returned by AvalAI, so all image models appear correctly in the image model list.

= 1.0.6 =
* The plugin is now fully translatable. Added a translation template (POT) and a complete Persian (fa_IR) translation.

= 1.0.5 =
* Image optimization is now an option in the settings (enabled by default), with a warning about large images when disabled.
* Generated image file names are now created in English (ASCII). Filter: `razhur_avalai_image_filename`.

= 1.0.4 =
* Added a default image aspect ratio setting. The selected ratio (1:1, 3:2, 2:3, 16:9, 9:16) is sent as the `size` parameter with every image request, with an optional prompt-text hint. Filter: `razhur_avalai_image_size`.

= 1.0.3 =
* Added per-task model selection (text, image, vision) on the AvalAI settings page; each list shows only relevant models. Applied through the `wpai_preferred_text_models`, `wpai_preferred_image_models` and `wpai_preferred_vision_models` filters, without modifying the core AI plugin.

= 1.0.2 =
* Added automatic optimization of AI-generated images on import (downscale to a maximum of 1536px and convert to WebP), while WordPress still generates all responsive sizes. Filters: `razhur_avalai_optimize_images`, `razhur_avalai_image_max_dimension`, `razhur_avalai_image_quality`, `razhur_avalai_image_mime`.

= 1.0.1 =
* Fixed "cURL error 28: Operation timed out" errors (especially for image generation) by setting an adequate request timeout. Filter: `razhur_avalai_request_timeout`.

= 1.0.0 =
* Initial release. Adds AvalAI as an AI provider with access to many different models and a configurable API base URL.

== Upgrade Notice ==

= 1.0.11 =
Plugin renamed to "Razhur Connector for AvalAI" and additional compliance fixes.
