From d98ef622d9b63f7ed5811421991aed0cf7fe57ef Mon Sep 17 00:00:00 2001 From: Mark Randall Havens Date: Fri, 13 Mar 2026 20:00:30 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20Add=20nonfiction=20taxonomy=20-=20Purpo?= =?UTF-8?q?se=20=C3=97=20Structure=20matrix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Created nonfiction_taxonomy.py with: - ReaderPurpose enum (6 purposes) - StructuralPattern enum (7 patterns) - PURPOSE_STRUCTURE_MATRIX for intelligent selection - NONFICTION_FRAMEWORKS (14+ frameworks) - select_framework() function - Created docs/NONFICTION_PIPELINE.md documenting the workflow This is the foundation for Issue #16 (Nonfiction Underdeveloped) --- docs/NONFICTION_PIPELINE.md | 89 +++++ opus_orchestrator/nonfiction_taxonomy.py | 459 +++++++++++++++++++++++ 2 files changed, 548 insertions(+) create mode 100644 docs/NONFICTION_PIPELINE.md create mode 100644 opus_orchestrator/nonfiction_taxonomy.py diff --git a/docs/NONFICTION_PIPELINE.md b/docs/NONFICTION_PIPELINE.md new file mode 100644 index 0000000..661a7fe --- /dev/null +++ b/docs/NONFICTION_PIPELINE.md @@ -0,0 +1,89 @@ +# Nonfiction Generation Pipeline +# ============================== +# How the workflow CHANGES based on Purpose × Structure + +## INPUT PHASE +## ----------- +# User provides: concept, purpose (why read), category (subject), optional preferred framework +# +# Example inputs: +# - "Leadership for introverts" + PURPOSE=TRANSFORM + CATEGORY=LEADERSHIP +# - "How to code in Python" + PURPOSE=LEARN_HANDS_ON + CATEGORY=TECHNOLOGY +# - "Why nations fail" + PURPOSE=DECIDE + CATEGORY=HISTORY + +## CLASSIFICATION PHASE (NEW) +## --------------------------- +# System maps: purpose → framework families → specific framework +# +# if PURPOSE == "learn_hands_on": +# framework = select("tutorial" or "howto") +# stages = ["prerequisites", "step 1", "step 2", ...] +# +# elif PURPOSE == "transform": +# framework = select("transformation_journey" or "mountain_structure") +# stages = ["wake-up", "denial", "dark night", ...] +# +# elif PURPOSE == "decide": +# framework = select("big_idea" or "problem_solution") +# stages = ["problem", "evidence", "solution", ...] + +## SCAFFOLDING PHASE (CHANGES) +## --------------------------- +# Different STAGES based on framework +# +# TUTORIAL scaffold: +# - Introduction → Prerequisites → Step 1 → Step 2 → Step 3 → Completion → Next Steps +# +# TRANSFORMATION_JOURNEY scaffold: +# - Wake-Up → Denial → Dark Night → Realization → Path → Struggles → Breakthrough → New Normal +# +# BIG_IDEA scaffold: +# - Promise → Opposition → Evidence → Implications → Counter-Arguments → Conclusion + +## DRAFTING PHASE (CHANGES) +## ------------------------ +# Different AGENTS activated based on purpose +# +# if PURPOSE == "learn_hands_on": +# agent = "TutorialWriter" # Focus on clarity, exercises, checkpoints +# tone = "encouraging, clear, patient" +# +# elif PURPOSE == "transform": +# agent = "TransformationWriter" # Focus on emotion, narrative, inspiration +# tone = "empathetic, honest, motivational" +# +# elif PURPOSE == "decide": +# agent = "EvidenceWriter" # Focus on data, proof, credibility +# tone = "authoritative, data-driven, persuasive" + +## CRITIQUE PHASE (CHANGES) +## ------------------------ +# Different EVALUATION CRITERIA based on purpose +# +# if PURPOSE == "learn_hands_on": +# check: "Can a reader actually complete the steps?" +# check: "Are prerequisites clear?" +# check: "Is there a sense of progression?" +# +# elif PURPOSE == "transform": +# check: "Does it feel emotionally honest?" +# check: "Is the transformation arc believable?" +# check: "Would this inspire change?" +# +# elif PURPOSE == "decide": +# check: "Is the evidence credible?" +# check: "Are counter-arguments addressed?" +# check: "Does it lead to a clear recommendation?" + +## OUTPUT PHASE (CHANGES) +## ---------------------- +# Different FORMAT based on purpose +# +# if PURPOSE == "learn_hands_on": +# format = "markdown_with_code_blocks, exercises, checkpoints" +# +# elif PURPOSE == "transform": +# format = "narrative_chapters, emotional_arcs" +# +# elif PURPOSE == "reference": +# format = "indexed_sections, cross_references, searchable" diff --git a/opus_orchestrator/nonfiction_taxonomy.py b/opus_orchestrator/nonfiction_taxonomy.py new file mode 100644 index 0000000..5e8ff72 --- /dev/null +++ b/opus_orchestrator/nonfiction_taxonomy.py @@ -0,0 +1,459 @@ +"""Nonfiction Framework Taxonomy for Opus Orchestrator. + +Purpose × Structure Matrix for intelligent framework selection. + +This module provides the meta-structure for organizing nonfiction frameworks +by reader PURPOSE (why they're reading) and STRUCTURAL PATTERN (how it's organized). +""" + +from enum import Enum +from typing import Optional + + +class ReaderPurpose(str, Enum): + """Why is the reader reading this book? + + This determines the TYPE of experience and VALUE they expect. + """ + LEARN_HANDS_ON = "learn_hands_on" # "I want to DO something" + UNDERSTAND = "understand" # "I want to GRASP a concept" + TRANSFORM = "transform" # "I want to CHANGE myself" + DECIDE = "decide" # "I want to make a decision" + REFERENCE = "reference" # "I want to LOOK something up" + BE_INSPIRED = "be_inspired" # "I want to feel something" + BE_ENTERTAINED = "be_entertained" # "I want to enjoy this" + + +class StructuralPattern(str, Enum): + """How is the content ORGANIZED? + + This determines the scaffolding and flow. + """ + SEQUENTIAL = "sequential" # Step 1 → Step 2 → Step 3 + NARRATIVE = "narrative" # Beginning → Middle → End + PROBLEM_SOLUTION = "problem_solution" # Pain → Solution → Evidence + COMPARATIVE = "comparative" # A vs B, then vs now + SPIRAL = "spiral" # Simple → Complex → Simple + MODULAR = "modular" # Standalone chapters, any order + ARGUMENT = "argument" # Claim → Evidence → Rebuttal + + +class NonfictionCategory(str, Enum): + """HIGH-LEVEL SUBJECT DOMAIN + + This determines vocabulary and expertise needed. + """ + BUSINESS = "business" + LEADERSHIP = "leadership" + ENTREPRENEURSHIP = "entrepreneurship" + SELF_HELP = "self_help" + MEMOIR = "memoir" + PHILOSOPHY = "philosophy" + SCIENCE = "science" + HISTORY = "history" + TECHNOLOGY = "technology" + FINANCE = "finance" + HEALTH = "health" + RELATIONSHIPS = "relationships" + CREATIVITY = "creativity" + SPIRITUALITY = "spirituality" + HOW_TO = "how_to" + + +# ============================================================================ +# PURPOSE × STRUCTURE MATRIX +# ============================================================================ + +# This is the intelligence: which frameworks work for which purposes + +PURPOSE_STRUCTURE_MATRIX = { + ReaderPurpose.LEARN_HANDS_ON: { + "preferred_patterns": [StructuralPattern.SEQUENTIAL, StructuralPattern.SPIRAL], + "framework_families": ["tutorial", "howto", "step_by_step"], + "stage_emphasis": "exercises, practice, milestones", + }, + ReaderPurpose.UNDERSTAND: { + "preferred_patterns": [StructuralPattern.SPIRAL, StructuralPattern.COMPARATIVE], + "framework_families": ["explanation", "concept", "analogy"], + "stage_emphasis": "examples, mental models, analogies", + }, + ReaderPurpose.TRANSFORM: { + "preferred_patterns": [StructuralPattern.NARRATIVE, StructuralPattern.PROBLEM_SOLUTION], + "framework_families": ["journey", "transformation", "memoir"], + "stage_emphasis": "emotional arc, before/after, proof of change", + }, + ReaderPurpose.DECIDE: { + "preferred_patterns": [StructuralPattern.ARGUMENT, StructuralPattern.COMPARATIVE], + "framework_families": ["big_idea", "case_study", "evidence_based"], + "stage_emphasis": "data, proof, tradeoffs, recommendations", + }, + ReaderPurpose.REFERENCE: { + "preferred_patterns": [StructuralPattern.MODULAR, StructuralPattern.SEQUENTIAL], + "framework_families": ["reference", "technical_manual", "api_docs"], + "stage_emphasis": "completeness, findability, accuracy", + }, + ReaderPurpose.BE_INSPIRED: { + "preferred_patterns": [StructuralPattern.NARRATIVE, StructuralPattern.COMPARATIVE], + "framework_families": ["biography", "visionary", "manifesto"], + "stage_emphasis": "vision, emotion, memorable moments", + }, +} + + +# ============================================================================ +# FRAMEWORK DEFINITIONS +# ============================================================================ + +# Each framework has: purpose, structure, stages, prompts + +NONFICTION_FRAMEWORKS = { + # --------------------------------------------------------------------- + # LEARN_HANDS_ON (Tutorials, How-To) + # --------------------------------------------------------------------- + "tutorial": { + "name": "Tutorial", + "description": "Guided learning by doing - complete a project", + "purpose": ReaderPurpose.LEARN_HANDS_ON, + "structure": StructuralPattern.SEQUENTIAL, + "stages": [ + "Welcome - What will you build and why?", + "Prerequisites - What do you need first?", + "Setup - Get your environment ready", + "Step 1 - Your first action", + "Step 2 - Build on Step 1", + "Step 3 - Add complexity", + "Step 4 - Debug/fix issues", + "Completion - You did it!", + "Next Steps - Where to go next", + ], + "prompt_template": "Write a tutorial that leads learners through {project} to achieve {outcome}. Include specific steps, code examples, and checkpoints.", + }, + + "howto": { + "name": "How-To Guide", + "description": "Accomplish a specific goal - reader knows what they want", + "purpose": ReaderPurpose.LEARN_HANDS_ON, + "structure": StructuralPattern.SEQUENTIAL, + "stages": [ + "Before You Start - Prerequisites", + "The Method - Core approach", + "Step 1 - First action", + "Step 2 - Build on Step 1", + "Step N - Final step", + "Troubleshooting - Common issues", + "Related Tasks - See also", + ], + "prompt_template": "Write a how-to guide for {goal}. Reader already knows what they want - give them direct steps.", + }, + + # --------------------------------------------------------------------- + # UNDERSTAND (Explanations, Concepts) + # --------------------------------------------------------------------- + "concept_explainer": { + "name": "Concept Explainer", + "description": "Build deep understanding through analogies and examples", + "purpose": ReaderPurpose.UNDERSTAND, + "structure": StructuralPattern.SPIRAL, + "stages": [ + "The Hook - Why this matters", + "What It Is - Simple definition", + "The Mental Model - Analogy for understanding", + "How It Works - Mechanism", + "Why It Works - Deep dive", + "Common Misconceptions - What people get wrong", + "Real Examples - Case studies", + "Connected Ideas - Related concepts", + ], + "prompt_template": "Explain {concept} to a reader who wants to truly understand it. Use vivid analogies, counterexamples, and build a mental model.", + }, + + "compare_contrast": { + "name": "Compare & Contrast", + "description": "Understand by comparing alternatives", + "purpose": ReaderPurpose.UNDERSTAND, + "structure": StructuralPattern.COMPARATIVE, + "stages": [ + "The Question - Why compare these?", + "Option A - Deep dive", + "Option B - Deep dive", + "Side-by-Side - Direct comparison table", + "Trade-offs - What you gain/lose with each", + "Recommendation - When to choose what", + ], + "prompt_template": "Compare {option_a} vs {option_b}. Help reader understand differences deeply and choose wisely.", + }, + + # --------------------------------------------------------------------- + # TRANSFORM (Self-Help, Memoir) + # --------------------------------------------------------------------- + "transformation_journey": { + "name": "Transformation Journey", + "description": "Take reader from stuck to transformed", + "purpose": ReaderPurpose.TRANSFORM, + "structure": StructuralPattern.NARRATIVE, + "stages": [ + "The Wake-Up - Recognize the problem", + "Denial - Why we resist change", + "The Dark Night - Lowest point", + "The Realization - Key insight", + "The Path - How to change", + "Struggles & Setbacks - Realistic journey", + "Breakthrough - The shift", + "New Normal - How life is different", + "Call to Action - Start now", + ], + "prompt_template": "Write a transformation narrative that helps readers go from {stuck_state} to {transformed_state}. Include emotional honesty and practical steps.", + }, + + "mountain_structure": { + "name": "Mountain Structure", + "description": "Classic narrative arc - normal → crisis → resolution", + "purpose": ReaderPurpose.TRANSFORM, + "structure": StructuralPattern.NARRATIVE, + "stages": [ + "Ordinary World - Life before", + "The Call - Something changes", + "Refusal - Why resist", + "Crossing the Threshold - Commitment", + "Tests and Allies - Who helps", + "The Ordeal - Biggest challenge", + "The Reward - What was gained", + "The Road Back - Bringing it home", + "Return with Elixir - Changed person", + ], + "prompt_template": "Write using the hero's journey structure applied to {topic}. Make it emotionally resonant and transformation-focused.", + }, + + "atomic_habits_style": { + "name": "Atomic Habits Framework", + "description": "Identity-based habit change", + "purpose": ReaderPurpose.TRANSFORM, + "structure": StructuralPattern.SEQUENTIAL, + "stages": [ + "The Surprising Power of Atomic Habits", + "The First Law - Make it Obvious", + "The Second Law - Make it Attractive", + "The Third Law - Make it Easy", + "The Fourth Law - Make it Satisfying", + "Advanced Tactics - Habit stacking, temptation bundling", + "The Inside Story - How it really works", + "The Outer World - How to make it stick", + ], + "prompt_template": "Write a habit-change book using identity-based framework. Focus on small changes that compound into big transformation.", + }, + + # --------------------------------------------------------------------- + # DECIDE (Business, Leadership) + # --------------------------------------------------------------------- + "big_idea": { + "name": "Big Idea Framework", + "description": "One core insight, proven thoroughly", + "purpose": ReaderPurpose.DECIDE, + "structure": StructuralPattern.ARGUMENT, + "stages": [ + "The Captivating Promise - What's the big idea?", + "The Opposition - What does conventional wisdom say?", + "The Evidence - Proof from multiple sources", + "The Implications - What does this mean?", + "The Counter-Arguments - Address skeptics", + "The Conclusion - What to do now", + ], + "prompt_template": "Present the big idea: {idea}. Challenge conventional wisdom, provide compelling evidence, lead to action.", + }, + + "problem_solution": { + "name": "Problem-Solution Framework", + "description": "Pain → Solution → Proof → Action", + "purpose": ReaderPurpose.DECIDE, + "structure": StructuralPattern.PROBLEM_SOLUTION, + "stages": [ + "The Problem - Paint the pain vividly", + "The Root Cause - Why it's happening", + "The Solution - Your methodology", + "The Evidence - Case studies and data", + "The Transformation - Before and after", + "The Call to Action - What to do now", + ], + "prompt_template": "Write a problem-solution book. Make the pain real, present your solution with proof, drive to action.", + }, + + "case_study": { + "name": "Case Study Collection", + "description": "Real examples prove the point", + "purpose": ReaderPurpose.DECIDE, + "structure": StructuralPattern.COMPARATIVE, + "stages": [ + "The Question - What are we exploring?", + "Case 1 - Deep dive", + "Case 2 - Deep dive", + "Case 3 - Deep dive", + "Patterns - What worked and why", + "Framework - Generalizable principles", + "Application - How to apply", + ], + "prompt_template": "Build your argument through {n} detailed case studies. Let real examples prove your point.", + }, + + # --------------------------------------------------------------------- + # REFERENCE (Technical) + # --------------------------------------------------------------------- + "diataxis_tutorial": { + "name": "Diátaxis Tutorial", + "description": "Learn by doing a project", + "purpose": ReaderPurpose.LEARN_HANDS_ON, + "structure": StructuralPattern.SEQUENTIAL, + "stages": [ + "Introduction - What will we build?", + "Prerequisites - What you need", + "Step 1: Setup", + "Step 2: First steps", + "Step 3: Building", + "Step 4: Enhancing", + "Step 5: Completion", + "Summary", + "Next Steps", + ], + }, + + "diataxis_howto": { + "name": "Diátaxis How-To", + "description": "Accomplish a specific task", + "purpose": ReaderPurpose.LEARN_HANDS_ON, + "structure": StructuralPattern.SEQUENTIAL, + "stages": [ + "Goal Statement", + "Prerequisites", + "Step 1", "Step 2", "Step N", + "Troubleshooting", + "Related Tasks", + ], + }, + + "diataxis_explanation": { + "name": "Diátaxis Explanation", + "description": "Deep understanding of a topic", + "purpose": ReaderPurpose.UNDERSTAND, + "structure": StructuralPattern.SPIRAL, + "stages": [ + "Overview", + "Background", + "Core Concepts", + "How It Works", + "Different Approaches", + "Why It Matters", + "Common Misconceptions", + "Further Reading", + ], + }, + + "diataxis_reference": { + "name": "Diátaxis Reference", + "description": "Complete, accurate reference", + "purpose": ReaderPurpose.REFERENCE, + "structure": StructuralPattern.MODULAR, + "stages": [ + "Overview", + "Syntax", + "Parameters", + "Returns", + "Examples", + "Errors", + "Notes", + "See Also", + ], + }, +} + + +# ============================================================================ +# THE INTELLIGENT SELECTOR +# ============================================================================ + +def select_framework( + purpose: ReaderPurpose, + category: Optional[NonfictionCategory] = None, + user_preferred_framework: Optional[str] = None, +) -> dict: + """Intelligently select the best framework based on purpose and category. + + Args: + purpose: Why is the reader reading? + category: What domain? (optional - for vocabulary) + user_preferred_framework: User explicitly chose one + + Returns: + Framework definition with prompts and stages + """ + # If user specified, try to use it + if user_preferred_framework and user_preferred_framework in NONFICTION_FRAMEWORKS: + return NONFICTION_FRAMEWORKS[user_preferred_framework] + + # Otherwise, use the matrix to select + if purpose not in PURPOSE_STRUCTURE_MATRIX: + # Default fallback + return NONFICTION_FRAMEWORKS["concept_explainer"] + + matrix_entry = PURPOSE_STRUCTURE_MATRIX[purpose] + framework_families = matrix_entry["framework_families"] + + # Find best match + for family in framework_families: + for key, fw in NONFICTION_FRAMEWORKS.items(): + if family.lower() in fw.get("name", "").lower(): + return fw + + # Ultimate fallback + return NONFICTION_FRAMEWORKS["concept_explainer"] + + +def get_frameworks_for_purpose(purpose: ReaderPurpose) -> list[dict]: + """Get all frameworks that work for a purpose.""" + if purpose not in PURPOSE_STRUCTURE_MATRIX: + return [] + + matrix_entry = PURPOSE_STRUCTURE_MATRIX[purpose] + families = matrix_entry["framework_families"] + + results = [] + for key, fw in NONFICTION_FRAMEWORKS.items(): + if any(f in fw.get("name", "").lower() for f in families): + results.append({"id": key, **fw}) + + return results + + +def describe_purpose(purpose: ReaderPurpose) -> dict: + """Get description of what a purpose means for the reader.""" + descriptions = { + ReaderPurpose.LEARN_HANDS_ON: { + "reader_thinks": "I want to DO something specific", + "value_received": "Skills I can use immediately", + "emotion": "Accomplished, capable", + "length_typical": "Short to medium (5-30k words)", + }, + ReaderPurpose.UNDERSTAND: { + "reader_thinks": "I want to GRASP how something works", + "value_received": "Mental models and deep understanding", + "emotion": "Enlightened, informed", + "length_typical": "Medium (20-60k words)", + }, + ReaderPurpose.TRANSFORM: { + "reader_thinks": "I want to CHANGE myself or my life", + "value_received": "A path to becoming different", + "emotion": "Hopeful, motivated, understood", + "length_typical": "Medium to long (30-80k words)", + }, + ReaderPurpose.DECIDE: { + "reader_thinks": "I need to make a decision or choice", + "value_received": "Clarity and confidence in choice", + "emotion": "Empowered, informed", + "length_typical": "Short to medium (10-40k words)", + }, + ReaderPurpose.REFERENCE: { + "reader_thinks": "I need to LOOK something up", + "value_received": "Accurate information, fast", + "emotion": "Efficient, relieved", + "length_typical": "Variable (manual size)", + }, + } + return descriptions.get(purpose, {})