Feature: Injection Depth for prompt components (depth-based insertion into conversation history) #18

New issue

Open

opened 2025-12-10 01:38:56 +00:00 by blightbow · 0 comments

blightbow commented

2025-12-10 01:38:56 +00:00

Owner

Summary

Implement injection depth support for prompt components, allowing content to be inserted at specific positions within the conversation history rather than before/after it.

Use Cases

Author's Notes - Remind the LLM of important context mid-conversation
Character Card post_history_instructions - "Jailbreak" prompts inserted near recent messages
World Info depth entries - Lore activated by keywords, positioned relative to where they appeared

Critical Constraint

Injection depth is CLAMPED to Conversation History bounds.

Depth N = N messages from bottom of Conversation History
If depth > history length → clamps to TOP of history
Injection CANNOT escape into other components
This limits attack surface from malicious character cards

Assembly Model

Before (current)

[System Prompt]              # ID 0
[Character Context]          # ID 1000
[Entity Context]             # ID 1500
[Semantic Memories]          # ID 2000
[Context Buffer]             # ID 3000
[Goals]                      # ID 4000
[Conversation History]       # ID 5000  ← Single block
[Pending Event]              # ID 6000
[Tool Result]                # ID 7000

After (with depth injection)

[Conversation History]       # ID 5000
  ├─ ... older messages ...
  ├─ [INJECTED at depth 4]   ← post_history_instructions, author's notes
  ├─ message (4th from end)
  ├─ message (3rd from end)
  ├─ message (2nd from end)
  └─ message (most recent)

Implementation

Extend PromptComponent dataclass

@dataclass
class PromptComponent:
    # ... existing fields ...
    injection_depth: int = 0      # 0 = normal, N = into history at depth N
    injection_order: int = 100    # Tiebreaker for same depth

Modify prompt assembly

Separate normal vs depth-injected components
For depth-injected: insert at max(0, len(history) - depth) (CLAMPED)
Sort by depth (desc) then order (asc) before inserting

Files to Modify

prompt_components.py - Add fields to dataclass
prompt_contexts.py - Handle depth-based injection
prompt_registry.py - Support depth/order in CRUD
commands/setup/component.py - Add /depth and /order switches

Tests

tests/test_injection_depth.py

V3 Spec Reference

The V3 character card spec defines these decorators:

@@depth N - Insert at Nth message from recent
@@reverse_depth N - Count from oldest message
@@position VALUE - Explicit placement

We implement the core @@depth concept with security constraints.

## Summary Implement injection depth support for prompt components, allowing content to be inserted at specific positions within the conversation history rather than before/after it. ## Use Cases - **Author's Notes** - Remind the LLM of important context mid-conversation - **Character Card `post_history_instructions`** - "Jailbreak" prompts inserted near recent messages - **World Info depth entries** - Lore activated by keywords, positioned relative to where they appeared ## Critical Constraint **Injection depth is CLAMPED to Conversation History bounds.** - Depth N = N messages from bottom of Conversation History - If depth > history length → clamps to TOP of history - Injection CANNOT escape into other components - This limits attack surface from malicious character cards ## Assembly Model ### Before (current) ``` [System Prompt] # ID 0 [Character Context] # ID 1000 [Entity Context] # ID 1500 [Semantic Memories] # ID 2000 [Context Buffer] # ID 3000 [Goals] # ID 4000 [Conversation History] # ID 5000 ← Single block [Pending Event] # ID 6000 [Tool Result] # ID 7000 ``` ### After (with depth injection) ``` [Conversation History] # ID 5000 ├─ ... older messages ... ├─ [INJECTED at depth 4] ← post_history_instructions, author's notes ├─ message (4th from end) ├─ message (3rd from end) ├─ message (2nd from end) └─ message (most recent) ``` ## Implementation ### Extend PromptComponent dataclass ```python @dataclass class PromptComponent: # ... existing fields ... injection_depth: int = 0 # 0 = normal, N = into history at depth N injection_order: int = 100 # Tiebreaker for same depth ``` ### Modify prompt assembly - Separate normal vs depth-injected components - For depth-injected: insert at `max(0, len(history) - depth)` (CLAMPED) - Sort by depth (desc) then order (asc) before inserting ### Files to Modify - `prompt_components.py` - Add fields to dataclass - `prompt_contexts.py` - Handle depth-based injection - `prompt_registry.py` - Support depth/order in CRUD - `commands/setup/component.py` - Add `/depth` and `/order` switches ### Tests - `tests/test_injection_depth.py` ## V3 Spec Reference The V3 character card spec defines these decorators: - `@@depth N` - Insert at Nth message from recent - `@@reverse_depth N` - Count from oldest message - `@@position VALUE` - Explicit placement We implement the core `@@depth` concept with security constraints.