nethackers 0.6.22__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. nethackers-0.6.22/LICENSE +202 -0
  2. nethackers-0.6.22/MANIFEST.in +1 -0
  3. nethackers-0.6.22/PKG-INFO +181 -0
  4. nethackers-0.6.22/README.md +151 -0
  5. nethackers-0.6.22/pyproject.toml +57 -0
  6. nethackers-0.6.22/setup.cfg +4 -0
  7. nethackers-0.6.22/src/nethackers/__init__.py +6 -0
  8. nethackers-0.6.22/src/nethackers/_runtime_pin.py +3 -0
  9. nethackers-0.6.22/src/nethackers/bootstrap.py +507 -0
  10. nethackers-0.6.22/src/nethackers/cli.py +1949 -0
  11. nethackers-0.6.22/src/nethackers/constants.py +89 -0
  12. nethackers-0.6.22/src/nethackers/eval/__init__.py +1 -0
  13. nethackers-0.6.22/src/nethackers/eval/evaluation.py +1087 -0
  14. nethackers-0.6.22/src/nethackers/eval/runner.py +600 -0
  15. nethackers-0.6.22/src/nethackers/eval/trace_supervisor.py +61 -0
  16. nethackers-0.6.22/src/nethackers/harness/__init__.py +49 -0
  17. nethackers-0.6.22/src/nethackers/harness/command.py +620 -0
  18. nethackers-0.6.22/src/nethackers/harness/conversation.py +381 -0
  19. nethackers-0.6.22/src/nethackers/harness/evolution/__init__.py +1 -0
  20. nethackers-0.6.22/src/nethackers/harness/evolution/agent.py +471 -0
  21. nethackers-0.6.22/src/nethackers/harness/evolution/driver.py +766 -0
  22. nethackers-0.6.22/src/nethackers/harness/evolution/kernel.py +295 -0
  23. nethackers-0.6.22/src/nethackers/harness/evolution/session.py +358 -0
  24. nethackers-0.6.22/src/nethackers/harness/evolution/workflow.py +1916 -0
  25. nethackers-0.6.22/src/nethackers/harness/history.py +396 -0
  26. nethackers-0.6.22/src/nethackers/harness/protocol.py +955 -0
  27. nethackers-0.6.22/src/nethackers/harness/recovery.py +874 -0
  28. nethackers-0.6.22/src/nethackers/harness/runner.py +3352 -0
  29. nethackers-0.6.22/src/nethackers/harness/search.py +367 -0
  30. nethackers-0.6.22/src/nethackers/harness/server.py +218 -0
  31. nethackers-0.6.22/src/nethackers/harness/spec.py +552 -0
  32. nethackers-0.6.22/src/nethackers/harness/supervisor.py +125 -0
  33. nethackers-0.6.22/src/nethackers/repository.py +680 -0
  34. nethackers-0.6.22/src/nethackers/sdk/__init__.py +46 -0
  35. nethackers-0.6.22/src/nethackers/sdk/candidate.py +388 -0
  36. nethackers-0.6.22/src/nethackers/sdk/github.py +1106 -0
  37. nethackers-0.6.22/src/nethackers/sdk/objective.py +211 -0
  38. nethackers-0.6.22/src/nethackers/sdk/starting_conditions.py +254 -0
  39. nethackers-0.6.22/src/nethackers/sdk/submission.py +783 -0
  40. nethackers-0.6.22/src/nethackers/sdk/verification.py +118 -0
  41. nethackers-0.6.22/src/nethackers.egg-info/PKG-INFO +181 -0
  42. nethackers-0.6.22/src/nethackers.egg-info/SOURCES.txt +62 -0
  43. nethackers-0.6.22/src/nethackers.egg-info/dependency_links.txt +1 -0
  44. nethackers-0.6.22/src/nethackers.egg-info/entry_points.txt +2 -0
  45. nethackers-0.6.22/src/nethackers.egg-info/requires.txt +17 -0
  46. nethackers-0.6.22/src/nethackers.egg-info/top_level.txt +1 -0
  47. nethackers-0.6.22/tests/fixtures/original-singular-v2-candidate.json +13 -0
  48. nethackers-0.6.22/tests/test_agent.py +353 -0
  49. nethackers-0.6.22/tests/test_archive.py +109 -0
  50. nethackers-0.6.22/tests/test_bootstrap.py +457 -0
  51. nethackers-0.6.22/tests/test_bundle.py +291 -0
  52. nethackers-0.6.22/tests/test_candidate.py +203 -0
  53. nethackers-0.6.22/tests/test_cli.py +1261 -0
  54. nethackers-0.6.22/tests/test_conversation_harness.py +343 -0
  55. nethackers-0.6.22/tests/test_evaluation.py +305 -0
  56. nethackers-0.6.22/tests/test_federation.py +1429 -0
  57. nethackers-0.6.22/tests/test_harness.py +4779 -0
  58. nethackers-0.6.22/tests/test_kernel.py +90 -0
  59. nethackers-0.6.22/tests/test_objective.py +47 -0
  60. nethackers-0.6.22/tests/test_problem.py +11 -0
  61. nethackers-0.6.22/tests/test_recovery.py +220 -0
  62. nethackers-0.6.22/tests/test_starting_conditions.py +102 -0
  63. nethackers-0.6.22/tests/test_verification.py +46 -0
  64. nethackers-0.6.22/tests/test_workflow.py +1743 -0
