Prompt Engineering

Prompt Engineering Skill

Comprehensive prompting techniques for effective LLM interactions across any model or framework.

Quick Start

import openai

client = openai.OpenAI()

# Basic prompt
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": "You are an expert engineer."},
        {"role": "user", "content": "Explain mooring systems."}
    ]
)

print(response.choices[0].message.content)

When to Use This Skill

USE when:

• Designing prompts from scratch for any use case
• Learning core principles applicable across all LLMs
• Need portable patterns not tied to specific frameworks
• Building simple LLM integrations without heavy dependencies
• Optimizing existing prompts for better results
• Creating reusable prompt templates for teams
• Debugging underperforming LLM applications
• Teaching prompt engineering to others

DON'T USE when:

• Need framework-specific features (use LangChain/DSPy)
• Require programmatic optimization (use DSPy)
• Building production RAG systems (use LangChain)
• Need conversation memory management (use frameworks)

Prerequisites

# OpenAI
pip install openai>=1.0.0
export OPENAI_API_KEY="sk-..."

# Anthropic
pip install anthropic>=0.5.0
export ANTHROPIC_API_KEY="sk-ant-..."

# Azure OpenAI
pip install openai>=1.0.0
export AZURE_OPENAI_ENDPOINT="https://..."
export AZURE_OPENAI_KEY="..."

# Optional: For testing prompts
pip install pytest promptfoo

Core Concepts

Anatomy of a Prompt

[SYSTEM CONTEXT]     - Who is the AI, what are its capabilities/constraints
[TASK DESCRIPTION]   - What needs to be done
[INPUT DATA]         - The specific content to process
[OUTPUT FORMAT]      - How the response should be structured
[EXAMPLES]           - Optional: demonstrations of desired behavior
[CONSTRAINTS]        - Limitations, things to avoid

The Prompt Engineering Loop

1. Define Goal     -> What do you want to achieve?
2. Draft Prompt    -> Initial attempt
3. Test            -> Run with diverse inputs
4. Analyze         -> Identify failures and patterns
5. Refine          -> Improve based on analysis
6. Repeat          -> Until quality meets requirements

Core Capabilities

1. Zero-Shot Prompting

Basic Zero-Shot:

def zero_shot_prompt(task: str, input_text: str) -> str:
    """
    Zero-shot prompting: Direct instruction without examples.
    Best for simple, well-defined tasks.
    """
    prompt = f"""
Task: {task}

Input: {input_text}

Output:
"""
    return prompt

# Usage
prompt = zero_shot_prompt(
    task="Classify this text as positive, negative, or neutral",
    input_text="The mooring analysis passed all safety requirements."
)
# Output: positive

Zero-Shot with Role:

def zero_shot_with_role(role: str, task: str, input_text: str) -> str:
    """
    Zero-shot with explicit role definition.
    """
    system = f"You are a {role}. You provide expert analysis."

    user = f"""
{task}

{input_text}
"""
    return system, user

# Usage
system, user = zero_shot_with_role(
    role="senior offshore engineer with 20 years experience",
    task="Review this mooring design and identify any concerns:",
    input_text="8-line spread mooring in 150m water depth..."
)

Zero-Shot Classification:

CLASSIFICATION_TEMPLATE = """
Classify the following engineering report into one of these categories:
- ANALYSIS: Technical analysis or simulation results
- INSPECTION: Field inspection or survey findings
- DESIGN: Design specifications or requirements
- INCIDENT: Incident reports or failure analysis
- MAINTENANCE: Maintenance records or procedures

Report:
{report_text}

Category:
"""

def classify_report(report_text: str) -> str:
    prompt = CLASSIFICATION_TEMPLATE.format(report_text=report_text)
    # Send to LLM
    return prompt

2. Few-Shot Prompting

Basic Few-Shot:

def few_shot_prompt(
    task_description: str,
    examples: list,
    input_text: str
) -> str:
    """
    Few-shot prompting with examples.
    Generally 2-5 examples work best.
    """
    prompt = f"{task_description}\n\n"

    # Add examples
    for i, ex in enumerate(examples, 1):
        prompt += f"Example {i}:\n"
        prompt += f"Input: {ex['input']}\n"
        prompt += f"Output: {ex['output']}\n\n"

    # Add actual input
    prompt += f"Now process this:\n"
    prompt += f"Input: {input_text}\n"
    prompt += f"Output:"

    return prompt

