subsequence 0.6.4__py3-none-any.whl

subsequence/chord_graphs/dorian_minor.py

@@ -0,0 +1,127 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+WEIGHT_STRONG = subsequence.chord_graphs.WEIGHT_STRONG
+WEIGHT_MEDIUM = subsequence.chord_graphs.WEIGHT_MEDIUM
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+
+# Dorian-specific weight for the signature i ↔ IV plagal motion.
+WEIGHT_DORIAN = 5
+
+
+class DorianMinor (subsequence.chord_graphs.ChordGraph):
+
+	"""Dorian-flavored minor harmony with a natural sixth degree.
+
+	The natural 6th (instead of the aeolian b6) gives minor harmony a
+	warmer, more hopeful quality. The IV chord (major subdominant in a
+	minor key) is the defining Dorian sound. No harmonic-minor dominant V
+	is used - the graph stays purely modal.
+
+	Good for lo-fi, neo-soul, chill electronic, jazz, and funk.
+	"""
+
+	def __init__ (self, include_dominant_7th: bool = False) -> None:
+
+		"""Configure whether to include dominant seventh chords.
+
+		Defaults to False because Dorian is modal - dominant 7ths
+		introduce functional tonal pull that weakens the modal feel.
+		"""
+
+		self.include_dominant_7th = include_dominant_7th
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a Dorian minor-key graph for the given key."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Dorian scale: 0, 2, 3, 5, 7, 9, 10
+		# Degrees:      i, ii, bIII, IV, v, vi°, bVII
+		tonic = subsequence.chords.Chord(root_pc=key_pc, quality="minor")
+		supertonic = subsequence.chords.Chord(root_pc=(key_pc + 2) % 12, quality="minor")
+		mediant = subsequence.chords.Chord(root_pc=(key_pc + 3) % 12, quality="major")
+		subdominant = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="major")
+		natural_dominant = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="minor")
+		submediant_dim = subsequence.chords.Chord(root_pc=(key_pc + 9) % 12, quality="diminished")
+		subtonic = subsequence.chords.Chord(root_pc=(key_pc + 10) % 12, quality="major")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- The Dorian signature: i ↔ IV ---
+		graph.add_transition(tonic, subdominant, WEIGHT_DORIAN)
+		graph.add_transition(subdominant, tonic, WEIGHT_DORIAN)
+
+		# --- Tonic departures ---
+		graph.add_transition(tonic, supertonic, WEIGHT_COMMON)
+		graph.add_transition(tonic, subtonic, WEIGHT_COMMON)
+		graph.add_transition(tonic, natural_dominant, WEIGHT_WEAK)
+		graph.add_transition(tonic, mediant, WEIGHT_WEAK)
+
+		# --- Supertonic departures ---
+		graph.add_transition(supertonic, natural_dominant, WEIGHT_MEDIUM)
+		graph.add_transition(supertonic, subdominant, WEIGHT_COMMON)
+		graph.add_transition(supertonic, tonic, WEIGHT_WEAK)
+
+		# --- Mediant (bIII) departures ---
+		graph.add_transition(mediant, subdominant, WEIGHT_COMMON)
+		graph.add_transition(mediant, subtonic, WEIGHT_COMMON)
+		graph.add_transition(mediant, tonic, WEIGHT_WEAK)
+
+		# --- Subdominant departures (beyond → tonic) ---
+		graph.add_transition(subdominant, natural_dominant, WEIGHT_COMMON)
+		graph.add_transition(subdominant, subtonic, WEIGHT_WEAK)
+		graph.add_transition(subdominant, submediant_dim, WEIGHT_WEAK)	# IV → vi° (passing dim; vi° resolves to v / i)
+
+		# --- Natural dominant (v) departures ---
+		graph.add_transition(natural_dominant, tonic, WEIGHT_MEDIUM)
+		graph.add_transition(natural_dominant, subdominant, WEIGHT_COMMON)
+		graph.add_transition(natural_dominant, mediant, WEIGHT_WEAK)
+
+		# --- Subtonic (bVII) departures ---
+		graph.add_transition(subtonic, tonic, WEIGHT_MEDIUM)
+		graph.add_transition(subtonic, subdominant, WEIGHT_COMMON)
+		graph.add_transition(subtonic, supertonic, WEIGHT_WEAK)
+
+		# --- Submediant dim (vi°) connectors ---
+		graph.add_transition(submediant_dim, natural_dominant, WEIGHT_MEDIUM)
+		graph.add_transition(submediant_dim, tonic, WEIGHT_WEAK)
+
+		if self.include_dominant_7th:
+			# Harmonic minor dominant - optional tonal color.
+			dominant_7th = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="dominant_7th")
+
+			graph.add_transition(natural_dominant, dominant_7th, WEIGHT_WEAK)
+			graph.add_transition(dominant_7th, tonic, WEIGHT_STRONG)
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return Dorian diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		diatonic: typing.Set[subsequence.chords.Chord] = set(
+			subsequence.chord_graphs.build_diatonic_chords(
+				subsequence.intervals.scale_pitch_classes(key_pc, "dorian"),
+				subsequence.intervals.DORIAN_QUALITIES
+			)
+		)
+
+		# Functional set: i, IV (Dorian signature), v, bVII.
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="minor"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="minor"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 10) % 12, quality="major"))
+
+		return diatonic, functional

