# user_service.py
from database import get_user

def get_user_email(user_id: int) -> str:
    user = get_user(user_id)  # This can return None
    return user.email  # TypeError: 'NoneType' object has no attribute 'email'

attention(i, j) = softmax(Q_i · K_j^T / sqrt(d_k))

# Monthly cost estimation
# Assuming GPT-4 pricing: $30/M input tokens, $60/M output tokens

ENGINEERS = 50
REQUESTS_PER_DAY = 20
DAYS_PER_MONTH = 22
AVG_OUTPUT_TOKENS = 500

# Scenario A: Well-curated context (4K input tokens)
input_tokens_a = 4000
monthly_cost_a = (ENGINEERS * REQUESTS_PER_DAY * DAYS_PER_MONTH * 
                   (input_tokens_a * 30 / 1_000_000 + 
                    AVG_OUTPUT_TOKENS * 60 / 1_000_000))

# Scenario B: Bloated context (40K input tokens)
input_tokens_b = 40000
monthly_cost_b = (ENGINEERS * REQUESTS_PER_DAY * DAYS_PER_MONTH * 
                   (input_tokens_b * 30 / 1_000_000 + 
                    AVG_OUTPUT_TOKENS * 60 / 1_000_000))

print(f"Curated context (4K):   ${monthly_cost_a:,.2f}/month")
print(f"Bloated context (40K):  ${monthly_cost_b:,.2f}/month")
print(f"Cost multiplier:        {monthly_cost_b/monthly_cost_a:.1f}x")
print(f"Monthly waste:          ${monthly_cost_b - monthly_cost_a:,.2f}")

Curated context (4K):   $6,160.00/month
Bloated context (40K):  $54,560.00/month
Cost multiplier:        8.9x
Monthly waste:          $48,400.00

effective_quality = S / (N + R × S)

Performance
    |
1.0 |          _________________
    |         /
0.9 |        /
    |       /
0.8 |      /
    |     /
0.7 |    /
    |   /
0.6 |--/----+-------------------
    |       |
0.5 |       |               ___
    |       |              /
0.4 |       |             /
    |       |            /
0.3 |       |___________/
    |
    +----+----+----+----+----+----→ Context Volume
     1K  2K  4K  8K 16K 32K
           ↑
      Optimal Zone

import numpy as np
from typing import List, Tuple

def hybrid_score(
    dense_scores: np.ndarray,
    sparse_scores: np.ndarray, 
    alpha: float = 0.6
) -> np.ndarray:
    """Combine dense and sparse retrieval scores.

    Dense scores capture semantic similarity.
    Sparse scores (e.g., BM25) capture exact keyword matches.
    Alpha controls the weighting (0.0 = sparse only, 1.0 = dense only).
    """
    # Normalize both score vectors to [0, 1]
    def min_max_normalize(scores):
        s_min, s_max = scores.min(), scores.max()
        if s_max - s_min == 0:
            return np.zeros_like(scores)
        return (scores - s_min) / (s_max - s_min)

    dense_norm = min_max_normalize(dense_scores)
    sparse_norm = min_max_normalize(sparse_scores)

    return alpha * dense_norm + (1 - alpha) * sparse_norm

def retrieve_hybrid(
    query: str,
    chunks: List[dict],
    dense_model,
    bm25_index,
    top_k: int = 5,
    alpha: float = 0.6
) -> List[dict]:
    """Perform hybrid retrieval with deduplication."""
    query_dense = dense_model.encode(query)
    chunk_embeddings = np.array([c['embedding'] for c in chunks])

    dense_scores = (chunk_embeddings @ query_dense.T).flatten()
    sparse_scores = np.array(bm25_index.get_scores(query))

    combined = hybrid_score(dense_scores, sparse_scores, alpha)
    top_indices = np.argsort(combined)[-top_k:][::-1]

    # Deduplicate: skip chunks that share >80% content with already-selected chunks
    selected = []
    for idx in top_indices:
        chunk_text = chunks[idx]['text']
        is_duplicate = any(
            jaccard_similarity(chunk_text, s['text']) > 0.8
            for s in selected
        )
        if not is_duplicate:
            selected.append(chunks[idx])
        if len(selected) >= top_k:
            break

    return selected

