Metadata-Version: 2.4
Name: veridist
Version: 1.0.0
Summary: Evidence-first distribution fitting with explicit execution contracts
Author-email: Ali Sadeghi Aghili <alisadeghiaghili@gmail.com>
License-Expression: BUSL-1.1
Project-URL: Homepage, https://github.com/alisadeghiaghili/veridist
Project-URL: Documentation, https://github.com/alisadeghiaghili/veridist/tree/main/python/docs
Project-URL: Repository, https://github.com/alisadeghiaghili/veridist
Project-URL: Issues, https://github.com/alisadeghiaghili/veridist/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Provides-Extra: test
Requires-Dist: coverage[toml]>=7.6; extra == "test"
Requires-Dist: mpmath==1.3.0; extra == "test"
Requires-Dist: PyYAML<7,>=6; extra == "test"
Requires-Dist: pytest>=8.3; extra == "test"
Requires-Dist: pytest-cov<8,>=6; extra == "test"
Provides-Extra: mutation
Requires-Dist: mutmut==3.7.0; extra == "mutation"
Requires-Dist: pytest>=8.3; extra == "mutation"
Provides-Extra: browser
Requires-Dist: playwright==1.62.0; extra == "browser"
Provides-Extra: lint
Requires-Dist: mypy>=1.13; extra == "lint"
Requires-Dist: ruff>=0.8; extra == "lint"
Provides-Extra: docs
Requires-Dist: Sphinx<9,>=8.2; extra == "docs"
Requires-Dist: myst-parser<5,>=4; extra == "docs"
Requires-Dist: sphinx-intl<3,>=2.3; extra == "docs"
Dynamic: license-file

# veridist

[English](https://github.com/alisadeghiaghili/veridist/blob/main/python/README.md) | [فارسی](https://github.com/alisadeghiaghili/veridist/blob/main/python/README.fa.md) | [Deutsch](https://github.com/alisadeghiaghili/veridist/blob/main/python/README.de.md)

## Status

`veridist` 1.0.0 is an evidence-backed public contract release.
It specifies and tests bounded delivery, replayability, pass budgets,
transactional retry, checkpoint compatibility, typed failures, execution
outcomes, and redacted provenance.

This build includes fixed-location Exponential, Weibull-minimum, and Lognormal
MLE cells for exact and independently right-censored lifetimes. They provide
point estimates when finite solutions exist and typed failures otherwise.
The uncensored exponential cell also has refit Monte Carlo KS, AD, and CvM
goodness-of-fit, AIC/BIC, calibration summaries, and adequacy-gated selection.
Inference is restricted to that declared cell and requires a caller-owned NumPy
generator.
Its public CSV path is strict: UTF-8 CSV with exactly `time,event_observed`,
event token `1`, and right-censoring token `0`. It executes one iterator pass
with a declared logical retained-payload chunk budget and returns a closed,
typed execution result. This is not a generic CSV reader or a portable RSS,
throughput, cancellation, retry, checkpoint, or broad out-of-core claim.
Retained evidence establishes bounded internal payload only for the measured
10k/100k/1m by 32KiB/64KiB/128KiB matrix; it does not establish a general
big-data or high-throughput capability.

`IterableDataSource` is the reusable public stream adapter for caller-owned
chunk iterables. Its immutable metadata explicitly declares one-pass or
replayable acquisition: a single-pass source fails with a typed pass-budget
error if acquired twice, while a replayable source requires an iterator
factory. `BoundedChunkBuffer` charges queued and consumer-held chunks until
`BufferedChunk.release()`; callers must release received chunks, normally in
`finally`. The only shipped file adapter remains the strict CSV lifetime
adapter—this does not add generic CSV, Parquet, Arrow, dataframe, database,
or broad out-of-core adapters.

For a sequential pure reducer, `veridist.engine.SQLiteCheckpointStore` provides
durable local checkpoint state with generation-based compare-and-swap and
cross-process SQLite locking. It is limited to one host and a local filesystem;
`fit_exponential_checkpointed_csv` supports explicit source-revision-bound
resume for the strict lifetime CSV path.

The separate scalar surface exposes immutable `FAMILY_REGISTRY` metadata for
normal, gamma, Weibull-minimum, lognormal, and right-Gumbel; scalar
`evaluate_log_density`, CDF, survival, quantile, and caller-owned RNG sampling
operations; and
exact-state `reduce_log_likelihood_chunks`. These operations are scalar and the
fit/inference capability matrix remains narrower than the operation registry.
The reducer represents successful binary64 terms exactly and rounds
the final total once; its unsigned-64 count cap implies a 2162-bit exact-total
bound. Its retained 10k/100k/1m evidence is scoped to tested normal streams.

Candidate scale measurement is deliberately manual: the `veridist-scale-evidence`
workflow first binds a clean, full candidate SHA and runs the evidence contracts,
then measures the public iterable likelihood and strict CSV/exponential paths on
Linux and Windows. It retains artifacts only after their own fail-closed SHA and
schema validation. Merely having this workflow, or a historical artifact, is not
evidence for a new candidate and is not a throughput or RSS claim.

## Install an evaluation build

Install from the nested source project after cloning the repository:

```console
git clone https://github.com/alisadeghiaghili/veridist.git
cd veridist/python
python -m pip install .
```

Or install a wheel that you built or obtained from a specific verified run:

```console
python -m pip install /path/to/veridist-1.0.0-py3-none-any.whl
```

The project does not direct users to install an unreleased package name from a
public index.

## Try the experimental vertical

```python
from pathlib import Path
from tempfile import TemporaryDirectory
from veridist import CsvLifetimeLimits, CsvLifetimeSchema, PublicSourceId, fit_exponential_csv
from veridist.families import ExponentialFitSuccess

with TemporaryDirectory() as directory:
    path = Path(directory) / "lifetimes.csv"
    path.write_text("time,event_observed\n1,1\n1,0\n", encoding="utf-8")
    fit = fit_exponential_csv(
        path, schema=CsvLifetimeSchema("time", "event_observed"),
        source_id=PublicSourceId("src_0123456789abcdef0123456789abcdef"),
        limits=CsvLifetimeLimits(32768, 32768),
    ).fit
assert isinstance(fit, ExponentialFitSuccess)
assert fit.rate == 0.5
assert fit.inference == "not_provided"
assert fit.censoring_assumption == "independent_right_censoring"
```

See the [documentation toolchain](docs/README.md) and the repository's
[evidence ledger](../docs/v1-readiness.md) for implemented checks and explicit
limits.

## License

BUSL-1.1 with an Apache-2.0 additional-use grant for personal,
non-commercial use; see [LICENSE](LICENSE).
