README.md

---
title: RFT Agent Simulation Engine
emoji: 🧪
colorFrom: blue
colorTo: purple
sdk: gradio
app_file: app.py
pinned: false
---


# 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.

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference