daftar 0.1.0__tar.gz

daftar-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

daftar-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include PUBLISHING.md
+recursive-include examples *.py
+recursive-include tests *.py

daftar-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: daftar
+Version: 0.1.0
+Summary: Record what produced each computational result: environment, code, parameters, seeds, inputs.
+Author: Aslan Satary Dizaji
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/aslansd/daftar
+Project-URL: Repository, https://github.com/aslansd/daftar
+Project-URL: Issues, https://github.com/aslansd/daftar/issues
+Keywords: reproducibility,provenance,simulation,computational-science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: jaxley
+Requires-Dist: jaxley; extra == "jaxley"
+Provides-Extra: cpm
+Requires-Dist: cpm-toolbox; extra == "cpm"
+Provides-Extra: meltingpot
+Requires-Dist: dm-meltingpot; extra == "meltingpot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Dynamic: license-file
+
+# daftar
+
+**دفتر** — *ledger, register, record-book.* The same word in Persian, Turkish
+(*defter*), Azerbaijani, Arabic, Urdu, and Hindi.
+
+Record what produced each computational result — the environment, code version,
+parameters, random seeds, and input files — so two runs can be compared and any
+past run can be rebuilt.
+
+Experiment trackers solved this for deep learning, where an experiment is
+`model.fit()`. They do not help when the experiment is a Hodgkin–Huxley
+simulation of 302 neurons, a hierarchical fit across 60 participants, or a
+200-episode multi-agent sweep. Those runs have no epochs, no loss curves, and no
+checkpoints. They have parameter grids, solver tolerances, random seeds, and
+derived quantities.
+
+**No dependencies. Runs offline. No account, no server, no network call.**
+
+```bash
+pip install daftar
+```
+
+---
+
+## The thirty-second version
+
+```python
+import daftar   # no alias: `df` would collide with the pandas convention
+
+with daftar.track("celegans", params={"dt": 0.025, "solver": "bwd_euler"}, seed=42) as run:
+    run.add_input("data/connectome.csv")
+    v = simulate(dt=0.025)
+    run.log_result("mean_rate_hz", float(v.mean()))
+```
+
+Then, next Thursday, when the number is different:
+
+```
+$ daftar diff r-4f21ab r-88c07e
+
+--- r-4f21ab  celegans  2026-05-14T14:02:11+00:00
++++ r-88c07e  celegans  2026-05-16T09:47:03+00:00
+
+candidate causes (1)
+  env.jax               0.4.35  ->  0.4.41
+
+observed effects (1)
+  result.mean_rate_hz   4.812  ->  4.796
+
+2 meaningful field(s) differ, 27 identical
+
+Results differ, and so do things that could explain it.
+The candidate causes below are where to look.
+```
+
+Same code, same seed, same inputs. A patch-level JAX upgrade moved the answer.
+That is the question this tool exists to answer, and it answers it the same
+afternoon you install it.
+
+---
+
+## Why this and not the eight tools that came before
+
+Binder, ReproZip, Sciunit, Whole Tale, Gigantum, Renku, Code Ocean: in a
+published survey, exactly **one of 38 researchers** had ever used a dedicated
+platform to save and re-run a computational experiment.
+
+Every one of those tools asked scientists to change how they work today in
+exchange for a benefit arriving in three years. That trade never closes.
+
+`daftar` inverts it. `diff` answers a question people ask weekly — *why is
+this number different from Tuesday's?* — and provenance arrives as a free side
+effect of a tool they already wanted. Reproducibility is the by-product, not
+the pitch.
+
+Three consequences of taking that seriously:
+
+- **One line and one indent.** No DSL, no workflow language, no migration. If
+  wrapping an existing simulation costs more than that, nobody does it.
+- **The manifest is plain JSON with sorted, dotted keys.** Readable and
+  greppable without this package installed, and `git diff`-able. If daftar
+  disappears, the record survives.
+- **Failed runs are recorded too.** A crashed run that took four hours is
+  exactly the one you will want to look at later.
+
+---
+
+## What gets captured
+
+| Namespace | Contents |
+|---|---|
+| `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
+| `param.*` | everything you chose, including defaults you never passed |
+| `seed.*` | seeds **applied** to `random`, numpy, torch; the JAX root key |
+| `input.*` | sha256 and size of every declared input file or directory |
+| `env.*` | interpreter, OS, and versions of packages the run actually imported |
+| `result.*` | scalar outcomes worth comparing |
+| `output.*` | sha256 of produced files |
+| `cost.*` | wall clock, host, cpu count |
+
+Two of these are less obvious than they look.
+
+**Seeds are applied, not merely recorded.** A tool that only writes down the
+seed is close to useless: if the code seeded itself from the clock, recording
+that fact tells you the run is irreproducible but does nothing to fix it.
+`track(seed=...)` sets every RNG it can reach, then records what it set. If you
+pass no seed, one is generated, applied, and recorded — an accidental seed that
+is written down is reproducible; a deliberate one that isn't, is not.
+
+**Dirty working trees get their diff hashed.** "Dirty" alone tells you there
+were uncommitted edits but not whether they were the *same* edits. Hashing the
+diff means two dirty runs can still be proven identical, which is the common
+case during a debugging session.
+
+---
+
+## The four commands
+
+```bash
+daftar list                    # what has been run
+daftar show r-4f21ab           # one run's full manifest
+daftar diff r-4f21ab r-88c07e  # what changed, and whether it mattered
+daftar vary -l my-sweep        # which fields differ across many runs
+daftar replay r-4f21ab         # what it would take to reproduce this
+daftar export r-4f21ab -o run.zip
+```
+
+`diff` exits 0 if the second run reproduces the first and 1 otherwise, so it
+works in CI as a regression check on your own results.
+
+### Verdicts
+
+`diff` does not just list changed fields. It separates fields that could have
+**caused** a difference (`code`, `param`, `seed`, `input`, `env`) from fields
+that merely **record** one (`result`, `output`), and reports what the
+combination implies:
+
+| Verdict | Meaning |
+|---|---|
+| `identical` | Nothing meaningful moved. |
+| `explained` | Results differ and so do plausible causes. Here they are. |
+| `no_effect` | Environment changed, results didn't. Evidence of robustness. |
+| **`nondeterministic`** | **Results differ and nothing that could have caused it does.** |
+| `incomparable` | The runs recorded different result fields. |
+
+That fourth verdict is the valuable one. An unseeded RNG buried three libraries
+deep can survive for years because nobody ever compares two runs precisely
+enough to notice. `daftar` reports it as a finding rather than a glitch.
+
+---
+
+## Sweeps
+
+```python
+result = daftar.sweep(
+    simulate, label="tau-sweep", seed=42,
+    dt=[0.025, 0.01], tau=[5.0, 10.0, 20.0],
+)
+print(result.table())
+```
+
+Each grid point is a separate run with its own manifest — not one run with a
+nested table. That means a sweep point and a run you did by hand last Tuesday
+are the same kind of object, and `diff` works across them. A sweep that fails at
+point 3 of 40 keeps the first two results.
+
+---
+
+## Replay
+
+`daftar replay` prints a plan, and deliberately does **not** execute
+anything. Re-running arbitrary recorded code would mean this package executes
+whatever a manifest tells it to, and it still could not restore your CUDA
+driver. What it does honestly is state the target state, check the current state
+against it, and list every discrepancy:
+
+```
+Replay plan for r-4f21ab
+
+  entrypoint   sim/celegans_hh.py::run_network
+  commit       9c1d0ae
+  seed         42
+
+  BLOCKERS -- this run cannot be reproduced as recorded:
+    - input file changed since the run: data/connectome.csv
+      (was a7f39b21, now 3e0c77af)
+```
+
+---
+
+## Export
+
+`daftar export` writes a zip containing `README.md`, `manifest.json`,
+`fields.tsv`, and the referenced input and output files. The README is generated
+in plain English at the archive root, so a successor learns what they are
+looking at without installing anything. A bundle that needs our tool to be
+understood defeats its own purpose.
+
+---
+
+## Framework adapters
+
+The core tracks any Python function. An adapter earns its existence only by
+knowing something a generic tracker cannot infer.
+
+| Adapter | Records what you'd otherwise lose |
+|---|---|
+| `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
+| `cpm` | parameter **bounds and priors**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
+| `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
+
+```python
+from daftar.adapters import jaxley as jxa
+
+with daftar.track("hh-cell", seed=0) as run:
+    v = jxa.integrate(cell, run, t_max=10.0, delta_t=0.025)
+```
+
+Adapters never import their framework at module load, so `import daftar`
+works with none of them installed. Every probe is best-effort: a provenance tool
+that crashes a four-hour simulation because a framework renamed an attribute has
+done far more harm than the missing field was worth.
+
+See `examples/adapter_usage.py` for the full pattern for each.
+
+### Why not Concordia
+
+Every Concordia agent step calls `LanguageModel.sample_text()`, and no major
+provider guarantees token-level determinism even with a fixed seed. `replay`
+there cannot mean what it means everywhere else, and shipping an adapter whose
+replay silently does not replay would undermine the one property this package
+sells.
+
+The right design is a different contract — wrap the model, hash every
+`(prompt, response)` pair in order, and have `diff` report the first step at
+which two runs diverged. That turns Concordia into the strongest argument for
+this whole package rather than an awkward fit, because LLM-driven simulation is
+the case where nobody can currently audit anything. It comes after the
+deterministic adapters have users.
+
+---
+
+## Try it
+
+```bash
+python examples/demo_end_to_end.py
+```
+
+No frameworks needed. Walks through a clean reproduction, a deliberate parameter
+change, a genuine nondeterminism catch, a sweep, a replay plan, and an export.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Licence
+
+Apache 2.0.

daftar-0.1.0/PUBLISHING.md

@@ -0,0 +1,112 @@
+# Publishing daftar
+
+## Why your TestPyPI upload returned 403
+
+**TestPyPI is a completely separate service from PyPI.** Separate database,
+separate accounts, separate API tokens. A token issued by `pypi.org` is
+meaningless to `test.pypi.org` and is rejected with a bare `403 Forbidden` —
+which is exactly what you saw.
+
+In likelihood order:
+
+1. **You used a PyPI token on TestPyPI.** Overwhelmingly the most common cause.
+2. **You have no TestPyPI account.** Registering on PyPI does not register you
+   on TestPyPI. Sign up separately at
+   <https://test.pypi.org/account/register/>.
+3. **Email not verified** on the TestPyPI account. Unverified accounts cannot
+   upload, and the error is a 403 with no explanation.
+4. **The name is taken on TestPyPI.** Its namespace is full of abandoned junk
+   and is pruned irregularly. If someone holds `daftar` there you get a 403,
+   and it says nothing about real PyPI, where `daftar` is confirmed free.
+
+To rule out 1–3, get a token from
+<https://test.pypi.org/manage/account/token/> and retry with `--verbose`:
+
+```bash
+python -m twine upload --repository testpypi --verbose dist/*
+```
+
+The verbose output distinguishes "bad credentials" from "you do not own this
+project name", which the plain error does not.
+
+## The thing worth noticing
+
+Your upload reached **100%** before failing. The bytes crossed the network and
+were rejected at the authorization layer. Uploading to the Python package index
+from where you are is not blocked. That was the open question, and it is now
+answered.
+
+## Recommendation: skip TestPyPI
+
+TestPyPI's purpose is rehearsing a release. You have already done the parts that
+matter:
+
+- `python -m build` succeeds with no warnings
+- `python -m twine check dist/*` passes both artifacts
+- the wheel installs into a clean virtualenv and imports with zero dependencies
+- 34 tests pass
+
+A successful TestPyPI upload would tell you nothing further, and every day spent
+debugging it is a day `daftar` remains unclaimed on the index that matters.
+
+```bash
+# 1. Account on pypi.org, email verified
+# 2. Token: pypi.org -> Account settings -> API tokens -> "Add API token"
+#    Scope "Entire account" for the first upload; re-scope to the project after.
+python -m twine upload dist/*
+```
+
+When prompted, paste the token including the `pypi-` prefix. Twine 7 asks for
+the token directly, so you do not need to type `__token__` as a username.
+
+To avoid re-pasting, put it in `~/.pypirc` (mode 600):
+
+```ini
+[distutils]
+index-servers = pypi testpypi
+
+[pypi]
+username = __token__
+password = pypi-AgEIcHlwaS5vcmc...
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-AgENdGVzdC5weXBpLm9yZw...
+```
+
+Note the two tokens differ: TestPyPI tokens encode `dGVzdC5weXBpLm9yZw` —
+base64 for `test.pypi.org`. If yours does not, you are holding the wrong one.
+
+## A version number can never be reused
+
+Not even after deleting the release. If 0.1.0 turns out wrong, ship 0.1.1. Do
+not agonise over the first upload; the name is the scarce thing, not the
+version.
+
+## Also claim
+
+- GitHub `github.com/aslansd/daftar` (the org name `daftar` was free when checked)
+- Update `[project.urls]` in `pyproject.toml` if you use a different path
+
+## Before announcing
+
+- [ ] `pytest -q` green
+- [ ] `python examples/demo_end_to_end.py` runs on a fresh clone
+- [ ] wheel installed into a clean venv and imported
+- [ ] README renders correctly on the live PyPI page
+- [ ] **run daftar across three of your own repos, unmodified**
+- [ ] `git tag v0.1.0 && git push --tags`
+
+The fifth item is the month-7 milestone from the feasibility plan and the only
+real test of whether the API is unobtrusive enough that you keep using it when
+nobody is watching. Do it before the announcement, not after.
+
+## On the licence
+
+`LICENSE` now contains the full Apache-2.0 text, and `pyproject.toml` declares
+`license = "Apache-2.0"` as an SPDX expression. This is not bookkeeping: the
+strategy rests on publishing freely available source code, which has generally
+been treated as "information and informational materials". A public repository
+with a permissive licence and a licence file present is a different legal object
+from a private or licence-gated artifact. Keep it that way.