contextops 0.1.0__py3-none-any.whl

contextops/analyzers/tokens.py

@@ -0,0 +1,76 @@
+"""
+Token Analyzer.
+
+Uses tiktoken to count tokens per ContextItem and estimate costs.
+Nothing fancy — just reliable counting and cost math.
+"""
+
+from __future__ import annotations
+
+import tiktoken
+
+from contextops.core.models import ContextBundle, TokenBreakdown
+
+
+# ── Pricing per 1K input tokens (USD) — GPT-4o as default reference ─────
+# Users can override this; these are just sensible defaults for estimation.
+DEFAULT_COST_PER_1K_TOKENS: float = 0.005  # $5 per 1M input tokens
+
+
+def count_tokens(text: str, model: str = "gpt-4o") -> int:
+    """
+    Count tokens for a given text using tiktoken.
+
+    Args:
+        text: The text to tokenize.
+        model: The model name for the encoding. Defaults to gpt-4o.
+
+    Returns:
+        The number of tokens.
+    """
+    try:
+        encoding = tiktoken.encoding_for_model(model)
+    except KeyError:
+        # Fallback to cl100k_base (covers GPT-4, GPT-3.5, etc.)
+        encoding = tiktoken.get_encoding("cl100k_base")
+
+    return len(encoding.encode(text))
+
+
+def analyze_tokens(
+    bundle: ContextBundle,
+    model: str = "gpt-4o",
+    cost_per_1k: float = DEFAULT_COST_PER_1K_TOKENS,
+) -> TokenBreakdown:
+    """
+    Count tokens for every item in the bundle and produce a breakdown.
+
+    Side effect: sets token_count on each ContextItem in the bundle.
+
+    Args:
+        bundle: The context bundle to analyze.
+        model: Model name for tiktoken encoding selection.
+        cost_per_1k: Cost per 1,000 input tokens in USD.
+
+    Returns:
+        A TokenBreakdown with totals, per-type distribution, and cost estimate.
+    """
+    by_type: dict[str, int] = {}
+    total = 0
+
+    for item in bundle.items:
+        tokens = count_tokens(item.content, model=model)
+        item.token_count = tokens
+        total += tokens
+
+        type_key = item.type.value
+        by_type[type_key] = by_type.get(type_key, 0) + tokens
+
+    cost = (total / 1000) * cost_per_1k
+
+    return TokenBreakdown(
+        total_tokens=total,
+        by_type=by_type,
+        estimated_cost_usd=cost,
+        wasted_tokens=0,  # filled in later by the engine after redundancy analysis
+    )

contextops/api/__init__.py

@@ -0,0 +1 @@
+# API subpackage

contextops/api/diff.py

