Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Agent helper utilities (reasoning options, model lists, etc.).
Keep this module free of agent state. It should only contain pure helpers.
Shared by OpenCode, Claude, and Codex integrations for reasoning-effort option building.
"""
from __future__ import annotations
from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
_REASONING_FALLBACK_OPTIONS = [
{"value": "low", "label": "Low"},
{"value": "medium", "label": "Medium"},
{"value": "high", "label": "High"},
]
_REASONING_VARIANT_ORDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]
# Explicit Off is a model-declared option, distinct from an unset effort.
# It remains truthy through the existing routing/default inheritance chain.
NO_REASONING_EFFORT = "none"
_REASONING_VARIANT_LABELS = {
"none": "None",
"minimal": "Minimal",
"low": "Low",
"medium": "Medium",
"high": "High",
"xhigh": "Extra High",
"max": "Max",
"ultra": "Ultra",
}
_UTILITY_MODEL_KEYWORDS = ["embedding", "tts", "whisper", "ada", "davinci", "turbo-instruct"]
def _parse_model_key(model_key: Optional[str]) -> tuple[str, str]:
if not model_key:
return "", ""
parts = model_key.split("/", 1)
if len(parts) != 2:
return "", ""
return parts[0], parts[1]
def _parse_provider_id(model_key: Optional[str]) -> Optional[str]:
provider_id, _ = _parse_model_key(model_key)
return provider_id or None
def get_opencode_provider_id(provider: dict | None) -> str:
if not isinstance(provider, dict):
return ""
provider_id = provider.get("id") or provider.get("provider_id") or provider.get("name") or ""
return provider_id if isinstance(provider_id, str) else ""
def _opencode_model_entry_id(model_entry: Any) -> str:
if isinstance(model_entry, str):
return model_entry
if not isinstance(model_entry, dict):
return ""
model_id = model_entry.get("id") or model_entry.get("modelID") or model_entry.get("model_id") or ""
return model_id if isinstance(model_id, str) else ""
def opencode_model_is_hub_projected(model_info: object) -> bool:
if not isinstance(model_info, dict):
return False
metadata = model_info.get("vibe_remote")
return (
isinstance(metadata, dict)
and metadata.get("model_hub_projected") is True
)
def opencode_model_picker_value(
provider_id: str,
model_id: str,
model_info: object,
) -> str:
"""Keep Model Hub's bare identity out of OpenCode transport addressing."""
if opencode_model_is_hub_projected(model_info):
return model_id
return f"{provider_id}/{model_id}" if provider_id else model_id
def _opencode_model_hub_model_ids(provider: dict) -> set[str]:
"""Return models projected from Model Hub for one public provider."""
projected: set[str] = set()
models = provider.get("models") if isinstance(provider, dict) else None
if isinstance(models, dict):
entries = models.items()
elif isinstance(models, list):
entries = ((_opencode_model_entry_id(entry), entry) for entry in models)
else:
return projected
for model_id, model_info in entries:
if not isinstance(model_id, str) or not isinstance(model_info, dict):
continue
if opencode_model_is_hub_projected(model_info):
projected.add(model_id)
return projected
def filter_opencode_models_to_allowed_providers(
opencode_models: dict,
allowed_providers: Iterable[str],
) -> dict:
"""Keep allowed providers plus exact public models projected by Model Hub."""
if not isinstance(opencode_models, dict):
return opencode_models
allowed = {
provider_id
for provider_id in allowed_providers
if isinstance(provider_id, str) and provider_id
}
providers = []
for provider in opencode_models.get("providers", []) or []:
if not isinstance(provider, dict):
continue
provider_id = get_opencode_provider_id(provider)
if not provider_id:
continue
projected_model_ids = _opencode_model_hub_model_ids(provider)
if provider_id in allowed:
providers.append(provider)
continue
if not projected_model_ids:
continue
raw_models = provider.get("models")
if isinstance(raw_models, dict):
models = {
model_id: model_info
for model_id, model_info in raw_models.items()
if model_id in projected_model_ids
}
elif isinstance(raw_models, list):
models = [
model_info
for model_info in raw_models
if _opencode_model_entry_id(model_info) in projected_model_ids
]
else:
models = {}
providers.append({**provider, "models": models})
return {**opencode_models, "providers": providers, "default": {}}
def find_opencode_model_info(
opencode_models: dict | None,
provider_id: str | None,
model_id: str | None,
) -> dict | None:
if not provider_id or not model_id or not isinstance(opencode_models, dict):
return None
for provider in opencode_models.get("providers", []) or []:
if get_opencode_provider_id(provider) != provider_id:
continue
models = provider.get("models", {}) if isinstance(provider, dict) else {}
if isinstance(models, dict):
model_info = models.get(model_id)
if isinstance(model_info, dict):
return model_info
return {} if model_info is not None else None
if isinstance(models, list):
for entry in models:
if _opencode_model_entry_id(entry) == model_id:
return entry if isinstance(entry, dict) else {}
return None
return None
def resolve_opencode_model_id(
opencode_models: dict | None,
provider_id: str | None,
model_id: str | None,
) -> str | None:
"""Return the catalog-canonical model id for a provider/model pair.
This does not lowercase user input. Exact catalog matches win; otherwise we
only adopt the catalog casing when there is exactly one case-insensitive
match. Ambiguous or unknown ids are preserved.
"""
if not provider_id or not model_id or not isinstance(opencode_models, dict):
return model_id
for provider in opencode_models.get("providers", []) or []:
if get_opencode_provider_id(provider) != provider_id:
continue
models = provider.get("models", {}) if isinstance(provider, dict) else {}
if isinstance(models, dict):
if model_id in models:
return model_id
matches = [key for key in models if isinstance(key, str) and key.casefold() == model_id.casefold()]
return matches[0] if len(matches) == 1 else model_id
if isinstance(models, list):
ids = [_opencode_model_entry_id(entry) for entry in models]
if model_id in ids:
return model_id
matches = [entry_id for entry_id in ids if entry_id and entry_id.casefold() == model_id.casefold()]
return matches[0] if len(matches) == 1 else model_id
return model_id
return model_id
def _opencode_model_supports_variant(model_info: dict | None, variant: str | None) -> bool:
if not isinstance(model_info, dict) or not isinstance(variant, str) or not variant.strip():
return False
variants = model_info.get("variants")
if isinstance(variants, dict) and variant in variants:
return True
capabilities = model_info.get("capabilities")
if variants is None and "variants" not in model_info and isinstance(capabilities, dict):
return capabilities.get("reasoning") is True
return False
def _opencode_model_has_no_variants(model_info: dict | None) -> bool:
if not isinstance(model_info, dict):
return False
capabilities = model_info.get("capabilities")
if isinstance(capabilities, dict):
if capabilities.get("reasoning") is True:
return False
if capabilities.get("reasoning") is False:
return True
variants = model_info.get("variants")
if variants is None and "variants" not in model_info:
return True
return isinstance(variants, dict) and not variants
def resolve_opencode_reasoning_effort(
model_dict: dict[str, str] | None,
requested_effort: str | None,
model_catalog: dict | None,
) -> str | None:
"""Return the variant OpenCode should receive for this model."""
normalized_effort = (requested_effort or "").strip() or None
if normalized_effort in {"default", "__default__"}:
normalized_effort = None
if not model_dict:
return normalized_effort
provider_id = model_dict.get("providerID")
model_id = model_dict.get("modelID")
if not provider_id or not model_id:
return normalized_effort
if not isinstance(model_catalog, dict):
return normalized_effort
model_info = find_opencode_model_info(model_catalog, provider_id, model_id)
if normalized_effort:
if _opencode_model_supports_variant(model_info, normalized_effort):
return normalized_effort
if isinstance(model_info, dict):
return None
return normalized_effort
if _opencode_model_has_no_variants(model_info):
return None
return normalized_effort
def _find_model_variants(opencode_models: dict, target_model: Optional[str]) -> Dict[str, Any]:
if not isinstance(opencode_models, dict):
return {}
if isinstance(target_model, str) and target_model:
matches = []
for provider in opencode_models.get("providers", []) or []:
if not isinstance(provider, dict):
continue
model_info = find_opencode_model_info(
opencode_models,
get_opencode_provider_id(provider),
target_model,
)
if opencode_model_is_hub_projected(model_info):
matches.append(model_info)
if len(matches) == 1:
variants = matches[0].get("variants", {})
return variants if isinstance(variants, dict) else {}
if matches:
return {}
target_provider, target_model_id = _parse_model_key(target_model)
if not target_provider or not target_model_id:
return {}
model_info = find_opencode_model_info(opencode_models, target_provider, target_model_id)
if isinstance(model_info, dict):
variants = model_info.get("variants", {})
if isinstance(variants, dict):
return variants
return {}
def _append_unique(target: List[str], value: Optional[str]) -> None:
if not value or value in target:
return
target.append(value)
def _extract_provider_ids_from_config(config: dict) -> List[str]:
providers: List[str] = []
if not isinstance(config, dict):
return providers
provider_value = config.get("provider")
if isinstance(provider_value, str):
_append_unique(providers, provider_value)
default_provider = config.get("default_provider")
if isinstance(default_provider, str):
_append_unique(providers, default_provider)
config_providers = config.get("providers")
if isinstance(config_providers, dict):
for key in config_providers.keys():
_append_unique(providers, key)
elif isinstance(config_providers, list):
for entry in config_providers:
if isinstance(entry, str):
_append_unique(providers, entry)
continue
if isinstance(entry, dict):
value = entry.get("id") or entry.get("provider") or entry.get("name")
if isinstance(value, str):
_append_unique(providers, value)
return providers
def resolve_opencode_provider_preferences(
opencode_default_config: dict,
current_model: Optional[str] = None,
) -> List[str]:
"""Return provider IDs to prefer first when listing models."""
providers: List[str] = []
_append_unique(providers, _parse_provider_id(current_model))
if isinstance(opencode_default_config, dict):
for provider_id in _extract_provider_ids_from_config(opencode_default_config):
_append_unique(providers, provider_id)
return providers
def resolve_opencode_allowed_providers(
opencode_default_config: dict,
opencode_models: Optional[dict] = None,
) -> List[str]:
"""Return provider IDs to include when listing models."""
providers = _extract_provider_ids_from_config(opencode_default_config)
if providers:
return providers
return []
def _model_sort_key(model_item: Tuple[str, Any]) -> Tuple[int, int, str]:
"""Sort models by utility penalty, release date (DESC), then id."""
model_id, model_info = model_item
mid_lower = (model_id or "").lower()
is_utility = any(keyword in mid_lower for keyword in _UTILITY_MODEL_KEYWORDS)
utility_penalty = 1 if is_utility else 0
release_date = "1970-01-01"
if isinstance(model_info, dict):
release_date = model_info.get("release_date", "1970-01-01") or "1970-01-01"
try:
date_int = -int(release_date.replace("-", ""))
except (ValueError, AttributeError):
date_int = 0
return (utility_penalty, date_int, model_id or "")
def build_opencode_model_option_items(
opencode_models: dict,
max_total: int,
preferred_providers: Optional[List[str]] = None,
allowed_providers: Optional[List[str]] = None,
keep: Optional[Callable[[str], bool]] = None,
) -> List[Dict[str, str]]:
"""Build sorted model options for OpenCode providers.
``keep`` drops an option value before it takes a provider's share of ``max_total`` (a value the select that
shows the list cannot carry), so the share goes to models that can be shown.
"""
if not isinstance(opencode_models, dict) or max_total <= 0:
return []
providers_data = opencode_models.get("providers", [])
providers: List[Tuple[str, dict]] = []
for provider in providers_data:
provider_id = get_opencode_provider_id(provider)
if not provider_id:
continue
providers.append((provider_id, provider))
if allowed_providers:
visible_models = filter_opencode_models_to_allowed_providers(
opencode_models,
allowed_providers,
)
providers_data = visible_models.get("providers", [])
providers = []
for provider in providers_data:
provider_id = get_opencode_provider_id(provider)
if provider_id:
providers.append((provider_id, provider))
if preferred_providers:
preferred_set = {p for p in preferred_providers if isinstance(p, str) and p}
if preferred_set:
provider_map = {pid: provider for pid, provider in providers}
ordered: List[Tuple[str, dict]] = []
for pid in preferred_providers:
provider = provider_map.get(pid)
if provider is not None:
ordered.append((pid, provider))
for pid, provider in providers:
if pid not in preferred_set:
ordered.append((pid, provider))
providers = ordered
num_providers = len(providers)
max_per_provider = max(5, (max_total // num_providers)) if num_providers > 0 else max_total
options: List[Dict[str, str]] = []
for provider_id, provider in providers:
provider_name = provider.get("name") or provider_id
models = provider.get("models", {})
if isinstance(models, dict):
model_items = list(models.items())
elif isinstance(models, list):
model_items = [
(entry, entry) if isinstance(entry, str) else (entry.get("id", ""), entry) for entry in models
]
else:
model_items = []
model_items.sort(key=_model_sort_key)
provider_model_count = 0
for model_id, model_info in model_items:
if provider_model_count >= max_per_provider:
break
if not model_id:
continue
if isinstance(model_info, dict):
model_name = model_info.get("name", model_id) or model_id
else:
model_name = model_id
full_model = opencode_model_picker_value(
provider_id,
model_id,
model_info,
)
if keep is not None and not keep(full_model):
continue
display = (
model_name
if opencode_model_is_hub_projected(model_info)
else f"{provider_name}: {model_name}" if provider_name else model_name
)
options.append({"label": display, "value": full_model})
provider_model_count += 1
if len(options) > max_total:
options = options[:max_total]
return options
def _build_reasoning_options_from_variants(variants: Dict[str, Any]) -> List[Dict[str, str]]:
sorted_variants = sorted(
variants.keys(),
key=lambda variant: (
_REASONING_VARIANT_ORDER.index(variant)
if variant in _REASONING_VARIANT_ORDER
else len(_REASONING_VARIANT_ORDER),
variant,
),
)
return [
{
"value": variant_key,
"label": _REASONING_VARIANT_LABELS.get(variant_key, variant_key.capitalize()),
}
for variant_key in sorted_variants
]
def build_reasoning_effort_options(
opencode_models: dict,
target_model: Optional[str],
) -> List[Dict[str, str]]:
"""Build reasoning effort options from OpenCode model metadata."""
options = [{"value": "__default__", "label": "(Default)"}]
variants = _find_model_variants(opencode_models, target_model)
if variants:
options.extend(_build_reasoning_options_from_variants(variants))
return options
options.extend(_REASONING_FALLBACK_OPTIONS)
return options
# ---------------------------------------------------------------------------
# Codex reasoning options
# ---------------------------------------------------------------------------
# Codex supports a fixed set of reasoning effort levels. Unlike OpenCode
# (which derives options from live model metadata), these are static.
# Defined here so that every IM module shares a single source of truth.
_CODEX_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh"]
_CLAUDE_REASONING_EFFORTS = ["low", "medium", "high"]
_CLAUDE_1M_CONTEXT_LABEL = "[1M]"
_CLAUDE_OPUS_ALIASES = {"opus", "opus[1m]"}
_CLAUDE_SONNET_ALIASES = {"sonnet", "sonnet[1m]"}
def _supports_claude_xhigh_reasoning(target_model: Optional[str]) -> bool:
normalized_model = (target_model or "").strip().lower()
if not normalized_model:
return False
return (
normalized_model in _CLAUDE_OPUS_ALIASES
or normalized_model in _CLAUDE_SONNET_ALIASES
or normalized_model.startswith("claude-opus-5")
or normalized_model.startswith("claude-opus-4-7")
or normalized_model.startswith("claude-opus-4-8")
or normalized_model.startswith("claude-sonnet-5")
or normalized_model.startswith("claude-fable-5")
)
def _supports_claude_max_reasoning(target_model: Optional[str]) -> bool:
normalized_model = (target_model or "").strip().lower()
if not normalized_model:
return False
return (
normalized_model in _CLAUDE_OPUS_ALIASES
or normalized_model in _CLAUDE_SONNET_ALIASES
or normalized_model.startswith("claude-opus-5")
or normalized_model.startswith("claude-opus-4-6")
or normalized_model.startswith("claude-opus-4-7")
or normalized_model.startswith("claude-opus-4-8")
or normalized_model.startswith("claude-sonnet-5")
or normalized_model.startswith("claude-sonnet-4-6")
or normalized_model.startswith("claude-fable-5")
)
def supports_claude_1m_context(target_model: Optional[str]) -> bool:
normalized_model = (target_model or "").strip().lower()
if not normalized_model:
return False
return (
normalized_model in _CLAUDE_OPUS_ALIASES
or normalized_model in _CLAUDE_SONNET_ALIASES
or normalized_model.startswith("claude-opus-5")
or normalized_model.startswith("claude-opus-4-6")
or normalized_model.startswith("claude-opus-4-7")
or normalized_model.startswith("claude-opus-4-8")
or normalized_model.startswith("claude-sonnet-5")
or normalized_model.startswith("claude-sonnet-4-6")
or normalized_model.startswith("claude-fable-5")
)
def format_claude_model_label(model: object) -> str:
model_id = str(model or "").strip()
if not model_id:
return model_id
if supports_claude_1m_context(model_id):
return f"{model_id} {_CLAUDE_1M_CONTEXT_LABEL}"
return model_id
def build_codex_reasoning_options(reasoning_efforts: Optional[List[str]] = None) -> List[Dict[str, str]]:
"""Return the canonical Codex reasoning-effort option list.
The returned format mirrors ``build_reasoning_effort_options`` so that
IM modules can render both OpenCode and Codex dropdowns with the same
helper logic.
"""
options: List[Dict[str, str]] = [{"value": "__default__", "label": "(Default)"}]
seen: set[str] = set()
for effort in reasoning_efforts if reasoning_efforts is not None else _CODEX_REASONING_EFFORTS:
if not isinstance(effort, str):
continue
effort = effort.strip()
if not effort or effort in seen:
continue
seen.add(effort)
options.append(
{
"value": effort,
"label": _REASONING_VARIANT_LABELS.get(effort, effort.capitalize()),
}
)
return options
def build_claude_reasoning_options(
target_model: Optional[str],
reasoning_efforts: Optional[List[str]] = None,
) -> List[Dict[str, str]]:
"""Return the canonical Claude reasoning-effort option list for a model.
Claude currently supports `low` / `medium` / `high` broadly. Newer
Opus 4.7, Opus 4.8, Opus 5, and Sonnet 5 models add `xhigh`; those
models plus Opus 4.6 and Sonnet 4.6 also support `max`.
"""
efforts = list(reasoning_efforts) if reasoning_efforts is not None else list(_CLAUDE_REASONING_EFFORTS)
if reasoning_efforts is None:
if _supports_claude_xhigh_reasoning(target_model):
efforts.append("xhigh")
if _supports_claude_max_reasoning(target_model):
efforts.append("max")
options: List[Dict[str, str]] = [{"value": "__default__", "label": "(Default)"}]
seen: set[str] = set()
for effort in efforts:
if not isinstance(effort, str):
continue
effort = effort.strip()
if not effort or effort in seen:
continue
seen.add(effort)
options.append(
{
"value": effort,
"label": _REASONING_VARIANT_LABELS.get(effort, effort.capitalize()),
}
)
return options
def resolve_model_reasoning_options(
reasoning_options: Optional[Dict[str, List[Dict[str, str]]]],
target_model: Optional[str],
fallback: List[Dict[str, str]],
) -> List[Dict[str, str]]:
"""Resolve per-model catalog options without leaking another backend's state."""
if isinstance(reasoning_options, dict):
model_key = (target_model or "").strip()
if model_key == "__default__":
model_key = ""
for key in (model_key, ""):
entries = reasoning_options.get(key)
if isinstance(entries, list) and entries:
return entries
return fallback
def normalize_claude_reasoning_effort(
target_model: Optional[str],
effort: Optional[str],
reasoning_efforts: Optional[List[str]] = None,
) -> Optional[str]:
"""Return a Claude effort only when it is valid for the target model."""
if not effort:
return None
allowed = {item["value"] for item in build_claude_reasoning_options(target_model, reasoning_efforts)}
return effort if effort in allowed else None