physbound 0.1.0__py3-none-any.whl

physbound/__init__.py

@@ -0,0 +1,3 @@
+"""PhysBound — Physical Layer Linter for AI hallucination detection."""
+
+__version__ = "0.1.0"

physbound/engines/constants.py

@@ -0,0 +1,25 @@
+"""Physical constants as Pint quantities wrapping SciPy CODATA values.
+
+All downstream modules import the shared UnitRegistry and constants from here.
+No raw floats should leak into engine code — everything carries units.
+"""
+
+import pint
+from scipy import constants as sc
+
+# Single shared registry — import this everywhere
+ureg = pint.UnitRegistry()
+Q_ = ureg.Quantity
+
+# Exact physical constants as Pint quantities (CODATA 2018 exact values)
+SPEED_OF_LIGHT = Q_(sc.speed_of_light, "m/s")  # 299_792_458 m/s (exact)
+BOLTZMANN = Q_(sc.Boltzmann, "J/K")  # 1.380649e-23 J/K (exact)
+PLANCK = Q_(sc.Planck, "J*s")  # 6.62607015e-34 J·s (exact)
+
+# IEEE standard reference temperature
+T_REF = Q_(290, "K")
+
+# Derived: thermal noise floor at T_REF, 1 Hz bandwidth
+# N = k_B * T = 1.380649e-23 * 290 = 4.00388e-21 W/Hz
+# In dBm/Hz: 10 * log10(4.00388e-21 / 1e-3) = -173.977 ≈ -174 dBm/Hz
+THERMAL_NOISE_FLOOR_DBM_PER_HZ = -174.0

physbound/engines/link_budget.py

@@ -0,0 +1,217 @@
+"""RF Link Budget calculator using Friis transmission equation.
+
+Formulas:
+    FSPL = 20*log10(d) + 20*log10(f) + 20*log10(4*pi/c)    (free-space path loss)
+    P_rx = P_tx + G_tx + G_rx - FSPL - L_tx - L_rx          (Friis transmission)
+    G_max = eta * (pi*D/lambda)^2                             (aperture limit)
+"""
+
+import math
+
+from physbound.engines.constants import SPEED_OF_LIGHT
+from physbound.engines.units import linear_to_db
+from physbound.errors import PhysicalViolationError
+from physbound.validators import validate_positive_distance, validate_positive_frequency
+
+# Default aperture efficiency for parabolic dish antennas
+DEFAULT_APERTURE_EFFICIENCY = 0.55
+
+
+def free_space_path_loss_db(frequency_hz: float, distance_m: float) -> float:
+    """Compute free-space path loss in dB.
+
+    FSPL(dB) = 20*log10(d) + 20*log10(f) + 20*log10(4*pi/c)
+
+    Args:
+        frequency_hz: Carrier frequency in Hz.
+        distance_m: Link distance in meters.
+
+    Returns:
+        FSPL in dB (positive value; a loss).
+    """
+    validate_positive_frequency(frequency_hz)
+    validate_positive_distance(distance_m)
+
+    c = SPEED_OF_LIGHT.magnitude  # m/s
+    fspl = (
+        20.0 * math.log10(distance_m)
+        + 20.0 * math.log10(frequency_hz)
+        + 20.0 * math.log10(4.0 * math.pi / c)
+    )
+    return fspl
+
+
+def max_aperture_gain_dbi(
+    diameter_m: float,
+    frequency_hz: float,
+    efficiency: float = DEFAULT_APERTURE_EFFICIENCY,
+) -> float:
+    """Compute maximum antenna gain for a circular aperture.
+
+    G_max = eta * (pi * D / lambda)^2
+
+    Args:
+        diameter_m: Antenna diameter in meters.
+        frequency_hz: Operating frequency in Hz.
+        efficiency: Aperture efficiency (default: 0.55 for parabolic dish).
+
+    Returns:
+        Maximum gain in dBi.
+    """
+    validate_positive_frequency(frequency_hz)
+    if diameter_m <= 0:
+        raise PhysicalViolationError(
+            message=f"Antenna diameter must be positive, got {diameter_m} m",
+            law_violated="Antenna Theory",
+            latex_explanation=r"$D > 0$ required for a physical antenna aperture",
+            claimed_value=diameter_m,
+            unit="m",
+        )
+
+    c = SPEED_OF_LIGHT.magnitude
+    wavelength = c / frequency_hz
+    g_linear = efficiency * (math.pi * diameter_m / wavelength) ** 2
+    return linear_to_db(g_linear)
+
+
+def validate_antenna_gain(
+    claimed_gain_dbi: float,
+    diameter_m: float,
+    frequency_hz: float,
+    label: str = "antenna",
+    efficiency: float = DEFAULT_APERTURE_EFFICIENCY,
+) -> float:
+    """Validate that claimed antenna gain doesn't exceed the aperture limit.
+
+    Args:
+        claimed_gain_dbi: Claimed antenna gain in dBi.
+        diameter_m: Antenna diameter in meters.
+        frequency_hz: Operating frequency in Hz.
+        label: Human label for error messages (e.g., "TX antenna").
+        efficiency: Aperture efficiency (default: 0.55).
+
+    Returns:
+        The computed G_max in dBi.
+
+    Raises:
+        PhysicalViolationError: If claimed gain exceeds G_max.
+    """
+    g_max = max_aperture_gain_dbi(diameter_m, frequency_hz, efficiency)
+
+    if claimed_gain_dbi > g_max:
+        c = SPEED_OF_LIGHT.magnitude
+        wavelength = c / frequency_hz
+        raise PhysicalViolationError(
+            message=(
+                f"{label} claimed gain {claimed_gain_dbi:.1f} dBi exceeds "
+                f"aperture limit {g_max:.1f} dBi for {diameter_m} m dish at "
+                f"{frequency_hz / 1e9:.3f} GHz"
+            ),
+            law_violated="Antenna Aperture Limit",
+            latex_explanation=(
+                rf"$G_{{\max}} = \eta \left(\frac{{\pi D}}{{\lambda}}\right)^2 = "
+                rf"{efficiency} \times \left(\frac{{\pi \times {diameter_m}}}"
+                rf"{{{wavelength:.4f}}}\right)^2 = {g_max:.1f}\,\text{{dBi}}$. "
+                rf"Claimed ${claimed_gain_dbi:.1f}\,\text{{dBi}}$ exceeds this limit."
+            ),
+            computed_limit=g_max,
+            claimed_value=claimed_gain_dbi,
+            unit="dBi",
+        )
+
+    return g_max
+
+
+def compute_link_budget(
+    tx_power_dbm: float,
+    tx_antenna_gain_dbi: float,
+    rx_antenna_gain_dbi: float,
+    frequency_hz: float,
+    distance_m: float,
+    tx_losses_db: float = 0.0,
+    rx_losses_db: float = 0.0,
+    tx_antenna_diameter_m: float | None = None,
+    rx_antenna_diameter_m: float | None = None,
+) -> dict:
+    """Compute a full RF link budget using the Friis transmission equation.
+
+    P_rx = P_tx + G_tx + G_rx - FSPL - L_tx - L_rx
+
+    Args:
+        tx_power_dbm: Transmit power in dBm.
+        tx_antenna_gain_dbi: Transmit antenna gain in dBi.
+        rx_antenna_gain_dbi: Receive antenna gain in dBi.
+        frequency_hz: Carrier frequency in Hz.
+        distance_m: Link distance in meters.
+        tx_losses_db: TX-side miscellaneous losses in dB.
+        rx_losses_db: RX-side miscellaneous losses in dB.
+        tx_antenna_diameter_m: Optional TX antenna diameter for aperture check.
+        rx_antenna_diameter_m: Optional RX antenna diameter for aperture check.
+
+    Returns:
+        Dict with FSPL, received power, warnings, human-readable, and LaTeX.
+
+    Raises:
+        PhysicalViolationError: If antenna gains exceed aperture limits.
+    """
+    warnings = []
+    tx_aperture_limit_dbi = None
+    rx_aperture_limit_dbi = None
+
+    # Validate antenna gains against aperture limits if diameters provided
+    if tx_antenna_diameter_m is not None:
+        tx_aperture_limit_dbi = validate_antenna_gain(
+            tx_antenna_gain_dbi, tx_antenna_diameter_m, frequency_hz, "TX antenna"
+        )
+
+    if rx_antenna_diameter_m is not None:
+        rx_aperture_limit_dbi = validate_antenna_gain(
+            rx_antenna_gain_dbi, rx_antenna_diameter_m, frequency_hz, "RX antenna"
+        )
+
+    # Friis model applicability warning above 300 GHz
+    if frequency_hz > 3e11:
+        warnings.append(
+            f"Frequency {frequency_hz / 1e9:.1f} GHz exceeds 300 GHz; "
+            "Friis free-space model may not be accurate due to atmospheric absorption"
+        )
+
+    # Compute FSPL and received power
+    fspl = free_space_path_loss_db(frequency_hz, distance_m)
+    received_power_dbm = (
+        tx_power_dbm + tx_antenna_gain_dbi + rx_antenna_gain_dbi
+        - fspl - tx_losses_db - rx_losses_db
+    )
+
+    c = SPEED_OF_LIGHT.magnitude
+    wavelength = c / frequency_hz
+
+    human_readable = (
+        f"Link Budget at {frequency_hz / 1e9:.3f} GHz, {distance_m:.1f} m:\n"
+        f"  TX Power:      {tx_power_dbm:.1f} dBm\n"
+        f"  TX Gain:       {tx_antenna_gain_dbi:.1f} dBi\n"
+        f"  RX Gain:       {rx_antenna_gain_dbi:.1f} dBi\n"
+        f"  FSPL:          {fspl:.2f} dB\n"
+        f"  TX Losses:     {tx_losses_db:.1f} dB\n"
+        f"  RX Losses:     {rx_losses_db:.1f} dB\n"
+        f"  Received Power: {received_power_dbm:.2f} dBm"
+    )
+
+    latex = (
+        rf"$P_{{\text{{rx}}}} = P_{{\text{{tx}}}} + G_{{\text{{tx}}}} + G_{{\text{{rx}}}} "
+        rf"- \text{{FSPL}} - L_{{\text{{tx}}}} - L_{{\text{{rx}}}} = "
+        rf"{tx_power_dbm:.1f} + {tx_antenna_gain_dbi:.1f} + {rx_antenna_gain_dbi:.1f} "
+        rf"- {fspl:.2f} - {tx_losses_db:.1f} - {rx_losses_db:.1f} = "
+        rf"{received_power_dbm:.2f}\,\text{{dBm}}$"
+    )
+
+    return {
+        "fspl_db": fspl,
+        "received_power_dbm": received_power_dbm,
+        "wavelength_m": wavelength,
+        "tx_aperture_limit_dbi": tx_aperture_limit_dbi,
+        "rx_aperture_limit_dbi": rx_aperture_limit_dbi,
+        "warnings": warnings,
+        "human_readable": human_readable,
+        "latex": latex,
+    }

