clef-router 0.1.0__tar.gz

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

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+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_router-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: clef-router
+Version: 0.1.0
+Summary: Route prompts between cheap and frontier LLMs using Cloudflare's Clef decision model.
+Author: Youssef Ouhaghi Ahmian
+License: Apache-2.0
+Keywords: ai,clef,cloudflare,cost-optimization,decision-model,llm,routing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clef-router
+
+Route prompts between cheap and frontier LLMs using Cloudflare's [Clef](https://blog.cloudflare.com/clef-decision-models/) decision model.
+
+## Quick start
+
+```bash
+pip install clef-router
+export CLEF_ACCOUNT_ID=your_cloudflare_account_id
+export CLEF_API_TOKEN=your_cloudflare_api_token
+```
+
+```python
+from clef_router import ClefRouter
+
+router = ClefRouter()
+result = router.route("What is the capital of France?")
+print(result.tier)       # "cheap"
+print(result.reason)     # "classified as simple, confidence 0.90"
+
+result = router.route("Design a distributed consensus algorithm")
+print(result.tier)       # "frontier"
+```
+
+## How it works
+
+```
+prompt → Clef decision model (Cloudflare Workers AI) → tier
+              ├─ simple   → cheap model
+              ├─ standard  → cheap model
+              ├─ complex   → frontier model
+              └─ uncertain → frontier (confidence gate)
+```
+
+## clef vs laya
+
+| | laya | Clef |
+|---|---|---|
+| Latency | 5.8ms | 38.8ms (flash) / 209.3ms (full) |
+| Quality (BFCL) | 38.13 | 98.76 |
+| Context | 32k | 64k |
+| Hosting | local CPU | Cloudflare API |
+| Cost | $0 | Workers AI pricing |
+
+Use [laya-router](https://github.com/Gjusev/laya-router) for sub-10ms local routing. Use clef-router when quality matters more than latency.
+
+## License
+
+Apache 2.0

clef_router-0.1.0/README.md

@@ -0,0 +1,49 @@
+# clef-router
+
+Route prompts between cheap and frontier LLMs using Cloudflare's [Clef](https://blog.cloudflare.com/clef-decision-models/) decision model.
+
+## Quick start
+
+```bash
+pip install clef-router
+export CLEF_ACCOUNT_ID=your_cloudflare_account_id
+export CLEF_API_TOKEN=your_cloudflare_api_token
+```
+
+```python
+from clef_router import ClefRouter
+
+router = ClefRouter()
+result = router.route("What is the capital of France?")
+print(result.tier)       # "cheap"
+print(result.reason)     # "classified as simple, confidence 0.90"
+
+result = router.route("Design a distributed consensus algorithm")
+print(result.tier)       # "frontier"
+```
+
+## How it works
+
+```
+prompt → Clef decision model (Cloudflare Workers AI) → tier
+              ├─ simple   → cheap model
+              ├─ standard  → cheap model
+              ├─ complex   → frontier model
+              └─ uncertain → frontier (confidence gate)
+```
+
+## clef vs laya
+
+| | laya | Clef |
+|---|---|---|
+| Latency | 5.8ms | 38.8ms (flash) / 209.3ms (full) |
+| Quality (BFCL) | 38.13 | 98.76 |
+| Context | 32k | 64k |
+| Hosting | local CPU | Cloudflare API |
+| Cost | $0 | Workers AI pricing |
+
+Use [laya-router](https://github.com/Gjusev/laya-router) for sub-10ms local routing. Use clef-router when quality matters more than latency.
+
+## License
+
+Apache 2.0

clef_router-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "clef-router"
+version = "0.1.0"
+description = "Route prompts between cheap and frontier LLMs using Cloudflare's Clef decision model."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+authors = [{ name = "Youssef Ouhaghi Ahmian" }]
+keywords = ["llm", "routing", "ai", "clef", "cloudflare", "decision-model", "cost-optimization"]
+dependencies = ["httpx>=0.25"]
+
+[project.scripts]
+clef-route = "clef_router.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clef_router"]

clef_router-0.1.0/src/clef_router/__init__.py

@@ -0,0 +1,93 @@
+"""clef-router: Route prompts between cheap and frontier LLMs using Cloudflare's Clef."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+import httpx
+
+
+@dataclass
+class RouteResult:
+    tier: str
+    complexity: str
+    confidence: float
+    reason: str
+    raw_response: dict = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class ClefRouter:
+    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-flash"
+    base_url: str = "https://api.cloudflare.com/client/v4"
+    min_confidence: float = 0.45
+    timeout: float = 30.0
+
+    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 route(self, prompt: str, context: Optional[str] = None) -> RouteResult:
+        state = f"User prompt to classify:\n{prompt}"
+        if context:
+            state = f"Context: {context}\n\n{state}"
+
+        payload = {
+            "state": state,
+            "questions": {
+                "complexity": {
+                    "type": "choice",
+                    "context": "How computationally complex is this prompt? "
+                               "simple = greeting, translation, basic lookup. "
+                               "standard = summarization, rewording, simple analysis. "
+                               "complex = reasoning, coding, multi-step, creative.",
+                    "choices": ["simple", "standard", "complex"],
+                },
+                "confidence": {
+                    "type": "score",
+                    "context": "How confident are you in this classification?",
+                    "levels": ["very_low", "low", "medium", "high", "very_high"],
+                },
+            },
+        }
+
+        resp = httpx.post(
+            self._endpoint, json=payload, headers=self._headers(), timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        result = data.get("result", {})
+        complexity = result.get("complexity", "complex")
+        conf_map = {"very_low": 0.1, "low": 0.3, "medium": 0.5, "high": 0.7, "very_high": 0.9}
+        confidence = conf_map.get(result.get("confidence", "low"), 0.3)
+
+        if confidence < self.min_confidence:
+            tier = "frontier"
+            reason = f"confidence {confidence:.2f} below threshold {self.min_confidence}, escalated"
+        elif complexity == "complex":
+            tier = "frontier"
+            reason = f"classified as {complexity}"
+        else:
+            tier = "cheap"
+            reason = f"classified as {complexity}, confidence {confidence:.2f}"
+
+        return RouteResult(
+            tier=tier, complexity=complexity, confidence=confidence,
+            reason=reason, raw_response=data,
+        )
+
+
+__version__ = "0.1.0"
+__all__ = ["ClefRouter", "RouteResult"]

clef_router-0.1.0/src/clef_router/cli.py

@@ -0,0 +1,34 @@
+"""CLI for clef-router."""
+
+import argparse
+import json
+
+from . import ClefRouter
+
+
+def main():
+    p = argparse.ArgumentParser(prog="clef-route", description="Route a prompt using Clef")
+    p.add_argument("prompt", help="The prompt to classify")
+    p.add_argument("--context", "-c", default=None)
+    p.add_argument("--json", action="store_true")
+    args = p.parse_args()
+
+    router = ClefRouter()
+    result = router.route(args.prompt, context=args.context)
+
+    if args.json:
+        print(json.dumps({
+            "tier": result.tier,
+            "complexity": result.complexity,
+            "confidence": result.confidence,
+            "reason": result.reason,
+        }, indent=2))
+    else:
+        print(f"tier:       {result.tier}")
+        print(f"complexity: {result.complexity}")
+        print(f"confidence: {result.confidence:.2f}")
+        print(f"reason:     {result.reason}")
+
+
+if __name__ == "__main__":
+    main()