def compress_code_context(
    file_path: str,
    file_content: str,
    target_symbols: List[str],
    compress_model
) -> str:
    """Compress a file into a context-efficient summary.

    Instead of including the full file, generate a compressed
    representation that preserves the structural information
    the model needs for reasoning.
    """
    prompt = f"""Analyze this Python file and produce a compressed context summary.

File: {file_path}

{file_content}

Extract:
1. All function/class signatures with their type annotations
2. Dependencies (imports)
3. For each symbol matching {target_symbols}: its implementation
4. Any relevant docstrings or comments
5. Cross-references to other modules

Format as concise Python-like pseudocode. Omit boilerplate.
"""

    compressed = compress_model.generate(prompt, max_tokens=1000)
    return compressed

from dataclasses import dataclass
from enum import Enum

class RelevanceTier(Enum):
    CRITICAL = 3    # Must include: target file, direct dependencies
    SUPPORTING = 2  # Should include: test files, type definitions
    CONTEXTUAL = 1  # Nice to have: related modules, docs
    NOISE = 0       # Exclude: unrelated files, boilerplate

@dataclass
class ScoredChunk:
    text: str
    relevance: RelevanceTier
    token_count: int
    score: float  # relevance_tier_weight * similarity_score

def prioritize_context(
    chunks: List[ScoredChunk],
    max_tokens: int = 8000
) -> List[ScoredChunk]:
    """Select chunks within a token budget, prioritizing relevance.

    Greedy selection: include highest-scoring chunks first
    until the token budget is exhausted.
    """
    # Sort by score descending
    sorted_chunks = sorted(chunks, key=lambda c: c.score, reverse=True)

    selected = []
    total_tokens = 0

    for chunk in sorted_chunks:
        if total_tokens + chunk.token_count > max_tokens:
            # If we have room for at least 200 tokens, try to include
            # a truncated version of this chunk
            remaining = max_tokens - total_tokens
            if remaining > 200 and chunk.relevance == RelevanceTier.CRITICAL:
                truncated = chunk.text[:remaining]
                selected.append(ScoredChunk(
                    text=truncated,
                    relevance=chunk.relevance,
                    token_count=remaining,
                    score=chunk.score
                ))
                total_tokens += remaining
            continue
        selected.append(chunk)
        total_tokens += chunk.token_count

    return selected

class ProgressiveContextAgent:
    """Agent that expands context incrementally.

    Strategy:
    1. Start with the minimum viable context (target file + query)
    2. Attempt the task
    3. If the model requests more information or produces
       low-confidence output, retrieve additional context
    4. Repeat up to a maximum expansion depth
    """

    def __init__(self, model, retriever, max_expansions=3):
        self.model = model
        self.retriever = retriever
        self.max_expansions = max_expansions

    def solve(self, task: str, initial_context: str) -> str:
        context = initial_context

        for depth in range(self.max_expansions):
            # Add a self-reflection prompt
            response = self.model.generate(
                f"""Task: {task}

Context:
{context}

Attempt the task. If you need more information,
respond with: NEED_MORE_CONTEXT: <description of what you need>

Otherwise, provide your solution."""
            )

            if not response.startswith("NEED_MORE_CONTEXT:"):
                return response

            # Model needs more context — retrieve it
            needed = response[len("NEED_MORE_CONTEXT:"):].strip()
            additional_chunks = self.retriever.retrieve(needed, top_k=3)

            additional_text = "\n\n--- Additional Context ---\n\n"
            additional_text += "\n\n".join(c['text'] for c in additional_chunks)
            context += additional_text

        # If we exhaust expansions, do one final attempt with full context
        return self.model.generate(
            f"""Task: {task}

Context:
{context}

Provide your best solution."""
        )