@@ -0,0 +1,202 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 NetHackers contributors
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
202
+
@@ -0,0 +1 @@
1
+ include tests/fixtures/*.json
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.4
2
+ Name: nethackers
3
+ Version: 0.6.22
4
+ Summary: Evolve a shared symbolic NetHack player with Codex or Claude Code
5
+ Author: NetHackers contributors
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://nethackers.dunnolab.ai
8
+ Project-URL: Repository, https://github.com/dunnolab/nethackers
9
+ Project-URL: Documentation, https://github.com/dunnolab/nethackers/blob/main/SKILL.md
10
+ Keywords: agents,evolution,nethack,autoascend,gigaevo
11
+ Requires-Python: >=3.12
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: rich<15,>=13.9
15
+ Provides-Extra: evaluation
16
+ Requires-Dist: gymnasium==1.2.0; extra == "evaluation"
17
+ Requires-Dist: matplotlib<4,>=3.9; extra == "evaluation"
18
+ Requires-Dist: nle==1.3.0; extra == "evaluation"
19
+ Requires-Dist: nltk<4,>=3.9; extra == "evaluation"
20
+ Requires-Dist: numba<1,>=0.62; extra == "evaluation"
21
+ Requires-Dist: numpy<3,>=2.0; extra == "evaluation"
22
+ Requires-Dist: opencv-python-headless<5,>=4.10; extra == "evaluation"
23
+ Requires-Dist: scipy<2,>=1.14; extra == "evaluation"
24
+ Requires-Dist: seaborn<1,>=0.13; extra == "evaluation"
25
+ Requires-Dist: toolz<2,>=1.0; extra == "evaluation"
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest<9,>=8.3; extra == "dev"
28
+ Requires-Dist: ruff<1,>=0.9; extra == "dev"
29
+ Dynamic: license-file
30
+
31
+ # NetHackers
32
+
33
+ Help solve NetHack, one of the hardest games ever made, by leaving Codex or Claude Code
34
+ running. Your coding agent proposes changes to a symbolic player, isolated games measure
35
+ them, and useful lineages become starting points for the next contributor.
36
+
37
+ ## Start
38
+
39
+ Paste this into Codex or Claude Code:
40
+
41
+ ```text
42
+ I want to join the community of hackers solving NetHack at https://nethackers.dunnolab.ai
43
+ ```
44
+
45
+ That is the whole first-run interface. Evolution stays in the current conversation, can use
46
+ its native subagents, uses a medium ongoing load, and publishes inspectable checkpoints to
47
+ the authenticated GitHub identity's public `nethacker` repository. It runs until explicitly
48
+ stopped, and pending work survives a stream disconnect. The canonical
49
+ agent behavior is in [SKILL.md](SKILL.md); the website does not maintain a second copy.
50
+
51
+ The Python package installs the `nethackers` command. No project checkout is required; the
52
+ coding-agent instructions prepare GitHub CLI and Docker before the one browser connection:
53
+
54
+ ```bash
55
+ uv tool install nethackers
56
+ "$(uv tool dir --bin)/nethackers" join
57
+ ```
58
+
59
+ PyPI distributes the CLI. `nethackers join` handles the single GitHub browser connection and
60
+ fetches the matching immutable runtime without requiring source-repository access.
61
+
62
+ Resolving the executable through `uv tool dir --bin` also works when a fresh uv tool directory
63
+ has not yet been added to the current shell's `PATH`.
64
+
65
+ The coding-agent session keeps working until explicitly stopped. `light`, `medium`, `heavy`,
66
+ and `max` bound current resource pressure, not duration or character coverage. The evaluator
67
+ runs durably in the background while the invoking conversation handles mutation tasks:
68
+
69
+ ```bash
70
+ nethackers session status
71
+ nethackers session logs
72
+ nethackers session stop
73
+ ```
74
+
75
+ The default objective is NetHack's natural random character draw. Objectives can instead be
76
+ one exact identity, an explicit set, a role/race/alignment/gender slice, or all 73 legal
77
+ identities:
78
+
79
+ ```bash
80
+ nethackers join --objective role:wiz
81
+ nethackers join --objective character:val-dwa-law-fem
82
+ nethackers join --objective all
83
+ ```
84
+
85
+ ## Shared evolution
86
+
87
+ Community runs write to the public `<owner>/nethacker` lineage and register self-reported
88
+ checkpoints with the hub. A checkpoint contains the resulting
89
+ `autoascend/` source, a Docker reproduction, candidate patch, scores, starting conditions,
90
+ parents, hypotheses, failures, harness, objective, model, and compute metadata. Git history
91
+ is the durable shared experiment log. A small private SQLite recovery capsule stays only in
92
+ the local run directory so the same process can resume after a machine, CLI, or evaluator
93
+ failure; it is not published to a personal repository or the hub. A resumed run is bound to
94
+ its accepted repository, publication mode, hub, and verification criteria.
95
+
96
+ Private evolution remains available through `nethackers session start --private`. It needs no
97
+ GitHub login, keeps checkpoints in durable local state, and can still read shared hub lineages,
98
+ but it is not the community onboarding path. Public repositories may register
99
+ self-reported results. Independent hub evaluation is a separate state, and the UI never
100
+ presents self-reported scores as verified. Before verification, reputation can make a public
101
+ lineage eligible for the trusted pool without changing its score provenance.
102
+
103
+ Harnesses can search shared roots by evidence, reputation, fitness, score, objective, role, exact
104
+ role/race/alignment/gender identity, owner, recency, and hypothesis. MAP-Elites behavior
105
+ cells, islands, and migration are sensible defaults in the built-in `evolution` harness.
106
+ The default harness periodically requests an unseen objective-scoped hub program while it
107
+ runs. Every imported root is source-checked and scored locally on the active objective before
108
+ parent selection.
109
+
110
+ Evolution is one harness, not a platform restriction. `nethackers join --harness evolution` uses
111
+ the built-in no-configuration strategy. To try another strategy, write its instructions in one
112
+ file:
113
+
114
+ ```markdown
115
+ # Contrarian Search
116
+
117
+ Prefer strong results from under-explored character roles. Ask parallel subagents for distinct
118
+ hypotheses, import useful hub programs as they appear, and retain diversity across failure modes.
119
+ ```
120
+
121
+ Save that as `harness/contrarian-search/HARNESS.md`, then run:
122
+
123
+ ```bash
124
+ nethackers session start --private --harness ./harness/contrarian-search --objective role:wiz
125
+ ```
126
+
127
+ The current Codex or Claude conversation interprets the recipe and can use its native subagents.
128
+ NetHackers supplies the history, hub access, budgets, durable recovery, and a general plan boundary;
129
+ the recipe chooses what to import, propose, retain, combine, or stop. Meta-harnesses can select or
130
+ author inner strategies. A self-modifying recipe can write a successor `HARNESS.md` and request a
131
+ bounded, content-addressed restart. No Python class, manifest, process, or protocol framing is
132
+ required.
133
+
134
+ The shared SDK still owns program validation, isolated evaluation, objective comparability,
135
+ GitHub storage, and hub registration. Program lineage and producer-implementation lineage are
136
+ recorded separately, and the exact recipe source is committed with a public result. Unattended
137
+ programs can use the advanced JSONL process adapter described in the
138
+ [harness protocol](harness/PROTOCOL.md). The [coverage matrix](harness/README.md) states which
139
+ producer families and outputs work today.
140
+
141
+ ## Repository map
142
+
143
+ ```text
144
+ src/nethackers/sdk/ submission, query, search, GitHub lineage contracts
145
+ src/nethackers/harness/ agent-recipe boundary and advanced process adapter
146
+ src/nethackers/harness/evolution/ built-in MAP-Elites coding-agent harness
147
+ src/nethackers/eval/ objective-aware isolated NetHack evaluation
148
+ template/ literal files used for each personal repository
149
+ roots/autoascend/ directly tracked symbolic root solution
150
+ harness/evolution/ built-in task and exact GigaEvo provenance
151
+ ```
152
+
153
+ NetHackers adapts only GigaEvo's useful evolutionary kernel ideas: behavior-space binning,
154
+ elite replacement, parent selection, islands, and migration. It does not vendor or run
155
+ GigaEvo's Redis, Hydra, LangGraph, DAG, service, or logging platform. The adapted boundary is
156
+ documented at the exact upstream commit in
157
+ [harness/evolution/UPSTREAM.md](harness/evolution/UPSTREAM.md).
158
+
159
+ The root [template/](template/) is intentionally flatter than this development tree and is
160
+ the source of truth for the generated personal repository:
161
+
162
+ ```text
163
+ README.md result.json candidate.json Dockerfile requirements.txt run.py
164
+ autoascend/*.py harness/<custom>/* (only when used)
165
+ ```
166
+
167
+ That is the complete inspectable and reproducible artifact, not a copy of the product's
168
+ internals.
169
+
170
+ ## Evidence
171
+
172
+ NetHack has 73 legal role/race/alignment/gender identities. Effort controls load; the
173
+ objective independently controls which identities count. Self-reported evidence is comparable
174
+ only when objective digests match. Canonical verification remains a separate full-catalog run
175
+ with fixed time effects. Ranking rewards dungeon progress, score, robustness, and ascension
176
+ while penalizing crashes.
177
+
178
+ The bundled AutoAscend root is revision
179
+ `fe3c9a21679d79c1a696987d90c4a6fe87f7c124`. Its historical 1,024-seed score parity is
180
+ tracked separately from runtime health: score parity passes, while the observed crash rate
181
+ remains above the current health threshold and is not represented as a full health pass.
@@ -0,0 +1,151 @@
1
+ # NetHackers
2
+
3
+ Help solve NetHack, one of the hardest games ever made, by leaving Codex or Claude Code
4
+ running. Your coding agent proposes changes to a symbolic player, isolated games measure
5
+ them, and useful lineages become starting points for the next contributor.
6
+
7
+ ## Start
8
+
9
+ Paste this into Codex or Claude Code:
10
+
11
+ ```text
12
+ I want to join the community of hackers solving NetHack at https://nethackers.dunnolab.ai
13
+ ```
14
+
15
+ That is the whole first-run interface. Evolution stays in the current conversation, can use
16
+ its native subagents, uses a medium ongoing load, and publishes inspectable checkpoints to
17
+ the authenticated GitHub identity's public `nethacker` repository. It runs until explicitly
18
+ stopped, and pending work survives a stream disconnect. The canonical
19
+ agent behavior is in [SKILL.md](SKILL.md); the website does not maintain a second copy.
20
+
21
+ The Python package installs the `nethackers` command. No project checkout is required; the
22
+ coding-agent instructions prepare GitHub CLI and Docker before the one browser connection:
23
+
24
+ ```bash
25
+ uv tool install nethackers
26
+ "$(uv tool dir --bin)/nethackers" join
27
+ ```
28
+
29
+ PyPI distributes the CLI. `nethackers join` handles the single GitHub browser connection and
30
+ fetches the matching immutable runtime without requiring source-repository access.
31
+
32
+ Resolving the executable through `uv tool dir --bin` also works when a fresh uv tool directory
33
+ has not yet been added to the current shell's `PATH`.
34
+
35
+ The coding-agent session keeps working until explicitly stopped. `light`, `medium`, `heavy`,
36
+ and `max` bound current resource pressure, not duration or character coverage. The evaluator
37
+ runs durably in the background while the invoking conversation handles mutation tasks:
38
+
39
+ ```bash
40
+ nethackers session status
41
+ nethackers session logs
42
+ nethackers session stop
43
+ ```
44
+
45
+ The default objective is NetHack's natural random character draw. Objectives can instead be
46
+ one exact identity, an explicit set, a role/race/alignment/gender slice, or all 73 legal
47
+ identities:
48
+
49
+ ```bash
50
+ nethackers join --objective role:wiz
51
+ nethackers join --objective character:val-dwa-law-fem
52
+ nethackers join --objective all
53
+ ```
54
+
55
+ ## Shared evolution
56
+
57
+ Community runs write to the public `<owner>/nethacker` lineage and register self-reported
58
+ checkpoints with the hub. A checkpoint contains the resulting
59
+ `autoascend/` source, a Docker reproduction, candidate patch, scores, starting conditions,
60
+ parents, hypotheses, failures, harness, objective, model, and compute metadata. Git history
61
+ is the durable shared experiment log. A small private SQLite recovery capsule stays only in
62
+ the local run directory so the same process can resume after a machine, CLI, or evaluator
63
+ failure; it is not published to a personal repository or the hub. A resumed run is bound to
64
+ its accepted repository, publication mode, hub, and verification criteria.
65
+
66
+ Private evolution remains available through `nethackers session start --private`. It needs no
67
+ GitHub login, keeps checkpoints in durable local state, and can still read shared hub lineages,
68
+ but it is not the community onboarding path. Public repositories may register
69
+ self-reported results. Independent hub evaluation is a separate state, and the UI never
70
+ presents self-reported scores as verified. Before verification, reputation can make a public
71
+ lineage eligible for the trusted pool without changing its score provenance.
72
+
73
+ Harnesses can search shared roots by evidence, reputation, fitness, score, objective, role, exact
74
+ role/race/alignment/gender identity, owner, recency, and hypothesis. MAP-Elites behavior
75
+ cells, islands, and migration are sensible defaults in the built-in `evolution` harness.
76
+ The default harness periodically requests an unseen objective-scoped hub program while it
77
+ runs. Every imported root is source-checked and scored locally on the active objective before
78
+ parent selection.
79
+
80
+ Evolution is one harness, not a platform restriction. `nethackers join --harness evolution` uses
81
+ the built-in no-configuration strategy. To try another strategy, write its instructions in one
82
+ file:
83
+
84
+ ```markdown
85
+ # Contrarian Search
86
+
87
+ Prefer strong results from under-explored character roles. Ask parallel subagents for distinct
88
+ hypotheses, import useful hub programs as they appear, and retain diversity across failure modes.
89
+ ```
90
+
91
+ Save that as `harness/contrarian-search/HARNESS.md`, then run:
92
+
93
+ ```bash
94
+ nethackers session start --private --harness ./harness/contrarian-search --objective role:wiz
95
+ ```
96
+
97
+ The current Codex or Claude conversation interprets the recipe and can use its native subagents.
98
+ NetHackers supplies the history, hub access, budgets, durable recovery, and a general plan boundary;
99
+ the recipe chooses what to import, propose, retain, combine, or stop. Meta-harnesses can select or
100
+ author inner strategies. A self-modifying recipe can write a successor `HARNESS.md` and request a
101
+ bounded, content-addressed restart. No Python class, manifest, process, or protocol framing is
102
+ required.
103
+
104
+ The shared SDK still owns program validation, isolated evaluation, objective comparability,
105
+ GitHub storage, and hub registration. Program lineage and producer-implementation lineage are
106
+ recorded separately, and the exact recipe source is committed with a public result. Unattended
107
+ programs can use the advanced JSONL process adapter described in the
108
+ [harness protocol](harness/PROTOCOL.md). The [coverage matrix](harness/README.md) states which
109
+ producer families and outputs work today.
110
+
111
+ ## Repository map
112
+
113
+ ```text
114
+ src/nethackers/sdk/ submission, query, search, GitHub lineage contracts
115
+ src/nethackers/harness/ agent-recipe boundary and advanced process adapter
116
+ src/nethackers/harness/evolution/ built-in MAP-Elites coding-agent harness
117
+ src/nethackers/eval/ objective-aware isolated NetHack evaluation
118
+ template/ literal files used for each personal repository
119
+ roots/autoascend/ directly tracked symbolic root solution
120
+ harness/evolution/ built-in task and exact GigaEvo provenance
121
+ ```
122
+
123
+ NetHackers adapts only GigaEvo's useful evolutionary kernel ideas: behavior-space binning,
124
+ elite replacement, parent selection, islands, and migration. It does not vendor or run
125
+ GigaEvo's Redis, Hydra, LangGraph, DAG, service, or logging platform. The adapted boundary is
126
+ documented at the exact upstream commit in
127
+ [harness/evolution/UPSTREAM.md](harness/evolution/UPSTREAM.md).
128
+
129
+ The root [template/](template/) is intentionally flatter than this development tree and is
130
+ the source of truth for the generated personal repository:
131
+
132
+ ```text
133
+ README.md result.json candidate.json Dockerfile requirements.txt run.py
134
+ autoascend/*.py harness/<custom>/* (only when used)
135
+ ```
136
+
137
+ That is the complete inspectable and reproducible artifact, not a copy of the product's
138
+ internals.
139
+
140
+ ## Evidence
141
+
142
+ NetHack has 73 legal role/race/alignment/gender identities. Effort controls load; the
143
+ objective independently controls which identities count. Self-reported evidence is comparable
144
+ only when objective digests match. Canonical verification remains a separate full-catalog run
145
+ with fixed time effects. Ranking rewards dungeon progress, score, robustness, and ascension
146
+ while penalizing crashes.
147
+
148
+ The bundled AutoAscend root is revision
149
+ `fe3c9a21679d79c1a696987d90c4a6fe87f7c124`. Its historical 1,024-seed score parity is
150
+ tracked separately from runtime health: score parity passes, while the observed crash rate
151
+ remains above the current health threshold and is not represented as a full health pass.
@@ -0,0 +1,57 @@
1
+ [build-system]
2
+ requires = ["setuptools>=75"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "nethackers"
7
+ version = "0.6.22"
8
+ description = "Evolve a shared symbolic NetHack player with Codex or Claude Code"
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = "Apache-2.0"
12
+ authors = [{ name = "NetHackers contributors" }]
13
+ keywords = ["agents", "evolution", "nethack", "autoascend", "gigaevo"]
14
+ dependencies = [
15
+ "rich>=13.9,<15",
16
+ ]
17
+
18
+ [project.urls]
19
+ Homepage = "https://nethackers.dunnolab.ai"
20
+ Repository = "https://github.com/dunnolab/nethackers"
21
+ Documentation = "https://github.com/dunnolab/nethackers/blob/main/SKILL.md"
22
+
23
+ [project.optional-dependencies]
24
+ evaluation = [
25
+ "gymnasium==1.2.0",
26
+ "matplotlib>=3.9,<4",
27
+ "nle==1.3.0",
28
+ "nltk>=3.9,<4",
29
+ "numba>=0.62,<1",
30
+ "numpy>=2.0,<3",
31
+ "opencv-python-headless>=4.10,<5",
32
+ "scipy>=1.14,<2",
33
+ "seaborn>=0.13,<1",
34
+ "toolz>=1.0,<2",
35
+ ]
36
+ dev = [
37
+ "pytest>=8.3,<9",
38
+ "ruff>=0.9,<1",
39
+ ]
40
+
41
+ [project.scripts]
42
+ nethackers = "nethackers.bootstrap:main"
43
+
44
+ [tool.setuptools.packages.find]
45
+ where = ["src"]
46
+
47
+ [tool.pytest.ini_options]
48
+ testpaths = ["tests"]
49
+ addopts = "-q"
50
+
51
+ [tool.ruff]
52
+ line-length = 100
53
+ target-version = "py312"
54
+ exclude = ["roots/autoascend"]
55
+
56
+ [tool.ruff.lint]
57
+ select = ["E", "F", "I", "UP", "B", "SIM"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,6 @@
1
+ """NetHackers distributed symbolic-agent evolution infrastructure."""
2
+
3
+ from nethackers.constants import BASELINE_COMMIT, BASELINE_REPOSITORY
4
+
5
+ __all__ = ["BASELINE_COMMIT", "BASELINE_REPOSITORY"]
6
+ __version__ = "0.6.22"
@@ -0,0 +1,3 @@
1
+ """Generated release pin for the source runtime fetched by the compact wheel."""
2
+
3
+ SOURCE_RUNTIME_DIGEST = "sha256:826b9a11f2fb1aa48bbd5f7e6d940437ba942adef3d112187f434ff96bfa5bd6"