peptide-repo/pr-vision
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

peptide-geo-monitor v0.1.0: internal AI-visibility dashboard (#1)

Browse Source 
New internal plugin: weekly LLM probes of core peptides (Perplexity sonar + GPT/Gemini-search via OpenRouter/CF gateway) -> custom table -> wp-admin trendline + standings. Provider interface + cost ledger w/ hard $5/mo cap + collector/panel seam (AI-visibility only). v1 = AI-visibility only.

QA: APPROVE-WITH-P2-NOTES — qa-reviews/peptide-geo-monitor/2026-06-13-f488f4a966cbb9e771d3abc20daee3fa49074520.md (P2 follow-ups: ltrim www display bug, PHPCS mandatory, dead cache)

Agent-Session: geomonitor v0.1.0 merge
This commit is contained in:
peptiderepo
2026-06-13 15:34:33 +07:00
committed by GitHub
parent ba58ead521
commit 46fda89e18
39 changed files with 3909 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
includes/collector/class-pgm-ai-visibility-collector.php Normal file
View File

@@ -0,0 +1,180 @@
<?php
declare(strict_types=1);
/**
* AI-visibility data collector — v1 implementation of PGM_Data_Collector.
*
* Reads the pgm_ai_visibility table and returns structured data for:
* - Trendline: per-run visibility score (% cited, position-weighted).
* - Standings: per-peptide latest cited status, our position, competing domains.
* - Run metadata: last run time, MTD cost vs cap.
*
* Score formula (documented in CONTEXT.md):
* base_score = cited_probes / total_probes (range 0–1)
* position_bonus = Σ (1 / our_position) for cited probes / total_probes
* visibility_score = round((base_score + position_bonus) / 2, 4)
*
* Who triggers: PGM_Admin_Page calls the registered collector via the registry.
* Dependencies: $wpdb, PGM_Table_Manager, PGM_Cost_Ledger, PGM_Config.
*
* @see interface-pgm-data-collector.php — Interface this implements.
* @see class-pgm-ai-visibility-panel.php — Renders the data returned here.
* @see CONTEXT.md — Score formula + glossary.
* @see ARCHITECTURE.md — §Storage, §Score.
* @package PeptideGeoMonitor
*/
class PGM_Ai_Visibility_Collector implements PGM_Data_Collector {
/**
* @var PGM_Cost_Ledger
*/
private PGM_Cost_Ledger $ledger;
/**
* @param PGM_Cost_Ledger|null $ledger Injected for testing.
*/
public function __construct( ?PGM_Cost_Ledger $ledger = null ) {
$this->ledger = $ledger ?? new PGM_Cost_Ledger();
}
/**
* {@inheritDoc}
*
* @return array{
* trendline: array<int, array{run_id: string, captured_at: string, score: float}>,
* standings: array<string, array{label: string, cited: bool, our_position: int|null, top_domains: string[], model_count: int}>,
* last_run_at: string|null,
* mtd_cost_usd: float,
* monthly_cap_usd: float,
* }
*/
public function collect(): array {
global $wpdb;
$table = PGM_Table_Manager::get_table_name();
// ── Trendline: one score per run_id ────────────────────────────
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
$run_rows = $wpdb->get_results(
// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
"SELECT run_id, MIN(captured_at) AS captured_at,
SUM(cited) AS cited_count,
COUNT(*) AS total_count,
SUM(CASE WHEN our_position IS NOT NULL THEN 1.0/our_position ELSE 0 END) AS position_sum
FROM {$table}
GROUP BY run_id
ORDER BY MIN(captured_at) ASC
LIMIT 52",
ARRAY_A
);
$trendline = array();
foreach ( (array) $run_rows as $row ) {
$trendline[] = array(
'run_id' => (string) $row['run_id'],
'captured_at' => (string) $row['captured_at'],
'score' => $this->compute_score(
(int) $row['cited_count'],
(int) $row['total_count'],
(float) $row['position_sum']
),
);
}
// ── Standings: latest result per peptide ────────────────────────
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
$standing_rows = $wpdb->get_results(
// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
"SELECT peptide_slug, peptide_label,
MAX(cited) AS cited,
MIN(CASE WHEN cited=1 THEN our_position ELSE NULL END) AS our_position,
GROUP_CONCAT(DISTINCT source_domains ORDER BY captured_at DESC SEPARATOR '|||') AS domains_json_list,
COUNT(DISTINCT model) AS model_count
FROM {$table}
WHERE run_id = (SELECT run_id FROM {$table} ORDER BY captured_at DESC LIMIT 1)
GROUP BY peptide_slug, peptide_label",
ARRAY_A
);
$standings = array();
foreach ( (array) $standing_rows as $row ) {
$top_domains = $this->extract_top_domains( (string) ( $row['domains_json_list'] ?? '' ) );
$standings[ (string) $row['peptide_slug'] ] = array(
'label' => (string) $row['peptide_label'],
'cited' => (bool) (int) $row['cited'],
'our_position' => null !== $row['our_position'] ? (int) $row['our_position'] : null,
'top_domains' => $top_domains,
'model_count' => (int) $row['model_count'],
);
}
// ── Run metadata ────────────────────────────────────────────────
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
$last_run = $wpdb->get_var(
// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
"SELECT MAX(captured_at) FROM {$table}"
);
return array(
'trendline' => $trendline,
'standings' => $standings,
'last_run_at' => $last_run ? (string) $last_run : null,
'mtd_cost_usd' => $this->ledger->get_month_to_date_usd(),
'monthly_cap_usd' => PGM_Config::get_monthly_budget_usd(),
);
}
/**
* {@inheritDoc}
*/
public function get_key(): string {
return 'ai_visibility';
}
/**
* Compute the visibility score from a run's aggregate stats.
*
* See CONTEXT.md for the full formula explanation.
*
* @param int $cited_count Number of probes where we were cited.
* @param int $total_count Total probes in the run.
* @param float $position_sum Sum of (1/our_position) for cited probes.
*
* @return float Visibility score in range [0, 1].
*/
public function compute_score( int $cited_count, int $total_count, float $position_sum ): float {
if ( 0 === $total_count ) {
return 0.0;
}
$base_score = $cited_count / $total_count;
$position_bonus = $position_sum / $total_count;
return round( ( $base_score + $position_bonus ) / 2.0, 4 );
}
/**
* Extract and deduplicate the top domain names from a GROUP_CONCAT result.
*
* @param string $domains_json_list Pipe-separated JSON arrays from GROUP_CONCAT.
*
* @return string[] Up to 5 top domains.
*/
private function extract_top_domains( string $domains_json_list ): array {
if ( '' === $domains_json_list ) {
return array();
}
$all = array();
$chunks = explode( '|||', $domains_json_list );
foreach ( $chunks as $chunk ) {
$decoded = json_decode( $chunk, true );
if ( is_array( $decoded ) ) {
$all = array_merge( $all, $decoded );
}
}
$counts = array_count_values( $all );
arsort( $counts );
$top = array_slice( array_keys( $counts ), 0, 5 );
return array_values( array_filter( $top, fn( $d ) => PGM_TARGET_DOMAIN !== $d ) );
}
}

40
includes/collector/interface-pgm-data-collector.php Normal file
View File

@@ -0,0 +1,40 @@
<?php
declare(strict_types=1);
/**
* Seam: contract for all GEO-monitor data collectors.
*
* v1 implements only PGM_Ai_Visibility_Collector. Future collectors
* (keyword rankings, schema coverage, technical-SEO) implement this
* interface and register themselves with PGM_Collector_Registry without
* changing the dashboard shell.
*
* Who triggers: PGM_Collector_Registry dispatches registered collectors.
* Dependencies: None — pure interface.
*
* @see class-pgm-ai-visibility-collector.php — v1 implementation.
* @see class-pgm-collector-registry.php — Registration hub.
* @see ARCHITECTURE.md — §Collector/Panel seam.
* @package PeptideGeoMonitor
*/
interface PGM_Data_Collector {
/**
* Collect and return the data payload for this category.
*
* The return shape is collector-specific; the dashboard panel for this
* category receives the same array and is responsible for rendering it.
*
* @return array<string, mixed> Collected data.
*/
public function collect(): array;
/**
* Short machine key identifying this collector (e.g. "ai_visibility").
*
* Used as the registry key and as the panel lookup key.
*
* @return string
*/
public function get_key(): string;
}

32
includes/core/class-pgm-activator.php Normal file
View File

@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
/**
* Plugin activation handler.
*
* Creates the custom database table via dbDelta and registers the weekly
* WP-Cron probe schedule. Safe to call on re-activation — dbDelta is
* idempotent and the cron schedule is only added when absent.
*
* Who triggers: register_activation_hook() in peptide-geo-monitor.php.
* Dependencies: PGM_Table_Manager, PGM_Cron, PGM_Config.
*
* @see class-pgm-table-manager.php — Database schema creation.
* @see class-pgm-cron.php — Cron scheduling.
* @package PeptideGeoMonitor
*/
class PGM_Activator {
/**
* Run all activation tasks.
*
* Side effects: Creates DB table, writes default options, schedules cron.
*
* @return void
*/
public static function activate(): void {
PGM_Table_Manager::create_table();
PGM_Config::seed_defaults();
PGM_Cron::schedule_weekly();
}
}

202
includes/core/class-pgm-admin-page.php Normal file
View File

@@ -0,0 +1,202 @@
<?php
declare(strict_types=1);
/**
* GEO Monitor top-level admin page.
*
* Registers the "GEO Monitor" menu item (manage_options), enqueues Chart.js,
* handles the "Run now" POST action (nonce + capability), and delegates
* rendering to the registered panels via PGM_Collector_Registry.
*
* Who triggers: PGM_Plugin::init() → is_admin() guard.
* Dependencies: PGM_Collector_Registry, PGM_Probe_Runner.
*
* @see class-pgm-plugin.php — Calls register_hooks().
* @see class-pgm-collector-registry.php — Provides panels.
* @see class-pgm-probe-runner.php — Invoked by the Run now action.
* @see ARCHITECTURE.md — §Admin dashboard.
* @package PeptideGeoMonitor
*/
class PGM_Admin_Page {
/**
* Admin menu slug.
*/
const MENU_SLUG = 'pgm-geo-monitor';
/**
* Nonce action for the Run now form.
*/
const NONCE_ACTION = 'pgm_run_now';
/**
* Nonce field name.
*/
const NONCE_FIELD = 'pgm_nonce';
/**
* Register WordPress admin hooks.
*
* Side effects: Adds admin_menu and admin_post actions.
*
* @return void
*/
public function register_hooks(): void {
add_action( 'admin_menu', array( $this, 'add_menu_page' ) );
add_action( 'admin_post_pgm_run_now', array( $this, 'handle_run_now' ) );
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_assets' ) );
}
/**
* Add the "GEO Monitor" top-level menu page.
*
* Side effects: Adds a WP admin menu entry.
*
* @return void
*/
public function add_menu_page(): void {
add_menu_page(
__( 'GEO Monitor', 'peptide-geo-monitor' ),
__( 'GEO Monitor', 'peptide-geo-monitor' ),
'manage_options',
self::MENU_SLUG,
array( $this, 'render_page' ),
'dashicons-chart-line',
58
);
}
/**
* Enqueue Chart.js on the GEO Monitor page only.
*
* @param string $hook Current admin page hook.
*
* @return void
*/
public function enqueue_assets( string $hook ): void {
if ( false === strpos( $hook, self::MENU_SLUG ) ) {
return;
}
wp_enqueue_script(
'pgm-chartjs',
'https://cdn.jsdelivr.net/npm/chart.js@4.4.3/dist/chart.umd.min.js',
array(),
'4.4.3',
true
);
wp_add_inline_style(
'wp-admin',
'.pgm-meta-bar{display:flex;gap:20px;margin:10px 0 15px;flex-wrap:wrap;}
.pgm-meta-item{background:#f6f7f7;padding:6px 12px;border-radius:4px;font-size:13px;}
.pgm-card{background:#fff;border:1px solid #c3c4c7;padding:16px 20px;margin-bottom:20px;border-radius:4px;}
.pgm-card h2{margin-top:0;}
.pgm-proxy-note{margin:10px 0;}
.pgm-standings th,.pgm-standings td{vertical-align:middle;}
canvas#pgm-trendline-chart{max-height:300px;}'
);
}
/**
* Handle the "Run now" POST action.
*
* Validates nonce and capability before dispatching to PGM_Probe_Runner.
* Redirects back to the admin page with a status query arg.
*
* Side effects: Triggers a full probe run; redirects.
*
* @return void
*/
public function handle_run_now(): void {
if ( ! current_user_can( 'manage_options' ) ) {
wp_die( esc_html__( 'Insufficient permissions.', 'peptide-geo-monitor' ), 403 );
}
$nonce = isset( $_POST[ self::NONCE_FIELD ] ) ? sanitize_text_field( wp_unslash( $_POST[ self::NONCE_FIELD ] ) ) : '';
if ( ! wp_verify_nonce( $nonce, self::NONCE_ACTION ) ) {
wp_die( esc_html__( 'Security check failed.', 'peptide-geo-monitor' ), 403 );
}
$runner = new PGM_Probe_Runner();
$counts = $runner->run();
$redirect = add_query_arg(
array(
'page' => self::MENU_SLUG,
'pgm_run_done' => 1,
'pgm_probed' => (int) $counts['probed'],
'pgm_skipped' => (int) ( $counts['skipped_budget'] + $counts['skipped_error'] ),
),
admin_url( 'admin.php' )
);
wp_safe_redirect( $redirect );
exit;
}
/**
* Render the full GEO Monitor admin page.
*
* Side effects: Outputs HTML directly.
*
* @return void
*/
public function render_page(): void {
if ( ! current_user_can( 'manage_options' ) ) {
wp_die( esc_html__( 'Insufficient permissions.', 'peptide-geo-monitor' ) );
}
echo '<div class="wrap">';
echo '<h1>' . esc_html__( 'GEO Monitor — AI Visibility', 'peptide-geo-monitor' ) . '</h1>';
$this->render_run_done_notice();
// "Run now" button form.
echo '<form method="post" action="' . esc_url( admin_url( 'admin-post.php' ) ) . '">';
echo '<input type="hidden" name="action" value="pgm_run_now">';
wp_nonce_field( self::NONCE_ACTION, self::NONCE_FIELD );
submit_button( __( 'Run now', 'peptide-geo-monitor' ), 'secondary', 'pgm_run_now_btn', false );
echo '</form>';
$registry = PGM_Collector_Registry::instance();
foreach ( $registry->get_collectors() as $key => $collector ) {
$panel = $registry->get_panel( $key );
if ( null === $panel ) {
continue;
}
$data = $collector->collect();
$panel->render( $data );
}
echo '</div>';
}
/**
* Render a success or partial notice after a Run now redirect.
*
* @return void
*/
private function render_run_done_notice(): void {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
if ( empty( $_GET['pgm_run_done'] ) ) {
return;
}
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$probed = (int) ( $_GET['pgm_probed'] ?? 0 );
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$skipped = (int) ( $_GET['pgm_skipped'] ?? 0 );
echo '<div class="notice notice-success is-dismissible"><p>';
echo esc_html(
sprintf(
/* translators: 1: probed count, 2: skipped count */
__( 'Run complete: %1$d probes collected, %2$d skipped (budget or error).', 'peptide-geo-monitor' ),
$probed,
$skipped
)
);
echo '</p></div>';
}
}

69
includes/core/class-pgm-autoloader.php Normal file
View File

@@ -0,0 +1,69 @@
<?php
declare(strict_types=1);
/**
* Class and interface autoloader for the Peptide GEO Monitor plugin.
*
* Converts PGM_* class/interface names to file paths under includes/.
* Naming conventions:
* PGM_Foo_Bar (class) → class-pgm-foo-bar.php
* PGM_Foo_Bar (interface) → interface-pgm-foo-bar.php (tried second)
*
* Who triggers: Plugin boot (peptide-geo-monitor.php) — called once before
* any PGM_* class or interface is instantiated.
* Dependencies: None (pure PHP).
*
* @package PeptideGeoMonitor
*/
class PGM_Autoloader {
/**
* Register the autoloader with the SPL stack.
*
* @return void
*/
public static function register(): void {
spl_autoload_register( array( static::class, 'load' ) );
}
/**
* Attempt to load a PGM_* class or interface file.
*
* Walks the known include subdirectories in order, trying the class-
* filename first and the interface-filename second.
*
* Side effects: require_once on a matching file.
*
* @param string $class_name Fully-qualified class or interface name.
*
* @return void
*/
public static function load( string $class_name ): void {
if ( 0 !== strpos( $class_name, 'PGM_' ) ) {
return;
}
$slug = strtolower( str_replace( '_', '-', $class_name ) );
$search_dirs = array(
PGM_PLUGIN_DIR . 'includes/core/',
PGM_PLUGIN_DIR . 'includes/providers/',
PGM_PLUGIN_DIR . 'includes/collector/',
PGM_PLUGIN_DIR . 'includes/panel/',
PGM_PLUGIN_DIR . 'includes/',
);
// Try class file first, then interface file.
$candidates = array( 'class-' . $slug . '.php', 'interface-' . $slug . '.php' );
foreach ( $search_dirs as $dir ) {
foreach ( $candidates as $file ) {
$path = $dir . $file;
if ( file_exists( $path ) ) {
require_once $path;
return;
}
}
}
}
}

112
includes/core/class-pgm-collector-registry.php Normal file
View File

@@ -0,0 +1,112 @@
<?php
declare(strict_types=1);
/**
* Registry: holds all registered collectors and panels.
*
* PGM_Plugin::init() registers the v1 AI-visibility collector + panel.
* Future collectors/panels call register_collector()/register_panel()
* without touching the dashboard shell.
*
* Who triggers: PGM_Plugin::init() on plugins_loaded.
* Dependencies: PGM_Data_Collector, PGM_Dashboard_Panel interfaces.
*
* @see interface-pgm-data-collector.php — Collector contract.
* @see interface-pgm-dashboard-panel.php — Panel contract.
* @see class-pgm-plugin.php — Calls register_* on boot.
* @see ARCHITECTURE.md — §Collector/Panel seam.
* @package PeptideGeoMonitor
*/
class PGM_Collector_Registry {
/**
* Singleton instance.
*
* @var PGM_Collector_Registry|null
*/
private static ?PGM_Collector_Registry $instance = null;
/**
* Registered collectors keyed by their collector key.
*
* @var array<string, PGM_Data_Collector>
*/
private array $collectors = array();
/**
* Registered panels keyed by their panel key (matches collector key).
*
* @var array<string, PGM_Dashboard_Panel>
*/
private array $panels = array();
/**
* Private constructor — use instance().
*/
private function __construct() {}
/**
* Get (or create) the singleton instance.
*
* @return static
*/
public static function instance(): static {
if ( null === static::$instance ) {
static::$instance = new static();
}
return static::$instance;
}
/**
* Register a data collector.
*
* @param PGM_Data_Collector $collector
*
* @return void
*/
public function register_collector( PGM_Data_Collector $collector ): void {
$this->collectors[ $collector->get_key() ] = $collector;
}
/**
* Register a dashboard panel.
*
* @param string $key Panel key (must match a collector key).
* @param PGM_Dashboard_Panel $panel
*
* @return void
*/
public function register_panel( string $key, PGM_Dashboard_Panel $panel ): void {
$this->panels[ $key ] = $panel;
}
/**
* Get all registered collectors.
*
* @return array<string, PGM_Data_Collector>
*/
public function get_collectors(): array {
return $this->collectors;
}
/**
* Get the panel for a given key (null when not registered).
*
* @param string $key Panel key.
*
* @return PGM_Dashboard_Panel|null
*/
public function get_panel( string $key ): ?PGM_Dashboard_Panel {
return $this->panels[ $key ] ?? null;
}
/**
* Reset the registry — test use only.
*
* @internal
* @return void
*/
public static function reset_for_testing(): void {
static::$instance = null;
}
}

129
includes/core/class-pgm-config.php Normal file
View File

@@ -0,0 +1,129 @@
<?php
declare(strict_types=1);
/**
* Configuration helper: seed defaults and retrieve plugin settings.
*
* All mutable settings live in wp_options under the pgm_ prefix. This class
* provides typed getters (no magic values in call sites) and seeds the initial
* defaults on first activation.
*
* Who triggers: PGM_Activator::activate() for seeding; every component that
* needs a setting reads through here.
* Dependencies: get_option(), update_option().
*
* @see CONTEXT.md — Domain glossary: peptides, prompt intents, models.
* @see ARCHITECTURE.md — §Config (options + defaults).
* @package PeptideGeoMonitor
*/
class PGM_Config {
/**
* Seed the default option values on first activation.
*
* Uses add_option() so existing values are never overwritten on re-activation.
*
* Side effects: Writes multiple wp_options rows on first run.
*
* @return void
*/
public static function seed_defaults(): void {
add_option( 'pgm_monthly_budget_usd', PGM_DEFAULT_MONTHLY_BUDGET_USD );
add_option( 'pgm_peptides', self::default_peptides() );
add_option( 'pgm_prompt_intents', self::default_prompt_intents() );
add_option( 'pgm_models', self::default_models() );
}
/**
* Get the monthly budget cap in USD.
*
* @return float Positive float; falls back to the plugin default.
*/
public static function get_monthly_budget_usd(): float {
$val = (float) get_option( 'pgm_monthly_budget_usd', PGM_DEFAULT_MONTHLY_BUDGET_USD );
return $val > 0.0 ? $val : PGM_DEFAULT_MONTHLY_BUDGET_USD;
}
/**
* Get the list of peptide slugs/labels to probe.
*
* Each element is an associative array with 'slug' and 'label' keys.
*
* @return array<int, array{slug: string, label: string}>
*/
public static function get_peptides(): array {
$raw = get_option( 'pgm_peptides', self::default_peptides() );
return is_array( $raw ) ? $raw : self::default_peptides();
}
/**
* Get the prompt intent templates.
*
* Each string may contain {peptide} as a placeholder.
*
* @return array<int, string>
*/
public static function get_prompt_intents(): array {
$raw = get_option( 'pgm_prompt_intents', self::default_prompt_intents() );
return is_array( $raw ) ? $raw : self::default_prompt_intents();
}
/**
* Get the model identifiers to probe with.
*
* @return array<int, string>
*/
public static function get_models(): array {
$raw = get_option( 'pgm_models', self::default_models() );
return is_array( $raw ) ? $raw : self::default_models();
}
/**
* Default set of ~12 high-interest peptides (slug + human-readable label).
*
* @return array<int, array{slug: string, label: string}>
*/
private static function default_peptides(): array {
return array(
array( 'slug' => 'bpc-157', 'label' => 'BPC-157' ),
array( 'slug' => 'tb-500', 'label' => 'TB-500' ),
array( 'slug' => 'mk-677', 'label' => 'MK-677' ),
array( 'slug' => 'cjc-1295', 'label' => 'CJC-1295' ),
array( 'slug' => 'ghrp-6', 'label' => 'GHRP-6' ),
array( 'slug' => 'ipamorelin', 'label' => 'Ipamorelin' ),
array( 'slug' => 'semaglutide', 'label' => 'Semaglutide' ),
array( 'slug' => 'tirzepatide', 'label' => 'Tirzepatide' ),
array( 'slug' => 'selank', 'label' => 'Selank' ),
array( 'slug' => 'semax', 'label' => 'Semax' ),
array( 'slug' => 'nad-plus', 'label' => 'NAD+' ),
array( 'slug' => 'aod-9604', 'label' => 'AOD-9604' ),
);
}
/**
* Default prompt intent templates — three query styles per peptide.
*
* @return array<int, string>
*/
private static function default_prompt_intents(): array {
return array(
'what is {peptide}',
'{peptide} benefits and dosage',
'{peptide} reconstitution guide',
);
}
/**
* Default models: Perplexity sonar (primary citation signal) + two
* OpenRouter-routed search-capable models for breadth.
*
* @return array<int, string>
*/
private static function default_models(): array {
return array(
'perplexity/sonar',
'openai/gpt-4o-search-preview',
'google/gemini-2.0-flash-001',
);
}
}

109
includes/core/class-pgm-cost-ledger.php Normal file
View File

@@ -0,0 +1,109 @@
<?php
declare(strict_types=1);
/**
* Cost ledger: per-call logging + hard monthly budget enforcement.
*
* Every paid API call goes through record_call(). Before each call the
* runner should check can_afford() to abort gracefully at the cap without
* throwing — a partial run that respects the budget is acceptable; an
* over-spend is not.
*
* Costs are stored in the pgm_ai_visibility table (cost_usd column per row)
* and summarized by summing the current calendar month's rows. No separate
* ledger table is needed; the visibility table IS the ledger.
*
* Who triggers: PGM_Probe_Runner before and after each API call.
* Dependencies: $wpdb, PGM_Table_Manager.
*
* @see class-pgm-probe-runner.php — Calls can_afford() and record_call().
* @see class-pgm-table-manager.php — Table where cost_usd is stored.
* @see CONTEXT.md — "monthly cap" definition.
* @package PeptideGeoMonitor
*/
class PGM_Cost_Ledger {
/**
* Retrieve the total probe cost incurred in the current calendar month (UTC).
*
* Side effects: Database read.
*
* @return float Sum of cost_usd for rows in the current month, in USD.
*/
public function get_month_to_date_usd(): float {
global $wpdb;
$table = PGM_Table_Manager::get_table_name();
$month = gmdate( 'Y-m' );
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
$result = $wpdb->get_var(
$wpdb->prepare(
// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
"SELECT COALESCE(SUM(cost_usd), 0) FROM {$table} WHERE DATE_FORMAT(captured_at, %s) = %s",
'%Y-%m',
$month
)
);
return (float) $result;
}
/**
* Check whether there is remaining budget for another API call.
*
* Callers should invoke this BEFORE dispatching a probe to avoid
* overspend. Returns false when MTD spend is at or above the cap.
*
* @param float $estimated_cost_usd Estimated cost of the upcoming call.
*
* @return bool True when the call can proceed within budget.
*/
public function can_afford( float $estimated_cost_usd ): bool {
$cap = PGM_Config::get_monthly_budget_usd();
$spent = $this->get_month_to_date_usd();
return ( $spent + $estimated_cost_usd ) <= $cap;
}
/**
* Check remaining budget headroom in USD.
*
* @return float Remaining USD; 0.0 when the cap is already hit.
*/
public function get_remaining_budget_usd(): float {
$cap = PGM_Config::get_monthly_budget_usd();
$spent = $this->get_month_to_date_usd();
return max( 0.0, $cap - $spent );
}
/**
* Record a completed API call's cost against a specific row ID.
*
* Updates the cost_usd column on the row created by PGM_Probe_Runner.
* The run is already written to the table before the cost is settled so
* even partial runs (budget abort) have their completed rows costed.
*
* Side effects: Database write.
*
* @param int $row_id Primary key of the pgm_ai_visibility row.
* @param float $cost_usd Actual cost in USD.
*
* @return bool True on success.
*/
public function update_row_cost( int $row_id, float $cost_usd ): bool {
global $wpdb;
$table = PGM_Table_Manager::get_table_name();
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
$result = $wpdb->update(
$table,
array( 'cost_usd' => number_format( $cost_usd, 8, '.', '' ) ),
array( 'id' => $row_id ),
array( '%s' ),
array( '%d' )
);
return false !== $result;
}
}

82
includes/core/class-pgm-cron.php Normal file
View File

@@ -0,0 +1,82 @@
<?php
declare(strict_types=1);
/**
* WP-Cron management for the weekly AI-visibility probe.
*
* Registers the pgm_weekly_probe hook, schedules/clears the event, and
* dispatches to PGM_Probe_Runner on each tick.
*
* Who triggers: PGM_Plugin::init() (hook registration), PGM_Activator
* (schedule), PGM_Deactivator (clear).
* Dependencies: PGM_Probe_Runner.
*
* @see class-pgm-probe-runner.php — Runner invoked on each cron tick.
* @see class-pgm-activator.php — Calls schedule_weekly() on activation.
* @package PeptideGeoMonitor
*/
class PGM_Cron {
/**
* Register WordPress action hooks.
*
* Side effects: Adds action for PGM_CRON_HOOK.
*
* @return void
*/
public function register_hooks(): void {
add_action( PGM_CRON_HOOK, array( $this, 'handle_cron_tick' ) );
}
/**
* Callback fired by WP-Cron on the weekly schedule.
*
* Side effects: Instantiates and runs PGM_Probe_Runner.
*
* @return void
*/
public function handle_cron_tick(): void {
$runner = new PGM_Probe_Runner();
$runner->run();
}
/**
* Schedule the weekly cron event if not already scheduled.
*
* Safe to call on re-activation — no-op when already scheduled.
*
* Side effects: Adds a WP-Cron event.
*
* @return void
*/
public static function schedule_weekly(): void {
if ( ! wp_next_scheduled( PGM_CRON_HOOK ) ) {
wp_schedule_event( time(), 'weekly', PGM_CRON_HOOK );
}
}
/**
* Remove the weekly cron schedule.
*
* Called on deactivation. Does not purge data.
*
* Side effects: Removes the WP-Cron event.
*
* @return void
*/
public static function clear_schedule(): void {
$timestamp = wp_next_scheduled( PGM_CRON_HOOK );
if ( false !== $timestamp ) {
wp_unschedule_event( $timestamp, PGM_CRON_HOOK );
}
}
/**
* Check whether the weekly event is currently scheduled.
*
* @return bool
*/
public static function is_scheduled(): bool {
return false !== wp_next_scheduled( PGM_CRON_HOOK );
}
}

29
includes/core/class-pgm-deactivator.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
declare(strict_types=1);
/**
* Plugin deactivation handler.
*
* Clears the scheduled WP-Cron event so probes stop running when the plugin
* is deactivated. Does NOT purge data — that is uninstall's job.
*
* Who triggers: register_deactivation_hook() in peptide-geo-monitor.php.
* Dependencies: PGM_Cron.
*
* @see class-pgm-cron.php — Cron registration + clearing.
* @see uninstall.php — Full data purge on uninstall.
* @package PeptideGeoMonitor
*/
class PGM_Deactivator {
/**
* Clear the weekly cron schedule.
*
* Side effects: Removes the pgm_weekly_probe event from WP-Cron.
*
* @return void
*/
public static function deactivate(): void {
PGM_Cron::clear_schedule();
}
}

41
includes/core/class-pgm-plugin.php Normal file
View File

@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
/**
* Main orchestrator for the Peptide GEO Monitor plugin.
*
* Boots sub-systems in the correct order, hooks into WP, and keeps
* the top-level file under the 300-line limit by delegating all logic
* to specialist classes.
*
* Who triggers: plugins_loaded action (peptide-geo-monitor.php).
* Dependencies: PGM_Cron, PGM_Admin_Page, PGM_Collector_Registry.
*
* @see ARCHITECTURE.md — Boot sequence diagram.
* @package PeptideGeoMonitor
*/
class PGM_Plugin {
/**
* Wire up all WordPress hooks.
*
* Side effects: Registers admin menus, enqueues assets, and registers the
* collector/panel registry.
*
* @return void
*/
public function init(): void {
$cron = new PGM_Cron();
$cron->register_hooks();
if ( is_admin() ) {
$page = new PGM_Admin_Page();
$page->register_hooks();
}
// Register the v1 AI-visibility collector + panel.
$registry = PGM_Collector_Registry::instance();
$registry->register_collector( new PGM_Ai_Visibility_Collector() );
$registry->register_panel( 'ai_visibility', new PGM_Ai_Visibility_Panel() );
}
}

69
includes/core/class-pgm-probe-result.php Normal file
View File

@@ -0,0 +1,69 @@
<?php
declare(strict_types=1);
/**
* Value object: the result of a single LLM probe call.
*
* Returned by every PGM_Probe_Provider implementation. Immutable — all
* fields are set in the constructor and read via typed getters.
*
* Who triggers: PGM_Perplexity_Provider and PGM_OpenRouter_Provider.
* Dependencies: None.
*
* @see interface-pgm-probe-provider.php — Provider interface that returns this.
* @see class-pgm-probe-runner.php — Consumes the result for storage.
* @see CONTEXT.md — "probe result", "cited", "our_position".
* @package PeptideGeoMonitor
*/
class PGM_Probe_Result {
/**
* @param string $raw_excerpt First ~500 chars of the LLM's response.
* @param string[] $source_domains Domains extracted from the provider's citations.
* @param bool $cited Whether peptiderepo.com appears in source_domains.
* @param int|null $our_position 1-based position of peptiderepo.com in sources, or null.
* @param float $cost_usd Estimated call cost in USD.
*/
public function __construct(
private readonly string $raw_excerpt,
private readonly array $source_domains,
private readonly bool $cited,
private readonly ?int $our_position,
private readonly float $cost_usd
) {}
/**
* @return string
*/
public function get_raw_excerpt(): string {
return $this->raw_excerpt;
}
/**
* @return string[]
*/
public function get_source_domains(): array {
return $this->source_domains;
}
/**
* @return bool
*/
public function is_cited(): bool {
return $this->cited;
}
/**
* @return int|null 1-based position or null when not cited.
*/
public function get_our_position(): ?int {
return $this->our_position;
}
/**
* @return float Estimated cost in USD.
*/
public function get_cost_usd(): float {
return $this->cost_usd;
}
}

202
includes/core/class-pgm-probe-runner.php Normal file
View File

@@ -0,0 +1,202 @@
<?php
declare(strict_types=1);
/**
* Orchestrates a full probe run: peptides × intents × models.
*
* For each combination the runner:
* 1. Checks the monthly budget cap (aborts gracefully when hit).
* 2. Caches responses for identical (peptide, intent, model) within the run.
* 3. Dispatches to the correct provider (resolved from PGM_Config::get_models()).
* 4. Writes a row to the pgm_ai_visibility table.
* 5. Settles the actual cost against the ledger row.
*
* Who triggers: PGM_Cron::handle_cron_tick() and PGM_Admin_Page (Run now action).
* Dependencies: PGM_Config, PGM_Cost_Ledger, PGM_Table_Manager, all providers.
*
* @see class-pgm-cron.php — Calls run() on the weekly schedule.
* @see class-pgm-cost-ledger.php — Budget cap enforcement.
* @see class-pgm-perplexity-provider.php
* @see class-pgm-openrouter-provider.php
* @see ARCHITECTURE.md — §Probe run flow.
* @package PeptideGeoMonitor
*/
class PGM_Probe_Runner {
/**
* @var PGM_Cost_Ledger
*/
private PGM_Cost_Ledger $ledger;
/**
* In-run response cache: key = "{peptide_slug}|{intent}|{model}" → PGM_Probe_Result.
*
* @var array<string, PGM_Probe_Result>
*/
private array $cache = array();
/**
* @param PGM_Cost_Ledger|null $ledger Injected for testing; auto-created otherwise.
*/
public function __construct( ?PGM_Cost_Ledger $ledger = null ) {
$this->ledger = $ledger ?? new PGM_Cost_Ledger();
}
/**
* Execute the full probe run.
*
* Iterates peptides × prompt intents × models. Aborts at the budget cap
* without throwing — partial results are kept. Each successful probe is
* persisted immediately so a mid-run failure doesn't lose data.
*
* Side effects: HTTP calls to LLM APIs, database writes.
*
* @return array{probed: int, skipped_budget: int, skipped_error: int}
* Summary counts for the admin log.
*/
public function run(): array {
$run_id = $this->generate_run_id();
$peptides = PGM_Config::get_peptides();
$intents = PGM_Config::get_prompt_intents();
$models = PGM_Config::get_models();
$counts = array(
'probed' => 0,
'skipped_budget' => 0,
'skipped_error' => 0,
);
foreach ( $peptides as $peptide ) {
foreach ( $intents as $intent_tpl ) {
$query = str_replace( '{peptide}', $peptide['label'], $intent_tpl );
foreach ( $models as $model ) {
$provider = $this->resolve_provider( $model );
if ( null === $provider || ! $provider->is_configured() ) {
$counts['skipped_error']++;
continue;
}
// Budget pre-check.
$estimated = $this->get_estimated_cost( $model );
if ( ! $this->ledger->can_afford( $estimated ) ) {
$counts['skipped_budget']++;
continue;
}
// In-run cache check.
$cache_key = $peptide['slug'] . '|' . $intent_tpl . '|' . $model;
if ( isset( $this->cache[ $cache_key ] ) ) {
$result = $this->cache[ $cache_key ];
} else {
try {
$result = $provider->probe( $query );
$this->cache[ $cache_key ] = $result;
} catch ( \Exception $e ) {
error_log( sprintf( 'PGM: probe failed [%s / %s]: %s', $model, $peptide['slug'], $e->getMessage() ) );
$counts['skipped_error']++;
continue;
}
}
$row_id = $this->persist_result( $run_id, $peptide, $model, $intent_tpl, $result );
if ( $row_id > 0 ) {
$this->ledger->update_row_cost( $row_id, $result->get_cost_usd() );
}
$counts['probed']++;
}
}
}
$this->cache = array(); // Reset cache after run.
return $counts;
}
/**
* Persist a single probe result to the database.
*
* @param string $run_id UUID for this run.
* @param array{slug:string, label:string} $peptide Peptide config.
* @param string $model Model identifier.
* @param string $intent_tpl Raw intent template string.
* @param PGM_Probe_Result $result Probe result.
*
* @return int Inserted row ID, or 0 on failure.
*/
private function persist_result( string $run_id, array $peptide, string $model, string $intent_tpl, PGM_Probe_Result $result ): int {
global $wpdb;
$table = PGM_Table_Manager::get_table_name();
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
$wpdb->insert(
$table,
array(
'run_id' => $run_id,
'captured_at' => current_time( 'mysql', true ),
'peptide_slug' => $peptide['slug'],
'peptide_label' => $peptide['label'],
'model' => $model,
'prompt_intent' => $intent_tpl,
'cited' => $result->is_cited() ? 1 : 0,
'our_position' => $result->get_our_position(),
'source_domains' => wp_json_encode( $result->get_source_domains() ),
'raw_excerpt' => $result->get_raw_excerpt(),
'cost_usd' => number_format( $result->get_cost_usd(), 8, '.', '' ),
),
array( '%s', '%s', '%s', '%s', '%s', '%s', '%d', '%d', '%s', '%s', '%s' )
);
return (int) $wpdb->insert_id;
}
/**
* Instantiate the correct provider class for a model string.
*
* @param string $model OpenRouter model identifier.
*
* @return PGM_Probe_Provider|null Null when the model is unrecognised.
*/
private function resolve_provider( string $model ): ?PGM_Probe_Provider {
if ( 'perplexity/sonar' === $model ) {
return new PGM_Perplexity_Provider();
}
// All other models route through the generic OpenRouter provider.
return new PGM_OpenRouter_Provider( $model );
}
/**
* Conservative per-call cost estimate used for the budget pre-check.
*
* @param string $model Model identifier.
*
* @return float Estimated USD.
*/
private function get_estimated_cost( string $model ): float {
if ( 'perplexity/sonar' === $model ) {
return PGM_Perplexity_Provider::ESTIMATED_COST_PER_PROBE;
}
return PGM_OpenRouter_Provider::ESTIMATED_COST_PER_PROBE;
}
/**
* Generate a UUID v4 run identifier.
*
* @return string
*/
private function generate_run_id(): string {
return sprintf(
'%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
wp_rand( 0, 0xffff ),
wp_rand( 0, 0xffff ),
wp_rand( 0, 0xffff ),
wp_rand( 0, 0x0fff ) | 0x4000,
wp_rand( 0, 0x3fff ) | 0x8000,
wp_rand( 0, 0xffff ),
wp_rand( 0, 0xffff ),
wp_rand( 0, 0xffff )
);
}
}

94
includes/core/class-pgm-table-manager.php Normal file
View File

@@ -0,0 +1,94 @@
<?php
declare(strict_types=1);
/**
* Database table creation and schema versioning for PGM.
*
* Creates {prefix}pgm_ai_visibility via dbDelta (idempotent). Tracks the
* schema version in the pgm_schema_version option so future migrations can
* detect when an upgrade is needed without destructive ALTER TABLE.
*
* Who triggers: PGM_Activator::activate() on plugin activation.
* Dependencies: $wpdb global, dbDelta() (requires upgrade.php).
*
* @see class-pgm-activator.php — Calls create_table() on activation.
* @see ARCHITECTURE.md — §Storage.
* @package PeptideGeoMonitor
*/
class PGM_Table_Manager {
/**
* Name of the custom table (without $wpdb->prefix).
*/
const TABLE_BASE = 'pgm_ai_visibility';
/**
* Create or upgrade the AI-visibility table.
*
* Uses dbDelta to create or non-destructively alter the table.
* Records the schema version in an option afterwards.
*
* Side effects: Writes to the database; sets pgm_schema_version option.
*
* @return void
*/
public static function create_table(): void {
global $wpdb;
$table_name = $wpdb->prefix . self::TABLE_BASE;
$charset_collate = $wpdb->get_charset_collate();
$sql = "CREATE TABLE {$table_name} (
id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
run_id VARCHAR(36) NOT NULL,
captured_at DATETIME NOT NULL,
peptide_slug VARCHAR(200) NOT NULL,
peptide_label VARCHAR(200) NOT NULL,
model VARCHAR(200) NOT NULL,
prompt_intent VARCHAR(200) NOT NULL,
cited TINYINT(1) NOT NULL DEFAULT 0,
our_position INT(11) NULL DEFAULT NULL,
source_domains LONGTEXT NOT NULL DEFAULT '',
raw_excerpt LONGTEXT NOT NULL DEFAULT '',
cost_usd DECIMAL(12,8) NOT NULL DEFAULT 0.00000000,
PRIMARY KEY (id),
KEY run_id (run_id),
KEY peptide_slug (peptide_slug),
KEY captured_at (captured_at)
) {$charset_collate};";
if ( ! function_exists( 'dbDelta' ) ) {
require_once ABSPATH . 'wp-admin/includes/upgrade.php';
}
dbDelta( $sql );
update_option( 'pgm_schema_version', PGM_SCHEMA_VERSION );
}
/**
* Get the full table name including the WP prefix.
*
* @return string
*/
public static function get_table_name(): string {
global $wpdb;
return $wpdb->prefix . self::TABLE_BASE;
}
/**
* Drop the AI-visibility table entirely.
*
* Called only from uninstall.php — never during normal deactivation.
*
* Side effects: Permanently destroys all probe data.
*
* @return void
*/
public static function drop_table(): void {
global $wpdb;
$table = $wpdb->prefix . self::TABLE_BASE;
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared
$wpdb->query( "DROP TABLE IF EXISTS {$table}" );
}
}

152
includes/panel/class-pgm-ai-visibility-panel.php Normal file
View File

@@ -0,0 +1,152 @@
<?php
declare(strict_types=1);
/**
* AI-visibility dashboard panel — renders the GEO Monitor admin page.
*
* Renders four sections:
* 1. Proxy-metric disclaimer note.
* 2. Chart.js trendline of visibility score across runs.
* 3. Per-peptide standings table (cited, position, top competitor domains).
* 4. MTD cost vs cap + last-run time.
*
* All output is escaped. Chart.js is enqueued via PGM_Admin_Page.
*
* Who triggers: PGM_Admin_Page::render_page() via PGM_Collector_Registry.
* Dependencies: PGM_Ai_Visibility_Collector (data format contract).
*
* @see interface-pgm-dashboard-panel.php — Interface this implements.
* @see class-pgm-ai-visibility-collector.php — Produces the $data array.
* @see class-pgm-admin-page.php — Enqueues Chart.js; calls render().
* @package PeptideGeoMonitor
*/
class PGM_Ai_Visibility_Panel implements PGM_Dashboard_Panel {
/**
* {@inheritDoc}
*
* @param array<string, mixed> $data Payload from PGM_Ai_Visibility_Collector.
*
* @return void
*/
public function render( array $data ): void {
$trendline = is_array( $data['trendline'] ?? null ) ? $data['trendline'] : array();
$standings = is_array( $data['standings'] ?? null ) ? $data['standings'] : array();
$last_run_at = isset( $data['last_run_at'] ) && $data['last_run_at'] ? esc_html( (string) $data['last_run_at'] ) : esc_html__( 'Never', 'peptide-geo-monitor' );
$mtd_cost = isset( $data['mtd_cost_usd'] ) ? (float) $data['mtd_cost_usd'] : 0.0;
$cap = isset( $data['monthly_cap_usd'] ) ? (float) $data['monthly_cap_usd'] : PGM_DEFAULT_MONTHLY_BUDGET_USD;
$this->render_proxy_note();
$this->render_meta_bar( $last_run_at, $mtd_cost, $cap );
$this->render_trendline( $trendline );
$this->render_standings( $standings );
}
/**
* {@inheritDoc}
*/
public function get_title(): string {
return __( 'AI Visibility', 'peptide-geo-monitor' );
}
/**
* Render the proxy-metric disclaimer note.
*
* @return void
*/
private function render_proxy_note(): void {
echo '<div class="notice notice-info pgm-proxy-note"><p>';
echo '<strong>' . esc_html__( 'Note:', 'peptide-geo-monitor' ) . '</strong> ';
echo esc_html__( 'Scores are measured via API probes — a directional proxy, not the consumer ChatGPT/Gemini apps (different retrieval, personalisation, and system prompts).', 'peptide-geo-monitor' );
echo '</p></div>';
}
/**
* Render the run metadata bar (last run, cost, cap).
*
* @param string $last_run_at Formatted last-run timestamp or "Never".
* @param float $mtd_cost Month-to-date spend in USD.
* @param float $cap Monthly cap in USD.
*
* @return void
*/
private function render_meta_bar( string $last_run_at, float $mtd_cost, float $cap ): void {
$pct = $cap > 0 ? min( 100.0, round( $mtd_cost / $cap * 100, 1 ) ) : 0;
echo '<div class="pgm-meta-bar">';
echo '<span class="pgm-meta-item"><strong>' . esc_html__( 'Last run:', 'peptide-geo-monitor' ) . '</strong> ' . esc_html( $last_run_at ) . '</span>';
echo '<span class="pgm-meta-item"><strong>' . esc_html__( 'MTD cost:', 'peptide-geo-monitor' ) . '</strong> $' . esc_html( number_format( $mtd_cost, 4 ) ) . ' / $' . esc_html( number_format( $cap, 2 ) ) . ' (' . esc_html( $pct ) . '% of cap)</span>';
echo '</div>';
}
/**
* Render the Chart.js visibility score trendline.
*
* @param array<int, array{run_id: string, captured_at: string, score: float}> $trendline
*
* @return void
*/
private function render_trendline( array $trendline ): void {
echo '<div class="pgm-card"><h2>' . esc_html__( 'Visibility Score — Trend', 'peptide-geo-monitor' ) . '</h2>';
if ( empty( $trendline ) ) {
echo '<p>' . esc_html__( 'No probe runs recorded yet. Click "Run now" to collect the first data point.', 'peptide-geo-monitor' ) . '</p></div>';
return;
}
$labels = array();
$scores = array();
foreach ( $trendline as $point ) {
$labels[] = esc_js( date( 'M j', strtotime( $point['captured_at'] ) ) );
$scores[] = (float) $point['score'];
}
$labels_json = wp_json_encode( $labels );
$scores_json = wp_json_encode( $scores );
echo '<canvas id="pgm-trendline-chart" height="120"></canvas>';
echo '<script>document.addEventListener("DOMContentLoaded",function(){';
echo 'var ctx=document.getElementById("pgm-trendline-chart").getContext("2d");';
echo 'new Chart(ctx,{type:"line",data:{labels:' . $labels_json . ',datasets:[{label:"Visibility Score",data:' . $scores_json . ',borderColor:"#2271b1",tension:0.3,fill:false}]},options:{scales:{y:{min:0,max:1,title:{display:true,text:"Score"}}},plugins:{legend:{display:false}}}});';
echo '});</script>';
echo '</div>';
}
/**
* Render the per-peptide current standings table.
*
* @param array<string, array{label: string, cited: bool, our_position: int|null, top_domains: string[], model_count: int}> $standings
*
* @return void
*/
private function render_standings( array $standings ): void {
echo '<div class="pgm-card"><h2>' . esc_html__( 'Current Standings', 'peptide-geo-monitor' ) . '</h2>';
if ( empty( $standings ) ) {
echo '<p>' . esc_html__( 'No standings data yet.', 'peptide-geo-monitor' ) . '</p></div>';
return;
}
echo '<table class="wp-list-table widefat fixed striped pgm-standings">';
echo '<thead><tr>';
echo '<th>' . esc_html__( 'Peptide', 'peptide-geo-monitor' ) . '</th>';
echo '<th>' . esc_html__( 'Cited?', 'peptide-geo-monitor' ) . '</th>';
echo '<th>' . esc_html__( 'Our Position', 'peptide-geo-monitor' ) . '</th>';
echo '<th>' . esc_html__( 'Top Competing Domains', 'peptide-geo-monitor' ) . '</th>';
echo '</tr></thead><tbody>';
foreach ( $standings as $row ) {
$cited_icon = $row['cited'] ? '&#x2705;' : '&#x274C;';
$position = null !== $row['our_position'] ? '#' . (int) $row['our_position'] : '—';
$domains = implode( ', ', array_map( 'esc_html', (array) $row['top_domains'] ) );
echo '<tr>';
echo '<td>' . esc_html( (string) $row['label'] ) . '</td>';
echo '<td>' . $cited_icon . '</td>'; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- only emoji
echo '<td>' . esc_html( $position ) . '</td>';
echo '<td>' . wp_kses_post( $domains ) . '</td>';
echo '</tr>';
}
echo '</tbody></table></div>';
}
}

38
includes/panel/interface-pgm-dashboard-panel.php Normal file
View File

@@ -0,0 +1,38 @@
<?php
declare(strict_types=1);
/**
* Seam: contract for all GEO-monitor dashboard panels.
*
* Each panel renders one data category within the GEO Monitor admin page.
* v1 ships only PGM_Ai_Visibility_Panel. Future panels (keyword rankings,
* schema coverage…) implement this and register with PGM_Collector_Registry.
*
* Who triggers: PGM_Admin_Page when building the GEO Monitor page.
* Dependencies: None — pure interface.
*
* @see class-pgm-ai-visibility-panel.php — v1 implementation.
* @see class-pgm-collector-registry.php — Registration hub.
* @see ARCHITECTURE.md — §Collector/Panel seam.
* @package PeptideGeoMonitor
*/
interface PGM_Dashboard_Panel {
/**
* Render the panel HTML into the current output buffer.
*
* Implementors MUST escape all output and MUST NOT echo raw DB values.
*
* @param array<string, mixed> $data Payload returned by the matching collector.
*
* @return void
*/
public function render( array $data ): void;
/**
* Short human-readable title for the panel tab / section heading.
*
* @return string
*/
public function get_title(): string;
}

80
includes/providers/class-pgm-citation-detector.php Normal file
View File

@@ -0,0 +1,80 @@
<?php
declare(strict_types=1);
/**
* Detects whether peptiderepo.com appears in a list of source domains.
*
* Centralises the citation-detection logic so both providers can share it
* without duplication. Also parses raw citation arrays/URLs into a clean
* domain list.
*
* Who triggers: PGM_Perplexity_Provider, PGM_OpenRouter_Provider.
* Dependencies: None (pure PHP).
*
* @see CONTEXT.md — "cited", "our_position", "source_domains".
* @package PeptideGeoMonitor
*/
class PGM_Citation_Detector {
/**
* Parse raw citation data from an API response into a clean domain list.
*
* Accepts either a flat array of URL strings or an array of objects with
* a 'url' key (Perplexity style). Unknown shapes are skipped gracefully.
*
* @param array<mixed> $raw_citations Raw citations from the API response.
*
* @return string[] Lowercase domain names (e.g. ['peptiderepo.com', 'examine.com']).
*/
public function parse_domains( array $raw_citations ): array {
$domains = array();
foreach ( $raw_citations as $item ) {
$url = '';
if ( is_string( $item ) ) {
$url = $item;
} elseif ( is_array( $item ) && isset( $item['url'] ) && is_string( $item['url'] ) ) {
$url = $item['url'];
}
if ( '' === $url ) {
continue;
}
$host = (string) wp_parse_url( $url, PHP_URL_HOST );
if ( '' !== $host ) {
$domains[] = strtolower( ltrim( $host, 'www.' ) );
}
}
return array_values( array_unique( $domains ) );
}
/**
* Detect whether PGM_TARGET_DOMAIN appears in a domain list.
*
* @param string[] $domains Parsed domain list from parse_domains().
*
* @return bool
*/
public function is_cited( array $domains ): bool {
return in_array( PGM_TARGET_DOMAIN, $domains, true );
}
/**
* Find the 1-based position of PGM_TARGET_DOMAIN in a domain list.
*
* Returns null when the target domain is not found.
*
* @param string[] $domains Parsed domain list.
*
* @return int|null
*/
public function get_our_position( array $domains ): ?int {
$pos = array_search( PGM_TARGET_DOMAIN, $domains, true );
if ( false === $pos ) {
return null;
}
return (int) $pos + 1; // Convert 0-based index to 1-based position.
}
}

172
includes/providers/class-pgm-gateway-client.php Normal file
View File

@@ -0,0 +1,172 @@
<?php
declare(strict_types=1);
/**
* Cloudflare AI Gateway HTTP client — shared by all providers.
*
* Builds the gateway URL, injects the Authorization header, applies
* exponential-backoff retry, and delegates cURL auth injection (for
* hosts that strip the Authorization header) — mirroring the approach
* used in PRAutoBlogger's OpenRouter provider.
*
* Gateway URL shape:
* https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openrouter
*
* Required WP-config constants (documented in README.md):
* PGM_CF_ACCOUNT_ID — Cloudflare account ID
* PGM_CF_GATEWAY_ID — AI Gateway name (e.g. "peptiderepo-prod")
* PGM_OPENROUTER_API_KEY — OpenRouter API key (sk-or-…)
*
* Who triggers: PGM_Perplexity_Provider, PGM_OpenRouter_Provider.
* Dependencies: wp_remote_post(), add_action(), curl_setopt().
*
* @see class-pgm-perplexity-provider.php — Uses post_to_gateway().
* @see class-pgm-openrouter-provider.php — Uses post_to_gateway().
* @see ARCHITECTURE.md — §External API integrations.
* @package PeptideGeoMonitor
*/
class PGM_Gateway_Client {
/**
* Base URL for the Cloudflare AI Gateway (without trailing slash).
*/
private const GATEWAY_BASE = 'https://gateway.ai.cloudflare.com/v1';
/**
* Fallback to direct OpenRouter when the gateway is not configured.
*/
private const OPENROUTER_BASE = 'https://openrouter.ai/api/v1';
/**
* Send a chat-completion POST request through the gateway (or direct).
*
* Retries with exponential backoff on transient failures (5xx, timeout).
* Throws on permanent failure after exhausting retries.
*
* Side effects: HTTP request; logs errors to PHP error log.
*
* @param string $provider_slug Gateway provider path segment (e.g. "openrouter", "perplexity").
* @param array<string, mixed> $body JSON request body.
* @param string $api_key Bearer token.
* @param string $endpoint Path appended after the provider base (default "/chat/completions").
*
* @return array<string, mixed> Decoded JSON response body.
*
* @throws \RuntimeException On permanent HTTP failure or parse error.
*/
public function post_to_gateway( string $provider_slug, array $body, string $api_key, string $endpoint = '/chat/completions' ): array {
$base_url = $this->build_base_url( $provider_slug );
$url = $base_url . $endpoint;
$base_host = (string) wp_parse_url( $base_url, PHP_URL_HOST );
$headers = array(
'Authorization' => 'Bearer ' . $api_key,
'Content-Type' => 'application/json',
'HTTP-Referer' => home_url(),
'X-Title' => 'Peptide GEO Monitor',
);
// Belt-and-suspenders cURL injection — some hosts strip Authorization.
$curl_filter = $this->register_curl_auth_filter( $headers, $base_host );
$last_error = '';
try {
for ( $attempt = 1; $attempt <= PGM_MAX_RETRIES; $attempt++ ) {
$response = wp_remote_post(
$url,
array(
'timeout' => PGM_API_TIMEOUT_SECONDS,
'headers' => $headers,
'body' => wp_json_encode( $body ),
)
);
if ( is_wp_error( $response ) ) {
$last_error = $response->get_error_message();
if ( $attempt < PGM_MAX_RETRIES ) {
sleep( PGM_RETRY_BASE_DELAY_SECONDS * (int) pow( 2, $attempt - 1 ) );
}
continue;
}
$status = wp_remote_retrieve_response_code( $response );
$raw_body = wp_remote_retrieve_body( $response );
if ( $status >= 500 || 429 === $status ) {
$last_error = sprintf( 'HTTP %d', $status );
if ( $attempt < PGM_MAX_RETRIES ) {
$retry_after = wp_remote_retrieve_header( $response, 'retry-after' );
$delay = $retry_after ? min( (int) $retry_after, 60 ) : PGM_RETRY_BASE_DELAY_SECONDS * (int) pow( 2, $attempt - 1 );
sleep( $delay );
}
continue;
}
if ( $status >= 400 ) {
throw new \RuntimeException(
sprintf( 'GEO Monitor gateway HTTP %d: %s', $status, substr( $raw_body, 0, 300 ) )
);
}
$data = json_decode( $raw_body, true );
if ( ! is_array( $data ) ) {
throw new \RuntimeException( 'GEO Monitor: invalid JSON response from gateway.' );
}
return $data;
}
} finally {
remove_action( 'http_api_curl', $curl_filter, 99 );
}
throw new \RuntimeException(
sprintf( 'GEO Monitor: gateway failed after %d attempts. Last: %s', PGM_MAX_RETRIES, $last_error )
);
}
/**
* Build the API base URL (gateway or direct fallback).
*
* @param string $provider_slug Path segment after gateway_id (e.g. "openrouter").
*
* @return string Base URL without trailing slash.
*/
public function build_base_url( string $provider_slug ): string {
if ( defined( 'PGM_CF_ACCOUNT_ID' ) && defined( 'PGM_CF_GATEWAY_ID' )
&& '' !== PGM_CF_ACCOUNT_ID && '' !== PGM_CF_GATEWAY_ID ) {
return sprintf(
'%s/%s/%s/%s',
self::GATEWAY_BASE,
PGM_CF_ACCOUNT_ID,
PGM_CF_GATEWAY_ID,
$provider_slug
);
}
return self::OPENROUTER_BASE;
}
/**
* Register cURL auth injection filter (mirrors PRAutoBlogger pattern).
*
* @param array<string, string> $headers Request headers including Authorization.
* @param string $base_host Upstream host — limits leakage scope.
*
* @return callable The registered filter (caller MUST remove_action after request).
*/
private function register_curl_auth_filter( array $headers, string $base_host ): callable {
$filter = function ( $handle, $parsed_args, $url ) use ( $headers, $base_host ): void {
if ( '' === $base_host || false === strpos( (string) $url, $base_host ) ) {
return;
}
$curl_headers = array();
foreach ( $headers as $name => $value ) {
$curl_headers[] = $name . ': ' . $value;
}
// phpcs:ignore WordPress.WP.AlternativeFunctions.curl_curl_setopt
curl_setopt( $handle, CURLOPT_HTTPHEADER, $curl_headers );
};
add_action( 'http_api_curl', $filter, 99, 3 );
return $filter;
}
}

160
includes/providers/class-pgm-openrouter-provider.php Normal file
View File

@@ -0,0 +1,160 @@
<?php
declare(strict_types=1);
/**
* Generic OpenRouter provider — parameterised for GPT-search and Gemini-search.
*
* One class handles any OpenRouter-routed model. The model identifier is set
* at construction time; the runner instantiates one provider per model from
* PGM_Config::get_models().
*
* GPT-search (openai/gpt-4o-search-preview) and Gemini-search
* (google/gemini-2.0-flash-001) do not return a structured citations array
* via OpenRouter — citations are parsed from URLs embedded in the response
* text or from any 'annotations' key the model may include.
*
* Required WP-config constant:
* PGM_OPENROUTER_API_KEY — OpenRouter key (sk-or-…)
*
* Who triggers: PGM_Probe_Runner via PGM_Probe_Provider interface.
* Dependencies: PGM_Gateway_Client, PGM_Citation_Detector, PGM_Probe_Result.
*
* @see interface-pgm-probe-provider.php — Interface this implements.
* @see class-pgm-gateway-client.php — Shared HTTP + retry logic.
* @see class-pgm-citation-detector.php — Domain extraction + detection.
* @see ARCHITECTURE.md — §Provider implementations.
* @package PeptideGeoMonitor
*/
class PGM_OpenRouter_Provider implements PGM_Probe_Provider {
/**
* Estimated cost per probe call in USD (conservative cross-model default).
*/
const ESTIMATED_COST_PER_PROBE = 0.003;
/**
* @var string OpenRouter model identifier (e.g. "openai/gpt-4o-search-preview").
*/
private string $model;
/**
* @var PGM_Gateway_Client
*/
private PGM_Gateway_Client $gateway;
/**
* @var PGM_Citation_Detector
*/
private PGM_Citation_Detector $detector;
/**
* @param string $model OpenRouter model identifier.
* @param PGM_Gateway_Client|null $gateway Injected for testing.
* @param PGM_Citation_Detector|null $detector Injected for testing.
*/
public function __construct( string $model, ?PGM_Gateway_Client $gateway = null, ?PGM_Citation_Detector $detector = null ) {
$this->model = $model;
$this->gateway = $gateway ?? new PGM_Gateway_Client();
$this->detector = $detector ?? new PGM_Citation_Detector();
}
/**
* {@inheritDoc}
*
* @param string $query
* @return PGM_Probe_Result
* @throws \RuntimeException On permanent API failure.
*/
public function probe( string $query ): PGM_Probe_Result {
$api_key = $this->resolve_api_key();
$body = array(
'model' => $this->model,
'messages' => array(
array( 'role' => 'user', 'content' => $query ),
),
'max_tokens' => 512,
);
$data = $this->gateway->post_to_gateway( 'openrouter', $body, $api_key );
return $this->parse_response( $data );
}
/**
* Parse the OpenRouter response into a PGM_Probe_Result.
*
* Attempts to extract citations from:
* 1. `annotations` array (some models include structured source references).
* 2. URLs found inline in the response text (regex fallback).
*
* @param array<string, mixed> $data Decoded API response.
*
* @return PGM_Probe_Result
*/
public function parse_response( array $data ): PGM_Probe_Result {
$content = '';
if ( isset( $data['choices'][0]['message']['content'] ) ) {
$content = (string) $data['choices'][0]['message']['content'];
}
$raw_excerpt = mb_substr( $content, 0, 500 );
// 1. Prefer structured annotations when present.
$raw_citations = array();
if ( isset( $data['choices'][0]['message']['annotations'] ) && is_array( $data['choices'][0]['message']['annotations'] ) ) {
foreach ( $data['choices'][0]['message']['annotations'] as $ann ) {
if ( isset( $ann['url_citation']['url'] ) ) {
$raw_citations[] = $ann['url_citation']['url'];
}
}
}
// 2. Regex fallback: extract URLs from response text.
if ( empty( $raw_citations ) && '' !== $content ) {
preg_match_all( '#https?://[^\s\)\]\"\'<>]+#i', $content, $matches );
$raw_citations = $matches[0] ?? array();
}
$domains = $this->detector->parse_domains( $raw_citations );
$cited = $this->detector->is_cited( $domains );
$our_position = $this->detector->get_our_position( $domains );
// Cost estimation from usage data.
$cost_usd = self::ESTIMATED_COST_PER_PROBE;
if ( isset( $data['usage']['total_tokens'] ) ) {
// Rough blended rate ~$2/1M tokens across GPT-4o and Gemini Flash.
$cost_usd = (float) $data['usage']['total_tokens'] * 0.000002;
}
return new PGM_Probe_Result( $raw_excerpt, $domains, $cited, $our_position, $cost_usd );
}
/**
* {@inheritDoc}
*/
public function get_name(): string {
return 'OpenRouter/' . $this->model;
}
/**
* {@inheritDoc}
*/
public function is_configured(): bool {
return defined( 'PGM_OPENROUTER_API_KEY' ) && '' !== PGM_OPENROUTER_API_KEY;
}
/**
* Retrieve the OpenRouter API key from wp-config constants.
*
* @return string
* @throws \RuntimeException When the constant is not defined or empty.
*/
private function resolve_api_key(): string {
if ( ! defined( 'PGM_OPENROUTER_API_KEY' ) || '' === PGM_OPENROUTER_API_KEY ) {
throw new \RuntimeException(
__( 'PGM_OPENROUTER_API_KEY constant is not defined. Add it to wp-config.php.', 'peptide-geo-monitor' )
);
}
return PGM_OPENROUTER_API_KEY;
}
}

149
includes/providers/class-pgm-perplexity-provider.php Normal file
View File

@@ -0,0 +1,149 @@
<?php
declare(strict_types=1);
/**
* Perplexity sonar provider — primary citation signal.
*
* Routes through the Cloudflare AI Gateway (openrouter path) because
* OpenRouter proxies Perplexity models. Perplexity's sonar returns
* an explicit `citations` array — the most faithful citation signal
* available (real web retrieval vs. training-time knowledge).
*
* Required WP-config constant:
* PGM_OPENROUTER_API_KEY — OpenRouter key (sk-or-…)
*
* Who triggers: PGM_Probe_Runner via the PGM_Probe_Provider interface.
* Dependencies: PGM_Gateway_Client, PGM_Citation_Detector, PGM_Probe_Result.
*
* @see interface-pgm-probe-provider.php — Interface this implements.
* @see class-pgm-gateway-client.php — Shared HTTP + retry logic.
* @see class-pgm-citation-detector.php — Domain extraction + detection.
* @see ARCHITECTURE.md — §Provider implementations.
* @see CONTEXT.md — "Perplexity sonar", "citations".
* @package PeptideGeoMonitor
*/
class PGM_Perplexity_Provider implements PGM_Probe_Provider {
/**
* Model identifier passed to OpenRouter for Perplexity routing.
*/
const MODEL = 'perplexity/sonar';
/**
* Estimated cost per probe call in USD (sonar is ~$0.005 / 1k tokens).
* Used by the ledger's can_afford() pre-check. Actual cost settled post-call.
*/
const ESTIMATED_COST_PER_PROBE = 0.005;
/**
* @var PGM_Gateway_Client
*/
private PGM_Gateway_Client $gateway;
/**
* @var PGM_Citation_Detector
*/
private PGM_Citation_Detector $detector;
/**
* @param PGM_Gateway_Client|null $gateway Injected for testing; auto-created otherwise.
* @param PGM_Citation_Detector|null $detector Injected for testing; auto-created otherwise.
*/
public function __construct( ?PGM_Gateway_Client $gateway = null, ?PGM_Citation_Detector $detector = null ) {
$this->gateway = $gateway ?? new PGM_Gateway_Client();
$this->detector = $detector ?? new PGM_Citation_Detector();
}
/**
* {@inheritDoc}
*
* Sends the query as a user message to perplexity/sonar via OpenRouter.
* Parses the citations[] array from the OpenRouter response envelope.
*
* @param string $query
*
* @return PGM_Probe_Result
* @throws \RuntimeException On permanent API failure.
*/
public function probe( string $query ): PGM_Probe_Result {
$api_key = $this->resolve_api_key();
$body = array(
'model' => self::MODEL,
'messages' => array(
array( 'role' => 'user', 'content' => $query ),
),
'max_tokens' => 512,
);
$data = $this->gateway->post_to_gateway( 'openrouter', $body, $api_key );
return $this->parse_response( $data );
}
/**
* Parse the OpenRouter/Perplexity response into a PGM_Probe_Result.
*
* Side effects: None.
*
* @param array<string, mixed> $data Decoded API response.
*
* @return PGM_Probe_Result
*/
public function parse_response( array $data ): PGM_Probe_Result {
// Extract text excerpt from the first choice.
$content = '';
if ( isset( $data['choices'][0]['message']['content'] ) ) {
$content = (string) $data['choices'][0]['message']['content'];
}
$raw_excerpt = mb_substr( $content, 0, 500 );
// Perplexity returns citations at the top level of the response envelope.
$raw_citations = array();
if ( isset( $data['citations'] ) && is_array( $data['citations'] ) ) {
$raw_citations = $data['citations'];
}
$domains = $this->detector->parse_domains( $raw_citations );
$cited = $this->detector->is_cited( $domains );
$our_position = $this->detector->get_our_position( $domains );
// Cost from usage data when available; fall back to estimate.
$cost_usd = self::ESTIMATED_COST_PER_PROBE;
if ( isset( $data['usage']['total_tokens'] ) ) {
// Sonar: ~$1 per 1M input, $1 per 1M output tokens. Avg ~$0.001/1k.
$cost_usd = (float) $data['usage']['total_tokens'] * 0.000001;
}
return new PGM_Probe_Result( $raw_excerpt, $domains, $cited, $our_position, $cost_usd );
}
/**
* {@inheritDoc}
*/
public function get_name(): string {
return 'Perplexity sonar';
}
/**
* {@inheritDoc}
*/
public function is_configured(): bool {
return defined( 'PGM_OPENROUTER_API_KEY' ) && '' !== PGM_OPENROUTER_API_KEY;
}
/**
* Retrieve the OpenRouter API key from wp-config constants.
*
* @return string
* @throws \RuntimeException When the constant is not defined or empty.
*/
private function resolve_api_key(): string {
if ( ! defined( 'PGM_OPENROUTER_API_KEY' ) || '' === PGM_OPENROUTER_API_KEY ) {
throw new \RuntimeException(
__( 'PGM_OPENROUTER_API_KEY constant is not defined. Add it to wp-config.php.', 'peptide-geo-monitor' )
);
}
return PGM_OPENROUTER_API_KEY;
}
}

56
includes/providers/interface-pgm-probe-provider.php Normal file
View File

@@ -0,0 +1,56 @@
<?php
declare(strict_types=1);
/**
* Contract for all LLM probe providers.
*
* Each provider implementation wraps one LLM backend (Perplexity sonar,
* OpenRouter GPT-search, OpenRouter Gemini-search, …). Swapping providers
* requires only a new class — the runner, ledger, and storage are agnostic.
*
* Who triggers: PGM_Probe_Runner for each (model, query) combination.
* Dependencies: None — pure interface.
*
* @see class-pgm-perplexity-provider.php — Perplexity sonar implementation.
* @see class-pgm-openrouter-provider.php — OpenRouter generic implementation.
* @see class-pgm-probe-runner.php — Dispatches to providers via this interface.
* @see CONTEXT.md — "provider", "probe".
* @package PeptideGeoMonitor
*/
interface PGM_Probe_Provider {
/**
* Send a search/retrieval query and return a structured probe result.
*
* Implementations MUST:
* - Extract cited source domains from the model's response.
* - Detect whether PGM_TARGET_DOMAIN appears in those sources.
* - Record our 1-based position (null when not cited).
* - Return the call's estimated USD cost.
* - Throw \RuntimeException on unrecoverable failure (caller logs + skips).
*
* @param string $query The natural-language query to send.
*
* @return PGM_Probe_Result
*
* @throws \RuntimeException When the API call fails after retries.
*/
public function probe( string $query ): PGM_Probe_Result;
/**
* Get a short human-readable name for this provider (e.g. "Perplexity sonar").
*
* @return string
*/
public function get_name(): string;
/**
* Check whether the required credentials/constants are configured.
*
* Returns false (never throws) so the runner can skip unconfigured
* providers without aborting the whole run.
*
* @return bool
*/
public function is_configured(): bool;
}