# Usage
examples = [
    {
        "input": "Tension: 2500 kN, Limit: 2800 kN",
        "output": "PASS - Tension is 89% of limit, within acceptable range."
    },
    {
        "input": "Tension: 3100 kN, Limit: 2800 kN",
        "output": "FAIL - Tension exceeds limit by 11%. Redesign required."
    },
    {
        "input": "Tension: 2750 kN, Limit: 2800 kN",
        "output": "WARNING - Tension is 98% of limit, minimal margin."
    }
]

prompt = few_shot_prompt(
    task_description="Evaluate mooring line tension against limits.",
    examples=examples,
    input_text="Tension: 2200 kN, Limit: 2800 kN"
)

Few-Shot with Diverse Examples:

def create_balanced_few_shot(examples_by_category: dict, input_text: str) -> str:
    """
    Create few-shot prompt with balanced examples across categories.
    """
    prompt = "Classify engineering documents into categories.\n\n"

    # Include one example from each category
    for category, examples in examples_by_category.items():
        ex = examples[0]  # Take first example from each
        prompt += f"Document: {ex['text']}\n"
        prompt += f"Category: {category}\n\n"

    prompt += f"Document: {input_text}\n"
    prompt += f"Category:"

    return prompt

# Usage
examples_by_category = {
    "ANALYSIS": [
        {"text": "FEA results show stress concentration at weld..."}
    ],
    "INSPECTION": [
        {"text": "Visual inspection revealed corrosion on flange..."}
    ],
    "DESIGN": [
        {"text": "The platform shall be designed for 100-year storm..."}
    ]
}

prompt = create_balanced_few_shot(
    examples_by_category,
    input_text="Fatigue analysis indicates 35-year service life..."
)

3. Chain-of-Thought Prompting

Basic Chain-of-Thought:

COT_TEMPLATE = """
Solve this problem step by step.

Problem: {problem}

Let me think through this carefully:

Step 1: First, I'll identify the key information...
Step 2: Next, I'll determine the approach...
Step 3: Then, I'll perform the calculations...
Step 4: Finally, I'll verify and state the answer...

Solution:
"""

def chain_of_thought_prompt(problem: str) -> str:
    return COT_TEMPLATE.format(problem=problem)

# Usage
prompt = chain_of_thought_prompt(
    problem="""
    A mooring line has a breaking load of 5000 kN.
    The maximum tension is 2800 kN.
    What is the safety factor, and does it meet the API RP 2SK
    requirement of 1.67 for intact conditions?
    """
)

Zero-Shot Chain-of-Thought:

def zero_shot_cot(question: str) -> str:
    """
    Zero-shot CoT: Simply append "Let's think step by step"
    Surprisingly effective for many reasoning tasks.
    """
    return f"{question}\n\nLet's think step by step."

# Usage
prompt = zero_shot_cot(
    "If a vessel offsets 50m from its mean position, and the "
    "mooring stiffness is 100 kN/m, what is the restoring force?"
)

Structured Chain-of-Thought:

STRUCTURED_COT_TEMPLATE = """
Analyze this engineering problem using structured reasoning.

Problem: {problem}

## Understanding
What are the key facts and requirements?

## Approach
What method or formula will I use?

## Calculation
Show the step-by-step calculation.

## Verification
How can I verify this is correct?

## Answer
State the final answer clearly.
"""

def structured_cot(problem: str) -> str:
    return STRUCTURED_COT_TEMPLATE.format(problem=problem)

Self-Consistency Chain-of-Thought:

import random

def self_consistency_cot(problem: str, num_paths: int = 5) -> str:
    """
    Generate multiple reasoning paths and take majority vote.
    Improves reliability for complex reasoning.
    """
    prompt = f"""
Solve this problem {num_paths} different ways, then determine the most likely correct answer.

Problem: {problem}

Approach 1:
[Solve using one method]

Approach 2:
[Solve using a different method]

... continue for all {num_paths} approaches ...

Consensus Answer:
[The answer that most approaches agree on]

Confidence:
[How many approaches agreed: X/{num_paths}]
"""
    return prompt

4. System Prompt Design

Role-Based System Prompt:

def create_role_system_prompt(
    role: str,
    expertise: list,
    personality: str = "professional and helpful",
    constraints: list = None
) -> str:
    """
    Create a role-based system prompt.
    """
    prompt = f"""You are a {role}.

## Expertise
You have deep knowledge in:
{chr(10).join(f"- {e}" for e in expertise)}

## Communication Style
You are {personality}. You provide clear, accurate information and acknowledge uncertainty when appropriate.
"""

    if constraints:
        prompt += f"""
## Constraints
{chr(10).join(f"- {c}" for c in constraints)}
"""

    return prompt

# Usage
system_prompt = create_role_system_prompt(
    role="senior offshore structural engineer",
    expertise=[
        "Mooring system design and analysis",
        "Fatigue assessment per DNV standards",
        "API and ISO offshore codes",
        "Finite element analysis"
    ],
    personality="thorough, safety-conscious, and educational",
    constraints=[
        "Always cite relevant standards when applicable",
        "Recommend consulting specialists for critical decisions",
        "Flag any safety concerns prominently"
    ]
)

Task-Specific System Prompt:

CODE_REVIEW_SYSTEM = """
You are an expert code reviewer specializing in Python and engineering software.

## Your Task
Review code for:
1. Correctness - Does it work as intended?
2. Safety - Are there potential bugs or edge cases?
3. Performance - Any inefficiencies?
4. Maintainability - Is it readable and well-structured?
5. Best Practices - Does it follow Python conventions?

## Response Format
For each issue found:
- **Location**: File and line number
- **Severity**: Critical / Major / Minor / Suggestion
- **Issue**: Description of the problem
- **Fix**: Suggested solution with code example

## Guidelines
- Be constructive, not critical
- Praise good patterns you see
- Focus on the most impactful issues first
- Explain WHY something is an issue
"""

DOCUMENT_ANALYSIS_SYSTEM = """
You are a technical document analyst specializing in engineering reports.

## Your Task
Analyze engineering documents to:
1. Extract key metrics and findings
2. Identify risks and concerns
3. Summarize conclusions
4. Note any missing information

## Response Format
Always structure your response as:
1. **Executive Summary** (2-3 sentences)
2. **Key Metrics** (bullet list with values and units)
3. **Findings** (numbered list)
4. **Risks** (with severity: High/Medium/Low)
5. **Recommendations** (actionable items)
6. **Information Gaps** (what's missing or unclear)

## Guidelines
- Use precise technical language
- Include units for all measurements
- Flag any values that seem unusual
- Note document quality and completeness
"""

5. Persona Design

Expert Persona:

def create_expert_persona(
    name: str,
    title: str,
    experience_years: int,
    specializations: list,
    notable_work: list = None,
    communication_style: str = None
) -> str:
    """
    Create a detailed expert persona for the AI.
    """
    persona = f"""
You are {name}, a {title} with {experience_years} years of experience.

## Background
You specialize in:
{chr(10).join(f"- {s}" for s in specializations)}
"""

    if notable_work:
        persona += f"""
## Notable Experience
{chr(10).join(f"- {w}" for w in notable_work)}
"""

    if communication_style:
        persona += f"""
## Communication Style
{communication_style}
"""

    persona += """
## Approach
- Draw on your extensive experience when answering
- Reference specific projects or cases when relevant
- Admit when something is outside your expertise
- Provide practical, actionable advice
"""

    return persona

# Usage
persona = create_expert_persona(
    name="Dr. Sarah Chen",
    title="Principal Mooring Engineer",
    experience_years=25,
    specializations=[
        "Deepwater mooring systems",
        "FPSO turret design",
        "Mooring integrity management",
        "API RP 2SK development committee member"
    ],
    notable_work=[
        "Led mooring design for 10+ FPSOs globally",
        "Developed industry guidelines for polyester moorings",
        "Expert witness in mooring failure investigations"
    ],
    communication_style="Direct and practical, with emphasis on safety and reliability. Uses real-world examples to illustrate points."
)

Adaptive Persona:

def create_adaptive_persona(
    expertise_level: str,  # beginner, intermediate, expert
    domain: str
) -> str:
    """
    Create persona that adapts to user's expertise level.
    """
    adaptations = {
        "beginner": {
            "language": "simple, avoiding jargon",
            "explanations": "detailed with background context",
            "examples": "basic, relatable analogies",
            "assumptions": "minimal prior knowledge"
        },
        "intermediate": {
            "language": "technical but with key term explanations",
            "explanations": "focused on application",
            "examples": "practical industry scenarios",
            "assumptions": "familiar with fundamentals"
        },
        "expert": {
            "language": "fully technical, industry standard",
            "explanations": "concise, focus on nuances",
            "examples": "complex edge cases",
            "assumptions": "deep domain knowledge"
        }
    }

    config = adaptations.get(expertise_level, adaptations["intermediate"])

    return f"""
You are a {domain} expert adapting your communication to a {expertise_level} audience.

## Communication Adaptation
- Use {config['language']} language
- Provide {config['explanations']} explanations
- Use {config['examples']} examples
- Assume {config['assumptions']}

## Guidelines
- Check understanding before proceeding to complex topics
- Offer to go deeper or simpler based on responses
- Be encouraging and supportive of learning
"""

# Usage
beginner_prompt = create_adaptive_persona("beginner", "mooring engineering")
expert_prompt = create_adaptive_persona("expert", "mooring engineering")

6. Structured Output

JSON Output:

JSON_OUTPUT_TEMPLATE = """
Analyze the following engineering data and return your analysis as JSON.

Data:
{input_data}

Return a JSON object with this exact structure:
{{
    "summary": "Brief summary of findings",
    "metrics": [
        {{"name": "metric name", "value": 123.45, "unit": "unit", "status": "pass/fail/warning"}}
    ],
    "risks": [
        {{"description": "risk description", "severity": "high/medium/low", "mitigation": "suggested action"}}
    ],
    "recommendation": "Overall recommendation"
}}

JSON Response:
"""

def structured_json_prompt(input_data: str) -> str:
    return JSON_OUTPUT_TEMPLATE.format(input_data=input_data)

Markdown Table Output:

TABLE_OUTPUT_TEMPLATE = """
Analyze the mooring line data and present results as a markdown table.

Data:
{input_data}

Create a table with columns:
| Line | Tension (kN) | Limit (kN) | Utilization (%) | Status |

Include a summary row at the bottom.

Response:
"""

XML Output:

XML_OUTPUT_TEMPLATE = """
Extract information from this document and format as XML.

Document:
{document}

Return XML with this structure:
<analysis>
    <document_type>...</document_type>
    <date>YYYY-MM-DD</date>
    <findings>
        <finding severity="high|medium|low">
            <description>...</description>
            <location>...</location>
        </finding>
    </findings>
    <metrics>
        <metric name="..." value="..." unit="..."/>
    </metrics>
</analysis>

XML Response:
"""

7. Prompt Templates

Reusable Template Class:

from string import Template
from typing import Dict, Any, Optional
import json

class PromptTemplate:
    """
    Reusable prompt template with validation and versioning.
    """

    def __init__(
        self,
        template: str,
        required_vars: list,
        optional_vars: list = None,
        version: str = "1.0.0",
        description: str = ""
    ):
        self.template = Template(template)
        self.required_vars = required_vars
        self.optional_vars = optional_vars or []
        self.version = version
        self.description = description

    def format(self, **kwargs) -> str:
        """Format template with provided variables."""
        # Validate required variables
        missing = set(self.required_vars) - set(kwargs.keys())
        if missing:
            raise ValueError(f"Missing required variables: {missing}")

        # Set defaults for optional variables
        for var in self.optional_vars:
            if var not in kwargs:
                kwargs[var] = ""

        return self.template.safe_substitute(**kwargs)

    def to_dict(self) -> Dict[str, Any]:
        """Export template as dictionary."""
        return {
            "template": self.template.template,
            "required_vars": self.required_vars,
            "optional_vars": self.optional_vars,
            "version": self.version,
            "description": self.description
        }

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "PromptTemplate":
        """Create template from dictionary."""
        return cls(
            template=data["template"],
            required_vars=data["required_vars"],
            optional_vars=data.get("optional_vars", []),
            version=data.get("version", "1.0.0"),
            description=data.get("description", "")
        )

    def save(self, path: str):
        """Save template to file."""
        with open(path, 'w') as f:
            json.dump(self.to_dict(), f, indent=2)

    @classmethod
    def load(cls, path: str) -> "PromptTemplate":
        """Load template from file."""
        with open(path) as f:
            return cls.from_dict(json.load(f))

# Usage
analysis_template = PromptTemplate(
    template="""
Analyze this $document_type for $purpose.

Document:
$content

Focus on:
$focus_areas

Provide your analysis following this structure:
1. Summary
2. Key Findings
3. Recommendations

$additional_instructions
""",
    required_vars=["document_type", "purpose", "content", "focus_areas"],
    optional_vars=["additional_instructions"],
    version="1.0.0",
    description="General document analysis template"
)

prompt = analysis_template.format(
    document_type="mooring analysis report",
    purpose="safety review",
    content="[Report content here...]",
    focus_areas="safety factors, fatigue life, extreme conditions"
)

Template Library:

class PromptLibrary:
    """
    Library of reusable prompt templates.
    """

    def __init__(self):
        self.templates: Dict[str, PromptTemplate] = {}

    def register(self, name: str, template: PromptTemplate):
        """Register a template."""
        self.templates[name] = template

    def get(self, name: str) -> PromptTemplate:
        """Get a template by name."""
        if name not in self.templates:
            raise KeyError(f"Template '{name}' not found")
        return self.templates[name]

    def list_templates(self) -> list:
        """List all available templates."""
        return [
            {"name": name, "description": t.description, "version": t.version}
            for name, t in self.templates.items()
        ]

    def save_library(self, path: str):
        """Save entire library to file."""
        data = {name: t.to_dict() for name, t in self.templates.items()}
        with open(path, 'w') as f:
            json.dump(data, f, indent=2)

    @classmethod
    def load_library(cls, path: str) -> "PromptLibrary":
        """Load library from file."""
        library = cls()
        with open(path) as f:
            data = json.load(f)
        for name, template_data in data.items():
            library.register(name, PromptTemplate.from_dict(template_data))
        return library

# Create standard library
library = PromptLibrary()

library.register("summarize", PromptTemplate(
    template="Summarize the following in $length:\n\n$text\n\nSummary:",
    required_vars=["length", "text"],
    description="Text summarization"
))

library.register("classify", PromptTemplate(
    template="Classify this text into one of: $categories\n\nText: $text\n\nCategory:",
    required_vars=["categories", "text"],
    description="Text classification"
))

library.register("extract", PromptTemplate(
    template="Extract $entity from this text:\n\n$text\n\nExtracted:",
    required_vars=["entity", "text"],
    description="Entity extraction"
))

# Usage
summarize = library.get("summarize")
prompt = summarize.format(length="2 sentences", text="[Long document...]")

8. Evaluation and Iteration

Prompt Testing Framework:

from dataclasses import dataclass
from typing import Callable, List
import json

@dataclass
class TestCase:
    """Single test case for prompt evaluation."""
    input_data: dict
    expected_output: str = None
    expected_contains: list = None
    expected_not_contains: list = None
    metadata: dict = None

@dataclass
class TestResult:
    """Result of a single test."""
    test_case: TestCase
    actual_output: str
    passed: bool
    score: float
    details: str

class PromptEvaluator:
    """
    Evaluate prompts against test cases.
    """

    def __init__(self, prompt_template: PromptTemplate, llm_caller: Callable):
        self.template = prompt_template
        self.llm_caller = llm_caller

    def run_test(self, test_case: TestCase) -> TestResult:
        """Run a single test case."""
        # Format prompt
        prompt = self.template.format(**test_case.input_data)

        # Get LLM response
        output = self.llm_caller(prompt)

        # Evaluate
        passed = True
        score = 1.0
        details = []

        # Check exact match
        if test_case.expected_output:
            if output.strip() != test_case.expected_output.strip():
                passed = False
                score -= 0.5
                details.append(f"Expected exact: {test_case.expected_output}")

        # Check contains
        if test_case.expected_contains:
            for term in test_case.expected_contains:
                if term.lower() not in output.lower():
                    passed = False
                    score -= 0.2
                    details.append(f"Missing: {term}")

        # Check not contains
        if test_case.expected_not_contains:
            for term in test_case.expected_not_contains:
                if term.lower() in output.lower():
                    passed = False
                    score -= 0.3
                    details.append(f"Should not contain: {term}")

        return TestResult(
            test_case=test_case,
            actual_output=output,
            passed=passed,
            score=max(0, score),
            details="; ".join(details) if details else "All checks passed"
        )

    def run_suite(self, test_cases: List[TestCase]) -> dict:
        """Run all test cases and return summary."""
        results = [self.run_test(tc) for tc in test_cases]

        passed = sum(1 for r in results if r.passed)
        avg_score = sum(r.score for r in results) / len(results)

        return {
            "total": len(results),
            "passed": passed,
            "failed": len(results) - passed,
            "pass_rate": passed / len(results),
            "avg_score": avg_score,
            "results": results
        }

# Usage
test_cases = [
    TestCase(
        input_data={"text": "Tension: 2500 kN, Limit: 2800 kN"},
        expected_contains=["pass", "within"],
        expected_not_contains=["fail", "exceed"]
    ),
    TestCase(
        input_data={"text": "Tension: 3100 kN, Limit: 2800 kN"},
        expected_contains=["fail", "exceed"],
        expected_not_contains=["pass", "within"]
    )
]

evaluator = PromptEvaluator(tension_check_template, llm_call)
results = evaluator.run_suite(test_cases)