class ContextWindowManager:
    """Manage context across a multi-turn agent session.

    Uses a sliding window with summarization:
    - Recent turns: kept verbatim
    - Older turns: progressively summarized
    - System context: always present
    """

    def __init__(self, model, max_context_tokens=8000):
        self.model = model
        self.max_context_tokens = max_context_tokens
        self.conversation_history = []
        self.summary = ""

    def add_turn(self, user_message: str, agent_response: str):
        self.conversation_history.append({
            'user': user_message,
            'agent': agent_response
        })
        self._manage_context()

    def _manage_context(self):
        """Compress old turns if context exceeds budget."""
        current_tokens = self._count_tokens()

        if current_tokens > self.max_context_tokens * 0.8:
            # Summarize the oldest 50% of turns
            turns_to_summarize = len(self.conversation_history) // 2
            if turns_to_summarize < 1:
                return

            old_turns = self.conversation_history[:turns_to_summarize]
            summary_text = "\n".join(
                f"User: {t['user']}\nAgent: {t['agent']}"
                for t in old_turns
            )

            self.summary = self.model.generate(
                f"""Summarize this conversation for context preservation.
Keep: decisions made, code written, files modified, open issues.
Drop: pleasantries, repeated explanations, verbose reasoning.

{summary_text}""",
                max_tokens=500
            )

            self.conversation_history = self.conversation_history[turns_to_summarize:]

    def get_context(self, new_user_message: str) -> str:
        parts = []
        if self.summary:
            parts.append(f"[Previous Conversation Summary]\n{self.summary}")

        for turn in self.conversation_history:
            parts.append(f"User: {turn['user']}\nAgent: {turn['agent']}")

        parts.append(f"User: {new_user_message}")
        return "\n\n".join(parts)

    def _count_tokens(self) -> int:
        text = self.get_context("")
        return len(text.split())  # Approximate token count

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

@dataclass
class ContextBudget:
    """Token budget allocation across context categories."""
    total: int = 8000
    system_prompt: int = 500
    task_description: int = 300
    target_code: int = 2000
    dependencies: int = 1500
    tests: int = 1000
    documentation: int = 500
    conversation_history: int = 1500

    @property
    def available_for_retrieval(self) -> int:
        return (self.target_code + self.dependencies + 
                self.tests + self.documentation)

