shunt 0.0.1__tar.gz

shunt-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env
+*.sqlite3
+.pytest_cache/

shunt-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PierrunoYT
+
+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.

shunt-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: shunt
+Version: 0.0.1
+Summary: Routes LLM requests between cheap open-source and premium models based on task difficulty
+Project-URL: Homepage, https://github.com/PierrunoYT/shunt.sh
+Author: PierrunoYT
+License: MIT
+License-File: LICENSE
+Keywords: cost-optimization,llm,openai,openrouter,router
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# shunt
+
+**Early development — APIs will change.**
+
+Shunt is a small, self-hosted router with an OpenAI-compatible API. It classifies
+every request — coding, reasoning, light chat — and forwards it to the cheapest
+open-source model that can handle it.
+
+```python
+from shunt import Router
+
+router = Router()
+track = router.classify("Refactor this function to be async")
+# -> "coding"
+```
+
+Planned for upcoming releases:
+
+- `shunt serve` — local OpenAI-compatible proxy server
+- Ordered fallback chains per track ("light", "general", "coding", "coding_heavy", "reasoning")
+- YAML configuration and a local SQLite cost ledger
+
+## Status
+
+`v0.0.1` is a name-holding stub for the project under active development.
+Follow progress at the project repository.
+
+## License
+
+MIT

shunt-0.0.1/README.md

@@ -0,0 +1,30 @@
+# shunt
+
+**Early development — APIs will change.**
+
+Shunt is a small, self-hosted router with an OpenAI-compatible API. It classifies
+every request — coding, reasoning, light chat — and forwards it to the cheapest
+open-source model that can handle it.
+
+```python
+from shunt import Router
+
+router = Router()
+track = router.classify("Refactor this function to be async")
+# -> "coding"
+```
+
+Planned for upcoming releases:
+
+- `shunt serve` — local OpenAI-compatible proxy server
+- Ordered fallback chains per track ("light", "general", "coding", "coding_heavy", "reasoning")
+- YAML configuration and a local SQLite cost ledger
+
+## Status
+
+`v0.0.1` is a name-holding stub for the project under active development.
+Follow progress at the project repository.
+
+## License
+
+MIT

shunt-0.0.1/alias/shunt-llm/README.md

@@ -0,0 +1,9 @@
+# shunt-llm
+
+Alias package. Install [`shunt`](https://pypi.org/project/shunt/) instead:
+
+```bash
+pip install shunt
+```
+
+Installing `shunt-llm` pulls in `shunt` and re-exports its API.

shunt-0.0.1/alias/shunt-llm/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shunt-llm"
+version = "0.0.1"
+description = "Alias for the 'shunt' package — routes LLM requests between cheap and premium models"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "PierrunoYT" }]
+dependencies = ["shunt"]
+
+[project.urls]
+Homepage = "https://github.com/PierrunoYT/shunt.sh"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shunt_llm"]

shunt-0.0.1/alias/shunt-llm/src/shunt_llm/__init__.py

@@ -0,0 +1,5 @@
+"""Alias for the ``shunt`` package."""
+
+from shunt import Router, Track, __version__
+
+__all__ = ["Router", "Track", "__version__"]

shunt-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shunt"
+version = "0.0.1"
+description = "Routes LLM requests between cheap open-source and premium models based on task difficulty"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "PierrunoYT" }]
+keywords = ["llm", "router", "openai", "openrouter", "cost-optimization"]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/PierrunoYT/shunt.sh"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shunt"]

shunt-0.0.1/src/shunt/__init__.py

@@ -0,0 +1,10 @@
+"""shunt: route LLM requests to the cheapest capable model.
+
+Early development. The public API consists of :class:`Router`, whose
+interface is a preview of the real implementation.
+"""
+
+from shunt.router import Router, Track
+
+__all__ = ["Router", "Track", "__version__"]
+__version__ = "0.0.1"

shunt-0.0.1/src/shunt/router.py

