jevlikedecisions 0.1.0__tar.gz

jevlikedecisions-0.1.0/.github/workflows/publish-root-python-package.yml

@@ -0,0 +1,184 @@
+name: Publish root Python package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+env:
+  DISTRIBUTION_DIRECTORY_NAME: distributions
+
+jobs:
+  build-verified-distributions:
+    name: Build and verify tagged distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      PROJECT_METADATA_FILE: ${{ github.workspace }}/pyproject.toml
+      DISTRIBUTION_ARTIFACT_NAME: verified-distributions
+    steps:
+      - name: Initialize the build distribution directory
+        env:
+          RUNNER_TEMP_DIRECTORY: ${{ runner.temp }}
+        run: echo "DISTRIBUTION_DIRECTORY=$RUNNER_TEMP_DIRECTORY/$DISTRIBUTION_DIRECTORY_NAME" >> "$GITHUB_ENV"
+
+      - name: Check out the complete tagged history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Derive the build Python version from project metadata
+        id: build-python
+        shell: bash
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import tomllib
+
+          metadata_path = pathlib.Path(os.environ["PROJECT_METADATA_FILE"])
+          requires_python = tomllib.loads(metadata_path.read_text())["project"]["requires-python"]
+          lower_bounds = [
+              bound.strip().removeprefix(">=")
+              for bound in requires_python.split(",")
+              if bound.strip().startswith(">=")
+          ]
+          if not lower_bounds:
+              raise SystemExit(
+                  "::error title=Python floor derivation failed::"
+                  "project.requires-python has no inclusive lower bound"
+              )
+          declared_floor_minor = max(lower_bounds, key=lambda value: tuple(map(int, value.split("."))))
+          with pathlib.Path(os.environ["GITHUB_OUTPUT"]).open("a") as output_file:
+              output_file.write(f"version={declared_floor_minor}\n")
+          PY
+
+      - name: Set up the metadata-declared build Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ steps.build-python.outputs.version }}
+
+      - name: Install distribution tooling
+        run: python -m pip install build packaging twine
+
+      - name: Build the source and wheel distributions once
+        run: python -m build --outdir "$DISTRIBUTION_DIRECTORY"
+
+      - name: Assert artifact versions match the triggering tag
+        env:
+          TRIGGERING_TAG: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          python - <<'PY'
+          import email
+          import glob
+          import os
+          import pathlib
+          import tarfile
+          import zipfile
+
+          from packaging.version import InvalidVersion, Version
+
+          distribution_directory = pathlib.Path(os.environ["DISTRIBUTION_DIRECTORY"])
+          wheel_paths = [pathlib.Path(path) for path in glob.glob(str(distribution_directory / "*.whl"))]
+          sdist_paths = [pathlib.Path(path) for path in glob.glob(str(distribution_directory / "*.tar.gz"))]
+          if len(wheel_paths) != 1 or len(sdist_paths) != 1:
+              raise SystemExit(
+                  "::error title=Distribution set invalid::"
+                  f"expected one wheel and one sdist, found {len(wheel_paths)} wheel(s) "
+                  f"and {len(sdist_paths)} sdist(s)"
+              )
+
+          with zipfile.ZipFile(wheel_paths[0]) as wheel_archive:
+              wheel_metadata_names = [
+                  name for name in wheel_archive.namelist() if name.endswith(".dist-info/METADATA")
+              ]
+              if len(wheel_metadata_names) != 1:
+                  raise SystemExit(
+                      "::error title=Wheel metadata invalid::"
+                      f"expected one METADATA file, found {len(wheel_metadata_names)}"
+                  )
+              wheel_metadata = email.message_from_bytes(wheel_archive.read(wheel_metadata_names[0]))
+
+          with tarfile.open(sdist_paths[0], mode="r:gz") as sdist_archive:
+              sdist_metadata_members = [
+                  member
+                  for member in sdist_archive.getmembers()
+                  if pathlib.PurePosixPath(member.name).name == "PKG-INFO"
+                  and len(pathlib.PurePosixPath(member.name).parts) == 2
+              ]
+              if len(sdist_metadata_members) != 1:
+                  raise SystemExit(
+                      "::error title=Source distribution metadata invalid::"
+                      f"expected one root package PKG-INFO file, found {len(sdist_metadata_members)}"
+                  )
+              extracted_metadata = sdist_archive.extractfile(sdist_metadata_members[0])
+              if extracted_metadata is None:
+                  raise SystemExit(
+                      "::error title=Source distribution metadata unreadable::"
+                      "could not read PKG-INFO"
+                  )
+              sdist_metadata = email.message_from_binary_file(extracted_metadata)
+
+          tag_name = os.environ["TRIGGERING_TAG"]
+          if not tag_name.startswith("v") or len(tag_name) == 1:
+              raise SystemExit(
+                  "::error title=Triggering tag invalid::"
+                  f"expected a v-prefixed version tag, received {tag_name!r}"
+              )
+          try:
+              expected_version = Version(tag_name.removeprefix("v"))
+              wheel_version = Version(wheel_metadata["Version"])
+              sdist_version = Version(sdist_metadata["Version"])
+          except (InvalidVersion, TypeError) as version_error:
+              raise SystemExit(
+                  "::error title=Distribution version unreadable::"
+                  f"could not parse the tag or artifact version: {version_error}"
+              ) from version_error
+
+          if wheel_version != expected_version or sdist_version != expected_version:
+              raise SystemExit(
+                  "::error title=Distribution version mismatch::"
+                  f"tag expects {expected_version}; wheel contains {wheel_version}; "
+                  f"source distribution contains {sdist_version}"
+              )
+          PY
+
+      - name: Validate both distributions with Twine
+        run: python -m twine check "$DISTRIBUTION_DIRECTORY"/*
+
+      - name: Upload the verified distribution bytes
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.DISTRIBUTION_ARTIFACT_NAME }}
+          path: ${{ env.DISTRIBUTION_DIRECTORY }}
+          if-no-files-found: error
+
+  publish-verified-distributions-to-pypi:
+    name: Publish verified distributions to PyPI
+    needs: build-verified-distributions
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      DISTRIBUTION_ARTIFACT_NAME: verified-distributions
+    steps:
+      - name: Initialize the PyPI distribution directory
+        env:
+          RUNNER_TEMP_DIRECTORY: ${{ runner.temp }}
+        run: echo "DISTRIBUTION_DIRECTORY=$RUNNER_TEMP_DIRECTORY/$DISTRIBUTION_DIRECTORY_NAME" >> "$GITHUB_ENV"
+
+      - name: Download the verified distribution bytes
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ env.DISTRIBUTION_ARTIFACT_NAME }}
+          path: ${{ env.DISTRIBUTION_DIRECTORY }}
+
+      - name: Publish verified distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: ${{ env.DISTRIBUTION_DIRECTORY }}

jevlikedecisions-0.1.0/.github/workflows/test-root-python-package.yml

@@ -0,0 +1,288 @@
+name: Test root Python package
+
+on:
+  # PR commits run via pull_request; scope pushes to main to avoid duplicate runs.
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-github-actions-workflows:
+    name: Lint every GitHub Actions workflow
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out workflow files
+        uses: actions/checkout@v4
+
+      - name: Validate every workflow and expression context
+        uses: raven-actions/actionlint@v2
+        with:
+          version: 1.7.7
+
+  derive-python-test-matrix:
+    name: Derive Python test versions from package metadata
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.python-test-matrix.outputs.matrix }}
+    steps:
+      - name: Check out package metadata
+        uses: actions/checkout@v4
+
+      - name: Derive every supported stable Python minor from package metadata
+        id: python-test-matrix
+        env:
+          PROJECT_METADATA_FILE: ./pyproject.toml
+          # setup-python resolves releases from this maintained manifest; using the
+          # same source keeps the matrix aligned with versions the action can install.
+          PYTHON_VERSIONS_MANIFEST_URL: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json
+        shell: python
+        run: |
+          import json
+          import os
+          import pathlib
+          import re
+          import tomllib
+          import urllib.error
+          import urllib.request
+
+          VERSION_PATTERN = re.compile(r"^\d+(?:\.\d+)+$")
+          SPECIFIER_PATTERN = re.compile(r"^(>=|<=|<)\s*(\d+(?:\.\d+)+)$")
+          BOUND_PATTERN = re.compile(
+              r"(?:^|,)\s*(>=|<=|<)\s*(\d+(?:\.\d+)+)\s*(?=,|$)"
+          )
+
+          def version_tuple(version_text):
+              return tuple(int(part) for part in version_text.split("."))
+
+          def padded_version(version, width):
+              return version + (0,) * (width - len(version))
+
+          def version_satisfies_bound(version, operator, bound):
+              width = max(len(version), len(bound))
+              comparable_version = padded_version(version, width)
+              comparable_bound = padded_version(bound, width)
+              if operator == ">=":
+                  return comparable_version >= comparable_bound
+              if operator == "<":
+                  return comparable_version < comparable_bound
+              return comparable_version <= comparable_bound
+
+          metadata_path = pathlib.Path(os.environ["PROJECT_METADATA_FILE"])
+          with metadata_path.open("rb") as metadata_file:
+              metadata = tomllib.load(metadata_file)
+
+          requires_python = metadata["project"].get("requires-python", "")
+          specifiers = [specifier.strip() for specifier in requires_python.split(",")]
+          if not specifiers or any(
+              not SPECIFIER_PATTERN.fullmatch(specifier) for specifier in specifiers
+          ):
+              raise SystemExit(
+                  "UNSUPPORTED_REQUIRES_PYTHON_SPECIFIER: "
+                  "expected only >=, <, or <= version bounds"
+              )
+          bounds = [
+              (operator, version_tuple(version_text))
+              for operator, version_text in BOUND_PATTERN.findall(requires_python)
+          ]
+          lower_bounds = [bound for operator, bound in bounds if operator == ">="]
+          if not lower_bounds:
+              raise SystemExit(
+                  "MISSING_INCLUSIVE_PYTHON_LOWER_BOUND: "
+                  "project.requires-python must contain an inclusive >= lower bound"
+              )
+
+          manifest_url = os.environ["PYTHON_VERSIONS_MANIFEST_URL"]
+          try:
+              with urllib.request.urlopen(manifest_url) as manifest_response:
+                  manifest = json.load(manifest_response)
+          except (OSError, urllib.error.URLError, json.JSONDecodeError) as error:
+              raise SystemExit(f"PYTHON_VERSION_DISCOVERY_FAILED: {error}") from error
+
+          if not isinstance(manifest, list):
+              raise SystemExit(
+                  "PYTHON_VERSION_MANIFEST_SHAPE_CHANGED: expected a JSON list"
+              )
+
+          stable_versions = []
+          for release in manifest:
+              if not isinstance(release, dict) or "version" not in release or "stable" not in release:
+                  raise SystemExit(
+                      "PYTHON_VERSION_MANIFEST_SHAPE_CHANGED: "
+                      "each release must contain version and stable fields"
+                  )
+              version_text = release["version"]
+              if release["stable"] is True and VERSION_PATTERN.fullmatch(version_text):
+                  stable_versions.append(version_tuple(version_text))
+
+          if not stable_versions:
+              raise SystemExit(
+                  "EMPTY_STABLE_PYTHON_VERSION_DISCOVERY: "
+                  "the versions manifest contained no stable releases"
+              )
+
+          supported_minors = sorted(
+              {
+                  release[:2]
+                  for release in stable_versions
+                  if all(
+                      version_satisfies_bound(release, operator, bound)
+                      for operator, bound in bounds
+                  )
+              }
+          )
+          if not supported_minors:
+              raise SystemExit(
+                  "EMPTY_SUPPORTED_PYTHON_MINOR_RANGE: "
+                  "no discovered stable release satisfies project.requires-python"
+              )
+
+          declared_floor_minor = max(lower_bounds)[:2]
+          latest_stable_minor = max(stable_versions)[:2]
+          matrix_entries = []
+          for supported_minor in supported_minors:
+              if supported_minor == declared_floor_minor:
+                  version_source = "declared-floor"
+              elif supported_minor == latest_stable_minor:
+                  version_source = "latest-stable"
+              else:
+                  version_source = "intermediate-supported-minor"
+              matrix_entries.append(
+                  {
+                      "python-version": ".".join(map(str, supported_minor)),
+                      "version-source": version_source,
+                  }
+              )
+
+          matrix = {"include": matrix_entries}
+          matrix_json = json.dumps(matrix, separators=(",", ":"))
+          print(matrix_json)
+          github_output = os.environ.get("GITHUB_OUTPUT")
+          if github_output:
+              with pathlib.Path(github_output).open("a") as output_file:
+                  print(f"matrix={matrix_json}", file=output_file)
+
+  test-root-python-package:
+    name: Test root package on Python ${{ matrix.python-version }} (${{ matrix.version-source }})
+    needs: derive-python-test-matrix
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.derive-python-test-matrix.outputs.matrix) }}
+    steps:
+      - name: Check out root package for Python ${{ matrix.python-version }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install root package with dev dependencies on Python ${{ matrix.python-version }}
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run whole test suite on Python ${{ matrix.python-version }}
+        run: python -m pytest tests -q
+
+  prove-built-distributions:
+    name: Prove built distributions on Python ${{ matrix.python-version }}
+    needs: derive-python-test-matrix
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.derive-python-test-matrix.outputs.matrix) }}
+    steps:
+      - name: Check out complete version history for distribution metadata
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up derived Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install distribution proof tools
+        run: python -m pip install build twine
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Assert packaged configuration is in wheel and source distribution
+        run: |
+          python - <<'PY'
+          import pathlib
+          import tarfile
+          import zipfile
+
+          distribution_directory = pathlib.Path("dist")
+          wheel_paths = tuple(distribution_directory.glob("*.whl"))
+          source_distribution_paths = tuple(distribution_directory.glob("*.tar.gz"))
+          expected_resource_suffix = "jevlikedecisions/config/jevlikedecisions.json"
+
+          if len(wheel_paths) != 1:
+              raise AssertionError(f"WHEEL_ARTIFACT_COUNT_ERROR: found {len(wheel_paths)} wheels")
+          if len(source_distribution_paths) != 1:
+              raise AssertionError(
+                  "SOURCE_DISTRIBUTION_ARTIFACT_COUNT_ERROR: "
+                  f"found {len(source_distribution_paths)} source distributions"
+              )
+
+          with zipfile.ZipFile(wheel_paths[0]) as wheel_archive:
+              wheel_members = wheel_archive.namelist()
+          if expected_resource_suffix not in wheel_members:
+              raise AssertionError(
+                  f"WHEEL_CONFIG_RESOURCE_MISSING: {expected_resource_suffix}"
+              )
+
+          with tarfile.open(source_distribution_paths[0], mode="r:gz") as source_archive:
+              source_distribution_members = source_archive.getnames()
+          if not any(
+              member.endswith(f"/{expected_resource_suffix}")
+              for member in source_distribution_members
+          ):
+              raise AssertionError(
+                  f"SOURCE_DISTRIBUTION_CONFIG_RESOURCE_MISSING: {expected_resource_suffix}"
+              )
+          PY
+
+      - name: Validate wheel and source distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Prove installed wheel loads its packaged configuration off source tree
+        working-directory: ${{ runner.temp }}
+        env:
+          INSTALLED_WHEEL_PROOF_VENV: ${{ runner.temp }}/jevlikedecisions-installed-wheel-proof
+        run: |
+          python -m venv "$INSTALLED_WHEEL_PROOF_VENV"
+          "$INSTALLED_WHEEL_PROOF_VENV/bin/python" -m pip install "$GITHUB_WORKSPACE"/dist/*.whl
+          "$INSTALLED_WHEEL_PROOF_VENV/bin/python" - <<'PY'
+          import pathlib
+          import os
+          from importlib.resources import files
+
+          import jevlikedecisions
+          from jevlikedecisions.configuration import load_decision_configuration
+
+          repository_root = pathlib.Path(os.environ["GITHUB_WORKSPACE"]).resolve()
+          installed_module_path = pathlib.Path(jevlikedecisions.__file__).resolve()
+          installed_package_resource = files("jevlikedecisions")
+          installed_config_resource = installed_package_resource.joinpath(
+              "config/jevlikedecisions.json"
+          )
+
+          if installed_module_path.is_relative_to(repository_root):
+              raise AssertionError(
+                  f"SOURCE_TREE_IMPORT_FALLBACK_ERROR: imported {installed_module_path}"
+              )
+          if not installed_config_resource.is_file():
+              raise AssertionError(
+                  f"INSTALLED_CONFIG_RESOURCE_MISSING: {installed_config_resource}"
+              )
+          installed_configuration = load_decision_configuration()
+          if not isinstance(installed_configuration, dict) or not installed_configuration:
+              raise AssertionError("INSTALLED_CONFIG_LOAD_ERROR: loader returned no configuration")
+          PY

jevlikedecisions-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+.pytest_cache/
+.coverage
+.mypy_cache/
+.ruff_cache/
+
+.venv.nosync/
+.venv/
+venv/

jevlikedecisions-0.1.0/DESIGN_PORTS_AND_ADAPTERS.md

@@ -0,0 +1,9 @@
+# Ports-and-adapters design
+
+The core validates canonical questions, selects an adapter by configured name, estimates through spendguard pricing, and validates canonical answers. It contains no provider endpoint, model, key, or price.
+
+`DecisionBackendPort` is structural. Each adapter alone owns its wire envelope and declares its supported question types. An unforeseen adapter is registered in the internal registry and enters the identical orchestration without editing the core or another adapter. An unsupported question type raises a typed refusal; there is no fallback.
+
+Paid transports implement the runtime-checked `MeteredDecisionTransportPort`. The port returns provider data together with usage, ledger id, cost-completeness state, and the known input-cost floor. The default transport requires the active spendguard gate, uses the provider key named by config, records actual response usage through spendguard, and withholds a completely settled result unless a ledger id is returned. Tests may inject a conforming transport fixture; this dispatch deliberately made no live call and spent zero dollars.
+
+Named gap: `anyjev` has no separately verified schema in the fetched evidence, so v1 does not invent an adapter.

jevlikedecisions-0.1.0/LICENSE

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

jevlikedecisions-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md DESIGN_PORTS_AND_ADAPTERS.md
+recursive-include src/jevlikedecisions/config *.json
+recursive-include tests/fixtures *.json
+

jevlikedecisions-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: jevlikedecisions
+Version: 0.1.0
+Summary: One typed decision abstraction over jev-like decision-model providers.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: llm-spendguard>=0.16.30
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Dynamic: license-file
+
+# jevlikedecisions
+
+`jevlikedecisions.decide(...)` is one typed decision entrypoint over a family of provider adapters. Shared evidence is sent once, in full, and responses are checked against both the provider shape and the originating questions. Backend selection is mandatory: no call silently falls back to the deterministic `mock_jevlike` backend.
+
+## Installation and spend-gate setup
+
+Python 3.11 or newer is required.
+
+Install the package and its sole runtime dependency, `llm-spendguard`, with pip:
+
+```console
+python -m pip install jevlikedecisions
+```
+
+> **Pending first release:** The package is not yet published on PyPI. Until the first release is published, clone this repository, change into the clone, and run `python -m pip install .`. Delete this note when publishing the first release.
+
+Before making a model call, arm the spend gate in the virtual environment. This is required: `jevlikedecisions` deliberately refuses to call a model from an interpreter where spendguard is not enforcing. With the target virtual environment activated, run:
+
+```console
+spendguard install-hook --venv "$VIRTUAL_ENV" --no-pkg
+```
+
+> **Temporary upstream workaround:** `--no-pkg` avoids a `FileNotFoundError` for pip-installed, non-editable `llm-spendguard` environments where `install-hook` otherwise looks for a repository `pyproject.toml`. Remove this flag and note after that upstream defect is fixed.
+
+Verify the activated interpreter:
+
+```console
+spendguard doctor
+```
+
+The successful verdict line is `ENFORCING HERE: 🟢 YES — calls from this interpreter are gated`.
+
+> **Temporary upstream workaround:** `spendguard doctor` may currently exit non-zero after printing that successful verdict, with `ValueError: Pricing returned no token cost`. Read the verdict line rather than the exit code; remove this note after that upstream defect is fixed.
+
+If gate setup is skipped, `decide()` refuses model calls through `require_enforcing_spendguard`.
+
+## Request and question schema
+
+Every surface accepts the same JSON object:
+
+```json
+{
+  "input_parts": ["complete evidence"],
+  "questions": [{"name": "safe", "type": "predicate", "description": "Is it safe?"}],
+  "backend": "mock_jevlike",
+  "intent": "documented-example",
+  "prompt_cache_key": null
+}
+```
+
+`intent` and `backend` are required. Every decision result identifies `backend`, `provider`, `model`, `route`, `via`, `ledger_id`, `usage`, `cost_complete`, and `known_input_cost_floor_usd`. Inspect `route` to distinguish in-process and metered results. `cost_complete` says whether the cost is fully settled; when a provider omits output-token usage, a metered result has `cost_complete: false`, no ledger id, and only the known input-cost floor. In-process results are settled at zero cost. Every question has `name`, `type`, and `description`. `type` is `predicate`, `choice`, or `score`. A choice also has `choices`, whose entries contain `value` and `description`. A score also has `levels`, whose entries contain `label` and `description`. Library validation is authoritative for every surface.
+
+Backend names and aliases come from the package configuration. An alias is accepted only at selection; estimates, approvals, receipts, audit evidence, and returned provenance always use the canonical backend name. Omitting `backend` never selects a default and produces a typed `DecisionUnavailable` refusal.
+
+| Canonical backend | Accepted aliases | Provider | Model | Usability and precondition |
+|---|---|---|---|---|
+| `openai_decisions` | `openai` | `openai` | `gpt-6-luna` | Usable only with `OPENAI_API_KEY`, an enforcing spendguard interpreter, and a matching estimate approval. The sole proven call is ledger `2bed00b5f31d4858`: 319 input tokens costing `$3.19e-05`; its output side is unproven. |
+| `typesafe_jev` | `jev` | `typesafe` | `jev-1.14.0` | Usable only with `TYPESAFE_API_KEY`, an enforcing spendguard interpreter, and a matching estimate approval. Input costs `$0.042` per 1M tokens and output is free, as documented at `docs.typesafe.ai/models`; the wire schema is documented at `docs.typesafe.ai/api/system-one`. No live TypeSafe call has yet been proven. |
+| `mock_jevlike` | none | `mock` | `deterministic` | Usable in-process and never selected implicitly. Predicate probability is exactly `0.5`; choice selects the first option with probability/confidence `1.0` and all others `0.0`; score selects the first level with score `0.0`, probability/confidence `1.0`, and all other levels `0.0`; reported input/output tokens are both `0`. |
+
+## Estimate, approve, then spend
+
+The shipped configuration contains exactly three backends: metered `typesafe_jev` and `openai_decisions`, plus the in-process `mock_jevlike` test double. Their only transport kinds are `http` and `in_process`. A backend that declares the removed `subscription` transport is refused when configuration loads; subscription-lane LLM access belongs in llm-spendguard.
+
+Choice questions may declare `"calibrated_choice_distribution": "required"` or `"calibrated_choice_distribution": "omitted"`. Omitting the declaration preserves the current `required` contract: `choice`, `probabilities` for every declared choice in order, and `confidence`. Declaring `omitted` explicitly requests only `name`, `type`, and `choice`; returning either `probabilities` or `confidence` is a named nonconformance, even if null. Unknown or malformed declarations are refused with the permitted values from the packaged `choice_distribution_contract` configuration beside `limits`. Mixed declarations in one call are supported. The shared validator enforces the declared answer fields across Python, CLI, HTTP, and MCP. Score questions are unchanged.
+
+Self-reported confidence is **not calibrated**. In the measured eight-question probe with twenty declared choices per question, gpt-6-luna returned top probability/confidence `1.0` on every item (entropy approximately zero; effective support `1.00`), while glm-5.3 returned top probability/confidence `0.99` on every item (entropy `0.0629`; effective support `1.06`). Those degenerate vectors do not establish calibrated uncertainty. At the working shape of 32 questions × 29 choices, the measured output grew from 2,149 to 23,270 tokens. The declaration allows callers to omit that unvalidated distribution rather than pay for it. The field describes the requested distribution contract; it does not certify calibration when required.
+
+Paid decisions fail closed. First call `decide(..., estimate_only=True)`: it counts the complete provider request, prices it through `spendguard.pricing`, spends `$0`, and persists a matching approval. Only a later identical `decide(...)` may reach the gated metered transport. Provider usage remains authoritative for the real receipt. Configure approval storage with `JEVLIKEDECISIONS_APPROVAL_DIR`, approval signing with `JEVLIKEDECISIONS_APPROVAL_INTEGRITY_KEY`, receipt storage with `JEVLIKEDECISIONS_RECEIPT_DIR`, and an alternate package configuration with `JEVLIKEDECISIONS_CONFIG`. Credentials are read only from the environment variable named by the selected backend configuration.
+
+## Python, CLI, HTTP, and MCP
+
+Python:
+
+```python
+from jevlikedecisions import decide
+
+estimate = decide(input_parts, questions, backend=backend, intent=intent, estimate_only=True)
+result = decide(input_parts, questions, backend=backend, intent=intent)
+```
+
+CLI input comes from a JSON file or stdin. `estimate` prints the estimate and its `approval_path`; `decide` prints answers and receipt fields. The `backend` value accepts either a canonical name or an alias reported by `backends`.
+
+```console
+jevlikedecisions backends
+jevlikedecisions estimate --backend "$JEVLIKEDECISIONS_BACKEND" request.json
+jevlikedecisions decide --backend "$JEVLIKEDECISIONS_BACKEND" request.json
+```
+
+The CLI flag fills a missing request `backend`; if both the flag and JSON field are present they must agree or the command fails. CLI exit codes follow `sysexits`: `0` (`EX_OK`) for success, `64` (`EX_USAGE`) for malformed input, `65` (`EX_DATAERR`) for a typed decision refusal, and `70` (`EX_SOFTWARE`) for an internal fault. The CLI reports every failure as `TypeName: message` on stderr; catching internal faults gives automation a stable code without hiding the fault.
+
+The standard-library HTTP server exposes `POST /backends`, `POST /estimate`, and `POST /decide`; its `backend` field accepts the same config-derived canonical names and aliases. HTTP `400` identifies a malformed request, `422` identifies a typed decision refusal, `503` specifically identifies `DecisionUnavailable`, and `500` identifies an internal fault. Keeping unavailable decisions at `503` preserves the established retry signal, while the JSON `error` field retains the exact typed refusal. Set `JEVLIKEDECISIONS_HTTP_PORT`; optionally set `JEVLIKEDECISIONS_HTTP_HOST`. With no `JEVLIKEDECISIONS_OPERATOR_TOKEN` it binds only to loopback. When that token is set, callers must send it as an operator bearer token. A paid caller must successfully call `/estimate` before `/decide` with the identical request.
+
+```console
+jevlikedecisions-http --host "$JEVLIKEDECISIONS_HTTP_HOST" --port "$JEVLIKEDECISIONS_HTTP_PORT"
+```
+
+The package's sole runtime dependency is `llm-spendguard`; its MCP surface is a standard-library JSON-RPC stdio server. The `list_decision_backends`, `estimate_decision`, and `make_decision` tools expose the same selection contract and send evidence whole. Enumeration is derived from configuration and reports canonical name, aliases, provider, model, usability, and every missing precondition; both decision tools accept exactly those canonical names and aliases. The approval from the estimate tool must exist before a paid call through the decision tool.
+
+```console
+jevlikedecisions-mcp
+```
+
+## Paid live-proof utility
+
+`scripts/run_paid_decision_live_proof.py` preserves the reproducible paid-call proof harness in the repository. It takes a configuration path rather than embedding one; `examples/paid_decision_live_proof.example.json` shows the input shape. By default it estimates every configured backend, prints the per-backend and total token/USD estimates, and exits without making a paid call. After reviewing that complete estimate, rerun with the explicit `--authorize-paid-calls` flag to execute every configured proof. Its records include reported-output-token status, cost completeness, and the known input-cost floor alongside the ledger and receipt evidence.
+
+```console
+PYTHONPATH=src python scripts/run_paid_decision_live_proof.py examples/paid_decision_live_proof.example.json
+PYTHONPATH=src python scripts/run_paid_decision_live_proof.py examples/paid_decision_live_proof.example.json --authorize-paid-calls
+```
+
+`assert_all_decisions_via_jevlikedecisions(...)` cross-checks package-owned receipts against spendguard rows by `ledger_id` and fails closed when there are no auditable receipts. Spendguard's calls table has no endpoint, route, or via columns, so this proves receipt-backed package calls; it cannot prove that no outside caller contacted a Decisions endpoint.
+
+## Troubleshooting
+
+A framework Python without a usable certificate bundle may need `SSL_CERT_FILE` set to the path of an installed CA bundle, such as the one supplied by certifi, before a real HTTPS call. Never put keys or secret values in configuration or examples.
+
+`anyjev` remains a named v1 schema gap: its authoritative independent wire contract was unavailable, so no fields were invented. It can be added as another adapter without changing `decide()`.
+## General LLM generation
+
+This package wraps the jev and OpenAI Decisions APIs only. General text generation was removed; use `llm-spendguard` for general LLM calls.