Skip to main content

Counterdex

Check a parameter claim against measurements, find a competing explanation, and compare what to measure next. Counterdex is a Python library and command-line tool for bounded scientific investigation with portable, freshly replayable evidence. It uses only the Python standard library and makes no network or model provider calls.

Version 0.3.0 supports one model:

C(t) = A · (exp(−ke · t) − exp(−ka · t))
A > 0,  0 < ke < ka

Time is in hours, concentration in mg/L, and rates in inverse hours. The admitted initial conditions are x(0)=1 and c(0)=0. Exact scientific execution and replay are qualified on CPython 3.11.

What Counterdex does

  • Discover competing candidates. Search a bounded rate grid with amplitude screening, then independently check retained exact parameter vectors against every included measurement and its declared hard allowance. A compatible vector strictly outside a closed claimed interval is a counterexample; either endpoint is inside the claim.
  • Compare a selected pair. Evaluate researcher-supplied feasible measurement times and a declared future allowance. Numerical guidance stays numerical. Checked separation requires two freshly compatible candidates and a strictly positive exact separation margin. Touching bands do not separate.
  • Review a new reading. Recheck the original candidates using an appended actual, transcribed or hypothetical observation at its own declared time and allowance. Preserve the parent evidence and candidate vectors rather than silently searching for replacements.
  • Replay evidence independently of the application. Check native bytes, complete lineage and exact input bindings against separately supplied expected identities, then recompute the scientific checks with the matching prepared package.

No counterexample found means inconclusive, never “claim proved.” Excluding one or both selected candidates does not exclude every other model. A successful replay confirms the recorded calculation under its declared scope; it does not upgrade an inconclusive result or establish the truth of the physical model.

Install

Create a CPython 3.11 environment:

python3.11 -m venv .counterdex-env
.counterdex-env/bin/python -m pip install --no-deps "counterdex==0.3.0"
.counterdex-env/bin/python -m counterdex capabilities

The distribution, Python import and console command are all named counterdex. The package has no runtime dependencies. Build and publication tools are separate development dependencies. Python 3.12/3.13 applications should invoke a separately prepared CPython 3.11 scientific process rather than relax the package's Python requirement.

Try a complete native replay

This example uses synthetic measurements, a retained counterexample and its separately stored anchors. Download the two public fixture files into a new folder; the replay itself is offline and requires no repository checkout:

mkdir counterdex-demo
cd counterdex-demo
curl --fail --location --output hero-baseline.native.json \
  https://raw.githubusercontent.com/Arnav-M10/DrBean-hp26/b60e9d997cdc262e50107953bafc422398435297/packages/groundwork_adapter/fixtures/repro/hero-baseline.native.json
curl --fail --location --output hero-baseline.anchors.json \
  https://raw.githubusercontent.com/Arnav-M10/DrBean-hp26/b60e9d997cdc262e50107953bafc422398435297/packages/groundwork_adapter/fixtures/repro/hero-baseline.anchors.json
../.counterdex-env/bin/python -I -m counterdex replay-native \
  hero-baseline.native.json --anchors hero-baseline.anchors.json

For this fixture the result has verification: "valid", expected_binding: "matches", replay: "passed", and scientific outcome "certified_counterexample". It checks two compatible exact vectors, including one strictly outside the reviewed closed claim. It is synthetic evidence, not an acquired experiment or an application approval.

For real work, obtain expected anchors through the reviewer's trusted channel. Replacing both an artifact and its anchors does not prove authorship or honest data collection. Old evidence needs its matching prepared source; Counterdex never installs or imports a version chosen by an evidence packet.

Python API

After downloading the two files above, the same fresh replay is available from Python:

../.counterdex-env/bin/python -I - <<'PY'
import json
from pathlib import Path
from counterdex import replay_packet

result = replay_packet(
    Path("hero-baseline.native.json").read_bytes(),
    expected=json.loads(Path("hero-baseline.anchors.json").read_text()),
)
print({key: result[key] for key in ("verification", "expected_binding", "replay")})
print(result["outcome"]["scientific_outcome"])
PY

The public API also exposes:

Entry point Purpose
normalize_problem, normalize_design, normalize_times Validate exact scientific projections without changing their reviewed meaning.
create_baseline Discover and check candidates for a reviewed historical problem.
replay_baseline Recompute historical compatibility and outside-claim checks.
create_suggestion Compare a frozen pair under the reviewed design scope.
replay_bundle Replay a standalone pair-design bundle.
replay_packet Replay an application-bound native packet and its required lineage.
capabilities Report supported operations and runtime qualification; this is not a verdict on supplied data.
ExecutionContext, AdapterError Provide cooperative execution limits and typed failures.

See the scientific input contract for complete input shapes and identities. Scientific scalar inputs use exact rational strings, not JSON floating-point numbers. Row order, excluded rows, notes and provenance participate in the problem identity. Candidate vectors, feasible times, allowance provenance, policies and limits participate in the design identity.

Command line and application integration

.counterdex-env/bin/python -m counterdex --help

Run the command above from the directory where the environment was created. Commands include capabilities, baseline, replay-baseline, run, replay, bridge, and replay-native; each command has --help. Evidence-producing CLI commands require an explicit output path and refuse to overwrite an existing file.

The bounded JSON subprocess bridge offers handshake, admission, investigate, design, review, recheck, and replay operations. In particular, recheck binds a separately reviewed observation proposal and its revised inputs to the original baseline or design packet. Read the bridge contract and exact application mapping for request schemas, approved limits, lineage and the POSIX parent-supervision example. Those technical documents retain dated integration notes; the library scope and release information on this page describe this distribution.

Counterdex checks mathematics and scope bindings. The calling application owns authentication, human review, approval, durable storage, provider consent and hard process supervision. Workflow IDs alone confer no authority. A new measurement design or changed assumptions need fresh application review and approval. Native bytes and the accepted report should be published together after checking their exact bindings.

The Dr. Bean application coordinates this workflow using its own backend and Deep Agents integration. They are separate from the Counterdex distribution; installing this library does not start a server, configure an AI provider or supply a browser verifier.

Scientific limits

This release does not establish global identifiability, search completeness, physical truth, model adequacy, instrument precision, a global design optimum, or a confidence interval. Hard allowances are reviewed bounds, not automatically inferred statistical uncertainties. The exact checker uses a fixed rational exponential-enclosure rule for the admitted analytic template. An unresolved enclosure is not evidence of incompatibility.

Generic ODE families, interventions, resets, shared offsets, correlated errors and nonlinear observables are unsupported. Native replay is qualified on CPython 3.11; in-browser mathematical replay is not qualified. Pair separation concerns only the two named candidates and approved feasible times. Numerical scores cannot be promoted to checked guarantees.

The public package preserves existing schema identifiers, hash domains and proof/selection-policy identifiers as compatibility data. Archived evidence retains its original bytes and source requirements.

Documentation and source

The source distribution includes tests, technical documentation, synthetic fixtures and the parent-supervision example. The wheel supplies the scientific runtime. The repository package directory is packages/groundwork_adapter/.

Metadata

Release files for counterdex 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for counterdex 0.3.0
File Size Uploaded Provenance Actions
counterdex-0.3.0.tar.gz 2.4 MB Without provenance Details for counterdex-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for counterdex 0.3.0
File Interpreter ABI Platform Actions
counterdex-0.3.0-py3-none-any.whl Python 3 none any Details for counterdex-0.3.0-py3-none-any.whl

Total release size: 2.5 MB

Release files / counterdex-0.3.0.tar.gz

Download URL counterdex-0.3.0.tar.gz
Size 2.4 MB
Tags Source
SHA-256 checksum
How to use checksums
92f6d2b6bbd5e8233da1915c74128326a6d1a5ae26cc893bec74671cd9f76c59
BLAKE2b-256 checksum
How to use checksums
89939f2f07cefe04a3b9411c917f51b1c91a509fd967291ceb10b8f18b54c572
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / counterdex-0.3.0-py3-none-any.whl

Download URL counterdex-0.3.0-py3-none-any.whl
Size 73.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5201a0a3401b611ff69aaf69feb380ff6ca554d7b3f97db3a4501bf0e1b46193
BLAKE2b-256 checksum
How to use checksums
c3343e1163d31f1347ad57ff22bbd7aed7f0da3ff86340deba7d97aa96f19071
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for counterdex 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page