'Favor understatement. Avoid superlatives and exclamation points. Let the facts carry the sentence.', 1 => 'Mix clear, direct statements with occasional enthusiasm. Avoid extremes in either direction.', 2 => 'Write with more energy and enthusiasm. Superlatives are fine, as long as they are supported by the facts given.', ); /** * Compile a profile (or none) plus blueprint-local overrides into a * prompt block and the structured lists validators need. * * @param array|null $profile BrandProfileData, or null when no * profile is assigned. * @param array $voice_overrides BlueprintVoiceOverrides {expression, note}. * @param array $options Optional extras. Supported key: * `sectionTones` (string[]): distinct * non-empty SectionTone values active * across the units being generated, * mentioned as one extra guidance line. * @return array{block:string,banned:string[],preferred:array,claims:string[],samples:string[],expression:int} */ public function compile( ?array $profile, array $voice_overrides, array $options = array() ): array { $description = self::stringOr( $profile['description'] ?? null, '' ); $audience = self::stringOr( $profile['audience'] ?? null, '' ); $traits = self::stringListOr( $profile['traits'] ?? null ); $writing_rules = self::stringListOr( $profile['writingRules'] ?? null ); $preferred_terms = self::pairListOr( $profile['preferredTerms'] ?? null ); $avoid_phrases = self::stringListOr( $profile['avoidPhrases'] ?? null ); $approved_samples = self::stringListOr( $profile['approvedSamples'] ?? null ); $claim_rules = self::stringListOr( $profile['claimRules'] ?? null ); $profile_expression = ( null !== $profile && is_int( $profile['expression'] ?? null ) ) ? $profile['expression'] : null; $override_expression = $voice_overrides['expression'] ?? null; $expression = in_array( $override_expression, array( 0, 1, 2 ), true ) ? $override_expression : ( in_array( $profile_expression, array( 0, 1, 2 ), true ) ? $profile_expression : 1 ); $note = is_string( $voice_overrides['note'] ?? null ) ? trim( $voice_overrides['note'] ) : ''; $section_tones = self::stringListOr( $options['sectionTones'] ?? null ); $claims = array_values( array_merge( BrandProfileSchema::lockedClaims(), $claim_rules ) ); return array( 'block' => $this->buildBlock( $description, $audience, $traits, $expression, $writing_rules, $preferred_terms, $avoid_phrases, $approved_samples, $claims, $note, $section_tones ), 'banned' => $avoid_phrases, 'preferred' => $preferred_terms, 'claims' => $claims, 'samples' => $approved_samples, 'expression' => $expression, ); } /** * @param string $description Brand description. * @param string $audience Target audience. * @param string[] $traits Trait keys. * @param int $expression Resolved expression level. * @param string[] $writing_rules Writing rules. * @param array $preferred_terms {use, insteadOf} pairs. * @param string[] $avoid_phrases Avoid phrases. * @param string[] $approved_samples Approved writing samples. * @param string[] $claims Locked claims + profile claim rules. * @param string $note Blueprint-local voice note. * @param string[] $section_tones Active per-section tone nudges. * @return string */ private function buildBlock( string $description, string $audience, array $traits, int $expression, array $writing_rules, array $preferred_terms, array $avoid_phrases, array $approved_samples, array $claims, string $note, array $section_tones ): string { $lines = array(); $lines[] = 'Brand voice:'; if ( '' !== $description ) { $lines[] = 'Brand: ' . $description; } if ( '' !== $audience ) { $lines[] = 'Audience: ' . $audience; } if ( ! empty( $traits ) ) { $trait_catalog = BrandProfileSchema::traits(); $trait_labels = array(); foreach ( $traits as $trait_key ) { $trait_labels[] = $trait_catalog[ $trait_key ]['label'] ?? $trait_key; } $lines[] = 'Write with these qualities: ' . implode( ', ', $trait_labels ) . '.'; } $expression_labels = BrandProfileSchema::expressionLabels(); $expression_label = $expression_labels[ $expression ] ?? $expression_labels[1]; $expression_hint = self::EXPRESSION_GUIDANCE[ $expression ] ?? self::EXPRESSION_GUIDANCE[1]; $lines[] = 'Tone intensity: ' . $expression_label . '. ' . $expression_hint; if ( ! empty( $writing_rules ) ) { $lines[] = 'Writing rules:'; foreach ( $writing_rules as $rule ) { $lines[] = '- ' . $rule; } } if ( ! empty( $preferred_terms ) ) { $lines[] = 'Preferred terms:'; foreach ( $preferred_terms as $pair ) { if ( '' !== $pair['use'] && '' !== $pair['insteadOf'] ) { $lines[] = '- Use "' . $pair['use'] . '" instead of "' . $pair['insteadOf'] . '".'; } } } if ( ! empty( $avoid_phrases ) ) { $lines[] = 'Never use these words or phrases: ' . implode( ', ', $avoid_phrases ) . '.'; } $lines[] = 'Rules you can never override, regardless of tone or creativity:'; foreach ( $claims as $claim ) { $lines[] = '- ' . $claim; } if ( ! empty( $approved_samples ) ) { $lines[] = 'Approved writing examples (match this style, do not copy the content):'; foreach ( $approved_samples as $index => $sample ) { $lines[] = ( $index + 1 ) . '. ' . $sample; } } if ( ! empty( $section_tones ) ) { $lines[] = 'Some sections ask for an additional, local tone nudge: ' . implode( ', ', $section_tones ) . '.'; } if ( '' !== $note ) { $lines[] = 'Additional note for this blueprint: ' . $note; } return implode( "\n", $lines ); } /** * @param mixed $value Candidate value. * @param string $default Default when not a string. * @return string */ private static function stringOr( $value, string $default ): string { return is_string( $value ) ? $value : $default; } /** * @param mixed $value Candidate value. * @return string[] */ private static function stringListOr( $value ): array { if ( ! is_array( $value ) ) { return array(); } return array_values( array_filter( $value, static function ( $item ): bool { return is_string( $item ) && '' !== $item; } ) ); } /** * @param mixed $value Candidate value. * @return array */ private static function pairListOr( $value ): array { if ( ! is_array( $value ) ) { return array(); } $pairs = array(); foreach ( $value as $pair ) { if ( is_array( $pair ) ) { $pairs[] = array( 'use' => self::stringOr( $pair['use'] ?? null, '' ), 'insteadOf' => self::stringOr( $pair['insteadOf'] ?? null, '' ), ); } } return $pairs; } }