use crate::providers;
pub const HYBRID_PREFIX: &str = "llmman.hybrid/";
const SEPARATOR: char = ',';
pub const ROUTE_HEADER: &str = "x-llmman-route";
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Pair<'a> {
pub local: &'a str,
pub provider: &'a str,
pub model: &'a str,
}
impl Pair<'_> {
pub fn remote_ref(&self) -> String {
providers::format_remote_ref(self.provider, self.model)
}
pub fn side_ref(&self, side: Side) -> String {
match side {
Side::Local => self.local.to_string(),
Side::Cloud => self.remote_ref(),
}
}
}
fn format_ref(local: &str, provider: &str, model: &str) -> String {
format!("{HYBRID_PREFIX}{local}{SEPARATOR}{provider}/{model}")
}
pub fn split_ref(reference: &str) -> Option<Pair<'_>> {
let rest = reference.strip_prefix(HYBRID_PREFIX)?;
let (local, remote) = rest.split_once(SEPARATOR)?;
let (provider, model) = remote.split_once('/')?;
(!local.is_empty() && !provider.is_empty() && !model.is_empty() && is_local_ref(local))
.then_some(Pair {
local,
provider,
model,
})
}
fn is_local_ref(reference: &str) -> bool {
!providers::is_remote_ref(reference) && !reference.starts_with(HYBRID_PREFIX)
}
pub fn is_hybrid_ref(reference: &str) -> bool {
split_ref(reference).is_some()
}
pub fn local_half(reference: &str) -> &str {
split_ref(reference).map_or(reference, |pair| pair.local)
}
pub fn pair_with_local(local: &str, remote_ref: &str) -> anyhow::Result<String> {
let (provider, model) = providers::split_remote_ref(remote_ref)
.ok_or_else(|| anyhow::anyhow!("not a provider-routed reference: {remote_ref}"))?;
anyhow::ensure!(
!local.is_empty(),
"a hybrid pair needs a local model as well as {provider}/{model}"
);
anyhow::ensure!(
!local.contains(SEPARATOR),
"local model {local:?} cannot be paired: {SEPARATOR:?} separates the two halves of a \
hybrid reference"
);
anyhow::ensure!(
is_local_ref(local),
"{local:?} is not served on this machine, so it cannot be a pair's local half"
);
Ok(format_ref(local, provider, model))
}
pub fn overflow_flags<'a>(
provider: Option<&'a str>,
model: Option<&'a str>,
primary_provider: Option<&str>,
) -> anyhow::Result<Option<(&'a str, &'a str)>> {
let provider = provider.map(str::trim);
let model = model.map(str::trim);
match (provider, model) {
(None, None) => Ok(None),
(Some(_), None) => anyhow::bail!(
"--overflow-provider also needs --overflow-model naming that provider's model"
),
(None, Some(_)) => anyhow::bail!(
"--overflow-model also needs --overflow-provider (openai, anthropic, openrouter, ...)"
),
(Some(provider), Some(model)) => {
anyhow::ensure!(
!provider.is_empty() && !model.is_empty(),
"--overflow-provider and --overflow-model both need a value"
);
anyhow::ensure!(
primary_provider.is_none(),
"--overflow-provider pairs a hosted model with the local --model, so it cannot \
be combined with --provider: pass the local model as --model."
);
Ok(Some((provider, model)))
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Side {
Local,
Cloud,
}
impl Side {
pub fn as_str(self) -> &'static str {
match self {
Self::Local => "local",
Self::Cloud => "cloud",
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Reason {
Pinned,
Overflow { bytes: u64, budget: u64 },
LocalFirst,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Decision {
pub side: Side,
pub reason: Reason,
}
pub fn route(pin: Option<Side>, request_bytes: Option<u64>, budget: Option<u64>) -> Decision {
if let Some(side) = pin {
return Decision {
side,
reason: Reason::Pinned,
};
}
match (request_bytes, budget) {
(Some(bytes), Some(budget)) if bytes > budget => Decision {
side: Side::Cloud,
reason: Reason::Overflow { bytes, budget },
},
_ => Decision {
side: Side::Local,
reason: Reason::LocalFirst,
},
}
}
pub fn parse_pin(value: Option<&[u8]>) -> anyhow::Result<Option<Side>> {
let Some(value) = value else {
return Ok(None);
};
let value = std::str::from_utf8(value)
.map_err(|_| anyhow::anyhow!("{ROUTE_HEADER}: value is not valid UTF-8"))?
.trim();
if value.is_empty() {
return Ok(None);
}
match value.to_ascii_lowercase().as_str() {
"local" => Ok(Some(Side::Local)),
"cloud" => Ok(Some(Side::Cloud)),
other => anyhow::bail!(
"{ROUTE_HEADER}: {other:?} is not a side of a hybrid pair, use \"local\" or \"cloud\""
),
}
}
const BYTES_PER_TOKEN: u64 = 4;
pub fn local_budget_bytes(ctx_size: Option<u32>, env: Option<&str>) -> Option<u64> {
match local_budget_override(env) {
Some(bytes) => bytes,
None => ctx_size.and_then(budget_bytes_for_ctx),
}
}
pub fn local_budget_override(env: Option<&str>) -> Option<Option<u64>> {
let value = env.map(str::trim).filter(|v| !v.is_empty())?;
match value.parse::<u64>() {
Ok(0) => Some(None),
Ok(bytes) => Some(Some(bytes)),
Err(_) => None,
}
}
pub fn budget_bytes_for_ctx(ctx_size: u32) -> Option<u64> {
(ctx_size > 0).then(|| u64::from(ctx_size).saturating_mul(BYTES_PER_TOKEN))
}
pub fn local_budget_bytes_from_env(ctx_size: Option<u32>) -> Option<u64> {
local_budget_bytes(
ctx_size,
std::env::var("LLMMAN_HYBRID_LOCAL_BYTES").ok().as_deref(),
)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_pair_round_trips_through_its_reference() {
let reference = format_ref("gemma4", "anthropic", "claude-sonnet-4-5");
assert_eq!(
reference,
"llmman.hybrid/gemma4,anthropic/claude-sonnet-4-5"
);
assert_eq!(
split_ref(&reference),
Some(Pair {
local: "gemma4",
provider: "anthropic",
model: "claude-sonnet-4-5",
})
);
}
#[test]
fn both_halves_keep_their_own_slashes() {
let reference = format_ref(
"hf.co/ggml-org/gemma-3-270m-GGUF",
"openrouter",
"z-ai/glm-5",
);
let pair = split_ref(&reference).expect("multi-segment halves must parse");
assert_eq!(pair.local, "hf.co/ggml-org/gemma-3-270m-GGUF");
assert_eq!(pair.provider, "openrouter");
assert_eq!(pair.model, "z-ai/glm-5");
}
#[test]
fn a_plain_reference_is_not_a_pair() {
for reference in [
"gemma4",
"hf.co/ggml-org/gemma-3-270m-GGUF",
"llmman.provider/anthropic/claude-sonnet-4-5",
"llmman.hybrid/gemma4",
"llmman.hybrid/gemma4,anthropic",
"llmman.hybrid/,anthropic/claude",
"llmman.hybrid/gemma4,/claude",
"llmman.hybrid/gemma4,anthropic/",
] {
assert_eq!(split_ref(reference), None, "{reference} parsed as a pair");
assert!(!is_hybrid_ref(reference), "{reference} parsed as a pair");
}
}
#[test]
fn a_local_half_that_is_not_local_is_not_a_pair() {
for reference in [
"llmman.hybrid/llmman.provider/openai/gpt-5,anthropic/claude",
"llmman.hybrid/llmman.hybrid/a,b/c,anthropic/claude",
] {
assert_eq!(split_ref(reference), None, "{reference} parsed as a pair");
}
assert!(pair_with_local(
"llmman.provider/openai/gpt-5",
"llmman.provider/anthropic/claude"
)
.is_err());
}
#[test]
fn side_ref_yields_an_ordinary_reference_for_either_half() {
let pair = split_ref("llmman.hybrid/gemma4,anthropic/claude-sonnet-4-5").unwrap();
assert_eq!(pair.side_ref(Side::Local), "gemma4");
assert_eq!(
pair.side_ref(Side::Cloud),
"llmman.provider/anthropic/claude-sonnet-4-5"
);
assert!(!is_hybrid_ref(&pair.side_ref(Side::Local)));
assert!(!is_hybrid_ref(&pair.side_ref(Side::Cloud)));
}
#[test]
fn local_half_of_a_pair_or_the_reference_itself() {
assert_eq!(
local_half("llmman.hybrid/gemma4,anthropic/claude-sonnet-4-5"),
"gemma4"
);
assert_eq!(local_half("gemma4:latest"), "gemma4:latest");
assert_eq!(
local_half("llmman.provider/anthropic/claude"),
"llmman.provider/anthropic/claude"
);
}
#[test]
fn pair_with_local_wraps_a_provider_reference() {
let remote = providers::format_remote_ref("anthropic", "claude-sonnet-4-5");
assert_eq!(
pair_with_local("gemma4", &remote).unwrap(),
"llmman.hybrid/gemma4,anthropic/claude-sonnet-4-5"
);
}
#[test]
fn pair_with_local_rejects_halves_it_could_not_recover() {
assert!(pair_with_local("gemma4", "claude-sonnet-4-5").is_err());
assert!(pair_with_local("", "llmman.provider/anthropic/claude").is_err());
assert!(pair_with_local("a,b", "llmman.provider/anthropic/claude").is_err());
}
#[test]
fn overflow_flags_need_each_other() {
assert_eq!(
overflow_flags(Some("anthropic"), Some("claude"), None).unwrap(),
Some(("anthropic", "claude"))
);
assert_eq!(overflow_flags(None, None, None).unwrap(), None);
assert_eq!(overflow_flags(None, None, Some("openai")).unwrap(), None);
let err = overflow_flags(Some("anthropic"), None, None).unwrap_err();
assert!(err.to_string().contains("--overflow-model"), "{err}");
let err = overflow_flags(None, Some("claude"), None).unwrap_err();
assert!(err.to_string().contains("--overflow-provider"), "{err}");
}
#[test]
fn overflow_flags_refuse_a_hosted_primary() {
let err = overflow_flags(Some("anthropic"), Some("claude"), Some("openai")).unwrap_err();
assert!(err.to_string().contains("--provider"), "{err}");
}
#[test]
fn overflow_flags_reject_blank_values_and_trim() {
assert!(overflow_flags(Some(""), Some("claude"), None).is_err());
assert!(overflow_flags(Some("anthropic"), Some(" "), None).is_err());
assert_eq!(
overflow_flags(Some(" anthropic "), Some(" claude "), None).unwrap(),
Some(("anthropic", "claude"))
);
}
#[test]
fn nothing_in_particular_stays_local() {
assert_eq!(
route(None, Some(1024), Some(262_144)),
Decision {
side: Side::Local,
reason: Reason::LocalFirst
}
);
}
#[test]
fn a_request_past_the_local_budget_goes_to_the_provider() {
assert_eq!(
route(None, Some(262_145), Some(262_144)),
Decision {
side: Side::Cloud,
reason: Reason::Overflow {
bytes: 262_145,
budget: 262_144
}
}
);
assert_eq!(route(None, Some(262_144), Some(262_144)).side, Side::Local);
}
#[test]
fn an_unknown_size_or_no_budget_stays_local() {
assert_eq!(route(None, None, Some(1)).side, Side::Local);
assert_eq!(route(None, Some(u64::MAX), None).side, Side::Local);
assert_eq!(route(None, None, None).side, Side::Local);
}
#[test]
fn a_pinned_side_beats_every_other_rule() {
assert_eq!(
route(Some(Side::Cloud), Some(1), Some(u64::MAX)),
Decision {
side: Side::Cloud,
reason: Reason::Pinned
}
);
assert_eq!(
route(Some(Side::Local), Some(u64::MAX), Some(1)),
Decision {
side: Side::Local,
reason: Reason::Pinned
}
);
}
#[test]
fn parse_pin_reads_both_sides_case_insensitively() {
assert_eq!(parse_pin(Some(b"local")).unwrap(), Some(Side::Local));
assert_eq!(parse_pin(Some(b" Local ")).unwrap(), Some(Side::Local));
assert_eq!(parse_pin(Some(b"cloud")).unwrap(), Some(Side::Cloud));
assert_eq!(parse_pin(Some(b"CLOUD")).unwrap(), Some(Side::Cloud));
}
#[test]
fn parse_pin_treats_absent_and_blank_alike() {
assert_eq!(parse_pin(None).unwrap(), None);
assert_eq!(parse_pin(Some(b"")).unwrap(), None);
assert_eq!(parse_pin(Some(b" ")).unwrap(), None);
}
#[test]
fn parse_pin_rejects_anything_that_is_not_a_side() {
for value in [
&b"locl"[..],
b"on-device",
b"remote",
b"true",
b"cloud,local",
&[0xff, 0xfe][..],
] {
let err = parse_pin(Some(value)).expect_err("must not parse as a side");
assert!(
err.to_string().contains(ROUTE_HEADER),
"error must name the header: {err}"
);
}
}
#[test]
fn the_budget_follows_the_daemons_own_context_length() {
assert_eq!(local_budget_bytes(Some(65536), None), Some(262_144));
assert_eq!(local_budget_bytes(Some(4096), None), Some(16_384));
}
#[test]
fn no_context_length_means_no_budget() {
assert_eq!(local_budget_bytes(None, None), None);
assert_eq!(local_budget_bytes(Some(0), None), None);
}
#[test]
fn the_environment_overrides_the_estimate() {
assert_eq!(local_budget_bytes(Some(65536), Some("1024")), Some(1024));
assert_eq!(local_budget_bytes(None, Some("1024")), Some(1024));
}
#[test]
fn zero_disables_the_overflow_rule_entirely() {
assert_eq!(local_budget_bytes(Some(65536), Some("0")), None);
assert_eq!(route(None, Some(u64::MAX), None).side, Side::Local);
}
#[test]
fn an_override_is_flagged_exactly_when_it_ignores_the_context_size() {
for env in [None, Some("1024"), Some("0"), Some("lots"), Some(" ")] {
let derived = local_budget_bytes(Some(4096), env);
let stated = local_budget_override(env);
assert_eq!(
stated.is_some(),
derived != Some(16_384),
"{env:?} is flagged as stated but derived {derived:?}"
);
if let Some(stated) = stated {
assert_eq!(stated, derived, "{env:?}");
}
}
}
#[test]
fn an_unparseable_override_falls_back_to_the_estimate() {
assert_eq!(local_budget_bytes(Some(4096), Some("lots")), Some(16_384));
assert_eq!(local_budget_bytes(Some(4096), Some("-1")), Some(16_384));
assert_eq!(local_budget_bytes(Some(4096), Some(" ")), Some(16_384));
}
#[test]
fn an_absurd_context_length_does_not_overflow_the_budget() {
assert_eq!(
local_budget_bytes(Some(u32::MAX), None),
Some(u64::from(u32::MAX) * 4)
);
}
}