compararive insights

README.md

@@ -19,260 +19,36 @@ The goal is not to “simulate everything”, but to build a configurable sandbo
 - **Bias experiments**: What happens to world stability when the population is biased toward “good nature” vs “bad nature”?
 - **Scarcity vs abundance**: How do shared natural resources shape inequality, wellbeing, cooperation/conflict, and longevity?
 - **Identity dynamics**: How do race/faith/beauty norms influence social networks and opportunity, and how do they compound over rebirth cycles?
-- **Randomness vs “engineering”**: Are outcomes explainable from explicit rules and parameters, or do they appear chaotic until you measure them?
-- **Philosophical lenses**: If we encode different schools of thought (e.g., Advaita, Vishishtadvaita, Buddhist frameworks) as rule sets, how do they change emergent behavior and “liberation” outcomes?
+- **Sustainability Equilibrium**: What is the ideal balance of population, resources, and moral bias to ensure world longevity?
 
-### High-level model (simple, measurable, extensible)
-To keep the simulation testable, each philosophical concept is mapped to something measurable.
+### Core Features
+- **Deterministic Simulation**: Tick-based engine where every run is reproducible via seed.
+- **Sustainable Equilibrium Optimizer**: An auto-tuning tool that hunts for parameters that maximize world longevity (surviving collapse).
+- **Run History & AI Comparison**: Automatically saves all runs and allows AI to generate comparative insights between two different worlds.
+- **Local AI Insights**: Uses Gemma 2 2b (via `llama_cpp` or `Ollama`) to quantitatively interpret simulation results and causal links.
 
+### High-level model
 - **Soul**: immutable id; persists across lifetimes; carries karma forward.
-- **Person (a body/life)**: a soul embodied for one lifetime with traits, identity markers, wellbeing, and relationships.
-- **Karma**: a numeric score (or vector later) updated by actions and outcomes; influences rebirth initialization.
-- **Nature (good/bad bias)**: a trait like `moral_bias ∈ [-1, 1]` affecting decisions (cooperate, hoard, harm, help).
-- **Resources**: global pool with replenishment; agents compete/coordinate to consume/produce.
-- **Society**: group labels (race/faith) and norms (beauty) influencing trust, mate choice, cooperation, and conflict.
-- **Events**: stochastic shocks (disease, drought, opportunity, tragedy) parameterized and observable in logs.
-- **Philosophical school / worldview**: a configurable “lens” that changes how agents interpret self/other, attachment, ethics, and the karma→rebirth→liberation mechanics (implemented as a pluggable ruleset, not hard-coded into the engine).
+- **Person**: a transient body with traits (moral bias, health, wellbeing).
+- **Karma**: numeric score updated by actions; influences next-life initialization.
+- **Resources**: global pool with replenishment; consumption influenced by moral bias (sharing vs hoarding).
+- **World Collapse**: Simulation ends if resources hit 0, everyone dies, or karma reaches 0.
 
