metaphor-machine 1.0.1

Algorithmic generation and optimization of AI music style prompts

Metaphor Machine

Algorithmic generation and optimization of AI music style prompts.

Metaphor Machine creates structured 5-slot style descriptions for AI music platforms like Suno and Producer.ai, then optimizes them through genetic and Bayesian algorithms to discover high-performing prompt patterns.

Installation

From source, with optimization extras:

git clone [e-mail]:stayen/metaphor-machine.git
cd module
pip -e ".[optimization]"

(see also below, for other installation modes)

From Pypi:

pip install metaphor-machine

With optimization extras:

pip install metaphor-machine[optimization]  # numpy, scipy
pip install metaphor-machine[llm]           # anthropic, openai
pip install metaphor-machine[all]           # everything

Quick Start

Basic Generation

from metaphor_machine import StyleComponents, MetaphorGenerator

# Load component pools
components = StyleComponents.from_yaml("style_components.yaml")

# Create generator with seed for reproducibility
generator = MetaphorGenerator(components, seed=42)

# Generate a single metaphor
metaphor = generator.generate_single()
print(metaphor)
# → "dark synthwave, whispered mantras, spiraling synths, neon-alley reverb, dread crescendo"

# Generate a 3-act chain
chain = generator.generate_chain()
print(chain.to_suno_style())
# → "Intro: cinematic orchestral... → Mid: voice opens into... → Outro: melody dissolves..."

Optimization (v1.0)

from metaphor_machine.optimization import (
    GeneticOptimizer,
    GeneticConfig,
    RuleBasedEvaluator,
)

# Create fitness evaluator
evaluator = RuleBasedEvaluator(
    preferred_terms=["darkwave", "ethereal", "haunting"],
    avoided_terms=["pop", "bright"],
)

# Configure genetic algorithm
config = GeneticConfig(
    population_size=30,
    generations=50,
    elite_size=2,
    mutation_rate=0.2,
)

# Run optimization
optimizer = GeneticOptimizer(generator, evaluator, config)
best = optimizer.run(verbose=True)

print(f"Best: {best.metaphor}")
print(f"Score: {best.score:.3f}")

Corpus Storage

from metaphor_machine.corpus import SQLiteCorpus, CorpusEntry

# Store optimization results
corpus = SQLiteCorpus("prompts.db")

for individual in optimizer.get_top_n(20):
    entry = CorpusEntry.from_metaphor(
        individual.metaphor,
        fitness_score=individual.score,
        tags={"genetic", "darkwave"},
        source="genetic_optimizer",
    )
    corpus.add(entry)

# Query high-performing prompts
results = corpus.query(min_score=0.8, tags={"darkwave"})
for entry in results:
    print(f"[{entry.fitness_score:.2f}] {entry.metaphor_text}")

corpus.close()

Metaphor Structure

Each metaphor consists of 5 slots:

Slot	Purpose	Example
Genre Anchor	Base genre (with optional prefix)	"dark synthwave", "japanese house"
Intimate Gesture	Vocal/lead behavior	"whispered mantras"
Dynamic Tension	Motion and energy	"spiraling synths"
Sensory Bridge	Environment/space	"neon-alley reverb"
Emotional Anchor	Feeling/resolution	"dread crescendo"

Genres are organized by family (electronic, hip-hop/urban, world/ethnic, rock/guitar, traditional/acoustic) with optional modifier prefixes (mood, intensity, style, regional, location, instruments).

The combinatorial space exceeds 35 trillion unique combinations.

Optimization Methods

Genetic Algorithm

Evolutionary search through selection, crossover, and mutation:

• Selection: Tournament, roulette, rank, truncation
• Crossover: Single-point, two-point, uniform (slot-level)
• Mutation: Per-slot probability replacement
• Elitism: Preserve top performers across generations

Bayesian Optimization

Sample-efficient search for expensive evaluations (human rating, actual audio generation):

• Surrogate model: RBF kernel interpolation
• Acquisition functions: Expected Improvement, UCB, Thompson sampling
• External observation: Support for async evaluation workflows

Fitness Evaluators

Evaluator	Speed	Use Case
RuleBasedEvaluator	Fast	Keyword matching, length, diversity
SemanticCoherenceEvaluator	Fast	Slot compatibility scoring
LLMEvaluator	Slow	Claude/GPT quality assessment
HumanFeedbackEvaluator	Slow	Interactive ground truth
CompositeEvaluator	Varies	Weighted combination

CLI Usage

# Generate single metaphor
mm generate

# Generate with seed
mm generate --seed 42

# Generate diverse batch
mm batch --count 10 --min-distance 3

# Generate 3-act chain
mm chain --seed 42

Architecture

metaphor_machine/
├── core/              # Metaphor, Generator, Chain
├── schemas/           # Pydantic models, config
├── optimization/      # Genetic, Bayesian, Fitness
├── corpus/            # SQLite/JSON storage
└── cli/               # Click commands

Roadmap

• v0.9.9: Core generation engine, CLI, seed reproducibility
• v1.0.0: Optimization layer (genetic, Bayesian, corpus)
• v1.1: Variation engine (Markov chains, latent navigation)
• v1.2: Audio feedback loop (librosa features, embedding similarity)

License

MIT

Links

• GitHub
• PyPI