physbound/engines/noise.py

@@ -0,0 +1,125 @@
+"""Thermal noise floor, Friis noise figure cascading, and receiver sensitivity.
+
+Formulas:
+    N = k_B * T * B                         (thermal noise power)
+    F_total = F_1 + (F_2-1)/G_1 + ...      (Friis noise cascade)
+    S_min = N_floor + NF + SNR_req          (receiver sensitivity)
+"""
+
+import math
+
+from physbound.engines.constants import BOLTZMANN, T_REF
+from physbound.engines.units import db_to_linear, linear_to_db
+from physbound.errors import PhysicalViolationError
+from physbound.validators import validate_positive_bandwidth, validate_temperature
+
+
+def thermal_noise_power_dbm(bandwidth_hz: float, temperature_k: float = 290.0) -> float:
+    """Compute thermal noise power N = k_B * T * B in dBm.
+
+    Args:
+        bandwidth_hz: Receiver bandwidth in Hz.
+        temperature_k: System noise temperature in Kelvin (default: 290K).
+
+    Returns:
+        Thermal noise power in dBm.
+    """
+    validate_positive_bandwidth(bandwidth_hz)
+    validate_temperature(temperature_k)
+
+    if temperature_k == 0:
+        return float("-inf")
+
+    k_b = BOLTZMANN.magnitude  # J/K
+    n_watts = k_b * temperature_k * bandwidth_hz
+    n_dbm = 10.0 * math.log10(n_watts / 1e-3)
+    return n_dbm
+
+
+def thermal_noise_power_watts(bandwidth_hz: float, temperature_k: float = 290.0) -> float:
+    """Compute thermal noise power N = k_B * T * B in watts.
+
+    Args:
+        bandwidth_hz: Receiver bandwidth in Hz.
+        temperature_k: System noise temperature in Kelvin (default: 290K).
+
+    Returns:
+        Thermal noise power in watts.
+    """
+    validate_positive_bandwidth(bandwidth_hz)
+    validate_temperature(temperature_k)
+
+    k_b = BOLTZMANN.magnitude
+    return k_b * temperature_k * bandwidth_hz
+
+
+def friis_noise_cascade(
+    stages: list[tuple[float, float]],
+) -> float:
+    """Compute cascaded noise figure using the Friis formula.
+
+    F_total = F_1 + (F_2 - 1)/G_1 + (F_3 - 1)/(G_1*G_2) + ...
+
+    Args:
+        stages: List of (gain_db, noise_figure_db) tuples for each stage.
+
+    Returns:
+        Total cascaded noise figure in dB.
+
+    Raises:
+        PhysicalViolationError: If noise figure is negative (below quantum limit).
+    """
+    if not stages:
+        raise PhysicalViolationError(
+            message="At least one stage is required for noise cascade",
+            law_violated="Friis Noise Formula",
+            latex_explanation=r"$F_\text{total}$ requires at least one stage",
+        )
+
+    for i, (gain_db, nf_db) in enumerate(stages):
+        if nf_db < 0:
+            raise PhysicalViolationError(
+                message=f"Stage {i + 1} noise figure is {nf_db} dB (negative); "
+                "this implies a noiseless amplifier below the quantum limit",
+                law_violated="Quantum Noise Limit",
+                latex_explanation=(
+                    rf"$NF_{{{i + 1}}} = {nf_db}\,\text{{dB}} < 0$; "
+                    r"violates the quantum noise limit $NF \geq 0\,\text{dB}$"
+                ),
+                claimed_value=nf_db,
+                unit="dB",
+            )
+
+    # Convert to linear
+    gains_linear = [db_to_linear(g) for g, _ in stages]
+    nf_linear = [db_to_linear(nf) for _, nf in stages]
+
+    # Friis formula
+    f_total = nf_linear[0]
+    cumulative_gain = 1.0
+    for i in range(1, len(stages)):
+        cumulative_gain *= gains_linear[i - 1]
+        f_total += (nf_linear[i] - 1.0) / cumulative_gain
+
+    return linear_to_db(f_total)
+
+
+def receiver_sensitivity_dbm(
+    bandwidth_hz: float,
+    noise_figure_db: float,
+    required_snr_db: float,
+    temperature_k: float = 290.0,
+) -> float:
+    """Compute minimum receiver sensitivity: S_min = N_floor + NF + SNR_req.
+
+    Args:
+        bandwidth_hz: Receiver bandwidth in Hz.
+        noise_figure_db: System noise figure in dB.
+        required_snr_db: Required SNR at the detector in dB.
+        temperature_k: Reference temperature in Kelvin (default: 290K).
+
+    Returns:
+        Minimum detectable signal power in dBm.
+    """
+    n_floor = thermal_noise_power_dbm(bandwidth_hz, temperature_k)
+    return n_floor + noise_figure_db + required_snr_db

