subsequence 0.6.4__py3-none-any.whl

subsequence/harmonic_state.py

@@ -0,0 +1,352 @@
+import random
+import typing
+
+import subsequence.chord_graphs.aeolian_minor
+import subsequence.chord_graphs.chromatic_mediant
+import subsequence.chord_graphs.diminished
+import subsequence.chord_graphs.dorian_minor
+import subsequence.chord_graphs.functional_major
+import subsequence.chord_graphs.hooktheory_major
+import subsequence.chord_graphs.lydian_major
+import subsequence.chord_graphs.mixolydian
+import subsequence.chord_graphs.phrygian_minor
+import subsequence.chord_graphs.suspended
+import subsequence.chord_graphs.turnaround_global
+import subsequence.chord_graphs.whole_tone
+import subsequence.chords
+import subsequence.weighted_graph
+
+
+DEFAULT_ROOT_DIVERSITY: float = 0.4
+
+
+
+# ---------------------------------------------------------------------------
+# Graph style registry — see _resolve_graph_style() below.
+# To register a new chord graph, add it to _D7_STYLES or _SIMPLE_STYLES there.
+# ---------------------------------------------------------------------------
+
+
+def _resolve_graph_style (
+	style: str,
+	include_dominant_7th: bool,
+	minor_turnaround_weight: float
+) -> subsequence.chord_graphs.ChordGraph:
+
+	"""Create a ChordGraph instance from a string style name and legacy parameters."""
+
+	if style in ("diatonic_major", "functional_major"):
+		return subsequence.chord_graphs.functional_major.DiatonicMajor(
+			include_dominant_7th = include_dominant_7th
+		)
+
+	if style in ("turnaround", "turnaround_global"):
+		return subsequence.chord_graphs.turnaround_global.TurnaroundModulation(
+			include_dominant_7th = include_dominant_7th,
+			minor_turnaround_weight = minor_turnaround_weight
+		)
+
+	# Styles with only an include_dominant_7th parameter.
+	_D7_STYLES: typing.Dict[
+		str,
+		typing.Callable[[bool], subsequence.chord_graphs.ChordGraph]
+	] = {
+		"aeolian_minor": subsequence.chord_graphs.aeolian_minor.AeolianMinor,
+		"lydian_major":  subsequence.chord_graphs.lydian_major.LydianMajor,
+		"dorian_minor":  subsequence.chord_graphs.dorian_minor.DorianMinor,
+		"hooktheory_major": subsequence.chord_graphs.hooktheory_major.HooktheoryMajor,
+		"pop_major": subsequence.chord_graphs.hooktheory_major.HooktheoryMajor,
+	}
+	if style in _D7_STYLES:
+		return _D7_STYLES[style](include_dominant_7th)
+
+	# Styles that take no extra parameters.
+	_SIMPLE_STYLES: typing.Dict[
+		str,
+		typing.Callable[[], subsequence.chord_graphs.ChordGraph]
+	] = {
+		"phrygian_minor":    subsequence.chord_graphs.phrygian_minor.PhrygianMinor,
+		"chromatic_mediant": subsequence.chord_graphs.chromatic_mediant.ChromaticMediant,
+		"suspended":         subsequence.chord_graphs.suspended.Suspended,
+		"mixolydian":        subsequence.chord_graphs.mixolydian.Mixolydian,
+		"whole_tone":        subsequence.chord_graphs.whole_tone.WholeTone,
+		"diminished":        subsequence.chord_graphs.diminished.Diminished,
+	}
+	if style in _SIMPLE_STYLES:
+		return _SIMPLE_STYLES[style]()
+
+	raise ValueError(f"Unknown graph style: {style!r}")
+
+
+
+class HarmonicState:
+
+	"""Holds the current chord and key context for the composition."""
+
+	def __init__ (
+		self,
+		key_name: str,
+		graph_style: typing.Union[str, subsequence.chord_graphs.ChordGraph] = "functional_major",
+		include_dominant_7th: bool = True,
+		key_gravity_blend: float = 1.0,
+		nir_strength: float = 0.5,
+		minor_turnaround_weight: float = 0.0,
+		root_diversity: float = DEFAULT_ROOT_DIVERSITY,
+		rng: typing.Optional[random.Random] = None
+	) -> None:
+
+		"""
+		Initialize the harmonic state using a chord transition graph.
+
+		Parameters:
+			key_name: Note name for the key (e.g., ``"C"``, ``"F#"``).
+			graph_style: Built-in style name or a custom ``ChordGraph`` instance.
+			include_dominant_7th: Include V7 chords in the graph (default True).
+			key_gravity_blend: Balance between functional and diatonic gravity
+				(0.0 = functional only, 1.0 = full diatonic). Default 1.0.
+			nir_strength: Melodic inertia from Narmour's Implication-Realization
+				model (0.0 = off, 1.0 = full). Default 0.5.
+			minor_turnaround_weight: For turnaround style, weight toward minor
+				turnarounds (0.0 to 1.0). Default 0.0.
+			root_diversity: Root-repetition damping factor (0.0 to 1.0). Each
+				recent chord sharing a candidate's root pitch class multiplies
+				the transition weight by this factor. At the default (0.4), one
+				recent same-root chord reduces the weight to 40%; two reduce it
+				to 16%. Set to 1.0 to disable the penalty entirely. Default 0.4.
+			rng: Optional seeded ``random.Random`` for deterministic playback.
+		"""
+
+		if key_gravity_blend < 0 or key_gravity_blend > 1:
+			raise ValueError("Key gravity blend must be between 0 and 1")
+
+		if nir_strength < 0 or nir_strength > 1:
+			raise ValueError("NIR strength must be between 0 and 1")
+
+		if minor_turnaround_weight < 0 or minor_turnaround_weight > 1:
+			raise ValueError("Minor turnaround weight must be between 0 and 1")
+
+		if root_diversity < 0 or root_diversity > 1:
+			raise ValueError("Root diversity must be between 0 and 1")
+
+		self.key_name = key_name
+		self.key_root_pc = subsequence.chords.key_name_to_pc(key_name)
+		self.key_gravity_blend = key_gravity_blend
+		self.nir_strength = nir_strength
+		self.root_diversity = root_diversity
+		self.minor_turnaround_weight = minor_turnaround_weight
+
+
+		if isinstance(graph_style, str):
+			chord_graph = _resolve_graph_style(graph_style, include_dominant_7th, minor_turnaround_weight)
+
+		else:
+			chord_graph = graph_style
+
+		self.graph, tonic = chord_graph.build(key_name)
+		self._diatonic_chords, self._function_chords = chord_graph.gravity_sets(key_name)
+
+		self.rng = rng or random.Random()
+		self.current_chord = tonic
+		self.history: typing.List[subsequence.chords.Chord] = []
+
+
+	def _calculate_nir_score (self, source: subsequence.chords.Chord, target: subsequence.chords.Chord) -> float:
+
+		"""
+		Calculate a Narmour Implication-Realization (NIR) score for a transition.
+		Returns a multiplier (default 1.0, >1.0 for boost).
+		"""
+
+		# step() appends the current chord to history BEFORE choosing, so
+		# history[-1] is always the source itself; the implication interval
+		# needs the chord we arrived FROM, which is history[-2].  (Using
+		# history[-1] here was the pre-2026-06 bug that left the reversal
+		# and continuation rules permanently inert.)
+		if len(self.history) < 2:
+			return 1.0
+
+		prev = self.history[-2]
+
+		# Calculate interval from Prev -> Source (The "Implication" generator)
+		# Using shortest-path distance in Pitch Class space (-6 to +6)
+		prev_diff = (source.root_pc - prev.root_pc) % 12
+		if prev_diff > 6:
+			prev_diff -= 12
+
+		prev_interval = abs(prev_diff)
+		prev_direction = 1 if prev_diff > 0 else -1 if prev_diff < 0 else 0
+
+		# Calculate interval from Source -> Target (The "Realization")
+		target_diff = (target.root_pc - source.root_pc) % 12
+		if target_diff > 6:
+			target_diff -= 12
+
+		target_interval = abs(target_diff)
+		target_direction = 1 if target_diff > 0 else -1 if target_diff < 0 else 0
+
+		score = 1.0
+
+		# --- Rule A: Reversal (Gap Fill) ---
+		# If the previous step was a large leap (> 4 on the 0–6 pitch-class
+		# shortest-path scale, where a tritone is 6), expect a direction change.
+		if prev_interval > 4:
+			# Expect change in direction
+			if target_direction != prev_direction and target_direction != 0:
+				score += 0.5
+
+			# Expect smaller interval (Gap Fill)
+			if target_interval < 4:
+				score += 0.3
+
+		# --- Rule B: Process (Continuation/Inertia) ---
+		# If previous was Small Step (< 3 semitones), expect similarity.
+		elif prev_interval > 0 and prev_interval < 3:
+			# Expect same direction
+			if target_direction == prev_direction:
+				score += 0.4
+
+			# Expect similar size
+			if abs(target_interval - prev_interval) <= 1:
+				score += 0.2
+
+		# --- Rule C: Closure ---
+		# Return to Tonic (Closure) is often implied after tension
+		if target.root_pc == self.key_root_pc:
+			score += 0.2
+
+		# --- Rule D: Proximity ---
+		# General preference for small intervals (≤ 3 semitones).
+		if target_interval > 0 and target_interval <= 3:
+			score += 0.3
+
+		# Scale the boost portion by nir_strength (score starts at 1.0, boost is the excess)
+		return 1.0 + (score - 1.0) * self.nir_strength
+
+	def _transition_weight (
+		self,
+		source: subsequence.chords.Chord,
+		target: subsequence.chords.Chord,
+		weight: int
+	) -> float:
+
+		"""
+		Combine three forces that shape chord transition probabilities:
+
+		1. **Key gravity** — blends functional pull (tonic, dominant) with
+		   full diatonic pull, controlled by ``key_gravity_blend``.
+		2. **Melodic inertia (NIR)** — Narmour's cognitive expectation
+		   model favoring continuation after small steps and reversal
+		   after large leaps, controlled by ``nir_strength``.
+		3. **Root diversity** — exponential damping that discourages
+		   revisiting a root pitch class heard recently, controlled by
+		   ``root_diversity``. Each recent chord sharing the target's
+		   root multiplies the weight by ``root_diversity`` (default
+		   0.4), so the penalty grows stronger with each consecutive
+		   same-root step.
+
+		The final modifier is:
+
+			``(1 + gravity_boost) × nir_score × diversity``
+		"""
+
+		is_function = 1.0 if target in self._function_chords else 0.0
+		is_diatonic = 1.0 if target in self._diatonic_chords else 0.0
+
+		# Decision path: blend controls whether key gravity favors functional or full diatonic chords.
+		boost = (1.0 - self.key_gravity_blend) * is_function + self.key_gravity_blend * is_diatonic
+
+		# Apply NIR gravity
+		nir_score = self._calculate_nir_score(source, target)
+
+		# Root diversity: penalise transitions to a root heard recently.
+		recent_same_root = sum(
+			1 for h in self.history
+			if h.root_pc == target.root_pc
+		)
+		diversity = self.root_diversity ** recent_same_root
+
+		return (1.0 + boost) * nir_score * diversity
+
+	def _record_transition_source (self, chord: subsequence.chords.Chord) -> None:
+
+		"""History bookkeeping for one transition: the outgoing chord enters history.
+
+		The first half of :meth:`step` — exposed so a constrained walk can
+		interleave it with its own draws (``before_choice``) and the NIR
+		weighting sees exactly the context it would live.
+		"""
+
+		self.history.append(chord)
+		if len(self.history) > 4:
+			self.history.pop(0)
+
+	def step (self) -> subsequence.chords.Chord:
+
+		"""Advance to the next chord based on the transition graph."""
+
+		# Update history before choosing next (so structure tracks the path)
+		self._record_transition_source(self.current_chord)
+
+		# Decision path: chord changes occur here; key changes are not automatic.
+		self.current_chord = self.graph.choose_next(self.current_chord, self.rng, weight_modifier=self._transition_weight)
+
+		return self.current_chord
+
+	def plan_next (self) -> subsequence.chords.Chord:
+
+		"""Choose the next chord without committing it — the horizon's pre-step.
+
+		Draws from the RNG exactly as :meth:`step` would (the draw IS the
+		pre-commitment), but leaves ``current_chord`` and ``history``
+		untouched.  Pair with :meth:`commit_chord` when the planned chord
+		becomes the sounding one; ``commit_chord(plan_next())`` is draw-for-
+		draw equivalent to ``step()``.
+		"""
+
+		saved_history = list(self.history)
+
+		self._record_transition_source(self.current_chord)
+
+		try:
+			return self.graph.choose_next(self.current_chord, self.rng, weight_modifier=self._transition_weight)
+		finally:
+			self.history = saved_history
+
+	def commit_chord (self, chord: subsequence.chords.Chord) -> subsequence.chords.Chord:
+
+		"""Make *chord* current with step()'s history bookkeeping, no RNG draw.
+
+		Used by the harmonic clock to commit a planned chord or replay a
+		frozen progression span while keeping NIR context coherent (the
+		outgoing chord enters history as the transition source, exactly as
+		``step()`` records it).
+		"""
+
+		self._record_transition_source(self.current_chord)
+
+		self.current_chord = chord
+
+		return self.current_chord
+
+
+	def get_current_chord (self) -> subsequence.chords.Chord:
+
+		"""Return the current chord."""
+
+		return self.current_chord
+
+
+	def get_key_name (self) -> str:
+
+		"""Return the current key name."""
+
+		return self.key_name
+
+
+	def get_chord_root_midi (self, base_midi: int, chord: subsequence.chords.Chord) -> int:
+
+		"""Calculate the MIDI root for a chord relative to the key root."""
+
+		offset = (chord.root_pc - self.key_root_pc) % 12
+
+		return base_midi + offset

subsequence/harmony.py

@@ -0,0 +1,197 @@
+"""Harmony helpers — diatonic chords without the chord-graph engine.
+
+Standalone convenience functions (``diatonic_chords``, ``diatonic_chord``,
+``diatonic_chord_sequence``) for building chords from a key and mode.  For
+generative progressions use ``progressions``.
+"""
+
+import typing
+
+import subsequence.chords
+import subsequence.intervals
+
+
+def diatonic_chords (key: str, mode: str = "ionian") -> typing.List[subsequence.chords.Chord]:
+
+	"""Return the diatonic triads for a key and mode.
+
+	This is a convenience function for generating chord sequences without
+	using the chord graph engine. The returned ``Chord`` objects can be
+	passed directly to ``p.chord()`` or ``chord.tones()`` inside a pattern.
+
+	Parameters:
+		key: Note name for the key (e.g., ``"C"``, ``"Eb"``, ``"F#"``).
+		mode: A mode with chord qualities defined (e.g. ``"ionian"``,
+			``"dorian"``, ``"minor"``). Scales without chord qualities
+			(e.g. ``"hirajoshi"``) will raise ``ValueError`` — use
+			``p.snap_to_scale()`` for pitch snapping instead.
+
+	Returns:
+		List of ``Chord`` objects, one per scale degree.
+
+	Example:
+		```python
+		# All 7 chords in Eb Major
+		chords = subsequence.harmony.diatonic_chords("Eb")
+
+		# Natural minor chords in A
+		chords = subsequence.harmony.diatonic_chords("A", mode="minor")
+
+		# Dorian chords in D
+		chords = subsequence.harmony.diatonic_chords("D", mode="dorian")
+		```
+	"""
+
+	if mode not in subsequence.intervals.SCALE_MODE_MAP:
+		available = ", ".join(sorted(subsequence.intervals.SCALE_MODE_MAP.keys()))
+		raise ValueError(f"Unknown mode: {mode!r}. Available: {available}")
+
+	_, qualities = subsequence.intervals.SCALE_MODE_MAP[mode]
+
+	if qualities is None:
+		raise ValueError(
+			f"Mode {mode!r} has no chord qualities defined. "
+			"Use register_scale(..., qualities=[...]) to add them, "
+			"or use p.snap_to_scale() for pitch snapping without harmony."
+		)
+	key_pc = subsequence.chords.key_name_to_pc(key)
+	scale_pcs = subsequence.intervals.scale_pitch_classes(key_pc, mode)
+
+	return [
+		subsequence.chords.Chord(root_pc=root_pc, quality=quality)
+		for root_pc, quality in zip(scale_pcs, qualities)
+	]
+
+
+def diatonic_chord (
+	key: str,
+	mode: str = "ionian",
+	degree: int = 0,
+) -> subsequence.chords.Chord:
+
+	"""Return a single diatonic chord by scale degree.
+
+	Convenience wrapper around :func:`diatonic_chords` for the common
+	case where only one chord is needed.
+
+	Parameters:
+		key: Root note name (e.g. ``"E"``, ``"Bb"``).
+		mode: Scale mode (default ``"ionian"``).
+		degree: Zero-indexed scale degree (0 = I/tonic, 4 = V/dominant, etc.).
+
+	Raises:
+		ValueError: If *degree* is out of range for the mode.
+
+	Example:
+		```python
+		tonic = diatonic_chord("E", "phrygian")              # I
+		dominant = diatonic_chord("E", "phrygian", degree=4)  # V
+		```
+	"""
+
+	chords = diatonic_chords(key, mode)
+
+	if degree < 0 or degree >= len(chords):
+		raise ValueError(
+			f"degree {degree} out of range for {mode} (0\u2013{len(chords) - 1})"
+		)
+
+	return chords[degree]
+
+
+def diatonic_chord_sequence (
+	key: str,
+	root_midi: int,
+	count: int,
+	mode: str = "ionian"
+) -> typing.List[typing.Tuple[subsequence.chords.Chord, int]]:
+
+	"""Return a list of ``(Chord, midi_root)`` tuples stepping diatonically upward.
+
+	Useful for mapping a continuous value (like altitude or brightness) to a
+	chord, or for building explicit rising/falling progressions without using
+	the chord graph engine.
+
+	The returned list has ``count`` entries. Each entry contains the ``Chord``
+	object (quality and pitch class) and the exact MIDI note number to use as
+	that chord's root. Pass both directly to ``p.chord(chord, root=midi_root)``.
+
+	Counts larger than the number of scale degrees wrap into higher octaves
+	automatically. The sequence always steps upward — reverse the list for
+	a falling sequence.
+
+	Parameters:
+		key: Note name for the key (e.g., ``"D"``, ``"Eb"``, ``"F#"``).
+		root_midi: MIDI note number for the first chord's root. Must fall on a
+			scale degree of the chosen key and mode.
+		count: Number of ``(Chord, midi_root)`` pairs to generate.
+		mode: One of ``"ionian"`` (or ``"major"``), ``"dorian"``,
+			``"phrygian"``, ``"lydian"``, ``"mixolydian"``,
+			``"aeolian"`` (or ``"minor"``), ``"locrian"``,
+			``"harmonic_minor"``, ``"melodic_minor"``.
+
+	Returns:
+		List of ``(Chord, int)`` tuples, one per step.
+
+	Raises:
+		ValueError: If ``key`` or ``mode`` is not recognised, or if
+			``root_midi`` does not fall on a scale degree of the key.
+
+	Example:
+		```python
+		# 7-step D Major ladder starting at D3 (MIDI 50)
+		sequence = subsequence.harmony.diatonic_chord_sequence("D", root_midi=50, count=7)
+
+		# Map a 0-1 value to a chord (e.g. from ISS altitude)
+		chord, root = sequence[int(ratio * (len(sequence) - 1))]
+		p.chord(chord, root=root, sustain=True)
+
+		# Falling sequence
+		for chord, root in reversed(subsequence.harmony.diatonic_chord_sequence("A", 57, 7, "minor")):
+		    ...
+		```
+	"""
+
+	# Validate mode before looking up the scale key. diatonic_chords() also
+	# validates internally, but diatonic_chord_sequence() is called directly
+	# from user code so we give a clear error here without going deeper.
+	if mode not in subsequence.intervals.SCALE_MODE_MAP:
+		available = ", ".join(sorted(subsequence.intervals.SCALE_MODE_MAP.keys()))
+		raise ValueError(f"Unknown mode: {mode!r}. Available: {available}")
+
+	scale_key, _ = subsequence.intervals.SCALE_MODE_MAP[mode]
+	scale_ivs = subsequence.intervals.get_intervals(scale_key)
+
+	key_pc = subsequence.chords.key_name_to_pc(key)
+	start_pc = root_midi % 12
+
+	# Locate the scale degree that matches the starting MIDI note.
+	start_degree: typing.Optional[int] = None
+
+	for i, iv in enumerate(scale_ivs):
+		if (key_pc + iv) % 12 == start_pc:
+			start_degree = i
+			break
+
+	if start_degree is None:
+		raise ValueError(
+			f"MIDI note {root_midi} (pitch class {start_pc}) is not a scale "
+			f"degree of {key!r} {mode!r}."
+		)
+
+	all_chords = diatonic_chords(key, mode=mode)
+	result: typing.List[typing.Tuple[subsequence.chords.Chord, int]] = []
+
+	num_degrees = len(scale_ivs)
+
+	for i in range(count):
+		degree = (start_degree + i) % num_degrees
+		octave_bump = (start_degree + i) // num_degrees
+		midi_root = (
+			root_midi
+			+ (scale_ivs[degree] - scale_ivs[start_degree])
+			+ 12 * octave_bump
+		)
+		result.append((all_chords[degree], midi_root))
+
+	return result

subsequence/held_notes.py

@@ -0,0 +1,91 @@
+"""Held-note tracking for live MIDI note input.
+
+``HeldNotes`` maintains the set of MIDI notes a player is currently holding
+on a ``note_input`` keyboard, so an arpeggiator (or any pattern) can read the
+live pitch set each cycle via ``p.held_notes()``.
+
+It is a tiny, dependency-free state machine.  All of its state lives on the
+sequencer loop thread: the mido callback thread only appends raw note events
+to a deque, which the loop drains and feeds here.  Because it is never touched
+from two threads, it needs no locking — and because it takes the current time
+as an argument (rather than reading the clock itself), it is fully
+deterministic and trivial to unit-test.
+
+Two smoothing behaviours guard against the arp dropping to silence:
+
+* **``release_ms`` debounce** — a just-released note lingers in the held set
+  for a short window, so the momentary all-keys-up gap during a hand-position
+  changeover does not register as "nothing held".
+* **``latch``** — the held set persists after release until a *new* chord is
+  started (the first key pressed after every key is up replaces it), like a
+  hardware arp's latch / a sustain pedal.  Under ``latch`` the ``release_ms``
+  window is unused — latch dominates.
+"""
+
+import typing
+
+
+class HeldNotes:
+
+	"""The live set of notes held on a ``note_input`` keyboard."""
+
+	def __init__ (self, release_ms: float = 0.0, latch: bool = False) -> None:
+
+		"""Create a held-note tracker.
+
+		Parameters:
+			release_ms: How long (milliseconds) a released note keeps counting
+				as held, smoothing the gap during hand-position changes.  0
+				removes a note the instant its note-off arrives.  Ignored when
+				``latch`` is True.
+			latch: When True, the held set persists after release until the
+				next chord is started.
+		"""
+
+		self._release_s: float = max(0.0, release_ms) / 1000.0
+		self._latch: bool = latch
+		# pitch -> velocity for notes physically down right now.
+		self._on: typing.Dict[int, int] = {}
+		# pitch -> perf_counter deadline for just-released notes (debounce window).
+		self._releasing: typing.Dict[int, float] = {}
+		# pitch -> velocity for the latched chord (latch mode only).
+		self._latched: typing.Dict[int, int] = {}
+
+	def note_on (self, pitch: int, velocity: int, now: float) -> None:
+
+		"""Register a note-on (``now`` = a perf_counter timestamp)."""
+
+		self._releasing.pop(pitch, None)
+		if self._latch and not self._on:
+			# First key after every key was up — start a fresh latched chord.
+			self._latched.clear()
+		self._on[pitch] = velocity
+
+	def note_off (self, pitch: int, now: float) -> None:
+
+		"""Register a note-off (``now`` = a perf_counter timestamp)."""
+
+		velocity = self._on.pop(pitch, None)
+		if velocity is None:
+			return
+		if self._latch:
+			self._latched[pitch] = velocity
+		elif self._release_s > 0.0:
+			self._releasing[pitch] = now + self._release_s
+
+	def snapshot (self, now: float) -> typing.List[int]:
+
+		"""Return the currently held MIDI notes, sorted ascending.
+
+		Combines notes physically down, any still within the ``release_ms``
+		debounce window at ``now``, and the latched chord.  Expired
+		release-window notes are pruned as a side effect.
+		"""
+
+		held: typing.Set[int] = set(self._on)
+		held.update(self._latched)
+		if self._releasing:
+			for pitch in [p for p, deadline in self._releasing.items() if deadline <= now]:
+				del self._releasing[pitch]
+			held.update(self._releasing)
+		return sorted(held)