print(f"Pass Rate: {results['pass_rate']:.1%}")
print(f"Average Score: {results['avg_score']:.2f}")

A/B Testing Prompts:

from typing import Dict, List
import random

class PromptABTest:
    """
    A/B test different prompt variants.
    """

    def __init__(self, variants: Dict[str, PromptTemplate], metric_fn: Callable):
        self.variants = variants
        self.metric_fn = metric_fn
        self.results: Dict[str, List[float]] = {name: [] for name in variants}

    def run_test(self, test_cases: List[TestCase], n_runs: int = 1) -> dict:
        """Run A/B test across variants."""

        for _ in range(n_runs):
            for test_case in test_cases:
                for name, template in self.variants.items():
                    prompt = template.format(**test_case.input_data)
                    output = llm_call(prompt)
                    score = self.metric_fn(test_case, output)
                    self.results[name].append(score)

        # Calculate statistics
        summary = {}
        for name, scores in self.results.items():
            summary[name] = {
                "mean": sum(scores) / len(scores),
                "min": min(scores),
                "max": max(scores),
                "n_samples": len(scores)
            }

        # Determine winner
        best = max(summary.items(), key=lambda x: x[1]["mean"])
        summary["winner"] = best[0]

        return summary

# Usage
variants = {
    "concise": PromptTemplate("Briefly analyze: $text", ["text"]),
    "detailed": PromptTemplate("Provide detailed analysis of: $text", ["text"]),
    "structured": PromptTemplate("Analyze with sections:\n$text", ["text"])
}

ab_test = PromptABTest(variants, quality_metric)
results = ab_test.run_test(test_cases, n_runs=3)

print(f"Winner: {results['winner']}")
for name, stats in results.items():
    if name != "winner":
        print(f"{name}: mean={stats['mean']:.2f}")

Complete Examples

Example 1: Multi-Stage Document Processor

from typing import Dict, List, Optional
from dataclasses import dataclass

@dataclass
class ProcessingResult:
    summary: str
    key_points: List[str]
    metrics: List[Dict]
    risks: List[Dict]
    recommendations: List[str]
    confidence: float

class DocumentProcessor:
    """
    Multi-stage document processing with specialized prompts.
    """

    def __init__(self, llm_caller: Callable):
        self.llm = llm_caller

        # Stage 1: Extract key information
        self.extract_prompt = """
Extract key information from this engineering document.

Document:
{document}

Return as JSON:
{{
    "document_type": "type of document",
    "date": "document date if present",
    "subject": "main subject",
    "key_points": ["point 1", "point 2", ...],
    "metrics": [
        {{"name": "metric name", "value": "value", "unit": "unit"}}
    ]
}}

JSON:
"""

        # Stage 2: Analyze for risks
        self.risk_prompt = """
Based on this document summary and metrics, identify potential risks.

Summary: {summary}
Metrics: {metrics}

For each risk, provide:
- Description
- Severity (high/medium/low)
- Likelihood (high/medium/low)
- Mitigation suggestion

Return as JSON list:
[
    {{
        "description": "...",
        "severity": "...",
        "likelihood": "...",
        "mitigation": "..."
    }}
]

Risks:
"""

        # Stage 3: Generate recommendations
        self.recommend_prompt = """
Based on this analysis, provide prioritized recommendations.

Key Points: {key_points}
Risks: {risks}

Provide 3-5 actionable recommendations, prioritized by importance.
Each recommendation should be specific and actionable.

Recommendations:
1.
"""

    def process(self, document: str) -> ProcessingResult:
        """Process document through all stages."""

        # Stage 1: Extract
        extract_result = self.llm(
            self.extract_prompt.format(document=document)
        )
        extracted = self._parse_json(extract_result)

        # Stage 2: Analyze risks
        risk_result = self.llm(
            self.risk_prompt.format(
                summary=extracted.get("subject", ""),
                metrics=str(extracted.get("metrics", []))
            )
        )
        risks = self._parse_json(risk_result)

        # Stage 3: Recommendations
        recommend_result = self.llm(
            self.recommend_prompt.format(
                key_points="\n".join(extracted.get("key_points", [])),
                risks=str(risks)
            )
        )
        recommendations = self._parse_recommendations(recommend_result)

        # Calculate confidence based on extraction quality
        confidence = self._calculate_confidence(extracted, risks)

        return ProcessingResult(
            summary=extracted.get("subject", ""),
            key_points=extracted.get("key_points", []),
            metrics=extracted.get("metrics", []),
            risks=risks if isinstance(risks, list) else [],
            recommendations=recommendations,
            confidence=confidence
        )

    def _parse_json(self, text: str) -> dict:
        """Parse JSON from LLM response."""
        import json
        try:
            # Find JSON in response
            start = text.find('{')
            end = text.rfind('}') + 1
            if start >= 0 and end > start:
                return json.loads(text[start:end])
            start = text.find('[')
            end = text.rfind(']') + 1
            if start >= 0 and end > start:
                return json.loads(text[start:end])
        except json.JSONDecodeError:
            pass
        return {}

    def _parse_recommendations(self, text: str) -> List[str]:
        """Parse numbered recommendations."""
        lines = text.strip().split('\n')
        recommendations = []
        for line in lines:
            line = line.strip()
            if line and line[0].isdigit():
                # Remove number prefix
                rec = line.lstrip('0123456789.').strip()
                if rec:
                    recommendations.append(rec)
        return recommendations

    def _calculate_confidence(self, extracted: dict, risks: list) -> float:
        """Calculate confidence score."""
        score = 0.5  # Base

        if extracted.get("key_points"):
            score += 0.15
        if extracted.get("metrics"):
            score += 0.15
        if risks and len(risks) > 0:
            score += 0.2

        return min(score, 1.0)

# Usage
processor = DocumentProcessor(llm_caller=call_openai)

result = processor.process("""
MOORING ANALYSIS REPORT
Project: Platform Alpha
Date: 2026-01-15

Executive Summary:
Analysis of 8-line spread mooring in 120m water depth.

Key Results:
- Maximum tension: 2,450 kN (Line 3, 100-year storm)
- Safety factor: 1.74 (minimum requirement: 1.67)
- Fatigue life: 38 years (design life: 25 years)

Observations:
- Line 3 shows highest utilization at fairlead
- Chain wear at 7% after 5 years operation
- Polyester sections in good condition
""")

print(f"Summary: {result.summary}")
print(f"Confidence: {result.confidence:.0%}")
print(f"\nKey Points:")
for point in result.key_points:
    print(f"  - {point}")
print(f"\nRisks:")
for risk in result.risks:
    print(f"  - [{risk.get('severity', 'unknown')}] {risk.get('description', '')}")
print(f"\nRecommendations:")
for i, rec in enumerate(result.recommendations, 1):
    print(f"  {i}. {rec}")

Example 2: Interactive Prompt Builder

class InteractivePromptBuilder:
    """
    Build prompts interactively with guided configuration.
    """

    def __init__(self):
        self.components = {
            "role": None,
            "context": None,
            "task": None,
            "format": None,
            "examples": [],
            "constraints": []
        }

    def set_role(self, role: str, expertise: List[str] = None) -> "InteractivePromptBuilder":
        """Set the AI's role."""
        role_text = f"You are a {role}."
        if expertise:
            role_text += f" You have expertise in: {', '.join(expertise)}."
        self.components["role"] = role_text
        return self

    def set_context(self, context: str) -> "InteractivePromptBuilder":
        """Set background context."""
        self.components["context"] = f"Context: {context}"
        return self

    def set_task(self, task: str, details: str = None) -> "InteractivePromptBuilder":
        """Set the main task."""
        task_text = f"Task: {task}"
        if details:
            task_text += f"\n\nDetails: {details}"
        self.components["task"] = task_text
        return self

    def set_format(self, format_type: str, structure: str = None) -> "InteractivePromptBuilder":
        """Set output format."""
        format_text = f"Output Format: {format_type}"
        if structure:
            format_text += f"\n\n{structure}"
        self.components["format"] = format_text
        return self

    def add_example(self, input_text: str, output_text: str) -> "InteractivePromptBuilder":
        """Add a few-shot example."""
        self.components["examples"].append({
            "input": input_text,
            "output": output_text
        })
        return self

    def add_constraint(self, constraint: str) -> "InteractivePromptBuilder":
        """Add a constraint."""
        self.components["constraints"].append(constraint)
        return self

    def build(self) -> tuple:
        """Build the final system and user prompts."""
        system_parts = []
        user_parts = []

        # System prompt components
        if self.components["role"]:
            system_parts.append(self.components["role"])

        if self.components["constraints"]:
            system_parts.append("Constraints:")
            for c in self.components["constraints"]:
                system_parts.append(f"- {c}")

        # User prompt components
        if self.components["context"]:
            user_parts.append(self.components["context"])

        if self.components["task"]:
            user_parts.append(self.components["task"])

        if self.components["examples"]:
            user_parts.append("\nExamples:")
            for i, ex in enumerate(self.components["examples"], 1):
                user_parts.append(f"\nExample {i}:")
                user_parts.append(f"Input: {ex['input']}")
                user_parts.append(f"Output: {ex['output']}")

        if self.components["format"]:
            user_parts.append(f"\n{self.components['format']}")

        return "\n".join(system_parts), "\n".join(user_parts)

    def preview(self) -> str:
        """Preview the complete prompt."""
        system, user = self.build()
        return f"=== SYSTEM ===\n{system}\n\n=== USER ===\n{user}"

