Skip to content

Why Plugins

Jump to bottom
smattymatty edited this page Aug 25, 2025 · 1 revision

Why Plugins? The 80-20 Architecture Philosophy

Small core, big plugin system - this is how we build tools that adapt to humans, not the other way around.

The Problem with Monolithic Tools

Traditional performance testing tools suffer from:

  • One-size-fits-none: Beginners are overwhelmed, experts are slowed down
  • Feature bloat: Every feature is loaded even if unused
  • Rigid workflows: Can't adapt to different skill levels
  • Poor maintainability: Core changes affect everything

The Plugin Solution

Django Mercury's plugin architecture embodies the 80-20 Human-in-the-Loop philosophy:

Small Core (20%)

The core only handles:

  • Basic test execution
  • Performance metric collection
  • Plugin orchestration
  • Profile management

Rich Plugin Ecosystem (80%)

Plugins provide everything else:

  • Educational features
  • Discovery mechanisms
  • Interactive interfaces
  • Reporting formats
  • AI integrations

Three Audiences, Three Experiences

The plugin system enables Mercury to serve three distinct audiences through profiles:

🎓 Students Get Education

mercury-test --profile student

Enabled plugins:

  • learn: Interactive quizzes and tutorials
  • wizard: Guided test selection
  • hints: Performance tips after tests
  • discovery: Helpful error messages

Experience: Slower, educational, builds understanding

💼 Experts Get Efficiency

mercury-test --profile expert

Enabled plugins:

  • discovery: Fast project location only

Disabled:

  • No interruptions
  • No tutorials
  • No hints

Experience: Fast, direct, professional

🤖 Agents Get Structure

mercury-test --profile agent

Enabled plugins:

  • discovery: Automated project finding

Output:

  • Structured JSON
  • Machine-readable errors
  • Automation-friendly

Experience: Predictable, parseable, integrable

Benefits of Plugin Architecture

1. Progressive Complexity

Users start with educational plugins and gradually move to expert mode:

# Student starting out
[profiles.student]
plugins.enabled = ["discovery", "wizard", "learn", "hints"]

# Growing expertise - fewer educational interruptions
[profiles.intermediate]
plugins.enabled = ["discovery", "wizard", "hints"]

# Expert - just the essentials
[profiles.expert]
plugins.enabled = ["discovery"]

2. Maintainable Codebase

Each plugin is self-contained:

# plugin_hints.py - completely independent
class HintsPlugin(MercuryPlugin):
    name = "hints"
    audiences = ["student"]
    
    def post_test_hook(self, args, result, elapsed):
        if elapsed > 100:
            self.show_performance_tips()

3. Community Extensibility

Anyone can add features without touching core:

# Custom plugin for your team
class TeamStandardsPlugin(MercuryPlugin):
    name = "team_standards"
    
    def post_test_hook(self, args, result, elapsed):
        self.check_team_performance_standards()
        self.generate_team_report()

4. Performance Optimization

Only load what you need:

# Lazy loading based on profile
if "learn" in enabled_plugins:
    from .learn import LearnPlugin  # Heavy educational content
    
# Expert mode never loads educational content

Real-World Example: Discovery Plugin

The discovery plugin demonstrates adaptable behavior:

For Students

def smart_find_manage_py(self, args):
    location = self._search_for_project()
    
    if not location:
        # Educational error message
        print("❌ Could not find Django project")
        print("💡 Suggestions:")
        print("  • Make sure you're in a Django project")
        print("  • Look for a manage.py file")
        print("  • Try: mercury-test --search-deep")
        print("📚 Learn about Django structure: [link]")

For Experts

def smart_find_manage_py(self, args):
    location = self._search_for_project()
    
    if not location:
        # Concise error
        print("No Django project found")
        return None

For Agents

def smart_find_manage_py(self, args):
    location = self._search_for_project()
    
    return {
        "status": "error" if not location else "success",
        "location": str(location) if location else None,
        "search_paths": self._get_searched_paths()
    }

Plugin Development Principles

1. Audience Awareness

Every plugin should know its audience:

class MercuryPlugin:
    audiences = ["student", "expert", "agent"]  # Who is this for?
    complexity_level = 1  # 1-5 scale

2. Progressive Disclosure

Start simple, reveal complexity as needed:

def show_results(self, results, verbosity=1):
    if verbosity == 1:
        print(f"Found {len(results)} issues")
    elif verbosity == 2:
        for issue in results:
            print(f"- {issue.type}: {issue.location}")
    else:
        # Full details with explanations

3. Fail Gracefully

Plugins should never break the core:

def execute(self, args):
    try:
        return self._do_work(args)
    except Exception as e:
        logger.warning(f"Plugin {self.name} failed: {e}")
        return 0  # Don't crash

Configuration Philosophy

Profile-Based Loading

# mercury_config.toml
[mercury]
profile = "student"  # This determines everything

[profiles.student]
plugins.enabled = ["discovery", "wizard", "learn", "hints"]
educational_mode = true
verbosity = "high"

[profiles.expert]
plugins.enabled = ["discovery"]
educational_mode = false
verbosity = "low"

Dynamic Adaptation

Plugins can be enabled/disabled per run:

# Expert wanting to learn something new
mercury-test --learn  # Temporarily enable learn plugin

# Student wanting faster results
mercury-test --no-hints  # Temporarily disable hints

The Human-in-the-Loop Advantage

Plugins preserve human wisdom while enabling automation:

Educational Plugins (Human Learning)

  • learn: Builds understanding through quizzes
  • wizard: Guides decision-making
  • hints: Provides contextual tips

Automation Plugins (Machine Efficiency)

  • discovery: Automates project finding
  • Future: auto_fix: Safe automatic fixes
  • Future: ci_reporter: CI/CD integration

Hybrid Plugins (Best of Both)

  • Future: mentor: AI-assisted learning
  • Future: reviewer: Automated code review with explanations

Why This Matters

The plugin architecture ensures Django Mercury:

  1. Grows with users - From student to expert
  2. Adapts to contexts - Development, CI/CD, education
  3. Preserves learning - Never fully automates understanding
  4. Enables innovation - Community can extend freely

Next Steps

Remember: The best tools adapt to humans, not the other way around. That's why we build with plugins.

Django Mercury Wiki

🏠 Overview

Clone this wiki locally