REGENESIS

Research platform for long-horizon autonomous civilization survival under stochastic pressure.

One agent. One place on Earth. Survive or vanish.

Why this project exists
Research question
What REGENESIS is (and is not)
Feature matrix
Screenshots
Quick start
System requirements
Installation
Running a simulation
Interactive menu
Command-line reference
Live visualization & offline archive
World model
Agent architecture
Technology system
Assets & modular catalogs
Memory, policy & learning
Train mode (Phase 22)
Experimental toolkit
Determinism, seeds & validity
Checkpoints & resume
Metrics & outputs
Phase roadmap
Repository layout
Tests & continuous integration
Reproducibility guide for papers / thesis
Design principles
Limitations (read this)
Ethics & dual-use note
Portfolio / admissions framing
Troubleshooting
FAQ
Contributing
License & citation
Appendix A — Full CLI cheat sheet
Appendix B — Output files
Appendix C — Stress protocols
Appendix D — Glossary
Appendix E — Suggested experiments
Appendix F — Changelog (high level)

1. Why this project exists

Most “AI agent” demos optimize short-horizon rewards in clean environments. Real survival—historical or post-catastrophe—is the opposite:

Long horizons (months to years of simulated days)
Partial information and noisy weather
Irreversible failure (extinction)
Coupled systems: food, water, population, technology, culture, disasters
Path dependence: early mistakes compound

REGENESIS exists to study whether structured memory, self-evaluation, experimentation, and external knowledge intake can improve long-horizon survival decisions in a reproducible simulator.

It is intended as a research instrument, not a commercial game.

2. Research question

Primary question:

Can an autonomous agent improve its decision-making capabilities through long-horizon experience, memory, experimentation, research, and self-evaluation?

Secondary questions the platform can support:

How do climate regimes (arid, cold, tropical, temperate) change survival distributions?
Do technology unlocks causally improve food stability (A/B tests)?
Does increasing a learned food_bias policy parameter improve survival vs a matched control?
Are runs replay-equivalent under a fixed master seed?
Can external textual knowledge (train mode) be converted into soft policy hints without rewriting core code?

3. What REGENESIS is (and is not)

Is

A seed-deterministic simulation platform
A daily-step agent–environment loop
A suite of experimental tools (batteries, counterfactuals, stress protocols)
A visualization of long runs (live + archival HTML)
A portfolio-grade research codebase with tests and CI

Is not

A claim of AGI or “solved” self-improvement
A full multiplayer world or AAA game
A guarantee of historical accuracy for every country-year
A system that autonomously rewrites its own source code (train mode deliberately avoids that)

Honesty is part of the scientific value. Over-claiming would destroy that value.

4. Feature matrix

Area	Status	Notes
Random start location + calendar offset	Implemented	Seed-deterministic
Master seed + named RNG streams	Implemented	Core validity requirement
Climate continuum (not binary)	Implemented	Aridity index + weather
Disasters / events / groups	Implemented	Country hazard weights
Population births/deaths/joins	Implemented	Dynamic, not fixed 20–25
Agriculture / hunting catalogs	Implemented	Country/climate filtered
Tech graph + production effects	Implemented	Multipliers on forage/farm/hunt/water/spoil
Rule agent + crisis focus	Implemented	Food/water/infra priorities
Memory lessons → policy biases	Implemented	Phase 19 cognitive closure
Bandit over focus actions	Implemented	Deterministic when using sim RNG
Counterfactual sketches	Implemented	Per-step alternatives
Train mode → policy hints	Implemented	Continuous until Ctrl+C
Live HTTP canvas	Implemented	Polls `state.json`
Offline `canvas_final.html`	Implemented	Survives server shutdown
100-seed experimental battery	Implemented	CSV + Markdown + HTML
Learning-curve experiment	Implemented	food_bias 0 vs 0.8 by climate
Tech A/B	Implemented	`--tech-ab`
Stress protocols	Implemented	`--stress`
Metrology lab	Implemented	`--lab`
Run comparison dashboard	Implemented	`--compare`
Replay-equivalence tests	Implemented	pytest + CI
Multi-settlement (outposts)	Lightweight	Phase 23 starter
Full AGI self-modify	Not a goal	Explicit non-goal

5. Screenshots

Place images in screenshots/ at the repository root. Suggested names:

File	Description
`screenshots/live_canvas.png`	Live expanding diary during a run
`screenshots/final_archive.png`	Offline `canvas_final.html` after completion
`screenshots/menu.png`	Interactive launcher menu
`screenshots/arid_run.png`	Arid climate pressure example
`screenshots/battery_report.png`	Battery HTML report (optional)

Example Markdown (after you add files):

![Live canvas](screenshots/live_canvas.png)
![Final archive](screenshots/final_archive.png)

If a screenshot is missing, the rest of the documentation remains valid.

6. Quick start

# Clone
git clone https://github.com/morteza323/REGENESIS.git
cd REGENESIS

# Optional virtual environment
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

pip install -r requirements.txt

# Interactive
python main.py --menu

# Or one-shot
python main.py --days 90 --fresh --seed 42

Windows double-click: start.bat
Unix: bash start.sh

7. System requirements

Python 3.10+ (3.11 recommended; CI uses 3.11)
OS: Windows, Linux, or macOS
Dependencies: standard library for core simulation; pytest for tests
Browser: any modern browser for live canvas (http://127.0.0.1:PORT/canvas.html)
Disk: small; long batteries write CSV/HTML under storage/experiments/

No GPU required. No paid API required for core runs.

8. Installation

8.1 From source

git clone https://github.com/morteza323/REGENESIS.git
cd REGENESIS
pip install -r requirements.txt
python main.py --help

8.2 Verify install

python main.py --replay-check --seed 42 --days 15
pytest tests/test_smoke_simulation.py tests/test_replay_equivalence.py -q

Expected: replay reports equivalent: True; pytest passes.

9. Running a simulation

9.1 Minimal

python main.py --days 90 --fresh

9.2 Reproducible

python main.py --days 90 --fresh --seed 85829

Same seed ⇒ same world lineage (see Determinism).

9.3 Fast mode

python main.py --days 365 --fresh --fast --seed 42

9.4 What happens each day

Observe world state (food, water, population, events, …)
Decide action / focus (rules + policy biases + optional bandit)
Act (labor allocation effects)
Environment (weather, production, spoilage, disasters, groups)
Population update (births, deaths, joins)
Technology research tick
Commit clock advance; write metrics / canvas state
Cognition log (prediction, reflection hooks, counterfactual sketch)

Extinction ends the run early. Survival to --days writes a finished archive.

10. Interactive menu

[1] Natural run      — fully random world; choose duration
[2] Custom run       — seed, country, climate, death-rule toggles
[3] Continue checkpoint
[4] Train mode       — continuous research loop (Ctrl+C to pause)
[5] Settings         — saved in storage/settings.json
[6] Exit

Settings persist default day counts, fast mode preference, and optional extinction toggles for controlled experiments.

11. Command-line reference

11.1 Core simulation

Flag	Meaning
`--days N`	Simulated days (default depends on path)
`--seed N`	Master seed
`--fresh`	Do not resume; new run
`--continue-run`	Resume checkpoint
`--fast`	Minimal delay
`--delay SEC`	Per-day delay
`--menu`	Force interactive menu
`--stress NAME`	Stress protocol (see Appendix C)

11.2 Research / experiments

Flag	Meaning
`--replay-check`	Replay-equivalence validity test
`--battery100`	Large seed × climate battery
`--n-seeds N`	Seed count for battery / learning curve
`--learning-curve`	food_bias 0 vs 0.8 by climate
`--tech-ab "Name"`	Causal A/B for a technology
`--counterfactual`	Control vs intervention branch
`--intervention X`	Intervention type for CF
`--lab`	Metrology lab table
`--compare RUN_A RUN_B`	HTML comparison dashboard
`--train`	Continuous train until Ctrl+C
`--train-once`	Single train round
`--no-web`	Train using local corpus only

12. Live visualization & offline archive

12.1 Live

During a run the engine may start a local HTTP server serving the run directory. The browser page polls state.json (not a full page reload every frame) so the diary updates without white flashes.

Typical URL:

http://127.0.0.1:8765/canvas.html

12.2 Diary geometry

Each day paints one cell of a solid growing square:

side = ceil(sqrt(n_days_painted))
cells fill in contiguous row-major order
day 1 = single small center tile (not a full-screen slab)

12.3 Offline archive (critical)

Every run should produce:

storage/runs/<run_id>/canvas.html        # working mirror
storage/runs/<run_id>/canvas_final.html  # durable snapshot
storage/runs/<run_id>/state.json
storage/runs/<run_id>/state_final.json
storage/runs/<run_id>/canvas_debug.log

If the live server stops when the process exits, open canvas_final.html via file browser. That file embeds the final state and does not require localhost.

12.4 Debug log

canvas_debug.log records pixel counts per save — useful if the live view and archive ever diverge.

13. World model

13.1 Space & time

Random (seeded) geographic start; country/climate metadata
Calendar offset so “day 1 of the run” is not always January 1
Seasons affect production

13.2 Climate

Continuous aridity and temperature effects—not a single binary desert flag. Arid and cold regimes have soft floors so early death is possible but not guaranteed instant zero resources.

13.3 Resources

Food: forage + farm + hunt − consumption − spoilage
Water: climate/rain/tech modulated
Materials: exploration / salvage influenced

Tech multipliers and modular asset biases stack on top of base formulas (core/economy/formulas.py, core/simulation/tick.py).

13.4 Population

Births under surplus; deaths under starvation/thirst/disease/raid pressure; joins from group encounters; optional outpost founding when population and stores allow.

13.5 Events & hazards

Event templates weighted by type and country hazard coefficients (assets/23_country_hazards.txt) so, for example, earthquake weight is higher in some regions than others.

14. Agent architecture

World state
    ↓
Observe
    ↓
Policy thresholds (Phase 19 biases)
    ↓
Rule decision (crisis food/water vs routine)
    ↓
Optional bandit overlay (non-crisis)
    ↓
Action string → labor / focus effects
    ↓
Environment resolution
    ↓
Memory lessons + reflection hooks

14.1 Decision outputs (examples)

food_conservation
water_conservation
material_collection
infrastructure

14.2 Where “intelligence” lives

Layer	Role
Rules	Hard survival priorities
PolicyState	Slow-moving biases from lessons
Bandit	Online adaptation of focus
Train hints	Soft priors from external text
Counterfactuals	Logged alternatives for analysis

There is no hidden cloud model required for a standard run.

15. Technology system

Large procedural / file-driven tech graph
Research progresses over days when conditions allow
Unlocks apply numeric multipliers (forage, farm, hunt, water, spoil, research speed)

Causal testing:

python main.py --tech-ab "Cooking" --days 40

Compare control vs treatment arms in storage/experiments/tech_ab/.

16. Assets & modular catalogs

Dozens of assets/*.txt catalogs (planting, hunting, norms, hazards, labor policies, …). Entries use:

=== ID:0001 ===
Name: ...
...

Loaded through parsers / AssetRegistry patterns so new tables can influence runs without rewriting the entire engine.

Design rule: prefer new data + small hooks over invasive rewrites.

17. Memory, policy & learning

17.1 Lessons

Tagged memories (food stress, drought, etc.) accumulate in world memory.

17.2 Policy closure (Phase 19)

core/cognition/policy.py revises:

food_bias
water_bias
explore_bias
infrastructure_bias

These adjust crisis thresholds in the agent.

17.3 Bandit

Epsilon-greedy focus selection with updates from day-to-day food/water deltas. Uses the simulation RNG stream (not Python’s global random) so experiments stay seed-stable.

17.4 Learning-curve experiment

python main.py --learning-curve --days 35 --n-seeds 8

Forces food_bias ∈ {0.0, 0.8} across climates and reports survival deltas in Markdown/HTML.

18. Train mode (Phase 22)

Train mode reads local corpus files under knowledge/train_corpus/ and optionally public web pages, extracts heuristic claims, aggregates policy scores, and writes:

storage/train_result/train_<timestamp>.json
storage/train_result/latest_policy_hints.json
storage/train_logs/seen_sources.json
storage/train_logs/train_<timestamp>.log

Important properties

Continuous until Ctrl+C (--train or menu [4])
Idempotent sources via seen_sources.json
Never modifies core/ source files automatically
Hints may be applied as mild policy biases at run start

python main.py --train --no-web    # offline corpus only
python main.py --train             # corpus + web attempts
python main.py --train-once

19. Experimental toolkit

19.1 100-seed battery

python main.py --battery100 --days 40 --n-seeds 100

Produces under storage/experiments/battery_100/:

battery_100.csv
battery_100.md
battery_100.html
battery_100.json

Includes survival by climate and observational splits on food_bias.

For a dry run on a laptop:

python main.py --battery100 --days 25 --n-seeds 12

19.2 Counterfactuals

python main.py --counterfactual --seed 42 --days 40 --intervention gift_food

Interventions include: gift_food, gift_water, force_food_focus, force_water_focus, unlock_fire.

19.3 Metrology lab

python main.py --lab --days 40

19.4 Compare two runs

python main.py --compare run_2026_09_01_42 run_2026_09_01_99

Builds an HTML sparkline dashboard from each run’s metrics.csv.

19.5 Stress protocols

See Appendix C.

20. Determinism, seeds & validity

20.1 Master seed

All stochasticity should flow from the master seed through named streams (weather, events, agent, …).

20.2 Replay-equivalence

python main.py --replay-check --seed 42 --days 30

Or:

pytest tests/test_replay_equivalence.py -q

Two fresh engines with the same seed must produce matching series of (pop, food, water, tech_count) for the tested horizon.

20.3 What breaks determinism

Using Python’s global random in the step path
Wall-clock timestamps inside decision logic
Unordered set iteration in numeric-critical code without sorting
Loading leftover canvas state into a “fresh” run (mitigated on resume=False)

21. Checkpoints & resume

Ctrl+C saves checkpoint + attempts metrics/canvas archive
Menu option [3] continues
CLI: --continue-run

Checkpoints are designed to restore world + clock so long experiments can pause safely.

22. Metrics & outputs

Per run directory (storage/runs/<run_id>/):

File	Purpose
`metrics.csv`	Day-level panel data
`metrics_summary.json`	Summary + cognitive/counterfactual tails
`run_log.txt`	Text log lines
`canvas_final.html`	Archival visualization
`state.json` / `state_final.json`	Machine-readable diary state
`checkpoint.json`	Resume payload
`manifest.json`	Run identity metadata

Experiment aggregates: storage/experiments/**.

23. Phase roadmap

Phase	Theme	State
1–16	World systems foundation	Legacy / present
17	Architecture, seeds, checkpoint	Done
18	Research survival platform, canvas, assets	Done
19	Cognitive closure (policy from lessons)	Done
20	Metrology lab	Done
21	Counterfactual engine	Done
22	Autonomous research / train	Done (heuristic)
23	Multi-settlement corridors	Lightweight
24	Culture–tech–pop coevolution metrics	Lightweight
25	Adversarial stress protocols	Done
26	Human-in-the-loop experiment UI	Future
27	Public research release pack	Future / this release starts it

Details: PHASES.md.

24. Repository layout

REGENESIS/
├── main.py                 # CLI + menu entry
├── config.py
├── version.py
├── start.bat / start.sh
├── requirements.txt
├── LICENSE
├── README.md               # this file
├── PHASES.md
├── ai/                     # agent, bandit hooks, optional LLM stubs
├── assets/                 # modular txt catalogs
├── core/
│   ├── simulation/         # engine, day, tick
│   ├── cognition/          # policy, loop, bandit
│   ├── experiments/        # battery, replay, A/B, compare
│   ├── train/              # train pipeline
│   ├── metrology/
│   ├── counterfactual/
│   ├── settlements/
│   ├── stress/
│   ├── visualization/      # canvas + live server
│   └── ...
├── knowledge/train_corpus/ # offline train text
├── tests/
├── phases/                 # phase notes
├── screenshots/            # optional images for GitHub
├── storage/                # runs, experiments, settings (often gitignored)
└── .github/workflows/ci.yml

25. Tests & continuous integration

pytest tests/test_replay_equivalence.py tests/test_smoke_simulation.py -q
python main.py --help

GitHub Actions (.github/workflows/ci.yml) runs on push/PR:

Install pytest
Run replay + smoke tests
Show CLI help

26. Reproducibility guide for papers / thesis

Publish the commit hash and version.py.
Report master seeds for every figure.
Report days cap, stress protocol, and intervention names.
Attach battery_*.csv or learning-curve tables.
State limitations (prototype agent, heuristic train, simplified ecology).
Prefer medians/IQRs across seeds, not single-run storytelling.

Example methods sentence:

Simulations were run with REGENESIS v1.0.0 under fixed master seeds. Each climate cell used the published seed list. Survival is the fraction of runs with positive population at the day cap. Replay-equivalence tests verified deterministic re-execution for the analysis horizon.

27. Design principles

Determinism before spectacle
Never delete working capabilities for stylistic rewrites
Data-modular assets over hard-coded special cases
Train must not edit core code
Offline archival truth (canvas_final) independent of live sockets
Honest claims in README and papers

28. Limitations (read this)

Ecology and culture are stylized, not GIS-validated reconstructions
Train extraction is keyword/heuristic, not scholarly NLP
Outposts are lightweight, not full multi-city economies
Balance is improved for arid/cold but not “solved” for all edge seeds
Long batteries are CPU-time expensive
Visualization is an analytic diary, not a photoreal map

These limits are intentional trade-offs for a clear research kernel.

29. Ethics & dual-use note

REGENESIS models abstract survival pressure for science and education. It is not intended to plan real harm or real-world disaster exploitation. Country hazard tables are coarse educational weights, not operational risk products.

30. Portfolio / admissions framing

Suitable bullet examples (keep them accurate):

Built a seed-deterministic long-horizon agent–environment research simulator in Python
Implemented experimental tooling: multi-seed batteries, tech A/B, counterfactual interventions, replay tests
Designed a policy-closure loop where episodic lessons adjust decision thresholds
Delivered reproducible artifacts (CSV/JSON/HTML) and CI-backed validity checks

Avoid:

“Fully autonomous self-improving AGI”
“Predicts real disasters accurately”
“Replaces climate science models”

31. Troubleshooting

Symptom	Likely cause	Fix
Browser: connection refused	Process ended; live server stopped	Open `canvas_final.html`
Live diary stuck early	Stale tab / old JS	Hard refresh; update to latest commit
`file://` has no live poll	Browser security	Use live HTTP during run; archive after
Replay false	Dirty state / old build	Pull latest; `resume=False` resets canvas
Train menu looks empty	One-shot confusion	Use continuous train; Ctrl+C to stop
Battery too slow	100×4×days	Lower `--n-seeds` / `--days`

32. FAQ

Q: Is this a game?
A: Game-like presentation, research-first purpose.

Q: Do I need an API key?
A: No for core simulation.

Q: Can I publish results?
A: Yes—cite the repo, commit, seeds, and limitations.

Q: Why solid square not spiral?
A: Spiral left visual holes; solid growing square reads as a completing painting and stays stable in live/archive modes.

Q: Does train change the engine code?
A: No. It only writes data under storage/train_result/.

33. Contributing

Keep changes seed-safe
Add/adjust tests for validity-sensitive code
Prefer asset tables + small hooks
Do not force network calls into the default smoke path
Open issues/PRs with seeds and short logs

34. License & citation

MIT License — see LICENSE.

REGENESIS — Long-horizon autonomous survival simulation platform, v1.0.0 (2026).
https://github.com/morteza323/REGENESIS

Appendix A — Full CLI cheat sheet

python main.py --menu
python main.py --days 90 --fresh --seed 42
python main.py --days 365 --fresh --fast --seed 7
python main.py --continue-run
python main.py --replay-check --seed 42 --days 30
python main.py --battery100 --days 40 --n-seeds 100
python main.py --battery100 --days 25 --n-seeds 12
python main.py --learning-curve --days 35 --n-seeds 8
python main.py --tech-ab "Cooking" --days 40
python main.py --counterfactual --seed 42 --days 40 --intervention gift_food
python main.py --lab --days 40
python main.py --stress food_shock --days 50 --fresh
python main.py --stress compound --days 50 --seed 99
python main.py --train
python main.py --train --no-web
python main.py --train-once --no-web
python main.py --compare run_id_a run_id_b
pytest tests/test_replay_equivalence.py tests/test_smoke_simulation.py -q

Appendix B — Output files

Run folder

storage/runs/<run_id>/
  manifest.json
  checkpoint.json
  metrics.csv
  metrics_summary.json
  run_log.txt
  simulation.log
  state.json
  state_final.json
  canvas.html
  canvas_final.html
  canvas_debug.log

Experiments

storage/experiments/battery_100/
storage/experiments/learning_curve/
storage/experiments/tech_ab/
storage/experiments/metrology_lab/
storage/experiments/counterfactual/
storage/experiments/compare/

Train

storage/train_result/
storage/train_logs/seen_sources.json

Appendix C — Stress protocols

Name	Effect (summary)
`none`	No scripted shock
`food_shock`	Food multiplied down on a fixed day
`water_shock`	Water multiplied down
`pop_influx`	Sudden population add
`raid_week`	Food loss + morale hit
`compound`	Combined pressure

python main.py --stress compound --days 60 --seed 123

Appendix D — Glossary

Term	Meaning
Master seed	Root integer for all RNG streams
Run ID	Folder identity for a simulation instance
Policy bias	Slow parameter shifting decision thresholds
Food AUC	Sum of food over days (area under curve)
Replay-equivalence	Same seed ⇒ same trajectory
Canvas diary	One cell per day visualization
Train hint	Soft prior from external text

Appendix E — Suggested experiments

Climate survival distribution — --battery100 with fixed days; plot survival by climate.
Tech necessity — --tech-ab for storage/cooking/irrigation-class techs.
Policy value — --learning-curve; report Δ survival.
Intervention timing — counterfactual gift_food at different intervene days (code-level extension).
Stress robustness — same seeds under none vs compound.
Train transfer — run --train-once --no-web, then matched seeds with/without latest_policy_hints.json present.

Appendix F — Changelog (high level)

v1.0.0 — Research release: live/offline canvas stability, deterministic bandit RNG, 100-seed battery, learning-curve experiment, compare dashboard, CI, MIT license, train loop, phases 19–25 tooling, arid/cold balance pass.

Final note

REGENESIS is a long-horizon experimental instrument. Its value is not a single lucky run with high population—it is the ability to ask a clear question, fix a seed, vary one factor, and keep an auditable trail of metrics, plots, and validity checks.

If you use it in coursework, thesis work, or applications, prefer precise claims and published seeds over marketing language.

One agent. One place. Survive or vanish—and measure what changed.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
ai		ai
assets		assets
core		core
knowledge		knowledge
phases		phases
screenshots		screenshots
storage		storage
tests		tests
ui		ui
.gitignore		.gitignore
LICENSE		LICENSE
PHASES.md		PHASES.md
README.md		README.md
config.py		config.py
main.py		main.py
requirements.txt		requirements.txt
start.bat		start.bat
start.sh		start.sh
version.py		version.py

Latest commit

History

Folders and files

Repository files navigation