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 trunk, at includes/ai/class-prompt-builder.php

393 lines 14.8 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	* @param string $language Target output language (empty = infer from content)
104	* @return string Formatted prompt
105	*/
106	public function build_seo_prompt(string $content, string $target_keyword, string $content_type, string $tone, string $provider = 'openai', string $language = ''): string {
107	return $this->get_seo_prompts()->build_seo_prompt($content, $target_keyword, $content_type, $tone, $provider, $language);
108	}
109
110	/**
111	* Build a focused SEO title improvement prompt.
112	*
113	* @since 1.14.0
114	*
115	* @param string $content Post content for context.
116	* @param string $current_title The current SEO title.
117	* @param string $target_keyword Target/focus keyword.
118	* @param string $content_type Type of content.
119	* @param string $tone Desired tone.
120	* @param string $suggestion The suggestion the new title must address.
121	* @param string $provider AI provider.
122	* @param array $sentiment_words Emotion/sentiment words the title check rewards.
123	* @param array $power_words Power words the title check rewards.
124	* @param string $language Target output language (empty = infer from content)
125	* @return string Formatted prompt
126	*/
127	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 $language = ''): string {
128	return $this->get_seo_prompts()->build_title_improvement_prompt($content, $current_title, $target_keyword, $content_type, $tone, $suggestion, $provider, $sentiment_words, $power_words, $language);
129	}
130
131	/**
132	* Build a focused meta-description improvement prompt.
133	*
134	* @since 1.14.0
135	*
136	* @param string $content Post content for context.
137	* @param string $current_desc The current meta description.
138	* @param string $target_keyword Target/focus keyword.
139	* @param string $content_type Type of content.
140	* @param string $tone Desired tone.
141	* @param string $suggestion The suggestion the description must address.
142	* @param string $provider AI provider.
143	* @param string $language Target output language (empty = infer from content)
144	* @return string Formatted prompt
145	*/
146	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 $language = ''): string {
147	return $this->get_seo_prompts()->build_meta_description_improvement_prompt($content, $current_desc, $target_keyword, $content_type, $tone, $suggestion, $provider, $language);
148	}
149
150	/**
151	* Build a prompt that explains why a specific SEO suggestion matters for a
152	* given post and how to resolve it (the "Explain with AI" copilot action).
153	*
154	* @since 1.18.0
155	*
156	* @param string $suggestion The SEO suggestion to explain.
157	* @param string $content Post content for context.
158	* @param string $title Post/SEO title for context.
159	* @param string $target_keyword Focus keyword (may be empty).
160	* @param string $content_type Type of content.
161	* @param string $provider AI provider.
162	* @return string Formatted prompt
163	*/
164	public function build_suggestion_explanation_prompt(string $suggestion, string $content, string $title, string $target_keyword, string $content_type, string $provider = 'openai'): string {
165	return $this->get_seo_prompts()->build_suggestion_explanation_prompt($suggestion, $content, $title, $target_keyword, $content_type, $provider);
166	}
167
168	/**
169	* Build a prompt proposing one authoritative external source to cite.
170	*
171	* @since 1.14.0
172	*
173	* @param string $content Post content for context.
174	* @param string $target_keyword Focus keyword.
175	* @param string $content_type Type of content.
176	* @param string $provider AI provider.
177	* @return string Formatted prompt
178	*/
179	public function build_dofollow_link_prompt(string $content, string $target_keyword, string $content_type, string $provider = 'openai'): string {
180	return $this->get_seo_prompts()->build_dofollow_link_prompt($content, $target_keyword, $content_type, $provider);
181	}
182
183	/**
184	* Build a prompt for a short keyword-rich closing paragraph.
185	*
186	* @since 1.14.0
187	*
188	* @param string $content Post content for context.
189	* @param string $target_keyword Focus keyword.
190	* @param string $content_type Type of content.
191	* @param string $tone Desired tone.
192	* @param int $keyword_mentions How many times to use the keyword.
193	* @param string $provider AI provider.
194	* @return string Formatted prompt
195	*/
196	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 {
197	return $this->get_seo_prompts()->build_keyword_paragraph_prompt($content, $target_keyword, $content_type, $tone, $keyword_mentions, $provider, $word_target);
198	}
199
200	/**
201	* Build content analysis prompt
202	*
203	* @since 1.0.0
204	*
205	* @param string $content Content to analyze
206	* @param array $metadata Existing metadata
207	* @param string $provider AI provider
208	* @return string Formatted prompt
209	*/
210	public function build_analysis_prompt(string $content, array $metadata, string $provider = 'openai'): string {
211	return $this->get_seo_prompts()->build_analysis_prompt($content, $metadata, $provider);
212	}
213
214	/**
215	* Build site identity optimization prompt
216	*
217	* @since 1.0.0
218	*
219	* @param array $site_data Site data to optimize
220	* @param string $business_type Business type
221	* @param string $target_audience Target audience
222	* @param string $tone Desired tone
223	* @param string $provider AI provider
224	* @return string Formatted prompt
225	*/
226	public function build_site_identity_prompt(array $site_data, string $business_type, string $target_audience, string $tone, string $provider = 'openai'): string {
227	return $this->get_site_identity_prompts()->build_site_identity_prompt($site_data, $business_type, $target_audience, $tone, $provider);
228	}
229
230	/**
231	* Build homepage meta optimization prompt
232	*
233	* @since 1.0.0
234	*
235	* @param array $content_data Meta content data
236	* @param string $business_type Business type
237	* @param string $target_audience Target audience
238	* @param string $tone Content tone
239	* @param array $context Additional context information
240	* @param string $provider AI provider
241	* @return string Formatted prompt
242	*/
243	public function build_homepage_meta_prompt(array $content_data, string $business_type, string $target_audience, string $tone, array $context = [], string $provider = 'openai'): string {
244	return $this->get_homepage_prompts()->build_homepage_meta_prompt($content_data, $business_type, $target_audience, $tone, $context, $provider);
245	}
246
247	/**
248	* Build homepage hero optimization prompt
249	*
250	* @since 1.0.0
251	*
252	* @param array $hero_data Hero content data
253	* @param string $business_type Business type
254	* @param string $target_audience Target audience
255	* @param string $tone Content tone
256	* @param array $context Additional context information
257	* @param string $provider AI provider
258	* @return string Formatted prompt
259	*/
260	public function build_homepage_hero_prompt(array $hero_data, string $business_type, string $target_audience, string $tone, array $context = [], string $provider = 'openai'): string {
261	return $this->get_homepage_prompts()->build_homepage_hero_prompt($hero_data, $business_type, $target_audience, $tone, $context, $provider);
262	}
263
264	/**
265	* Build content brief generation prompt
266	*
267	* @since 1.0.0
268	*
269	* @param array $target_keywords Primary and secondary keywords
270	* @param string $content_type Type of content
271	* @param string $target_audience Target audience
272	* @param string $content_length Desired content length
273	* @param string $tone Content tone
274	* @param string $competitor_analysis Pre-analyzed competitor content (or empty string)
275	* @param string $additional_context Additional context
276	* @param string $provider AI provider
277	* @return string Generated prompt
278	*/
279	public function build_content_brief_prompt(
280	array $target_keywords,
281	string $content_type,
282	string $target_audience,
283	string $content_length,
284	string $tone,
285	string $competitor_analysis,
286	string $additional_context,
287	string $provider = 'openai',
288	string $language = ''
289	): string {
290	return $this->get_content_brief_prompts()->build_content_brief_prompt(
291	$target_keywords,
292	$content_type,
293	$target_audience,
294	$content_length,
295	$tone,
296	$competitor_analysis,
297	$additional_context,
298	$provider,
299	$language
300	);
301	}
302
303	/**
304	* Get SEO Prompts instance
305	*
306	* @since 1.0.0
307	*
308	* @return SEO_Prompts SEO Prompts instance
309	*/
310	private function get_seo_prompts(): SEO_Prompts {
311	if (!$this->seo_prompts) {
312	// Ensure SEO Prompts is loaded
313	if (!class_exists('ThinkRank\\AI\\Prompts\\SEO_Prompts')) {
314	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-seo-prompts.php';
315	}
316	$this->seo_prompts = new SEO_Prompts();
317	}
318	return $this->seo_prompts;
319	}
320
321	/**
322	* Get Site Identity Prompts instance
323	*
324	* @since 1.0.0
325	*
326	* @return Site_Identity_Prompts Site Identity Prompts instance
327	*/
328	private function get_site_identity_prompts(): Site_Identity_Prompts {
329	if (!$this->site_identity_prompts) {
330	// Ensure Site Identity Prompts is loaded
331	if (!class_exists('ThinkRank\\AI\\Prompts\\Site_Identity_Prompts')) {
332	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-site-identity-prompts.php';
333	}
334	$this->site_identity_prompts = new Site_Identity_Prompts();
335	}
336	return $this->site_identity_prompts;
337	}
338
339	/**
340	* Get Homepage Prompts instance
341	*
342	* @since 1.0.0
343	*
344	* @return Homepage_Prompts Homepage Prompts instance
345	*/
346	private function get_homepage_prompts(): Homepage_Prompts {
347	if (!$this->homepage_prompts) {
348	// Ensure Homepage Prompts is loaded
349	if (!class_exists('ThinkRank\\AI\\Prompts\\Homepage_Prompts')) {
350	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-homepage-prompts.php';
351	}
352	$this->homepage_prompts = new Homepage_Prompts();
353	}
354	return $this->homepage_prompts;
355	}
356
357	/**
358	* Get LLMs.txt Prompts instance
359	*
360	* @since 1.0.0
361	*
362	* @return LLMs_Txt_Prompts LLMs.txt Prompts instance
363	*/
364	private function get_llms_txt_prompts(): LLMs_Txt_Prompts {
365	if (!$this->llms_txt_prompts) {
366	// Ensure LLMs.txt Prompts is loaded
367	if (!class_exists('ThinkRank\\AI\\Prompts\\LLMs_Txt_Prompts')) {
368	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-llms-txt-prompts.php';
369	}
370	$this->llms_txt_prompts = new LLMs_Txt_Prompts();
371	}
372	return $this->llms_txt_prompts;
373	}
374
375	/**
376	* Get Content Brief Prompts instance
377	*
378	* @since 1.0.0
379	*
380	* @return Content_Brief_Prompts Content Brief Prompts instance
381	*/
382	private function get_content_brief_prompts(): Content_Brief_Prompts {
383	if (!$this->content_brief_prompts) {
384	// Ensure Content Brief Prompts is loaded
385	if (!class_exists('ThinkRank\\AI\\Prompts\\Content_Brief_Prompts')) {
386	require_once THINKRANK_PLUGIN_DIR . 'includes/ai/prompts/class-content-brief-prompts.php';
387	}
388	$this->content_brief_prompts = new Content_Brief_Prompts();
389	}
390	return $this->content_brief_prompts;
391	}
392	}
393