2026-03-13 20:00:30 +00:00
"""Nonfiction Framework Taxonomy for Opus Orchestrator.
Purpose ×
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"
2026-03-14 09:24:31 +00:00
EDUCATION = "education"
ACADEMIC = "academic"
RPG = "rpg"
2026-03-13 20:00:30 +00:00
# ============================================================================
# PURPOSE ×
# ============================================================================
# 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 , {})