class ContextCurationPipeline:
    """Full context curation pipeline for coding agents."""

    def __init__(self, model, embedder, budget: ContextBudget):
        self.model = model
        self.embedder = embedder
        self.budget = budget
        self._dedup_cache = {}

    def curate(self, query: str, repo_index) -> str:
        """Build an optimized context for the given query."""
        sections = {}

        # 1. Identify target files
        target_files = self._identify_target_files(query, repo_index)
        target_code = self._extract_target_code(target_files, query)
        sections['target_code'] = self._truncate_to_budget(
            target_code, self.budget.target_code
        )

        # 2. Resolve dependencies (imports, type references)
        dependencies = self._resolve_dependencies(target_code, repo_index)
        sections['dependencies'] = self._truncate_to_budget(
            dependencies, self.budget.dependencies
        )

        # 3. Find relevant tests
        tests = self._find_relevant_tests(target_files, query, repo_index)
        sections['tests'] = self._truncate_to_budget(
            tests, self.budget.tests
        )

        # 4. Semantic retrieval for additional context
        additional = self._semantic_retrieve(query, repo_index, top_k=5)
        additional = self._deduplicate(additional, sections.values())
        sections['documentation'] = self._truncate_to_budget(
            additional, self.budget.documentation
        )

        # 5. Assemble with priority ordering
        return self._assemble_context(sections)

    def _identify_target_files(self, query, index) -> List[str]:
        """Use filename matching and query analysis to find target files."""
        # Implementation: combine filename search, symbol search,
        # and semantic similarity on file-level embeddings
        ...

    def _extract_target_code(self, files, query) -> str:
        """Extract relevant functions/classes from target files."""
        # Parse each file, extract only functions/classes
        # that are referenced in the query or are the most
        # recently modified in the file
        ...

    def _resolve_dependencies(self, code, index) -> str:
        """Follow import statements to resolve type definitions."""
        # Parse imports, look up referenced modules,
        # extract only the specific classes/functions imported
        ...

    def _deduplicate(self, chunks, existing_sections) -> str:
        """Remove chunks that overlap with already-selected content."""
        existing_text = "\n".join(str(s) for s in existing_sections)
        existing_hash = set(
            hashlib.md5(line.encode()).hexdigest()
            for line in existing_text.split('\n')
            if line.strip()
        )

        deduped_lines = []
        for chunk in chunks.split('\n'):
            line_hash = hashlib.md5(chunk.encode()).hexdigest()
            if line_hash not in existing_hash and chunk.strip():
                deduped_lines.append(chunk)

        return "\n".join(deduped_lines)

    def _assemble_context(self, sections: dict) -> str:
        """Assemble context sections with clear delimiters.

        Ordering matters: place most relevant content
        at the beginning and end (avoiding the "lost in the middle" zone).
        """
        parts = []

        # Critical context first (primacy effect)
        parts.append(f"## Target Code\n{sections.get('target_code', '')}")

        # Supporting context in the middle
        parts.append(f"## Dependencies\n{sections.get('dependencies', '')}")
        parts.append(f"## Related Tests\n{sections.get('tests', '')}")

        # Additional context last (recency effect)
        parts.append(f"## Additional Context\n{sections.get('documentation', '')}")

        return "\n\n---\n\n".join(parts)

    def _truncate_to_budget(self, text: str, budget: int) -> str:
        """Truncate text to fit within token budget."""
        tokens = text.split()
        if len(tokens) <= budget:
            return text

        # Try to truncate at a logical boundary (function end, blank line)
        truncated = ' '.join(tokens[:budget])

        # Find the last complete function or block
        for boundary in ['\ndef ', '\nclass ', '\n
', '\n#']:
            last_pos = truncated.rfind(boundary)
            if last_pos > budget * 0.5:  # Only cut if we keep >50%
                truncated = truncated[:last_pos]
                break

        return truncated + "\n\n# [Truncated for context budget]"

---

## Part VII: Building a Context Budget System — A Practical Implementation

Theory is only useful if you can operationalize it. Below is a production-ready framework for implementing context budgeting in a coding agent. This is not pseudocode — it's a pattern you can adapt directly into your agent's orchestration layer.

### The ContextBudget Class

@property
def effective_score(self) -> float:
    """Combine priority, relevance, and recency into a single score."""
    recency_decay = max(0.0, 1.0 - (time.time() - self.timestamp) / 3600)
    return (self.priority.value * 0.4 +
            self.relevance_score * 0.4 +
            recency_decay * 0.2)

@property
def fingerprint(self) -> str:
    """Hash for deduplication."""
    return hashlib.md5(self.content.encode()).hexdigest()

Key insight: The context window is not a free-for-all.
Every token added displaces another token. This class
enforces that trade-off explicitly.
"""

def __init__(self, max_tokens: int = 128_000):
    self.max_tokens = max_tokens
    self._items: List[ContextItem] = []
    self._seen_fingerprints: set = set()
    self._relevance_filter: Optional[Callable] = None
    self._on_eviction: Optional[Callable] = None

def set_relevance_filter(self, filter_fn: Callable[[str, str], float]):
    """
    Inject a relevance filter function.
    Signature: filter_fn(item_content, task_description) -> float [0, 1]
    """
    self._relevance_filter = filter_fn

def set_eviction_callback(self, callback: Callable[[ContextItem], None]):
    """Called when an item is evicted — useful for logging/metrics."""
    self._on_eviction = callback

def add(self, content: str, priority: Priority, source: str,
        task_description: str = "") -> bool:
    """
    Attempt to add an item to the context budget.
    Returns True if added, False if rejected (duplicate or over budget).
    """
    # Deduplication check
    fp = hashlib.md5(content.encode()).hexdigest()
    if fp in self._seen_fingerprints:
        return False

    # Estimate token count (rough: 1 token ≈ 4 chars for English/code)
    token_count = max(1, len(content) // 4)

    # Compute relevance score
    relevance = 1.0
    if self._relevance_filter and task_description:
        relevance = self._relevance_filter(content, task_description)

    item = ContextItem(
        content=content,
        priority=priority,
        source=source,
        token_count=token_count,
        relevance_score=relevance,
    )

    # Check if we can fit it
    current_total = sum(i.token_count for i in self._items)
    if current_total + token_count > self.max_tokens:
        # Try to evict lowest-scoring items to make room
        if not self._evict_to_fit(token_count):
            return False

    self._items.append(item)
    self._seen_fingerprints.add(fp)
    return True

def _evict_to_fit(self, needed_tokens: int) -> bool:
    """Evict lowest-scoring items until we have room."""
    current_total = sum(i.token_count for i in self._items)
    available = self.max_tokens - current_total

    if available >= needed_tokens:
        return True

    # Sort by effective score (lowest first) — evict worst first
    sorted_items = sorted(self._items, key=lambda i: i.effective_score)

    for item in sorted_items:
        if available >= needed_tokens:
            return True
        if item.priority == Priority.CRITICAL:
            # Never evict critical items
            continue
        available += item.token_count
        self._items.remove(item)
        self._seen_fingerprints.discard(item.fingerprint)
        if self._on_eviction:
            self._on_eviction(item)

    return available >= needed_tokens

def render(self) -> str:
    """Render all items in priority order for the LLM."""
    sorted_items = sorted(
        self._items,
        key=lambda i: i.effective_score,
        reverse=True
    )
    sections = []
    for item in sorted_items:
        sections.append(f"[{item.priority.name}|{item.source}]\n{item.content}")
    return "\n\n---\n\n".join(sections)

def stats(self) -> Dict:
    """Return budget utilization statistics."""
    total_used = sum(i.token_count for i in self._items)
    by_priority = {}
    for item in self._items:
        p = item.priority.name
        by_priority[p] = by_priority.get(p, 0) + item.token_count
    return {
        "total_tokens_used": total_used,
        "max_tokens": self.max_tokens,
        "utilization_pct": round(total_used / self.max_tokens * 100, 1),
        "item_count": len(self._items),
        "by_priority": by_priority,
    }

### Usage Example: A Realistic Coding Task

# Task: "Fix the race condition in the order processing pipeline"
task = "Fix the race condition in the order processing pipeline"

# 1. System prompt (always critical)
budget.add(
    "You are an expert software engineer. Focus on correctness and clarity.",
    Priority.CRITICAL, "system_prompt"
)

# 2. The user's actual request
budget.add(
    task,
    Priority.CRITICAL, "user_request"
)

# 3. The relevant file — this is what matters
budget.add(
    """# order_processor.py

async def process_order(self, order: Order) -> Order:
    # Race condition: multiple coroutines can read _orders
    # simultaneously while another is modifying it
    current_orders = self._orders.copy()  # Not atomic with append below
    order.status = OrderStatus.PROCESSING
    self._orders.append(order)  # Could be interleaved with another append
    await self._validate(order)
    order.status = OrderStatus.COMPLETED
    return order

async def _validate(self, order: Order):
    await asyncio.sleep(0.1)  # Simulates I/O
    if order.total <= 0:
        raise ValueError("Invalid order total")

# 4. Related test file
budget.add(
    """# test_order_processor.py

# 5. A completely irrelevant file that got pulled in by a naive retriever
budget.add(
    """# user_auth.py

async def login(self, username: str, password: str) -> str:
    # Authentication logic...
    token = secrets.token_hex(32)
    self._sessions[token] = username
    return token

async def logout(self, token: str):
    self._sessions.pop(token, None)

# 6. Another irrelevant file
budget.add(
    """# email_service.py

# 7. A duplicate of the order processor (naive retrieval returns it twice)
budget.add(
    """# order_processor.py

async def process_order(self, order: Order) -> Order:
    current_orders = self._orders.copy()
    order.status = OrderStatus.PROCESSING
    self._orders.append(order)
    await self._validate(order)
    order.status = OrderStatus.COMPLETED
    return order

print("=== Context Budget Stats ===")
for key, value in budget.stats().items():
    print(f"  {key}: {value}")

print("\n=== Rendered Context (priority-ordered) ===")
print(budget.render()[:2000])  # Truncate for display

print("\n=== What the agent should focus on ===")
print("The race condition is in process_order(): the lock exists but is never acquired.")
print("The fix: wrap the read-modify-write sequence in an async with self._lock: block.")

### Output Analysis

Running this demonstrates three key behaviors:

1. **The duplicate is silently rejected** — the fingerprint check prevents the same file from consuming budget twice.
2. **Low-priority irrelevant files score lower** — `user_auth.py` and `email_service.py` will be the first candidates for eviction if the budget tightens.
3. **The critical and high-priority items dominate the rendered output** — the agent sees the relevant code first and with the most prominence.

---

## Part VIII: The Relevance Filter — A Lightweight Implementation

The `relevance_filter` callback in the budget system is where most of the magic happens. Here's a practical implementation that doesn't require a separate LLM call:

This is not perfect, but it's fast enough to run on every context item
and catches the most egregious irrelevancies.
"""

def __init__(self, min_overlap_ratio: float = 0.15):
    self.min_overlap_ratio = min_overlap_ratio
    self._stop_words: Set[str] = {
        "the", "a", "an", "is", "are", "was", "were", "be", "been",
        "being", "have", "has", "had", "do", "does", "did", "will",
        "would", "could", "should", "may", "might", "shall", "can",
        "to", "of", "in", "for", "on", "with", "at", "by", "from",
        "as", "into", "through", "during", "before", "after", "and",
        "but", "or", "nor", "not", "so", "yet", "both", "either",
        "neither", "each", "every", "all", "any", "few", "more",
        "most", "other", "some", "such", "no", "only", "own", "same",
        "than", "too", "very", "just", "because", "if", "when",
        "where", "how", "what", "which", "who", "whom", "this",
        "that", "these", "those", "import", "from", "def", "class",
        "return", "async", "await", "self", "None", "True", "False",
        "List", "Dict", "Optional", "Tuple", "Set",
    }

def _extract_keywords(self, text: str) -> Set[str]:
    """Extract meaningful keywords from text."""
    # Remove code syntax noise
    text = re.sub(r'import\s+\w+', '', text)
    text = re.sub(r'from\s+\w+', '', text)
    text = re.sub(r'def\s+\w+', '', text)
    text = re.sub(r'class\s+\w+', '', text)
    # Tokenize
    tokens = re.findall(r'[a-zA-Z_][a-zA-Z0-9_]*', text.lower())
    return {t for t in tokens if t not in self._stop_words and len(t) > 2}

def __call__(self, item_content: str, task_description: str) -> float:
    """
    Compute relevance score between an item and the task.
    Returns 0.0 (irrelevant) to 1.0 (highly relevant).
    """
    task_keywords = self._extract_keywords(task_description)
    item_keywords = self._extract_keywords(item_content)

    if not task_keywords:
        return 0.5  # Neutral if we can't determine task keywords

    overlap = task_keywords & item_keywords
    # Use Jaccard-like metric but weighted toward task coverage
    task_coverage = len(overlap) / len(task_keywords)
    item_precision = len(overlap) / max(len(item_keywords), 1)

    # Blend: we care more about whether the item covers the task's concepts
    score = 0.7 * task_coverage + 0.3 * item_precision
    return min(1.0, max(0.0, score))

This filter is fast (microseconds per call), deterministic, and catches the most obvious irrelevancies. For production systems, you can layer it with a lightweight embedding-based similarity check for cases where keyword overlap fails but semantic relevance is high.

---

## Part IX: Context Budgeting Strategies — A Decision Framework

Not every task deserves the same context budget treatment. Here's a decision framework:

| Task Type | Strategy | Rationale |
|-----------|----------|-----------|
| **Single-file fix** | Aggressive pruning — keep only the target file + its imports | The answer is local; extra context is pure noise |
| **Cross-module refactor** | Moderate pruning — keep all touched modules + interface definitions | Need to see the full change surface |
| **Bug investigation** | Layered exploration — start minimal, add context only when the first pass fails | Avoid anchoring on wrong hypotheses |
| **Feature implementation** | Schema-heavy — prioritize type definitions, interfaces, and existing patterns over implementation details | The agent needs to match existing conventions |
| **Code review** | Full context — the entire diff + surrounding files | Reviews require holistic understanding |

The key insight: **there is no one-size-fits-all context budget**. The right amount of context depends on the task's locality. A bug in a single function needs 500 tokens of context, not 50,000.

### Implementing Adaptive Budgeting

def __init__(self, base_budget: int = 32_000):
    self.base_budget = base_budget

def determine_budget(self, task_description: str, 
                      files_in_scope: int,
                      has_tests: bool) -> int:
    """
    Dynamically size the context budget.

    Heuristic: more files in scope = more context needed,
    but with diminishing returns.
    """
    import math

    # Base budget adjusted for file count
    # Diminishing returns: log scale
    file_factor = math.log2(files_in_scope + 1) * 4000

    # Tests add value — the agent can validate its understanding
    test_bonus = 4000 if has_tests else 0

    # Cap at a reasonable maximum
    budget = min(self.base_budget + file_factor + test_bonus, 64_000)

    # Floor: never go below a minimum viable context
    budget = max(budget, 8_000)

    return budget

def should_expand(self, initial_result: str, 
                   task_description: str) -> bool:
    """
    Decide whether to retry with more context after a failed attempt.

    Signals for expansion:
    - Agent asks for more information
    - Agent produces a generic response
    - Agent references symbols not in its context
    """
    expansion_signals = [
        "I don't have enough context",
        "Can you provide",
        "I'm not sure which",
        "Please clarify",
        "I need to see",
        "Without seeing",
    ]
    for signal in expansion_signals:
        if signal.lower() in initial_result.lower():
            return True

    # If the response is very short, it might be a refusal or confusion
    if len(initial_result) < 100:
        return True

    return False

---

## Part X: The Broader Implications — What This Means for the Industry

The context trap is not just a technical problem. It has organizational and economic consequences that are worth naming explicitly.

### The False Promise of "Just Make the Window Bigger"

Every model release cycle brings a new context window size. 4K became 8K, 8K became 32K, 32K became 128K, and now we're seeing 1M+ token windows. The marketing narrative is always the same: "Now your AI can read entire codebases."

This narrative is seductive because it's simple. It tells engineers that the solution to context problems is more context. But as we've established, this is backwards. More context without better selection leads to worse performance, not better.

The real question is not "how big is the window?" but "how well is the window used?" A 32K window with disciplined budgeting will outperform a 128K window stuffed with irrelevant files.

### The Economic Implication

Context is not free. Even with efficient attention mechanisms, processing 128K tokens costs more than processing 32K tokens — in latency, in compute, and in the opportunity cost of tokens that could have been spent on more relevant information.

Teams that treat context as a free resource are essentially throwing money away. Every token of irrelevant context is a token that could have been spent on the information that actually matters.

### The Human Analogy

Consider a senior engineer debugging a production issue. They don't read the entire codebase. They don't read every log file. They form a hypothesis, look at the specific code path involved, check the relevant logs, and iterate. They use their working memory (which is roughly 4-7 items) effectively by focusing on what's relevant to the current hypothesis.

AI coding agents should work the same way. The context window is the agent's working memory. Working memory is a scarce resource. The teams that understand this will build better agents.

---

## Part XI: A Practical Checklist for Context Engineering

Here's a concise checklist you can use to evaluate and improve your coding agent's context pipeline:

### 1. Measure Your Current State
- [ ] What is the average token count of your agent's context?
- [ ] What percentage of context tokens are relevant to the current task?
- [ ] How many duplicate or near-duplicate items appear in your context?
- [ ] What is your agent's success rate on tasks with <8K context vs. >32K context?

### 2. Implement Deduplication
- [ ] Fingerprint every context item before adding it
- [ ] Reject exact duplicates silently
- [ ] Flag near-duplicates for review (same file, different versions)

### 3. Implement Prioritization
- [ ] Assign priority levels to every context item
- [ ] Implement a scoring function that combines priority, relevance, and recency
- [ ] Render context in priority order (most important first)

### 4. Implement Relevance Filtering
- [ ] Add a keyword-based relevance filter as a first pass
- [ ] Optionally add an embedding-based similarity check for semantic relevance
- [ ] Set a minimum relevance threshold below which items are discarded

### 5. Implement Budget Enforcement
- [ ] Set a hard token limit for your context window
- [ ] Implement eviction logic that removes lowest-scoring items first
- [ ] Never evict critical items (system prompt, user request)
- [ ] Log evictions for analysis and tuning

### 6. Implement Adaptive Sizing
- [ ] Adjust budget based on task type (single-file fix vs. cross-module refactor)
- [ ] Implement retry-with-more-context when the agent signals confusion
- [ ] Set both minimum and maximum budget bounds

### 7. Monitor and Iterate
- [ ] Track context utilization percentage over time
- [ ] Track agent success rate as a function of context size
- [ ] A/B test context strategies on a representative task set
- [ ] Review evicted items periodically — are you evicting the right things?

---

## Conclusion: The Discipline of Less

The context trap is a reminder that in AI engineering, as in all engineering, more is not always better. The context window is a resource, not a repository. It should be treated with the same discipline as memory, bandwidth, or compute — carefully budgeted, strategically allocated, and ruthlessly optimized.

The teams that will build the best coding agents are not the ones chasing the largest context windows. They are the ones who understand that **the right information, presented clearly, beats the right information buried under noise every single time.**

Build your context pipeline like you build your code: with intention, with tests, and with a deep respect for the cost of every token.

The future of AI coding agents is not bigger contexts. It's smarter contexts. And that's a future worth building.