PromptBuilder.structured_section()method

Add a structured section with clear hierarchical boundaries and visual organization.

USAGE

PromptBuilder.structured_section(
    title,
    content,
    priority=Priority.MEDIUM,
    required=False,
)

Structured sections create distinct attention clusters that prevent attention drift in complex prompts by providing clear visual and cognitive boundaries around related content. Each section is formatted with an uppercase title and organized content, enabling the AI model to process information in logical, digestible chunks while maintaining focus on specific aspects of the task.

Parameters

title : str

Section heading that will be converted to uppercase for clear visual separation. Should be descriptive and specific to the content type (e.g., "Review Areas", "Performance Metrics", "Security Requirements", etc.). The title helps create mental models for information organization.

content : Union[str, List[str]]

Section content provided as either a single string or a list of items. When provided as a list, each item is automatically formatted with bullet points for clear visual organization. Content should be specific, actionable, and relevant to the section’s purpose.

priority : Priority = Priority.MEDIUM

Attention priority level for section placement in the final prompt structure. Higher priority sections appear earlier in the prompt to leverage primacy effects. Defaults to Priority.MEDIUM for balanced attention allocation.

required : bool = False

Whether to mark the section as required in the output by appending "(Required)" to the section title. This visual indicator emphasizes critical sections that must be addressed in the response. Defaults to False.

Returns

PromptBuilder

Self for method chaining, allowing combination with other prompt building methods to create comprehensive, structured prompts.

Research Foundation

Attention Clustering Theory. Creates distinct attention clusters for preventing attention drift in complex prompts. The structured approach leverages cognitive psychology principles of chunking and visual hierarchy to improve information processing and comprehension.

Cognitive Boundary Management. Structured sections group related information together, creating focused attention zones that help the model process complex requirements systematically. This prevents attention from being scattered across disconnected information and maintains cognitive coherence throughout the prompt.

Visual Hierarchy Psychology. Each section uses uppercase titles and consistent formatting to create clear visual boundaries. This visual organization helps both human readers and AI models navigate complex prompts more effectively by leveraging established patterns of visual information processing.

Priority-Based Information Architecture. Sections are automatically ordered by priority and insertion order in the final prompt, ensuring that higher-priority content receives appropriate attention placement while maintaining logical information flow that aligns with cognitive processing patterns.

Integration Notes

• Attention Clustering: creates focused information zones that prevent cognitive overload
• Visual Organization: consistent formatting improves prompt readability and navigation
• Priority-Based Ordering: sections are automatically sorted by priority for optimal attention flow
• Flexible Content: supports both single-string and list-based content organization
• Requirement Emphasis: required sections receive visual emphasis to ensure coverage
• Cognitive Chunking: information is organized in digestible units that align with human processing limits

The .structured_section() method provides a powerful tool for organizing complex information in attention-optimized ways, enabling the creation of sophisticated prompts that maintain clarity and focus while addressing multiple aspects of complex tasks.

Examples

---

Basic structured section

Create a simple section with clear organization:

import talk_box as tb

# Single-item structured section
builder = (
    tb.PromptBuilder()
    .persona("software architect", "system design")
    .task_context("review microservices architecture")
    .structured_section(
        "Architecture Principles",
        "focus on scalability, maintainability, and fault tolerance"
    )
)

print(builder)

You are a software architect with expertise in system design.

TASK: review microservices architecture

ARCHITECTURE PRINCIPLES:
focus on scalability, maintainability, and fault tolerance

List-based structured section

Use list format for multiple related items:

# Multi-item structured section
builder = (
    tb.PromptBuilder()
    .persona("security engineer", "application security")
    .task_context("conduct security audit of web application")
    .structured_section(
        "Security Focus Areas", [
            "authentication and authorization mechanisms",
            "input validation and sanitization",
            "data encryption and protection",
            "API security and rate limiting"
        ]
    )
)

print(builder)

You are a security engineer with expertise in application security.

TASK: conduct security audit of web application

SECURITY FOCUS AREAS:
- authentication and authorization mechanisms
- input validation and sanitization
- data encryption and protection
- API security and rate limiting

High-priority required section

Create critical sections that must be addressed:

# High-priority required section
builder = (
    tb.PromptBuilder()
    .persona("data scientist", "machine learning")
    .task_context("evaluate model performance and bias")
    .structured_section(
        "Model Validation", [
            "accuracy metrics across demographic groups",
            "bias detection and mitigation strategies",
            "cross-validation and generalization testing",
            "ethical considerations and fairness metrics"
        ],
        priority=tb.Priority.HIGH,
        required=True
    )
)

print(builder)

You are a data scientist with expertise in machine learning.

TASK: evaluate model performance and bias

MODEL VALIDATION (Required):
- accuracy metrics across demographic groups
- bias detection and mitigation strategies
- cross-validation and generalization testing
- ethical considerations and fairness metrics

Multiple sections with different priorities

Build comprehensive prompts with multiple organized sections:

# Complex prompt with multiple structured sections
builder = (
    tb.PromptBuilder()
    .persona("technical lead", "code review and mentorship")
    .critical_constraint("focus on production readiness and team learning")
    .task_context("review pull request for junior developer")
    .structured_section(
        "Code Quality Assessment", [
            "logic correctness and edge case handling",
            "security vulnerabilities and best practices",
            "performance implications and optimizations",
            "code readability and maintainability"
        ],
        priority=tb.Priority.HIGH,
        required=True
    )
    .structured_section(
        "Learning Opportunities", [
            "design patterns that could be applied",
            "best practices worth highlighting",
            "areas for skill development",
            "recommended learning resources"
        ],
        priority=tb.Priority.MEDIUM
    )
    .structured_section(
        "Team Knowledge Sharing", [
            "patterns that could be standardized",
            "documentation improvements needed",
            "opportunities for pair programming",
            "code that exemplifies good practices"
        ],
        priority=tb.Priority.LOW
    )
)