physbound/engines/shannon.py

@@ -0,0 +1,106 @@
+"""Shannon-Hartley channel capacity theorem implementation.
+
+Formulas:
+    C = B * log2(1 + SNR)                  (channel capacity in bps)
+    eta = C / B = log2(1 + SNR)            (spectral efficiency in bps/Hz)
+    SNR_linear = 10^(SNR_dB / 10)          (dB to linear conversion)
+"""
+
+import math
+
+from physbound.engines.units import db_to_linear, linear_to_db
+from physbound.errors import PhysicalViolationError
+from physbound.validators import validate_positive_bandwidth, validate_positive_snr
+
+
+def channel_capacity_bps(bandwidth_hz: float, snr_linear: float) -> float:
+    """Compute Shannon-Hartley channel capacity: C = B * log2(1 + SNR).
+
+    Args:
+        bandwidth_hz: Channel bandwidth in Hz.
+        snr_linear: Signal-to-noise ratio (linear, not dB).
+
+    Returns:
+        Maximum channel capacity in bits per second.
+    """
+    validate_positive_bandwidth(bandwidth_hz)
+    validate_positive_snr(snr_linear)
+    return bandwidth_hz * math.log2(1.0 + snr_linear)
+
+
+def spectral_efficiency(snr_linear: float) -> float:
+    """Compute spectral efficiency: eta = log2(1 + SNR) in bps/Hz.
+
+    Args:
+        snr_linear: Signal-to-noise ratio (linear, not dB).
+
+    Returns:
+        Spectral efficiency in bits/sec/Hz.
+    """
+    validate_positive_snr(snr_linear)
+    return math.log2(1.0 + snr_linear)
+
+
+def snr_db_to_linear(snr_db: float) -> float:
+    """Convert SNR from dB to linear: SNR_linear = 10^(SNR_dB / 10)."""
+    return db_to_linear(snr_db)
+
+
+def validate_throughput_claim(
+    bandwidth_hz: float,
+    snr_linear: float,
+    claimed_throughput_bps: float,
+) -> dict:
+    """Validate a throughput claim against the Shannon-Hartley limit.
+
+    Args:
+        bandwidth_hz: Channel bandwidth in Hz.
+        snr_linear: Signal-to-noise ratio (linear, not dB).
+        claimed_throughput_bps: Claimed throughput to validate in bps.
+
+    Returns:
+        Dict with capacity, claim validity, and excess percentage.
+
+    Raises:
+        PhysicalViolationError: If claimed throughput exceeds Shannon limit.
+    """
+    capacity = channel_capacity_bps(bandwidth_hz, snr_linear)
+    eta = spectral_efficiency(snr_linear)
+
+    if claimed_throughput_bps > capacity:
+        excess_pct = ((claimed_throughput_bps - capacity) / capacity) * 100.0
+        snr_db = linear_to_db(snr_linear)
+        raise PhysicalViolationError(
+            message=(
+                f"Claimed throughput {claimed_throughput_bps:.1f} bps exceeds "
+                f"Shannon limit of {capacity:.1f} bps by {excess_pct:.1f}%"
+            ),
+            law_violated="Shannon-Hartley Theorem",
+            latex_explanation=(
+                rf"$C = B \log_2(1 + \text{{SNR}}) = "
+                rf"{bandwidth_hz:.0f} \times \log_2(1 + {snr_linear:.2f}) = "
+                rf"{capacity:.1f}\,\text{{bps}}$. "
+                rf"Claimed ${claimed_throughput_bps:.1f}\,\text{{bps}}$ exceeds "
+                rf"the Shannon limit by ${excess_pct:.1f}\%$."
+            ),
+            computed_limit=capacity,
+            claimed_value=claimed_throughput_bps,
+            unit="bps",
+        )
+
+    # Warn if spectral efficiency is unusually high (> 20 bps/Hz)
+    warnings = []
+    claimed_eta = claimed_throughput_bps / bandwidth_hz
+    if claimed_eta > 20:
+        warnings.append(
+            f"Claimed spectral efficiency {claimed_eta:.1f} bps/Hz exceeds "
+            "20 bps/Hz; possible but unusual in practical systems"
+        )
+
+    return {
+        "capacity_bps": capacity,
+        "spectral_efficiency_bps_hz": eta,
+        "claim_is_valid": True,
+        "excess_percentage": 0.0,
+        "warnings": warnings,
+    }

