Upload 7 files

README.md

@@ -1,209 +1,51 @@
----
-title: RFT Agent Simulation Engine
-emoji: 🐨
-colorFrom: yellow
-colorTo: purple
-sdk: gradio
-sdk_version: 6.6.0
-app_file: app.py
-pinned: false
-license: other
-short_description: Multi‑agent drift & stability simulator.
----
-
----
-
-RFT Agent Simulation Engine — MVP Release
-
-A symbolic multi‑agent simulation engine built to model drift, stability, coherence, and emergent behaviour in complex systems.
-Developed as the first operational software implementation of the Rendered Frame Theory (RFT) agent architecture.
-
-This MVP provides a clean, modular, reproducible simulation environment that runs entirely in Python and is fully compatible with Google Colab and Hugging Face Spaces.
-
----
-
-🚀 Features
-
-✔ Multi‑Agent Simulation
-
-Each agent evolves over time through:
-
-• Awareness field updates (Φ)
-• Collapse‑torque dynamics (τ_eff)
-• Mutation
-• Drift
-• Fitness scoring
-• Tier‑independent behaviour
-
-
-✔ System‑Level Metrics
-
-The engine computes:
-
-• Coherence (average Φ across agents)
-• Stability (variance of Φ)
-• Emergent divergence patterns
-
-
-✔ Full Visualization Suite
-
-Automatically generates and saves:
-
-• phi_plot.png
-• tau_plot.png
-• fitness_plot.png
-• coherence_plot.png
-• stability_plot.png
-
-
-All plots are high‑resolution (300 dpi).
-
-✔ JSON Export
-
-Final agent states are exported to:
-
-• final_agent_states.json
-
-
-✔ One‑Click Packaging
-
-A built‑in ZIP builder creates:
-
-• rft_simulation_engine.zip
-containing all project files and generated artifacts.
-
-
-✔ Colab‑Optimized Dev Mode
-
-When running in Google Colab:
-
-• Gradio UI is bypassed
-• Simulation runs automatically
-• Plots display inline
-• All files save to disk
-
-
----
-
-📦 Project Structure
-
-agent.py            # RFTAgent class
-simulation.py       # RFTSimulation engine
-visualization.py    # Plotting utilities
-utils.py            # JSON export + ZIP builder
-app.py              # Gradio UI + Colab dev mode
-test_runner.py      # Automated test simulation
-requirements.txt    # Dependencies
-README.md           # Documentation
-
-
----
-
-▶️ Running the Simulation (Colab)
-
-To run the engine in Google Colab:
-
-from test_runner import run_test_simulation
-run_test_simulation()
-
-
-This will:
-
-• Run a 3‑agent, 100‑step simulation
-• Display all plots inline
-• Save all PNGs
-• Export final_agent_states.json
-• Print file paths
-
-
----
-
-🌐 Running the Gradio App (Hugging Face Space)
-
-When deployed on Hugging Face:
-
-python app.py
-
-
-The UI allows you to configure:
-
-• Number of agents
-• Number of steps
-• Mutation rate
-• Drift rate
-• Random seed
-
-
-And outputs:
-
-• All plots
-• JSON export
-• Downloadable results
-
-
----
-
-🧪 Example Output
-
-The engine produces:
-
-• Divergent agent trajectories
-• Torque evolution curves
-• Fitness progression
-• System coherence decay
-• Stability variance growth
-
-
-These behaviours emerge naturally from the agent update rules.
-
----
-
-📁 Packaging the Project
-
-To generate a ZIP containing all files and outputs:
-
-from utils import zip_project
-zip_project()
-
-
-This creates:
-
-• rft_simulation_engine.zip
-ready for download or distribution.
-
-
----
-
-🛠 Requirements
-
-numpy
-matplotlib
-gradio
-
-
----
-
-📣 About This Project
-
-This MVP demonstrates the first operational implementation of the RFT agent architecture.
-It is designed for:
-
-• AI researchers
-• Complex systems modellers
-• Simulation engineers
-• Worldbuilders
-• Anyone exploring emergent behaviour
-
-
-Future versions will introduce:
-
-• Agent packs
-• Mutation packs
-• Universe packs
-• Codex integration
-• Long‑run simulations
-• Advanced metrics
-
-
----
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# RFT Agent Simulation Engine MVP
+
+This project implements a Minimal Viable Product (MVP) of an RFT (Relational Frame Theory) Agent Simulation Engine. It allows for simulating the dynamics of RFT agents, visualizing their behavior, and exporting their states.
+
+## Project Structure
+- `agent.py`: Defines the `RFTAgent` class.
+- `simulation.py`: Defines the `RFTSimulation` class to manage agent interactions over time.
+- `visualization.py`: Contains functions for plotting simulation results using `matplotlib`.
+- `app.py`: Implements a Gradio web interface for running simulations and visualizing results.
+- `utils.py`: Provides utility functions for JSON export and seeding random number generators.
+- `requirements.txt`: Lists all Python package dependencies.
+- `README.md`: This file.
+
+## How to Run in Colab
+
+1.  **Open this Colab Notebook:** Ensure you have access to the notebook where these files were generated.
+2.  **Run All Cells:** Execute all cells in the notebook sequentially. This will create all the necessary `.py` files, `requirements.txt`, and `README.md` in your Colab environment.
+3.  **Install Dependencies:** Open a new code cell and run:
+    ```bash
+    !pip install -r requirements.txt
+    ```
+4.  **Run the Gradio App:** To launch the interactive Gradio interface, open a new code cell and run:
+    ```python
+    import app
+    app.iface.launch(debug=True)
+    ```
+    You will get a public URL (or a local URL if running locally) to access the Gradio interface in your browser.
+
+## How to Deploy to Hugging Face Spaces
+
+1.  **Create a New Space:** Go to [Hugging Face Spaces](https://huggingface.co/spaces) and create a new Space. Choose `Gradio` as the SDK.
+2.  **Upload Files:** Upload all the generated files (`agent.py`, `simulation.py`, `visualization.py`, `app.py`, `utils.py`, `requirements.txt`, `README.md`) to your Hugging Face Space repository.
+3.  **Configure `app.py`:** Ensure your `app.py` has the `iface.launch()` call at the end (as provided). Hugging Face Spaces automatically detects and runs Gradio apps.
+4.  **Monitor Build Logs:** Check the build logs in your Space settings for any dependency installation issues or errors.
+5.  **Access the App:** Once successfully built, your Gradio app will be live and accessible via the Space URL.
+
+## Example Usage
+
+After running `app.iface.launch()` in Colab, navigate to the provided URL. You will see a Gradio interface where you can adjust parameters:
+
+- **Number of Agents:** e.g., 3
+- **Steps:** e.g., 100
+- **Mutation Rate:** e.g., 0.05
+- **Drift Rate:** e.g., 0.02
+- **Random Seed:** e.g., 42
+
+Click the 'Submit' button to run the simulation. The interface will display:
+
+- Plots for individual agent Phi, Tau Effective, and Fitness over time.
+- Plots for System Coherence (average Phi) and System Stability (variance of Phi) over time.
+- A downloadable JSON file containing the final states of all agents.

agent.py

@@ -0,0 +1,48 @@
+import numpy as np
+import random
+
+class RFTAgent:
+    def __init__(self, phi_init, tier, mutation_rate, drift_rate):
+        self.phi = phi_init
+        self.tau_eff = 0.0 # Initial tau_eff, will be updated
+        self.tier = tier
+        self.fitness = 0.0 # Initial fitness, will be updated
+        self.mutation_rate = mutation_rate
+        self.drift_rate = drift_rate
+        self.history = {
+            'phi': [],
+            'tau_eff': [],
+            'tier': [],
+            'fitness': []
+        }
+
+    def update_tau(self):
+        # tau_eff = 0.5*phi + random noise (using uniform for simplicity, can be normal)
+        self.tau_eff = 0.5 * self.phi + random.uniform(-0.1, 0.1)
+
+    def mutate(self):
+        # phi = phi + random.normal(0, mutation_rate)
+        self.phi += np.random.normal(0, self.mutation_rate)
+
+    def drift(self):
+        # phi = phi + drift_rate * tau_eff
+        self.phi += self.drift_rate * self.tau_eff
+
+    def update_fitness(self):
+        # fitness = abs(phi) + abs(tau_eff) + tier*0.1
+        self.fitness = abs(self.phi) + abs(self.tau_eff) + self.tier * 0.1
+
+    def step(self):
+        self.mutate()
+        self.drift()
+        self.update_tau()
+        self.update_fitness()
+        self._log_history()
+
+    def _log_history(self):
+        self.history['phi'].append(self.phi)
+        self.history['tau_eff'].append(self.tau_eff)
+        self.history['tier'].append(self.tier)
+        self.history['fitness'].append(self.fitness)
+
+print("agent.py created successfully.")

app.py

@@ -0,0 +1,105 @@
+import gradio as gr
+import json
+import os
+import matplotlib.pyplot as plt # Kept for potential future gr.Plot use or if figures are handled directly
+from simulation import RFTSimulation
+from utils import export_json, seed_everything
+from IPython.display import Image, display # For Colab dev mode inline image display
+
+# Helper function to run simulation and generate plots/export data
+def run_simulation_and_plot(num_agents, steps, mutation_rate, drift_rate, seed=None):
+    if seed is not None:
+        seed_everything(seed)
+
+    # Instantiate simulation with save_plots=True, so it saves plots during its run() method
+    simulation = RFTSimulation(num_agents, steps, mutation_rate, drift_rate, save_plots=True)
+
+    # Run the simulation. The internal run method will save plots if save_plots=True.
+    # It returns all_agents_history, coherence_list, stability_list.
+    all_agents_history, coherence_list, stability_list = simulation.run()
+
+    # Prepare final agent states for JSON export
+    final_agent_states = []
+    for i, agent in enumerate(simulation.agents):
+        final_agent_states.append({
+            'id': i + 1,
+            'phi': agent.phi,
+            'tau_eff': agent.tau_eff,
+            'tier': agent.tier,
+            'fitness': agent.fitness
+        })
+
+    # Export JSON
+    json_filename = "final_agent_states.json"
+    export_json(final_agent_states, json_filename)
+
+    # Return filenames of the generated plots and the JSON for Gradio or dev mode display
+    plot_filenames = [
+        'phi_plot.png',
+        'tau_plot.png',
+        'fitness_plot.png',
+        'coherence_plot.png',
+        'stability_plot.png'
+    ]
+
+    return (*plot_filenames, json_filename)
+
+# Gradio Interface setup
+iface = gr.Interface(
+    fn=run_simulation_and_plot,
+    inputs=[
+        gr.Slider(1, 10, value=3, step=1, label="Number of Agents"),
+        gr.Slider(10, 500, value=100, step=10, label="Steps"),
+        gr.Slider(0.01, 0.5, value=0.05, step=0.01, label="Mutation Rate"),
+        gr.Slider(0.01, 0.5, value=0.02, step=0.01, label="Drift Rate"),
+        gr.Number(value=42, label="Random Seed (optional, leave empty for random)") # Clarified label
+    ],
+    outputs=[
+        gr.Image(label="Phi Plot"), # Changed to gr.Image to display saved PNGs
+        gr.Image(label="Tau Effective Plot"),
+        gr.Image(label="Fitness Plot"),
+        gr.Image(label="Coherence Plot"),
+        gr.Image(label="Stability Plot"),
+        gr.File(label="Exported Final Agent States (JSON)")
+    ],
+    title="RFT Agent Simulation Engine MVP",
+    description="Simulate RFT Agents and visualize their dynamics."
+)
+
+# Colab-friendly "dev mode" or Gradio launch logic
+# Check if running in Colab environment (simple heuristic)
+IN_COLAB = 'COLAB_GPU' in os.environ or 'Google' in os.environ.get('COLAB_CLOUD_PLATFORM', '')
+
+if IN_COLAB:
+    print("Running in Colab development mode (skipping Gradio launch).")
+    # Run the test simulation logic as per requirements
+    num_agents = 3
+    steps = 100
+    mutation_rate = 0.05
+    drift_rate = 0.02
+    seed = 42
+
+    print("\n--- Running Test Simulation in Dev Mode ---")
+    # Call the core simulation function. It will save plots and JSON.
+    plot_files_and_json_file = run_simulation_and_plot(num_agents, steps, mutation_rate, drift_rate, seed)
+    plot_files = plot_files_and_json_file[:-1]
+    json_file = plot_files_and_json_file[-1]
+
+    print("\nSimulation complete. Displaying plots and exported JSON path:")
+    for plot_file in plot_files:
+        print(f"  - {os.path.abspath(plot_file)}")
+        if os.path.exists(plot_file):
+            display(Image(filename=plot_file)) # Display inline in Colab
+        else:
+            print(f"Warning: Plot file {plot_file} not found for inline display.")
+
+    print(f"  - {os.path.abspath(json_file)}")
+    print(f"Final agent states exported to {json_file}")
+    print("\n--- End of Test Simulation in Dev Mode ---")
+
+else:
+    print("Running Gradio interface. Call iface.launch() to start it.")
+    # For local development, uncomment this to launch Gradio:
+    # iface.launch()
+
+print("app.py updated successfully.")

requirements.txt

@@ -0,0 +1,5 @@
+matplotlib
+numpy
+gradio
+
+print("requirements.txt created successfully.")

simulation.py

@@ -0,0 +1,55 @@
+import numpy as np
+from agent import RFTAgent
+import visualization # Added import for visualization
+
+class RFTSimulation:
+    def __init__(self, num_agents, steps, mutation_rate, drift_rate, save_plots=False): # Added save_plots
+        self.agents = []
+        self.steps = steps
+        self.mutation_rate = mutation_rate
+        self.drift_rate = drift_rate
+        self.save_plots = save_plots # Stored save_plots
+        self.coherence_list = [] # Initialized coherence_list
+        self.stability_list = [] # Initialized stability_list
+
+        for _ in range(num_agents):
+            phi_init = np.random.uniform(-1, 1)
+            tier = np.random.randint(1, 5)
+            agent = RFTAgent(phi_init, tier, mutation_rate, drift_rate)
+            self.agents.append(agent)
+
+    def run(self):
+        for _ in range(self.steps):
+            for agent in self.agents:
+                agent.step()
+            # Append current coherence and stability after all agents have stepped
+            self.coherence_list.append(self.compute_coherence())
+            self.stability_list.append(self.compute_stability())
+
+        # Conditional plot saving
+        if self.save_plots:
+            all_agents_history = self.get_history()
+            visualization.plot_phi(all_agents_history, filename='phi_plot.png')
+            visualization.plot_tau(all_agents_history, filename='tau_plot.png')
+            visualization.plot_fitness(all_agents_history, filename='fitness_plot.png')
+            visualization.plot_coherence(self.coherence_list, filename='coherence_plot.png')
+            visualization.plot_stability(self.stability_list, filename='stability_plot.png')
+
+        return (self.get_history(), self.coherence_list, self.stability_list) # Modified return value
+
+    def get_history(self):
+        return [agent.history for agent in self.agents]
+
+    def compute_coherence(self):
+        # Average phi across agents at the current step
+        if not self.agents:
+            return 0.0
+        return np.mean([agent.phi for agent in self.agents])
+
+    def compute_stability(self):
+        # Variance of phi across agents at the current step
+        if not self.agents:
+            return 0.0
+        return np.var([agent.phi for agent in self.agents])
+
+print("simulation.py updated successfully.")

utils.py

@@ -0,0 +1,65 @@
+import json
+import numpy as np
+import random
+import os
+import zipfile
+
+def export_json(data, filename):
+    with open(filename, 'w') as f:
+        json.dump(data, f, indent=4)
+    print(f"Data exported to {filename}")
+
+def seed_everything(seed):
+    random.seed(seed)
+    np.random.seed(seed)
+    print(f"Random seeds set to {seed}")
+
+def zip_project(output_name="rft_simulation_engine.zip"):
+    files_to_zip = [
+        'agent.py',
+        'simulation.py',
+        'visualization.py',
+        'app.py',
+        'utils.py',
+        'requirements.txt',
+        'README.md',
+        'test_runner.py',
+        'final_agent_states.json',
+        'phi_plot.png',
+        'tau_plot.png',
+        'fitness_plot.png',
+        'coherence_plot.png',
+        'stability_plot.png'
+    ]
+
+    with zipfile.ZipFile(output_name, 'w') as zf:
+        for file in files_to_zip:
+            if os.path.exists(file):
+                zf.write(file)
+                print(f"Added {file} to {output_name}")
+            else:
+                print(f"Warning: {file} not found, skipping.")
+    print(f"Successfully created {output_name} containing all specified files.")
+
+def zip_huggingface_repo(output_name='rft_hf_repo.zip'):
+    """Creates a zip archive containing only the core project files for Hugging Face deployment."""
+    files_to_include = [
+        'agent.py',
+        'simulation.py',
+        'visualization.py',
+        'app.py',
+        'utils.py',
+        'requirements.txt',
+        'README.md'
+    ]
+
+    with zipfile.ZipFile(output_name, 'w') as zf:
+        for file in files_to_include:
+            if os.path.exists(file):
+                zf.write(file)
+                print(f"Added {file} to {output_name}")
+            else:
+                print(f"Warning: {file} not found, skipping for Hugging Face repo zip.")
+    print(f"Successfully created Hugging Face repository zip: {output_name}")
+
+print("utils.py updated successfully with new zip_huggingface_repo function.")

visualization.py

@@ -0,0 +1,65 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+def plot_phi(all_agents_history, filename=None):
+    plt.figure(figsize=(10, 6))
+    for i, agent_history in enumerate(all_agents_history):
+        plt.plot(agent_history['phi'], label=f'Agent {i+1} Phi')
+    plt.xlabel('Step')
+    plt.ylabel('Phi')
+    plt.title('Agent Phi Over Time')
+    plt.legend()
+    plt.grid(True)
+    if filename is not None:
+        plt.savefig(filename, dpi=300, bbox_inches='tight')
+    plt.close()
+
+def plot_tau(all_agents_history, filename=None):
+    plt.figure(figsize=(10, 6))
+    for i, agent_history in enumerate(all_agents_history):
+        plt.plot(agent_history['tau_eff'], label=f'Agent {i+1} Tau Eff')
+    plt.xlabel('Step')
+    plt.ylabel('Tau Effective')
+    plt.title('Agent Tau Effective Over Time')
+    plt.legend()
+    plt.grid(True)
+    if filename is not None:
+        plt.savefig(filename, dpi=300, bbox_inches='tight')
+    plt.close()
+
+def plot_fitness(all_agents_history, filename=None):
+    plt.figure(figsize=(10, 6))
+    for i, agent_history in enumerate(all_agents_history):
+        plt.plot(agent_history['fitness'], label=f'Agent {i+1} Fitness')
+    plt.xlabel('Step')
+    plt.ylabel('Fitness')
+    plt.title('Agent Fitness Over Time')
+    plt.legend()
+    plt.grid(True)
+    if filename is not None:
+        plt.savefig(filename, dpi=300, bbox_inches='tight')
+    plt.close()
+
+def plot_coherence(coherence_list, filename=None):
+    plt.figure(figsize=(10, 6))
+    plt.plot(coherence_list)
+    plt.xlabel('Step')
+    plt.ylabel('Average Phi')
+    plt.title('System Coherence Over Time (Average Phi)')
+    plt.grid(True)
+    if filename is not None:
+        plt.savefig(filename, dpi=300, bbox_inches='tight')
+    plt.close()
+
+def plot_stability(stability_list, filename=None):
+    plt.figure(figsize=(10, 6))
+    plt.plot(stability_list)
+    plt.xlabel('Step')
+    plt.ylabel('Variance of Phi')
+    plt.title('System Stability Over Time (Variance of Phi)')
+    plt.grid(True)
+    if filename is not None:
+        plt.savefig(filename, dpi=300, bbox_inches='tight')
+    plt.close()
+
+print("visualization.py updated successfully.")