-### Bringing in philosophical schools of thought (planned)
-At some point this simulation should support multiple **worldviews** as first-class configuration, such as:
-- **Advaita (Adhvaitha)**: non-dual framing; emphasis on ignorance/knowledge; reduced self/other separation.
-- **Vishishtadvaita (Vishistadvaitha)**: qualified non-dual framing; enduring individuality in relation to the whole.
-- **Buddhist lenses**: no fixed self, dependent origination; attachment/craving as drivers of suffering; liberation as reduction of craving/ignorance.
-
-Implementation-wise, these won’t be treated as “religion labels” like `faith`. Instead, they act as **simulation rule modules** that can change:
-- **Decision policy**: cooperation vs hoarding vs harm vs help; attachment, compassion, renunciation as parameters.
-- **Suffering/wellbeing model**: how craving/aversion affects wellbeing beyond material resources.
-- **Karma semantics**: how actions update karma and which actions matter.
-- **Rebirth mapping**: how karma affects next-life traits and circumstances.
-- **Liberation / exit conditions** (optional): when a soul stops rebirthing (e.g., thresholds, convergent criteria, or explicit “moksha/nirvana” state in the model).
-
-The key constraint: we’ll keep the **core engine neutral** and make worldviews pluggable so we can run the same initial world under different lenses and compare outcomes.
-
-### Why a phased approach
-This idea contains many interacting systems. If we build UI/visuals first, we’ll optimize for looks before we know the world model creates interesting behavior.
-
-So we build **engine-first**, prove the simulation produces meaningful metrics and repeatable experiments, then layer visualization and richer social dynamics.
-
-## Phased roadmap
-Each phase should end with something runnable and measurable.
-
-### Phase 0 — Foundations (scaffolding + repeatability)
-- Basic repo structure and packaging
-- Single config object (or YAML/JSON) that fully defines a run
-- Deterministic seeding for reproducible scenarios
-- Logging/tracing of key events
-
-### Phase 1 — Core life-cycle engine (V1 target)
-- A world with a **fixed soul pool**
-- Birth/life/death loop with a tick-based simulation (e.g., one tick = one year)
-- Shared resource pool with scarcity/abundance knobs
-- Karma accumulation and rebirth mapping
-- Metrics + simple charts
-
-### Phase 2 — Social interactions
-- Friendship/partnering rules
-- Cooperation/conflict mechanics
-- Network effects (who influences whom)
-- New metrics: cohesion, inequality, conflict rate, cluster formation
-
-### Phase 3 — Identity + norms
-- Race/faith labels and trust matrices
-- “Beauty” norms as socially defined advantage/disadvantage
-- Bias and discrimination parameters
-
-### Phase 4 — Rich events + scenario comparison UX
-- Expanded event catalogue and world shocks
-- Side-by-side scenario runner (good-biased vs bad-biased, scarcity vs abundance)
-- Saved runs, replay, and comparative dashboards
-
-### Phase 5 — Philosophical schools as pluggable worldviews
-- Define a `Worldview` interface (policy + karma + rebirth + liberation hooks)
-- Implement first set of worldview modules (Advaita, Vishishtadvaita, Buddhist lens)
-- Add scenario comparison: same seed/config, different worldview → compare metrics and liberation rates
-- Add new metrics relevant to worldviews (e.g., attachment/craving proxy, compassion proxy, “liberation” events)
-
-## V1 technical plan (build the minimum interesting world)
-V1 is the smallest version that can answer: **does “good vs bad bias” + “scarcity vs abundance” meaningfully change world-level outcomes over generations?**
-
-### Deliverable (what “done” looks like for V1)
-- A single command starts an interactive app where you can:
-  - set parameters (seed, population size, resource abundance, bias toward good/bad nature)
-  - run for `N` ticks / generations
-  - view metrics and charts
-- Runs are reproducible via seed + config snapshot.
-
-### Running (Windows / PowerShell)
-From `c:\Workspace\agentic-ai\projects\god`:
-
-- Run the CLI (prints JSON):
-
-```bash
-uv sync
-uv run god-sim --ticks 200 --num-souls 300
-```
-
-- Run the UI (Streamlit):
-
-```bash
-uv sync
-uv run streamlit run .\src\god_sim\app\streamlit_app.py
-```
-
-### Run history persistence
-- Every simulation run is automatically saved to `data/run_history.json`.
-- Each record contains:
-  - `run_id`, `created_at_utc`
-  - `config`
-  - `final` metrics snapshot
-  - full `series` time-series data
-- The dashboard includes a **Run History** section to compare recent runs.
-
-### Local LLM insights (Gemma via Ollama)
-The UI can optionally ask a **local** model to summarize and interpret a run (no cloud required).
-
-1) Install and start Ollama, then pull a small Gemma model (example):
+### Running the App
+The app is optimized for Hugging Face Spaces using Docker, but can be run locally:
 
 ```bash
-ollama pull gemma2:2b
-ollama serve
+# Run the UI (Streamlit)
+uv run streamlit run src/god_sim/app/streamlit_app.py
 ```
 
-2) Run the app and click **Generate insights from last run**.
-
-3) Optional environment variables:
-- `GOD_LLM_PROVIDER`: `ollama` (default) or `openai_compatible`
-- `OLLAMA_BASE_URL`: default `http://localhost:11434`
-- `OLLAMA_MODEL`: default `gemma2:2b`
-- `OPENAI_BASE_URL`: default `http://localhost:1234/v1` (for local OpenAI-compatible servers)
-- `OPENAI_MODEL`: default `gemma`
-- `OPENAI_API_KEY`: only if your local server requires it
-
-### Fully offline LLM insights (no server) using your HF `.bin`
-Your Hugging Face repo contains a local file `gemma-2b-it-cpu-int4.bin` (uploaded here: [`vikramvasudevan/gemma-for-panchangam`](https://huggingface.co/vikramvasudevan/gemma-for-panchangam)).
-
-Important format note:
-- `llama-cpp-python` expects **GGUF** files for `provider=llama_cpp`.
-- A `.bin` file may download successfully but still fail to load in `llama_cpp`.
-- If you want to use your current `.bin`, use `provider=ollama` (server mode), or obtain/convert a GGUF model for fully offline `llama_cpp`.
-
-1) Download the model file into `.\models\`:
-
-```bash
-uv sync
-uv run god-sim-download-model --repo vikramvasudevan/gemma-for-panchangam --file gemma-2b-it-cpu-int4.bin --out models
-```
-
-2) Run the UI and choose provider `llama_cpp` in the Insights section, or set env vars:
-- `GOD_LLM_PROVIDER=llama_cpp`
-- `GOD_LLM_MODEL_PATH=models/<your-model>.gguf`
-- (optional) `GOD_LLM_N_CTX=4096`, `GOD_LLM_N_THREADS=0`
-
-If the model path is missing, the app now tries to **auto-download** from Hugging Face by default.
-
-Optional controls:
-- `GOD_LLM_AUTO_DOWNLOAD=1` (default) or `0`
-- `GOD_LLM_HF_REPO=vikramvasudevan/gemma-for-panchangam`
-- `GOD_LLM_HF_FILE=gemma-2b-it-cpu-int4.bin`
-
-### Recommended stack
-- **Python**: `dataclasses` + type hints
-- **Numerics**: `numpy` (optionally `pandas` if it helps)
-- **Visualization/UI**: **Streamlit** (fastest to iterate on “play God” sliders + charts)
-- **Plots**: `plotly` (or `matplotlib`)
-
-### Suggested code organization
-```
-god/
-  README.md
-  pyproject.toml
-  main.py                    # CLI or entrypoint (later can launch Streamlit)
-  src/god_sim/
-    __init__.py
-    config.py                # WorldConfig, scenario presets
-    domain/
-      soul.py                 # Soul (id, karma)
-      person.py               # Person (traits, identity, wellbeing, relationships)
-      world.py                # World state (population, resources, time)
-      resources.py            # ResourcePool (replenish, consume)
-      events.py               # Event types and effects
-    engine/
-      sim.py                  # run_simulation(), step_world()
-      rebirth.py              # Rebirth rules (karma → next-life initialization)
-      karma.py                # Karma updates from actions/outcomes
-    rules/
-      decisions.py            # cooperate/hoard/help/harm policy driven by moral_bias
-      social.py               # (minimal in V1) optional basic interaction
-    analytics/
-      metrics.py              # collectors + aggregations
-      report.py               # plot helpers
-    app/
-      streamlit_app.py        # sliders → run → charts
-```
-
-### Core data model (V1)
-Start numeric and simple; keep everything observable.
-
-- `Soul`
-  - `soul_id: int`
-  - `karma: float`
-
-- `Person`
-  - `soul_id: int`
-  - `age: int`
-  - `max_age: int` (sampled)
-  - `health: float`
-  - `wellbeing: float`
-  - `moral_bias: float` (good↔bad)
-  - `consumption_need: float`
-  - (optional in V1) `race`, `faith`, `beauty_score` (can exist but not heavily used yet)
-
-- `World`
-  - `time: int`
-  - `resource_pool: ResourcePool`
-  - `people: list[Person]`
-  - `souls: dict[int, Soul]`
-
-### Simulation loop (tick-based)
-For each tick:
-- Replenish global resources
-- For each person:
-  - consume resources (if insufficient, wellbeing/health drop)
-  - decide actions influenced by `moral_bias` (e.g., share vs hoard)
-  - sample an event (configurable probabilities)
-  - update wellbeing/health/karma
-- Age everyone, apply deaths
-- For each death:
-  - update soul karma summary if needed
-  - rebirth: create a new `Person` for the same `Soul`, with traits drawn from distributions shifted by karma
-- Collect metrics for this tick
-
-### Metrics to track in V1 (minimum set)
-- Population alive over time (should remain stable-ish given constant soul pool, but death/birth timing matters)
-- Mean/median karma and distribution (histogram)
-- Mean/median wellbeing and distribution
-- Resource pool level over time
-- Inequality proxy (simple: Gini of wellbeing or resources consumed; can be added later)
-- Event counts by type
-
-### Scenario knobs (V1 controls)
-- `seed`
-- `num_souls`
-- `ticks`
-- `resource_replenish_rate`
-- `resource_capacity`
-- `baseline_consumption_need`
-- `event_rate` and event mix
-- `initial_moral_bias_mean` and `initial_moral_bias_std`
-- `rebirth_influence_strength` (how strongly karma affects next-life traits)
-
-### Testing/validation (pragmatic)
-- Same config + seed produces the same metrics time series
-- Extreme scenarios behave sensibly:
-  - very low replenish rate → widespread suffering / collapse-like signals
-  - high replenish rate + good bias → higher wellbeing and lower conflict proxies (even if conflict is minimal in V1)
-
----
+### Local LLM insights
+1) Install Ollama and pull Gemma: `ollama pull gemma2:2b`
+2) Run the app and click **Generate insights**.
 
-### Notes
-- The original project statement is preserved as `README.backup.md` in this folder.
+### Hugging Face Deployment
+The app uses `llama_cpp` with GGUF for fast, serverless insights:
+- **Provider**: `llama_cpp`
+- **Model Repo**: `bartowski/gemma-2-2b-it-GGUF`
+- **Model File**: `gemma-2-2b-it-Q4_K_M.gguf`
+- **Context Window**: 8192 tokens.

SKILLS.md

@@ -1,68 +1,33 @@
 # GOD Simulation Skills & Knowledge
 
-This document serves as a guide for working on the GOD reincarnation-based social simulation. It outlines the core mental models, technical patterns, and workflows used in this project.
+This document serves as a guide for working on the GOD reincarnation-based social simulation.
 
 ## 核心理念 (Core Philosophy)
 The project is a "world engine" simulating a fixed pool of souls cycling through birth, life, death, and rebirth.
 - **Fixed Soul Pool:** Souls are persistent; only their physical manifestations (Persons) cycle.
-- **Karma-Driven Rebirth:** Actions in one life influence the starting conditions of the next.
-- **Resource Scarcity:** A central driver for behavior (cooperation vs. hoarding).
-- **Extensible Worldviews:** (Planned) Pluggable rulesets for different philosophical lenses (Advaita, Buddhist, etc.).
+- **Sustainability Equilibrium:** The goal is to find parameters where the world does not collapse.
+- **Collapse Conditions:** Resources = 0, Population = 0, or Karma = 0.
 
-## Domain Models (`src/god_sim/domain/`)
-- **`Soul`**: Immutable ID + persistent `karma`. Carries history across lifetimes.
-- **`Person`**: The transient physical entity. Has `age`, `health`, `wellbeing`, `moral_bias`, and `consumption_need`.
-- **`World`**: Container for the `ResourcePool`, `Person` list, and `Soul` dictionary.
-- **`ResourcePool`**: Manages finite resources with a replenishment rate.
+## Simulation Engine (`src/god_sim/engine/`)
 
-## Simulation Engine (`src/god_sim/engine/sim.py`)
-- **Tick-Based:** The simulation progresses in discrete time steps (ticks).
-- **Step Logic:**
-    1. **Replenish Resources:** Global pool grows by `replenish_rate`.
-    2. **Consumption & Interaction:**
-        - High `moral_bias` (good) -> Sharing part of resources.
-        - Low `moral_bias` (bad) -> Hoarding (requesting more than need).
-        - Shortfalls hurt health/wellbeing; surplus helps.
-    3. **Karma Updates:** Updated based on `moral_bias` and life events.
-    4. **Events:** Stochastic shocks (positive/negative) impacting health/wellbeing.
-    5. **Aging & Death:** Health drops with age; death triggers rebirth.
-    6. **Rebirth:** A new `Person` is created for the `Soul`. Karma influences the new `moral_bias`.
+### Core Simulator (`sim.py`)
+- **Step Logic:** Replenish -> Consume/Interact -> Update Karma -> Events -> Age/Death -> Rebirth.
+- **Collapsed Flag:** Every tick checks if the world has met any exit conditions.
 
-## Analytics & Metrics (`src/god_sim/analytics/`)
-- Every tick produces a metric snapshot: `alive`, `resource`, `mean_karma`, `mean_wellbeing`, `mean_health`, `events`.
-- **Persistence:** Runs are saved to `data/run_history.json` for comparison.
+### Sustainable Equilibrium Optimizer (`optimizer.py`)
+- **Evaluation**: Uses a fitness function based on "Longevity" (ticks survived).
+- **Random Search**: Iterates through parameter combinations to find the highest fitness world configuration for a fixed resource capacity.
 
-## AI Insights (`src/god_sim/insights/`)
-The system uses LLMs to interpret simulation results.
-- **Providers:** Supports `ollama` (local dev), `openai_compatible`, and `llama_cpp` (recommended for Hugging Face).
-- **Format Note:** `llama_cpp` requires **GGUF** files. Old `.bin` files will not work.
-- **Recommended for HF Spaces:**
-    - `GOD_LLM_PROVIDER`: `llama_cpp`
-    - `GOD_LLM_HF_REPO`: `bartowski/gemma-2-2b-it-GGUF`
-    - `GOD_LLM_HF_FILE`: `gemma-2-2b-it-Q4_K_M.gguf`
-- **Workflow:**
-    1. `build_run_summary` extracts deltas and trends from the simulation output.
-    2. LLM analyzes JSON summary to provide bulleted insights and suggested experiments.
+## AI Insights & Comparisons (`src/god_sim/insights/`)
+The system uses LLMs (Gemma 2 2b) to interpret results.
+- **Single Run (`generate_insights`)**: Quantitative analysis of deltas and trends.
+- **Comparative (`generate_comparative_insights`)**: Analyzing two runs to find causal links between parameter changes and outcomes.
+- **Local Deployment**: Uses `llama_cpp` with GGUF files and an 8192 context window.
 
-## Development Workflows
-
-### Running the CLI
-```bash
-uv run god-sim --ticks 200 --num-souls 300
-```
-
-### Running the Dashboard
-```bash
-uv run streamlit run src/god_sim/app/streamlit_app.py
-```
+## Analytics & Persistence (`src/god_sim/analytics/`)
+- **JSON Serialization**: Uses a custom `SimulationEncoder` in `history.py` to handle `numpy` types and booleans.
+- **Run History**: Saved to `data/run_history.json`.
 
-### Key Configurations (`src/god_sim/config.py`)
-Modify `WorldConfig` to tune the simulation:
-- `initial_moral_bias_mean/std`: Sets the world's starting "nature".
-- `resource_replenish_rate`: Controls scarcity.
-- `rebirth_influence_strength`: Controls how much karma matters for the next life.
-
-## Adding New Features
-- **New Metrics:** Update `step_world` return dict and `analytics/metrics.py`.
-- **New Rules:** Add logic to `step_world` or create a new module in `rules/`.
-- **New Worldviews:** Implement hooks in `engine/sim.py` that change `moral_bias` interpretation or karma calculation.
+## Development Workflows
+- **Hugging Face**: Deployed via Docker. Environment variables `GOD_LLM_PROVIDER`, `GOD_LLM_HF_REPO`, and `GOD_LLM_HF_FILE` control the AI engine.
+- **Streamlit**: Main entry point is `src/god_sim/app/streamlit_app.py`.

src/god_sim/app/streamlit_app.py

@@ -218,6 +218,30 @@ if history:
             }
         )
     st.dataframe(pd.DataFrame(rows), width="stretch")
+
+    st.subheader("⚖️ AI Comparison")
+    st.caption("Select two runs from history to compare them using AI.")
+    compare_runs = st.multiselect(
+        "Select exactly 2 runs",
+        options=list(run_options.keys()),
+        max_selections=2,
+        help="Select two runs to see how their parameters influenced the emergent world outcomes."
+    )
+    
+    if len(compare_runs) == 2:
+        if st.button("Generate Comparative Insights"):
+            from god_sim.insights.llm import generate_comparative_insights
+            run_a = run_options[compare_runs[0]]
+            run_b = run_options[compare_runs[1]]
+            
+            cfg_ins = insight_config_from_env()
+            # (Assuming standard provider/model selection from below or env)
+            try:
+                with st.spinner("Analyzing differences..."):
+                    comparison_text = generate_comparative_insights(run_a, run_b, cfg=cfg_ins)
+                st.markdown(comparison_text)
+            except Exception as e:
+                st.error(f"Comparison failed: {e}")
 else:
     st.caption("No runs stored yet. Run a simulation to create history.")
 

src/god_sim/insights/llm.py

@@ -236,3 +236,61 @@ def generate_insights(sim_output: dict[str, Any], cfg: InsightConfig | None = No
     data = r.json()
     return str(data["choices"][0]["message"]["content"]).strip()
 
+def generate_comparative_insights(out_a: dict[str, Any], out_b: dict[str, Any], cfg: InsightConfig | None = None, timeout_s: int = 120) -> str:
+    cfg = cfg or insight_config_from_env()
+    summary_a = build_run_summary(out_a, df_tail_rows=10)
+    summary_b = build_run_summary(out_b, df_tail_rows=10)
+
+    user_prompt = (
+        "Compare these TWO simulation runs (A and B).\n\n"
+        f"RUN_A_SUMMARY:\n{json.dumps(summary_a, indent=2)}\n\n"
+        f"RUN_B_SUMMARY:\n{json.dumps(summary_b, indent=2)}\n\n"
+        "Analyze the impact of the parameter differences on the outcomes.\n"
+        "Return:\n"
+        "1) Key differences in longevity and stability\n"
+        "2) Causal link: which parameter change likely caused the most significant divergence?\n"
+        "3) Which world was 'healthier' and why?\n"
+    )
+
+    if cfg.provider == "ollama":
+        url = cfg.ollama_base_url.rstrip("/") + "/api/generate"
+        payload = {
+            "model": cfg.ollama_model,
+            "prompt": user_prompt,
+            "system": "You are a comparative analyst for world simulations. Focus on causal differences.",
+            "stream": False,
+            "options": {"temperature": cfg.temperature},
+        }
+        r = requests.post(url, json=payload, timeout=timeout_s)
+        r.raise_for_status()
+        return str(r.json().get("response", "")).strip()
+
+    if cfg.provider == "llama_cpp":
+        try:
+            from llama_cpp import Llama
+        except ImportError:
+            raise RuntimeError("llama-cpp-python not available.")
+
+        model_path = Path(cfg.model_path)
+        llm = Llama(model_path=str(model_path), n_ctx=cfg.n_ctx, n_threads=None if cfg.n_threads <= 0 else cfg.n_threads, verbose=False)
+        prompt = f"System: You are a comparative analyst.\nUser: {user_prompt}"
+        out = llm(prompt, max_tokens=cfg.max_tokens, temperature=cfg.temperature, stop=["</s>"])
+        return str(out["choices"][0]["text"]).strip()
+
+    # OpenAI-compatible
+    url = cfg.openai_base_url.rstrip("/") + "/chat/completions"
+    headers = {"Content-Type": "application/json"}
+    if cfg.openai_api_key:
+        headers["Authorization"] = f"Bearer {cfg.openai_api_key}"
+    payload = {
+        "model": cfg.openai_model,
+        "temperature": cfg.temperature,
+        "max_tokens": cfg.max_tokens,
+        "messages": [
+            {"role": "system", "content": "You are a comparative analyst."},
+            {"role": "user", "content": user_prompt},
+        ],
+    }
+    r = requests.post(url, headers=headers, json=payload, timeout=timeout_s)
+    r.raise_for_status()
+    return str(r.json()["choices"][0]["message"]["content"]).strip()