Athenian AI Product Builder

Developer starting point

This baseline was generated from the local athenian-ai-product-builder source folder and the linked product record. The source folder is the reviewed implementation boundary for this pass; runtime behavior and repository commit identity should be reconciled before treating this as release-grade API reference.

Technical Architecture

Main File Structure

athenian-ai-product-builder.php
includes/
  class-aapb-plugin.php
  class-aapb-admin-settings.php
  class-aapb-ai-client.php
  class-aapb-product-panel.php
  class-aapb-templates.php
  helpers.php
assets/
  admin-product.css
  admin-product.js
  admin-settings.css
  admin-settings.js
data/
  default-guidance-templates.json
  user-guidance-templates.json
docs/
  aapb-marketing-document.md
  athenian-platform-marketing.md
  athenian-platform-technical.md

Primary Classes

| Class | Purpose | |---|---| | Plugin | Bootstrap, defaults, settings retrieval, API key resolution, logging, HPOS-related setup. | | Admin_Settings | Tools-page settings UI, settings registration, settings sanitization, tabbed admin interface. | | Product_Panel | WooCommerce product metabox, admin product assets, AJAX handlers, product context, enrichment application, image handling, eBay meta handling. | | AI_Client | OpenAI Responses API request handling, text extraction, structured enrichment request payloads, eBay taxonomy hints, schema generation. | | Templates | JSON template loading, merging, normalization, fallback defaults, JavaScript preset catalog. |

WordPress Hooks

| Hook | Purpose | |---|---| | before_woocommerce_init | Declares WooCommerce Custom Order Tables / HPOS compatibility. | | plugins_loaded | Boots the plugin singleton. | | init | Reserved upgrade/migration hook. | | admin_menu | Registers the settings submenu under Tools. | | admin_init | Registers settings and settings sections. | | admin_enqueue_scripts | Loads settings/product editor assets. | | add_meta_boxes | Adds the AI Product Builder metabox to products. | | wp_ajax_aapb_generate | Handles AI copy generation. | | wp_ajax_aapb_enrich | Handles product-data enrichment and field population. | | wp_ajax_aapb_debug_get_product | Returns debug product/meta data for authorized users. |

AJAX Endpoints

| Action | Purpose | Capability/Nonce Behavior | |---|---|---| | aapb_generate | Generates product copy from product context and selected preset. | Requires management permission and plugin nonce. | | aapb_enrich | Enriches product data from identifier or query and applies selected fields. | Requires management permission and plugin nonce. | | aapb_debug_get_product | Returns product debug context and eBay connector form values. | Requires management permission and plugin nonce. |

REST Routes and Shortcodes

No custom REST routes or public shortcodes were detected in the inspected source package. This plugin is currently centered on WordPress admin and WooCommerce product-editor workflows.

---

Data Model and Configuration

WordPress Options

| Option | Purpose | |---|---| | aapb_settings | Main plugin settings, including enablement, model/endpoint, generation context, enrichment settings, image behavior, eBay settings, and SKU settings. | | aapb_templates | Legacy/backward-compatible template storage that can be merged with JSON templates. |

Product Meta Written by the Plugin

AAPB can write its own eBay-related product meta:

_aapb_ebay_title
_aapb_ebay_subtitle
_aapb_ebay_condition_id
_aapb_ebay_condition_name
_aapb_ebay_condition_description
_aapb_ebay_category_id
_aapb_ebay_category_path
_aapb_ebay_notes
_aapb_ebay_item_specifics_json

It can also mirror connector-oriented eBay meta:

_ath_ebay_category_id
_ath_ebay_category_path
_ath_ebay_category_tree_id
_ath_ebay_condition_id
_ath_ebay_listing_format
_ath_ebay_aspects_json

WooCommerce Product Fields Updated

Depending on settings and result data, AAPB can update:

• post_title / product name.
• post_excerpt / short description.
• post_content / long description.
• Product SKU.
• Regular price.
• Sale price.
• Length.
• Width.
• Height.
• Weight.
• Product categories.
• Product tags.
• Featured image.

JSON Template Files

| File | Purpose | |---|---| | data/default-guidance-templates.json | Bundled category/product copy guidance. | | data/user-guidance-templates.json | Starter user-template structure. | | wp-content/uploads/aapb/user-guidance-templates.json | Preferred update-safe location for site-specific templates. |

---

AI and API Behavior

Text Generation

The copy generator uses the configured API endpoint, defaulting to:

https://api.openai.com/v1/responses

The default model in the inspected plugin defaults is:

gpt-5.2

The plugin sends chat-style input messages to the Responses API and extracts text from common response shapes such as output_text, output[].content[], or legacy choices[0].message.content structures.

Structured Enrichment

Structured enrichment uses a strict JSON schema named:

aapb_product_enrichment

The enrichment request uses a larger output-token budget than simple copy generation and retries with a higher token limit when the response is incomplete because of token truncation.

Image Generation

Settings include image generation controls for:

• Image endpoint.
• Image model.
• Image MIME type.
• Target image size.
• Product-photo prompt style.

However, the inspected AI_Client class does not currently define the generate_image_b64() method that Product_Panel::maybe_set_featured_image() calls. The generated-image feature should be treated as a planned or incomplete implementation until that method is added or connected to the image endpoint.

---

Security and Safety Model

Capability Checks

The product panel uses a can_manage() gate that checks the helper function when present and otherwise falls back to administrative WooCommerce/WordPress capabilities:

