API Reference¶
Core models¶
InferenceRequest¶
The unit of measurement. Every API hit generates one.
class InferenceRequest(BaseModel):
request_id: str
model_id: str
data_center_id: str
hardware_id: str
input_tokens: int
output_tokens: int
batch_size: int = 1
wall_clock_seconds: float | None = None
measured_gpu_joules: float | None = None
measured_host_joules: float | None = None
measured_gpu_utilization: float | None = None
grid_gco2_per_kwh: float | None = None
timestamp: datetime = datetime.now(timezone.utc)
ImpactEstimate¶
The environmental receipt returned for each request.
class ImpactEstimate(BaseModel):
request_id: str
tier: Tier
category: ImpactCategory
interval: PredictionInterval
unit: str
pedigree_gsd2: float
attribution_share: float = 1.0
methodology_notes: list[str]
sources: list[str]
computed_at: datetime
PredictionInterval¶
A 90% prediction interval produced by conformal calibration or Monte Carlo propagation.
class PredictionInterval(BaseModel):
point: float
lower: float
upper: float
coverage: float = 0.90
method: Literal["monte_carlo", "conformal", "bayesian_posterior"] = "monte_carlo"
Pipeline¶
Pipeline¶
class Pipeline:
def __init__(self, registry: Registry, config: PipelineConfig | None = None) -> None: ...
def estimate(self, request: InferenceRequest, force_tier: Tier | None = None) -> PipelineEstimate: ...
PipelineConfig¶
class PipelineConfig(BaseModel):
use_electricity_maps: bool = False
use_boaviztapi: bool = False
default_alpha: float = 0.10 # 90% coverage
fallback_to_lower_tier: bool = True
Registry¶
Registry¶
class Registry:
def register_model(self, card: ModelCard) -> None: ...
def register_hardware(self, profile: HardwareProfile) -> None: ...
def register_data_center(self, profile: DataCenterProfile) -> None: ...
def get_model(self, model_id: str) -> ModelCard | None: ...
def get_hardware(self, hardware_id: str) -> HardwareProfile | None: ...
def get_data_center(self, data_center_id: str) -> DataCenterProfile | None: ...
default_registry()¶
Returns a registry pre-loaded with illustrative entries. Not for production use without verification.
Uncertainty module¶
PedigreeScore¶
class PedigreeScore(NamedTuple):
reliability: int # 1-5
completeness: int # 1-5
temporal: int # 1-5
geographic: int # 1-5
technological: int # 1-5
sigma_ln / aggregate_gsd2¶
from vetted_inference.uncertainty import sigma_ln, aggregate_gsd2
sigma = sigma_ln(ped, flow_kind="energy_electricity")
gsd2 = aggregate_gsd2(ped, flow_kind="energy_electricity")
LogNormalParam / propagate¶
from vetted_inference.uncertainty import LogNormalParam, propagate
p1 = LogNormalParam(median=1.14, sigma_ln=0.20)
p2 = LogNormalParam(median=300.0, sigma_ln=0.15)
result = propagate(lambda c, g: c * g / 400.0, [p1, p2], n_draws=20_000)
calibrate_split_conformal / empirical_coverage¶
from vetted_inference.uncertainty import calibrate_split_conformal, empirical_coverage
calib = calibrate_split_conformal(point_predictions, actuals, alpha=0.10)
intervals = [calib.interval(p) for p in test_points]
coverage = empirical_coverage(intervals, test_actuals)