agentgraph/shared/models/reference_based/content_reference.py

from pydantic import BaseModel, Field
from typing import Optional


class ContentReference(BaseModel):
    """
    Reference to content location in the original trace using line numbers and character positions.
    This allows AI agents to provide position metadata instead of full content, enabling 
    efficient mapping back to the original trace while reducing hallucination risks.
    
    CRITICAL FOR LLMs: Line counting accuracy is essential for proper content resolution.
    Use systematic counting methods and verify your line numbers before submission.
    """
    line_start: Optional[int] = Field(None, 
        description="""Starting line number where the content begins (1-based indexing from <L1>, <L2>... markers).
        
        ACCURACY REQUIREMENTS FOR LLMs:
        - Count <L#> markers systematically from the beginning of the input
        - Use anchor points: find distinctive text first, then count nearby lines
        - Double-check by counting backwards from a known reference point
        - For multi-line content, this should be the FIRST line containing the content
        - In key-value pairs (e.g. "content": "..."), reference the line where the VALUE starts, not the key
        
        COMMON ERRORS TO AVOID:
        - Miscounting due to skipping indented continuation lines
        - Confusing line numbers when content spans multiple <L#> markers
        - Using approximate counting instead of precise marker identification
        
        VERIFICATION: Before submitting, locate your chosen line number and confirm it contains the expected content start."""
    )
    line_end: Optional[int] = Field(None, 
        description="""Ending line number where content ends (1-based indexing from <L1>, <L2>... markers).
        
        ACCURACY REQUIREMENTS FOR LLMs:
        - Must be >= line_start (validation will fail otherwise)
        - For single-line content, line_end should equal line_start
        - For multi-line content, find the LAST line containing the content
        - Include indented continuation lines that are part of the same logical content block
        
        VERIFICATION STRATEGY:
        - Count from line_start to ensure proper range
        - Confirm the line_end marker contains the actual end of the content
        - Check that no content continues beyond your specified line_end"""
    )
    
    def validate_line_range(self) -> bool:
        """Validate that line_end >= line_start"""
        return self.line_end >= self.line_start
    
    def get_line_count(self) -> int:
        """Get the number of lines this reference spans"""
        return self.line_end - self.line_start + 1
    
    def is_single_line(self) -> bool:
        """Check if this reference is within a single line"""
        return self.line_start == self.line_end
    
    def __str__(self) -> str:
        """String representation for debugging"""
        if self.is_single_line():
            return f"Line {self.line_start}"
        else:
            return f"Lines {self.line_start}-{self.line_end}"