@@ -0,0 +1,124 @@
+"""
+ContextOps Diff API.
+
+Computes a deterministic delta between two context payloads.
+Provides the data model and logic for `contextops diff`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from contextops.api.inspect import inspect_context
+from contextops.core.models import AnalysisResult, Recommendation
+
+
+@dataclass
+class ContextDiffResult:
+    """The computed difference between two context analysis results."""
+    # Source results
+    result_a: AnalysisResult
+    result_b: AnalysisResult
+
+    # Numeric Deltas (B - A)
+    score_delta: int
+    token_delta: int
+    waste_delta: int
+    cost_delta: float
+
+    # Structure Deltas (B - A)
+    structure_delta: dict[str, float]
+
+    # Recommendation Lifecycle
+    resolved_recommendations: list[Recommendation] = field(default_factory=list)
+    new_recommendations: list[Recommendation] = field(default_factory=list)
+    persisting_recommendations: list[Recommendation] = field(default_factory=list)
+
+    @property
+    def net_impact(self) -> str:
+        """Categorical summary of the overall change."""
+        if self.score_delta > 0:
+            return "IMPROVEMENT"
+        elif self.score_delta < 0:
+            return "DEGRADATION"
+        else:
+            return "NEUTRAL"
+
+
+def get_recommendation_id(rec: Recommendation) -> str:
+    """
+    Generate a deterministic, stable ID for a recommendation.
+    
+    This is critical for the set-based diff logic. We hash the normalized issue string.
+    Do NOT use fuzzy matching or ML embeddings here.
+    """
+    # Normalize: lowercase and collapse all whitespace to single spaces
+    normalized = re.sub(r'\s+', ' ', rec.issue.lower().strip())
+    return hashlib.md5(normalized.encode("utf-8")).hexdigest()[:12]
+
+
+def diff_contexts(
+    raw_input_a: str | list[dict[str, Any]] | dict[str, Any],
+    raw_input_b: str | list[dict[str, Any]] | dict[str, Any],
+) -> ContextDiffResult:
+    """
+    Compare two context payloads and return a deterministic diff result.
+    """
+    result_a = inspect_context(raw_input_a)
+    result_b = inspect_context(raw_input_b)
+
+    return diff_analysis_results(result_a, result_b)
+
+
+def diff_analysis_results(result_a: AnalysisResult, result_b: AnalysisResult) -> ContextDiffResult:
+    """Compare two pre-computed AnalysisResult objects."""
+    
+    # 1. Numeric Deltas
+    score_delta = result_b.score - result_a.score
+    token_delta = result_b.token_breakdown.total_tokens - result_a.token_breakdown.total_tokens
+    waste_delta = result_b.token_breakdown.wasted_tokens - result_a.token_breakdown.wasted_tokens
+    cost_delta = result_b.token_breakdown.estimated_cost_usd - result_a.token_breakdown.estimated_cost_usd
+
+    # 2. Structure Deltas
+    structure_delta = {
+        "redundancy": result_b.score_breakdown.redundancy_penalty - result_a.score_breakdown.redundancy_penalty,
+        "density": result_b.score_breakdown.density_penalty - result_a.score_breakdown.density_penalty,
+        "structure_imbalance": result_b.score_breakdown.structure_penalty - result_a.score_breakdown.structure_penalty,
+        "concentration": result_b.score_breakdown.concentration_penalty - result_a.score_breakdown.concentration_penalty,
+    }
+
+    # 3. Recommendation Lifecycle
+    dict_a = {get_recommendation_id(r): r for r in result_a.recommendations}
+    dict_b = {get_recommendation_id(r): r for r in result_b.recommendations}
+
+    ids_a = set(dict_a.keys())
+    ids_b = set(dict_b.keys())
+
+    resolved_ids = ids_a - ids_b
+    new_ids = ids_b - ids_a
+    persisting_ids = ids_a & ids_b
+
+    resolved = [dict_a[rid] for rid in resolved_ids]
+    new = [dict_b[nid] for nid in new_ids]
+    persisting = [dict_b[pid] for pid in persisting_ids]  # Use B's updated version
+
+    # Sort deterministically by severity/impact
+    resolved.sort(key=lambda r: (-r.impact_score, -r.token_savings, r.issue))
+    new.sort(key=lambda r: (-r.impact_score, -r.token_savings, r.issue))
+    persisting.sort(key=lambda r: (-r.impact_score, -r.token_savings, r.issue))
+
+    return ContextDiffResult(
+        result_a=result_a,
+        result_b=result_b,
+        score_delta=score_delta,
+        token_delta=token_delta,
+        waste_delta=waste_delta,
+        cost_delta=cost_delta,
+        structure_delta=structure_delta,
+        resolved_recommendations=resolved,
+        new_recommendations=new,
+        persisting_recommendations=persisting,
+    )

contextops/api/inspect.py

@@ -0,0 +1,52 @@
+"""
+ContextOps Programmatic API.
+
+This is the primary interface for using ContextOps as a library.
+Import and call `inspect_context()` with any supported input format.
+
+Example:
+    from contextops.api.inspect import inspect_context
+
+    result = inspect_context({
+        "system": "You are a helpful assistant.",
+        "chunks": ["chunk 1", "chunk 2"],
+    })
+    print(result.score)
+    print(json.dumps(result.to_dict(), indent=2))
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contextops.core.config import ContextOpsConfig
+from contextops.core.engine import analyze
+from contextops.core.models import AnalysisResult
+from contextops.core.normalizer import normalize
+
+
+def inspect_context(
+    raw_input: str | list[dict[str, Any]] | dict[str, Any],
+    model: str = "gpt-4o",
+    cost_per_1k: float = 0.005,
+    config: ContextOpsConfig | None = None,
+) -> AnalysisResult:
+    """
+    Analyze an LLM context and return a full AnalysisResult.
+
+    This is the main entry point for the ContextOps library.
+
+    Args:
+        raw_input: Raw LLM context in any supported format:
+            - str: treated as a system prompt
+            - list[dict]: OpenAI-style message list
+            - dict: structured dict with system/messages/chunks/memory/tools
+        model: Model name for tiktoken encoding.
+        cost_per_1k: Cost per 1K input tokens in USD.
+        config: Optional custom threshold configuration.
+
+    Returns:
+        AnalysisResult containing score, breakdown, findings, and recommendations.
+    """
+    bundle = normalize(raw_input)
+    return analyze(bundle, model=model, cost_per_1k=cost_per_1k, config=config)

contextops/api/stability.py

