Skip to content

docs: shorter README, new benchmark charts, MIT OR Apache-2.0 license - #43

Merged
Zikithezikit merged 7 commits into
dev-v2from
docs-readme-benchmarks
Oct 31, 2026
Merged

Zikithezikit merged 7 commits into
dev-v2from
docs-readme-benchmarks

Conversation

@Zikithezikit

Copy link
Copy Markdown
Owner

This shortens the README, replaces the benchmark and its charts, and moves the project from the Unlicense to MIT OR Apache-2.0. No source code under src/ or python/ changes, so no Kyber or ML-KEM output changes either.

Commits, in order

  1. docs: benchmark ML-KEM on a release build and redraw the charts
  2. docs: shorten the README and rewrite it in plain prose
  3. chore: license under MIT OR Apache-2.0 instead of the Unlicense

The benchmark

The old script only parsed the Kyber performance tests, and its figures looked like they came from a debug build (Kyber768 key generation at 0.76 ms). benchmark.py now times ML_KEM_* and Kyber* directly through the public API, as the median of 7 rounds of 500 calls, and writes performance-tests/results.json. It draws two charts, latency.png and ml_kem_vs_kyber.png, in place of the four old ones. make benchmark builds the release extension first. matplotlib is listed in performance-tests/requirements.txt so CI and requirements-dev.txt do not pull it in. The chart colors passed the dataviz skill's color-blind and contrast check on a white background.

On an Intel Core i7-7700 with Python 3.14, ML_KEM_768 takes 0.052 ms for key generation, 0.058 ms for encapsulation and 0.071 ms for decapsulation. ML-KEM and the Kyber classes are within about 10 percent of each other. This is one machine and one run, and the README says so.

The README

Same facts, fewer words, about two thirds of the old length. I ran every Python block in it, and the error message it shows is the one the library raises. The security section keeps the earlier wording: the ML-KEM code passes ACVP, CCTV and Wycheproof, nobody outside the project has audited it, and there is no constant-time claim. It now points to SECURITY.md for what is open, including the Keccak stack copies.

The license

LICENSE-MIT and LICENSE-APACHE are added and LICENSE is removed. The Apache text is the file from apache.org (11358 bytes, SHA-256 cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30). Cargo.toml and pyproject.toml say MIT OR Apache-2.0, pyproject.toml lists both files in license-files, and the Public Domain classifier is gone. A wheel built from this branch has License-Expression: MIT OR Apache-2.0 in METADATA and contains both license files. The README, CONTRIBUTING.md, the changelog, CLAUDE.md, AGENTS.md and PLAN-2.0.md are updated. Releases up to 1.0.5 stay under the Unlicense, and the README says so.

Things to check

  • The MIT file says "Copyright (c) 2026 Yoav Haimov", taken from the pyproject.toml author and the first commit date. Change it if the holder or year should differ.
  • All commits in the history come from the maintainer's addresses and the Zikithezikit account, which I assumed are the same person. If anyone else wrote code that is in the repo, relicensing needs their agreement. This is not legal advice.
  • The license change could be its own PR. It sits here because the README License section changed in both the docs and the license commits.

Verified

  • scripts/check.sh (fmt, clippy -D warnings, cargo test, maturin develop, pytest) passed on the tip, and on the first two commits through git rebase --exec against origin/dev-v2. For the third commit I ran it on the tip only.
  • The benchmark ran on a release build, and I looked at both charts.
  • The wheel metadata check above.

Not verified

  • The numbers on other machines, Python versions or operating systems.
  • The README renders as intended on GitHub. I checked the Markdown by reading it, not in the web view.

Generated with Claude Code

https://claude.ai/code/session_01CXWjkNs3Htog36snV9FcXb

Zikithezikit and others added 7 commits October 31, 2026 10:06
The old benchmark parsed the Kyber performance tests only and its figures came
from a debug build. benchmark.py now times ML_KEM_* and Kyber* directly (median
of 7 rounds of 500 calls), writes results.json, and draws two charts that replace
the four old ones. make benchmark builds the release extension first. The chart
dependency is in performance-tests/requirements.txt, not in requirements-dev.txt.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXWjkNs3Htog36snV9FcXb
Same facts, fewer words: install, quick start, a shorter class tour, sizes,
errors, the Kyber deprecation, security status and the new benchmark table and
charts. Every Python block in it was run, and the error message it shows is the
real one. The performance section now says what was measured and on what.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXWjkNs3Htog36snV9FcXb
Adds LICENSE-MIT and LICENSE-APACHE (the Apache text is the apache.org file,
11358 bytes, SHA-256 cfc7749b...523d30) and removes LICENSE. Sets license =
"MIT OR Apache-2.0" in Cargo.toml and pyproject.toml, with license-files, and
drops the Public Domain classifier. The built wheel's METADATA has
License-Expression: MIT OR Apache-2.0 and ships both files. Releases up to 1.0.5
stay under the Unlicense; the README, CONTRIBUTING.md, the changelog and the
agent notes say so.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXWjkNs3Htog36snV9FcXb
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ents file

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@Zikithezikit
Zikithezikit merged commit 8afb6b2 into dev-v2 Oct 31, 2026
45 checks passed
@Zikithezikit
Zikithezikit deleted the docs-readme-benchmarks branch October 31, 2026 08:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant