463 lines
18 KiB
Python
463 lines
18 KiB
Python
"""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"
|
||
EDUCATION = "education"
|
||
ACADEMIC = "academic"
|
||
RPG = "rpg"
|
||
|
||
|
||
# ============================================================================
|
||
# 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, {})
|