contextops 0.1.0__py3-none-any.whl

contextops/core/normalizer.py

@@ -0,0 +1,187 @@
+"""
+Context Normalizer.
+
+Converts raw LLM inputs into the canonical ContextBundle format.
+Supports:
+  - OpenAI-style message lists
+  - Raw dict lists with type/content
+  - Single string inputs (treated as system prompt)
+"""
+
+from __future__ import annotations
+
+from contextops.core.models import ContextBundle, ContextItem, ContextType
+
+
+# Maps OpenAI message roles to our ContextType enum
+_ROLE_MAP: dict[str, ContextType] = {
+    "system": ContextType.SYSTEM,
+    "user": ContextType.MESSAGE,
+    "assistant": ContextType.MESSAGE,
+    "tool": ContextType.TOOL,
+    "function": ContextType.TOOL,
+}
+
+
+def normalize(raw_input: str | list[dict] | dict) -> ContextBundle:
+    """
+    Normalize any supported raw input into a ContextBundle.
+
+    Args:
+        raw_input: One of:
+            - A plain string (treated as a system prompt)
+            - A list of OpenAI-style message dicts
+            - A dict with explicit 'messages', 'chunks', 'memory', 'system' keys
+
+    Returns:
+        A ContextBundle with all items normalized.
+
+    Raises:
+        ValueError: If the input format is not recognized.
+    """
+    if isinstance(raw_input, str):
+        return _normalize_string(raw_input)
+    elif isinstance(raw_input, list):
+        return _normalize_message_list(raw_input)
+    elif isinstance(raw_input, dict):
+        # Unwrap benchmark-style "input" wrapper if present
+        if "input" in raw_input and isinstance(raw_input["input"], dict):
+            raw_input = raw_input["input"]
+        return _normalize_structured_dict(raw_input)
+    else:
+        raise ValueError(
+            f"Unsupported input type: {type(raw_input).__name__}. "
+            "Expected str, list[dict], or dict."
+        )
+
+
+def _normalize_string(text: str) -> ContextBundle:
+    """Treat a single string as a system prompt."""
+    item = ContextItem(
+        type=ContextType.SYSTEM,
+        content=text,
+        source="raw_string",
+    )
+    return ContextBundle(items=[item])
+
+
+def _normalize_message_list(messages: list[dict]) -> ContextBundle:
+    """
+    Normalize an OpenAI-style message list.
+
+    Each dict should have at least 'role' and 'content' keys.
+    """
+    items: list[ContextItem] = []
+
+    for i, msg in enumerate(messages):
+        if not isinstance(msg, dict):
+            raise ValueError(f"Message at index {i} is not a dict: {type(msg).__name__}")
+
+        role = msg.get("role", "user")
+        content = msg.get("content", "")
+        context_type = _ROLE_MAP.get(role, ContextType.MESSAGE)
+
+        # Extract source hint if available
+        source = msg.get("name") or msg.get("source") or f"message_{i}"
+
+        item = ContextItem(
+            type=context_type,
+            content=content if content else "",
+            source=source,
+            metadata={"role": role, "index": i},
+        )
+        items.append(item)
+
+    return ContextBundle(items=items)
+
+
+def _normalize_structured_dict(data: dict) -> ContextBundle:
+    """
+    Normalize a structured dict with explicit context sections.
+
+    Expected keys (all optional):
+        - system: str
+        - messages: list[dict] with role/content
+        - chunks / retrieval: list[str | dict]
+        - memory: list[str | dict]
+        - tools: list[str | dict]
+    """
+    items: list[ContextItem] = []
+
+    # System prompt
+    if "system" in data:
+        items.append(ContextItem(
+            type=ContextType.SYSTEM,
+            content=data["system"],
+            source="system_prompt",
+        ))
+
+    # Chat messages
+    for i, msg in enumerate(data.get("messages", [])):
+        if isinstance(msg, str):
+            items.append(ContextItem(
+                type=ContextType.MESSAGE,
+                content=msg,
+                source=f"message_{i}",
+            ))
+        elif isinstance(msg, dict):
+            role = msg.get("role", "user")
+            items.append(ContextItem(
+                type=_ROLE_MAP.get(role, ContextType.MESSAGE),
+                content=msg.get("content", ""),
+                source=msg.get("source", f"message_{i}"),
+                metadata={"role": role, "index": i},
+            ))
+
+    # Retrieval chunks (key can be 'chunks' or 'retrieval')
+    chunks = data.get("chunks", data.get("retrieval", []))
+    for i, chunk in enumerate(chunks):
+        if isinstance(chunk, str):
+            items.append(ContextItem(
+                type=ContextType.RETRIEVAL,
+                content=chunk,
+                source=f"chunk_{i}",
+            ))
+        elif isinstance(chunk, dict):
+            items.append(ContextItem(
+                type=ContextType.RETRIEVAL,
+                content=chunk.get("content", ""),
+                source=chunk.get("source", f"chunk_{i}"),
+                metadata={k: v for k, v in chunk.items() if k not in ("content", "source")},
+            ))
+
+    # Memory
+    for i, mem in enumerate(data.get("memory", [])):
+        if isinstance(mem, str):
+            items.append(ContextItem(
+                type=ContextType.MEMORY,
+                content=mem,
+                source=f"memory_{i}",
+            ))
+        elif isinstance(mem, dict):
+            items.append(ContextItem(
+                type=ContextType.MEMORY,
+                content=mem.get("content", ""),
+                source=mem.get("source", f"memory_{i}"),
+                metadata={k: v for k, v in mem.items() if k not in ("content", "source")},
+            ))
+
+    # Tool outputs
+    for i, tool in enumerate(data.get("tools", [])):
+        if isinstance(tool, str):
+            items.append(ContextItem(
+                type=ContextType.TOOL,
+                content=tool,
+                source=f"tool_{i}",
+            ))
+        elif isinstance(tool, dict):
+            # Tool outputs may use 'content' or 'output' as the text key
+            tool_content = tool.get("content", "") or tool.get("output", "")
+            items.append(ContextItem(
+                type=ContextType.TOOL,
+                content=tool_content,
+                source=tool.get("source", tool.get("name", f"tool_{i}")),
+                metadata={k: v for k, v in tool.items() if k not in ("content", "source", "output", "name")},
+            ))
+
+    return ContextBundle(items=items)

