contextops 0.1.0__tar.gz

contextops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhijeet Baug
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contextops-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: contextops
+Version: 0.1.0
+Summary: Deterministic context linter for LLM applications — analyze, score, and optimize your LLM context payloads.
+Author: Abhijeet Baug
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Abhijeet777/contextops
+Project-URL: Repository, https://github.com/Abhijeet777/contextops
+Project-URL: Issues, https://github.com/Abhijeet777/contextops/issues
+Project-URL: Documentation, https://github.com/Abhijeet777/contextops#readme
+Project-URL: Changelog, https://github.com/Abhijeet777/contextops/blob/main/CHANGELOG.md
+Keywords: llm,context,observability,rag,token,optimization,linter,ci,deterministic,prompt-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# ContextOps
+
+**The deterministic context linter for LLM applications.**
+
+[![PyPI version](https://img.shields.io/pypi/v/contextops.svg)](https://pypi.org/project/contextops/)
+[![Python](https://img.shields.io/pypi/pyversions/contextops.svg)](https://pypi.org/project/contextops/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://img.shields.io/badge/CI-stable-brightgreen.svg)](STABILITY.md)
+
+ContextOps analyzes the context fed into your LLM and tells you what's broken — redundant chunks, wasted tokens, structural imbalance — with a **deterministic 0–100 score** and actionable fixes.
+
+Think of it as **ESLint for your LLM prompts**.
+
+---
+
+## Why ContextOps?
+
+Most LLM applications blindly stuff context into the prompt window. This leads to:
+
+- 💸 **Wasted spend** — paying for redundant tokens that don't improve output
+- 🔁 **Silent regressions** — a "small RAG change" floods the context with duplicates
+- 🏗️ **Structural drift** — retrieval chunks slowly dominate the entire prompt
+- 🎯 **No visibility** — teams have no way to measure context quality in CI
+
+ContextOps gives you that visibility. It runs in your CI pipeline, scores every context payload, and fails the build if quality degrades.
+
+---
+
+## Quick Start
+
+```bash
+pip install contextops
+```
+
+### See it in action
+
+```bash
+# Run the built-in demo — instant "wow moment"
+contextops demo
+```
+
+### Analyze your own context
+
+```bash
+# Full analysis with rich terminal output
+contextops inspect context.json
+
+# CI mode: fail if score drops below threshold
+contextops check context.json --min-score 70
+
+# Compare two snapshots for regressions
+contextops diff before.json after.json
+
+# JSON output for dashboards and automation
+contextops inspect context.json --json-output
+```
+
+### Python API
+
+```python
+from contextops.api.inspect import inspect_context
+
+result = inspect_context({
+    "system": "You are a helpful assistant.",
+    "chunks": [
+        {"content": "Refund policy: 30 days...", "source": "docs/refund.md"},
+        {"content": "Refund policy: within 30 days...", "source": "docs/refund.md"},
+    ],
+    "memory": ["User asked about refunds before."],
+})
+
+print(f"Score: {result.score}/100")
+print(f"Wasted tokens: {result.token_breakdown.wasted_tokens}")
+for rec in result.recommendations:
+    print(f"  → {rec.fix}")
+```
+
+---
+
+## What It Measures
+
+ContextOps computes a **0–100 Context Score** from four independent penalty dimensions:
+
+| Dimension | What It Detects | Max Penalty |
+|---|---|---|
+| **Redundancy** | Duplicate / near-duplicate chunks (N-gram + Jaccard) | 30 pts |
+| **Density** | Wasted tokens from structural bloat | 30 pts |
+| **Structure** | Imbalanced type distribution (e.g., retrieval > 70%) | 20 pts |
+| **Concentration** | Source dominance or highly imbalanced chunk distribution | 20 pts |
+
+```
+Context Score = 100 - (Redundancy + Density + Structure + Concentration)
+```
+
+Every penalty maps to a **specific finding** with **token savings** and an **actionable fix**.
+
+---
+
+## CI / CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Context Quality Gate
+
+on: [pull_request]
+
+jobs:
+  context-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install contextops
+
+      - name: Check context quality
+        run: contextops check prompts/context.json --min-score 75
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Score meets threshold — build passes |
+| `1` | Score below threshold — build fails |
+
+### Regression Detection
+
+```bash
+# Save a baseline
+contextops inspect prompts/v1.json --json-output > baseline.json
+
+# After changes, compare
+contextops diff baseline.json prompts/v2.json
+```
+
+---
+
+## Context File Format
+
+ContextOps accepts a JSON file with any combination of these keys:
+
+```json
+{
+    "system": "Your system prompt here",
+    "messages": [
+        {"role": "user", "content": "User question"}
+    ],
+    "chunks": [
+        {"content": "Retrieved chunk text", "source": "docs/page.md"}
+    ],
+    "memory": [
+        "Previous conversation context"
+    ],
+    "tools": [
+        {"name": "search_api", "output": "Tool response text"}
+    ]
+}
+```
+
+It also accepts raw OpenAI message lists:
+
+```json
+[
+    {"role": "system", "content": "You are helpful."},
+    {"role": "user", "content": "What is the refund policy?"}
+]
+```
+
+---
+
+## CLI Reference
+
+| Command | Purpose |
+|---|---|
+| `contextops inspect <file>` | Analyze and display results |
+| `contextops check <file> --min-score N` | CI gate with exit codes |
+| `contextops demo` | Built-in demo context |
+| `contextops stability <file>` | Deterministic stability report |
+| `contextops diff <file_a> <file_b>` | Compare two snapshots |
+
+### Flags
+
+| Flag | Commands | Purpose |
+|---|---|---|
+| `--json-output` | inspect, check | Machine-readable JSON output |
+| `--min-score N` | check | Minimum passing score (0–100) |
+| `--model <name>` | inspect, check | Target model for cost estimation |
+| `--explain` | inspect, check | Show detailed penalty reasoning |
+| `--config <file>` | inspect, check | Custom threshold config file |
+
+---
+
+## Design Principles
+
+1. **Deterministic** — Same input → same output. Always. No randomness, no embeddings, no LLM calls.
+2. **Explainable** — Every penalty maps to a real issue with a token count and a fix.
+3. **CI-native** — Designed for pipelines first. Exit codes, JSON output, threshold gating.
+4. **Zero network** — Runs entirely offline. No API keys, no external services.
+
+---
+
+## Stability Contract
+
+ContextOps ships with a formal [Stability Contract](STABILITY.md) that guarantees:
+
+- **Scoring determinism** — same input always produces the same score
+- **Schema stability** — JSON output fields never change within a major version
+- **Performance bounds** — sub-second for payloads up to 50,000 tokens
+- **Semantic versioning** — scoring formula changes require a major version bump
+
+This contract exists so teams can trust ContextOps in production CI pipelines.
+
+---
+
+## Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/Abhijeet777/contextops.git
+cd contextops
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run chaos stress tests
+pytest tests/test_chaos.py -v
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

contextops-0.1.0/README.md

@@ -0,0 +1,238 @@
+# ContextOps
+
+**The deterministic context linter for LLM applications.**
+
+[![PyPI version](https://img.shields.io/pypi/v/contextops.svg)](https://pypi.org/project/contextops/)
+[![Python](https://img.shields.io/pypi/pyversions/contextops.svg)](https://pypi.org/project/contextops/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://img.shields.io/badge/CI-stable-brightgreen.svg)](STABILITY.md)
+
+ContextOps analyzes the context fed into your LLM and tells you what's broken — redundant chunks, wasted tokens, structural imbalance — with a **deterministic 0–100 score** and actionable fixes.
+
+Think of it as **ESLint for your LLM prompts**.
+
+---
+
+## Why ContextOps?
+
+Most LLM applications blindly stuff context into the prompt window. This leads to:
+
+- 💸 **Wasted spend** — paying for redundant tokens that don't improve output
+- 🔁 **Silent regressions** — a "small RAG change" floods the context with duplicates
+- 🏗️ **Structural drift** — retrieval chunks slowly dominate the entire prompt
+- 🎯 **No visibility** — teams have no way to measure context quality in CI
+
+ContextOps gives you that visibility. It runs in your CI pipeline, scores every context payload, and fails the build if quality degrades.
+
+---
+
+## Quick Start
+
+```bash
+pip install contextops
+```
+
+### See it in action
+
+```bash
+# Run the built-in demo — instant "wow moment"
+contextops demo
+```
+
+### Analyze your own context
+
+```bash
+# Full analysis with rich terminal output
+contextops inspect context.json
+
+# CI mode: fail if score drops below threshold
+contextops check context.json --min-score 70
+
+# Compare two snapshots for regressions
+contextops diff before.json after.json
+
+# JSON output for dashboards and automation
+contextops inspect context.json --json-output
+```
+
+### Python API
+
+```python
+from contextops.api.inspect import inspect_context
+
+result = inspect_context({
+    "system": "You are a helpful assistant.",
+    "chunks": [
+        {"content": "Refund policy: 30 days...", "source": "docs/refund.md"},
+        {"content": "Refund policy: within 30 days...", "source": "docs/refund.md"},
+    ],
+    "memory": ["User asked about refunds before."],
+})
+
+print(f"Score: {result.score}/100")
+print(f"Wasted tokens: {result.token_breakdown.wasted_tokens}")
+for rec in result.recommendations:
+    print(f"  → {rec.fix}")
+```
+
+---
+
+## What It Measures
+
+ContextOps computes a **0–100 Context Score** from four independent penalty dimensions:
+
+| Dimension | What It Detects | Max Penalty |
+|---|---|---|
+| **Redundancy** | Duplicate / near-duplicate chunks (N-gram + Jaccard) | 30 pts |
+| **Density** | Wasted tokens from structural bloat | 30 pts |
+| **Structure** | Imbalanced type distribution (e.g., retrieval > 70%) | 20 pts |
+| **Concentration** | Source dominance or highly imbalanced chunk distribution | 20 pts |
+
+```
+Context Score = 100 - (Redundancy + Density + Structure + Concentration)
+```
+
+Every penalty maps to a **specific finding** with **token savings** and an **actionable fix**.
+
+---
+
+## CI / CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Context Quality Gate
+
+on: [pull_request]
+
+jobs:
+  context-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install contextops
+
+      - name: Check context quality
+        run: contextops check prompts/context.json --min-score 75
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Score meets threshold — build passes |
+| `1` | Score below threshold — build fails |
+
+### Regression Detection
+
+```bash
+# Save a baseline
+contextops inspect prompts/v1.json --json-output > baseline.json
+
+# After changes, compare
+contextops diff baseline.json prompts/v2.json
+```
+
+---
+
+## Context File Format
+
+ContextOps accepts a JSON file with any combination of these keys:
+
+```json
+{
+    "system": "Your system prompt here",
+    "messages": [
+        {"role": "user", "content": "User question"}
+    ],
+    "chunks": [
+        {"content": "Retrieved chunk text", "source": "docs/page.md"}
+    ],
+    "memory": [
+        "Previous conversation context"
+    ],
+    "tools": [
+        {"name": "search_api", "output": "Tool response text"}
+    ]
+}
+```
+
+It also accepts raw OpenAI message lists:
+
+```json
+[
+    {"role": "system", "content": "You are helpful."},
+    {"role": "user", "content": "What is the refund policy?"}
+]
+```
+
+---
+
+## CLI Reference
+
+| Command | Purpose |
+|---|---|
+| `contextops inspect <file>` | Analyze and display results |
+| `contextops check <file> --min-score N` | CI gate with exit codes |
+| `contextops demo` | Built-in demo context |
+| `contextops stability <file>` | Deterministic stability report |
+| `contextops diff <file_a> <file_b>` | Compare two snapshots |
+
+### Flags
+
+| Flag | Commands | Purpose |
+|---|---|---|
+| `--json-output` | inspect, check | Machine-readable JSON output |
+| `--min-score N` | check | Minimum passing score (0–100) |
+| `--model <name>` | inspect, check | Target model for cost estimation |
+| `--explain` | inspect, check | Show detailed penalty reasoning |
+| `--config <file>` | inspect, check | Custom threshold config file |
+
+---
+
+## Design Principles
+
+1. **Deterministic** — Same input → same output. Always. No randomness, no embeddings, no LLM calls.
+2. **Explainable** — Every penalty maps to a real issue with a token count and a fix.
+3. **CI-native** — Designed for pipelines first. Exit codes, JSON output, threshold gating.
+4. **Zero network** — Runs entirely offline. No API keys, no external services.
+
+---
+
+## Stability Contract
+
+ContextOps ships with a formal [Stability Contract](STABILITY.md) that guarantees:
+
+- **Scoring determinism** — same input always produces the same score
+- **Schema stability** — JSON output fields never change within a major version
+- **Performance bounds** — sub-second for payloads up to 50,000 tokens
+- **Semantic versioning** — scoring formula changes require a major version bump
+
+This contract exists so teams can trust ContextOps in production CI pipelines.
+
+---
+
+## Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/Abhijeet777/contextops.git
+cd contextops
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run chaos stress tests
+pytest tests/test_chaos.py -v
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

contextops-0.1.0/contextops/__init__.py

@@ -0,0 +1,3 @@
+"""ContextOps — Context observability for LLM applications."""
+
+__version__ = "0.1.0"

contextops-0.1.0/contextops/analyzers/__init__.py

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

contextops-0.1.0/contextops/analyzers/density.py

@@ -0,0 +1,146 @@
+"""
+Density Analyzer — Phase 2.5 (Metric Orthogonalization).
+
+Computes the structural Density Signal from raw context text.
+
+Signal contract:
+    - Reads ONLY from raw ContextBundle item content strings.
+    - Does NOT read wasted_tokens, redundancy findings, or any other analyzer output.
+    - Is the sole authoritative input for density_penalty in the scoring engine.
+
+Three orthogonal character buckets (exhaustive, non-overlapping):
+    payload_chars   = alphanumeric  (actual information)
+    syntax_chars    = non-alphanum, non-whitespace (brackets, punctuation, markup)
+    whitespace_chars = whitespace   (layout/formatting overhead)
+    total_chars = payload + syntax + whitespace  (always sums to 1.0)
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from contextops.core.models import ContextBundle, DensitySignal
+
+
+def normalize_density_input(text: str) -> list[str]:
+    """
+    Standardize text preprocessing for density metrics to prevent metric drift.
+
+    Rules (frozen — do not change without updating all callers):
+        1. Lowercase
+        2. Replace non-alphanumeric (including underscore) with spaces
+        3. Split on whitespace only
+
+    The regex uses [^a-z0-9\\s] (not \\w) to ensure underscores are treated
+    as punctuation, not part of identifiers. This makes snake_case and kebab-case
+    consistent (both split into component words).
+    """
+    text = text.lower()
+    text = re.sub(r'[^a-z0-9\s]', ' ', text)
+    return text.split()
+
+
+def _calc_format_overhead(text: str) -> float:
+    """
+    Format Overhead (FO): Ratio of syntax chars to total chars.
+
+    FO = syntax_chars / total_chars
+    where syntax_chars = non-alphanumeric AND non-whitespace characters
+    (brackets, punctuation, markup, operators, etc.)
+
+    Range: 0.0 (no syntax overhead) → 1.0 (all syntax, no payload or whitespace).
+    Does NOT include whitespace — that is measured separately by WL.
+    """
+    total_chars = len(text)
+    if total_chars == 0:
+        return 0.0
+
+    syntax_chars = sum(1 for c in text if not c.isalnum() and not c.isspace())
+    return max(0.0, min(1.0, syntax_chars / total_chars))
+
+
+def _calc_whitespace_waste(text: str) -> float:
+    """
+    Whitespace Waste (WL): Ratio of whitespace chars to total chars.
+
+    WL = whitespace_chars / total_chars
+    where whitespace_chars = space, tab, newline, carriage return, etc.
+
+    Range: 0.0 (no whitespace) → 1.0 (all whitespace).
+    Does NOT include syntax chars — that is measured separately by FO.
+    """
+    total_chars = len(text)
+    if total_chars == 0:
+        return 0.0
+
+    whitespace_chars = sum(1 for c in text if c.isspace())
+    return max(0.0, min(1.0, whitespace_chars / total_chars))
+
+
+def _calc_entropy_compression(text: str) -> float:
+    """
+    Entropy Compression (EC): Statistical measure of repetitive boilerplate.
+
+    EC = 1 - normalized_shannon_entropy
+
+    High EC → low entropy → highly repetitive token distribution.
+    Low EC  → high entropy → diverse vocabulary (good).
+
+    Normalization: entropy / log2(unique_words) so range is always 0.0–1.0.
+    """
+    words = normalize_density_input(text)
+    if not words:
+        return 0.0
+
+    total_words = len(words)
+    word_counts = Counter(words)
+    unique_words = len(word_counts)
+
+    if unique_words <= 1:
+        return 1.0  # single word repeated — maximum compression
+
+    # Shannon entropy
+    entropy = 0.0
+    for count in word_counts.values():
+        p = count / total_words
+        entropy -= p * math.log2(p)
+
+    max_entropy = math.log2(unique_words)
+    normalized_entropy = entropy / max_entropy
+
+    return max(0.0, min(1.0, 1.0 - normalized_entropy))
+
+
+def compute_density_signal(bundle: ContextBundle) -> DensitySignal:
+    """
+    Compute the structural Density Signal from raw context content.
+
+    Signal contract: reads ONLY raw item.content strings.
+    Must NOT read token_count, wasted_tokens, or any analyzer output.
+
+    Weights (initial): FO=0.4, WL=0.2, EC=0.4
+    These are calibrated so typical clean context scores near 0.1–0.3,
+    and heavily bloated context scores near 0.6–0.9.
+    """
+    if not bundle.items:
+        return DensitySignal(0.0, 0.0, 0.0, 0.0)
+
+    total_text = "\n".join(item.content for item in bundle.items)
+
+    if not total_text.strip():
+        return DensitySignal(0.0, 0.0, 0.0, 0.0)
+
+    fo = _calc_format_overhead(total_text)
+    wl = _calc_whitespace_waste(total_text)
+    ec = _calc_entropy_compression(total_text)
+
+    # Weights: w_fo=0.4, w_wl=0.2, w_ec=0.4
+    total_signal = (0.4 * fo) + (0.2 * wl) + (0.4 * ec)
+
+    return DensitySignal(
+        format_overhead=round(fo, 3),
+        whitespace_waste=round(wl, 3),
+        entropy_compression=round(ec, 3),
+        total_density_signal=round(total_signal, 3),
+    )