subproto 0.1.0__tar.gz

subproto-0.1.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,62 @@
+name: Bug report
+description: A command that does not do what its page says it does
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The single most useful thing you can paste here is the command and its real
+        output. Most "it does not work" reports are a Python version, a port in use,
+        or a slot that is observing rather than enforcing — `doctor` tells you which.
+  - type: textarea
+    id: command
+    attributes:
+      label: The command, exactly as you typed it
+      render: shell
+      placeholder: |
+        subproto demo --port 8000 --slots
+        subproto report
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected, and what printed instead
+      description: Paste the output. Do not paraphrase a number.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `subproto doctor`
+      description: |
+        If that command does not exist in your version, paste instead:
+        `python3 --version`, `uname -sr` (or your Windows build), and
+        `echo "$SUBPROTO_HOME"`.
+      render: shell
+    validations:
+      required: true
+  - type: dropdown
+    id: slotstate
+    attributes:
+      label: Are any slots enforcing?
+      description: Observation-only is the default; a drop you did not turn on is a different bug.
+      options: [none, SUBPROTO_APPLY set, a config file, I do not know]
+    validations:
+      required: true
+  - type: textarea
+    id: noise
+    attributes:
+      label: Anything else running on this machine
+      description: >
+        A second proxy, an Ollama server, a training run or a laptop on battery changes
+        both the latency numbers and whether a model backend answers in time.
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirmations
+      options:
+        - label: I can reproduce this on a fresh `SUBPROTO_HOME` (or I say what is in mine)
+          required: true
+        - label: I redacted any API key or source code from the pasted output
+          required: true

subproto-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: SECURITY.md — what subproto does and does not send anywhere
+    url: https://github.com/aashish254/limen/blob/main/SECURITY.md
+    about: It is a local proxy with no telemetry and no update check. Read this before wiring it into an agent that handles private code.
+  - name: WIRING.md — base_url per coding agent
+    url: https://github.com/aashish254/limen/blob/main/WIRING.md
+    about: Claude Code, Codex, Gemini CLI, Cline, aider, OpenCode. Open an issue if your agent or version is missing.
+  - name: CONTRIBUTING.md — the invariants a PR has to keep
+    url: https://github.com/aashish254/limen/blob/main/CONTRIBUTING.md
+    about: Zero dependencies, colour only on a state word, and a test that would have failed without your change.

subproto-0.1.0/.github/ISSUE_TEMPLATE/model-or-agent.yml

@@ -0,0 +1,59 @@
+name: Wiring a model or an agent
+description: Add a model backend to the registry, or document an agent's base_url setup
+labels: ["good first issue"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Two kinds of contribution live here, and both are small:
+
+        **A model backend.** `subproto/systemone/registry.py` is the only file that
+        knows model families. If your server already answers `GET /health` and
+        `POST /score` (`{"state", "question", "options"}` in, `{option: probability}`
+        out), you can point at it today with `SUBPROTO_MODEL=http://host:port` and no
+        code change — a registry entry is only needed to give it a name in the report
+        and the ablation.
+
+        **An agent's wiring.** `WIRING.md` holds the exact `base_url` / env setup per
+        coding agent. A missing agent, or a setup that changed upstream, is an issue
+        worth opening.
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Which one is this?
+      options: [a model backend / adapter, an agent's wiring page, something else]
+    validations:
+      required: true
+  - type: textarea
+    id: contract
+    attributes:
+      label: For a backend — what does it answer?
+      description: >
+        Paste a real `curl` of `/health` and of one `/score` request and response. If
+        it answers a different shape, say so: the adapter seam is in
+        `subproto/systemone/base.py`, and a translation layer there is a reasonable
+        change if the question it answers is genuinely the same question.
+      render: shell
+  - type: textarea
+    id: evidence
+    attributes:
+      label: For a wiring page — how did you verify it?
+      description: The command you ran, and the line in `subproto report` that proves traffic reached the proxy.
+  - type: textarea
+    id: numbers
+    attributes:
+      label: What it scores on the labelled set (optional, and never required to open this)
+      description: >
+        `LAYA_URL=http://127.0.0.1:8000 python3 -m bench.ablation --adapters laya` prints
+        precision against the shipped heuristic and an `answered N/M` column. A backend
+        that answered nothing must print `—`, not a number: if your run shows a number
+        for an unreachable endpoint, that is a bug, please open it separately.
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirmations
+      options:
+        - label: I read CONTRIBUTING.md, including the invariants
+          required: true
+        - label: No API key or proprietary prompt data is pasted above
+          required: true

subproto-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## What rule does this change?
+
+One or two sentences. Name the decision the code makes, not the file you edited.
+
+## How do I see it fail without this change?
+
+```
+the command you ran
+```
+
+Paste the **real** output, including the line that shows the fix.
+
+## Gate
+
+- [ ] `bash run_tests.sh` prints `ALL GATES PASS` (paste the last 3 lines)
+- [ ] New rule ⇒ new mutant in `bench/mutation_gate.py`, and it is reported `KILLED`
+- [ ] Any printed page touched ⇒ `subproto/tests/test_style.py` still passes
+- [ ] Any claim in README/SPEC/ROADMAP changed ⇒ the number came from a command above
+
+## Invariants
+
+Which of I2 (cached prefix), I3 (tail is sacred), I4 (local only), I5 (byte
+transparent), I6 (measured not claimed) does this touch, and what keeps it whole?
+
+## Labels
+
+Fixes #… — or say `no issue` for a drive-by.

subproto-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,168 @@
+name: verify
+
+# Three jobs, answering three different questions:
+#   suite    — do the tests pass on someone else's OS, on both supported Pythons?
+#   gates    — does the whole one-command gate (benches, demo, mutation gate) hold?
+#   install  — can a stranger `pip install` this and run the command, from a
+#              directory that is *not* the clone? Nothing in the runtime may
+#              depend on repo files, so this job unpacks the wheel elsewhere.
+#
+# No API key, no spend, no model weights: the Laya legs skip themselves unless
+# SUBPROTO_LAYA_PYTHON names an interpreter that can import `laya`, and `fakeup`
+# stands in for every provider.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  suite:
+    name: pytest ${{ matrix.os }} py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.9", "3.11"]
+        os: [ubuntu-latest, macos-latest]
+        include:
+          # Windows runs, but is not a release gate: `os.getloadavg` is POSIX and
+          # ANSI escape handling differs. It is reported rather than hidden, so a
+          # Windows contributor sees the real state of their platform here.
+          - os: windows-latest
+            python: "3.11"
+    continue-on-error: ${{ matrix.os == 'windows-latest' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          allow-prereleases: false
+      - name: Install pytest (the package itself has zero dependencies)
+        run: python -m pip install --quiet "pytest>=7"
+      - name: Byte-compile every package under -W error
+        run: >-
+          python -W error -m compileall -q subproto fakeup bench train
+      - name: pytest
+        run: python -m pytest -q
+
+  gates:
+    name: one-command gate (benches + demo + mutation gate)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev requirements
+        run: python -m pip install --quiet -r requirements-dev.txt
+      - name: bash run_tests.sh
+        run: bash run_tests.sh
+        env:
+          PYTHON: python3.11
+
+  install:
+    name: pip install and run (${{ matrix.os }} py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.9", "3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Build the sdist and the wheel
+        run: |
+          python -m pip install --quiet build
+          python -m build
+      - name: Install the wheel into a clean venv, offline
+        run: |
+          python -m venv .verify-venv
+          .verify-venv/bin/python -m pip install --quiet --no-index --find-links dist subproto
+          .verify-venv/bin/python -m pip check
+      - name: The installed package agrees about which build it is
+        run: |
+          .verify-venv/bin/python - <<'PYV'
+          import importlib.metadata as md
+          import subproto
+          assert md.version("subproto") == subproto.__version__, (
+              md.version("subproto"), subproto.__version__)
+          print("metadata and subproto.__version__ agree:", subproto.__version__)
+          PYV
+          .verify-venv/bin/subproto --version
+      - name: Run the installed command from outside the clone
+        shell: bash
+        run: |
+          set -euo pipefail
+          ROOT="$PWD"
+          WORK="$(mktemp -d)"
+          BIN="$ROOT/.verify-venv/bin/subproto"
+          cd "$WORK"
+          SUBPROTO_HOME="$WORK/home" "$BIN" --help > /dev/null
+          SUBPROTO_HOME="$WORK/home" "$BIN" doctor --port 0 --json > doctor.json
+          SUBPROTO_HOME="$WORK/home" "$BIN" demo --port 8743 --slots > demo.log
+          SUBPROTO_HOME="$WORK/home" "$BIN" report
+          echo "--- doctor ---"; cat doctor.json
+          echo "--- demo tail ---"; tail -5 demo.log
+      - name: The installed Router ranks on evidence that shipped with it
+        shell: bash
+        run: |
+          set -euo pipefail
+          PY="$GITHUB_WORKSPACE/.verify-venv/bin/python"
+          # From a directory that is not the clone, twice over: inside the clone a
+          # `import subproto` answers from the source tree, so every assertion below
+          # would pass with nothing installed at all. A pip user has no source tree,
+          # and a Router that reads its ranking evidence out of one worked in CI and
+          # nowhere in their day — degrading to manual selection so quietly that no
+          # test fails (S46/M4).
+          cd "$(mktemp -d)"
+          "$PY" -c "import subproto; assert 'site-packages' in subproto.__file__, subproto.__file__"
+          "$PY" - <<'PYV'
+          import json, os, subproto
+          from subproto.systemone import router
+          path = router.DEFAULT_ABLATION_JSON
+          pkg = os.path.dirname(os.path.abspath(subproto.__file__))
+          assert path.startswith(pkg + os.sep), "%s is outside the package" % path
+          data = json.load(open(path))
+          assert {"heuristic", "adapters"} <= set(data), sorted(data)
+          # `adapters` is a list of records keyed by "name" — the schema load_evidence()
+          # reads. This used to test `"laya" in data["adapters"]`, a shape guess that was
+          # never true of the file and reddened all four install legs of the first public
+          # run: the suite proves this through load_evidence(), so nothing local saw it.
+          assert "laya" in [a.get("name") for a in data["adapters"]], data["adapters"]
+          ev = router.load_evidence()
+          assert {"heuristic", "laya"} <= set(ev), sorted(ev)
+          print("installed Router ranks on %s" % os.path.relpath(path, pkg))
+          PYV
+      - name: Confirm the sdist carries what the docs tell people to run
+        run: |
+          python - <<'PYSMOKE'
+          import glob, os, tarfile
+          name = glob.glob("dist/*.tar.gz")[0]
+          names = set(tarfile.open(name).getnames())
+          top = os.path.basename(name)[: -len(".tar.gz")]
+          need = ["pyproject.toml", "run_tests.sh", "bench/ablation.py",
+                  "bench/mutation_gate.py", "fakeup/server.py", "WIRING.md"]
+          missing = [n for n in need if "%s/%s" % (top, n) not in names]
+          assert not missing, "sdist is missing: %s" % missing
+          print("sdist carries the bench and the fakeup mock")
+          PYSMOKE
+      - name: Run install.sh, the no-package-index route the README leads with
+        run: |
+          set -euo pipefail
+          SUBPROTO_BIN_DIR="$PWD/.verify-bin" bash install.sh
+          export SUBPROTO_HOME="$(mktemp -d)"
+          ./.verify-bin/subproto doctor --port 0 --json
+          ./.verify-bin/subproto demo --port 8744 --slots > /dev/null
+          ./.verify-bin/subproto report | head -3

subproto-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,43 @@
+name: pages
+
+# The landing page is a build artifact of the measurement run, so it is committed and
+# published as-is: `bench/launch_stats.py` measures, `tools/make_site.py` renders, and
+# this workflow only carries `_site/` to Pages. Nothing recomputes a number here, so the
+# page a reviewer reads on github.io is byte-identical to the one in the repo.
+
+on:
+  push:
+    branches: [main]
+    paths: ["_site/**", "docs/assets/fonts/**", ".github/workflows/pages.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Refuse to publish a page with an unrendered token
+        run: |
+          if grep -rl '{{[A-Z_]*}}' _site >/dev/null 2>&1; then
+            grep -rn '{{[A-Z_]*}}' _site
+            exit 1
+          fi
+          test -s _site/index.html
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,81 @@
+name: publish
+
+# The release is built and uploaded from the tag, by CI, with no credential stored on
+# anybody's laptop: PyPI trusts this workflow's OIDC identity, registered once as a
+# "pending publisher" on pypi.org. Nothing here recomputes a number — `verify` is the
+# gate on the code, and this job only packages the tagged tree, proves the artifact
+# installs and runs, and hands it to the index.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Which tag to publish
+        default: v0.1.0
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref_name }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Every classifier must be one PyPI recognises
+        run: |
+          set -euo pipefail
+          python - <<'PYP'
+          import re, html, tomllib, urllib.request
+          declared = tomllib.load(open("pyproject.toml", "rb"))["project"]["classifiers"]
+          page = urllib.request.urlopen("https://pypi.org/classifiers/").read().decode()
+          valid = {html.unescape(re.sub(r"<[^>]+>", "", m.group(1))).strip()
+                   for m in re.finditer(r'data-clipboard-target="source">(.*?)</a>', page, re.S)}
+          assert len(valid) > 500, "the classifier list did not parse (%d)" % len(valid)
+          bad = [c for c in declared if c not in valid]
+          for c in declared:
+              print("%s %s" % ("ok  " if c not in bad else "BAD ", c))
+          # One invented trove 400s the whole upload, after the files are already sent.
+          assert not bad, "not on https://pypi.org/classifiers/: %s" % bad
+          PYP
+      - name: Build the sdist and the wheel
+        run: |
+          python -m pip install --quiet build twine
+          python -m build
+          twine check dist/*
+      - name: The artifact must carry the version the tag was cut from
+        run: |
+          set -euo pipefail
+          REF="${{ github.event.inputs.tag || github.ref_name }}"
+          TAG="${REF#v}"
+          SRC="$(python -c 'import subproto; print(subproto.__version__)')"
+          WHEEL="$(basename dist/*.whl)"
+          echo "tag=$TAG source=$SRC wheel=$WHEEL"
+          test "$SRC" = "$TAG" || { echo "subproto.__version__ disagrees with the tag"; exit 1; }
+          test "$WHEEL" = "subproto-$TAG-py3-none-any.whl" \
+            || { echo "the built wheel is not tagged $TAG"; exit 1; }
+      - name: Install the built wheel offline and run it
+        run: |
+          set -euo pipefail
+          python -m venv .smoke
+          .smoke/bin/python -m pip install --quiet --no-index --find-links dist subproto
+          .smoke/bin/python -m pip check
+          cd "$(mktemp -d)"
+          SUBPROTO_HOME="$PWD" .smoke/bin/subproto --version
+          SUBPROTO_HOME="$PWD" .smoke/bin/subproto doctor --port 0 > /dev/null
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

subproto-0.1.0/.subproto.example.json

@@ -0,0 +1,9 @@
+{
+  "data_dir": "~/.subproto",
+  "port": 8787,
+  "store_bodies": false,
+  "record_features": true,
+  "laya_url": null,
+  "openai_upstream": "https://api.openai.com",
+  "anthropic_upstream": "https://api.anthropic.com"
+}