Update README.md

README.md

@@ -12,3 +12,970 @@ short_description: Forge ecosystems from small models
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# WorldSmithAI
+
+**Production-Level Agent-Based World Simulation Framework**
+
+WorldSmithAI is a modular Python framework that converts natural language descriptions into generic agent-based worlds and simulates emergent behavior.
+
+The core idea is simple:
+
+```text
+Natural language prompt
+→ WorldSpec JSON DSL
+→ Pydantic validation
+→ WorldFactory
+→ World
+→ Scheduler
+→ Agents
+→ Policies
+→ Behaviors
+→ Metrics
+→ Visualization
+→ Narration
+→ Gradio UI
+```
+
+WorldSmithAI is intentionally **not hardcoded for any single domain**.
+
+There are no runtime classes like:
+
+```python
+class Sheep
+class Wolf
+class Scientist
+class Merchant
+class Dragon
+```
+
+Instead, every world is composed from generic runtime concepts:
+
+```python
+Agent
+Behavior
+Resource
+Event
+World
+Policy
+```
+
+That means the same engine can simulate:
+
+- farm ecosystems
+- medieval civilizations
+- research ecosystems
+- startup economies
+- social networks
+- fantasy worlds
+- transport networks
+- power grids
+- space colonies
+- any DSL-generated ecosystem
+
+---
+
+## Project Status
+
+WorldSmithAI is designed as a hackathon-grade prototype with production-oriented architecture.
+
+Current capabilities include:
+
+- generic agent representation
+- behavior abstraction
+- concrete behavior modules
+- rule-based policies
+- contextual bandit policy scaffold
+- Pydantic DSL schema
+- JSON parser and semantic validator
+- WorldFactory for DSL → runtime conversion
+- metrics for diversity, entropy, stability, and interestingness
+- Matplotlib renderer
+- GIF/MP4 animation support
+- chart generation
+- deterministic narration
+- root-level Gradio app
+- CLI runner
+- example DSL worlds
+
+The system works without an external LLM by using a deterministic fallback world generator. If a model is configured, the model is only responsible for generating JSON DSL, never Python code.
+
+---
+
+## Repository Layout
+
+```text
+WorldSmithAI/
+├── app.py
+├── callbacks.py
+├── main.py
+├── README.md
+├── requirements.txt
+│
+├── core/
+│   ├── agent.py
+│   ├── behavior.py
+│   ├── resource.py
+│   ├── event.py
+│   ├── world.py
+│   └── scheduler.py
+│
+├── behaviors/
+│   ├── movement.py
+│   ├── consume.py
+│   ├── trade.py
+│   ├── attack.py
+│   ├── research.py
+│   ├── collaboration.py
+│   ├── transport.py
+│   ├── construction.py
+│   ├── governance.py
+│   ├── market.py
+│   ├── adoption.py
+│   ├── planning.py
+│   └── memory.py
+│
+├── policies/
+│   ├── base_policy.py
+│   ├── rule_policy.py
+│   └── contextual_bandit.py
+│
+├── dsl/
+│   ├── schema.py
+│   ├── parser.py
+│   └── validator.py
+│
+├── factory/
+│   └── world_factory.py
+│
+├── metrics/
+│   ├── diversity.py
+│   ├── entropy.py
+│   ├── stability.py
+│   └── interestingness.py
+│
+├── visualization/
+│   ├── renderer.py
+│   ├── animation.py
+│   └── charts.py
+│
+├── llm/
+│   ├── world_generator.py
+│   ├── narrator.py
+│   └── prompts.py
+│
+└── examples/
+    ├── farm.json
+    ├── civilization.json
+    └── research.json
+```
+
+`app.py` is intentionally at the repository root because Hugging Face Gradio Spaces expect the app entry point there.
+
+---
+
+## Core Design Principles
+
+WorldSmithAI follows these principles:
+
+1. **No hardcoded species or domains**
+
+   A wolf, scientist, startup founder, train, dragon, or power node is just an `Agent` with a different `type`, `state`, `memory`, `goals`, `behaviors`, and `policy`.
+
+2. **DSL-first world definition**
+
+   Worlds are described as JSON using the `WorldSpec` schema.
+
+3. **LLM generates JSON only**
+
+   The model never generates Python code. The Python engine remains deterministic.
+
+4. **Composition over inheritance**
+
+   Agent behavior comes from behavior objects and policies, not subclass-specific logic.
+
+5. **Strong module boundaries**
+
+   Parsing, validation, factory construction, simulation, visualization, metrics, narration, and UI are separate layers.
+
+6. **Gradio app is thin**
+
+   `app.py` defines the UI. `callbacks.py` runs the engine pipeline.
+
+---
+
+## Installation
+
+### 1. Clone the repository
+
+```bash
+git clone <your-repo-url>
+cd WorldSmithAI
+```
+
+### 2. Create a virtual environment
+
+Python 3.11 or newer is recommended.
+
+```bash
+python -m venv .venv
+```
+
+Activate it:
+
+```bash
+source .venv/bin/activate
+```
+
+On Windows PowerShell:
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+### 3. Install dependencies
+
+If your project already has a `requirements.txt`, run:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+```
+
+If you have not created `requirements.txt` yet, use this minimal set:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install gradio pydantic numpy matplotlib pillow huggingface_hub
+```
+
+Optional development tools:
+
+```bash
+python -m pip install pytest ruff mypy
+```
+
+Optional MP4 support requires `ffmpeg` installed on the system. GIF output works through Pillow and is the safer default.
+
+---
+
+## Suggested `requirements.txt`
+
+Create this file at the repository root:
+
+```text
+gradio
+pydantic>=2
+numpy
+matplotlib
+pillow
+huggingface_hub
+```
+
+Optional dev dependencies can be placed in `requirements-dev.txt`:
+
+```text
+pytest
+ruff
+mypy
+```
+
+---
+
+## Can This Be Tested Locally?
+
+Yes. WorldSmithAI can be tested locally without Hugging Face Spaces and without an external LLM.
+
+The deterministic fallback generator allows this command to work even if no model is configured:
+
+```bash
+python main.py --prompt "A research ecosystem with scientists, reviewers, funding agents, and knowledge resources" --steps 10 --no-animation
+```
+
+For a faster smoke test, disable all visual outputs:
+
+```bash
+python main.py \
+  --prompt "A tiny farm ecosystem with farmers, water, crops, and soil health" \
+  --steps 5 \
+  --no-animation \
+  --no-charts \
+  --no-final-image \
+  --no-narrative
+```
+
+If that completes, your parser, schema, world generation fallback, validation, factory, scheduler, policies, behaviors, and metrics are at least importable and executable.
+
+---
+
+## Local Smoke Test Checklist
+
+Run these from the repository root.
+
+### 1. Check Python syntax
+
+```bash
+python -m compileall .
+```
+
+This catches syntax errors across all modules.
+
+### 2. List example worlds
+
+```bash
+python main.py --list-examples
+```
+
+Expected output should include some or all of:
+
+```text
+farm
+civilization
+research
+```
+
+### 3. Validate an example DSL file
+
+```bash
+python main.py --example research --validate-only
+```
+
+Or directly:
+
+```bash
+python main.py --dsl examples/research.json --validate-only
+```
+
+This checks:
+
+- JSON parsing
+- Pydantic schema validation
+- semantic DSL validation
+
+### 4. Run a short simulation without animation
+
+```bash
+python main.py --example research --steps 5 --no-animation
+```
+
+This checks:
+
+- WorldFactory
+- runtime object construction
+- policies
+- behaviors
+- scheduler/world stepping
+- metrics
+- charts/final image unless disabled
+
+### 5. Run the fastest full-pipeline smoke test
+
+```bash
+python main.py \
+  --example farm \
+  --steps 5 \
+  --no-animation \
+  --no-charts \
+  --no-final-image \
+  --no-narrative
+```
+
+This is useful when debugging core engine issues.
+
+### 6. Run a full local artifact test
+
+```bash
+python main.py --example research --steps 20 --output-dir outputs/research_test
+```
+
+Expected outputs:
+
+```text
+outputs/research_test/
+├── world_spec.json
+├── validation_report.json
+├── metrics.json
+├── narrative.md
+├── run_summary.json
+├── simulation.gif
+├── population chart image
+├── resource chart image
+└── final world image
+```
+
+Exact image filenames may depend on the callback artifact writer.
+
+### 7. Run the Gradio app locally
+
+```bash
+python app.py
+```
+
+Then open the local URL printed in the terminal, usually something like:
+
+```text
+http://127.0.0.1:7860
+```
+
+Try the default prompt first. Then try one of:
+
+```text
+A medieval civilization with rulers, merchants, artisans, guards, public trust, taxes, and trade.
+
+A startup economy with founders, customers, investors, market adoption, and shifting goals.
+
+A fantasy world with dragons, mages, healers, mana, alliances, and negotiation.
+```
+
+---
+
+## CLI Usage
+
+`main.py` is the local command-line entry point.
+
+### Run an example world
+
+```bash
+python main.py --example research --steps 60
+```
+
+### Run a DSL file
+
+```bash
+python main.py --dsl examples/farm.json --steps 80
+```
+
+### Generate a world from a prompt
+
+```bash
+python main.py \
+  --prompt "A fantasy kingdom with dragons, mages, merchants, mana, trade, and alliances" \
+  --steps 70
+```
+
+### Validate only
+
+```bash
+python main.py --dsl examples/civilization.json --validate-only
+```
+
+### Generate DSL only
+
+```bash
+python main.py \
+  --prompt "A transport network with hubs, carriers, queues, chargers, and route planning" \
+  --generate-only
+```
+
+### Disable expensive outputs
+
+```bash
+python main.py --example research --steps 20 --no-animation --no-charts
+```
+
+### Use MP4 animation
+
+```bash
+python main.py --example research --steps 30 --animation-format mp4
+```
+
+If MP4 fails, install `ffmpeg` or use GIF:
+
+```bash
+python main.py --example research --steps 30 --animation-format gif
+```
+
+---
+
+## Gradio App Usage
+
+Start the app:
+
+```bash
+python app.py
+```
+
+The UI includes:
+
+1. **Generate + Simulate**
+
+   Enter a natural-language world prompt. The app generates DSL, builds a world, runs simulation, and returns:
+
+   - generated JSON DSL
+   - validation report
+   - animation
+   - population chart
+   - resource chart
+   - final world image
+   - narrative summary
+   - metrics JSON
+
+2. **Generate DSL only**
+
+   Use this to inspect the generated `WorldSpec` before simulation.
+
+3. **Simulate existing DSL**
+
+   Paste JSON or load an example from `examples/`.
+
+4. **Validate DSL**
+
+   Validate a JSON world spec without running it.
+
+---
+
+## Optional Model Setup
+
+WorldSmithAI works without an LLM by using a deterministic fallback generator.
+
+To enable a Hugging Face model for DSL generation, set:
+
+```bash
+export WORLDSMITHAI_MODEL_ID="your-model-id"
+```
+
+Optional token:
+
+```bash
+export HF_TOKEN="your-hugging-face-token"
+```
+
+Then run:
+
+```bash
+python app.py
+```
+
+The model is only asked to generate WorldSpec JSON. It is not allowed to generate Python code.
+
+If the model fails or returns invalid JSON, WorldSmithAI can fall back to deterministic generation.
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `WORLDSMITHAI_MODEL_ID` | Optional Hugging Face model id for JSON DSL generation |
+| `HF_TOKEN` | Optional Hugging Face token |
+| `WORLDSMITHAI_OUTPUT_DIR` | Directory for generated artifacts |
+| `WORLDSMITHAI_DEFAULT_STEPS` | Default simulation steps in the app |
+| `WORLDSMITHAI_MAX_FRAMES` | Maximum animation frames |
+| `WORLDSMITHAI_LOG_LEVEL` | Logging level, for example `INFO` or `DEBUG` |
+
+Example:
+
+```bash
+export WORLDSMITHAI_DEFAULT_STEPS=60
+export WORLDSMITHAI_MAX_FRAMES=80
+export WORLDSMITHAI_LOG_LEVEL=INFO
+python app.py
+```
+
+---
+
+## DSL Example
+
+A minimal world looks like this:
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "tiny_world",
+  "name": "Tiny World",
+  "description": "A minimal generic world.",
+  "simulation": {
+    "steps": 10,
+    "seed": 0,
+    "scheduler": "sequential",
+    "activation": "sequential",
+    "collect_history": true
+  },
+  "space": {
+    "dimensions": 2,
+    "bounds": [[0, 10], [0, 10]],
+    "toroidal": false,
+    "enforce_bounds": true
+  },
+  "agents": [
+    {
+      "id": "agent_1",
+      "type": "explorer",
+      "position": [1, 1],
+      "state": {
+        "energy": 10,
+        "credits": 5
+      },
+      "memory": {
+        "goals": [
+          {
+            "id": "learn",
+            "importance": 1,
+            "score": 1
+          }
+        ]
+      },
+      "goals": [
+        {
+          "id": "learn",
+          "importance": 1,
+          "score": 1
+        }
+      ],
+      "behaviors": [
+        {
+          "name": "prioritize",
+          "params": {
+            "source_path": "memory.goals"
+          }
+        },
+        {
+          "name": "choose_goal",
+          "params": {}
+        },
+        {
+          "name": "remember",
+          "params": {
+            "category": "initial",
+            "content": {
+              "note": "hello world"
+            }
+          }
+        }
+      ],
+      "policy": {
+        "type": "rule_policy",
+        "params": {
+          "rules": [
+            {
+              "behavior_name": "choose_goal",
+              "score_delta": 3
+            },
+            {
+              "behavior_name": "prioritize",
+              "score_delta": 2
+            },
+            {
+              "behavior_name": "remember",
+              "score_delta": 1
+            }
+          ]
+        }
+      },
+      "alive": true,
+      "metadata": {}
+    }
+  ],
+  "resources": [],
+  "events": [],
+  "metrics": [
+    {
+      "name": "diversity",
+      "params": {
+        "collection": "agents",
+        "group_by_path": "type"
+      }
+    }
+  ],
+  "metadata": {}
+}
+```
+
+---
+
+## Architecture Notes
+
+### World generation
+
+`llm/world_generator.py` converts prompts into `WorldSpec`.
+
+If no model client is configured, it uses a deterministic fallback builder.
+
+### Parsing and validation
+
+`dsl/parser.py` accepts:
+
+- JSON strings
+- dictionaries
+- JSON files
+- Markdown-fenced JSON
+- model responses containing JSON
+
+`dsl/schema.py` performs structural validation.
+
+`dsl/validator.py` performs semantic validation, such as checking behavior names, policy names, constructor parameters, and references.
+
+### Runtime construction
+
+`factory/world_factory.py` turns `WorldSpec` into runtime objects:
+
+```text
+WorldSpec
+→ Agent
+→ Resource
+→ Event
+→ Behavior
+→ Policy
+→ World
+```
+
+### Simulation
+
+The world and scheduler advance agents. Agents delegate decision-making to policies, and behaviors mutate generic state/memory.
+
+### Visualization
+
+`visualization/renderer.py` renders a single world state.
+
+`visualization/animation.py` renders GIF or MP4 animations.
+
+`visualization/charts.py` renders population and resource curves.
+
+### Metrics
+
+`metrics/` includes:
+
+- diversity
+- entropy
+- stability
+- interestingness
+
+### Narration
+
+`llm/narrator.py` produces deterministic narrative summaries and can optionally use a model client for polished narration.
+
+---
+
+## Testing Strategy
+
+A practical local testing ladder:
+
+### Level 1: Syntax
+
+```bash
+python -m compileall .
+```
+
+### Level 2: DSL parsing
+
+```bash
+python main.py --dsl examples/farm.json --validate-only
+python main.py --dsl examples/civilization.json --validate-only
+python main.py --dsl examples/research.json --validate-only
+```
+
+### Level 3: Fast simulation
+
+```bash
+python main.py --example farm --steps 5 --no-animation --no-charts --no-final-image --no-narrative
+```
+
+### Level 4: Metrics and narration
+
+```bash
+python main.py --example research --steps 10 --no-animation --no-charts --no-final-image
+```
+
+### Level 5: Full artifact generation
+
+```bash
+python main.py --example civilization --steps 20 --output-dir outputs/civilization_test
+```
+
+### Level 6: Gradio UI
+
+```bash
+python app.py
+```
+
+---
+
+## Troubleshooting
+
+### `ModuleNotFoundError`
+
+Make sure you are running commands from the repository root:
+
+```bash
+pwd
+```
+
+The current directory should contain:
+
+```text
+app.py
+callbacks.py
+main.py
+core/
+behaviors/
+dsl/
+factory/
+metrics/
+visualization/
+llm/
+```
+
+Then run:
+
+```bash
+python -m compileall .
+```
+
+### `ImportError` for a behavior module
+
+Check that the behavior file exists and that the behavior registry includes the expected names.
+
+For example:
+
+```bash
+python - <<'PY'
+from dsl.validator import load_default_behavior_registry
+
+result = load_default_behavior_registry()
+print("Behavior count:", len(result.registry))
+print("Import errors:", result.import_errors)
+print("Names:", sorted(result.registry.keys())[:50])
+PY
+```
+
+### Unknown behavior warnings
+
+If semantic validation reports unknown behavior names, check:
+
+1. the behavior file exists
+2. it defines a `BEHAVIOR_REGISTRY`
+3. the behavior name in JSON matches the registry key
+4. `factory/world_factory.py` includes the behavior module in `DEFAULT_BEHAVIOR_MODULES`
+
+### Constructor parameter warnings
+
+If the validator reports unknown constructor parameters, either:
+
+- fix the JSON behavior params, or
+- update the behavior dataclass to accept the parameter, or
+- run in permissive mode through `callbacks.py`, which is friendlier for hackathon demos.
+
+### MP4 animation fails
+
+Use GIF instead:
+
+```bash
+python main.py --example research --steps 30 --animation-format gif
+```
+
+MP4 requires `ffmpeg` installed on the host.
+
+### Gradio app starts but generation is slow
+
+Use fewer steps:
+
+```bash
+export WORLDSMITHAI_DEFAULT_STEPS=20
+export WORLDSMITHAI_MAX_FRAMES=30
+python app.py
+```
+
+Or disable model usage in the UI and use deterministic fallback generation.
+
+### Model returns invalid JSON
+
+The parser can extract JSON from common model response formats, but small models may still produce invalid JSON.
+
+Use:
+
+- the deterministic fallback generator
+- “Generate DSL only” tab
+- “Validate DSL” tab
+- simpler prompts
+- fewer agents
+
+---
+
+## Hugging Face Space Notes
+
+For a Gradio Space, keep these files at the repository root:
+
+```text
+app.py
+callbacks.py
+requirements.txt
+```
+
+The Space should install dependencies from `requirements.txt`.
+
+Recommended Space hardware for the deterministic version is CPU basic. If you use a larger model locally inside the Space, choose hardware appropriate for that model.
+
+---
+
+## Development Tips
+
+Run formatting and lint checks if you install dev tools:
+
+```bash
+ruff check .
+```
+
+Run type checks if your environment is ready:
+
+```bash
+mypy .
+```
+
+Run a quick no-UI smoke test before pushing:
+
+```bash
+python main.py --example research --steps 5 --no-animation --no-charts --no-final-image --no-narrative
+```
+
+Then run the app:
+
+```bash
+python app.py
+```
+
+---
+
+## Hackathon Demo Script
+
+A good demo flow:
+
+1. Open the app.
+2. Enter a world prompt, for example:
+
+   ```text
+   A startup economy where founders, investors, customers, and competitors bid for attention,
+   adopt strategies, collaborate, forecast demand, and rebalance resources.
+   ```
+
+3. Run simulation for 40 to 60 steps.
+4. Show the generated DSL.
+5. Show the animation.
+6. Show population and resource charts.
+7. Show metrics JSON.
+8. Read the narrative summary.
+9. Explain that the model generated only JSON, while the deterministic Python engine executed the simulation.
+
+---
+
+## Current Limitations
+
+WorldSmithAI is designed as a hackathon-grade but production-oriented framework. Some areas are intentionally extensible:
+
+- event execution is generic and can be expanded
+- richer scheduler activation modes can be added
+- metric registry integration can be expanded
+- behavior parameter schemas can be tightened
+- model-specific generation adapters can be added
+- graph/network visualization can be added
+- multi-run comparison can be added
+- unit tests should be expanded as the codebase stabilizes
+
+---
+
+
+
+## Acknowledgments
+
+Built for the Hugging Face Build Small Hackathon.
+
+WorldSmithAI explores how small language models can generate compact, validated world DSLs while deterministic Python systems execute and visualize the resulting simulations.