subsequence/helpers/network.py

@@ -0,0 +1,58 @@
+"""Network utility functions.
+
+Provides robust local IP and broadcast address discovery without requiring
+external dependencies like ``psutil``.
+"""
+
+import socket
+import typing
+
+
+def get_local_ip () -> str:
+
+	"""Discover the primary local IP address of the machine.
+
+	Uses a non-connecting UDP socket trick to find the IP of the default
+	outbound interface currently used for external routing.
+
+	Returns:
+		The local IP address as a string, or "127.0.0.1" if discovery fails.
+	"""
+
+	local_ip = "127.0.0.1"
+	try:
+		# Connecting a UDP socket to an external address (no data is actually
+		# sent) reveals which local IP the OS would use for that route.
+		probe = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+		try:
+			probe.connect(("8.8.8.8", 80))
+			local_ip = probe.getsockname()[0]
+		finally:
+			probe.close()
+	except Exception:
+		pass
+
+	return local_ip
+
+
+def get_local_broadcasts () -> typing.List[str]:
+
+	"""Return subnet broadcast addresses inferred from local interface IPs.
+
+	Computes the /24 broadcast address based on the primary local IP route.
+
+	Returns:
+		A list containing the computed broadcast address, or an empty list
+		if the primary interface is a loopback or link-local address.
+	"""
+
+	broadcasts: typing.List[str] = []
+	local_ip = get_local_ip()
+
+	if not local_ip.startswith("127.") and not local_ip.startswith("169.254."):
+		parts = local_ip.split(".")
+		if len(parts) == 4:
+			parts[3] = "255"
+			broadcasts.append(".".join(parts))
+
+	return broadcasts