awerouter 0.2.0__tar.gz

awerouter-0.2.0/LICENSE

@@ -0,0 +1,207 @@
+Mozilla Public License Version 2.0
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+     means each individual or legal entity that creates, contributes to
+     the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+     means the combination of the Contributions of others (if any) used
+     by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+     means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+     means Source Code Form to which the initial Contributor has attached
+     the notice in Exhibit A, the Executable Form of such Source Code
+     Form, and Modifications of such Source Code Form, in each case
+     including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+     means that the work at issue cannot be redistributed under the terms
+     of this License without violating, conflicting with, or otherwise
+     being incompatible with the terms of the Secondary License.
+
+1.6. "Larger Work"
+     means a work that combines Covered Software with other material, in
+     a separate file or files, that is not Covered Software.
+
+1.7. "License"
+     means this document.
+
+1.8. "Licensable"
+     means having the right to grant, to the maximum extent possible,
+     whether at the time of the initial grant or subsequently, any and
+     all of the rights conveyed by this License.
+
+1.9. "Modifications"
+     means any of the following:
+
+     (a) any addition to or deletion from the substance or structure of
+         the Covered Software; or
+
+     (b) any new Source Code Form to which the initial Contributor has
+         attached the notice in Exhibit A and which constitutes Covered
+         Software.
+
+1.10. "Patent Claims" of a Contributor
+      means any patent claim, including without limitation, method,
+      process, and apparatus claims, in any patent Licensable by such
+      Contributor that would be infringed, but for the grant of the
+      License, by the making, using, selling, offering for sale, having
+      made, import, or transfer of either its Contributions or its
+      Contributor Version.
+
+1.11. "Secondary License"
+      means either the GNU General Public License, Version 2.0, or any
+      later version of such license published by the Free Software
+      Foundation; or the GNU Lesser General Public License, Version 2.1,
+      or any later version of such license published by the Free Software
+      Foundation; or the GNU Affero General Public License, Version 3.0,
+      or any later version of such license published by the Free Software
+      Foundation.
+
+1.12. "Source Code Form"
+     means the form of software preferred for making modifications.
+
+1.13. "You" (or "Your")
+     means an individual or a legal entity exercising rights under this
+     License.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+     Each Contributor hereby grants You a world-wide, royalty-free,
+     non-exclusive license, subject to third-party intellectual property
+     claims, under intellectual property rights (other than patent or
+     trademark) Licensable by such Contributor to use, reproduce, make
+     available, modify, display, perform, distribute, and otherwise
+     exploit its Contributions, either on an unmodified basis, with
+     Modifications, or as part of a Larger Work; and under Patent Claims
+     of such Contributor to make, use, sell, offer for sale, have made,
+     import, and otherwise transfer either its Contributions or its
+     Contributor Version.
+
+2.2. Effective Date
+
+     The licenses granted in Section 2.1 with respect to any Contribution
+     become effective for each Contribution on the date the Contributor
+     first distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+     Nothing in this License shall be construed as excluding or limiting
+     any implied license or other defense to infringement that may
+     otherwise be available to You under applicable patent law.
+
+2.4. Subsequent Licenses
+
+     No Contributor makes additional grants as a result of Your choice to
+     distribute the Covered Software under a subsequent version of this
+     License or under the terms of a Secondary License (if permitted
+     under the terms of this License).
+
+2.5. Representation
+
+     Each Contributor represents that the Contributor believes its
+     Contributions are its original creation(s) or it has sufficient
+     rights to grant the rights to its Contributions conveyed by this
+     License.
+
+3. Obligations
+--------------
+
+3.1. Distribution of Source Code Form
+
+     All distribution of Covered Software in Source Code Form, including
+     any Modifications that You create or to which You contribute, must
+     be under the terms of this License. You must inform recipients that
+     the Source Code Form of the Covered Software is subject to the terms
+     of this License, and how they can obtain a copy of this License.
+
+3.2. Distribution of Executable Form
+
+     If You distribute Covered Software in Executable Form then:
+
+     (a) such Covered Software must also be made available in Source Code
+         Form; and
+
+     (b) You may distribute such Executable Form under the terms of this
+         License; and
+
+     (c) You must include a copy of this License with every copy of the
+         Covered Software in Executable Form You distribute; and
+
+     (d) You may not prevent recipients from copying, modifying, or
+         further distributing the Covered Software in Source Code Form.
+
+3.3. Distribution of a Larger Work
+
+     You may create and distribute a Larger Work under terms of Your
+     choice, provided that You also comply with the requirements of this
+     License for the Covered Software.
+
+3.4. Notices
+
+     You may not remove or alter the substance of any license notices
+     (including copyright notices, patent notices, disclaimers of
+     warranty, or limitations of liability) contained within the Source
+     Code Form of the Covered Software.
+
+3.5. Application of Additional Terms
+
+     You may not offer or impose any additional or different terms on any
+     portion of the Covered Software that would alter or restrict the
+     applicable version of this License or the recipients' rights
+     hereunder.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+     if You fail to comply with any of its terms. However, if You become
+     compliant, then the rights granted under this License are
+     reinstated.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+     infringement claim (excluding declaratory judgment actions,
+     counter-claims, and cross-claims) alleging that a Contributor
+     Version directly or indirectly infringes any patent, then the rights
+     granted to You by any and all Contributors for the Covered Software
+     under Sections 2.1 and 2.2 shall terminate.
+
+6. Disclaimer of Warranty
+-------------------------
+
+Covered Software is provided under this License on an "as is" basis,
+without warranty of any kind, either express or implied.
+
+7. Limitation of Liability
+---------------------------
+
+To the extent permitted by applicable law, in no event shall any
+Contributor be liable to You for any indirect, special, incidental, or
+consequential damages.
+
+8. Miscellaneous
+----------------
+
+8.1. This License represents the complete agreement concerning subject
+     matter hereof.
+
+8.2. If any provision of this License is held to be unenforceable, it
+     shall be reformed only to the minimum extent necessary.

awerouter-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include README_cn.md
+recursive-include assets *.jpg *.png
+recursive-include docs *.md

awerouter-0.2.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: awerouter
+Version: 0.2.0
+Summary: Smart LLM router: fast cheap tasks to flash, hard decisions to pro.
+Author: Peng
+License: MPL-2.0
+Keywords: ai,llm,router,claude,proxy,claude-code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <h1>awerouter: Smart LLM Router</h1>
+  <p><strong>Route cheap/fast tasks to Flash, hard decisions to Pro.</strong></p>
+  <p>Transparent Anthropic proxy that routes Claude Code requests by structural signals — no keyword guessing, no LLM classifier.</p>
+  <p>
+    <strong>English</strong> ·
+    <a href="./README_cn.md">简体中文</a>
+  </p>
+  <p>
+    <img src="https://img.shields.io/pypi/v/awerouter?style=flat-square&color=7C3AED" alt="Version">
+    <img src="https://img.shields.io/badge/python-%E2%89%A53.9-0EA5E9?style=flat-square" alt="Python">
+    <img src="https://img.shields.io/badge/license-MPL--2.0-22C55E?style=flat-square" alt="License">
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/status-alpha-c96a3d?style=flat-square" alt="Status">
+    <img src="https://img.shields.io/badge/install-pip-22C55E?style=flat-square" alt="pip">
+    <img src="https://img.shields.io/badge/platform-terminal-334155?style=flat-square" alt="Platform">
+    <img src="https://img.shields.io/pypi/dm/awerouter?style=flat-square" alt="Downloads">
+    <img src="https://img.shields.io/github/stars/mugpeng/awerouter?style=flat-square" alt="Stars">
+  </p>
+  <p>
+    <a href="https://ko-fi.com/mugpeng"><img src="https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
+  </p>
+</div>
+
+> Transparent proxy that splits Claude Code traffic across providers by cost and capability.
+
+## Install
+
+```bash
+pip install awerouter
+```
+
+## Quick Start
+
+```bash
+# 1. Init config (creates ~/.config/awerouter/{providers,routing}.json)
+awerouter init
+
+# 2. Interactively add a profile (writes both files, references stay consistent)
+awerouter add
+#    or edit by hand: providers.json for keys (${ENV_VAR}), routing.json for flash/pro
+
+# 3. Start the daemon (profile name optional when only one exists)
+awerouter serve [cc-router-1]     # shorthand: awerouter cc-router-1
+
+# 4. Point CC at it — the serve banner prints both lines below
+export ANTHROPIC_BASE_URL=http://127.0.0.1:20128
+# aweswitch profile env: ANTHROPIC_MODEL=auto, _HAIKU_=flash, _OPUS_=pro
+```
+
+## Config
+
+Two files in `~/.config/awerouter/` (override with `AWEROUTER_CONFIG_DIR`):
+
+**providers.json** — endpoints + keys, grouped by agent (redacted in `config show`):
+
+```json
+{
+  "claude": {
+    "stepfun":   { "base_url": "https://api.stepfun.com/step_plan", "auth": "${STEPFUN_AUTH_TOKEN}" },
+    "anthropic": { "base_url": "https://api.anthropic.com",          "auth": "${ANTHROPIC_KEY}" }
+  },
+  "codex": {
+    "stepfun": { "base_url": "https://api.stepfun.com/v1", "auth": "${STEPFUN_AUTH_TOKEN}" }
+  }
+}
+```
+
+The auth header is **auto-detected from `base_url`**: `anthropic.com` → `x-api-key` (bare token); everyone else → `Authorization` (auto-prefixes `Bearer `). No `auth_header` field needed unless the heuristic is wrong.
+
+**routing.json** — strategy, no secrets (safe to commit):
+
+```json
+{
+  "settings": {
+    "backgroundModel": "flash",
+    "thinkModel": "pro"
+  },
+  "cc-router-1": {
+    "agent": "claude",
+    "longContextThreshold": 8000,
+    "destinations": {
+      "flash": "stepfun,step-3.7-flash",
+      "pro":   "anthropic,claude-opus-5"
+    }
+  }
+}
+```
+
+`settings` is optional (defaults: `flash`/`pro`). It defines the model ids CC sends for background (Haiku) and think (Opus) tiers. The main loop uses `auto` — routed by difficulty by L3. Set these in your aweswitch profile: `ANTHROPIC_DEFAULT_HAIKU_MODEL=flash`, `ANTHROPIC_MODEL=auto`, `ANTHROPIC_DEFAULT_OPUS_MODEL=pro`.
+
+Keys reference `${ENV_VAR}` syntax. Missing env vars die with a clear message at startup.
+
+> **Profile-based routing:** `routing.json` groups configs under profile ids (like aweswitch). `awerouter serve <profile>` starts one; with a single profile it auto-selects. `agent` maps the profile to a providers.json group.
+
+## How It Routes
+
+Three-layer first-match-wins pipeline, evaluated per request:
+
+| Layer | Signal | Decision |
+|-------|--------|----------|
+| L1 Capability | `web_search` tool in body | **pro** (flash can't run it) |
+| L2 Tier label | `model == c1/flash` or `c1/think` | flash / pro respectively |
+| L3 Difficulty | token count > threshold, or has image | **pro**; else **flash** |
+
+CC's `/model` picker sets the tier model id (c1/flash / c1/pro / c1/think). awerouter reads it and routes accordingly — no keyword parsing, no LLM classifier.
+
+## Commands
+
+```bash
+awerouter init                        # create default config (= config init)
+awerouter add                         # interactively add a profile (and new providers)
+awerouter list                        # list profiles (name, agent, flash, pro, threshold)
+awerouter show [PROFILE]              # show one profile or all config (redacted)
+awerouter serve [PROFILE] [--port 20128] [--host 127.0.0.1]
+awerouter <PROFILE>                   # shorthand for serve PROFILE
+awerouter config path | show | edit | init
+awerouter log [--lines 20]
+awerouter stats
+awerouter calibrate
+```
+
+`calibrate` shows the message-token distribution of L3 traffic (the threshold-sensitive layer; messages only — system prompt and tools are excluded) and suggests candidate `longContextThreshold` values at p90/p95/p99. Run it after some real traffic, then edit `routing.json`.
+
+## Troubleshooting
+
+**CC shows `502 status code (no body)` right after launch** — a shell proxy (Clash etc.) is hijacking loopback traffic. Requests to `127.0.0.1:20128` go into the proxy, whose `127.0.0.1` is itself, so nothing is listening and the proxy returns an empty 502. `serve` prints a warning when it detects this; fix it by exempting loopback in your shell config:
+
+```bash
+export no_proxy=127.0.0.1,localhost NO_PROXY=127.0.0.1,localhost
+```
+
+Then open a new terminal and relaunch CC.
+
+## Development
+
+```bash
+git clone https://github.com/mugpeng/awerouter
+cd awerouter
+pip install -e ".[dev]"
+pytest
+```
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for architecture notes, config semantics, and the release process.
+
+## Support
+
+If awerouter saves you money, consider supporting it:
+
+- ⭐ Star the repo — it helps others find it.
+- ☕ [Ko-fi](https://ko-fi.com/mugpeng) — buy me a coffee.
+- 💬 WeChat — scan the QR code below.
+
+<p align="center">
+  <img src="assets/images/wechat-pay.jpg" alt="WeChat Pay" width="240">
+</p>
+
+> awerouter is free and open source. Sponsors keep it maintained — thank you.

awerouter-0.2.0/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+  <h1>awerouter: Smart LLM Router</h1>
+  <p><strong>Route cheap/fast tasks to Flash, hard decisions to Pro.</strong></p>
+  <p>Transparent Anthropic proxy that routes Claude Code requests by structural signals — no keyword guessing, no LLM classifier.</p>
+  <p>
+    <strong>English</strong> ·
+    <a href="./README_cn.md">简体中文</a>
+  </p>
+  <p>
+    <img src="https://img.shields.io/pypi/v/awerouter?style=flat-square&color=7C3AED" alt="Version">
+    <img src="https://img.shields.io/badge/python-%E2%89%A53.9-0EA5E9?style=flat-square" alt="Python">
+    <img src="https://img.shields.io/badge/license-MPL--2.0-22C55E?style=flat-square" alt="License">
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/status-alpha-c96a3d?style=flat-square" alt="Status">
+    <img src="https://img.shields.io/badge/install-pip-22C55E?style=flat-square" alt="pip">
+    <img src="https://img.shields.io/badge/platform-terminal-334155?style=flat-square" alt="Platform">
+    <img src="https://img.shields.io/pypi/dm/awerouter?style=flat-square" alt="Downloads">
+    <img src="https://img.shields.io/github/stars/mugpeng/awerouter?style=flat-square" alt="Stars">
+  </p>
+  <p>
+    <a href="https://ko-fi.com/mugpeng"><img src="https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
+  </p>
+</div>
+
+> Transparent proxy that splits Claude Code traffic across providers by cost and capability.
+
+## Install
+
+```bash
+pip install awerouter
+```
+
+## Quick Start
+
+```bash
+# 1. Init config (creates ~/.config/awerouter/{providers,routing}.json)
+awerouter init
+
+# 2. Interactively add a profile (writes both files, references stay consistent)
+awerouter add
+#    or edit by hand: providers.json for keys (${ENV_VAR}), routing.json for flash/pro
+
+# 3. Start the daemon (profile name optional when only one exists)
+awerouter serve [cc-router-1]     # shorthand: awerouter cc-router-1
+
+# 4. Point CC at it — the serve banner prints both lines below
+export ANTHROPIC_BASE_URL=http://127.0.0.1:20128
+# aweswitch profile env: ANTHROPIC_MODEL=auto, _HAIKU_=flash, _OPUS_=pro
+```
+
+## Config
+
+Two files in `~/.config/awerouter/` (override with `AWEROUTER_CONFIG_DIR`):
+
+**providers.json** — endpoints + keys, grouped by agent (redacted in `config show`):
+
+```json
+{
+  "claude": {
+    "stepfun":   { "base_url": "https://api.stepfun.com/step_plan", "auth": "${STEPFUN_AUTH_TOKEN}" },
+    "anthropic": { "base_url": "https://api.anthropic.com",          "auth": "${ANTHROPIC_KEY}" }
+  },
+  "codex": {
+    "stepfun": { "base_url": "https://api.stepfun.com/v1", "auth": "${STEPFUN_AUTH_TOKEN}" }
+  }
+}
+```
+
+The auth header is **auto-detected from `base_url`**: `anthropic.com` → `x-api-key` (bare token); everyone else → `Authorization` (auto-prefixes `Bearer `). No `auth_header` field needed unless the heuristic is wrong.
+
+**routing.json** — strategy, no secrets (safe to commit):
+
+```json
+{
+  "settings": {
+    "backgroundModel": "flash",
+    "thinkModel": "pro"
+  },
+  "cc-router-1": {
+    "agent": "claude",
+    "longContextThreshold": 8000,
+    "destinations": {
+      "flash": "stepfun,step-3.7-flash",
+      "pro":   "anthropic,claude-opus-5"
+    }
+  }
+}
+```
+
+`settings` is optional (defaults: `flash`/`pro`). It defines the model ids CC sends for background (Haiku) and think (Opus) tiers. The main loop uses `auto` — routed by difficulty by L3. Set these in your aweswitch profile: `ANTHROPIC_DEFAULT_HAIKU_MODEL=flash`, `ANTHROPIC_MODEL=auto`, `ANTHROPIC_DEFAULT_OPUS_MODEL=pro`.
+
+Keys reference `${ENV_VAR}` syntax. Missing env vars die with a clear message at startup.
+
+> **Profile-based routing:** `routing.json` groups configs under profile ids (like aweswitch). `awerouter serve <profile>` starts one; with a single profile it auto-selects. `agent` maps the profile to a providers.json group.
+
+## How It Routes
+
+Three-layer first-match-wins pipeline, evaluated per request:
+
+| Layer | Signal | Decision |
+|-------|--------|----------|
+| L1 Capability | `web_search` tool in body | **pro** (flash can't run it) |
+| L2 Tier label | `model == c1/flash` or `c1/think` | flash / pro respectively |
+| L3 Difficulty | token count > threshold, or has image | **pro**; else **flash** |
+
+CC's `/model` picker sets the tier model id (c1/flash / c1/pro / c1/think). awerouter reads it and routes accordingly — no keyword parsing, no LLM classifier.
+
+## Commands
+
+```bash
+awerouter init                        # create default config (= config init)
+awerouter add                         # interactively add a profile (and new providers)
+awerouter list                        # list profiles (name, agent, flash, pro, threshold)
+awerouter show [PROFILE]              # show one profile or all config (redacted)
+awerouter serve [PROFILE] [--port 20128] [--host 127.0.0.1]
+awerouter <PROFILE>                   # shorthand for serve PROFILE
+awerouter config path | show | edit | init
+awerouter log [--lines 20]
+awerouter stats
+awerouter calibrate
+```
+
+`calibrate` shows the message-token distribution of L3 traffic (the threshold-sensitive layer; messages only — system prompt and tools are excluded) and suggests candidate `longContextThreshold` values at p90/p95/p99. Run it after some real traffic, then edit `routing.json`.
+
+## Troubleshooting
+
+**CC shows `502 status code (no body)` right after launch** — a shell proxy (Clash etc.) is hijacking loopback traffic. Requests to `127.0.0.1:20128` go into the proxy, whose `127.0.0.1` is itself, so nothing is listening and the proxy returns an empty 502. `serve` prints a warning when it detects this; fix it by exempting loopback in your shell config:
+
+```bash
+export no_proxy=127.0.0.1,localhost NO_PROXY=127.0.0.1,localhost
+```
+
+Then open a new terminal and relaunch CC.
+
+## Development
+
+```bash
+git clone https://github.com/mugpeng/awerouter
+cd awerouter
+pip install -e ".[dev]"
+pytest
+```
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for architecture notes, config semantics, and the release process.
+
+## Support
+
+If awerouter saves you money, consider supporting it:
+
+- ⭐ Star the repo — it helps others find it.
+- ☕ [Ko-fi](https://ko-fi.com/mugpeng) — buy me a coffee.
+- 💬 WeChat — scan the QR code below.
+
+<p align="center">
+  <img src="assets/images/wechat-pay.jpg" alt="WeChat Pay" width="240">
+</p>
+
+> awerouter is free and open source. Sponsors keep it maintained — thank you.