physbound/engines/units.py

@@ -0,0 +1,103 @@
+"""Unit conversion helpers for RF engineering calculations.
+
+All functions operate on Pint quantities and enforce dimensional correctness.
+"""
+
+import math
+
+import pint
+
+from physbound.engines.constants import Q_, SPEED_OF_LIGHT, ureg
+from physbound.errors import PhysicalViolationError
+
+
+def validate_dimensions(quantity: pint.Quantity, expected: str, name: str = "value") -> None:
+    """Raise PhysicalViolationError if quantity dimensions don't match expected.
+
+    Args:
+        quantity: The Pint quantity to check.
+        expected: Pint dimensionality string, e.g. '[length]', '[power]'.
+        name: Human-readable name for error messages.
+    """
+    if not quantity.check(expected):
+        raise PhysicalViolationError(
+            message=f"{name} has dimensions {quantity.dimensionality}, expected {expected}",
+            law_violated="Dimensional Analysis",
+            latex_explanation=(
+                rf"$\text{{{name}}}$ has dimensions "
+                rf"$\left[{quantity.dimensionality}\right]$, "
+                rf"expected $\left[{expected}\right]$"
+            ),
+        )
+
+
+def watts_to_dbm(power: pint.Quantity) -> float:
+    """Convert a Pint power quantity to dBm (dimensionless float).
+
+    Args:
+        power: Power as a Pint quantity with dimensions of [power].
+
+    Returns:
+        Power in dBm as a plain float.
+    """
+    validate_dimensions(power, "[length] ** 2 * [mass] / [time] ** 3", "power")
+    power_watts = power.to(ureg.watt).magnitude
+    if power_watts <= 0:
+        raise PhysicalViolationError(
+            message=f"Power must be positive, got {power_watts} W",
+            law_violated="Conservation of Energy",
+            latex_explanation=r"$P > 0$ required; negative power is non-physical",
+            claimed_value=power_watts,
+            unit="W",
+        )
+    return 10.0 * math.log10(power_watts / 1e-3)
+
+
+def dbm_to_watts(power_dbm: float) -> pint.Quantity:
+    """Convert dBm float to Pint watts quantity.
+
+    Args:
+        power_dbm: Power in dBm.
+
+    Returns:
+        Power as a Pint Quantity in watts.
+    """
+    return Q_(1e-3 * 10.0 ** (power_dbm / 10.0), "watt")
+
+
+def frequency_to_wavelength(freq: pint.Quantity) -> pint.Quantity:
+    """Compute wavelength from frequency: lambda = c / f.
+
+    Args:
+        freq: Frequency as a Pint quantity with dimensions of [time]^-1.
+
+    Returns:
+        Wavelength as a Pint Quantity in meters.
+    """
+    validate_dimensions(freq, "1 / [time]", "frequency")
+    if freq.magnitude <= 0:
+        raise PhysicalViolationError(
+            message=f"Frequency must be positive, got {freq}",
+            law_violated="Electromagnetic Theory",
+            latex_explanation=r"$f > 0$ required for physical electromagnetic radiation",
+            claimed_value=freq.magnitude,
+            unit=str(freq.units),
+        )
+    return (SPEED_OF_LIGHT / freq).to(ureg.meter)
+
+
+def db_to_linear(db: float) -> float:
+    """Convert a dB value to linear ratio: 10^(dB/10)."""
+    return 10.0 ** (db / 10.0)
+
+
+def linear_to_db(linear: float) -> float:
+    """Convert a linear ratio to dB: 10*log10(linear)."""
+    if linear <= 0:
+        raise PhysicalViolationError(
+            message=f"Linear value must be positive for dB conversion, got {linear}",
+            law_violated="Mathematical Constraint",
+            latex_explanation=r"$\text{dB} = 10 \log_{10}(x)$ requires $x > 0$",
+            claimed_value=linear,
+        )
+    return 10.0 * math.log10(linear)

physbound/errors.py

