Update README.md

README.md

@@ -11,4 +11,199 @@ 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