hezgene 1.0.1__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.
- hezgene-1.0.1/LICENSE +21 -0
- hezgene-1.0.1/PKG-INFO +309 -0
- hezgene-1.0.1/README.md +263 -0
- hezgene-1.0.1/pyproject.toml +75 -0
- hezgene-1.0.1/setup.cfg +4 -0
- hezgene-1.0.1/src/hezgene/__init__.py +41 -0
- hezgene-1.0.1/src/hezgene/__main__.py +14 -0
- hezgene-1.0.1/src/hezgene/analysis/__init__.py +0 -0
- hezgene-1.0.1/src/hezgene/analysis/complexity.py +175 -0
- hezgene-1.0.1/src/hezgene/analysis/dependencies.py +74 -0
- hezgene-1.0.1/src/hezgene/analysis/file_ingestor.py +278 -0
- hezgene-1.0.1/src/hezgene/analysis/project_scanner.py +85 -0
- hezgene-1.0.1/src/hezgene/ci_cd/__init__.py +6 -0
- hezgene-1.0.1/src/hezgene/ci_cd/github_actions.py +110 -0
- hezgene-1.0.1/src/hezgene/ci_cd/gitlab_ci.py +67 -0
- hezgene-1.0.1/src/hezgene/cli.py +1545 -0
- hezgene-1.0.1/src/hezgene/core/__init__.py +0 -0
- hezgene-1.0.1/src/hezgene/core/config.py +160 -0
- hezgene-1.0.1/src/hezgene/core/dna_tracker.py +392 -0
- hezgene-1.0.1/src/hezgene/core/engine.py +10 -0
- hezgene-1.0.1/src/hezgene/demo.py +299 -0
- hezgene-1.0.1/src/hezgene/deployment/__init__.py +0 -0
- hezgene-1.0.1/src/hezgene/deployment/deployer.py +187 -0
- hezgene-1.0.1/src/hezgene/engine.py +314 -0
- hezgene-1.0.1/src/hezgene/evaluation/__init__.py +0 -0
- hezgene-1.0.1/src/hezgene/evaluation/gauntlet.py +887 -0
- hezgene-1.0.1/src/hezgene/evaluation/tournament.py +78 -0
- hezgene-1.0.1/src/hezgene/mutation/__init__.py +0 -0
- hezgene-1.0.1/src/hezgene/mutation/ast_mutator.py +445 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/__init__.py +25 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/anthropic_provider.py +112 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/base.py +109 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/factory.py +56 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/gemini_provider.py +112 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/ollama.py +160 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/openai_provider.py +133 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/prompts.py +162 -0
- hezgene-1.0.1/src/hezgene/mutation/llm/venomx_provider.py +100 -0
- hezgene-1.0.1/src/hezgene/mutation/llm_mutator.py +161 -0
- hezgene-1.0.1/src/hezgene/project/__init__.py +1 -0
- hezgene-1.0.1/src/hezgene/project/project_manager.py +410 -0
- hezgene-1.0.1/src/hezgene/web/__init__.py +0 -0
- hezgene-1.0.1/src/hezgene/web/api.py +1008 -0
- hezgene-1.0.1/src/hezgene/web/app.py +63 -0
- hezgene-1.0.1/src/hezgene/web/evolution_worker.py +697 -0
- hezgene-1.0.1/src/hezgene/web/launcher.py +60 -0
- hezgene-1.0.1/src/hezgene/web/models.py +49 -0
- hezgene-1.0.1/src/hezgene/web/websocket.py +47 -0
- hezgene-1.0.1/src/hezgene.egg-info/PKG-INFO +309 -0
- hezgene-1.0.1/src/hezgene.egg-info/SOURCES.txt +52 -0
- hezgene-1.0.1/src/hezgene.egg-info/dependency_links.txt +1 -0
- hezgene-1.0.1/src/hezgene.egg-info/entry_points.txt +3 -0
- hezgene-1.0.1/src/hezgene.egg-info/requires.txt +29 -0
- hezgene-1.0.1/src/hezgene.egg-info/top_level.txt +1 -0
hezgene-1.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hezron Paipai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
hezgene-1.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hezgene
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Autonomous genetic software evolution — code that improves itself
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/TechVenom/HezGene
|
|
7
|
+
Project-URL: Documentation, https://github.com/TechVenom/HezGene/tree/main/docs
|
|
8
|
+
Project-URL: Repository, https://github.com/TechVenom/HezGene.git
|
|
9
|
+
Project-URL: Issues, https://github.com/TechVenom/HezGene/issues
|
|
10
|
+
Keywords: evolution,genetic,self-improving,optimization,autonomous
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: click>=8.0
|
|
22
|
+
Requires-Dist: rich>=13.0
|
|
23
|
+
Requires-Dist: rich-click>=1.7
|
|
24
|
+
Requires-Dist: psutil>=5.9
|
|
25
|
+
Requires-Dist: gitpython>=3.1
|
|
26
|
+
Requires-Dist: ast-comments>=1.2
|
|
27
|
+
Requires-Dist: fastapi>=0.104
|
|
28
|
+
Requires-Dist: uvicorn>=0.23
|
|
29
|
+
Requires-Dist: websockets>=11.0
|
|
30
|
+
Provides-Extra: llm-openai
|
|
31
|
+
Requires-Dist: openai>=1.0; extra == "llm-openai"
|
|
32
|
+
Provides-Extra: llm-anthropic
|
|
33
|
+
Requires-Dist: anthropic>=0.18; extra == "llm-anthropic"
|
|
34
|
+
Provides-Extra: llm-google
|
|
35
|
+
Requires-Dist: google-generativeai>=0.4; extra == "llm-google"
|
|
36
|
+
Provides-Extra: all-llm
|
|
37
|
+
Requires-Dist: openai>=1.0; extra == "all-llm"
|
|
38
|
+
Requires-Dist: anthropic>=0.18; extra == "all-llm"
|
|
39
|
+
Requires-Dist: google-generativeai>=0.4; extra == "all-llm"
|
|
40
|
+
Provides-Extra: dev
|
|
41
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
42
|
+
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
43
|
+
Requires-Dist: ruff>=0.1; extra == "dev"
|
|
44
|
+
Requires-Dist: black>=23.0; extra == "dev"
|
|
45
|
+
Dynamic: license-file
|
|
46
|
+
|
|
47
|
+
# 🧬 HezGene — The DNA of Software
|
|
48
|
+
|
|
49
|
+
<!-- Badge Bar -->
|
|
50
|
+
[](https://pypi.org/project/hezgene/)
|
|
51
|
+
[](https://pypi.org/project/hezgene/)
|
|
52
|
+
[](LICENSE)
|
|
53
|
+
[](https://pypi.org/project/hezgene/)
|
|
54
|
+
[](https://github.com/TechVenom/HezGene)
|
|
55
|
+
|
|
56
|
+

|
|
57
|
+
|
|
58
|
+
*Watch a function evolve from 18 slow lines to 6 optimized lines in 30 seconds — 52% faster, 67% less code.*
|
|
59
|
+
|
|
60
|
+
## Title + One-Liner
|
|
61
|
+
|
|
62
|
+
Type `hezgene run` in your terminal and it evolves your Python code — spawning mutants, testing them in an arena, and saving the winner safely. Your code gets faster, cleaner, and more robust without you touching it.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 🔥 Why HezGene Exists
|
|
67
|
+
|
|
68
|
+
Software rots. Bugs accumulate. Technical debt kills projects. Humans are terrible at maintaining complex systems over time. Every refactor risks breaking things.
|
|
69
|
+
|
|
70
|
+
**The radical idea:** What if code wasn't written by humans and then frozen? What if it was **alive**?
|
|
71
|
+
|
|
72
|
+
HezGene is the first autonomous genetic software evolution platform. Every function has DNA — performance metrics, bug history, complexity scores. HezGene spawns mutant versions, tests them in an arena, and deploys the winner automatically. Your code gets better **without you touching it**.
|
|
73
|
+
|
|
74
|
+
> *"This is our Bitcoin moment. We're not building another app — we're creating a new way software exists."*
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Quick Start (Three Commands)
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
pip install hezgene
|
|
82
|
+
hezgene init
|
|
83
|
+
hezgene run src/
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
That’s it. Your functions now have mutants competing. (By default, winners are written to `.hezgene/sandbox/` — add `--apply` when you want to deploy changes to your source files.)
|
|
87
|
+
|
|
88
|
+
## What You Get
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
.hezgene/
|
|
92
|
+
├── sandbox/ # evolved code (safe — originals untouched)
|
|
93
|
+
├── backups/ # automatic backups before every deployment
|
|
94
|
+
├── dna_registry.json # genetic profiles of every function
|
|
95
|
+
└── history.json # evolution event timeline
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Prerequisites Table
|
|
99
|
+
|
|
100
|
+
| Requirement | Minimum | Check | Install |
|
|
101
|
+
|-------------|---------|-------|---------|
|
|
102
|
+
| Python | 3.10+ | `python --version` | https://python.org |
|
|
103
|
+
| LLM (optional) | Ollama or API key | `ollama list` | https://ollama.com |
|
|
104
|
+
|
|
105
|
+
## Installation (Multiple Methods)
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# Recommended (if you use uv)
|
|
109
|
+
uv tool install hezgene
|
|
110
|
+
|
|
111
|
+
# Alternatives
|
|
112
|
+
pipx install hezgene
|
|
113
|
+
pip install hezgene
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Not currently distributed via Homebrew or winget in this repository. If you maintain a formula/package, PRs are welcome.
|
|
117
|
+
|
|
118
|
+
## Quick Demo
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
hezgene-demo
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
A short terminal walkthrough: original slow code → DNA extracted → mutants spawned → arena fight → winner announced → sandbox output → verification.
|
|
125
|
+
|
|
126
|
+
## Core Workflow (5 Steps)
|
|
127
|
+
|
|
128
|
+
1. **Extract** — Every function gets DNA (speed, memory, complexity, bugs)
|
|
129
|
+
2. **Mutate** — AST strategies + optional LLM mutations
|
|
130
|
+
3. **Evaluate** — 5-Ring Fitness Gauntlet (correctness, speed, memory, edge cases, readability)
|
|
131
|
+
4. **Select** — Tournament manager picks the winner
|
|
132
|
+
5. **Deploy** — Winner replaces original with backup + rollback safety (only with `--apply`)
|
|
133
|
+
|
|
134
|
+
## Common Commands (80/20)
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
hezgene init # Initialize in a project
|
|
138
|
+
hezgene run src/utils.py # Evolve a file (sandbox mode)
|
|
139
|
+
hezgene run src/utils.py:func # Evolve a specific function
|
|
140
|
+
hezgene run --target slowest # Auto-find and evolve worst function
|
|
141
|
+
hezgene run src/ --llm # Include AI-powered mutations
|
|
142
|
+
hezgene run src/utils.py --apply # Deploy directly (not just sandbox)
|
|
143
|
+
hezgene verify # Confirm evolved code matches original
|
|
144
|
+
hezgene dna src/utils.py:func # Show function DNA profile
|
|
145
|
+
hezgene log # View evolution history
|
|
146
|
+
hezgene freeze src/auth.py:verify # Protect critical functions
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## LLM Configuration
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
# Ollama (local)
|
|
153
|
+
hezgene config --set llm.provider ollama
|
|
154
|
+
hezgene config --set llm.model gemma2:2b
|
|
155
|
+
|
|
156
|
+
# OpenAI-compatible
|
|
157
|
+
hezgene config --set llm.provider openai
|
|
158
|
+
hezgene config --set llm.model gpt-4o-mini
|
|
159
|
+
|
|
160
|
+
# Anthropic
|
|
161
|
+
hezgene config --set llm.provider anthropic
|
|
162
|
+
hezgene config --set llm.model claude-sonnet-4-20250514
|
|
163
|
+
|
|
164
|
+
# Gemini
|
|
165
|
+
hezgene config --set llm.provider gemini
|
|
166
|
+
hezgene config --set llm.model gemini-2.5-flash
|
|
167
|
+
|
|
168
|
+
# VENOMX
|
|
169
|
+
hezgene config --set llm.provider venomx
|
|
170
|
+
hezgene config --set llm.model default
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## What HezGene Handles
|
|
174
|
+
|
|
175
|
+
| Type | What | Notes |
|
|
176
|
+
|------|------|-------|
|
|
177
|
+
| Standalone functions | ✅ Evolved | Functions with >2 lines |
|
|
178
|
+
| Class methods | ✅ Evolved | Dunder methods are skipped |
|
|
179
|
+
| Very short functions | ❌ Skipped | “Too short to optimize” |
|
|
180
|
+
| Imports / module-level statements | ❌ Skipped | Never modified directly |
|
|
181
|
+
|
|
182
|
+
## Safety Features
|
|
183
|
+
|
|
184
|
+
- **Sandbox by default** — `hezgene run` never touches original files unless `--apply` is used
|
|
185
|
+
- **Correctness verification** — Every mutant must produce identical outputs
|
|
186
|
+
- **Automatic backups** — Timestamped backup before every deployment
|
|
187
|
+
- **Rollback** — `hezgene rollback <file.py>` restores the most recent backup
|
|
188
|
+
- **Freeze protection** — Critical functions locked from evolution
|
|
189
|
+
- **Minimum improvement threshold** — Only meaningful improvements are deployed
|
|
190
|
+
|
|
191
|
+
## Web Dashboard
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
hezgene ui
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Launches the dashboard at `http://127.0.0.1:8000`. Use `--port` to change the port:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
hezgene ui --port 8080
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## CI/CD Integration
|
|
204
|
+
|
|
205
|
+
GitHub Actions:
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
hezgene ci --github
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
GitLab CI:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
hezgene ci --gitlab
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Privacy
|
|
218
|
+
|
|
219
|
+
- **AST mutations** — Processed locally. Nothing leaves your machine.
|
|
220
|
+
- **LLM mutations** — Only sent to your configured LLM provider when `--llm` is used.
|
|
221
|
+
- **No telemetry** — No usage tracking. No analytics. No phone home.
|
|
222
|
+
|
|
223
|
+
## Troubleshooting
|
|
224
|
+
|
|
225
|
+
| Problem | Fix |
|
|
226
|
+
|---------|-----|
|
|
227
|
+
| `hezgene: command not found` | Use `uv tool install hezgene`, `pipx install hezgene`, or `python -m pip install hezgene` |
|
|
228
|
+
| "No evolvable functions found" | Functions must be >2 lines. Try `hezgene scan <path>` to see what’s detected. |
|
|
229
|
+
| "No mutant beat the original" | Try `--llm` for semantic mutations, or increase generations: `hezgene run <path> -g 10` |
|
|
230
|
+
| LLM connection fails | Run `hezgene status` and verify your provider/model settings |
|
|
231
|
+
| Verification fails | The mutant changed behavior. Use sandbox output or `hezgene rollback <file.py>` if you deployed |
|
|
232
|
+
|
|
233
|
+
## Full Command Reference
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
# Core
|
|
237
|
+
hezgene init # Initialize project
|
|
238
|
+
hezgene scan <path> # Analyze file/directory
|
|
239
|
+
hezgene run <path> # Evolve (sandbox mode)
|
|
240
|
+
hezgene run <path> --apply # Evolve and deploy
|
|
241
|
+
hezgene run <path> --llm # Include AI mutations
|
|
242
|
+
hezgene run --target slowest # Auto-target worst function
|
|
243
|
+
hezgene run --target buggiest # Auto-target most errors
|
|
244
|
+
hezgene run -g 10 # 10 mutant generations
|
|
245
|
+
hezgene verify <path> # Verify correctness
|
|
246
|
+
hezgene log # Evolution history
|
|
247
|
+
|
|
248
|
+
# DNA
|
|
249
|
+
hezgene dna <path>:<function> # Show DNA profile
|
|
250
|
+
hezgene freeze <path>:<function> # Protect from evolution
|
|
251
|
+
hezgene unfreeze <path>:<function> # Resume evolution
|
|
252
|
+
|
|
253
|
+
# Management
|
|
254
|
+
hezgene status # System status
|
|
255
|
+
hezgene config --list # Show settings
|
|
256
|
+
hezgene config --set <key> <value> # Change setting
|
|
257
|
+
hezgene clean # Clear sandbox
|
|
258
|
+
hezgene clean --all # Clear everything
|
|
259
|
+
hezgene rollback <path> # Undo last deployment for a file
|
|
260
|
+
|
|
261
|
+
# Web
|
|
262
|
+
hezgene ui # Launch dashboard
|
|
263
|
+
hezgene ui --port 8080 # Custom port
|
|
264
|
+
|
|
265
|
+
# CI/CD
|
|
266
|
+
hezgene ci --github # Generate GitHub Actions
|
|
267
|
+
hezgene ci --gitlab # Generate GitLab CI
|
|
268
|
+
|
|
269
|
+
# Demo
|
|
270
|
+
hezgene-demo # Terminal demo
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## Environment Variables
|
|
274
|
+
|
|
275
|
+
| Variable | Purpose | Default |
|
|
276
|
+
|----------|---------|---------|
|
|
277
|
+
| `HEZGENE_LLM_PROVIDER` | LLM backend | `ollama` |
|
|
278
|
+
| `HEZGENE_LLM_MODEL` | Model name | config/default |
|
|
279
|
+
| `HEZGENE_API_KEY` | API key (for hosted providers) | empty |
|
|
280
|
+
| `HEZGENE_BASE_URL` | Custom endpoint base URL | provider default |
|
|
281
|
+
| `HEZGENE_MIN_IMPROVEMENT` | Minimum improvement threshold | `0.001` |
|
|
282
|
+
| `HEZGENE_SANDBOX_DIR` | Custom sandbox path | `.hezgene/sandbox/` |
|
|
283
|
+
| `HEZGENE_MAX_GENERATIONS` | Mutants per cycle | `5` |
|
|
284
|
+
| `HEZGENE_NON_INTERACTIVE` | Skip all prompts | `0` |
|
|
285
|
+
|
|
286
|
+
## Contributing
|
|
287
|
+
|
|
288
|
+
HezGene is open source (MIT). Contributions welcome.
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
git clone https://github.com/TechVenom/HezGene.git
|
|
292
|
+
cd HezGene
|
|
293
|
+
pip install -e ".[dev]"
|
|
294
|
+
pytest
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## License
|
|
298
|
+
|
|
299
|
+
MIT — free for personal and commercial use.
|
|
300
|
+
|
|
301
|
+
## Author
|
|
302
|
+
|
|
303
|
+
**Hezron Paipai** — System Engineer & AI Architect
|
|
304
|
+
GitHub: https://github.com/TechVenom
|
|
305
|
+
Email: venomx.agent.future@proton.me
|
|
306
|
+
|
|
307
|
+
## Star History
|
|
308
|
+
|
|
309
|
+
[](https://star-history.com/#TechVenom/HezGene&Date)
|
hezgene-1.0.1/README.md
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# 🧬 HezGene — The DNA of Software
|
|
2
|
+
|
|
3
|
+
<!-- Badge Bar -->
|
|
4
|
+
[](https://pypi.org/project/hezgene/)
|
|
5
|
+
[](https://pypi.org/project/hezgene/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://pypi.org/project/hezgene/)
|
|
8
|
+
[](https://github.com/TechVenom/HezGene)
|
|
9
|
+
|
|
10
|
+

|
|
11
|
+
|
|
12
|
+
*Watch a function evolve from 18 slow lines to 6 optimized lines in 30 seconds — 52% faster, 67% less code.*
|
|
13
|
+
|
|
14
|
+
## Title + One-Liner
|
|
15
|
+
|
|
16
|
+
Type `hezgene run` in your terminal and it evolves your Python code — spawning mutants, testing them in an arena, and saving the winner safely. Your code gets faster, cleaner, and more robust without you touching it.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 🔥 Why HezGene Exists
|
|
21
|
+
|
|
22
|
+
Software rots. Bugs accumulate. Technical debt kills projects. Humans are terrible at maintaining complex systems over time. Every refactor risks breaking things.
|
|
23
|
+
|
|
24
|
+
**The radical idea:** What if code wasn't written by humans and then frozen? What if it was **alive**?
|
|
25
|
+
|
|
26
|
+
HezGene is the first autonomous genetic software evolution platform. Every function has DNA — performance metrics, bug history, complexity scores. HezGene spawns mutant versions, tests them in an arena, and deploys the winner automatically. Your code gets better **without you touching it**.
|
|
27
|
+
|
|
28
|
+
> *"This is our Bitcoin moment. We're not building another app — we're creating a new way software exists."*
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Quick Start (Three Commands)
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install hezgene
|
|
36
|
+
hezgene init
|
|
37
|
+
hezgene run src/
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
That’s it. Your functions now have mutants competing. (By default, winners are written to `.hezgene/sandbox/` — add `--apply` when you want to deploy changes to your source files.)
|
|
41
|
+
|
|
42
|
+
## What You Get
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
.hezgene/
|
|
46
|
+
├── sandbox/ # evolved code (safe — originals untouched)
|
|
47
|
+
├── backups/ # automatic backups before every deployment
|
|
48
|
+
├── dna_registry.json # genetic profiles of every function
|
|
49
|
+
└── history.json # evolution event timeline
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Prerequisites Table
|
|
53
|
+
|
|
54
|
+
| Requirement | Minimum | Check | Install |
|
|
55
|
+
|-------------|---------|-------|---------|
|
|
56
|
+
| Python | 3.10+ | `python --version` | https://python.org |
|
|
57
|
+
| LLM (optional) | Ollama or API key | `ollama list` | https://ollama.com |
|
|
58
|
+
|
|
59
|
+
## Installation (Multiple Methods)
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# Recommended (if you use uv)
|
|
63
|
+
uv tool install hezgene
|
|
64
|
+
|
|
65
|
+
# Alternatives
|
|
66
|
+
pipx install hezgene
|
|
67
|
+
pip install hezgene
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Not currently distributed via Homebrew or winget in this repository. If you maintain a formula/package, PRs are welcome.
|
|
71
|
+
|
|
72
|
+
## Quick Demo
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
hezgene-demo
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
A short terminal walkthrough: original slow code → DNA extracted → mutants spawned → arena fight → winner announced → sandbox output → verification.
|
|
79
|
+
|
|
80
|
+
## Core Workflow (5 Steps)
|
|
81
|
+
|
|
82
|
+
1. **Extract** — Every function gets DNA (speed, memory, complexity, bugs)
|
|
83
|
+
2. **Mutate** — AST strategies + optional LLM mutations
|
|
84
|
+
3. **Evaluate** — 5-Ring Fitness Gauntlet (correctness, speed, memory, edge cases, readability)
|
|
85
|
+
4. **Select** — Tournament manager picks the winner
|
|
86
|
+
5. **Deploy** — Winner replaces original with backup + rollback safety (only with `--apply`)
|
|
87
|
+
|
|
88
|
+
## Common Commands (80/20)
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
hezgene init # Initialize in a project
|
|
92
|
+
hezgene run src/utils.py # Evolve a file (sandbox mode)
|
|
93
|
+
hezgene run src/utils.py:func # Evolve a specific function
|
|
94
|
+
hezgene run --target slowest # Auto-find and evolve worst function
|
|
95
|
+
hezgene run src/ --llm # Include AI-powered mutations
|
|
96
|
+
hezgene run src/utils.py --apply # Deploy directly (not just sandbox)
|
|
97
|
+
hezgene verify # Confirm evolved code matches original
|
|
98
|
+
hezgene dna src/utils.py:func # Show function DNA profile
|
|
99
|
+
hezgene log # View evolution history
|
|
100
|
+
hezgene freeze src/auth.py:verify # Protect critical functions
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## LLM Configuration
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
# Ollama (local)
|
|
107
|
+
hezgene config --set llm.provider ollama
|
|
108
|
+
hezgene config --set llm.model gemma2:2b
|
|
109
|
+
|
|
110
|
+
# OpenAI-compatible
|
|
111
|
+
hezgene config --set llm.provider openai
|
|
112
|
+
hezgene config --set llm.model gpt-4o-mini
|
|
113
|
+
|
|
114
|
+
# Anthropic
|
|
115
|
+
hezgene config --set llm.provider anthropic
|
|
116
|
+
hezgene config --set llm.model claude-sonnet-4-20250514
|
|
117
|
+
|
|
118
|
+
# Gemini
|
|
119
|
+
hezgene config --set llm.provider gemini
|
|
120
|
+
hezgene config --set llm.model gemini-2.5-flash
|
|
121
|
+
|
|
122
|
+
# VENOMX
|
|
123
|
+
hezgene config --set llm.provider venomx
|
|
124
|
+
hezgene config --set llm.model default
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## What HezGene Handles
|
|
128
|
+
|
|
129
|
+
| Type | What | Notes |
|
|
130
|
+
|------|------|-------|
|
|
131
|
+
| Standalone functions | ✅ Evolved | Functions with >2 lines |
|
|
132
|
+
| Class methods | ✅ Evolved | Dunder methods are skipped |
|
|
133
|
+
| Very short functions | ❌ Skipped | “Too short to optimize” |
|
|
134
|
+
| Imports / module-level statements | ❌ Skipped | Never modified directly |
|
|
135
|
+
|
|
136
|
+
## Safety Features
|
|
137
|
+
|
|
138
|
+
- **Sandbox by default** — `hezgene run` never touches original files unless `--apply` is used
|
|
139
|
+
- **Correctness verification** — Every mutant must produce identical outputs
|
|
140
|
+
- **Automatic backups** — Timestamped backup before every deployment
|
|
141
|
+
- **Rollback** — `hezgene rollback <file.py>` restores the most recent backup
|
|
142
|
+
- **Freeze protection** — Critical functions locked from evolution
|
|
143
|
+
- **Minimum improvement threshold** — Only meaningful improvements are deployed
|
|
144
|
+
|
|
145
|
+
## Web Dashboard
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
hezgene ui
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Launches the dashboard at `http://127.0.0.1:8000`. Use `--port` to change the port:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
hezgene ui --port 8080
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## CI/CD Integration
|
|
158
|
+
|
|
159
|
+
GitHub Actions:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
hezgene ci --github
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
GitLab CI:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
hezgene ci --gitlab
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Privacy
|
|
172
|
+
|
|
173
|
+
- **AST mutations** — Processed locally. Nothing leaves your machine.
|
|
174
|
+
- **LLM mutations** — Only sent to your configured LLM provider when `--llm` is used.
|
|
175
|
+
- **No telemetry** — No usage tracking. No analytics. No phone home.
|
|
176
|
+
|
|
177
|
+
## Troubleshooting
|
|
178
|
+
|
|
179
|
+
| Problem | Fix |
|
|
180
|
+
|---------|-----|
|
|
181
|
+
| `hezgene: command not found` | Use `uv tool install hezgene`, `pipx install hezgene`, or `python -m pip install hezgene` |
|
|
182
|
+
| "No evolvable functions found" | Functions must be >2 lines. Try `hezgene scan <path>` to see what’s detected. |
|
|
183
|
+
| "No mutant beat the original" | Try `--llm` for semantic mutations, or increase generations: `hezgene run <path> -g 10` |
|
|
184
|
+
| LLM connection fails | Run `hezgene status` and verify your provider/model settings |
|
|
185
|
+
| Verification fails | The mutant changed behavior. Use sandbox output or `hezgene rollback <file.py>` if you deployed |
|
|
186
|
+
|
|
187
|
+
## Full Command Reference
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
# Core
|
|
191
|
+
hezgene init # Initialize project
|
|
192
|
+
hezgene scan <path> # Analyze file/directory
|
|
193
|
+
hezgene run <path> # Evolve (sandbox mode)
|
|
194
|
+
hezgene run <path> --apply # Evolve and deploy
|
|
195
|
+
hezgene run <path> --llm # Include AI mutations
|
|
196
|
+
hezgene run --target slowest # Auto-target worst function
|
|
197
|
+
hezgene run --target buggiest # Auto-target most errors
|
|
198
|
+
hezgene run -g 10 # 10 mutant generations
|
|
199
|
+
hezgene verify <path> # Verify correctness
|
|
200
|
+
hezgene log # Evolution history
|
|
201
|
+
|
|
202
|
+
# DNA
|
|
203
|
+
hezgene dna <path>:<function> # Show DNA profile
|
|
204
|
+
hezgene freeze <path>:<function> # Protect from evolution
|
|
205
|
+
hezgene unfreeze <path>:<function> # Resume evolution
|
|
206
|
+
|
|
207
|
+
# Management
|
|
208
|
+
hezgene status # System status
|
|
209
|
+
hezgene config --list # Show settings
|
|
210
|
+
hezgene config --set <key> <value> # Change setting
|
|
211
|
+
hezgene clean # Clear sandbox
|
|
212
|
+
hezgene clean --all # Clear everything
|
|
213
|
+
hezgene rollback <path> # Undo last deployment for a file
|
|
214
|
+
|
|
215
|
+
# Web
|
|
216
|
+
hezgene ui # Launch dashboard
|
|
217
|
+
hezgene ui --port 8080 # Custom port
|
|
218
|
+
|
|
219
|
+
# CI/CD
|
|
220
|
+
hezgene ci --github # Generate GitHub Actions
|
|
221
|
+
hezgene ci --gitlab # Generate GitLab CI
|
|
222
|
+
|
|
223
|
+
# Demo
|
|
224
|
+
hezgene-demo # Terminal demo
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## Environment Variables
|
|
228
|
+
|
|
229
|
+
| Variable | Purpose | Default |
|
|
230
|
+
|----------|---------|---------|
|
|
231
|
+
| `HEZGENE_LLM_PROVIDER` | LLM backend | `ollama` |
|
|
232
|
+
| `HEZGENE_LLM_MODEL` | Model name | config/default |
|
|
233
|
+
| `HEZGENE_API_KEY` | API key (for hosted providers) | empty |
|
|
234
|
+
| `HEZGENE_BASE_URL` | Custom endpoint base URL | provider default |
|
|
235
|
+
| `HEZGENE_MIN_IMPROVEMENT` | Minimum improvement threshold | `0.001` |
|
|
236
|
+
| `HEZGENE_SANDBOX_DIR` | Custom sandbox path | `.hezgene/sandbox/` |
|
|
237
|
+
| `HEZGENE_MAX_GENERATIONS` | Mutants per cycle | `5` |
|
|
238
|
+
| `HEZGENE_NON_INTERACTIVE` | Skip all prompts | `0` |
|
|
239
|
+
|
|
240
|
+
## Contributing
|
|
241
|
+
|
|
242
|
+
HezGene is open source (MIT). Contributions welcome.
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
git clone https://github.com/TechVenom/HezGene.git
|
|
246
|
+
cd HezGene
|
|
247
|
+
pip install -e ".[dev]"
|
|
248
|
+
pytest
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
## License
|
|
252
|
+
|
|
253
|
+
MIT — free for personal and commercial use.
|
|
254
|
+
|
|
255
|
+
## Author
|
|
256
|
+
|
|
257
|
+
**Hezron Paipai** — System Engineer & AI Architect
|
|
258
|
+
GitHub: https://github.com/TechVenom
|
|
259
|
+
Email: venomx.agent.future@proton.me
|
|
260
|
+
|
|
261
|
+
## Star History
|
|
262
|
+
|
|
263
|
+
[](https://star-history.com/#TechVenom/HezGene&Date)
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "hezgene"
|
|
7
|
+
version = "1.0.1"
|
|
8
|
+
description = "Autonomous genetic software evolution — code that improves itself"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = {text = "MIT"}
|
|
11
|
+
keywords = ["evolution", "genetic", "self-improving", "optimization", "autonomous"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 4 - Beta",
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"License :: OSI Approved :: MIT License",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.10",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.14",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"click>=8.0",
|
|
24
|
+
"rich>=13.0",
|
|
25
|
+
"rich-click>=1.7",
|
|
26
|
+
"psutil>=5.9",
|
|
27
|
+
"gitpython>=3.1",
|
|
28
|
+
"ast-comments>=1.2",
|
|
29
|
+
"fastapi>=0.104",
|
|
30
|
+
"uvicorn>=0.23",
|
|
31
|
+
"websockets>=11.0",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
llm-openai = ["openai>=1.0"]
|
|
36
|
+
llm-anthropic = ["anthropic>=0.18"]
|
|
37
|
+
llm-google = ["google-generativeai>=0.4"]
|
|
38
|
+
all-llm = [
|
|
39
|
+
"openai>=1.0",
|
|
40
|
+
"anthropic>=0.18",
|
|
41
|
+
"google-generativeai>=0.4",
|
|
42
|
+
]
|
|
43
|
+
dev = [
|
|
44
|
+
"pytest>=7.0",
|
|
45
|
+
"pytest-cov>=4.0",
|
|
46
|
+
"ruff>=0.1",
|
|
47
|
+
"black>=23.0",
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
[project.scripts]
|
|
51
|
+
hezgene = "hezgene.cli:main"
|
|
52
|
+
hezgene-demo = "hezgene.demo:main"
|
|
53
|
+
|
|
54
|
+
[project.urls]
|
|
55
|
+
Homepage = "https://github.com/TechVenom/HezGene"
|
|
56
|
+
Documentation = "https://github.com/TechVenom/HezGene/tree/main/docs"
|
|
57
|
+
Repository = "https://github.com/TechVenom/HezGene.git"
|
|
58
|
+
Issues = "https://github.com/TechVenom/HezGene/issues"
|
|
59
|
+
|
|
60
|
+
[tool.setuptools]
|
|
61
|
+
package-dir = {"" = "src"}
|
|
62
|
+
|
|
63
|
+
[tool.setuptools.packages.find]
|
|
64
|
+
where = ["src"]
|
|
65
|
+
|
|
66
|
+
[tool.ruff]
|
|
67
|
+
target-version = "py310"
|
|
68
|
+
line-length = 100
|
|
69
|
+
|
|
70
|
+
[tool.ruff.lint]
|
|
71
|
+
select = ["E", "F", "I", "N", "W", "UP"]
|
|
72
|
+
|
|
73
|
+
[tool.pytest.ini_options]
|
|
74
|
+
testpaths = ["tests"]
|
|
75
|
+
pythonpath = ["src"]
|
hezgene-1.0.1/setup.cfg
ADDED