README.md

---
title: 'RFT Agent Simulation Engine '
emoji: 🌖
colorFrom: yellow
colorTo: green
sdk: gradio
sdk_version: 4.26.0
app_file: app.py
pinned: false
license: other
short_description: Agent drift, torque & coherence 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