• manage_woocommerce
• manage_options

The settings page is registered with manage_options.

Nonce Verification

AJAX workflows verify a plugin nonce before generation, enrichment, or debug product access. The nonce is localized into the product editor script and accepted under either nonce or aapb_nonce request fields for compatibility.

Input Sanitization

The plugin sanitizes and normalizes:

• Settings values.
• URLs.
• Numeric limits.
• Currency codes.
• Product identifiers.
• eBay metadata.
• Template rows.
• Generated/enriched HTML using WordPress-safe content functions.

Secret Handling

The plugin supports secure API key resolution through filters, constants, and Athenian Secure API Key Manager. When Secure API Key Manager is available, the settings page masks the key and avoids writing new SecureStore-resolved secrets into options.

AI Output Guardrails

Generation prompts instruct the AI to:

• Use only provided product context.
• Avoid inventing specifications, certifications, compatibility claims, warranty terms, or unsupported details.
• Return editor-safe HTML.
• Avoid mentioning that it is an AI.

Structured enrichment prompts use confidence and match-reason fields to express uncertainty.

---

Admin Workflow

Settings Workflow

The plugin adds a settings page under:

Tools → AI Product Builder

The settings interface is organized into tabbed sections:

• General — plugin enablement, endpoint, API key, model, temperature, output tokens, debug logging.
• Generation — guidance-template paths and prompt-generation context controls.
• Enrichment — identifier enrichment, field-writing rules, word targets, image strategy, eBay fields, and SKU behavior.
• Developer — hook/filter reference and implementation notes.

Product Editor Workflow

Inside the WooCommerce product editor, operators can:

1. Open the AI Product Builder side panel.
2. Choose Generate or Enrich.
3. Select a guidance preset.
4. Generate HTML-ready product copy for the short or long description.
5. Look up a product by identifier or text query.
6. Review the enrichment result.
7. Populate configured WooCommerce fields.
8. Continue editing the product normally.

JavaScript Editor Integration

The product editor asset (assets/admin-product.js) supports both classic and block-editor style update paths. It attempts to write generated/enriched values into:

• Classic editor title/content/excerpt fields.
• TinyMCE content editor.
• WordPress editor data store when available.
• Featured media data where applicable.
• eBay-related form/meta fields where supported.

This helps the plugin work across multiple WordPress editor contexts.

---

Technical Notes for Implementers

Production Setup Checklist

1. Confirm WooCommerce is active and products are editable.
2. Configure OpenAI credentials using Athenian Secure API Key Manager or AAPB_OPENAI_API_KEY.
3. Review the default model and endpoint settings.
4. Configure generation context toggles to avoid sending unnecessary data.
5. Decide whether enrichment should only fill empty fields or overwrite existing fields.
6. Confirm which fields enrichment may write: prices, dimensions, categories, tags, attributes, images, eBay metadata.
7. Review SKU generation settings before enabling forced SKU overwrites.
8. Test remote image sideloading on a staging product.
9. Treat generated image mode as incomplete until AI_Client::generate_image_b64() is implemented.
10. If using eBay metadata, confirm connector meta expectations and test category/aspects mapping.

Extension Filters

The inspected source exposes several useful filters, including:

| Filter | Purpose | |---|---| | aapb_api_key | Override/resolve the API key programmatically. | | aapb_ai_payload | Modify the general generation API payload. | | aapb_product_context | Modify product context before copy generation. | | aapb_enrich_ai_payload | Modify the structured enrichment API payload. | | aapb_enrich_by_identifier | Provide a custom lookup hint before AI enrichment. | | aapb_enrich_by_query | Provide a custom lookup hint for text-search enrichment. | | aapb_enrich_by_upc | Backward-compatible UPC hint filter. | | aapb_enrich_enable_builtin_upc_fallback | Enable/disable built-in UPC fallback. | | aapb_builtin_upc_lookup_url | Override the UPC fallback lookup URL. | | aapb_builtin_upc_lookup_result | Modify UPC fallback results. | | aapb_enrich_fallback_sku | Customize SKU fallback values during enrichment. | | aapb_enrich_image_prompt | Customize the generated image prompt. | | aapb_sanitize_ebay_block | Modify sanitized eBay metadata. | | aapb_ebay_taxonomy_hint | Modify eBay taxonomy hints before use. |

Implementation Review Notes

The package passes PHP syntax checks for the main plugin file and included PHP classes.

Items to review before relying on all optional features in production:

• Product_Panel::maybe_set_featured_image() calls AI_Client::generate_image_b64(), but that method is not present in the inspected AI_Client class. Remote image sideloading exists; generated image mode needs implementation.
• In AI_Client::fetch_ebay_taxonomy_hint(), two debug return branches reference $dbg, while the local debug variable is named $out_debug. Those branches should be reviewed to avoid notices/errors in rare eBay taxonomy failure paths.
• The JavaScript checks AAPB.ebayMetaPrefix but the localized AAPB object currently includes ajaxUrl, nonce, ver, and presets. The JavaScript has a fallback prefix, so this is not fatal, but localization could be expanded for clarity.
• Attribute writing is exposed as an advanced enrichment setting, but production behavior should be reviewed carefully against variable products and existing taxonomy attributes before enabling at scale.
• AI enrichment can produce estimates when exact product data is unknown. Operators should treat confidence and match reason as review signals, especially for query-based lookup.

---