Update app.py

app.py

@@ -1,7 +1,1032 @@
+"""
+Root-level Gradio app for WorldSmithAI.
+
+This file is intended to live directly beside callbacks.py in the repository
+root. It does not assume an app/ package or folder.
+
+The UI is intentionally thin:
+- app.py defines the Gradio interface.
+- callbacks.py runs generation, parsing, validation, world construction,
+  simulation, visualization, metrics, and narration.
+- The simulation engine remains generic and DSL-driven.
+
+Environment variables:
+    WORLDSMITHAI_MODEL_ID:
+        Optional Hugging Face model id for model-generated DSL.
+
+    HF_TOKEN:
+        Optional Hugging Face token for private or gated models.
+
+    WORLDSMITHAI_OUTPUT_DIR:
+        Optional directory for generated GIFs, MP4s, charts, and images.
+
+    WORLDSMITHAI_DEFAULT_STEPS:
+        Optional default simulation step count.
+
+    WORLDSMITHAI_MAX_FRAMES:
+        Optional maximum animation frame count.
+
+    WORLDSMITHAI_LOG_LEVEL:
+        Optional logging level. Defaults to INFO.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import traceback
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
 import gradio as gr
 
-def greet(name):
-    return "Hello " + name + "!!"
+from callbacks import (
+    CallbackConfig,
+    CallbackResult,
+    apply_step_override,
+    callback_failure_result,
+    generate_world_from_prompt,
+    load_example_callback,
+    parse_constraints,
+    run_worldsmith_pipeline,
+    simulate_dsl_pipeline,
+    validate_dsl_callback,
+)
+from dsl.validator import validate_world_spec
+
+
+APP_TITLE = "WorldSmithAI"
+APP_SUBTITLE = "Production-Level Agent-Based World Simulation Framework"
+APP_VERSION = "0.1.0"
+
+DEFAULT_PROMPT = (
+    "Create a compact research ecosystem where scientists, engineers, reviewers, "
+    "and funding agents exchange knowledge, compete for attention, collaborate, "
+    "and adapt their goals over time."
+)
+
+PROMPT_EXAMPLES = [
+    [
+        "A medieval civilization with merchants, rulers, artisans, scholars, guards, "
+        "taxes, trade, regulations, and resource pressure."
+    ],
+    [
+        "A startup economy with founders, investors, customers, operators, competitors, "
+        "market bidding, adoption dynamics, and shifting goals."
+    ],
+    [
+        "A fantasy world with mages, dragons, healers, merchants, mana resources, "
+        "alliances, communication, negotiation, and magical infrastructure."
+    ],
+    [
+        "A transport network with hubs, carriers, dispatchers, chargers, passengers, "
+        "queues, routes, deliveries, and congestion."
+    ],
+    [
+        "A power grid world with generators, storage nodes, consumers, regulators, "
+        "energy resources, subsidies, enforcement, and rebalancing."
+    ],
+    [
+        "A space colony with colonists, engineers, botanists, navigators, miners, "
+        "oxygen resources, habitat expansion, and survival goals."
+    ],
+]
+
+CUSTOM_CSS = """
+#worldsmith-header {
+    padding: 1.1rem 1.25rem;
+    border-radius: 1rem;
+    background: linear-gradient(135deg, rgba(80, 80, 120, 0.12), rgba(120, 120, 160, 0.08));
+    border: 1px solid rgba(120, 120, 160, 0.18);
+}
+.worldsmith-small {
+    font-size: 0.92rem;
+    opacity: 0.82;
+}
+.worldsmith-status textarea {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+}
+"""
+
+
+logging.basicConfig(
+    level=os.getenv("WORLDSMITHAI_LOG_LEVEL", "INFO").upper(),
+    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class AppModelStatus:
+    """Status of the optional model client used by the UI."""
+
+    enabled: bool
+    model_id: str | None
+    message: str
+
+    def to_markdown(self) -> str:
+        """Return display Markdown for model status."""
+
+        if self.enabled:
+            return f"**Model client:** configured with `{self.model_id}`."
+
+        return f"**Model client:** not configured. {self.message}"
+
+
+class OptionalHFInferenceClient:
+    """Small adapter around huggingface_hub.InferenceClient.
+
+    This adapter is optional. If a model id is not configured, the app still
+    works through WorldSmithAI's deterministic fallback generator.
+    """
+
+    def __init__(self, model_id: str, token: str | None = None) -> None:
+        """Initialize the optional Hugging Face inference adapter."""
+
+        from huggingface_hub import InferenceClient
+
+        self.model_id = model_id
+        self.client = InferenceClient(model=model_id, token=token)
+
+    def generate(
+        self,
+        prompt: str | None = None,
+        messages: list[dict[str, str]] | None = None,
+        max_new_tokens: int = 2048,
+        temperature: float = 0.2,
+        **_: Any,
+    ) -> str:
+        """Generate text using common InferenceClient methods."""
+
+        if messages:
+            chat_text = self._try_chat_completion(
+                messages,
+                max_new_tokens=max_new_tokens,
+                temperature=temperature,
+            )
+            if chat_text:
+                return chat_text
+
+        if prompt:
+            text_generation = self._try_text_generation(
+                prompt,
+                max_new_tokens=max_new_tokens,
+                temperature=temperature,
+            )
+            if text_generation:
+                return text_generation
+
+        raise RuntimeError("InferenceClient did not return generated text")
+
+    def _try_chat_completion(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        max_new_tokens: int,
+        temperature: float,
+    ) -> str | None:
+        """Try chat-style generation methods."""
+
+        try:
+            chat_completion = getattr(self.client, "chat_completion", None)
+            if callable(chat_completion):
+                response = chat_completion(
+                    messages=messages,
+                    max_tokens=max_new_tokens,
+                    temperature=temperature,
+                )
+                return _extract_model_text(response)
+        except Exception:
+            logger.debug("InferenceClient.chat_completion failed", exc_info=True)
+
+        try:
+            chat = getattr(self.client, "chat", None)
+            completions = getattr(chat, "completions", None)
+            create = getattr(completions, "create", None)
+            if callable(create):
+                response = create(
+                    messages=messages,
+                    max_tokens=max_new_tokens,
+                    temperature=temperature,
+                )
+                return _extract_model_text(response)
+        except Exception:
+            logger.debug("InferenceClient.chat.completions.create failed", exc_info=True)
+
+        return None
+
+    def _try_text_generation(
+        self,
+        prompt: str,
+        *,
+        max_new_tokens: int,
+        temperature: float,
+    ) -> str | None:
+        """Try text-generation style methods."""
+
+        try:
+            text_generation = getattr(self.client, "text_generation", None)
+            if callable(text_generation):
+                response = text_generation(
+                    prompt,
+                    max_new_tokens=max_new_tokens,
+                    temperature=temperature,
+                    return_full_text=False,
+                )
+                return _extract_model_text(response)
+        except Exception:
+            logger.debug("InferenceClient.text_generation failed", exc_info=True)
+
+        return None
+
+
+def build_optional_model_client() -> tuple[Any | None, AppModelStatus]:
+    """Build the optional model client from environment variables."""
+
+    model_id = (
+        os.getenv("WORLDSMITHAI_MODEL_ID")
+        or os.getenv("WORLD_SMITH_MODEL_ID")
+        or os.getenv("HF_MODEL_ID")
+    )
+    token = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN")
+
+    if not model_id:
+        return None, AppModelStatus(
+            enabled=False,
+            model_id=None,
+            message="Set WORLDSMITHAI_MODEL_ID to enable model-generated DSL.",
+        )
+
+    try:
+        client = OptionalHFInferenceClient(model_id=model_id, token=token)
+        return client, AppModelStatus(
+            enabled=True,
+            model_id=model_id,
+            message="Model client configured.",
+        )
+    except Exception as exc:
+        logger.warning("Optional model client could not be configured: %s", exc)
+        return None, AppModelStatus(
+            enabled=False,
+            model_id=model_id,
+            message=(
+                f"WORLDSMITHAI_MODEL_ID={model_id} was found, but the client "
+                f"could not be initialized: {exc}. The app will use deterministic fallback."
+            ),
+        )
+
+
+MODEL_CLIENT, MODEL_STATUS = build_optional_model_client()
+
+
+def app_callback_config(
+    *,
+    steps: int | float | str | None,
+    animation_format: str,
+) -> CallbackConfig:
+    """Create callback configuration from UI values and environment defaults."""
+
+    default_steps = _env_int("WORLDSMITHAI_DEFAULT_STEPS", 60)
+    max_frames = _env_int("WORLDSMITHAI_MAX_FRAMES", 80)
+    output_dir = os.getenv("WORLDSMITHAI_OUTPUT_DIR") or None
+
+    return CallbackConfig(
+        output_dir=output_dir,
+        steps=_coerce_optional_int(steps) if steps is not None else default_steps,
+        max_animation_frames=max(1, max_frames),
+        animation_format=animation_format,
+    )
+
+
+def run_from_prompt_ui(
+    prompt: str,
+    steps: int | float,
+    constraints: str,
+    animation_format: str,
+    use_configured_model: bool,
+) -> tuple[Any, ...]:
+    """Run the full prompt-to-simulation pipeline for the main UI tab."""
+
+    client = MODEL_CLIENT if use_configured_model else None
+    config = app_callback_config(steps=steps, animation_format=animation_format)
+
+    try:
+        result = run_worldsmith_pipeline(
+            prompt=prompt,
+            constraints=parse_constraints(constraints),
+            client=client,
+            config=config,
+        )
+        return result_to_ui_tuple(result)
+    except Exception as exc:
+        logger.exception("Prompt simulation failed")
+        return failure_to_ui_tuple(exc)
+
+
+def generate_dsl_only_ui(
+    prompt: str,
+    constraints: str,
+    use_configured_model: bool,
+    steps: int | float,
+) -> tuple[str, str, str]:
+    """Generate DSL only, without running simulation."""
+
+    client = MODEL_CLIENT if use_configured_model else None
+    config = app_callback_config(steps=steps, animation_format="gif")
+
+    try:
+        generation = generate_world_from_prompt(
+            prompt=prompt,
+            constraints=parse_constraints(constraints),
+            client=client,
+            config=config,
+        )
+        spec = apply_step_override(generation.spec, _coerce_optional_int(steps))
+        report = validate_world_spec(
+            spec,
+            config=config.resolved_validation_config(),
+        )
+        status = (
+            f"Generated `{spec.id}` with {len(spec.agents)} agent(s), "
+            f"{len(spec.resources)} resource(s), and "
+            f"{len(spec.behavior_names)} behavior reference(s). "
+            f"Validation: {len(report.errors)} error(s), {len(report.warnings)} warning(s)."
+        )
+        return (
+            spec.to_json_string(indent=2, exclude_none=True),
+            _safe_json_dumps(report.to_dict()),
+            status,
+        )
+    except Exception as exc:
+        logger.exception("DSL generation failed")
+        return "", "{}", f"DSL generation failed: {exc}"
+
+
+def simulate_dsl_ui(
+    dsl_json: str,
+    steps: int | float,
+    animation_format: str,
+    use_configured_model_for_narration: bool,
+) -> tuple[Any, ...]:
+    """Run simulation from user-supplied DSL JSON."""
+
+    client = MODEL_CLIENT if use_configured_model_for_narration else None
+    config = app_callback_config(steps=steps, animation_format=animation_format)
+
+    try:
+        result = simulate_dsl_pipeline(
+            dsl_json=dsl_json,
+            client=client,
+            config=config,
+        )
+        return result_to_ui_tuple(result)
+    except Exception as exc:
+        logger.exception("DSL simulation failed")
+        return failure_to_ui_tuple(exc, world_spec_json=dsl_json)
+
+
+def validate_dsl_ui(dsl_json: str) -> tuple[str, str]:
+    """Validate DSL JSON in the validation tab."""
+
+    return validate_dsl_callback(dsl_json)
+
+
+def load_example_ui(example_name: str | None) -> tuple[str, str]:
+    """Load an example JSON file into the DSL editor."""
+
+    if not example_name:
+        return "", "Choose an example first."
+
+    examples = discover_examples()
+    path = examples.get(example_name)
+    if path is None:
+        return "", f"Unknown example: {example_name}"
+
+    return load_example_callback(path)
+
+
+def clear_main_outputs() -> tuple[Any, ...]:
+    """Clear main-tab outputs."""
+
+    return (
+        "",
+        "",
+        gr.update(value=None, visible=False),
+        gr.update(value=None, visible=False),
+        None,
+        None,
+        None,
+        "",
+        "",
+        "",
+    )
+
+
+def result_to_ui_tuple(result: CallbackResult) -> tuple[Any, ...]:
+    """Map CallbackResult to the app output component order."""
+
+    animation_image, animation_video = animation_path_updates(result.animation_path)
+
+    return (
+        result.world_spec_json,
+        result.validation_json,
+        animation_image,
+        animation_video,
+        result.population_chart_path,
+        result.resource_chart_path,
+        result.final_image_path,
+        _markdown_narrative(result.narrative),
+        result.metrics_json,
+        result.status_message,
+    )
+
+
+def failure_to_ui_tuple(
+    error: BaseException,
+    *,
+    world_spec_json: str = "",
+) -> tuple[Any, ...]:
+    """Map an exception to a safe UI output tuple."""
+
+    result = callback_failure_result(error, world_spec_json=world_spec_json)
+    details = {
+        "success": False,
+        "error_type": error.__class__.__name__,
+        "error": str(error),
+        "traceback": traceback.format_exc(),
+        "callback_result": result.to_dict(),
+    }
+
+    return (
+        result.world_spec_json,
+        result.validation_json,
+        gr.update(value=None, visible=False),
+        gr.update(value=None, visible=False),
+        None,
+        None,
+        None,
+        _markdown_narrative(result.narrative),
+        _safe_json_dumps(details),
+        result.status_message,
+    )
+
+
+def animation_path_updates(path: str | None) -> tuple[Any, Any]:
+    """Return Gradio updates for GIF/image and MP4/video animation components."""
+
+    if not path:
+        return gr.update(value=None, visible=False), gr.update(value=None, visible=False)
+
+    suffix = Path(path).suffix.lower()
+
+    if suffix in {".mp4", ".webm", ".mov", ".m4v"}:
+        return gr.update(value=None, visible=False), gr.update(value=path, visible=True)
+
+    return gr.update(value=path, visible=True), gr.update(value=None, visible=False)
+
+
+def discover_examples() -> dict[str, Path]:
+    """Discover JSON example files in the root-level examples directory."""
+
+    examples_dir = Path(__file__).resolve().parent / "examples"
+    if not examples_dir.exists():
+        return {}
+
+    return {
+        path.stem.replace("_", " ").title(): path
+        for path in sorted(examples_dir.glob("*.json"))
+    }
+
+
+def build_demo() -> gr.Blocks:
+    """Build and return the Gradio Blocks demo."""
+
+    examples = discover_examples()
+    example_names = list(examples.keys())
+    default_steps = _env_int("WORLDSMITHAI_DEFAULT_STEPS", 60)
+
+    with gr.Blocks(
+        title=f"{APP_TITLE} — Agent-Based World Simulation",
+        css=CUSTOM_CSS,
+        analytics_enabled=False,
+    ) as demo:
+        gr.Markdown(
+            f"""
+<div id="worldsmith-header">
+
+# {APP_TITLE}
+### {APP_SUBTITLE}
+
+WorldSmithAI converts natural language into a validated JSON DSL, builds a deterministic Python
+agent-based world, simulates emergent behavior, and returns animation, charts, metrics, and narration.
+
+<span class="worldsmith-small">
+No species or domains are hardcoded. A farmer, dragon, scientist, vehicle, startup, power node,
+or civilization actor is a generic Agent with state, memory, behaviors, and policy.
+</span>
+
+</div>
+"""
+        )
+
+        with gr.Accordion("Runtime status", open=False):
+            gr.Markdown(MODEL_STATUS.to_markdown())
+            gr.Markdown(
+                "If no model client is configured, the app still runs with the deterministic fallback DSL generator. "
+                "Set WORLDSMITHAI_MODEL_ID in the Space environment to enable model-generated DSL."
+            )
+
+        with gr.Tabs():
+            with gr.Tab("Generate + Simulate"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        prompt = gr.Textbox(
+                            label="World prompt",
+                            value=DEFAULT_PROMPT,
+                            lines=8,
+                            placeholder=(
+                                "Describe any agent-based world: farm, civilization, research lab, "
+                                "startup economy, fantasy realm, transport system..."
+                            ),
+                        )
+                        constraints = gr.Textbox(
+                            label="Optional constraints",
+                            value='{"max_agents": 6, "demo_size": "small"}',
+                            lines=4,
+                            placeholder='Example: {"max_agents": 6, "steps": 80}',
+                        )
+
+                        with gr.Row():
+                            steps = gr.Slider(
+                                minimum=1,
+                                maximum=250,
+                                value=default_steps,
+                                step=1,
+                                label="Simulation steps",
+                            )
+                            animation_format = gr.Dropdown(
+                                choices=["gif", "mp4"],
+                                value="gif",
+                                label="Animation format",
+                            )
+
+                        use_model = gr.Checkbox(
+                            label="Use configured model client when available",
+                            value=MODEL_CLIENT is not None,
+                            interactive=True,
+                        )
+
+                        with gr.Row():
+                            run_button = gr.Button("Generate world + run simulation", variant="primary")
+                            clear_button = gr.Button("Clear outputs")
+
+                        gr.Examples(
+                            examples=PROMPT_EXAMPLES,
+                            inputs=[prompt],
+                            label="Prompt examples",
+                        )
+
+                    with gr.Column(scale=1):
+                        status = gr.Textbox(
+                            label="Status",
+                            lines=3,
+                            interactive=False,
+                            elem_classes=["worldsmith-status"],
+                        )
+                        narrative = gr.Markdown(label="Narrative summary")
+
+                with gr.Tab("Visual outputs"):
+                    with gr.Row():
+                        animation_image = gr.Image(
+                            label="Simulation animation GIF",
+                            type="filepath",
+                            visible=True,
+                        )
+                        animation_video = gr.Video(
+                            label="Simulation animation MP4",
+                            visible=False,
+                        )
+
+                    with gr.Row():
+                        final_image = gr.Image(
+                            label="Final world state",
+                            type="filepath",
+                        )
+                        population_chart = gr.Image(
+                            label="Population chart",
+                            type="filepath",
+                        )
+                        resource_chart = gr.Image(
+                            label="Resource chart",
+                            type="filepath",
+                        )
+
+                with gr.Tab("Generated DSL + diagnostics"):
+                    world_spec_json = gr.Code(
+                        label="Generated WorldSpec JSON",
+                        language="json",
+                        lines=24,
+                    )
+                    validation_json = gr.Code(
+                        label="Validation report",
+                        language="json",
+                        lines=16,
+                    )
+                    metrics_json = gr.Code(
+                        label="Metrics and run diagnostics",
+                        language="json",
+                        lines=24,
+                    )
+
+                main_outputs = [
+                    world_spec_json,
+                    validation_json,
+                    animation_image,
+                    animation_video,
+                    population_chart,
+                    resource_chart,
+                    final_image,
+                    narrative,
+                    metrics_json,
+                    status,
+                ]
+
+                run_button.click(
+                    fn=run_from_prompt_ui,
+                    inputs=[prompt, steps, constraints, animation_format, use_model],
+                    outputs=main_outputs,
+                    show_progress=True,
+                )
+
+                clear_button.click(
+                    fn=clear_main_outputs,
+                    inputs=[],
+                    outputs=main_outputs,
+                )
+
+            with gr.Tab("Generate DSL only"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        dsl_prompt = gr.Textbox(
+                            label="World prompt",
+                            value=DEFAULT_PROMPT,
+                            lines=8,
+                        )
+                        dsl_constraints = gr.Textbox(
+                            label="Optional constraints",
+                            value='{"max_agents": 6}',
+                            lines=4,
+                        )
+                        dsl_steps = gr.Slider(
+                            minimum=1,
+                            maximum=250,
+                            value=default_steps,
+                            step=1,
+                            label="Simulation steps to put in DSL",
+                        )
+                        dsl_use_model = gr.Checkbox(
+                            label="Use configured model client when available",
+                            value=MODEL_CLIENT is not None,
+                        )
+                        generate_dsl_button = gr.Button("Generate DSL", variant="primary")
+
+                    with gr.Column(scale=1):
+                        generated_dsl_status = gr.Textbox(
+                            label="Status",
+                            lines=3,
+                            interactive=False,
+                        )
+                        generated_dsl_validation = gr.Code(
+                            label="Validation report",
+                            language="json",
+                            lines=16,
+                        )
+
+                generated_dsl = gr.Code(
+                    label="Generated WorldSpec JSON",
+                    language="json",
+                    lines=28,
+                )
+
+                generate_dsl_button.click(
+                    fn=generate_dsl_only_ui,
+                    inputs=[dsl_prompt, dsl_constraints, dsl_use_model, dsl_steps],
+                    outputs=[generated_dsl, generated_dsl_validation, generated_dsl_status],
+                    show_progress=True,
+                )
+
+            with gr.Tab("Simulate existing DSL"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        example_dropdown = gr.Dropdown(
+                            choices=example_names,
+                            value=example_names[0] if example_names else None,
+                            label="Load example JSON",
+                            interactive=bool(example_names),
+                        )
+                        load_example_button = gr.Button("Load selected example")
+                        example_status = gr.Textbox(
+                            label="Example status",
+                            lines=2,
+                            interactive=False,
+                        )
+
+                        existing_dsl = gr.Code(
+                            label="WorldSpec JSON",
+                            language="json",
+                            lines=28,
+                            value="",
+                        )
+
+                        with gr.Row():
+                            existing_steps = gr.Slider(
+                                minimum=1,
+                                maximum=250,
+                                value=default_steps,
+                                step=1,
+                                label="Simulation steps override",
+                            )
+                            existing_animation_format = gr.Dropdown(
+                                choices=["gif", "mp4"],
+                                value="gif",
+                                label="Animation format",
+                            )
+
+                        existing_use_model = gr.Checkbox(
+                            label="Use configured model client for narration when available",
+                            value=False,
+                        )
+                        simulate_dsl_button = gr.Button("Simulate DSL", variant="primary")
+
+                    with gr.Column(scale=1):
+                        existing_status = gr.Textbox(
+                            label="Status",
+                            lines=3,
+                            interactive=False,
+                        )
+                        existing_narrative = gr.Markdown(label="Narrative summary")
+
+                with gr.Tab("DSL simulation visuals"):
+                    with gr.Row():
+                        existing_animation_image = gr.Image(
+                            label="Simulation animation GIF",
+                            type="filepath",
+                            visible=True,
+                        )
+                        existing_animation_video = gr.Video(
+                            label="Simulation animation MP4",
+                            visible=False,
+                        )
+
+                    with gr.Row():
+                        existing_final_image = gr.Image(
+                            label="Final world state",
+                            type="filepath",
+                        )
+                        existing_population_chart = gr.Image(
+                            label="Population chart",
+                            type="filepath",
+                        )
+                        existing_resource_chart = gr.Image(
+                            label="Resource chart",
+                            type="filepath",
+                        )
+
+                with gr.Tab("DSL simulation diagnostics"):
+                    existing_validation = gr.Code(
+                        label="Validation report",
+                        language="json",
+                        lines=16,
+                    )
+                    existing_metrics = gr.Code(
+                        label="Metrics and run diagnostics",
+                        language="json",
+                        lines=24,
+                    )
+
+                load_example_button.click(
+                    fn=load_example_ui,
+                    inputs=[example_dropdown],
+                    outputs=[existing_dsl, example_status],
+                )
+
+                simulate_dsl_button.click(
+                    fn=simulate_dsl_ui,
+                    inputs=[
+                        existing_dsl,
+                        existing_steps,
+                        existing_animation_format,
+                        existing_use_model,
+                    ],
+                    outputs=[
+                        existing_dsl,
+                        existing_validation,
+                        existing_animation_image,
+                        existing_animation_video,
+                        existing_population_chart,
+                        existing_resource_chart,
+                        existing_final_image,
+                        existing_narrative,
+                        existing_metrics,
+                        existing_status,
+                    ],
+                    show_progress=True,
+                )
+
+            with gr.Tab("Validate DSL"):
+                validation_input = gr.Code(
+                    label="WorldSpec JSON to validate",
+                    language="json",
+                    lines=28,
+                )
+                validate_button = gr.Button("Validate DSL", variant="primary")
+                validation_output = gr.Code(
+                    label="Validation report",
+                    language="json",
+                    lines=24,
+                )
+                validation_status = gr.Textbox(
+                    label="Status",
+                    lines=3,
+                    interactive=False,
+                )
+
+                validate_button.click(
+                    fn=validate_dsl_ui,
+                    inputs=[validation_input],
+                    outputs=[validation_output, validation_status],
+                )
+
+            with gr.Tab("About"):
+                gr.Markdown(
+                    """
+## WorldSmithAI architecture
+
+WorldSmithAI follows this pipeline:
+
+Natural language prompt
+→ SLM-generated JSON DSL
+→ Pydantic schema validation
+→ Semantic DSL validation
+→ WorldFactory
+→ World / Scheduler / Agents / Policies / Behaviors
+→ Metrics / Visualization / Narration
+→ Gradio UI
+
+### Important design constraint
+
+The simulation engine is deterministic Python. The model generates JSON only, never Python code.
+
+### UI outputs
+
+- Animation: GIF by default; MP4 if selected and ffmpeg is available.
+- Population chart: grouped by agent type.
+- Resource chart: grouped by resource type and weighted by amount.
+- Narrative: deterministic by default, optionally model-assisted if a client is configured.
+- Diagnostics: includes DSL validation, factory build report, metric history, artifact paths, and generation mode.
+
+### Suggested root-level Space layout
+
+app.py  
+callbacks.py  
+requirements.txt  
+core/  
+behaviors/  
+policies/  
+dsl/  
+factory/  
+metrics/  
+visualization/  
+llm/  
+examples/
+"""
+                )
+
+    return demo
+
+
+def _extract_model_text(response: Any) -> str | None:
+    """Extract text from common model response shapes."""
+
+    if response is None:
+        return None
+
+    if isinstance(response, str):
+        return response.strip()
+
+    if isinstance(response, bytes):
+        return response.decode("utf-8").strip()
+
+    if isinstance(response, Mapping):
+        for key in ("text", "content", "generated_text", "output", "response"):
+            value = response.get(key)
+            if value is not None:
+                return _extract_model_text(value)
+
+        choices = response.get("choices")
+        if isinstance(choices, list) and choices:
+            return _extract_model_text(choices[0])
+
+        message = response.get("message")
+        if isinstance(message, Mapping):
+            return _extract_model_text(message.get("content"))
+
+    for attr in ("text", "content", "generated_text", "output", "response"):
+        value = getattr(response, attr, None)
+        if value is not None:
+            return _extract_model_text(value)
+
+    choices = getattr(response, "choices", None)
+    if choices:
+        return _extract_model_text(choices[0])
+
+    message = getattr(response, "message", None)
+    if message is not None:
+        return _extract_model_text(message)
+
+    return None
+
+
+def _coerce_optional_int(value: int | float | str | None) -> int | None:
+    """Coerce UI numeric values to optional int."""
+
+    if value is None or value == "":
+        return None
+
+    return int(float(value))
+
+
+def _env_int(name: str, default: int) -> int:
+    """Read an integer environment variable with a safe default."""
+
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+
+    try:
+        return int(float(raw))
+    except ValueError:
+        logger.warning("Invalid integer environment variable %s=%r", name, raw)
+        return default
+
+
+def _safe_json_dumps(value: Any) -> str:
+    """Serialize values as pretty JSON for Gradio Code components."""
+
+    return json.dumps(
+        _json_safe(value),
+        indent=2,
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+
+
+def _json_safe(value: Any) -> Any:
+    """Return JSON-friendly representation of arbitrary values."""
+
+    if value is None or isinstance(value, (str, bool)):
+        return value
+
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+
+    if isinstance(value, float):
+        if value != value or value in {float("inf"), float("-inf")}:
+            return None
+        return value
+
+    if isinstance(value, Mapping):
+        return {str(key): _json_safe(nested) for key, nested in value.items()}
+
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(item) for item in value]
+
+    if hasattr(value, "to_dict") and callable(value.to_dict):
+        return _json_safe(value.to_dict())
+
+    if hasattr(value, "model_dump") and callable(value.model_dump):
+        return _json_safe(value.model_dump(mode="json"))
+
+    return str(value)
+
+
+def _markdown_narrative(text: str) -> str:
+    """Return narrative text formatted for Markdown display."""
+
+    cleaned = str(text or "").strip()
+    if not cleaned:
+        return "No narrative was generated."
+
+    return cleaned
+
+
+demo = build_demo()
+app = demo
+
 
-demo = gr.Interface(fn=greet, inputs="text", outputs="text")
-demo.launch()
+if __name__ == "__main__":
+    demo.queue().launch()