@@ -0,0 +1,34 @@
+"""PhysBound error types with LaTeX-formatted physics violation explanations."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PhysicalViolationError(Exception):
+    """Raised when an input or claim violates a physical law or hard limit.
+
+    Always carries a LaTeX explanation suitable for rendering in technical documents.
+    """
+
+    message: str
+    law_violated: str
+    latex_explanation: str
+    computed_limit: float | None = None
+    claimed_value: float | None = None
+    unit: str = ""
+
+    def __str__(self) -> str:
+        return f"[{self.law_violated}] {self.message}"
+
+    def to_dict(self) -> dict:
+        """Serialize for JSON MCP response."""
+        return {
+            "error": True,
+            "violation_type": "PhysicalViolationError",
+            "law_violated": self.law_violated,
+            "message": self.message,
+            "latex": self.latex_explanation,
+            "computed_limit": self.computed_limit,
+            "claimed_value": self.claimed_value,
+            "unit": self.unit,
+        }

physbound/models/common.py

@@ -0,0 +1,11 @@
+"""Shared Pydantic models for PhysBound MCP tool responses."""
+
+from pydantic import BaseModel
+
+
+class PhysBoundResult(BaseModel):
+    """Base output envelope for all PhysBound tool responses."""
+
+    human_readable: str
+    latex: str
+    warnings: list[str] = []

physbound/models/link_budget.py

@@ -0,0 +1,33 @@
+"""Pydantic models for the RF Link Budget tool."""
+
+from pydantic import BaseModel, Field
+
+from physbound.models.common import PhysBoundResult
+
+
+class LinkBudgetInput(BaseModel):
+    """Input parameters for RF link budget calculation using Friis transmission equation."""
+
+    tx_power_dbm: float = Field(description="Transmit power in dBm")
+    tx_antenna_gain_dbi: float = Field(description="Transmit antenna gain in dBi")
+    rx_antenna_gain_dbi: float = Field(description="Receive antenna gain in dBi")
+    frequency_hz: float = Field(gt=0, description="Carrier frequency in Hz")
+    distance_m: float = Field(gt=0, description="Link distance in meters")
+    tx_losses_db: float = Field(default=0.0, description="TX-side miscellaneous losses in dB")
+    rx_losses_db: float = Field(default=0.0, description="RX-side miscellaneous losses in dB")
+    tx_antenna_diameter_m: float | None = Field(
+        default=None, description="TX antenna diameter in meters (enables aperture limit check)"
+    )
+    rx_antenna_diameter_m: float | None = Field(
+        default=None, description="RX antenna diameter in meters (enables aperture limit check)"
+    )
+
+
+class LinkBudgetOutput(PhysBoundResult):
+    """Output of the RF link budget calculation."""
+
+    fspl_db: float
+    received_power_dbm: float
+    wavelength_m: float
+    tx_aperture_limit_dbi: float | None = None
+    rx_aperture_limit_dbi: float | None = None

physbound/models/noise.py

@@ -0,0 +1,37 @@
+"""Pydantic models for the Thermal Noise Floor tool."""
+
+from pydantic import BaseModel, Field
+
+from physbound.models.common import PhysBoundResult
+
+
+class NoiseStage(BaseModel):
+    """A single amplifier/component stage for Friis noise figure cascading."""
+
+    gain_db: float = Field(description="Stage gain in dB")
+    noise_figure_db: float = Field(ge=0, description="Stage noise figure in dB")
+
+
+class NoiseFloorInput(BaseModel):
+    """Input parameters for thermal noise floor and receiver sensitivity calculation."""
+
+    bandwidth_hz: float = Field(gt=0, description="Receiver bandwidth in Hz")
+    temperature_k: float = Field(
+        default=290.0, ge=0, description="System noise temperature in Kelvin (default: 290K)"
+    )
+    stages: list[NoiseStage] | None = Field(
+        default=None, description="Optional cascade of amplifier stages for Friis noise formula"
+    )
+    required_snr_db: float | None = Field(
+        default=None, description="Required SNR in dB for receiver sensitivity calculation"
+    )
+
+
+class NoiseFloorOutput(PhysBoundResult):
+    """Output of thermal noise floor and sensitivity calculation."""
+
+    thermal_noise_dbm: float
+    thermal_noise_watts: float
+    cascaded_noise_figure_db: float | None = None
+    system_noise_temp_k: float | None = None
+    receiver_sensitivity_dbm: float | None = None

physbound/models/shannon.py

@@ -0,0 +1,40 @@
+"""Pydantic models for the Shannon-Hartley Channel Capacity tool."""
+
+from pydantic import BaseModel, Field, model_validator
+
+from physbound.models.common import PhysBoundResult
+
+
+class ShannonInput(BaseModel):
+    """Input parameters for Shannon-Hartley channel capacity validation."""
+
+    bandwidth_hz: float = Field(gt=0, description="Channel bandwidth in Hz")
+    snr_linear: float | None = Field(
+        default=None, description="Signal-to-noise ratio (linear, not dB)"
+    )
+    snr_db: float | None = Field(
+        default=None, description="Signal-to-noise ratio in dB (alternative to snr_linear)"
+    )
+    claimed_throughput_bps: float | None = Field(
+        default=None, description="Throughput claim to validate in bits per second"
+    )
+
+    @model_validator(mode="after")
+    def exactly_one_snr(self):
+        if self.snr_linear is None and self.snr_db is None:
+            raise ValueError("Exactly one of snr_linear or snr_db must be provided")
+        if self.snr_linear is not None and self.snr_db is not None:
+            raise ValueError("Provide only one of snr_linear or snr_db, not both")
+        return self
+
+
+class ShannonOutput(PhysBoundResult):
+    """Output of Shannon-Hartley channel capacity calculation."""
+
+    capacity_bps: float
+    spectral_efficiency_bps_hz: float
+    snr_db: float
+    snr_linear: float
+    claimed_throughput_bps: float | None = None
+    claim_is_valid: bool | None = None
+    excess_percentage: float | None = None

physbound/server.py

@@ -0,0 +1,279 @@
+"""PhysBound MCP Server — Physical Layer Linter for AI hallucination detection.
+
+Exposes three RF validation tools via the Model Context Protocol (MCP):
+  1. rf_link_budget — Friis transmission link budget with aperture limit checks
+  2. shannon_hartley — Shannon-Hartley channel capacity and throughput validation
+  3. noise_floor — Thermal noise, Friis noise cascade, and receiver sensitivity
+"""
+
+from fastmcp import FastMCP
+
+from physbound.engines import link_budget as lb_engine
+from physbound.engines import noise as nz_engine
+from physbound.engines import shannon as sh_engine
+from physbound.engines.units import db_to_linear, linear_to_db
+from physbound.errors import PhysicalViolationError
+from physbound.models.link_budget import LinkBudgetInput, LinkBudgetOutput
+from physbound.models.noise import NoiseFloorInput, NoiseFloorOutput
+from physbound.models.shannon import ShannonInput, ShannonOutput
+
+mcp = FastMCP(
+    name="PhysBound",
+    instructions=(
+        "Physics validation MCP server. Validates RF link budgets, "
+        "Shannon-Hartley channel capacity claims, and thermal noise calculations "
+        "against hard physical limits. Catches AI hallucinations in physics."
+    ),
+)
+
+
+@mcp.tool
+def rf_link_budget(
+    tx_power_dbm: float,
+    tx_antenna_gain_dbi: float,
+    rx_antenna_gain_dbi: float,
+    frequency_hz: float,
+    distance_m: float,
+    tx_losses_db: float = 0.0,
+    rx_losses_db: float = 0.0,
+    tx_antenna_diameter_m: float | None = None,
+    rx_antenna_diameter_m: float | None = None,
+) -> dict:
+    """Calculate a complete RF link budget using the Friis transmission equation.
+
+    Computes free-space path loss (FSPL), received power, and validates antenna
+    gains against aperture limits (G_max = eta * (pi*D/lambda)^2). Rejects any
+    configuration that implies physically impossible antenna performance.
+
+    Use this tool when you need to:
+    - Estimate received signal strength for a wireless link
+    - Validate whether a claimed link budget is physically achievable
+    - Check if antenna gain claims are consistent with antenna dimensions
+    - Compute free-space path loss at a given frequency and distance
+
+    Returns both human-readable summary and machine-readable JSON with all
+    intermediate values. Returns a PhysicalViolationError dict if any input
+    violates physics.
+
+    Args:
+        tx_power_dbm: Transmit power in dBm
+        tx_antenna_gain_dbi: Transmit antenna gain in dBi
+        rx_antenna_gain_dbi: Receive antenna gain in dBi
+        frequency_hz: Carrier frequency in Hz (must be > 0)
+        distance_m: Link distance in meters (must be > 0)
+        tx_losses_db: TX-side miscellaneous losses in dB (default: 0)
+        rx_losses_db: RX-side miscellaneous losses in dB (default: 0)
+        tx_antenna_diameter_m: TX antenna diameter in meters (enables aperture check)
+        rx_antenna_diameter_m: RX antenna diameter in meters (enables aperture check)
+    """
+    try:
+        result = lb_engine.compute_link_budget(
+            tx_power_dbm=tx_power_dbm,
+            tx_antenna_gain_dbi=tx_antenna_gain_dbi,
+            rx_antenna_gain_dbi=rx_antenna_gain_dbi,
+            frequency_hz=frequency_hz,
+            distance_m=distance_m,
+            tx_losses_db=tx_losses_db,
+            rx_losses_db=rx_losses_db,
+            tx_antenna_diameter_m=tx_antenna_diameter_m,
+            rx_antenna_diameter_m=rx_antenna_diameter_m,
+        )
+        return LinkBudgetOutput(**result).model_dump()
+    except PhysicalViolationError as e:
+        return e.to_dict()
+
+
+@mcp.tool
+def shannon_hartley(
+    bandwidth_hz: float,
+    snr_linear: float | None = None,
+    snr_db: float | None = None,
+    claimed_throughput_bps: float | None = None,
+) -> dict:
+    """Calculate Shannon-Hartley channel capacity and validate throughput claims.
+
+    Computes the theoretical maximum data rate C = B * log2(1 + SNR) for an AWGN
+    channel. If a claimed throughput is provided, validates it against this limit.
+    Any claim exceeding the Shannon limit is a physical impossibility.
+
+    Use this tool when you need to:
+    - Calculate maximum achievable throughput for a given bandwidth and SNR
+    - Validate whether a throughput claim is physically possible
+    - Determine spectral efficiency limits
+    - Check if a modulation/coding scheme claim is realistic
+
+    Returns a PhysicalViolationError dict when a claim exceeds the Shannon limit.
+
+    Args:
+        bandwidth_hz: Channel bandwidth in Hz (must be > 0)
+        snr_linear: Signal-to-noise ratio (linear, not dB). Provide this OR snr_db.
+        snr_db: Signal-to-noise ratio in dB. Provide this OR snr_linear.
+        claimed_throughput_bps: Optional throughput claim to validate in bits/sec
+    """
+    try:
+        # Validate and resolve SNR
+        params = ShannonInput(
+            bandwidth_hz=bandwidth_hz,
+            snr_linear=snr_linear,
+            snr_db=snr_db,
+            claimed_throughput_bps=claimed_throughput_bps,
+        )
+
+        # Resolve SNR to both representations
+        if params.snr_db is not None:
+            resolved_snr_linear = db_to_linear(params.snr_db)
+            resolved_snr_db = params.snr_db
+        else:
+            resolved_snr_linear = params.snr_linear
+            resolved_snr_db = linear_to_db(params.snr_linear)
+
+        capacity = sh_engine.channel_capacity_bps(params.bandwidth_hz, resolved_snr_linear)
+        eta = sh_engine.spectral_efficiency(resolved_snr_linear)
+
+        # If throughput claim provided, validate it
+        claim_is_valid = None
+        excess_percentage = None
+        warnings = []
+
+        if params.claimed_throughput_bps is not None:
+            result = sh_engine.validate_throughput_claim(
+                params.bandwidth_hz, resolved_snr_linear, params.claimed_throughput_bps
+            )
+            claim_is_valid = result["claim_is_valid"]
+            excess_percentage = result["excess_percentage"]
+            warnings = result["warnings"]
+
+        human_readable = (
+            f"Shannon-Hartley Capacity:\n"
+            f"  Bandwidth:  {params.bandwidth_hz / 1e6:.3f} MHz\n"
+            f"  SNR:        {resolved_snr_db:.1f} dB ({resolved_snr_linear:.2f} linear)\n"
+            f"  Capacity:   {capacity:.1f} bps ({capacity / 1e6:.3f} Mbps)\n"
+            f"  Spectral Efficiency: {eta:.3f} bps/Hz"
+        )
+
+        latex = (
+            rf"$C = B \log_2(1 + \text{{SNR}}) = "
+            rf"{params.bandwidth_hz:.0f} \times \log_2(1 + {resolved_snr_linear:.2f}) = "
+            rf"{capacity:.1f}\,\text{{bps}}$"
+        )
+
+        return ShannonOutput(
+            capacity_bps=capacity,
+            spectral_efficiency_bps_hz=eta,
+            snr_db=resolved_snr_db,
+            snr_linear=resolved_snr_linear,
+            claimed_throughput_bps=params.claimed_throughput_bps,
+            claim_is_valid=claim_is_valid,
+            excess_percentage=excess_percentage,
+            human_readable=human_readable,
+            latex=latex,
+            warnings=warnings,
+        ).model_dump()
+
+    except PhysicalViolationError as e:
+        return e.to_dict()
+
+
+@mcp.tool
+def noise_floor(
+    bandwidth_hz: float,
+    temperature_k: float = 290.0,
+    stages: list[dict] | None = None,
+    required_snr_db: float | None = None,
+) -> dict:
+    """Calculate thermal noise power (kTB), cascaded noise figure, and receiver sensitivity.
+
+    Computes the fundamental thermal noise floor N = k_B * T * B, which is
+    -174 dBm/Hz at the IEEE standard temperature of 290K. Optionally cascades
+    multiple amplifier/filter stages using the Friis noise figure formula
+    F_total = F_1 + (F_2-1)/G_1 + (F_3-1)/(G_1*G_2) + ... and computes
+    receiver sensitivity as S_min = N_floor + NF + SNR_required.
+
+    Use this tool when you need to:
+    - Determine the thermal noise floor for a receiver bandwidth
+    - Cascade noise figures through a multi-stage receiver chain
+    - Calculate minimum detectable signal / receiver sensitivity
+    - Validate that a claimed noise figure is physically plausible
+
+    Returns a PhysicalViolationError dict if inputs violate thermodynamic limits.
+
+    Args:
+        bandwidth_hz: Receiver bandwidth in Hz (must be > 0)
+        temperature_k: System noise temperature in Kelvin (default: 290K, must be >= 0)
+        stages: Optional list of stages, each with 'gain_db' and 'noise_figure_db' keys
+        required_snr_db: Required SNR in dB for sensitivity calculation
+    """
+    try:
+        params = NoiseFloorInput(
+            bandwidth_hz=bandwidth_hz,
+            temperature_k=temperature_k,
+            stages=[{"gain_db": s["gain_db"], "noise_figure_db": s["noise_figure_db"]}
+                    for s in stages] if stages else None,
+            required_snr_db=required_snr_db,
+        )
+
+        n_dbm = nz_engine.thermal_noise_power_dbm(params.bandwidth_hz, params.temperature_k)
+        n_watts = nz_engine.thermal_noise_power_watts(params.bandwidth_hz, params.temperature_k)
+
+        warnings = []
+        cascaded_nf_db = None
+        system_noise_temp_k = None
+        sensitivity_dbm = None
+
+        # Friis noise cascade if stages provided
+        if params.stages:
+            stage_tuples = [(s.gain_db, s.noise_figure_db) for s in params.stages]
+            cascaded_nf_db = nz_engine.friis_noise_cascade(stage_tuples)
+            # System noise temperature: T_sys = T_ref * (F - 1)
+            f_linear = db_to_linear(cascaded_nf_db)
+            system_noise_temp_k = params.temperature_k * (f_linear - 1)
+
+        # Receiver sensitivity
+        if params.required_snr_db is not None:
+            nf = cascaded_nf_db if cascaded_nf_db is not None else 0.0
+            sensitivity_dbm = nz_engine.receiver_sensitivity_dbm(
+                params.bandwidth_hz, nf, params.required_snr_db, params.temperature_k
+            )
+
+        human_readable = (
+            f"Thermal Noise Floor:\n"
+            f"  Temperature: {params.temperature_k:.1f} K\n"
+            f"  Bandwidth:   {params.bandwidth_hz / 1e6:.3f} MHz\n"
+            f"  Noise Power: {n_dbm:.2f} dBm ({n_watts:.3e} W)"
+        )
+        if cascaded_nf_db is not None:
+            human_readable += f"\n  Cascaded NF: {cascaded_nf_db:.2f} dB"
+        if sensitivity_dbm is not None:
+            human_readable += f"\n  Sensitivity: {sensitivity_dbm:.2f} dBm"
+
+        latex = (
+            rf"$N = k_B T B = {BOLTZMANN_VAL:.4e} \times {params.temperature_k:.1f} "
+            rf"\times {params.bandwidth_hz:.0f} = {n_dbm:.2f}\,\text{{dBm}}$"
+        )
+
+        return NoiseFloorOutput(
+            thermal_noise_dbm=n_dbm,
+            thermal_noise_watts=n_watts,
+            cascaded_noise_figure_db=cascaded_nf_db,
+            system_noise_temp_k=system_noise_temp_k,
+            receiver_sensitivity_dbm=sensitivity_dbm,
+            human_readable=human_readable,
+            latex=latex,
+            warnings=warnings,
+        ).model_dump()
+
+    except PhysicalViolationError as e:
+        return e.to_dict()
+
+
+# Constant for LaTeX rendering
+BOLTZMANN_VAL = 1.380649e-23
+
+
+def main():
+    """Entry point for `physbound` console script and stdio MCP."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

physbound/validators.py

@@ -0,0 +1,70 @@
+"""Hard-limit guard functions enforcing physical laws.
+
+These validators are called by engine modules before computation to reject
+inputs that would violate fundamental physics. Each raises PhysicalViolationError
+with a LaTeX explanation on failure.
+"""
+
+from physbound.errors import PhysicalViolationError
+
+
+def validate_positive_frequency(frequency_hz: float) -> None:
+    """Reject non-positive frequencies."""
+    if frequency_hz <= 0:
+        raise PhysicalViolationError(
+            message=f"Frequency must be positive, got {frequency_hz} Hz",
+            law_violated="Electromagnetic Theory",
+            latex_explanation=r"$f > 0$ required; negative or zero frequency is non-physical",
+            claimed_value=frequency_hz,
+            unit="Hz",
+        )
+
+
+def validate_positive_distance(distance_m: float) -> None:
+    """Reject non-positive distances."""
+    if distance_m <= 0:
+        raise PhysicalViolationError(
+            message=f"Distance must be positive, got {distance_m} m",
+            law_violated="Euclidean Geometry",
+            latex_explanation=r"$d > 0$ required for physical separation between TX and RX",
+            claimed_value=distance_m,
+            unit="m",
+        )
+
+
+def validate_positive_bandwidth(bandwidth_hz: float) -> None:
+    """Reject non-positive bandwidths."""
+    if bandwidth_hz <= 0:
+        raise PhysicalViolationError(
+            message=f"Bandwidth must be positive, got {bandwidth_hz} Hz",
+            law_violated="Signal Processing",
+            latex_explanation=r"$B > 0$ required; zero or negative bandwidth is non-physical",
+            claimed_value=bandwidth_hz,
+            unit="Hz",
+        )
+
+
+def validate_temperature(temperature_k: float) -> None:
+    """Reject negative absolute temperatures."""
+    if temperature_k < 0:
+        raise PhysicalViolationError(
+            message=f"Temperature must be >= 0 K, got {temperature_k} K",
+            law_violated="Third Law of Thermodynamics",
+            latex_explanation=(
+                r"$T \geq 0\,\text{K}$ required by the third law of thermodynamics; "
+                r"negative absolute temperature is non-physical in this context"
+            ),
+            claimed_value=temperature_k,
+            unit="K",
+        )
+
+
+def validate_positive_snr(snr_linear: float) -> None:
+    """Reject non-positive linear SNR values."""
+    if snr_linear <= 0:
+        raise PhysicalViolationError(
+            message=f"SNR (linear) must be positive, got {snr_linear}",
+            law_violated="Information Theory",
+            latex_explanation=r"$\text{SNR} > 0$ required; signal power cannot be non-positive",
+            claimed_value=snr_linear,
+        )

physbound-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: physbound
+Version: 0.1.0
+Summary: Physical Layer Linter — validates RF and physics calculations against hard physical limits
+Project-URL: Homepage, https://github.com/JonesRobM/physbound
+Project-URL: Repository, https://github.com/JonesRobM/physbound
+Project-URL: Issues, https://github.com/JonesRobM/physbound/issues
+Author-email: Robert Jones <jonesrobm@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Requires-Dist: fastmcp==2.14.5
+Requires-Dist: numpy==2.2.3
+Requires-Dist: pint==0.25.2
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: scipy==1.15.2
+Provides-Extra: dev
+Requires-Dist: mypy==1.15.0; extra == 'dev'
+Requires-Dist: pre-commit==4.1.0; extra == 'dev'
+Requires-Dist: pytest-cov==6.0.0; extra == 'dev'
+Requires-Dist: pytest==8.3.5; extra == 'dev'
+Requires-Dist: python-dotenv>=1.1.0; extra == 'dev'
+Requires-Dist: ruff==0.9.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PhysBound
+
+**Physical Layer Linter** — An MCP server that validates RF and physics calculations against hard physical limits. Catches AI hallucinations in engineering workflows.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-107%20passed-brightgreen.svg)]()
+
+---
+
+## What LLMs Get Wrong
+
+LLMs routinely hallucinate physics. PhysBound catches it:
+
+| # | Category | LLM Hallucination | PhysBound Truth | Verdict |
+|---|----------|-------------------|-----------------|---------|
+| 1 | Shannon-Hartley | "20 MHz 802.11n at 15 dB SNR achieves 500 Mbps" | Shannon limit: **100.6 Mbps** | CAUGHT |
+| 2 | Shannon-Hartley | "100 MHz 5G channel at 20 dB SNR delivers 2 Gbps" | Shannon limit: **665.8 Mbps** | CAUGHT |
+| 3 | Antenna Aperture | "30 cm dish at 1 GHz provides 45 dBi gain" | Aperture limit: **7.4 dBi** | CAUGHT |
+| 4 | Thermal Noise | "Noise floor of -180 dBm/Hz at room temperature" | Actual: **-174.0 dBm/Hz** at 290K | CAUGHT |
+| 5 | Link Budget | "Wi-Fi at 2.4 GHz reaches 10 km at -40 dBm" | Actual RX power: **-94.1 dBm** | CAUGHT |
+| 6 | Link Budget | "1W to GEO with 0 dBi antennas at -80 dBm" | Actual RX power: **-175.1 dBm** | CAUGHT |
+
+*Generated automatically by `pytest tests/test_marketing.py -s`*
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+pip install physbound
+```
+
+### Use with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "physbound": {
+      "command": "uv",
+      "args": ["run", "--from", "physbound", "physbound"]
+    }
+  }
+}
+```
+
+That's it. Claude now has access to physics-validated RF calculations.
+
+---
+
+## Tools
+
+### `rf_link_budget`
+
+Computes a full RF link budget using the Friis transmission equation. Validates antenna gains against aperture limits.
+
+**Example:** *"What's the received power for a 2.4 GHz link at 100 m with 20 dBm TX, 10 dBi TX gain, 3 dBi RX gain?"*
+
+Returns: FSPL, received power, wavelength, and optional aperture limit checks. Rejects antenna gains that violate `G_max = eta * (pi * D / lambda)^2`.
+
+### `shannon_hartley`
+
+Computes Shannon-Hartley channel capacity `C = B * log2(1 + SNR)` and validates throughput claims.
+
+**Example:** *"Can a 20 MHz channel with 15 dB SNR support 500 Mbps?"*
+
+Returns: Theoretical capacity, spectral efficiency, and whether the claim is physically possible. Flags violations with the exact percentage by which the claim exceeds the Shannon limit.
+
+### `noise_floor`
+
+Computes thermal noise power `N = k_B * T * B`, cascades noise figures through multi-stage receivers using the Friis noise formula, and calculates receiver sensitivity.
+
+**Example:** *"What's the noise floor for a 1 MHz receiver at 290K with a two-stage LNA chain?"*
+
+Returns: Thermal noise in dBm and watts, cascaded noise figure, system noise temperature, and receiver sensitivity.
+
+---
+
+## Physics Guarantees
+
+Every calculation is validated against hard physical limits:
+
+- **Speed of light:** `c = 299,792,458 m/s` — no exceptions
+- **Thermal noise floor:** `N = -174 dBm/Hz` at 290K — the IEEE standard reference
+- **Shannon limit:** `C = B * log2(1 + SNR)` — no throughput claim exceeds this
+- **Aperture limit:** `G_max = eta * (pi * D / lambda)^2` — antenna gain is bounded by physics
+
+Violations return structured `PhysicalViolationError` responses with LaTeX explanations, not silent failures.
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/JonesRobM/physbound.git
+cd physbound
+uv sync --all-extras
+
+# Run tests
+uv run pytest tests/ -v
+
+# Print hallucination delta table
+uv run pytest tests/test_marketing.py -s
+
+# Start MCP server locally
+uv run physbound
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