contextops-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,24 @@
+contextops/__init__.py,sha256=40J9Neb2T1yPnISprBxgUDKHnr9XJDvY85Vz5ne6Kh0,88
+contextops/analyzers/__init__.py,sha256=bG7cSV3bZwongV_AIWoVhrXrdSNmuFNGelFaJKHwe00,23
+contextops/analyzers/density.py,sha256=xlIHwgd17rOVWevimRs3fj6vFoUhsimH9oRjw-wIvT4,4838
+contextops/analyzers/redundancy.py,sha256=GpUasQ3zpMn6j091Z3XJL4pcFe8h9W_A-5Exfn6qU4M,13336
+contextops/analyzers/structure.py,sha256=-5Sdsu5KBDxg5MNuX0epwNrx_vgOSOC3OEq9L2zQV8c,4090
+contextops/analyzers/tokens.py,sha256=GUY1V1DTd8go27LNx7HEvmujzl3MKFNb8Feqsj0i0n0,2143
+contextops/api/__init__.py,sha256=vxJNiD7nkMawrrr8Q0A6BE5rUhumj7WA9zsJEJC4gHc,17
+contextops/api/diff.py,sha256=OQGjCdmRmIl2EruJXqgjfYRoY0WnyNGu8uIhvpGv7yo,4457
+contextops/api/inspect.py,sha256=6B9LyK3Fn9L2o--wWy8iFuBKxWqDYxVLON6H53cnkNU,1660
+contextops/api/stability.py,sha256=t25ewU9lmec76kM5WxNYWrZHa6RWvr8GV7dGgGA97_4,9049
+contextops/cli/__init__.py,sha256=S4gk3Xl6GIbvLFlda3yITbWovOuwTu0JViGhtfG1sZo,17
+contextops/cli/main.py,sha256=GJ2q9vRNAfqPSll4TnXyhvwKhRvYmmUTwIN3M4ZNprM,11881
+contextops/cli/renderer.py,sha256=EB4Iu_gqq0GF4ZjKHXDb8rf9NM2LYUZjGYTjWeqy6zU,18391
+contextops/core/__init__.py,sha256=km68QyE3lKvt3nk2S7bxZaTZWxKWB53apJFRoRTTJjo,18
+contextops/core/config.py,sha256=7FL1D5VaYWmTPamz5HRv8LrXmvoWDNtyiECNM14GNq0,1767
+contextops/core/engine.py,sha256=TRG-82FTi-Oymjjoo59q2UIsBxoQvPTdjBxU2QBCfe4,13643
+contextops/core/models.py,sha256=uzjLT3-DiJ9zrShw8EWSY7982RfXc0OJkc5xbZ5tc-Q,8510
+contextops/core/normalizer.py,sha256=2LvJTnpuHTIoPalSwgl4PqlKgsx7FfblNkDU9T6Zd4g,6194
+contextops-0.1.0.dist-info/licenses/LICENSE,sha256=Hr9dxbQeTKHbjT1hjE5Kj_eTjTMlD4YHwirrrKF1opo,1070
+contextops-0.1.0.dist-info/METADATA,sha256=ZY99Q-Gl9pkgWzt0hwNK2jIg3LlrAc25Fr0RalIstn8,8269
+contextops-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+contextops-0.1.0.dist-info/entry_points.txt,sha256=_ESCua3aXYYCq5qDqRzBEFWGXx-BRk49lNsxydH_HZQ,55
+contextops-0.1.0.dist-info/top_level.txt,sha256=wyZsAyPljX_F4eF9heBKToX1JBMLyZbK1Lirppld3YM,11
+contextops-0.1.0.dist-info/RECORD,,

contextops-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

contextops-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contextops = contextops.cli.main:cli

contextops-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+contextops