Athenian AI Repricing Agent

Developer starting point

This baseline documents repricing code and controls. It does not claim that an external AI request, live price update, or customer-facing price change has been exercised.

Admin Workflow

1. Configure the Plugin

Admins access the plugin through:

WooCommerce -> AI Repricing Agent

The settings screen controls:

• AI model override
• Prefer APC AI when available
• Emit platform events / kernel logs
• Log level
• HTTP timeout
• User-Agent
• Search max URLs
• Minimum priced offers for AI
• Minimum offer confidence
• Outlier max multiplier
• Outlier min multiplier
• Price epsilon
• Bundle/pack offer allowance
• AJAX apply permission

2. Map a Product Source URL

On the WooCommerce product edit screen, admins can set a Pricing source URL and optionally enable Use mapped source only.

Mapped-only mode is most useful when a known external URL is the desired reference source and broad search should be avoided.

3. Run a Repricing Check

Admins can run checks from:

• Product edit metabox
• Product list row action
• WP-CLI

AIRA collects signals, extracts offers, normalizes data, asks AI or uses mapped-only logic, stores the result, and returns a recommendation.

4. Review the Recommendation

The product metabox shows:

• Summary
• Current price
• Suggested price
• Change/no-change decision
• Provider path
• AI reasoning
• Extracted offers
• Supporting matches
• Search results
• Debug JSON

5. Apply the Suggested Price

If a suggested price exists and the recommendation says the product should change, an admin can apply the saved suggestion.

The plugin updates:

• Sale price if the product is currently on sale
• Otherwise regular price, using suggested_regular_price when present

---

Technical Architecture

Main Bootstrap

athenian-ai-repricing-agent.php

Defines plugin constants and loads:

Athenian\AIRepricing\Plugin::instance();

Namespace Structure

| Namespace | Responsibility | |---|---| | Athenian\AIRepricing | Plugin bootstrap, options, platform integration, logging, utility helpers | | Athenian\AIRepricing\Admin | Admin menu, settings, AJAX actions, product metabox | | Athenian\AIRepricing\CLI | WP-CLI commands | | Athenian\AIRepricing\DB | Custom table schema and repository writes | | Athenian\AIRepricing\Engine | Repricing workflow orchestration | | Athenian\AIRepricing\OpenAI | Direct OpenAI Responses API client | | Athenian\AIRepricing\Scrape | HTTP fetching and price extraction | | Athenian\AIRepricing\Search | Search runner and provider management | | Athenian\AIRepricing\Search\Providers | Serper provider implementation | | Athenian\AIRepricing\Sites | Source-site adapter selection | | Athenian\AIRepricing\Sites\Adapters | Schema JSON-LD and Shopify extraction adapters | | Athenian\AIRepricing\Woo | WooCommerce product meta fields and row actions |

---

Data Model

Custom Tables

#### wp_ath_aira_checks

Stores repricing check-level records.

| Column | Purpose | |---|---| | id | Primary key | | created_at | Check timestamp in GMT | | product_id | WooCommerce product ID | | template_id | Repricing template ID | | query | Product-derived search query | | current_price | Product price at check time | | suggested_price | AI/mapped suggested price | | confidence | Recommendation confidence | | should_change | Boolean flag for price change recommendation | | summary | Human-readable summary | | ai_json | Full AI recommendation payload | | signals_json | Search/scrape/offer payload | | context_json | Product/platform/mapped-source context |

Indexes:

• Primary key on id
• product_time on (product_id, created_at)

#### wp_ath_aira_offers

Stores offer-level evidence associated with checks.

| Column | Purpose | |---|---| | id | Primary key | | check_id | Related check record | | product_id | WooCommerce product ID | | source_type | mapped, search, or related source type | | source | Extraction/search source | | domain | Extracted source domain | | url | Source URL | | title | Source/offer title | | price | Extracted price | | currency | Extracted or inferred currency | | extract_method | Extraction method or adapter | | extract_conf | Extraction confidence | | match_conf | AI/match confidence when available | | raw_json | Raw extracted details |

Indexes:

• Primary key on id
• check_id
• product_domain on (product_id, domain)

Options

Primary option:

ath_aira_options

Default settings include:

openai_model             = gpt-4.1-mini
prefer_platform_ai       = true
emit_platform_events     = true
log_level                = info
http_timeout             = 25
user_agent               = Mozilla/5.0 (compatible; AthenianAIRepricingAgent/3.1; +https://example.com)
min_priced_offers_for_ai = 2
price_epsilon            = 0.0001
allow_apply_from_ajax    = false
search_max_urls          = 8
min_offer_confidence     = 0.40
offer_outlier_max_mult   = 2.5
offer_outlier_min_mult   = 0.4
allow_bundle_offers      = false
serper_api_key           = ""

Product Meta

| Meta Key | Purpose | |---|---| | _ath_aira_source_url | Product-level mapped pricing source URL | | _ath_aira_source_only | Boolean flag to skip search/AI ranking and use mapped source only | | _ath_aira_last_check_id | Last repricing check ID | | _ath_aira_last_check_at | Last check timestamp | | _ath_aira_last_template_id | Last template ID used | | _ath_aira_last_summary | Last human-readable summary | | _ath_aira_last_payload | Last search/scrape/offer payload JSON | | _ath_aira_last_ai | Last AI recommendation JSON | | _ath_aira_last_suggested_price | Last suggested price | | _ath_aira_last_should_change | Last change/no-change flag | | _mpn | Product MPN included in query context when present |

---

Repricing Workflow

Standard Search + AI Flow

1. Load product by ID.
2. Build context from product name, SKU, brand, MPN, price, currency, and permalink.
3. Load selected repricing template.
4. Check mapped source state.
5. If not mapped-only, collect search signals.
6. Optionally scrape allowed/direct targets.
7. Extract offers from search results and mapped source.
8. Normalize offers and filter poor matches.
9. Build AI messages with strict instruction rules.
10. Prefer APC AI if configured and available.
11. Fall back to direct OpenAI Responses API when needed.
12. Normalize the recommendation result.
13. Persist check and offer history.
14. Update product-level last-check metadata.
15. Emit platform event.
16. Return structured result to admin UI or CLI.

Mapped-Source-Only Flow

1. Load mapped source URL from _ath_aira_source_url.
2. Detect adapter with SiteRepo.
3. Extract price directly from Shopify JSON or schema/meta adapter.
4. Compare external mapped price against current product price using price_epsilon.
5. Build deterministic recommendation without search or AI ranking.
6. Persist the result and update product metadata.

---

External Service Integrations

WooCommerce

AIRA is WooCommerce-native and integrates with:

• Product edit pricing fields
• Product save handling
• Product edit metaboxes
• Product list row actions
• Product price updates
• WooCommerce logger
• WooCommerce currency context

Serper

Serper provides Google search result discovery for product-aware competitor searches.

Credential path:

• ath_aira_options['serper_api_key']
• Fallback from ASAKM service serper, field api_key

OpenAI

The direct OpenAI path uses the Responses API with strict JSON schema output.

Credential path:

• ASAKM service openai, field api_key
• Optional Athenian Platform Core AI Registry provider data

Athenian Secure API Key Manager

AIRA can use ASAKM through:

• asakm_get() function when available
• Athenian\SecureAPI\SecureStore when available

This avoids hardcoding API credentials in plugin code.

Athenian Platform Core AI

AIRA can route AI recommendations through APC AI first when:

• prefer_platform_ai is enabled
• Athenian\PlatformCore\AI\Manager exists

Athenian Platform Kernel

AIRA can emit platform logs through:

Athenian\Kernel\Logger::log_run(...)

It also fires platform-style actions:

do_action('ath_aira/event', $evt);
do_action('athenian/repricing/event', $evt);

---

WordPress Hooks and Actions

| Hook / Action | Purpose | |---|---| | plugins_loaded | Boot WooCommerce-dependent modules and install schema | | admin_menu | Register WooCommerce submenu page | | admin_init | Register plugin settings | | add_meta_boxes | Register product AI Repricing metabox | | admin_enqueue_scripts | Load metabox JS/CSS on product edit screens | | woocommerce_product_options_pricing | Render mapped-source product fields | | woocommerce_admin_process_product_object | Save mapped-source product fields | | post_row_actions | Add AI Reprice Check product row action | | admin_post_ath_aira_check_product | Handle row-action repricing checks | | wp_ajax_ath_aira_check_product | Run metabox repricing check | | wp_ajax_ath_aira_apply_suggested | Apply saved suggested price | | ath_aira/event | Emit internal repricing events | | athenian/repricing/event | Emit broader platform repricing events |

---

Security and Operational Controls

Capability Checks

All admin operations require:

manage_woocommerce

Nonce Protection

AJAX and row-action flows use nonce validation:

• ath_aira_ajax
• ath_aira_check_product_{product_id}

Sanitization

The plugin sanitizes:

• Source URLs with esc_url_raw
• Template IDs
• Domains
• Admin settings fields
• Numeric threshold values
• User-Agent strings
• Product mapping fields

Conservative Price Application

The metabox can display suggestions without automatically applying them.

Price application from the check workflow is blocked unless:

allow_apply_from_ajax = true

The standalone apply-suggested AJAX action applies only a previously saved suggested price and still requires capability + nonce validation.

Bot Wall Handling

The scrape workflow detects obvious bot-wall/captcha patterns in fetched HTML and marks the target as failed rather than trusting a bad extraction.

Logging

AIRA logs to the best available channel:

1. apc_log() when available
2. WooCommerce logger when available
3. PHP error_log() fallback

Log levels include:

• debug
• info
• warn
• error

---

Technical Verification Notes

During inspection, all PHP files in the plugin package passed php -l syntax checks.

Observed package contents include:

• 22 PHP files
• Admin CSS/JS assets
• Repository marketing and platform documentation
• Search provider implementation
• Site extraction adapters
• Database schema installer
• WP-CLI command registration
• WooCommerce product metadata integration

No REST routes, shortcodes, custom post types, or custom taxonomies were detected in the inspected source package.

---

Implementation Notes

• The plugin is intentionally product-level in its current inspected form. It does not expose a bulk repricing screen in the provided package.
• Search templates exist in the option model, but the current admin settings UI does not appear to provide a full visual template editor.
• The default template uses Serper search with cautious scraping disabled by default.
• Direct mapped-source extraction can operate without AI when mapped-source-only mode is enabled.
• Direct price application is deliberately controlled and capability-gated.
• The default User-Agent contains an example URL and should be reviewed before production use.
• External search/scrape behavior depends on the accessibility and structure of source sites; bot walls or missing structured pricing data may limit extraction.
• Search-based offer extraction currently relies on the available search and extraction workflow and should be validated against target merchant catalogs before large-scale usage.

---