PromptSection

Represents a structured section of an attention-optimized prompt with priority and ordering metadata.

USAGE

PromptSection(
    content,
    priority=Priority.MEDIUM,
    section_type='general',
    order_hint=0,
)

The PromptSection class is a fundamental building block used by PromptBuilder to create sophisticated, attention-optimized prompts. Each section encapsulates content along with metadata that controls how the section is positioned and prioritized within the final prompt. This enables precise control over attention flow and information hierarchy.

Integration with PromptBuilder:

While users can create PromptSection objects directly, they are typically created automatically by PromptBuilder methods. The sections are then assembled according to attention principles to create optimized final prompts. This design provides both high-level convenience through PromptBuilder and fine-grained control through direct PromptSection manipulation.

Attention Optimization:

Each section contributes to the overall attention strategy:

• Priority: determines relative importance and influences final ordering
• Section Type: enables grouping and specialized handling of content types
• Order Hint: provides fine-grained control over section positioning
• Content: the actual prompt text optimized for the section’s role

The combination of these attributes allows the prompt building system to create prompts that leverage attention mechanisms effectively, ensuring critical information receives appropriate model focus while maintaining natural conversation flow.

Parameters

content : str

The text content of the prompt section. This is the actual text that will appear in the final prompt. Content should be crafted to serve the section’s specific purpose within the overall prompt strategy.

priority : Priority = Priority.MEDIUM

Attention priority level determining section placement order and emphasis. Higher priority sections are typically placed in more prominent positions. Defaults to Priority.MEDIUM.

section_type : str = 'general'

Type classification for the section enabling specialized handling and grouping. This allows the prompt builder to apply type-specific optimization strategies. Defaults to "general".

order_hint : int = 0

Fine-grained ordering hint where lower numbers appear earlier in the prompt. This provides precise control over section positioning beyond priority levels. Sections with the same priority are ordered by this value. Defaults to 0.

Returns

PromptSection

A new prompt section with the specified content and metadata.

Priority Levels

The available priority levels are:

• Priority.CRITICAL: highest importance, placed prominently
• Priority.HIGH: important content requiring strong attention
• Priority.MEDIUM: standard priority for general content
• Priority.LOW: supporting information, de-emphasized placement
• Priority.MINIMAL: background context, least prominent placement

Section Types

Common section types include:

• "persona": role and behavioral context
• "constraint": requirements and limitations
• "analysis": core analysis tasks and objectives
• "format": output formatting requirements
• "example": input/output examples and demonstrations
• "emphasis": final reinforcement and focus directives
• "general": general-purpose content

Section Lifecycle

Prompt sections typically follow this lifecycle within the prompt building process:

1. Creation: sections are created with content and metadata
2. Collection: multiple sections are gathered by the PromptBuilder
3. Sorting: sections are ordered by priority and order_hint values
4. Grouping: sections are grouped by type for specialized handling
5. Assembly: final prompt is constructed from ordered sections
6. Optimization: content is refined for attention and coherence

Design Principles

Attention Optimization: sections are designed to work together to guide model attention effectively, with priority and positioning controlling information hierarchy.

Modularity: each section encapsulates a specific aspect of the prompt, enabling reusable components and systematic prompt construction.

Flexibility: the section system supports both structured workflows through standard section types and custom applications through extensible metadata.

Composability: sections can be combined, reordered, and manipulated to create sophisticated prompt strategies for different use cases.

Cognitive Alignment: section design aligns with cognitive psychology principles like primacy/recency effects and information chunking for optimal comprehension.

Integration Notes

• Automatic Ordering: when used with PromptBuilder, sections are automatically ordered by priority and order_hint for optimal attention flow
• Type-Based Processing: section types enable specialized handling and validation within the prompt building pipeline
• Content Optimization: section content should be crafted for clarity and specificity to maximize prompt effectiveness
• Memory Efficiency: sections are lightweight dataclasses suitable for large-scale prompt construction workflows

The PromptSection class provides the foundation for systematic, attention-optimized prompt engineering, enabling both simple prompt construction and sophisticated multi-component prompt strategies.

Examples

---

Creating basic prompt sections

Create sections for different types of prompt content:

import talk_box as tb

# High-priority persona section
persona_section = tb.PromptSection(
    content="You are a senior software architect with expertise in distributed systems.",
    priority=tb.Priority.CRITICAL,
    section_type="persona",
    order_hint=1
)

# Critical constraint section
constraint_section = tb.PromptSection(
    content="Focus only on scalability issues that impact performance.",
    priority=tb.Priority.CRITICAL,
    section_type="constraint",
    order_hint=2
)

# Medium-priority analysis section
analysis_section = tb.PromptSection(
    content="Analyze the system architecture for bottlenecks and optimization opportunities.",
    priority=tb.Priority.MEDIUM,
    section_type="analysis",
    order_hint=10
)

print(f"Persona: {persona_section.content}")
print(f"Priority: {persona_section.priority}")
print(f"Type: {persona_section.section_type}")

Working with section priorities

Use priorities to control attention hierarchy:

# Create sections with different priorities
sections = [
    tb.PromptSection(
        content="Secondary consideration: Check for code style consistency.",
        priority=tb.Priority.LOW,
        section_type="analysis"
    ),
    tb.PromptSection(
        content="CRITICAL: Identify security vulnerabilities immediately.",
        priority=tb.Priority.CRITICAL,
        section_type="constraint"
    ),
    tb.PromptSection(
        content="Important: Focus on performance bottlenecks.",
        priority=tb.Priority.HIGH,
        section_type="analysis"
    ),
    tb.PromptSection(
        content="Background context: This is a financial application.",
        priority=tb.Priority.MINIMAL,
        section_type="general"
    )
]

Using section types for specialized handling

Organize content by type for targeted optimization:

# Create sections representing different prompt components
prompt_sections = [
    tb.PromptSection(
        content="You are an expert code reviewer.",
        priority=tb.Priority.CRITICAL,
        section_type="persona"
    ),
    tb.PromptSection(
        content="Focus on security issues and performance problems.",
        priority=tb.Priority.HIGH,
        section_type="constraint"
    ),
    tb.PromptSection(
        content="Analyze the code for bugs, security flaws, and inefficiencies.",
        priority=tb.Priority.MEDIUM,
        section_type="analysis"
    ),
    tb.PromptSection(
        content="Format: List critical issues first, then suggestions.",
        priority=tb.Priority.MEDIUM,
        section_type="format"
    ),
    tb.PromptSection(
        content="Example: 'CRITICAL: SQL injection vulnerability on line 42'",
        priority=tb.Priority.LOW,
        section_type="example"
    )
]

Fine-grained ordering with order_hint

Use order_hint for precise section positioning:

# Create sections with same priority but different order hints
setup_sections = [
    tb.PromptSection(
        content="You are a helpful assistant.",
        priority=tb.Priority.HIGH,
        section_type="persona",
        order_hint=1  # First
    ),
    tb.PromptSection(
        content="You specialize in Python programming.",
        priority=tb.Priority.HIGH,
        section_type="persona",
        order_hint=2  # Second
    ),
    tb.PromptSection(
        content="You focus on writing clean, efficient code.",
        priority=Priority.HIGH,
        section_type="persona",
        order_hint=3  # Third
    )
]

Building sections for different prompt strategies

Create sections optimized for specific attention patterns:

# Front-loading critical information (primacy bias)
critical_first = tb.PromptSection(
    content="IMMEDIATE PRIORITY: Check for buffer overflow vulnerabilities.",
    priority=tb.Priority.CRITICAL,
    section_type="constraint",
    order_hint=1
)

# Core task definition
main_task = tb.PromptSection(
    content="Review this C++ code for security issues and memory management problems.",
    priority=tb.Priority.HIGH,
    section_type="analysis",
    order_hint=10
)

# Final emphasis (recency bias)
final_emphasis = tb.PromptSection(
    content="Remember: Security vulnerabilities are the highest priority.",
    priority=Priority.HIGH,
    section_type="emphasis",
    order_hint=100
)

Integration with PromptBuilder workflow

See how sections work within the larger prompt building process:

# Create a prompt builder
builder = tb.PromptBuilder()

# Builder methods create PromptSection objects internally
builder.persona("senior developer", "code review")
builder.critical_constraint("Focus on security vulnerabilities")
builder.core_analysis(["Memory management", "Input validation", "Error handling"])

# You can also add custom sections directly
custom_section = tb.PromptSection(
    content="Pay special attention to authentication mechanisms.",
    priority=tb.Priority.HIGH,
    section_type="constraint",
    order_hint=5
)

# Add custom section to builder's internal collection
builder.sections.append(custom_section)

# Build final prompt (sections are automatically ordered and assembled)
final_prompt = builder
print("Final assembled prompt:")
print(final_prompt)

Advanced section manipulation

Perform sophisticated operations on section collections:

# Create a collection of mixed sections
mixed_sections = [
    tb.PromptSection("Core task", tb.Priority.HIGH, "analysis", 1),
    tb.PromptSection("Important constraint", tb.Priority.HIGH, "constraint", 2),
    tb.PromptSection("Background info", tb.Priority.LOW, "general", 3),
    tb.PromptSection("Critical requirement", tb.Priority.CRITICAL, "constraint", 0),
    tb.PromptSection("Output format", tb.Priority.MEDIUM, "format", 4)
]

# Filter high-priority sections
high_priority = [s for s in mixed_sections if s.priority.value >= tb.Priority.HIGH.value]

# Find all constraint sections
constraints = [s for s in mixed_sections if s.section_type == "constraint"]

# Get earliest section by order_hint
earliest = min(mixed_sections, key=lambda s: s.order_hint)

# Calculate total content length
total_length = sum(len(s.content) for s in mixed_sections)

print(f"High priority sections: {len(high_priority)}")
print(f"Constraint sections: {len(constraints)}")
print(f"Earliest section: {earliest.content}")
print(f"Total content length: {total_length} characters")

Custom section types for specialized workflows

Define custom section types for specific applications:

# Custom section types for code review workflow
code_review_sections = [
    tb.PromptSection(
        content="You are a senior code reviewer with 10+ years experience.",
        priority=tb.Priority.CRITICAL,
        section_type="reviewer_persona"
    ),
    tb.PromptSection(
        content="This code will be deployed to production systems.",
        priority=tb.Priority.HIGH,
        section_type="deployment_context"
    ),
    tb.PromptSection(
        content="Check: Security, Performance, Maintainability, Testing",
        priority=tb.Priority.HIGH,
        section_type="review_checklist"
    ),
    tb.PromptSection(
        content="Format: Critical issues first, then improvements, then praise",
        priority=tb.Priority.MEDIUM,
        section_type="response_structure"
    ),
    tb.PromptSection(
        content="Remember: Constructive feedback builds better developers.",
        priority=tb.Priority.MEDIUM,
        section_type="review_philosophy"
    )
]

# Process sections by custom type
workflow_map = {
    "reviewer_persona": "Sets reviewer identity and expertise",
    "deployment_context": "Provides operational context",
    "review_checklist": "Defines evaluation criteria",
    "response_structure": "Controls output organization",
    "review_philosophy": "Guides feedback tone and approach"
}

print("Code review workflow sections:")
for section in code_review_sections:
    purpose = workflow_map.get(section.section_type, "General purpose")
    print(f"• {section.section_type}: {purpose}")
    print(f"  Content: {section.content}")
    print()