subsequence/chord_graphs/functional_major.py

@@ -0,0 +1,102 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+WEIGHT_STRONG = subsequence.chord_graphs.WEIGHT_STRONG
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+WEIGHT_DECEPTIVE = subsequence.chord_graphs.WEIGHT_DECEPTIVE
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+
+
+class DiatonicMajor (subsequence.chord_graphs.ChordGraph):
+
+	"""Single-key functional major harmony graph."""
+
+	def __init__ (self, include_dominant_7th: bool = True) -> None:
+
+		"""Configure whether to include dominant seventh chords."""
+
+		self.include_dominant_7th = include_dominant_7th
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build the graph for a given major key."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		chords = subsequence.chord_graphs.build_diatonic_chords(
+			subsequence.intervals.scale_pitch_classes(key_pc, "ionian"),
+			subsequence.intervals.IONIAN_QUALITIES
+		)
+
+		tonic = chords[0]
+		supertonic = chords[1]
+		mediant = chords[2]
+		subdominant = chords[3]
+		dominant = chords[4]
+		submediant = chords[5]
+		leading = chords[6]
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		graph.add_transition(tonic, subdominant, WEIGHT_COMMON)
+		graph.add_transition(tonic, dominant, WEIGHT_COMMON)
+		graph.add_transition(tonic, submediant, WEIGHT_COMMON)
+		graph.add_transition(tonic, supertonic, WEIGHT_WEAK)
+
+		graph.add_transition(supertonic, dominant, WEIGHT_STRONG)
+
+		graph.add_transition(mediant, submediant, WEIGHT_COMMON)
+		graph.add_transition(mediant, subdominant, WEIGHT_WEAK)
+
+		graph.add_transition(subdominant, dominant, WEIGHT_STRONG, label="open")
+		graph.add_transition(subdominant, supertonic, WEIGHT_COMMON)
+		# The plagal close (IV → I, the "Amen") — outside strict functional
+		# motion, so weak; it also makes the "soft" cadence formula walkable.
+		graph.add_transition(subdominant, tonic, WEIGHT_WEAK, label="soft")
+
+		graph.add_transition(dominant, tonic, WEIGHT_STRONG, label="strong")
+		graph.add_transition(dominant, submediant, WEIGHT_DECEPTIVE, label="fakeout")
+
+		graph.add_transition(submediant, supertonic, WEIGHT_COMMON)
+		graph.add_transition(submediant, subdominant, WEIGHT_COMMON)
+		graph.add_transition(submediant, dominant, WEIGHT_WEAK)
+
+		graph.add_transition(leading, tonic, WEIGHT_STRONG)
+
+		# Make the two remaining diatonic triads reachable as occasional colour —
+		# they were defined with resolving edges but nothing led into them:
+		#   vi → iii  — the descending-thirds sequence (I–V–vi–iii–IV).
+		#   IV → vii° — predominant into the leading-tone triad (a dominant
+		#               substitute), which then resolves via its vii° → I edge.
+		graph.add_transition(submediant, mediant, WEIGHT_WEAK)
+		graph.add_transition(subdominant, leading, WEIGHT_WEAK)
+
+		if self.include_dominant_7th:
+			# Decision path: optional dominant seventh color for stronger cadences.
+			dominant_7th = subsequence.chords.Chord(root_pc=dominant.root_pc, quality="dominant_7th")
+
+			graph.add_transition(dominant, dominant_7th, WEIGHT_WEAK)
+			graph.add_transition(dominant_7th, tonic, WEIGHT_STRONG, label="strong")
+			graph.add_transition(dominant_7th, submediant, WEIGHT_DECEPTIVE, label="fakeout")
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return major-key diatonic and functional chord sets."""
+
+		return subsequence.chord_graphs._major_key_gravity_sets(key_name)
+
+
+def build_graph (key_name: str, include_dominant_7th: bool = True, minor_turnaround_weight: float = 0.0) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+	"""Build a functional major-key graph and return it with the tonic chord."""
+
+	graph_obj = DiatonicMajor(include_dominant_7th=include_dominant_7th)
+
+	return graph_obj.build(key_name)

subsequence/chord_graphs/hooktheory_major.py

@@ -0,0 +1,88 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+# Corpus-tendency transition table for a major key — relative frequencies in
+# the spirit of Hooktheory's Theorytab statistics (pop/rock songwriting), a
+# baked table, NOT a textbook functional-flow rulebook.  Each row is a
+# per-source distribution: the weights compare targets of ONE chord.  Diatonic
+# triads only (I ii iii IV V vi vii°), indexed 1–7 by scale degree.
+#
+# The well-known empirical tendencies it encodes: I leans to V/IV/vi; V resolves
+# strongly to I and deceptively to vi; IV→I and IV→V; vi→IV/V/ii; ii→V; iii is
+# rare and usually heads to vi or IV; vii°→I.
+_DEGREE_TRANSITIONS: typing.Dict[int, typing.List[typing.Tuple[int, int]]] = {
+	1: [(5, 8), (4, 8), (6, 7), (2, 4), (3, 2), (7, 1)],
+	2: [(5, 9), (4, 4), (1, 3), (6, 2), (7, 1), (3, 1)],
+	3: [(6, 7), (4, 7), (1, 3), (2, 2), (5, 2)],
+	4: [(1, 8), (5, 7), (6, 4), (2, 4), (3, 1)],
+	5: [(1, 9), (6, 7), (4, 6), (2, 2), (3, 1)],
+	6: [(4, 7), (5, 6), (2, 5), (1, 4), (3, 2)],
+	7: [(1, 9), (6, 3), (5, 2), (3, 1)],
+}
+
+
+class HooktheoryMajor (subsequence.chord_graphs.ChordGraph):
+
+	"""Major-key graph weighted by pop/rock corpus tendencies.
+
+	The same seven diatonic triads as :class:`DiatonicMajor`, but the
+	transition weights follow real songwriting frequencies (Hooktheory-informed)
+	rather than textbook function — so the walk gravitates to the four-chord
+	loops that dominate popular music (I–V–vi–IV and its rotations) and uses
+	iii sparingly.  Optionally colours the dominant with a seventh.
+	"""
+
+	def __init__ (self, include_dominant_7th: bool = True) -> None:
+
+		"""Configure whether to add a dominant-seventh colour on V."""
+
+		self.include_dominant_7th = include_dominant_7th
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build the corpus-weighted graph for a given major key."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		chords = subsequence.chord_graphs.build_diatonic_chords(
+			subsequence.intervals.scale_pitch_classes(key_pc, "ionian"),
+			subsequence.intervals.IONIAN_QUALITIES
+		)
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		for source_degree, targets in _DEGREE_TRANSITIONS.items():
+			source = chords[source_degree - 1]
+			for target_degree, weight in targets:
+				graph.add_transition(source, chords[target_degree - 1], weight)
+
+		if self.include_dominant_7th:
+			# A V7 colour the corpus reaches from V and that resolves home or
+			# deceptively, mirroring the V row's strongest moves.
+			dominant = chords[4]
+			dominant_7th = subsequence.chords.Chord(root_pc=dominant.root_pc, quality="dominant_7th")
+
+			graph.add_transition(dominant, dominant_7th, subsequence.chord_graphs.WEIGHT_MEDIUM)
+			graph.add_transition(dominant_7th, chords[0], 9)		# V7 → I
+			graph.add_transition(dominant_7th, chords[5], 7)		# V7 → vi (deceptive)
+			graph.add_transition(dominant_7th, chords[3], 6)		# V7 → IV
+
+		return graph, chords[0]
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return major-key diatonic and functional chord sets."""
+
+		return subsequence.chord_graphs._major_key_gravity_sets(key_name)
+
+
+def build_graph (key_name: str, include_dominant_7th: bool = True) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+	"""Build a corpus-weighted major-key graph and return it with the tonic chord."""
+
+	return HooktheoryMajor(include_dominant_7th=include_dominant_7th).build(key_name)