physbound-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+physbound/__init__.py,sha256=95SB7Cb_K3ZjQDu6wp0UE8ofrvCaW59zh1SOq_GIg0s,97
+physbound/errors.py,sha256=bnWVIJAY-KrypBS0X3gUt6LInCPsj_pHn-sUgoTZvYo,1041
+physbound/server.py,sha256=Q9MdPPK0xxMcYAlnOc5E4OoCkXF2ejq9ixituW44a80,11187
+physbound/validators.py,sha256=q5JJutOxznBlSo4vW4fAHNrWWVsZHn0doqCZ9qv-Tg4,2692
+physbound/engines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+physbound/engines/constants.py,sha256=YFjFdCZ_D3aPuYmjToT_Oxb35fVZjkTEbGz4jXXIkmM,928
+physbound/engines/link_budget.py,sha256=FczE30W0FV6nxVsbkgDUfYBbKF15CqJUUsA9VMesCf4,7599
+physbound/engines/noise.py,sha256=Da27RZrxpSpBWnC-n0NJHqCMX9jGzK69tl-QHXfbfYc,4088
+physbound/engines/shannon.py,sha256=CZoTN19JcDbR5jFHpo772R4OfxT_N4nrHVqznX4od28,3620
+physbound/engines/units.py,sha256=ddAZLCFS1qHSsRHhJSaoMFQWuXixkDP7-Dx1dyHILKA,3478
+physbound/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+physbound/models/common.py,sha256=66VWbzqSM1b0XxVIiIMa-0ojD8lrR9uiM1vpCMnybuA,265
+physbound/models/link_budget.py,sha256=3cBiWAWtoZVvCLVhHGycaqK08Le_DSkHZ8YC3I7EMEQ,1416
+physbound/models/noise.py,sha256=PZ4clSzFsJ5omA2ZbgxiY1l3tBLahgSs3DRKTv3f_9Q,1344
+physbound/models/shannon.py,sha256=ZVC7O35LKOrohiyTwlt-Neo39XGFw2l326Xlc4yaS2M,1478
+physbound-0.1.0.dist-info/METADATA,sha256=68U98NW3_kUEhB_PTwF4oDfHTHesOWQYwd81Pjhbxhw,5124
+physbound-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+physbound-0.1.0.dist-info/entry_points.txt,sha256=nQ1ILpnBm3CqMU0Ygzmk9yt866Ki0EooQmN7DcwIp5M,52
+physbound-0.1.0.dist-info/licenses/LICENSE,sha256=t7gUixl245pipySIQOuZ0P-TCdxmtgKQfaRmryGa7iU,1069
+physbound-0.1.0.dist-info/RECORD,,

physbound-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

physbound-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+physbound = physbound.server:main

physbound-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.