AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Quality presets for the Agent Council: Fast, Balanced and Thorough.
A preset sets the model and deep-reasoning flag of every agent at once. It
is not stored anywhere: applying one writes ordinary per-agent overrides
(``agents.overrides.set_override`` / ``clear_override``), so history,
rollback and later per-agent edits keep working, and the active preset is
worked out from those overrides when the Council asks.
Presets change quality only. They never cap spend.
Model names are resolved at request time against the install's model
allowlist (``providers.allowed_models_for``), taking the first preferred
model the install can serve. A preset whose model this install can't reach
is reported as unavailable rather than silently picking something else.
This module is pure: callers pass each agent's defaults and current
overrides in as ``AgentState`` and apply the returned ``AgentWrite`` list.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Literal
from openexecutive.providers import model_supports_deep_reasoning
PresetId = Literal["fast", "balanced", "thorough"]
PRESET_IDS: tuple[PresetId, ...] = ("fast", "balanced", "thorough")
# Order ``preset_status`` tries presets in; Balanced first so it wins ties.
_STATUS_ORDER: tuple[PresetId, ...] = ("balanced", "fast", "thorough")
# Preferred models, best first. The first one the install allows wins.
_FAST_MODELS: tuple[str, ...] = ("claude-haiku-5-5", "claude-haiku-4-5")
_THOROUGH_MODELS: tuple[str, ...] = ("claude-opus-5-5", "claude-opus-5")
@dataclass(frozen=True)
class PresetSpec:
id: PresetId
label: str
description: str
PRESETS: dict[PresetId, PresetSpec] = {
"fast": PresetSpec(
id="fast",
label="Fast",
description=(
"A small, fast model for every agent, with deep reasoning off. "
"Quickest answers."
),
),
"balanced": PresetSpec(
id="balanced",
label="Balanced",
description="Each agent's built-in model and deep-reasoning setting.",
),
"thorough": PresetSpec(
id="thorough",
label="Thorough",
description=(
"The largest model for the Executive and the specialists, with "
"deep reasoning on where the model supports it. Background "
"helpers keep their built-in settings."
),
),
}
@dataclass(frozen=True)
class AgentState:
"""One agent's defaults and current overrides (None = no override)."""
agent_id: str
model_default: str
deep_default: bool
model_override: str | None
deep_override: bool | None
# The Executive or a domain specialist (BaseAgent.visibility == "core").
# Thorough moves core agents up and leaves the rest on their defaults.
core: bool = False
# Whether the agent's own calls honour the deep-reasoning flag. The
# Executive's turn never sends thinking fields, so a preset leaves its
# flag alone.
uses_deep_reasoning: bool = True
@property
def model(self) -> str:
return self.model_override if self.model_override is not None else self.model_default
@property
def deep(self) -> bool:
return self.deep_override if self.deep_override is not None else self.deep_default
@dataclass(frozen=True)
class AgentTarget:
model: str
deep: bool
@dataclass(frozen=True)
class AgentWrite:
"""Override values to store so the agent matches its preset target.
``None`` clears the field back to the agent's default.
"""
agent_id: str
model: str | None
deep: bool | None
def _first_allowed(preferred: tuple[str, ...], allowed: list[str]) -> str | None:
allowed_set = set(allowed)
return next((m for m in preferred if m in allowed_set), None)
def preset_model(preset_id: PresetId, allowed: list[str]) -> str | None:
"""The model a preset moves agents to, or None when it keeps defaults
(Balanced) or when the install allows none of its preferred models."""
if preset_id == "fast":
return _first_allowed(_FAST_MODELS, allowed)
if preset_id == "thorough":
return _first_allowed(_THOROUGH_MODELS, allowed)
return None
def preset_available(preset_id: PresetId, allowed: list[str]) -> bool:
return preset_id == "balanced" or preset_model(preset_id, allowed) is not None
def target_for(preset_id: PresetId, agent: AgentState, *, allowed: list[str]) -> AgentTarget:
"""What ``agent`` should run on under ``preset_id``.
Raises ``ValueError`` when the preset is unavailable on this install.
"""
default = AgentTarget(model=agent.model_default, deep=agent.deep_default)
if preset_id == "balanced":
return default
model = preset_model(preset_id, allowed)
if model is None:
raise ValueError(f"Preset {preset_id!r} is not available on this install")
if preset_id == "fast":
deep = False if agent.uses_deep_reasoning else agent.deep_default
return AgentTarget(model=model, deep=deep)
# Thorough: core agents move up; background helpers keep their defaults.
if not agent.core:
return default
deep = (
model_supports_deep_reasoning(model)
if agent.uses_deep_reasoning
else agent.deep_default
)
return AgentTarget(model=model, deep=deep)
def matches(agent: AgentState, target: AgentTarget) -> bool:
return agent.model == target.model and agent.deep == target.deep
def writes_for(
preset_id: PresetId, agents: list[AgentState], *, allowed: list[str]
) -> list[AgentWrite]:
"""Override writes that bring every agent onto ``preset_id``.
Agents already on their target are left out, so applying the active
preset again writes nothing. A field whose target equals the agent's
default is cleared rather than stored, so Balanced leaves no model or
deep-reasoning override behind.
"""
out: list[AgentWrite] = []
for agent in agents:
target = target_for(preset_id, agent, allowed=allowed)
if matches(agent, target):
continue
out.append(
AgentWrite(
agent_id=agent.agent_id,
model=None if target.model == agent.model_default else target.model,
deep=None if target.deep == agent.deep_default else target.deep,
)
)
return out
@dataclass(frozen=True)
class PresetStatus:
"""Which preset the council is on.
``active`` is the preset every agent matches, or None ("Custom").
``base`` is the available preset the most agents match (Balanced on a
tie), and ``custom_agents`` lists the agents that differ from it.
"""
active: PresetId | None
base: PresetId
custom_agents: list[str]
def preset_status(agents: list[AgentState], *, allowed: list[str]) -> PresetStatus:
best: tuple[int, PresetId, list[str]] | None = None
for preset_id in _STATUS_ORDER:
if not preset_available(preset_id, allowed):
continue
diverging = [
a.agent_id
for a in agents
if not matches(a, target_for(preset_id, a, allowed=allowed))
]
if best is None or len(diverging) < best[0]:
best = (len(diverging), preset_id, diverging)
assert best is not None # Balanced is always available.
_, base, diverging = best
return PresetStatus(
active=base if not diverging else None,
base=base,
custom_agents=diverging,
)