import json
import logging
import re
from app.services.llm import call_llm_routed
logger = logging.getLogger(__name__)
REFERENCE_SECTIONS = [
{"key": "glossary", "label": "Glossary & Dictionary", "description": "A-Z terms and definitions", "min_entries": 20},
{"key": "history", "label": "History & Origins", "description": "How this field evolved", "min_entries": 5},
{"key": "getting_started", "label": "Getting Started Guide", "description": "Beginner's roadmap", "min_entries": 8},
{"key": "pro_tips", "label": "Pro Tips & Strategies", "description": "Expert-level techniques", "min_entries": 10},
{"key": "equipment", "label": "Equipment & Gear Guide", "description": "Reviews and recommendations", "min_entries": 8},
{"key": "statistics", "label": "Industry Statistics", "description": "Key numbers and market data", "min_entries": 8},
{"key": "formulas", "label": "Common Calculations", "description": "Quick-reference formulas and math", "min_entries": 5},
{"key": "regulations", "label": "Regulatory & Compliance", "description": "Rules, licenses, requirements", "min_entries": 5},
{"key": "community", "label": "Community Resources", "description": "Associations, forums, events", "min_entries": 8},
{"key": "faq", "label": "Frequently Asked Questions", "description": "Common questions answered", "min_entries": 10},
{"key": "media", "label": "Video & Media Resources", "description": "Curated educational content", "min_entries": 5},
{"key": "checklists", "label": "Templates & Checklists", "description": "Downloadable practical tools", "min_entries": 3},
]
SECTION_ICONS = {
"glossary": "📖",
"history": "🏛️",
"getting_started": "🚀",
"pro_tips": "💡",
"equipment": "🛠️",
"statistics": "📊",
"formulas": "🧮",
"regulations": "⚖️",
"community": "🤝",
"faq": "❓",
"media": "🎬",
"checklists": "✅",
}
DEFAULT_BRAND_COLORS = {
"primary": "#4F46E5",
"secondary": "#7C3AED",
"accent": "#06B6D4",
}
def _safe_colors(brand_colors: dict = None) -> dict:
if not brand_colors:
return DEFAULT_BRAND_COLORS.copy()
return {
"primary": brand_colors.get("primary", brand_colors.get("color_primary", DEFAULT_BRAND_COLORS["primary"])),
"secondary": brand_colors.get("secondary", brand_colors.get("color_secondary", DEFAULT_BRAND_COLORS["secondary"])),
"accent": brand_colors.get("accent", brand_colors.get("color_accent", DEFAULT_BRAND_COLORS["accent"])),
}
def _build_niche_context_block(niche_name: str, niche_data: dict) -> str:
if not niche_data:
return f'Niche: "{niche_name}"'
parts = [f'Niche Name: {niche_name}']
if niche_data.get("description"):
parts.append(f'Description: {niche_data["description"]}')
if niche_data.get("target_audience"):
parts.append(f'Target Audience: {niche_data["target_audience"]}')
if niche_data.get("monetization_model"):
parts.append(f'Monetization Model: {niche_data["monetization_model"]}')
if niche_data.get("affiliate_programs"):
parts.append(f'Affiliate Programs: {json.dumps(niche_data["affiliate_programs"])}')
if niche_data.get("synopsis"):
parts.append(f'Synopsis: {niche_data["synopsis"]}')
if niche_data.get("valuation_band"):
parts.append(f'Valuation Band: {niche_data["valuation_band"]}')
if niche_data.get("score"):
parts.append(f'Viability Score: {niche_data["score"]}/10')
return "\n".join(parts)
def _parse_json_response(response: str) -> dict:
cleaned = response.strip()
if cleaned.startswith("```"):
cleaned = cleaned.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
start = cleaned.find("{")
end = cleaned.rfind("}") + 1
if start >= 0 and end > start:
cleaned = cleaned[start:end]
try:
return json.loads(cleaned)
except json.JSONDecodeError:
cleaned = re.sub(r',\s*([}\]])', r'\1', cleaned)
try:
return json.loads(cleaned)
except json.JSONDecodeError:
logger.error(f"Failed to parse JSON response: {response[:500]}")
return {}
def generate_reference_outline(niche_name: str, niche_data: dict) -> dict:
niche_context = _build_niche_context_block(niche_name, niche_data)
sections_list = "\n".join(
[f'- key: "{s["key"]}", label: "{s["label"]}", description: "{s["description"]}", min_entries: {s["min_entries"]}'
for s in REFERENCE_SECTIONS]
)
system_prompt = (
"You are a world-class niche research analyst and encyclopedia architect. "
"You specialize in creating comprehensive, authoritative reference libraries "
"that demonstrate deep industry expertise. You never produce generic content — "
"every recommendation is specific, researched, and tailored to the exact niche. "
"Always respond with valid JSON."
)
prompt = f"""Create a detailed reference library outline for the following niche business.
NICHE CONTEXT:
{niche_context}
AVAILABLE SECTIONS:
{sections_list}
TASK:
Analyze the niche and determine which sections (8-12) are most relevant and valuable. For each selected section, provide:
1. Whether it should be included (true/false)
2. A relevance score (1-10) for this specific niche
3. A list of 5-15 specific subtopics/entries that should be covered
4. A brief rationale for why this section matters for this niche
Think about what someone entering this niche would NEED to know. What would save them weeks of research? What insider knowledge would make them look like an expert?
Return JSON in this exact format:
{{
"niche_name": "{niche_name}",
"library_title": "The Complete [Niche] Reference Library",
"library_subtitle": "A one-line description of the library's value",
"total_sections": 10,
"sections": {{
"glossary": {{
"included": true,
"relevance": 9,
"rationale": "Why this section matters for this niche",
"subtopics": ["Term 1", "Term 2", "Term 3", "..."]
}},
"history": {{
"included": true,
"relevance": 7,
"rationale": "...",
"subtopics": ["Topic 1", "Topic 2", "..."]
}}
}}
}}
Include ALL 12 section keys in your response. Set "included": false for sections that are not relevant. Ensure at least 8 sections are included.
CRITICAL: The subtopics must be SPECIFIC to the "{niche_name}" niche. Not generic business subtopics. Real, industry-specific terms, concepts, tools, regulations, and resources that demonstrate deep domain expertise."""
try:
response = call_llm_routed("site_copy", prompt, system_prompt, max_tokens=8192)
outline = _parse_json_response(response)
if not outline or "sections" not in outline:
logger.warning(f"Outline generation returned incomplete data for {niche_name}, using defaults")
outline = _build_default_outline(niche_name)
included_count = sum(1 for s in outline.get("sections", {}).values() if s.get("included"))
if included_count < 8:
for section in REFERENCE_SECTIONS:
key = section["key"]
if key not in outline.get("sections", {}):
outline.setdefault("sections", {})[key] = {
"included": True,
"relevance": 5,
"rationale": f"Standard reference section for {niche_name}",
"subtopics": [],
}
elif not outline["sections"][key].get("included"):
if included_count < 8:
outline["sections"][key]["included"] = True
included_count += 1
return outline
except Exception as e:
logger.error(f"Error generating reference outline for {niche_name}: {e}")
return _build_default_outline(niche_name)
def _build_default_outline(niche_name: str) -> dict:
sections = {}
for s in REFERENCE_SECTIONS:
sections[s["key"]] = {
"included": True,
"relevance": 7,
"rationale": f"Essential reference content for {niche_name}",
"subtopics": [],
}
return {
"niche_name": niche_name,
"library_title": f"The Complete {niche_name.replace('_', ' ').title()} Reference Library",
"library_subtitle": f"Everything you need to know about {niche_name.replace('_', ' ')}",
"total_sections": len(REFERENCE_SECTIONS),
"sections": sections,
}
def generate_reference_section(section_key: str, section_config: dict, niche_name: str, niche_data: dict, outline: dict) -> dict:
niche_context = _build_niche_context_block(niche_name, niche_data)
section_outline = outline.get("sections", {}).get(section_key, {})
subtopics = section_outline.get("subtopics", [])
subtopics_str = ", ".join(subtopics) if subtopics else "Generate appropriate subtopics"
min_entries = section_config.get("min_entries", 5)
section_specific_instructions = _get_section_instructions(section_key, niche_name, niche_data)
system_prompt = (
"You are a niche encyclopedia author with deep expertise across hundreds of industries. "
"You produce content that reads like it was written by a 20-year veteran of the industry — "
"specific, authoritative, practical, and packed with insider knowledge. "
"Every entry must have real substance. No generic advice. No filler. "
"If you mention a product, give the actual product name. If you cite a statistic, give a real number. "
"If you reference a resource, give the actual name and where to find it. "
"Always respond with valid JSON."
)
prompt = f"""Generate comprehensive reference content for the "{section_config['label']}" section of the {niche_name} Reference Library.
NICHE CONTEXT:
{niche_context}
SECTION: {section_config['label']}
SECTION DESCRIPTION: {section_config['description']}
SUGGESTED SUBTOPICS: {subtopics_str}
MINIMUM ENTRIES REQUIRED: {min_entries}
{section_specific_instructions}
QUALITY STANDARDS:
- Every entry must contain SPECIFIC, REAL information — not generic business advice
- Use actual industry terminology, real product names, real organization names
- Include actual numbers, statistics, prices, and measurements where relevant
- Content should demonstrate deep domain expertise in {niche_name}
- A reader should think "this person has been in the {niche_name} industry for years"
- Each entry should save the reader 15-30 minutes of independent research
Return JSON in this exact format:
{{
"section_key": "{section_key}",
"section_label": "{section_config['label']}",
"section_description": "A rich 2-3 sentence description of this section for {niche_name}",
"entry_count": {min_entries},
"entries": [
{{
"term": "Entry Title/Term",
"definition": "A clear, concise 1-2 sentence definition or summary",
"details": "A detailed 3-8 sentence explanation with specific facts, examples, numbers, and practical advice. This is the expanded content shown when the user clicks to read more.",
"tags": ["tag1", "tag2", "tag3"],
"related_terms": ["Related Entry 1", "Related Entry 2"],
"affiliate_opportunity": {{
"has_opportunity": true,
"program_name": "Amazon Associates / specific affiliate program",
"product_category": "What type of product/service",
"typical_commission": "5-15%",
"recommendation": "Brief recommendation text"
}},
"pro_tip": "An insider tip or lesser-known fact (optional, include when relevant)",
"source": "Citation or reference source (optional)"
}}
]
}}
Generate at least {min_entries} entries. For the glossary section, generate at least 20 entries sorted A-Z.
CRITICAL: Return ONLY valid JSON. No markdown, no code fences."""
try:
response = call_llm_routed("site_copy", prompt, system_prompt, max_tokens=16384)
section_data = _parse_json_response(response)
if not section_data or "entries" not in section_data:
logger.warning(f"Section generation returned no entries for {section_key} in {niche_name}")
section_data = {
"section_key": section_key,
"section_label": section_config["label"],
"section_description": section_config["description"],
"entry_count": 0,
"entries": [],
}
for entry in section_data.get("entries", []):
if "term" not in entry:
entry["term"] = entry.get("title", entry.get("name", "Untitled"))
if "definition" not in entry:
entry["definition"] = entry.get("summary", entry.get("description", ""))
if "details" not in entry:
entry["details"] = entry.get("content", entry.get("body", entry.get("explanation", "")))
if "tags" not in entry:
entry["tags"] = []
if "related_terms" not in entry:
entry["related_terms"] = []
if "affiliate_opportunity" not in entry:
entry["affiliate_opportunity"] = {"has_opportunity": False}
section_data["entry_count"] = len(section_data.get("entries", []))
return section_data
except Exception as e:
logger.error(f"Error generating section {section_key} for {niche_name}: {e}")
return {
"section_key": section_key,
"section_label": section_config["label"],
"section_description": section_config["description"],
"entry_count": 0,
"entries": [],
"error": str(e),
}
def _get_section_instructions(section_key: str, niche_name: str, niche_data: dict) -> str:
affiliates = niche_data.get("affiliate_programs", []) if niche_data else []
affiliates_str = ", ".join(affiliates) if affiliates else "research and suggest relevant affiliate programs"
instructions = {
"glossary": f"""GLOSSARY-SPECIFIC INSTRUCTIONS:
- Sort entries alphabetically A-Z
- Include both beginner and advanced terms
- Cover technical jargon, slang, abbreviations, and industry-specific terminology
- Each definition should be precise enough to use in a professional context
- Include pronunciation guides for uncommon terms
- Cross-reference related terms extensively""",
"history": f"""HISTORY-SPECIFIC INSTRUCTIONS:
- Cover the origin story and key milestones chronologically
- Include specific dates, names of founders/pioneers, and locations
- Highlight pivotal moments that shaped the industry
- Connect historical context to current industry state
- Include interesting facts and lesser-known history""",
"getting_started": f"""GETTING STARTED-SPECIFIC INSTRUCTIONS:
- Structure as a step-by-step roadmap from complete beginner to competent practitioner
- Include estimated time and cost for each step
- Mention specific resources, courses, or certifications by name
- Address common beginner mistakes and how to avoid them
- Include a "quick start" path for those who want to begin immediately""",
"pro_tips": f"""PRO TIPS-SPECIFIC INSTRUCTIONS:
- Focus on expert-level strategies that differentiate professionals from amateurs
- Include specific techniques with step-by-step instructions
- Reference named strategies, frameworks, or methodologies used by industry leaders
- Include "the thing most people get wrong" insights
- Each tip should provide measurable improvement or competitive advantage""",
"equipment": f"""EQUIPMENT-SPECIFIC INSTRUCTIONS:
- Include specific product names, models, and brands
- Provide price ranges (budget, mid-range, professional)
- Include affiliate opportunity data for each item: program name ({affiliates_str}), typical commission rates
- Rate items on value-for-money, durability, and performance
- Include "what to buy first" prioritization
- Mention where to buy (specific retailers, online stores)""",
"statistics": f"""STATISTICS-SPECIFIC INSTRUCTIONS:
- Include actual numbers: market size, growth rates, average revenues, participation rates
- Cite sources where possible (industry reports, government data, trade associations)
- Include year of data for currency
- Cover both macro (industry-wide) and micro (individual business) statistics
- Include trend data showing growth or decline
- Make numbers actionable — explain what they mean for someone in this niche""",
"formulas": f"""FORMULAS-SPECIFIC INSTRUCTIONS:
- Include the actual mathematical formula with variable explanations
- Provide worked examples with real numbers
- Cover pricing formulas, conversion rates, capacity calculations, ROI formulas
- Include industry-standard benchmarks for formula inputs
- Each formula should solve a real problem the target audience faces""",
"regulations": f"""REGULATIONS-SPECIFIC INSTRUCTIONS:
- Cover federal, state, and local regulations where applicable
- Include specific license names, certifying bodies, and costs
- Mention insurance requirements with typical coverage amounts
- Reference specific laws, codes, or standards by name and number
- Include compliance checklists and renewal timelines
- Note regional variations (US-focused unless niche is international)""",
"community": f"""COMMUNITY-SPECIFIC INSTRUCTIONS:
- List specific associations, organizations, and trade groups by name with URLs
- Include online communities (subreddits, forums, Facebook groups, Discord servers)
- List major industry events, conferences, and trade shows with typical dates
- Include networking opportunities and mentorship programs
- Reference industry publications, podcasts, and newsletters by name""",
"faq": f"""FAQ-SPECIFIC INSTRUCTIONS:
- Address the questions that are ACTUALLY most frequently asked (not what you think should be asked)
- Include both beginner questions and advanced questions
- Provide thorough, authoritative answers (not one-liners)
- Include "related questions" for each FAQ
- Address misconceptions and common mistakes
- Include cost-related questions that real customers/practitioners ask""",
"media": f"""MEDIA-SPECIFIC INSTRUCTIONS:
- Reference specific YouTube channels, podcasts, and online courses by name
- Include estimated course durations and whether free or paid (with prices)
- Rate resources by quality and relevance
- Include book recommendations with authors and ISBN/edition info
- Reference specific tutorial series or educational content creators
- Include documentary or educational video recommendations""",
"checklists": f"""CHECKLISTS-SPECIFIC INSTRUCTIONS:
- Create practical, actionable checklists that someone could print and use immediately
- Include startup checklists, daily operation checklists, and maintenance checklists
- Each checklist item should be specific and actionable (not vague)
- Include estimated time for completing each checklist
- Reference specific tools, forms, or resources needed for each item
- Include regulatory compliance checklists where applicable""",
}
return instructions.get(section_key, "")
def generate_full_reference_library(niche_name: str, niche_data: dict, progress_callback=None) -> dict:
if progress_callback:
progress_callback("Generating reference library outline...", 0, 1)
outline = generate_reference_outline(niche_name, niche_data)
library = {
"niche_name": niche_name,
"library_title": outline.get("library_title", f"The Complete {niche_name.replace('_', ' ').title()} Reference Library"),
"library_subtitle": outline.get("library_subtitle", ""),
"sections": {},
"metadata": {
"total_entries": 0,
"total_sections": 0,
"section_order": [],
},
}
included_sections = []
for section_config in REFERENCE_SECTIONS:
key = section_config["key"]
section_outline = outline.get("sections", {}).get(key, {})
if section_outline.get("included", True):
included_sections.append((key, section_config, section_outline))
included_sections.sort(key=lambda x: x[2].get("relevance", 5), reverse=True)
total_sections = len(included_sections)
for idx, (key, section_config, section_outline) in enumerate(included_sections):
if progress_callback:
progress_callback(
f"Generating {section_config['label']}... ({idx + 1}/{total_sections})",
idx + 1,
total_sections + 1,
)
section_data = generate_reference_section(key, section_config, niche_name, niche_data, outline)
section_data["icon"] = SECTION_ICONS.get(key, "📄")
section_data["relevance"] = section_outline.get("relevance", 5)
library["sections"][key] = section_data
library["metadata"]["total_entries"] += section_data.get("entry_count", 0)
library["metadata"]["section_order"].append(key)
library["metadata"]["total_sections"] = len(library["sections"])
if progress_callback:
progress_callback(
f"Reference library complete! {library['metadata']['total_entries']} entries across {library['metadata']['total_sections']} sections.",
total_sections + 1,
total_sections + 1,
)
return library
def render_reference_html(library: dict, brand_colors: dict = None) -> str:
colors = _safe_colors(brand_colors)
primary = colors["primary"]
secondary = colors["secondary"]
accent = colors["accent"]
title = library.get("library_title", "Reference Library")
subtitle = library.get("library_subtitle", "")
niche_name = library.get("niche_name", "")
sections = library.get("sections", {})
section_order = library.get("metadata", {}).get("section_order", list(sections.keys()))
total_entries = library.get("metadata", {}).get("total_entries", 0)
nav_items_html = ""
sections_html = ""
for key in section_order:
section = sections.get(key)
if not section:
continue
label = section.get("section_label", key.replace("_", " ").title())
icon = section.get("icon", SECTION_ICONS.get(key, "📄"))
entry_count = section.get("entry_count", 0)
entries = section.get("entries", [])
section_desc = section.get("section_description", "")
nav_items_html += f"""
{icon}{label}{entry_count}"""
letter_nav_html = ""
if key == "glossary" and entries:
letters = sorted(set(e.get("term", "?")[0].upper() for e in entries if e.get("term")))
letter_nav_html = '
'
for letter in letters:
letter_nav_html += f'{letter}'
letter_nav_html += 'All'
letter_nav_html += '
'
entries_html = ""
for i, entry in enumerate(entries):
term = _escape_html(entry.get("term", ""))
definition = _escape_html(entry.get("definition", ""))
details = _escape_html(entry.get("details", ""))
tags = entry.get("tags", [])
related = entry.get("related_terms", [])
affiliate = entry.get("affiliate_opportunity", {})
pro_tip = _escape_html(entry.get("pro_tip", ""))
source = _escape_html(entry.get("source", ""))
first_letter = term[0].upper() if term else ""
tags_html = ""
for tag in tags[:5]:
tags_html += f'{_escape_html(tag)}'
related_html = ""
if related:
related_html = '
Related: '
for r in related[:4]:
related_html += f'{_escape_html(r)}'
related_html += '