subsequence/chord_graphs/lydian_major.py

@@ -0,0 +1,130 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+WEIGHT_STRONG = subsequence.chord_graphs.WEIGHT_STRONG
+WEIGHT_MEDIUM = subsequence.chord_graphs.WEIGHT_MEDIUM
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+WEIGHT_DECEPTIVE = subsequence.chord_graphs.WEIGHT_DECEPTIVE
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+
+# Lydian-specific weight for the signature I ↔ II shimmer.
+WEIGHT_LYDIAN = 5
+
+
+class LydianMajor (subsequence.chord_graphs.ChordGraph):
+
+	"""Lydian-flavored major harmony with a raised fourth degree.
+
+	The raised 4th (#4) gives a bright, floating quality. The II chord
+	(major, a whole step above tonic) is the defining Lydian sound  - 
+	the I ↔ II "shimmer" is the strongest motion in the graph. The
+	natural IV chord is absent entirely, keeping the harmony purely modal.
+
+	Good for ambient, cinematic, and progressive electronic music.
+	"""
+
+	def __init__ (self, include_dominant_7th: bool = True) -> None:
+
+		"""Configure whether to include dominant seventh chords."""
+
+		self.include_dominant_7th = include_dominant_7th
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a Lydian major-key graph for the given key."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Lydian scale: 0, 2, 4, 6, 7, 9, 11
+		# Degrees:      I, II, iii, #iv°, V, vi, vii
+		tonic = subsequence.chords.Chord(root_pc=key_pc, quality="major")
+		supertonic = subsequence.chords.Chord(root_pc=(key_pc + 2) % 12, quality="major")
+		mediant = subsequence.chords.Chord(root_pc=(key_pc + 4) % 12, quality="minor")
+		sharp_four_dim = subsequence.chords.Chord(root_pc=(key_pc + 6) % 12, quality="diminished")
+		dominant = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="major")
+		submediant = subsequence.chords.Chord(root_pc=(key_pc + 9) % 12, quality="minor")
+		leading = subsequence.chords.Chord(root_pc=(key_pc + 11) % 12, quality="minor")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- The Lydian shimmer: I ↔ II ---
+		graph.add_transition(tonic, supertonic, WEIGHT_LYDIAN)
+		graph.add_transition(supertonic, tonic, WEIGHT_LYDIAN)
+
+		# --- Tonic departures ---
+		graph.add_transition(tonic, dominant, WEIGHT_COMMON)
+		graph.add_transition(tonic, submediant, WEIGHT_COMMON)
+		graph.add_transition(tonic, mediant, WEIGHT_WEAK)
+
+		# --- Supertonic departures (beyond → tonic) ---
+		graph.add_transition(supertonic, dominant, WEIGHT_COMMON)
+		graph.add_transition(supertonic, mediant, WEIGHT_WEAK)
+
+		# --- Mediant departures ---
+		graph.add_transition(mediant, submediant, WEIGHT_COMMON)
+		graph.add_transition(mediant, tonic, WEIGHT_WEAK)
+
+		# --- Dominant departures ---
+		graph.add_transition(dominant, tonic, WEIGHT_STRONG)
+		graph.add_transition(dominant, submediant, WEIGHT_DECEPTIVE)
+
+		# --- Submediant departures ---
+		graph.add_transition(submediant, supertonic, WEIGHT_COMMON)
+		graph.add_transition(submediant, dominant, WEIGHT_COMMON)
+		graph.add_transition(submediant, tonic, WEIGHT_WEAK)
+
+		# --- Leading tone (vii) departures ---
+		graph.add_transition(leading, tonic, WEIGHT_STRONG)
+		graph.add_transition(leading, supertonic, WEIGHT_WEAK)
+
+		# --- #iv° connectors ---
+		graph.add_transition(sharp_four_dim, dominant, WEIGHT_MEDIUM)
+		graph.add_transition(sharp_four_dim, tonic, WEIGHT_WEAK)
+
+		# Make the two diatonic chords that had only outgoing edges reachable, as
+		# occasional colour:
+		#   I → #iv° — passing into the signature raised-4 dim (→ V / I).
+		#   V → vii  — into the minor leading-tone triad, which resolves vii → I.
+		graph.add_transition(tonic, sharp_four_dim, WEIGHT_WEAK)
+		graph.add_transition(dominant, leading, WEIGHT_WEAK)
+
+		if self.include_dominant_7th:
+			dominant_7th = subsequence.chords.Chord(root_pc=dominant.root_pc, quality="dominant_7th")
+
+			graph.add_transition(dominant, dominant_7th, WEIGHT_WEAK)
+			graph.add_transition(dominant_7th, tonic, WEIGHT_STRONG)
+			graph.add_transition(dominant_7th, submediant, WEIGHT_DECEPTIVE)
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return Lydian diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		diatonic: typing.Set[subsequence.chords.Chord] = set(
+			subsequence.chord_graphs.build_diatonic_chords(
+				subsequence.intervals.scale_pitch_classes(key_pc, "lydian"),
+				subsequence.intervals.LYDIAN_QUALITIES
+			)
+		)
+
+		# Add dominant 7th to diatonic set.
+		dominant_7th = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="dominant_7th")
+		diatonic.add(dominant_7th)
+
+		# Functional set: I, II (Lydian signature), V.
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 2) % 12, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="major"))
+		functional.add(dominant_7th)
+
+		return diatonic, functional