print(builder)

You are a technical lead with expertise in code review and mentorship.

CRITICAL REQUIREMENTS:
- focus on production readiness and team learning

TASK: review pull request for junior developer

CODE QUALITY ASSESSMENT (Required):
- logic correctness and edge case handling
- security vulnerabilities and best practices
- performance implications and optimizations
- code readability and maintainability

TEAM KNOWLEDGE SHARING:
- patterns that could be standardized
- documentation improvements needed
- opportunities for pair programming
- code that exemplifies good practices

LEARNING OPPORTUNITIES:
- design patterns that could be applied
- best practices worth highlighting
- areas for skill development
- recommended learning resources

Domain-specific structured sections

Create sections tailored to specific industries or contexts. Here’s an example for healthcare:

builder = (
    tb.PromptBuilder()
    .persona("healthcare software architect", "HIPAA compliance")
    .task_context("review patient data management system")
    .structured_section(
        "HIPAA Compliance Requirements", [
            "patient data encryption and access controls",
            "audit trail and logging mechanisms",
            "data minimization and retention policies",
            "breach detection and notification procedures"
        ],
        priority=tb.Priority.CRITICAL,
        required=True
    )
)

print(builder)

You are a healthcare software architect with expertise in HIPAA compliance.

TASK: review patient data management system

HIPAA COMPLIANCE REQUIREMENTS (Required):
- patient data encryption and access controls
- audit trail and logging mechanisms
- data minimization and retention policies
- breach detection and notification procedures

And here’s one for finance:

builder = (
    tb.PromptBuilder()
    .persona("financial systems architect", "regulatory compliance")
    .task_context("design trading system architecture")
    .structured_section(
        "Regulatory Considerations", [
            "market data handling and latency requirements",
            "trade reporting and compliance monitoring",
            "risk management and circuit breakers",
            "audit trails and regulatory reporting"
        ],
        priority=tb.Priority.HIGH,
        required=True
    )
)

print(builder)

You are a financial systems architect with expertise in regulatory compliance.

TASK: design trading system architecture

REGULATORY CONSIDERATIONS (Required):
- market data handling and latency requirements
- trade reporting and compliance monitoring
- risk management and circuit breakers
- audit trails and regulatory reporting

Performance and optimization sections

Structure performance-related requirements clearly:

builder = (
    tb.PromptBuilder()
    .persona("performance engineer", "web application optimization")
    .task_context("optimize application performance for high traffic")
    .structured_section(
        "Performance Targets", [
            "page load times under 2 seconds",
            "API response times under 100ms",
            "support for 10,000 concurrent users",
            "99.9% uptime availability"
        ],
        priority=tb.Priority.HIGH,
        required=True
    )
    .structured_section(
        "Optimization Areas", [
            "frontend asset optimization and caching",
            "database query performance and indexing",
            "CDN implementation and edge caching",
            "server-side rendering and lazy loading"
        ],
        priority=tb.Priority.MEDIUM
    )
)

print(builder)

You are a performance engineer with expertise in web application optimization.

TASK: optimize application performance for high traffic

PERFORMANCE TARGETS (Required):
- page load times under 2 seconds
- API response times under 100ms
- support for 10,000 concurrent users
- 99.9% uptime availability

OPTIMIZATION AREAS:
- frontend asset optimization and caching
- database query performance and indexing
- CDN implementation and edge caching
- server-side rendering and lazy loading

Research and analysis sections

Structure analytical requirements and methodologies:

# Research analysis prompt
builder = (
    tb.PromptBuilder()
    .persona("research analyst", "market intelligence")
    .task_context("analyze emerging technology adoption trends")
    .structured_section(
        "Research Methodology", [
            "quantitative data analysis and statistical testing",
            "qualitative interviews and survey analysis",
            "competitive landscape and market mapping",
            "trend analysis and future projections"
        ],
        priority=tb.Priority.HIGH,
        required=True
    )
    .structured_section(
        "Deliverable Requirements", [
            "executive summary with key findings",
            "detailed methodology and data sources",
            "visual charts and trend illustrations",
            "actionable recommendations and next steps"
        ],
        priority=tb.Priority.MEDIUM,
        required=True
    )
)

print(builder)

You are a research analyst with expertise in market intelligence.

TASK: analyze emerging technology adoption trends

RESEARCH METHODOLOGY (Required):
- quantitative data analysis and statistical testing
- qualitative interviews and survey analysis
- competitive landscape and market mapping
- trend analysis and future projections

DELIVERABLE REQUIREMENTS (Required):
- executive summary with key findings
- detailed methodology and data sources
- visual charts and trend illustrations
- actionable recommendations and next steps

Mixed content types in sections

Combine different content formats within sections:

builder = (
    tb.PromptBuilder()
    .persona("technical writer", "API documentation")
    .task_context("create comprehensive API documentation")
    .structured_section(
        "documentation Standards",
        "follow OpenAPI 3.0 specification for consistency and completeness"
    )
    .structured_section(
        "Required Documentation Elements", [
            "endpoint descriptions with purpose and usage",
            "request/response schemas with examples",
            "authentication and authorization details",
            "error codes and troubleshooting guidance"
        ],
        required=True
    )
)

print(builder)

You are a technical writer with expertise in API documentation.

TASK: create comprehensive API documentation

DOCUMENTATION STANDARDS:
follow OpenAPI 3.0 specification for consistency and completeness

REQUIRED DOCUMENTATION ELEMENTS (Required):
- endpoint descriptions with purpose and usage
- request/response schemas with examples
- authentication and authorization details
- error codes and troubleshooting guidance