clef-compactor 0.1.0__tar.gz

clef_compactor-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - run: uv publish

clef_compactor-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: clef-compactor
+Version: 0.1.0
+Summary: Query-aware RAG context compaction using Cloudflare's Clef. Keep the evidence, cut the noise.
+Author: Youssef Ouhaghi Ahmian
+License: Apache-2.0
+Keywords: clef,cloudflare,compaction,context,llm,rag,tokens
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clef-compactor
+
+Query-aware RAG context compaction using Cloudflare's [Clef](https://blog.cloudflare.com/clef-decision-models/).
+
+Your retrieval pipeline returns 12 chunks. Your LLM reads all of them. You pay for all of them. clef-compactor scores each document against the query using Clef's 64k context window and cuts the noise.
+
+**Delete, do not rewrite.** Documents are kept verbatim or removed with an auditable reason. Never summarized.
+
+## Quick start
+
+```bash
+pip install clef-compactor
+export CLEF_ACCOUNT_ID=your_id
+export CLEF_API_TOKEN=your_token
+```
+
+```python
+from clef_compactor import ClefCompactor
+
+compactor = ClefCompactor()
+result = compactor.compact(
+    question="What is the refund policy?",
+    documents=retrieved_chunks,
+    token_budget=1000,
+)
+# result.kept: documents that survived
+# result.dropped: [{doc, score, reason}] for the ones cut
+# result.total_output_tokens < result.total_input_tokens
+```
+
+## CLI
+
+```bash
+clef-compact -q "refund policy" -d "doc1..." "doc2..." --budget 1000
+```
+
+## Why Clef for compaction?
+
+Clef's 64k context window means you can score more documents in a single pass than with laya (32k). The quality is higher (BFCL 98.76 vs laya's 38.13), which means fewer false positives when scoring document relevance.
+
+For sub-10ms local compaction, see [laya-compactor](https://github.com/Gjusev/laya-compactor).
+
+## License
+
+Apache 2.0

clef_compactor-0.1.0/README.md

@@ -0,0 +1,45 @@
+# clef-compactor
+
+Query-aware RAG context compaction using Cloudflare's [Clef](https://blog.cloudflare.com/clef-decision-models/).
+
+Your retrieval pipeline returns 12 chunks. Your LLM reads all of them. You pay for all of them. clef-compactor scores each document against the query using Clef's 64k context window and cuts the noise.
+
+**Delete, do not rewrite.** Documents are kept verbatim or removed with an auditable reason. Never summarized.
+
+## Quick start
+
+```bash
+pip install clef-compactor
+export CLEF_ACCOUNT_ID=your_id
+export CLEF_API_TOKEN=your_token
+```
+
+```python
+from clef_compactor import ClefCompactor
+
+compactor = ClefCompactor()
+result = compactor.compact(
+    question="What is the refund policy?",
+    documents=retrieved_chunks,
+    token_budget=1000,
+)
+# result.kept: documents that survived
+# result.dropped: [{doc, score, reason}] for the ones cut
+# result.total_output_tokens < result.total_input_tokens
+```
+
+## CLI
+
+```bash
+clef-compact -q "refund policy" -d "doc1..." "doc2..." --budget 1000
+```
+
+## Why Clef for compaction?
+
+Clef's 64k context window means you can score more documents in a single pass than with laya (32k). The quality is higher (BFCL 98.76 vs laya's 38.13), which means fewer false positives when scoring document relevance.
+
+For sub-10ms local compaction, see [laya-compactor](https://github.com/Gjusev/laya-compactor).
+
+## License
+
+Apache 2.0

clef_compactor-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "clef-compactor"
+version = "0.1.0"
+description = "Query-aware RAG context compaction using Cloudflare's Clef. Keep the evidence, cut the noise."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+authors = [{ name = "Youssef Ouhaghi Ahmian" }]
+keywords = ["rag", "context", "compaction", "clef", "cloudflare", "llm", "tokens"]
+dependencies = ["httpx>=0.25", "tiktoken>=0.7"]
+
+[project.scripts]
+clef-compact = "clef_compactor.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clef_compactor"]

clef_compactor-0.1.0/src/clef_compactor/__init__.py

@@ -0,0 +1,114 @@
+"""clef-compactor: Query-aware RAG context compaction using Cloudflare's Clef."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+import httpx
+import tiktoken
+
+
+@dataclass
+class CompactResult:
+    """Result of compacting a retrieval batch."""
+    kept: list[dict]  # documents that survived, with their scores
+    dropped: list[dict]  # documents cut, with score and reason
+    total_input_tokens: int
+    total_output_tokens: int
+    token_budget: int
+    raw_response: dict = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class ClefCompactor:
+    """Score and compact RAG retrieval batches using Cloudflare's Clef."""
+
+    account_id: str = field(default_factory=lambda: os.environ.get("CLEF_ACCOUNT_ID", ""))
+    api_token: str = field(default_factory=lambda: os.environ.get("CLEF_API_TOKEN", ""))
+    model: str = "@cf/cloudflare/clef"
+    base_url: str = "https://api.cloudflare.com/client/v4"
+    timeout: float = 60.0
+    encoding_model: str = "cl100k_base"  # for token counting
+
+    def __post_init__(self):
+        if not self.account_id:
+            raise ValueError("Set CLEF_ACCOUNT_ID env var or pass account_id")
+        if not self.api_token:
+            raise ValueError("Set CLEF_API_TOKEN env var or pass api_token")
+
+    @property
+    def _endpoint(self) -> str:
+        return f"{self.base_url}/accounts/{self.account_id}/ai/run/{self.model}"
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self.api_token}", "Content-Type": "application/json"}
+
+    def _count_tokens(self, text: str) -> int:
+        enc = tiktoken.get_encoding(self.encoding_model)
+        return len(enc.encode(text))
+
+    def compact(
+        self,
+        question: str,
+        documents: list[str],
+        token_budget: int = 1000,
+    ) -> CompactResult:
+        """Score each document against the question and keep the best within budget."""
+        if not documents:
+            return CompactResult(kept=[], dropped=[], total_input_tokens=0,
+                                 total_output_tokens=0, token_budget=token_budget)
+
+        state = f"Question: {question}\n\nDocuments to score:\n"
+        questions = {}
+        for i, doc in enumerate(documents):
+            snippet = doc[:300]  # truncate for context efficiency
+            state += f"\n[Doc {i+1}]: {snippet}...\n"
+            questions[f"relevance_{i+1}"] = {
+                "type": "score",
+                "context": f"How relevant is document {i+1} to answering the question? "
+                           "essential = directly answers the question. "
+                           "relevant = provides supporting information. "
+                           "background = tangentially related. "
+                           "irrelevant = not useful.",
+                "levels": ["irrelevant", "background", "relevant", "essential"],
+            }
+
+        payload = {"state": state, "questions": questions}
+        resp = httpx.post(
+            self._endpoint, json=payload, headers=self._headers(), timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json().get("result", {})
+
+        score_map = {"irrelevant": 0, "background": 1, "relevant": 2, "essential": 3}
+        scored = []
+        for i, doc in enumerate(documents):
+            raw_score = data.get(f"relevance_{i+1}", "irrelevant")
+            score = score_map.get(raw_score, 0)
+            tokens = self._count_tokens(doc)
+            scored.append({"doc": doc, "score": score, "raw": raw_score, "tokens": tokens})
+
+        # Sort by score descending, keep within budget
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        kept, dropped = [], []
+        running_tokens = 0
+        for item in scored:
+            if item["score"] <= 0:
+                dropped.append({**item, "reason": "irrelevant"})
+            elif running_tokens + item["tokens"] <= token_budget:
+                kept.append(item)
+                running_tokens += item["tokens"]
+            else:
+                dropped.append({**item, "reason": "budget_exhausted"})
+
+        total_input = sum(item["tokens"] for item in scored)
+        return CompactResult(
+            kept=kept, dropped=dropped,
+            total_input_tokens=total_input,
+            total_output_tokens=running_tokens,
+            token_budget=token_budget,
+        )
+
+
+__version__ = "0.1.0"
+__all__ = ["ClefCompactor", "CompactResult"]

clef_compactor-0.1.0/src/clef_compactor/cli.py

@@ -0,0 +1,37 @@
+"""CLI for clef-compactor."""
+
+import argparse
+import json
+
+from . import ClefCompactor
+
+
+def main():
+    p = argparse.ArgumentParser(prog="clef-compact", description="Compact RAG context using Clef")
+    p.add_argument("--question", "-q", required=True)
+    p.add_argument("--docs", "-d", nargs="+", required=True, help="Document texts")
+    p.add_argument("--budget", "-b", type=int, default=1000)
+    p.add_argument("--json", action="store_true")
+    args = p.parse_args()
+
+    compactor = ClefCompactor()
+    result = compactor.compact(args.question, args.docs, token_budget=args.budget)
+
+    if args.json:
+        print(json.dumps({
+            "kept": len(result.kept),
+            "dropped": len(result.dropped),
+            "input_tokens": result.total_input_tokens,
+            "output_tokens": result.total_output_tokens,
+            "saved_pct": round(100 * (1 - result.total_output_tokens / max(result.total_input_tokens, 1)), 1),
+        }, indent=2))
+    else:
+        print(f"kept:          {len(result.kept)} docs")
+        print(f"dropped:       {len(result.dropped)} docs")
+        print(f"input tokens:  {result.total_input_tokens}")
+        print(f"output tokens: {result.total_output_tokens}")
+        print(f"saved:         {100 * (1 - result.total_output_tokens / max(result.total_input_tokens, 1)):.1f}%")
+
+
+if __name__ == "__main__":
+    main()