@@ -0,0 +1,264 @@
+"""
+ContextOps Stability API.
+
+Runs deterministic perturbations against a context bundle to verify the scoring
+engine behaves logically. Testing properties and invariants over specific scores.
+"""
+
+from __future__ import annotations
+
+import copy
+import random
+from dataclasses import dataclass, field
+from typing import Any
+
+from contextops.core.engine import analyze
+from contextops.core.models import ContextItem, ContextType, RedundancyClassification
+from contextops.core.normalizer import normalize
+
+
+@dataclass
+class InvariantResult:
+    """The outcome of a single stability invariant check."""
+    name: str
+    passed: bool
+    severity: str = "critical"
+    diagnostic_info: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class StabilityReport:
+    """Complete stability report containing all invariant checks."""
+    base_score: int = 0
+    base_tokens: int = 0
+    base_waste_tokens: int = 0
+    invariants: list[InvariantResult] = field(default_factory=list)
+
+    @property
+    def score_percentage(self) -> int:
+        """Percentage of invariants that passed."""
+        if not self.invariants:
+            return 0
+        passed = sum(1 for inv in self.invariants if inv.passed)
+        return int((passed / len(self.invariants)) * 100)
+
+
+def run_stability_report(raw_input: str | list[dict] | dict) -> StabilityReport:
+    """
+    Run the formal sanity-check layer for the scoring engine.
+    
+    Applies deterministic mutations to the context bundle and verifies
+    that the system behaves logically.
+    """
+    base_bundle = normalize(raw_input)
+    base_result = analyze(base_bundle)
+    base_score = base_result.score
+
+    invariants = []
+
+    # 1. Shuffle Invariant
+    # ContextOps should care about content, not ordering.
+    shuffled_bundle = copy.deepcopy(base_bundle)
+    shuffled_bundle.items = sorted(shuffled_bundle.items, key=lambda x: x.id, reverse=True)
+    shuffle_result = analyze(shuffled_bundle)
+    invariants.append(InvariantResult(
+        name="Shuffle Invariant",
+        passed=(shuffle_result.score == base_score),
+        severity="critical",
+    ))
+
+    # 2. Duplicate Injection
+    # Injecting an exact duplicate must be detected and penalized.
+    dup_passed = True
+    dup_diagnostic = {}
+    if base_bundle.items:
+        retrieval_items = base_bundle.items_by_type(ContextType.RETRIEVAL)
+        if not retrieval_items:
+            retrieval_items = base_bundle.items
+
+        dup_bundle = copy.deepcopy(base_bundle)
+        item_to_dup = copy.deepcopy(retrieval_items[0])
+        item_to_dup.id = item_to_dup.id + "_dup"
+        dup_bundle.items.append(item_to_dup)
+
+        dup_result = analyze(dup_bundle)
+        score_delta = dup_result.score - base_score
+
+        dup_passed = (dup_result.score < base_score)
+        dup_diagnostic = {
+            "Score Delta": f"{score_delta:+d}",
+            "Expected Direction": "Decrease",
+        }
+    else:
+        dup_diagnostic = {"Note": "No items to duplicate"}
+
+    invariants.append(InvariantResult(
+        name="Duplicate Injection",
+        passed=dup_passed,
+        severity="critical",
+        diagnostic_info=dup_diagnostic
+    ))
+
+    # 3. Noise Injection
+    # Pure synthetic noise shouldn't magically improve the score.
+    noise_bundle = copy.deepcopy(base_bundle)
+    noise_content = " ".join([f"TOKEN_{i:04d}" for i in range(1, 101)])
+    noise_item = ContextItem(
+        type=ContextType.RETRIEVAL,
+        content=noise_content,
+        source="synthetic_noise"
+    )
+    noise_bundle.items.append(noise_item)
+    noise_result = analyze(noise_bundle)
+    noise_score_delta = noise_result.score - base_score
+    invariants.append(InvariantResult(
+        name="Noise Injection",
+        passed=(noise_result.score <= base_score),
+        severity="important",
+        diagnostic_info={
+            "Score Delta": f"{noise_score_delta:+d}",
+            "Expected Direction": "<= 0",
+        }
+    ))
+
+    # 4. Chunk Split Invariant
+    # Splitting content shouldn't dramatically alter conclusions.
+    split_passed = True
+    split_diagnostic = {}
+    if base_bundle.items:
+        split_bundle = copy.deepcopy(base_bundle)
+        non_system_indices = [
+            i for i, item in enumerate(split_bundle.items) 
+            if item.type != ContextType.SYSTEM
+        ]
+        if non_system_indices:
+            longest_idx = max(non_system_indices, key=lambda i: len(split_bundle.items[i].content))
+            longest_item = split_bundle.items.pop(longest_idx)
+
+            mid = len(longest_item.content) // 2
+            part1 = longest_item.content[:mid]
+            part2 = longest_item.content[mid:]
+
+            item1 = ContextItem(type=longest_item.type, content=part1, source=longest_item.source)
+            item2 = ContextItem(type=longest_item.type, content=part2, source=longest_item.source)
+
+            split_bundle.items.append(item1)
+            split_bundle.items.append(item2)
+
+            split_result = analyze(split_bundle)
+            split_delta = split_result.score - base_score
+
+            DEFAULT_SPLIT_TOLERANCE = 10
+            split_passed = (abs(split_delta) <= DEFAULT_SPLIT_TOLERANCE)
+            split_diagnostic = {
+                "Base Score": base_score,
+                "Split Score": split_result.score,
+                "Delta": f"{split_delta:+d}",
+            }
+        else:
+            split_diagnostic = {"Note": "No non-system items to split"}
+    else:
+        split_diagnostic = {"Note": "No items to split"}
+
+    invariants.append(InvariantResult(
+        name="Chunk Split Invariant",
+        passed=split_passed,
+        severity="important",
+        diagnostic_info=split_diagnostic
+    ))
+
+    # 5. Boilerplate Invariant
+    # Tests the core philosophy: expected repetition vs real waste.
+    bp_bundle = copy.deepcopy(base_bundle)
+    bp_item = ContextItem(
+        type=ContextType.SYSTEM,
+        content="You are a helpful assistant. Please follow all instructions carefully.",
+        source="system"
+    )
+    bp_item_dup = copy.deepcopy(bp_item)
+    bp_item_dup.id = bp_item.id + "_dup"
+
+    bp_bundle.items.extend([bp_item, bp_item_dup])
+    bp_result = analyze(bp_bundle)
+
+    # Only check findings between the two injected boilerplate items
+    bp_ids = {bp_item.id, bp_item_dup.id}
+    bp_pair_findings = [
+        f for f in bp_result.redundancy_findings
+        if f.item_a_id in bp_ids and f.item_b_id in bp_ids
+    ]
+
+    detected_bp = any(
+        f.classification == RedundancyClassification.BOILERPLATE
+        for f in bp_pair_findings
+    )
+    detected_redundant = any(
+        f.classification == RedundancyClassification.REDUNDANT_CONTEXT
+        for f in bp_pair_findings
+    )
+
+    invariants.append(InvariantResult(
+        name="Boilerplate Invariant",
+        passed=(detected_bp and not detected_redundant),
+        severity="critical",
+        diagnostic_info={
+            "Detected as BOILERPLATE": detected_bp,
+            "Detected as REDUNDANT_CONTEXT": detected_redundant,
+        }
+    ))
+
+    # 6. Semantic Blindness Guard
+    # Semantic blindness is a feature, not a bug. Verify it stays that way.
+    SEMANTIC_BLINDNESS_CASES = [
+        (
+            "The startup raised one million dollars.",
+            "The company secured $1M in funding."
+        ),
+        (
+            "The API request timed out after thirty seconds.",
+            "The endpoint exceeded its 30-second timeout threshold."
+        ),
+        (
+            "The quick brown fox jumps over the lazy dog.",
+            "A fast dark-colored canine leaped above a resting dog."
+        ),
+    ]
+
+    sb_passed = True
+    sb_diagnostics = []
+
+    for case_idx, (text1, text2) in enumerate(SEMANTIC_BLINDNESS_CASES):
+        sb_bundle = copy.deepcopy(base_bundle)
+        item1 = ContextItem(type=ContextType.RETRIEVAL, content=text1, source=f"sb_a_{case_idx}")
+        item2 = ContextItem(type=ContextType.RETRIEVAL, content=text2, source=f"sb_b_{case_idx}")
+        sb_bundle.items.extend([item1, item2])
+
+        sb_result = analyze(sb_bundle)
+
+        has_redundancy = any(
+            f.classification == RedundancyClassification.REDUNDANT_CONTEXT
+            and ((f.item_a_id == item1.id and f.item_b_id == item2.id) or
+                 (f.item_a_id == item2.id and f.item_b_id == item1.id))
+            for f in sb_result.redundancy_findings
+        )
+
+        if has_redundancy:
+            sb_passed = False
+            sb_diagnostics.append(f"Case {case_idx+1} triggered redundancy")
+
+    invariants.append(InvariantResult(
+        name="Semantic Blindness Guard",
+        passed=sb_passed,
+        severity="important",
+        diagnostic_info={
+            "Redundancy Detected": not sb_passed,
+            "Details": ", ".join(sb_diagnostics) if sb_diagnostics else "Clean across all cases",
+        }
+    ))
+
+    return StabilityReport(
+        base_score=base_score,
+        base_tokens=base_result.token_breakdown.total_tokens,
+        base_waste_tokens=base_result.token_breakdown.wasted_tokens,
+        invariants=invariants
+    )

contextops/cli/__init__.py

@@ -0,0 +1 @@
+# CLI subpackage