subsequence/chord_graphs/mixolydian.py

@@ -0,0 +1,98 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+WEIGHT_STRONG = subsequence.chord_graphs.WEIGHT_STRONG
+WEIGHT_MEDIUM = subsequence.chord_graphs.WEIGHT_MEDIUM
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+WEIGHT_MIXOLYDIAN = 5
+
+
+class Mixolydian (subsequence.chord_graphs.ChordGraph):
+
+	"""Major-mode chord graph with a flat seventh degree.
+
+	Scale: 1, 2, 3, 4, 5, 6, b7.
+	Chords: I (major), ii (minor), iii° (diminished), IV (major),
+	v (minor), vi (minor), bVII (major).
+
+	The I ↔ bVII shuttle is the defining colour. The minor v avoids
+	dominant function, keeping progressions open and unresolved.
+	Common in EDM, synthwave, and rock-influenced electronic music.
+	"""
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a Mixolydian mode graph."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		tonic = subsequence.chords.Chord(root_pc=key_pc, quality="major")
+		supertonic = subsequence.chords.Chord(root_pc=(key_pc + 2) % 12, quality="minor")
+		mediant = subsequence.chords.Chord(root_pc=(key_pc + 4) % 12, quality="diminished")
+		subdominant = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="major")
+		minor_dominant = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="minor")
+		submediant = subsequence.chords.Chord(root_pc=(key_pc + 9) % 12, quality="minor")
+		flat_seven = subsequence.chords.Chord(root_pc=(key_pc + 10) % 12, quality="major")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- I ↔ bVII: the Mixolydian shuttle ---
+		graph.add_transition(tonic, flat_seven, WEIGHT_MIXOLYDIAN)
+		graph.add_transition(flat_seven, tonic, WEIGHT_MIXOLYDIAN)
+
+		# --- Plagal motion ---
+		graph.add_transition(subdominant, tonic, WEIGHT_STRONG)
+		graph.add_transition(tonic, subdominant, WEIGHT_MEDIUM)
+
+		# --- bVII ↔ IV: common EDM chain ---
+		graph.add_transition(flat_seven, subdominant, WEIGHT_MEDIUM)
+		graph.add_transition(subdominant, flat_seven, WEIGHT_COMMON)
+
+		# --- Minor dominant ---
+		graph.add_transition(minor_dominant, tonic, WEIGHT_MEDIUM)
+		graph.add_transition(tonic, minor_dominant, WEIGHT_COMMON)
+
+		# --- Supertonic ---
+		graph.add_transition(supertonic, minor_dominant, WEIGHT_COMMON)
+		graph.add_transition(supertonic, subdominant, WEIGHT_COMMON)
+		graph.add_transition(tonic, supertonic, WEIGHT_WEAK)
+
+		# --- Submediant ---
+		graph.add_transition(submediant, flat_seven, WEIGHT_COMMON)
+		graph.add_transition(submediant, subdominant, WEIGHT_WEAK)
+		graph.add_transition(tonic, submediant, WEIGHT_WEAK)
+		graph.add_transition(minor_dominant, submediant, WEIGHT_WEAK)
+
+		# --- Mediant (diminished - rare, colour) ---
+		graph.add_transition(mediant, subdominant, WEIGHT_WEAK)
+		graph.add_transition(mediant, tonic, WEIGHT_WEAK)
+		graph.add_transition(supertonic, mediant, WEIGHT_WEAK)
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return Mixolydian diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		diatonic: typing.Set[subsequence.chords.Chord] = set(
+			subsequence.chord_graphs.build_diatonic_chords(
+				subsequence.intervals.scale_pitch_classes(key_pc, "mixolydian"),
+				subsequence.intervals.MIXOLYDIAN_QUALITIES
+			)
+		)
+
+		# Functional: I, IV, bVII (the primary colour chords).
+		functional: typing.Set[subsequence.chords.Chord] = set()
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 10) % 12, quality="major"))
+
+		return diatonic, functional

