thinkrank / includes / ai / class-prompt-builder.php

class-prompt-builder.php in ThinkRank AI SEO – AI SEO Plugin for WordPress: Schema, XML Sitemaps, Meta Tags, Search Console & Local SEO 1.26.0, at includes/ai/class-prompt-builder.php

388 lines 14.4 KB

Raw Download Zip

1	<?php
2	/**
3	* AI Prompt Builder Class
4	*
5	* Coordinator class that delegates to specialized prompt classes.
6	* Provides consistent interface while organizing prompts by type.
7	* Supports LLMs.txt, SEO, Site Identity, Homepage, and other AI-powered features.
8	*
9	* @package ThinkRank
10	* @subpackage AI
11	* @since 1.0.0
12	*/
13
14	declare(strict_types=1);
15
16	namespace ThinkRank\AI;
17
18	// Prevent direct access
19	if (!defined('ABSPATH')) {
20	exit;
21	}
22
23	use ThinkRank\AI\Prompts\SEO_Prompts;
24	use ThinkRank\AI\Prompts\Site_Identity_Prompts;
25	use ThinkRank\AI\Prompts\Homepage_Prompts;
26	use ThinkRank\AI\Prompts\LLMs_Txt_Prompts;
27	use ThinkRank\AI\Prompts\Content_Brief_Prompts;
28
29	/**
30	* AI Prompt Builder Class
31	*
32	* Coordinator class that delegates to specialized prompt classes.
33	* Provides consistent interface for all AI optimization prompts.
34	*
35	* @since 1.0.0
36	*/
37	class Prompt_Builder {
38
39	/**
40	* SEO Prompts instance
41	*
42	* @since 1.0.0
43	* @var SEO_Prompts\|null
44	*/
45	private ?SEO_Prompts $seo_prompts = null;
46
47	/**
48	* Site Identity Prompts instance
49	*
50	* @since 1.0.0
51	* @var Site_Identity_Prompts\|null
52	*/
53	private ?Site_Identity_Prompts $site_identity_prompts = null;
54
55	/**
56	* Homepage Prompts instance
57	*
58	* @since 1.0.0
59	* @var Homepage_Prompts\|null
60	*/
61	private ?Homepage_Prompts $homepage_prompts = null;
62
63	/**
64	* LLMs.txt Prompts instance
65	*
66	* @since 1.0.0
67	* @var LLMs_Txt_Prompts\|null
68	*/
69	private ?LLMs_Txt_Prompts $llms_txt_prompts = null;
70
71	/**
72	* Content Brief Prompts instance
73	*
74	* @since 1.0.0
75	* @var Content_Brief_Prompts\|null
76	*/
77	private ?Content_Brief_Prompts $content_brief_prompts = null;
78
79	/**
80	* Build LLMs.txt optimization prompt
81	*
82	* @since 1.0.0
83	*
84	* @param array $website_data Website data to optimize
85	* @param array $options Optimization options
86	* @param string $provider AI provider ('openai', 'claude', etc.)
87	* @return string Formatted prompt
88	*/
89	public function build_llms_txt_prompt(array $website_data, array $options = [], string $provider = 'openai'): string {
90	return $this->get_llms_txt_prompts()->build_llms_txt_prompt($website_data, $options, $provider);
91	}
92
93	/**
94	* Build SEO metadata optimization prompt
95	*
96	* @since 1.0.0
97	*
98	* @param string $content Content to optimize
99	* @param string $target_keyword Target keyword
100	* @param string $content_type Type of content
101	* @param string $tone Desired tone
102	* @param string $provider AI provider
103	* @return string Formatted prompt
104	*/
105	public function build_seo_prompt(string $content, string $target_keyword, string $content_type, string $tone, string $provider = 'openai'): string {
106	return $this->get_seo_prompts()->build_seo_prompt($content, $target_keyword, $content_type, $tone, $provider);
107	}
108
109	/**
110	* Build a focused SEO title improvement prompt.
111	*
112	* @since 1.14.0
113	*
114	* @param string $content Post content for context.
115	* @param string $current_title The current SEO title.
116	* @param string $target_keyword Target/focus keyword.
117	* @param string $content_type Type of content.
118	* @param string $tone Desired tone.
119	* @param string $suggestion The suggestion the new title must address.
120	* @param string $provider AI provider.
121	* @param array $sentiment_words Emotion/sentiment words the title check rewards.
122	* @param array $power_words Power words the title check rewards.
123	* @return string Formatted prompt
124	*/
125	public function build_title_improvement_prompt(string $content, string $current_title, string $target_keyword, string $content_type, string $tone, string $suggestion, string $provider = 'openai', array $sentiment_words = [], array $power_words = []): string {
126	return $this->get_seo_prompts()->build_title_improvement_prompt($content, $current_title, $target_keyword, $content_type, $tone, $suggestion, $provider, $sentiment_words, $power_words);
127	}
128
129	/**
130	* Build a focused meta-description improvement prompt.
131	*
132	* @since 1.14.0
133	*
134	* @param string $content Post content for context.
135	* @param string $current_desc The current meta description.
136	* @param string $target_keyword Target/focus keyword.
137	* @param string $content_type Type of content.
138	* @param string $tone Desired tone.
139	* @param string $suggestion The suggestion the description must address.
140	* @param string $provider AI provider.
141	* @return string Formatted prompt
142	*/
143	public function build_meta_description_improvement_prompt(string $content, string $current_desc, string $target_keyword, string $content_type, string $tone, string $suggestion, string $provider = 'openai'): string {
144	return $this->get_seo_prompts()->build_meta_description_improvement_prompt($content, $current_desc, $target_keyword, $content_type, $tone, $suggestion, $provider);
145	}
146
147	/**
148	* Build a prompt that explains why a specific SEO suggestion matters for a
149	* given post and how to resolve it (the "Explain with AI" copilot action).
150	*
151	* @since 1.18.0
152	*
153	* @param string $suggestion The SEO suggestion to explain.
154	* @param string $content Post content for context.
155	* @param string $title Post/SEO title for context.
156	* @param string $target_keyword Focus keyword (may be empty).
157	* @param string $content_type Type of content.
158	* @param string $provider AI provider.
159	* @return string Formatted prompt
160	*/
161	public function build_suggestion_explanation_prompt(string $suggestion, string $content, string $title, string $target_keyword, string $content_type, string $provider = 'openai'): string {
162	return $this->get_seo_prompts()->build_suggestion_explanation_prompt($suggestion, $content, $title, $target_keyword, $content_type, $provider);
163	}
164
165	/**
166	* Build a prompt proposing one authoritative external source to cite.
167	*
168	* @since 1.14.0
169	*
170	* @param string $content Post content for context.
171	* @param string $target_keyword Focus keyword.
172	* @param string $content_type Type of content.
173	* @param string $provider AI provider.
174	* @return string Formatted prompt
175	*/
176	public function build_dofollow_link_prompt(string $content, string $target_keyword, string $content_type, string $provider = 'openai'): string {
177	return $this->get_seo_prompts()->build_dofollow_link_prompt($content, $target_keyword, $content_type, $provider);
178	}
179
180	/**
181	* Build a prompt for a short keyword-rich closing paragraph.
182	*
183	* @since 1.14.0
184	*
185	* @param string $content Post content for context.
186	* @param string $target_keyword Focus keyword.
187	* @param string $content_type Type of content.
188	* @param string $tone Desired tone.
189	* @param int $keyword_mentions How many times to use the keyword.
190	* @param string $provider AI provider.
191	* @return string Formatted prompt
192	*/
193	public function build_keyword_paragraph_prompt(string $content, string $target_keyword, string $content_type, string $tone, int $keyword_mentions, string $provider = 'openai', int $word_target = 90): string {
194	return $this->get_seo_prompts()->build_keyword_paragraph_prompt($content, $target_keyword, $content_type, $tone, $keyword_mentions, $provider, $word_target);
195	}
196
197	/**
198	* Build content analysis prompt
199	*
200	* @since 1.0.0
201	*
202	* @param string $content Content to analyze
203	* @param array $metadata Existing metadata
204	* @param string $provider AI provider
205	* @return string Formatted prompt
206	*/
207	public function build_analysis_prompt(string $content, array $metadata, string $provider = 'openai'): string {
208	return $this->get_seo_prompts()->build_analysis_prompt($content, $metadata, $provider);
209	}
210
211	/**
212	* Build site identity optimization prompt
213	*
214	* @since 1.0.0
215	*
216	* @param array $site_data Site data to optimize
217	* @param string $business_type Business type
218	* @param string $target_audience Target audience
219	* @param string $tone Desired tone
220	* @param string $provider AI provider
221	* @return string Formatted prompt
222	*/
223	public function build_site_identity_prompt(array $site_data, string $business_type, string $target_audience, string $tone, string $provider = 'openai'): string {
224	return $this->get_site_identity_prompts()->build_site_identity_prompt($site_data, $business_type, $target_audience, $tone, $provider);
225	}
226
227	/**
228	* Build homepage meta optimization prompt
229	*
230	* @since 1.0.0
231	*
232	* @param array $content_data Meta content data
233	* @param string $business_type Business type
234	* @param string $target_audience Target audience
235	* @param string $tone Content tone
236	* @param array $context Additional context information
237	* @param string $provider AI provider
238	* @return string Formatted prompt
239	*/
240	public function build_homepage_meta_prompt(array $content_data, string $business_type, string $target_audience, string $tone, array $context = [], string $provider = 'openai'): string {
241	return $this->get_homepage_prompts()->build_homepage_meta_prompt($content_data, $business_type, $target_audience, $tone, $context, $provider);
242	}
243
244	/**
245	* Build homepage hero optimization prompt
246	*
247	* @since 1.0.0
248	*
249	* @param array $hero_data Hero content data
250	* @param string $business_type Business type
251	* @param string $target_audience Target audience
252	* @param string $tone Content tone
253	* @param array $context Additional context information
254	* @param string $provider AI provider
255	* @return string Formatted prompt
256	*/
257	public function build_homepage_hero_prompt(array $hero_data, string $business_type, string $target_audience, string $tone, array $context = [], string $provider = 'openai'): string {
258	return $this->get_homepage_prompts()->build_homepage_hero_prompt($hero_data, $business_type, $target_audience, $tone, $context, $provider);
259	}
260
261	/**
262	* Build content brief generation prompt
263	*
264	* @since 1.0.0
265	*
266	* @param array $target_keywords Primary and secondary keywords
267	* @param string $content_type Type of content
268	* @param string $target_audience Target audience
269	* @param string $content_length Desired content length
270	* @param string $tone Content tone
271	* @param string $competitor_analysis Pre-analyzed competitor content (or empty string)
272	* @param string $additional_context Additional context
273	* @param string $provider AI provider
274	* @return string Generated prompt
275	*/
276	public function build_content_brief_prompt(
277	array $target_keywords,
278	string $content_type,
279	string $target_audience,
280	string $content_length,
281	string $tone,
282	string $competitor_analysis,
283	string $additional_context,
284	string $provider = 'openai'
285	): string {
286	return $this->get_content_brief_prompts()->build_content_brief_prompt(
287	$target_keywords,
288	$content_type,
289	$target_audience,
290	$content_length,
291	$tone,
292	$competitor_analysis,
293	$additional_context,
294	$provider
295	);
296	}
297
298	/**
299	* Get SEO Prompts instance
300	*
301	* @since 1.0.0
302	*
303	* @return SEO_Prompts SEO Prompts instance
304	*/
305	private function get_seo_prompts(): SEO_Prompts {
306	if (!$this->seo_prompts) {
307	// Ensure SEO Prompts is loaded
308	if (!class_exists('ThinkRank\\AI\\Prompts\\SEO_Prompts')) {
309	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-seo-prompts.php';
310	}
311	$this->seo_prompts = new SEO_Prompts();
312	}
313	return $this->seo_prompts;
314	}
315
316	/**
317	* Get Site Identity Prompts instance
318	*
319	* @since 1.0.0
320	*
321	* @return Site_Identity_Prompts Site Identity Prompts instance
322	*/
323	private function get_site_identity_prompts(): Site_Identity_Prompts {
324	if (!$this->site_identity_prompts) {
325	// Ensure Site Identity Prompts is loaded
326	if (!class_exists('ThinkRank\\AI\\Prompts\\Site_Identity_Prompts')) {
327	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-site-identity-prompts.php';
328	}
329	$this->site_identity_prompts = new Site_Identity_Prompts();
330	}
331	return $this->site_identity_prompts;
332	}
333
334	/**
335	* Get Homepage Prompts instance
336	*
337	* @since 1.0.0
338	*
339	* @return Homepage_Prompts Homepage Prompts instance
340	*/
341	private function get_homepage_prompts(): Homepage_Prompts {
342	if (!$this->homepage_prompts) {
343	// Ensure Homepage Prompts is loaded
344	if (!class_exists('ThinkRank\\AI\\Prompts\\Homepage_Prompts')) {
345	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-homepage-prompts.php';
346	}
347	$this->homepage_prompts = new Homepage_Prompts();
348	}
349	return $this->homepage_prompts;
350	}
351
352	/**
353	* Get LLMs.txt Prompts instance
354	*
355	* @since 1.0.0
356	*
357	* @return LLMs_Txt_Prompts LLMs.txt Prompts instance
358	*/
359	private function get_llms_txt_prompts(): LLMs_Txt_Prompts {
360	if (!$this->llms_txt_prompts) {
361	// Ensure LLMs.txt Prompts is loaded
362	if (!class_exists('ThinkRank\\AI\\Prompts\\LLMs_Txt_Prompts')) {
363	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-llms-txt-prompts.php';
364	}
365	$this->llms_txt_prompts = new LLMs_Txt_Prompts();
366	}
367	return $this->llms_txt_prompts;
368	}
369
370	/**
371	* Get Content Brief Prompts instance
372	*
373	* @since 1.0.0
374	*
375	* @return Content_Brief_Prompts Content Brief Prompts instance
376	*/
377	private function get_content_brief_prompts(): Content_Brief_Prompts {
378	if (!$this->content_brief_prompts) {
379	// Ensure Content Brief Prompts is loaded
380	if (!class_exists('ThinkRank\\AI\\Prompts\\Content_Brief_Prompts')) {
381	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-content-brief-prompts.php';
382	}
383	$this->content_brief_prompts = new Content_Brief_Prompts();
384	}
385	return $this->content_brief_prompts;
386	}
387	}
388