langchef 0.1.0__tar.gz

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

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: The agent contract
+    url: https://deepskandpal.github.io/LangChef/cli.html
+    about: What each command does, what it writes, and what the exit codes mean. Read this before filing about CLI behaviour.
+  - name: How the numbers work
+    url: https://deepskandpal.github.io/LangChef/numbers.html
+    about: What a verdict, an interval and a detection limit actually mean here.

langchef-0.1.0/.github/ISSUE_TEMPLATE/decision.yml

@@ -0,0 +1,51 @@
+name: Decision
+description: A call to make, not code to write
+labels: ["type:decision", "lifecycle:spec", "agent:needs-human"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Decisions are left open on purpose, with the evidence that closes them named up front, so
+        that none of them becomes a standing debate. Settled ones go into `DECISIONS.md` with a
+        date and are not reopened.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: The question, in one line.
+    validations: {required: true}
+  - type: textarea
+    id: background
+    attributes:
+      label: Background
+      description: Why it is open, and what it costs to get wrong.
+    validations: {required: true}
+  - type: textarea
+    id: options
+    attributes:
+      label: Options
+      value: |
+        ### (a) 
+        - **For:** 
+        - **Against:** 
+
+        ### (b) 
+        - **For:** 
+        - **Against:** 
+    validations: {required: true}
+  - type: textarea
+    id: default
+    attributes:
+      label: The default if nobody decides
+      description: |
+        There is always one, and it is usually the bad one — a threshold hard-coded where nobody
+        reviews it. Name it, so that drifting is a choice rather than an accident.
+    validations: {required: true}
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria (closes when)
+      description: The evidence, the date, or the trigger. Not "when we have time".
+      value: |
+        - [ ] The call is written into `DECISIONS.md` as a new dated entry
+    validations: {required: true}

langchef-0.1.0/.github/ISSUE_TEMPLATE/defect.yml

@@ -0,0 +1,52 @@
+name: Defect
+description: Behaviour that is wrong, not merely absent
+labels: ["type:defect", "lifecycle:ready"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **A wrong number is worse than a crash here, because nothing complains.** If a figure looks
+        wrong, this is the most valuable issue you can file.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: The behaviour, and what it should be instead.
+    validations: {required: true}
+  - type: textarea
+    id: background
+    attributes:
+      label: Background
+      description: How it was found, and why it matters more or less than it looks like it does.
+    validations: {required: true}
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to see it
+      description: The commands. Prefer the dogfood workspace, which needs no API key.
+      render: shell
+    validations: {required: true}
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What kind of wrong
+      options:
+        - A wrong number — silent, and looks like a right number
+        - A wrong verdict — the arithmetic is right, the conclusion is not
+        - An integrity gap — the result can be manufactured
+        - A crash or an error
+        - An inconvenience
+    validations: {required: true}
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      value: |
+        - [ ] A test that fails before the fix and passes after
+        - [ ] `./scripts/verify.sh` stays green (10/10)
+    validations: {required: true}
+  - type: input
+    id: start
+    attributes:
+      label: Start at
+      placeholder: src/langchef/judge/runner.py

langchef-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,66 @@
+name: Feature
+description: A capability that does not exist yet
+labels: ["type:feature", "lifecycle:spec"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Write this so somebody — or something — can pick it up cold, months from now, with no
+        memory of this conversation. That is the whole standard. See any existing issue for the
+        shape; [#28](https://github.com/deepskandpal/LangChef/issues/28) is a good example.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: One or two sentences, imperative. The capability, not the implementation.
+    validations: {required: true}
+  - type: textarea
+    id: background
+    attributes:
+      label: Background
+      description: |
+        Why this exists and what is worse without it. Where it came from — a build-order section,
+        a defect, a conversation. Be concrete: "it would be nice" is not a reason.
+    validations: {required: true}
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      value: |
+        - **Blocked by:** #
+        - **Blocks:** #
+        - **Related:** #
+        - **Needs a person:** 
+    validations: {required: true}
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: |
+        Observable and checkable. Include the ways this could be built *wrongly* — a silently
+        dropped row, a threshold that stops being declared, an interval that stops matching its
+        point estimate. Those are the criteria that earn their place.
+      value: |
+        - [ ] 
+        - [ ] `./scripts/verify.sh` stays green (10/10)
+    validations: {required: true}
+  - type: textarea
+    id: notes
+    attributes:
+      label: Implementation notes
+      description: Start at which file, what constrains it, what has already gone wrong nearby.
+      value: |
+        **Start at** `src/langchef/`
+    validations: {required: true}
+  - type: textarea
+    id: scope
+    attributes:
+      label: Out of scope
+      description: What this is not. Build order §10 lists things that are never built — check it.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Area labels are collision boundaries. Two agents must not hold the same one.
+      options: [core, judge, workspace, cli, connect, packs, adapters, dogfood, docs, ci]
+    validations: {required: true}

langchef-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+Closes #
+
+## What changed
+
+<!-- One paragraph. What a reviewer needs to know before reading the diff. -->
+
+## Checks
+
+- [ ] `./scripts/verify.sh` — all 10 steps pass locally
+- [ ] Any new statistic has a known-answer test against an independent implementation
+- [ ] Generated files were regenerated, not hand-edited (`docs/*.html`, `docs/AGENT-CONTRACT.md`)
+- [ ] No provider SDK is imported outside `src/langchef/judge/providers.py`
+- [ ] If a rubric-scoring check changed, `VERSION` in `providers.py` was bumped
+- [ ] If this settles a decision, `DECISIONS.md` has a new dated entry
+
+## What I did not do
+
+<!-- Scope left out, and why. An honest gap here is worth more than a tidy diff. -->

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

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: verify (python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      # Both legs always report. A break on one version should not hide the
+      # result on the other, which is the whole reason for testing two.
+      fail-fast: false
+      matrix:
+        # The range pyproject declares: requires-python = ">=3.12,<3.14".
+        # Advertising support for a version nothing runs is a claim, not a fact.
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Every check lives in scripts/verify.sh so that what runs here and what
+      # a person runs locally cannot drift apart. See that file for the list.
+      - name: Verify
+        run: ./scripts/verify.sh
+        env:
+          UV_PYTHON: ${{ matrix.python }}

langchef-0.1.0/.github/workflows/claim.yml

@@ -0,0 +1,97 @@
+# Claiming an issue, done by the repository rather than by the claimant.
+#
+# AGENTS.md used to ask a claimant to comment and then move the issue to
+# `lifecycle:doing`. Outside contributors cannot set labels, so step two was
+# impossible for exactly the people the instruction was written for, and for
+# three hours on 27 August #25 looked free after it had been claimed. Two
+# contributors wrote the same fix.
+#
+# The first version of this workflow matched claim phrasings with a regex. On
+# 28 August @raappo wrote "I'd love to" where the pattern expected "I'd like
+# to", #64 stayed `lifecycle:ready` for thirteen hours with a PR already open
+# against it, and a second contributor duplicated the work overnight. The
+# symptom of a missed phrase is silence, which looks exactly like no claim.
+#
+# So there is no phrase list any more. **Any comment from a person on a
+# `lifecycle:ready` issue claims it.** On a board this specific a comment is
+# almost never anything else, and the asymmetry is decisive: a false positive
+# costs one label and is undone by replying, while a false negative costs
+# somebody a night of duplicated work. The confirmation comment says how to
+# undo it, which is what makes the trade safe.
+
+name: Claim
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+
+jobs:
+  claim:
+    if: ${{ !github.event.issue.pull_request && github.event.comment.user.type != 'Bot' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const issue_number = context.issue.number;
+            const claimant = context.payload.comment.user.login;
+
+            if (claimant === owner) return;          // the maintainer is not claiming
+
+            const labels = context.payload.issue.labels.map((l) => l.name);
+            const ready = labels.includes("lifecycle:ready");
+            const doing = labels.includes("lifecycle:doing");
+            if (!ready && !doing) return;            // spec, blocked or done: not claimable
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number, per_page: 100,
+            });
+
+            // The first person who was not the maintainer or a bot. Under this
+            // rule that comment is the claim, whatever it said.
+            const first = comments.find(
+              (c) =>
+                c.id !== context.payload.comment.id &&
+                c.user.login !== owner &&
+                c.user.type !== "Bot",
+            );
+
+            if (doing && first && first.user.login !== claimant) {
+              await github.rest.issues.createComment({
+                owner, repo, issue_number,
+                body:
+                  `@${claimant} before you spend time on this: ` +
+                  `@${first.user.login} claimed it on ${first.created_at.slice(0, 10)} ` +
+                  `(${first.html_url}).\n\n` +
+                  "Please check with them before continuing, or take something else from " +
+                  "[`lifecycle:ready`](../../issues?q=is%3Aopen+label%3Alifecycle%3Aready). " +
+                  "If they have gone quiet, say so here and a maintainer will reassign it.",
+              });
+              return;
+            }
+
+            if (!ready) return;                      // already doing, and it is theirs
+
+            await github.rest.issues.addLabels({
+              owner, repo, issue_number, labels: ["lifecycle:doing"],
+            });
+            await github.rest.issues
+              .removeLabel({ owner, repo, issue_number, name: "lifecycle:ready" })
+              .catch(() => {});
+            await github.rest.issues.createComment({
+              owner, repo, issue_number,
+              body:
+                `Marked \`lifecycle:doing\` for @${claimant}.\n\n` +
+                "You cannot set labels on a repository you do not have write access to, " +
+                "so the repository does it for you. Branch as " +
+                `\`${issue_number}-short-slug\` and open a PR when ready.\n\n` +
+                "**If you were only asking a question and did not mean to claim this**, " +
+                "say so and a maintainer will move it back to `lifecycle:ready`. " +
+                "We would rather label one question by mistake than let two people " +
+                "write the same patch, which has happened twice here.",
+            });

langchef-0.1.0/.github/workflows/pr-guard.yml

@@ -0,0 +1,119 @@
+# The side door.
+#
+# claim.yml guards the front door: someone comments on an issue, the repository
+# moves the label and says who holds it. PR #59 walked straight past it by
+# opening a pull request without ever commenting, which is a door claim.yml
+# cannot see. By then the work was already written, which is the cost this is
+# meant to avoid.
+#
+# Two checks, both disclosures rather than refusals. Neither fails the build:
+# a maintainer decides, and a bot that blocks a good contribution is worse than
+# one that says something a maintainer can ignore.
+#
+# SECURITY: pull_request_target runs with the base repository's token, which is
+# what makes commenting on a fork PR possible at all. It is only safe because
+# nothing here checks out or executes the pull request's code. Do not add
+# actions/checkout to this file.
+
+name: PR guard
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  pull-requests: write
+  issues: read
+  contents: read
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const pr = context.payload.pull_request;
+            const author = pr.user.login;
+            const number = pr.number;
+            const notes = [];
+
+            // ---- 1. is the issue this closes already held by somebody else?
+            const text = `${pr.title}\n${pr.body || ""}`;
+            const refs = new Set();
+            const KEYWORD =
+              /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implements?|part of)\s+#(\d+)/gi;
+            for (const m of text.matchAll(KEYWORD)) refs.add(Number(m[1]));
+            // A bare #N in the title counts too: #59 said "(#25)" and nothing else.
+            for (const m of (pr.title || "").matchAll(/#(\d+)/g)) refs.add(Number(m[1]));
+
+            const CLAIM = new RegExp(
+              [
+                "starting\\s+(on|work)", "i'?m\\s+starting", "i\\s+am\\s+starting",
+                "i\\s+am\\s+ready\\s+to\\s+start", "claiming\\s+this", "taking\\s+this",
+                "working\\s+on\\s+this", "i'?d\\s+like\\s+to\\s+(work\\s+on|take)",
+                "i\\s+would\\s+like\\s+to\\s+work\\s+on",
+              ].join("|"),
+              "i",
+            );
+
+            for (const n of refs) {
+              if (n === number) continue;
+              let issue;
+              try {
+                issue = (await github.rest.issues.get({owner, repo, issue_number: n})).data;
+              } catch { continue; }
+              if (issue.pull_request) continue;
+
+              const labels = issue.labels.map((l) => (typeof l === "string" ? l : l.name));
+              if (!labels.includes("lifecycle:doing")) continue;
+
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner, repo, issue_number: n, per_page: 100,
+              });
+              const prior = comments.filter(
+                (c) =>
+                  c.user.login !== author &&
+                  c.user.login !== owner &&
+                  c.user.type !== "Bot" &&
+                  CLAIM.test(c.body || ""),
+              );
+              if (!prior.length) continue;
+
+              const first = prior[0];
+              notes.push(
+                `**#${n} is already held.** @${first.user.login} claimed it on ` +
+                  `${first.created_at.slice(0, 10)} (${first.html_url}), and it is labelled ` +
+                  "`lifecycle:doing`.\n\n" +
+                  "This is worth checking before you spend more time on it. Our claim " +
+                  "automation only watches for a comment on the issue, so opening a pull " +
+                  "request directly walks past it, which is our gap rather than yours.",
+              );
+            }
+
+            // ---- 2. does it change behaviour without changing a test?
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner, repo, pull_number: number, per_page: 100,
+            });
+            const paths = files.map((f) => f.filename);
+            const touchesSrc = paths.some((p) => p.startsWith("src/"));
+            const touchesTests = paths.some((p) => p.startsWith("tests/"));
+            if (touchesSrc && !touchesTests) {
+              notes.push(
+                "**This changes `src/` without changing `tests/`.**\n\n" +
+                  "Most issues here list the tests they expect in their acceptance criteria, " +
+                  "and `scripts/verify.sh` runs the suite as step 8. If the change is genuinely " +
+                  "untestable, say so in the description and it will be taken at face value.",
+              );
+            }
+
+            if (!notes.length) return;
+            await github.rest.issues.createComment({
+              owner, repo, issue_number: number,
+              body:
+                notes.join("\n\n---\n\n") +
+                "\n\n<sub>Posted automatically by `pr-guard.yml`. Neither of these fails the " +
+                "build; a maintainer decides.</sub>",
+            });

langchef-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+# Publishing to PyPI, with no credential anywhere in this repository.
+#
+# Trusted Publishing (OIDC): PyPI is configured to trust this exact repository,
+# workflow filename and environment, and GitHub mints a short-lived token per
+# run. There is no API token to create, share, paste into a secret, rotate, or
+# leak. If this file is renamed, or the environment below changes, PyPI stops
+# trusting it and the upload fails closed.
+#
+# The build job runs the same verify.sh that guards every push, on both
+# supported interpreters, before anything is uploaded. A release that skipped
+# the checks would defeat the point of having them.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+jobs:
+  verify:
+    name: verify (python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: ./scripts/verify.sh
+        env:
+          UV_PYTHON: ${{ matrix.python }}
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      # The tag is the source of truth for the version. A tag that disagrees
+      # with pyproject.toml means one of the two is a typo, and guessing which
+      # is how a wrong version reaches PyPI permanently: uploads cannot be
+      # replaced, only yanked.
+      - name: Tag matches pyproject version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          if [ "$tag" != "$pkg" ]; then
+            echo "tag v$tag does not match pyproject version $pkg" >&2
+            exit 1
+          fi
+          echo "v$tag matches pyproject"
+
+      - run: uv build
+
+      # Catches the metadata problems that make a page look broken on PyPI,
+      # before the upload rather than after it.
+      - name: Check the distribution metadata
+        run: uv run --isolated --no-project --with twine twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write          # the whole credential story: a short-lived OIDC token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

langchef-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.DS_Store
+
+# Dogfood artifacts — regenerate with `uv run python -m dogfood.build`.
+dogfood/workspace/
+dogfood/truth/

langchef-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12