README.md

metadata

title: 'RFT Agent Simulation Engine '
emoji: 🌖
colorFrom: yellow
colorTo: green
sdk: gradio
sdk_version: 6.6.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