# Usage
builder = InteractivePromptBuilder()

system, user = (
    builder
    .set_role("senior offshore engineer", ["mooring design", "structural analysis"])
    .set_context("Reviewing mooring analysis report for regulatory submission")
    .set_task(
        "Review the mooring analysis and identify any issues",
        "Focus on safety factors, fatigue life, and extreme conditions"
    )
    .add_example(
        "SF = 1.65, Limit = 1.67",
        "ISSUE: Safety factor 1.65 is below minimum requirement of 1.67"
    )
    .add_example(
        "Fatigue life = 80 years, Design life = 25 years",
        "OK: Fatigue life exceeds 3x design life requirement"
    )
    .add_constraint("Always cite the relevant standard for each finding")
    .add_constraint("Use severity levels: Critical, Major, Minor")
    .set_format("Structured markdown", """
## Summary
[Overall assessment]

## Findings
| ID | Finding | Severity | Standard |
|----|---------|----------|----------|
| 1  | ...     | ...      | ...      |

## Recommendations
1. ...
""")
    .build()
)

print(builder.preview())

Integration Patterns

OpenAI Integration

import openai

def create_openai_caller(model: str = "gpt-4", temperature: float = 0.7):
    """Create OpenAI API caller."""
    client = openai.OpenAI()

    def call(prompt: str, system: str = None) -> str:
        messages = []
        if system:
            messages.append({"role": "system", "content": system})
        messages.append({"role": "user", "content": prompt})

        response = client.chat.completions.create(
            model=model,
            messages=messages,
            temperature=temperature
        )
        return response.choices[0].message.content

    return call

# Usage
llm = create_openai_caller(model="gpt-4", temperature=0.3)
response = llm("Explain mooring catenary equations", system="You are an engineer.")

Anthropic Integration

import anthropic

def create_anthropic_caller(model: str = "claude-3-opus-20240229"):
    """Create Anthropic API caller."""
    client = anthropic.Anthropic()

    def call(prompt: str, system: str = None) -> str:
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            system=system or "",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.content[0].text

    return call

# Usage
llm = create_anthropic_caller()
response = llm("Explain mooring design", system="You are an offshore engineer.")

Best Practices

1. Be Specific and Clear

# Bad
prompt = "Analyze this."

# Good
prompt = """
Analyze this mooring analysis report for safety compliance.

Check the following:
1. Safety factors meet API RP 2SK requirements (>=1.67 intact, >=1.25 damaged)
2. Fatigue life exceeds 3x design life
3. All load cases are covered

Report:
{report}

Provide findings in a table format.
"""

2. Use Consistent Formatting

# Establish consistent patterns
STANDARD_SECTIONS = """
## Input
{input}

## Task
{task}

## Output Format
{format}

## Constraints
{constraints}
"""

3. Provide Context

# Include relevant background
context = """
This is a mooring analysis for an FPSO in the Gulf of Mexico.
Water depth: 1500m
Mooring type: Polyester-chain hybrid
Design life: 25 years
Applicable standard: API RP 2SK 4th Edition
"""

4. Iterate Based on Failures

# Keep track of failures
failures = []

def log_failure(prompt, expected, actual, notes):
    failures.append({
        "prompt": prompt,
        "expected": expected,
        "actual": actual,
        "notes": notes
    })

# Review and improve
def analyze_failures():
    # Find patterns in failures
    # Adjust prompts accordingly
    pass

Troubleshooting

Inconsistent Outputs

# Lower temperature for consistency
response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
    temperature=0.1  # Lower = more consistent
)

# Or use seed for reproducibility
response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
    seed=42
)

Outputs Too Long/Short

# Control length explicitly
prompt = """
Provide a summary in exactly 3 sentences.
Do not exceed 100 words.
"""

# Or use max_tokens
response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
    max_tokens=150
)

Wrong Format

# Be very explicit about format
prompt = """
Return ONLY a JSON object. No ex

…(truncated)