costroid_power/lib.rs
1//! `costroid-power` — the local-inference economics engine (the headline differentiator, §3.1.B).
2//!
3//! This crate owns the **dual-mode** power/cost model: it turns a local model run (token counts +
4//! real or estimated power draw integrated over wall-clock time) into **joules/token**, **Wh per
5//! 1M tokens**, and **$ per 1M tokens**, with the measurement source stamped on every figure (R6).
6//!
7//! # Status — M3a in progress (built on the M0 scaffold)
8//! In place and green on every target: the [`PowerSampler`] abstraction (§6.3) with its **four**
9//! sources and the wall-meter-led runtime selector, the [`MeasurementMode`] stamp (§6.4), and
10//! the [`cost`] model (§3.2) with deterministic worked-example tests. **Deferred to M3b
11//! (human-gated, on real hardware):** the live sysfs read confirmation on the gfx1151 APU, the
12//! LibreHardwareMonitor live loopback read (M3a ships its parser seam), and a captured
13//! joules/token figure — no real power number is ever fabricated in code (R10).
14//!
15//! # Invariants honored here
16//! - **No `unwrap`/`expect`/`panic!`** in library code; every failure is a [`PowerError`].
17//! - **Gated by `#[cfg(target_os = "linux")]` + the off-by-default `power` feature** (R1, named
18//! `power` not `telemetry`): non-Linux / feature-off builds compile a clean "unavailable"
19//! path, never a broken build, and the default workspace build never links a power path.
20//! - **No network, no GPU FFI:** the inference runner is a *subprocess* (A2), so this crate
21//! pulls no HTTP client and (with `unsafe_code = "forbid"` workspace-wide) no `unsafe` bindings.
22
23pub mod cost;
24mod error;
25pub mod harness;
26mod measured;
27mod mode;
28pub mod models;
29pub mod profile;
30pub mod runner;
31mod sampler;
32
33pub use cost::{cloud_cost, local_run_cost, CostInputs, LocalRunCost};
34pub use error::PowerError;
35pub use harness::{
36 average_watts, benchmark_id, compute_report, estimate_run, run_measured, LocalRunReport,
37 DEFAULT_BENCHMARK_SUITE,
38};
39pub use measured::{measured_mode_for, MEASURED_MODELS};
40pub use mode::MeasurementMode;
41pub use models::{bundled_models, ModelManifest, ModelQuality, ModelSpec, GEMMA4_MANIFEST_AS_OF};
42pub use profile::{
43 bundled_power_profiles, ElectricityRate, HardwareProfile, PowerProfiles, ProfileOverrides,
44 ResolvedProfile, DEFAULT_HARDWARE_PROFILE_ID, POWER_PROFILE_AS_OF,
45};
46pub use runner::{
47 parse_llama_cpp_stats, parse_ollama_stats, LlamaCppRunner, OllamaRunner, RunOutput, RunSpec,
48 Runner, StubRunner,
49};
50pub use sampler::{
51 select_sampler, EstimatedPowerSampler, PowerSampler, SysfsPowerSampler, WallMeterPowerSampler,
52 WindowsLhmPowerSampler,
53};