"""Nonfiction generator using rigorous frameworks. Generate technical documentation using Diátaxis, Technical Manual, and Codebase Tour frameworks. """ import os from typing import Any, Optional from dotenv import load_dotenv load_dotenv() from opus_orchestrator.nonfiction_frameworks import ( NonfictionFramework, get_nonfiction_framework, ) from opus_orchestrator.utils.llm import LLMClient from opus_orchestrator.config import get_config class NonfictionGenerator: """Generate nonfiction using rigorous frameworks.""" def __init__( self, framework: NonfictionFramework = NonfictionFramework.TECHNICAL_MANUAL, topic: str = "", source_content: str = "", model: Optional[str] = None, ): """Initialize nonfiction generator. Args: framework: Nonfiction framework to use topic: Topic to document source_content: Source code/content to document model: Override model name """ self.framework = framework self.topic = topic self.source_content = source_content config = get_config() self.llm = LLMClient( provider=config.agent.provider, model=model or config.agent.model, ) self.framework_info = get_nonfiction_framework(framework) def generate(self, target_word_count: int = 5000) -> str: """Generate nonfiction document. Args: target_word_count: Target word count Returns: Generated document """ if self.framework == NonfictionFramework.CODEBASE_TOUR: return self._generate_codebase_tour(target_word_count) elif self.framework == NonfictionFramework.TECHNICAL_MANUAL: return self._generate_technical_manual(target_word_count) elif self.framework == NonfictionFramework.DIAXIS_TUTORIAL: return self._generate_diataxis_tutorial(target_word_count) elif self.framework == NonfictionFramework.DIAXIS_HOWTO: return self._generate_diataxis_howto(target_word_count) elif self.framework == NonfictionFramework.DIAXIS_EXPLANATION: return self._generate_diataxis_explanation(target_word_count) elif self.framework == NonfictionFramework.DIAXIS_REFERENCE: return self._generate_diataxis_reference(target_word_count) else: return self._generate_technical_manual(target_word_count) def _generate_codebase_tour(self, target_word_count: int) -> str: """Generate codebase tour documentation.""" source_summary = self.source_content[:10000] if self.source_content else "No source content provided" prompt = f"""Generate comprehensive CODEBASE TOUR documentation. FRAMEWORK: Codebase Tour - Document a codebase systematically TOPIC: {self.topic} SOURCE CODE/CONTENT: {source_summary} Generate the following sections: 1. Repository Overview - What is this project, what problem does it solve? 2. High-Level Architecture - System components and data flow 3. Core Components - Purpose and API of main components 4. Data Structures - Key structs and relationships 5. Core Functions - Main entry points and algorithms 6. Interfaces - How components communicate 7. Configuration - Config files and options 8. Testing - Test strategies and key files 9. Contributing - Development setup and PR process Write in a technical, precise tone. Be specific and use code examples. Target approximately {target_word_count} words. """ return self.llm.complete( system_prompt="You are an expert technical writer specializing in codebase documentation.", user_prompt=prompt, temperature=0.7, ) def _generate_technical_manual(self, target_word_count: int) -> str: """Generate technical manual.""" source_summary = self.source_content[:10000] if self.source_content else "No source content provided" prompt = f"""Generate a comprehensive TECHNICAL MANUAL. FRAMEWORK: Technical Manual - From foundations to mastery TOPIC: {self.topic} SOURCE CONTENT: {source_summary} Generate a technical manual with: 1. Introduction - Why this topic matters 2. Core Concepts - Essential background knowledge 3. Architecture - High-level system design 4. Getting Started - First steps for beginners 5. Deep Dive Sections - Detailed exploration of key topics 6. Practical Examples - Hands-on code examples 7. Best Practices - How experts do it 8. Troubleshooting - Common problems and solutions 9. Reference - API/command reference Write in a professional, thorough, practical tone. Target approximately {target_word_count} words. """ return self.llm.complete( system_prompt="You are an expert technical writer specializing in technical manuals and educational content.", user_prompt=prompt, temperature=0.7, ) def _generate_diataxis_tutorial(self, target_word_count: int) -> str: """Generate Diátaxis tutorial.""" prompt = f"""Generate a DIÁTEXIS TUTORIAL. FRAMEWORK: Tutorial - Learn by doing a concrete project TOPIC: {self.topic} Generate a tutorial that leads the learner through a complete project: 1. Introduction - What will we build and why? 2. Prerequisites - What do you need before starting? 3. Step 1: Setup - Getting the environment ready 4. Step 2: First Steps - Your initial actions 5. Step 3: Building - Creating something concrete 6. Step 4: Enhancement - Adding features 7. Step 5: Completion - Finishing the project 8. Summary - What you learned 9. Next Steps - Where to go from here Write in an encouraging, clear, patient tone. Use numbered steps. Make it achievable for beginners. Target approximately {target_word_count} words. """ return self.llm.complete( system_prompt="You are an expert technical educator specializing in tutorials.", user_prompt=prompt, temperature=0.7, ) def _generate_diataxis_howto(self, target_word_count: int) -> str: """Generate Diátaxis how-to guide.""" prompt = f"""Generate a DIÁTEXIS HOW-TO GUIDE. FRAMEWORK: How-To Guide - Accomplish a specific task TOPIC: {self.topic} Generate a practical how-to guide: 1. Goal Statement - What problem does this solve? 2. Prerequisites - What's needed? 3. Step 1 - First action 4. Step 2 - Second action 5. Step N - Final step 6. Troubleshooting - Common issues 7. Related Tasks - See also Write in a direct, authoritative tone. No fluff. Target approximately {target_word_count} words. """ return self.llm.complete( system_prompt="You are an expert technical writer specializing in how-to guides.", user_prompt=prompt, temperature=0.7, ) def _generate_diataxis_explanation(self, target_word_count: int) -> str: """Generate Diátaxis explanation.""" prompt = f"""Generate a DIÁTEXIS EXPLANATION. FRAMEWORK: Explanation - Clarify and deepen understanding TOPIC: {self.topic} Generate an explanatory document: 1. Overview - What are we exploring? 2. Background - What do you need to know first? 3. Core Concepts - The key ideas 4. How It Works - Under the hood 5. Different Approaches - Alternative perspectives 6. Why It Matters - Significance 7. Common Misconceptions - What people get wrong 8. Further Reading - Deepen knowledge Write in a thoughtful, explanatory tone. Build mental models. Target approximately {target_word_count} words. """ return self.llm.complete( system_prompt="You are an expert educator specializing in explanatory writing.", user_prompt=prompt, temperature=0.7, ) def _generate_diataxis_reference(self, target_word_count: int) -> str: """Generate Diátaxis reference.""" prompt = f"""Generate DIÁTEXIS REFERENCE documentation. FRAMEWORK: Reference - Accurate, complete information lookup TOPIC: {self.topic} Generate reference documentation: 1. Overview - What is this? 2. Syntax - How to use it 3. Parameters - What it accepts 4. Returns - What it produces 5. Examples - Usage patterns 6. Errors - What can go wrong 7. Notes - Important details 8. See Also - Related topics Write in a precise, technical, complete tone. Target approximately {target_word_count} words. """ return self.llm.complete( system_prompt="You are an expert technical writer specializing in reference documentation.", user_prompt=prompt, temperature=0.7, ) def create_nonfiction_generator( framework: NonfictionFramework = NonfictionFramework.TECHNICAL_MANUAL, topic: str = "", source_content: str = "", ) -> NonfictionGenerator: """Factory function to create a nonfiction generator.""" return NonfictionGenerator( framework=framework, topic=topic, source_content=source_content, )