subsequence/chord_graphs/phrygian_minor.py

@@ -0,0 +1,76 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.weighted_graph
+
+
+WEIGHT_STRONG = subsequence.chord_graphs.WEIGHT_STRONG
+WEIGHT_MEDIUM = subsequence.chord_graphs.WEIGHT_MEDIUM
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+
+
+class PhrygianMinor (subsequence.chord_graphs.ChordGraph):
+
+	"""Minor chord graph utilizing Phrygian and Plagal motion.
+
+	Consists of four minor chords: i, bii, iv, v.
+	The Phrygian bII (major) is replaced here by a minor bii for a darker,
+	more modal sound often found in techno and minimal repetition.
+	The Phrygian cadence (bii -> i) is the primary resolution.
+	"""
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a minimal all-minor Phrygian graph."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Four chords, all minor.
+		tonic = subsequence.chords.Chord(root_pc=key_pc, quality="minor")
+		flat_two = subsequence.chords.Chord(root_pc=(key_pc + 1) % 12, quality="minor")
+		subdominant = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="minor")
+		natural_dominant = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="minor")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- Tonic departures ---
+		graph.add_transition(tonic, flat_two, WEIGHT_MEDIUM)
+		graph.add_transition(tonic, subdominant, WEIGHT_MEDIUM)
+		graph.add_transition(tonic, natural_dominant, WEIGHT_WEAK)
+
+		# --- Phrygian cadence: bii -> i (strongest resolution) ---
+		graph.add_transition(flat_two, tonic, WEIGHT_STRONG)
+		graph.add_transition(flat_two, natural_dominant, WEIGHT_WEAK)
+
+		# --- Plagal motion ---
+		graph.add_transition(subdominant, tonic, WEIGHT_STRONG)
+		graph.add_transition(subdominant, natural_dominant, WEIGHT_MEDIUM)
+
+		# --- Natural dominant departures ---
+		graph.add_transition(natural_dominant, tonic, WEIGHT_MEDIUM)
+		graph.add_transition(natural_dominant, flat_two, WEIGHT_WEAK)
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return all-minor diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# All four chords are diatonic to this palette.
+		diatonic: typing.Set[subsequence.chords.Chord] = set()
+
+		for interval in [0, 1, 5, 7]:
+			root_pc = (key_pc + interval) % 12
+			diatonic.add(subsequence.chords.Chord(root_pc=root_pc, quality="minor"))
+
+		# Functional set: tonic, bii (Phrygian), subdominant.
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		for interval in [0, 1, 5]:
+			root_pc = (key_pc + interval) % 12
+			functional.add(subsequence.chords.Chord(root_pc=root_pc, quality="minor"))
+
+		return diatonic, functional