GEMINI.md

Gemini Code Understanding

Project Overview

This project, "NecroFusion Coliseum," is a web-based research demo for multimodal model fusion. It is built using Python and the Gradio library for the user interface. The backend leverages several machine learning libraries, including PyTorch, Diffusers, and Transformers, to perform tasks related to image generation and model fusion.

The application allows users to:

• Generate images from text prompts using Stable Diffusion models.
• Experiment with LoRA (Low-Rank Adaptation) model fusion.
• Use an agent-guided system to evolve prompts over multiple generations.
• View a leaderboard of model fusion runs, ranked by image quality.
• Interact with the NecroFusion Agent, a chatbot that can perform tasks using natural language.

A paid tier subscription is planned for the future, which will unlock additional features, including access to more Stable Diffusion models.

Building and Running

To build and run this project locally, you will need to have Docker installed.

1. Clone the repository:

   git clone https://huggingface.co/spaces/OnyxMunk/NecroFusion-Coliseum
   cd NecroFusion-Coliseum
   

2. Build the Docker image:

   docker build -t necrofusion .
   

3. Run the Docker container:

   docker run -p 7860:7860 -e HF_TOKEN=your_token necrofusion
   

After running the container, the application will be accessible at http://localhost:7860.

NecroFusion Agent

The NecroFusion Agent is a chatbot that can perform tasks in the NecroFusion Coliseum using natural language. The agent can use the following tools:

• text_to_image_tool: This tool generates an image from a prompt and a model.
• lora_fusion_tool: This tool fuses two LoRA models with a given alpha value.
• prompt_evolution_tool: This tool evolves a prompt for a given number of generations.

You can interact with the agent by going to the "🤖 NecroFusion Agent" tab and typing in your request. For example:

• "Generate an image of a cat riding a skateboard using the dreamshaper-8 model."
• "Fuse the 'lora-a' and 'lora-b' models with an alpha of 0.5."
• "Evolve the prompt 'a beautiful landscape' for 3 generations."

Advertisements and Future Features

The Space includes several promotional messages to highlight upcoming features and draw users in:

• Main Page Banner: Promotes the new NecroFusion Agent and hints at Pro features and more models.
• LoRA Fusion Tab: Advertises advanced LoRA fusion strategies and more adapter models coming soon.
• Prompt Evolution Tab: Highlights upcoming advanced agent graph visualizations and custom evolution strategies.
• Text to Image Tab (Model Dropdown): Indicates specific models are reserved for a "Paid Tier - Coming Soon."

Hugging Face Agent System

The project incorporates a specialized 7-agent swarm for prompt engineering, code quality, and deployment optimization. Each agent is defined by a modular system prompt with specific focus areas and measurable outcomes.

Agent Role	Focus Area	Measurable Outcome
PythonCore	High-performance HF Python	Pythonic Efficiency Index (PEI)
StyleGuardian	PEP 8 & Clean Code	PEP 8 Compliance Score
DependencyMaster	requirements.txt Optimization	Dependency Health Score
ModularityArchitect	Separation of Concerns	Modularity Ratio
GradioUIAgent	UI/UX & Performance	UX Friction Score
DockerDeploy	Container Optimization	Image Optimization Ratio
TestingInitiator	Reliability & QA	Test Coverage Percentage

The system prompts for these agents are located in the prompts/ directory.

Development Conventions

• Language: The project is written in Python.
• Styling: The code follows the general conventions of Python, with clear and descriptive variable and function names.
• Dependencies: Python dependencies are listed in requirements.txt.
• Modularity: The code is organized into modules. For example, the leaderboard.py module encapsulates all the logic for the leaderboard feature.
• UI: The user interface is built using the Gradio library. The UI code is located in app.py.
• Containerization: The project uses a Dockerfile for containerization, which is based on a Hugging Face-provided base image.
• Testing: There are no explicit tests in the provided files.

TODO: Add a section on testing practices if any are introduced.