fix(security): add token budget limiting and LLM validator sanitization

[Mr-Neutr0n]

Summary

Addresses security findings from issue #2056:

1. Retry Amplification Mitigation (Medium severity)

   • Added optional token_budget parameter to create() calls
   • When set, retries will stop if cumulative tokens exceed the budget
   • New TokenBudgetExceeded exception provides detailed context (budget, tokens used, attempts)
   • Prevents runaway costs from adversarial/prompt-injected responses that always fail validation

2. LLM Validator Injection Protection (Medium severity)

   • User values are now wrapped with explicit delimiters (---BEGIN VALUE--- / ---END VALUE---)
   • Delimiter characters in user input are escaped (\``and---`)
   • Uses structured format that clearly separates user value from validation rules
   • Prevents prompt injection attacks that could manipulate validator decisions

Usage

# New token_budget parameter to prevent retry amplification
try:
    response = client.chat.completions.create(
        response_model=StrictModel,
        max_retries=10,
        token_budget=10000,  # Stop if we use more than 10k tokens total
        ...
    )
except TokenBudgetExceeded as e:
    print(f"Stopped after {e.n_attempts} attempts, used {e.total_tokens_used} tokens")

Changes

• instructor/core/exceptions.py: Added TokenBudgetExceeded exception
• instructor/core/retry.py: Added token_budget parameter and get_total_tokens() helper
• instructor/core/patch.py: Wired token_budget through to retry functions
• instructor/validation/llm_validators.py: Added input sanitization and structured prompts
• instructor/__init__.py: Exported TokenBudgetExceeded
• Added tests for both security fixes

Test Plan

• Added test_token_budget_exceeded and test_token_budget_exceeded_inherits_from_instructor_error to tests/test_exceptions.py
• Added tests/test_security_fixes.py with tests for get_total_tokens() helper and sanitization logic
• Syntax validation passes for all modified files

Fixes #2056

[Mr-Neutr0n]

Friendly follow-up - is there anything I can improve in this PR? Happy to address any feedback.

[Mr-Neutr0n]

Friendly bump! Let me know if there's anything I should update or improve to help move this forward.