@@ -0,0 +1,48 @@
+"""Skeleton router. The heuristics here are intentionally minimal; the real
+classifier and provider fallback chains land in 0.1.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+
+class Track(str, Enum):
+    """A routing track: an ordered chain of models suited to a task class."""
+
+    LIGHT = "light"
+    GENERAL = "general"
+    CODING = "coding"
+    CODING_HEAVY = "coding_heavy"
+    REASONING = "reasoning"
+
+
+_CODE_HINTS = re.compile(
+    r"\b(refactor|debug|function|class|bug|compile|stack ?trace|regex|sql|"
+    r"python|javascript|typescript|rust|api|unit test)\b|```",
+    re.IGNORECASE,
+)
+_REASONING_HINTS = re.compile(
+    r"\b(prove|theorem|step[- ]by[- ]step|logic|math|equation|derive|optimi[sz]e)\b",
+    re.IGNORECASE,
+)
+
+
+class Router:
+    """Classifies prompts onto tracks. Stub implementation.
+
+    The 0.1 release will add provider configuration, fallback chains, and an
+    OpenAI-compatible ``serve`` mode. The :meth:`classify` signature is stable.
+    """
+
+    def classify(self, prompt: str) -> str:
+        """Return the track name for *prompt* using cheap keyword heuristics."""
+        if len(prompt) < 40 and not _CODE_HINTS.search(prompt):
+            return Track.LIGHT.value
+        if _CODE_HINTS.search(prompt):
+            heavy = len(prompt) > 2000 or "refactor" in prompt.lower()
+            return (Track.CODING_HEAVY if heavy else Track.CODING).value
+        if _REASONING_HINTS.search(prompt):
+            return Track.REASONING.value
+        return Track.GENERAL.value

shunt-0.0.1/website/index.html

@@ -0,0 +1,258 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Shunt — route prompts to the cheapest capable model</title>
+  <meta name="description" content="Shunt is a self-hosted, OpenAI-compatible router that sends every request to the cheapest open-source model that can handle it." />
+  <style>
+    :root {
+      --paper: #fcfbf8;
+      --ink: #1a1a18;
+      --faint: #6b6b65;
+      --line: #d9d7d0;
+      --accent: #c2410c;
+      --code-bg: #f3f1ea;
+      --max: 880px;
+    }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      background: var(--paper);
+      color: var(--ink);
+      font-family: Georgia, "Times New Roman", serif;
+      font-size: 17px;
+      line-height: 1.65;
+    }
+
+    code, pre, .mono {
+      font-family: ui-monospace, "SF Mono", Consolas, "Cascadia Mono", monospace;
+      font-size: 0.86em;
+    }
+
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+
+    .wrap { max-width: var(--max); margin: 0 auto; padding: 0 24px; }
+
+    /* Header */
+    header {
+      border-bottom: 1px solid var(--line);
+      padding: 18px 0;
+    }
+    .header-row {
+      display: flex; align-items: baseline; justify-content: space-between;
+      flex-wrap: wrap; gap: 12px;
+    }
+    .name {
+      font-family: ui-monospace, "SF Mono", Consolas, monospace;
+      font-size: 1.05rem; font-weight: 700; letter-spacing: 0.01em;
+      color: var(--ink);
+    }
+    .name:hover { text-decoration: none; }
+    nav a {
+      color: var(--faint); margin-left: 22px;
+      font-family: ui-monospace, "SF Mono", Consolas, monospace;
+      font-size: 0.82rem;
+    }
+    nav a:hover { color: var(--ink); text-decoration: none; }
+
+    /* Hero */
+    .hero { padding: 72px 0 56px; border-bottom: 1px solid var(--line); }
+    h1 {
+      font-size: clamp(1.9rem, 4.5vw, 2.7rem);
+      font-weight: 400;
+      line-height: 1.2;
+      letter-spacing: -0.01em;
+      max-width: 21em;
+    }
+    .hero .sub {
+      margin-top: 20px; max-width: 38em; color: var(--faint);
+    }
+    .hero .install {
+      margin-top: 32px;
+      display: inline-block;
+      background: var(--code-bg);
+      border: 1px solid var(--line);
+      padding: 10px 16px;
+    }
+    .hero .install code { font-size: 0.92rem; }
+    .hero .links { margin-top: 16px; font-size: 0.95rem; }
+    .hero .links a + a { margin-left: 18px; }
+
+    /* Sections */
+    section { padding: 52px 0; border-bottom: 1px solid var(--line); }
+    h2 {
+      font-size: 1.05rem;
+      font-family: ui-monospace, "SF Mono", Consolas, monospace;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: var(--faint);
+      margin-bottom: 26px;
+    }
+    section p { max-width: 42em; }
+    section p + p { margin-top: 14px; }
+
+    /* How it works list */
+    ol.steps {
+      counter-reset: step;
+      list-style: none;
+      max-width: 42em;
+    }
+    ol.steps li {
+      counter-increment: step;
+      padding: 16px 0 16px 56px;
+      position: relative;
+    }
+    ol.steps li + li { border-top: 1px solid var(--line); }
+    ol.steps li::before {
+      content: counter(step, decimal-leading-zero);
+      position: absolute; left: 0; top: 18px;
+      font-family: ui-monospace, "SF Mono", Consolas, monospace;
+      font-size: 0.8rem; color: var(--accent);
+    }
+    ol.steps strong { font-weight: 700; }
+
+    /* Code block */
+    pre {
+      background: var(--code-bg);
+      border: 1px solid var(--line);
+      padding: 18px 20px;
+      overflow-x: auto;
+      line-height: 1.6;
+      margin-top: 22px;
+      max-width: 42em;
+    }
+    pre .c { color: var(--faint); }
+    pre .s { color: var(--accent); }
+
+    /* Table */
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 0.95rem;
+    }
+    th, td { text-align: left; padding: 10px 14px 10px 0; vertical-align: top; }
+    th {
+      font-family: ui-monospace, "SF Mono", Consolas, monospace;
+      font-size: 0.75rem; font-weight: 700;
+      text-transform: uppercase; letter-spacing: 0.07em;
+      color: var(--faint);
+      border-bottom: 1px solid var(--ink);
+    }
+    td { border-bottom: 1px solid var(--line); }
+    td.mono { white-space: nowrap; }
+    .num { font-variant-numeric: tabular-nums; }
+
+    /* Footer */
+    footer { padding: 32px 0 48px; color: var(--faint); font-size: 0.9rem; }
+    footer .wrap { display: flex; justify-content: space-between; flex-wrap: wrap; gap: 10px; }
+
+    @media (max-width: 560px) {
+      nav a { margin-left: 14px; }
+      ol.steps li { padding-left: 40px; }
+    }
+  </style>
+</head>
+<body>
+
+  <header>
+    <div class="wrap header-row">
+      <a class="name" href="#">shunt</a>
+      <nav>
+        <a href="#how">how it works</a>
+        <a href="#routes">routes</a>
+        <a href="#start">install</a>
+        <a href="#">github</a>
+      </nav>
+    </div>
+  </header>
+
+  <div class="hero">
+    <div class="wrap">
+      <h1>Most prompts don't need a frontier model. Shunt sends each one to the cheapest model that can handle it.</h1>
+      <p class="sub">
+        Shunt is a small, self-hosted router with an OpenAI-compatible API. It classifies
+        every request — coding, reasoning, light chat — and forwards it to an open-source
+        model priced for the job, from $0.01 per million tokens.
+      </p>
+      <div class="install"><code>pip install shunt &amp;&amp; shunt serve</code></div>
+      <div class="links">
+        <a href="#start">Quickstart</a>
+        <a href="#">Documentation</a>
+        <a href="#">Source</a>
+      </div>
+    </div>
+  </div>
+
+  <section id="how">
+    <div class="wrap">
+      <h2>How it works</h2>
+      <ol class="steps">
+        <li><strong>Point your client at Shunt.</strong> It speaks the OpenAI API, so existing SDKs, agents, and tools work unchanged — you only swap the base URL.</li>
+        <li><strong>Each prompt is classified.</strong> A fast local heuristic (with an optional small-model fallback) tags the request: coding, heavy reasoning, general chat, or trivial.</li>
+        <li><strong>The request is switched to a track.</strong> Each track is an ordered chain of open-source models, cheapest capable first. Provider down or rate-limited? Shunt falls through to the next model without surfacing an error.</li>
+        <li><strong>Spend is recorded.</strong> A local SQLite ledger tracks tokens and cost per route, and what the same traffic would have cost on a frontier model.</li>
+      </ol>
+      <pre><span class="c"># your code, unchanged except the base URL</span>
+client = OpenAI(base_url=<span class="s">"http://localhost:8484/v1"</span>)
+
+client.chat.completions.create(
+    model=<span class="s">"shunt/auto"</span>,
+    messages=[{<span class="s">"role"</span>: <span class="s">"user"</span>, <span class="s">"content"</span>: <span class="s">"Refactor this function..."</span>}],
+)</pre>
+    </div>
+  </section>
+
+  <section id="routes">
+    <div class="wrap">
+      <h2>Default routes</h2>
+      <p>Every track is plain YAML in <code>shunt.yaml</code>. Reorder models, change prices, add providers — Shunt ships with sensible defaults and gets out of the way.</p>
+      <br />
+      <table>
+        <thead>
+          <tr><th>Track</th><th>Used for</th><th>First choice</th><th class="num">Output, $/M</th></tr>
+        </thead>
+        <tbody>
+          <tr><td class="mono"><code>light</code></td><td>Classification, extraction, short replies</td><td>Qwen3 8B</td><td class="num">0.01</td></tr>
+          <tr><td class="mono"><code>general</code></td><td>Standard chat and writing</td><td>DeepSeek V4 Flash</td><td class="num">0.20</td></tr>
+          <tr><td class="mono"><code>coding</code></td><td>Everyday code generation and edits</td><td>Qwen3 Coder 30B</td><td class="num">0.27</td></tr>
+          <tr><td class="mono"><code>coding_heavy</code></td><td>Large refactors, difficult debugging</td><td>DeepSeek V4 Pro</td><td class="num">0.87</td></tr>
+          <tr><td class="mono"><code>reasoning</code></td><td>Math, logic, multi-step planning</td><td>Kimi K2.5</td><td class="num">1.90</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+
+  <section>
+    <div class="wrap">
+      <h2>Principles</h2>
+      <p><strong>Self-hosted by default.</strong> Shunt runs on your machine with your provider keys. Prompts never pass through infrastructure you didn't choose.</p>
+      <p><strong>Boring and inspectable.</strong> One Python process, one YAML config, one SQLite file. No dashboard SaaS, no telemetry, no account.</p>
+      <p><strong>Cheap means cheap.</strong> Routing overhead is a few milliseconds and the classifier never calls a paid model unless you opt in.</p>
+    </div>
+  </section>
+
+  <section id="start">
+    <div class="wrap">
+      <h2>Quickstart</h2>
+      <pre>$ pip install shunt
+$ export OPENROUTER_API_KEY=sk-or-...
+$ shunt serve
+<span class="c">listening on http://localhost:8484/v1
+5 tracks loaded from shunt.yaml</span></pre>
+      <p>Then set <code>base_url</code> in any OpenAI client and use <code>model="shunt/auto"</code>. That's the whole integration.</p>
+    </div>
+  </section>
+
+  <footer>
+    <div class="wrap">
+      <span>Shunt — MIT licensed.</span>
+      <span><a href="#">GitHub</a> · <a href="#">Docs</a> · <a href="#">Changelog</a></span>
+    </div>
+  </footer>
+
+</body>
+</html>