weightclass 0.1.0__tar.gz

weightclass-0.1.0/LICENSE

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

weightclass-0.1.0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: weightclass
+Version: 0.1.0
+Summary: Local, policy-driven routing for Codex and Claude workflows.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ictechgy/weightclass
+Project-URL: Repository, https://github.com/ictechgy/weightclass
+Project-URL: Issues, https://github.com/ictechgy/weightclass/issues
+Keywords: cli,codex,claude,router,task-classification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+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: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# weightclass
+
+**weightclass** is a local, policy-driven router for Codex and Claude Code
+workflows. It classifies a task in memory as `low`, `standard`, or `high`,
+chooses a deterministic model-and-effort route, and can start one selected
+vendor process in the foreground.
+
+By default, a request stays with its explicit source vendor. Cross-vendor
+routing is available only through a reviewed policy opt-in. An optional V2
+route can start a separately installed API runtime after explicit review and
+egress acknowledgement; weightclass never reads API credentials or makes
+provider network requests itself.
+
+## Install
+
+weightclass has no runtime dependencies beyond Python 3.10 or later.
+
+```sh
+uv tool install weightclass      # or: pipx install weightclass
+brew install ictechgy/tap/weightclass
+```
+
+Or from a local checkout:
+
+```sh
+git clone https://github.com/ictechgy/weightclass.git
+cd weightclass
+python3 -m pip install .
+```
+
+All three install the `wclass` command. The native Codex and Claude CLIs must
+already be installed and authenticated; weightclass never reads or changes
+their authentication or subscription state.
+
+Releases are cut by pushing a tag; see [RELEASING.md](RELEASING.md).
+
+For reviewable native Codex and Claude Code invocation examples, see
+[Native integrations](docs/integrations.md).
+
+## Run locally
+
+`wclass --help` lists the whole surface:
+
+```text
+wclass [-h] [--version] {classify,route,run,render,v2} ...
+```
+
+`classify`, `route`, and `run` read the task from standard input. `render`
+prints the command of a policy route named by a workflow descriptor and never
+reads a task. `v2` selects a declarative API route; see
+[V2 API routing](#v2-api-routing-through-an-external-runtime).
+
+Every malformed invocation — an unknown subcommand, a missing argument, a bad
+policy — exits `2` with `{"error": "invalid_input"}` on standard error and
+nothing else, so a caller can parse the failure without scraping usage text.
+Flag names are never abbreviated: `--confirm-api-egress` cannot be shortened.
+
+Exit codes are weightclass's own; a selected command's status never overwrites
+them:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. For `run` and `v2 run`, the selected command exited `0`. |
+| `2` | `invalid_task` or `invalid_input`. |
+| `3` | `unsupported_route` — no policy route matched. |
+| `4` | `executor_unavailable` — the command could not be started. |
+| `5` | `api_confirmation_required` — V2 without `--confirm-api-egress`. |
+| `6` | `route_fingerprint_mismatch` — the reviewed route changed. |
+| `7` | `executor_failed` — the command started and exited non-zero. |
+
+Code `1` is not weightclass's; it means the interpreter died on an unhandled
+exception, which is a bug worth reporting.
+
+Code `7` carries the real status in its diagnostic, as
+`{"error": "executor_failed", "executor_exit_code": N}` or, for a command killed
+by a signal, `{"error": "executor_failed", "executor_signal": N}`. A selected
+command inherits standard error, so this diagnostic is always written on a fresh
+line and is the **last line** of standard error — parse that line, not the whole
+stream, which also holds whatever the command itself printed.
+
+A vendor CLI that reports success while declining to do the work still exits
+`0`; weightclass cannot detect that and does not claim to.
+
+Inspect a route before running it:
+
+```sh
+printf '%s' 'Fix a spelling typo in the README.' | wclass route --source-vendor codex
+printf '%s' 'Fix a spelling typo in the README.' | wclass run --source-vendor codex
+```
+
+The built-in routes are intentionally conservative:
+
+- Codex: `low`, `standard`, and `high` use an ephemeral `exec` session in a
+  workspace-write sandbox with `model_reasoning_effort` set to `low`, `medium`,
+  and `high`. Codex has no dedicated effort flag, so the effort is passed as a
+  `-c` configuration override for that one invocation.
+- Claude: `low`, `standard`, and `high` use print mode, no session persistence,
+  and efforts `low`, `medium`, and `high`. Permissions are `acceptEdits`,
+  because print mode is non-interactive: a permission mode that asks a human
+  has nobody to ask, so every edit is refused while `claude` still exits `0` —
+  the router would report success having changed nothing. `acceptEdits`
+  auto-accepts file edits only, which lets the Claude route change files as the
+  Codex route already could. It does not make the two identical: Codex's
+  `workspace-write` also runs commands, while under `acceptEdits` a non-edit
+  tool still goes to a prompt that print mode cannot answer.
+
+Neither default route pins a model. Model selection stays your reviewed
+policy's decision, expressed inside that policy's `command`; see
+[Override the routes](#override-the-routes).
+
+`--source-vendor` is required when weightclass is called from a Codex or Claude
+integration. With the default policy, `--source-vendor codex` selects only
+Codex routes and `--source-vendor claude` selects only Claude routes.
+weightclass is a standalone process, so it does not try to infer its parent
+application.
+
+When `--source-vendor` is omitted, weightclass still pins every tier to a
+single vendor: the vendor of the first route declared in the policy (`codex`
+for the built-in routes). A tier is never silently served by a second vendor —
+that requires `"allow_mixed_vendors": true`. The `vendor` field is always
+present in `wclass route` output.
+
+Classification is local and deterministic. Security, authentication,
+authorization, data, migration, concurrency, performance, production, and
+architecture signals route to `high`. Short typo, spelling, formatting, and
+rename tasks route to `low`; other valid tasks route to `standard`. Unknown or
+oversized task input fails closed.
+
+Three rules make the outcome predictable:
+
+- Signals are matched on whole words, so `reproduction` does not count as
+  `production`. Korean has no word boundaries, so Korean signals are matched by
+  containment and a compound word that embeds a signal may over-escalate.
+- When both a `high` and a `low` signal are present, `high` wins. Under-rating a
+  task is the more expensive mistake.
+- A task of 1,200 characters or more is treated as `high` on length alone, so
+  pasting a large context escalates the tier regardless of wording.
+
+## Override the routes
+
+Use `wclass route --policy policy.json` or `wclass run --policy policy.json` to
+use a reviewed local policy. Routes are considered in listed order, so the
+first matching `tier` is selected. Add `--source-vendor codex` or
+`--source-vendor claude` when invoking it from that vendor. Configure model
+labels and vendor-specific effort arguments only with labels you know are
+available to you.
+
+```json
+{
+  "allow_mixed_vendors": false,
+  "routes": [
+    {
+      "id": "codex-low",
+      "vendor": "codex",
+      "tier": "low",
+      "command": ["codex", "exec", "--model", "your-low-model-label", "-"]
+    },
+    {
+      "id": "claude-high",
+      "vendor": "claude",
+      "tier": "high",
+      "command": ["claude", "--print", "--model", "your-high-model-label", "--effort", "high"]
+    }
+  ]
+}
+```
+
+The `command` tokens are opaque policy values. weightclass validates their shape
+but does not assert vendor CLI semantics or subscription access. Always run
+`wclass route` with a representative non-sensitive task to inspect a policy
+before using `wclass run`.
+
+A token is passed to the selected program as one `argv` entry, without a shell,
+so a token may contain spaces — an install path such as
+`/Users/me/My Tools/claude`, or a multi-word flag value.
+
+A token may not contain a character that a reviewer would not see, since review
+is the whole point of rendering the command. Rejected are every Unicode `C`
+category — control characters, format characters such as zero-width space and
+the bidirectional overrides, surrogates, private-use and unassigned code points
+— along with any whitespace other than the ASCII space, and leading or trailing
+whitespace. The same rule applies to V2's `model` and `effort` labels.
+
+## Bind a run to the selection you reviewed
+
+`wclass route` prints a `route_fingerprint` over the selected route id, vendor,
+command, tier, and the policy's `allow_mixed_vendors` setting — every field the
+descriptor itself shows, so you can recompute it from what you read. Pass it
+back to bind the run to that selection:
+
+```sh
+task='Review this authorization change.'
+fingerprint="$(printf '%s' "$task" | wclass route --policy policy.json \
+  | python3 -c 'import json,sys; print(json.load(sys.stdin)["route_fingerprint"])')"
+printf '%s' "$task" | wclass run --policy policy.json \
+  --ack-route-fingerprint "$fingerprint"
+```
+
+If the policy, the selected route, or the task's tier changed since the review,
+the run stops with exit `6` and `{"error": "route_fingerprint_mismatch"}` rather
+than executing an unreviewed command.
+
+Three limits are worth stating plainly:
+
+- **The flag is optional, and omitting it binds nothing.** `wclass run` without
+  `--ack-route-fingerprint` re-selects from the policy as it finds it. This
+  differs from `wclass v2 run`, where the acknowledgement is mandatory because
+  that path can send your task to a paid API.
+- **The task is not bound, only its tier.** A fingerprint reviewed for one
+  `low` task will run any other `low` task that selects the same route. Binding
+  the task would mean retaining a hash of it, and weightclass does not hash task
+  content.
+- **The argv is bound, not the program.** If the command names a path whose
+  contents are replaced between review and run, the fingerprint still matches.
+  It binds the policy's selection, not the identity of the executable — the same
+  limit V2 has for `--api-runtime`.
+
+A route has no separate `model` field, and a policy that declares one is
+rejected. Only `command` is ever executed, and weightclass cannot verify that a
+label matches the model a command actually selects without asserting vendor CLI
+semantics it deliberately does not assert. A label it cannot verify would let a
+reviewed descriptor advertise one model while another runs, so the model is
+declared once, inside `command`, where `wclass route` prints it in full.
+
+Set `"allow_mixed_vendors": true` only when you intentionally want a Codex
+request to select a Claude route, or the reverse. When it is `false` or absent,
+the vendor filter is applied before tier selection — including when
+`--source-vendor` is omitted, in which case the vendor of the first declared
+tier route is used.
+
+## V2 API routing through an external runtime
+
+V2 adds declarative API-route selection without turning weightclass into an API
+client. weightclass does not read API keys, inspect authentication, or make
+network requests. Instead, you provide an already-installed, trusted runtime
+at an absolute, executable path. That runtime is responsible for provider
+credentials, HTTP, billing, and any provider output.
+
+Use a V2 policy only for API routes; unlike the V1 legacy policy, it cannot
+contain arbitrary command arrays. A route is eligible only for its declared
+source vendors. `codex` maps to the OpenAI provider family and `claude` maps to
+the Anthropic provider family; `allow_cross_provider` must be `true` before a
+route can cross those families.
+
+```json
+{
+  "schema_version": 2,
+  "allow_cross_provider": false,
+  "allow_api": true,
+  "routes": [
+    {
+      "id": "openai-high-api",
+      "tier": "high",
+      "eligible_source_vendors": ["codex"],
+      "provider": "openai",
+      "transport": "api",
+      "model": "your-openai-model-label",
+      "effort": "high",
+      "intended_recipient": "OpenAI API",
+      "intended_billing_boundary": "your OpenAI API account"
+    }
+  ]
+}
+```
+
+First review the selected destination and copy the returned fingerprint.
+weightclass reports the intended recipient and billing boundary from the
+reviewed policy; it does not verify either claim.
+
+```sh
+printf '%s' 'Review this authorization change.' | \
+  wclass v2 route \
+  --policy api-policy.json --source-vendor codex \
+  --api-runtime /absolute/path/to/weightclass-runtime
+```
+
+Starting an API route requires both an explicit egress confirmation and the
+exact fingerprint from that review. weightclass recomputes the route before
+spawning the runtime, so a change to the selected model, effort, source,
+destination, runtime path, or API/cross-provider permission invalidates the
+acknowledgement.
+
+```sh
+printf '%s' 'Review this authorization change.' | \
+  wclass v2 run \
+  --policy api-policy.json --source-vendor codex \
+  --api-runtime /absolute/path/to/weightclass-runtime \
+  --confirm-api-egress --ack-route-fingerprint 'sha256:copied-from-route'
+```
+
+For a selected V2 route, weightclass invokes exactly this fixed protocol,
+without a shell, and passes the task only on standard input:
+
+```text
+/absolute/path/to/weightclass-runtime --provider PROVIDER --model MODEL --effort EFFORT
+```
+
+Do not put API keys, tokens, task text, or personal information in the policy,
+route metadata, or command line. V2 does not provide retries, failover,
+credential management, background execution, or a bundled provider runtime.
+
+## Security boundary and non-goals
+
+- No persistence: weightclass writes no router artifacts or vendor
+  configuration.
+- Task text is read only from standard input, held in memory to classify and
+  pass to the selected child process, then discarded. weightclass never logs,
+  stores, echoes, or places it in diagnostics.
+- weightclass never reads credentials, subscription balances, pricing, cookies,
+  or vendor configuration. It does not capture or process vendor output. V2
+  does not issue provider HTTP requests; a separately installed runtime may do
+  so only after the explicit acknowledgement described above.
+- Route selection is deterministic. Unsupported, malformed, or unsafe input
+  fails closed with a redacted JSON diagnostic.
+- weightclass does not infer source vendor, model availability, subscription
+  tier, or remaining usage. Supply the source vendor explicitly and put model
+  arguments in a reviewed policy's `command` when model routing is required.
+- `wclass run` starts exactly one configured command in the foreground without
+  a shell, retry, backgrounding, recovery, or process supervision.
+- weightclass is not an API proxy, credential manager, cloud service,
+  subscription checker, bundled provider runtime, or unattended multi-agent
+  supervisor.
+- Policies must be reviewed before use. Do not place secrets in a policy.
+- `wclass route` binds a later `wclass run` only when you pass the fingerprint
+  it prints, and only to the policy's selection — see
+  [Bind a run to the selection you reviewed](#bind-a-run-to-the-selection-you-reviewed)
+  for what that does and does not cover. Your control of the policy file, plus
+  the built-in routes that live in code and cannot be swapped, is the boundary
+  that always applies. Treat a policy file the way you treat a shell script.
+- A selected command receives the task on standard input and inherits standard
+  output and error. Whatever it does with the task — including writing it
+  somewhere — is outside weightclass's control, and its exit status is its own.
+
+## Development verification
+
+weightclass has no runtime dependencies. These development tools are not
+required to use it, only to reproduce what CI checks:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests
+PYTHONPATH=src python3 -m compileall -q src
+
+python3 -m pip install ruff mypy build twine
+ruff check src tests
+ruff format --check src tests
+mypy
+python3 -m build && twine check dist/*
+```
+
+## License
+
+[MIT](LICENSE)