AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
from __future__ import annotations
import logging
from abc import ABC, abstractmethod
from typing import Any, Literal
from openexecutive.audit.usage import log_model_usage
from openexecutive.config import get_settings
from openexecutive.providers import get_provider, model_supports_deep_reasoning
_SPECIALIST_TIMEOUT = 180.0
logger = logging.getLogger(__name__)
AgentVisibility = Literal["core", "internal"]
class BaseAgent(ABC):
name: str
domain: str
model: str
use_deep_reasoning: bool = False
# "core": an agent a user would recognise (the Executive and the domain
# specialists), listed in the Agent Council's simple view. "internal":
# triage and the helper agents, shown only under "Show all agents".
visibility: AgentVisibility = "internal"
@abstractmethod
def get_system_prompt(self) -> str: ...
def base_system_prompt(self) -> str:
"""The built-in prompt, or the Council's replacement for it."""
from openexecutive.agents.overrides import get_override
ov = get_override(self.name)
if ov is not None and ov.prompt is not None:
return ov.prompt
return self.get_system_prompt()
def effective_system_prompt(self) -> str:
"""System prompt as sent: the base prompt plus any additional
instructions saved in the Council."""
from openexecutive.agents.overrides import append_instructions, get_override
ov = get_override(self.name)
return append_instructions(
self.base_system_prompt(), ov.instructions if ov is not None else None
)
def effective_model(self) -> str:
from openexecutive.agents.overrides import get_override
ov = get_override(self.name)
if ov is not None and ov.model is not None:
return ov.model
return self.model
def effective_use_deep_reasoning(self) -> bool:
from openexecutive.agents.overrides import get_override
ov = get_override(self.name)
if ov is not None and ov.use_deep_reasoning is not None:
return ov.use_deep_reasoning
return self.use_deep_reasoning
async def analyze(
self,
query: str,
context: str = "",
retrieved_knowledge: str = "",
episodic_context: str = "",
failure_cases: str = "",
department_memory: str = "",
*,
company_stage: str = "",
principal_role: str = "",
standing_facts: str = "",
system_prompt_override: str | None = None,
model_override: str | None = None,
deep_reasoning_override: bool | None = None,
actor: str = "specialist",
) -> str:
"""Run one prose specialist call and return its text.
Every call records a ``cache_event`` usage row under ``actor``, so
the call counts toward the session cost summary and ``/audit/usage``
like every other model call. The router sets ``actor`` per path
(``specialist`` for chat-turn consults, ``specialist_workflow`` for
workflow steps); the Council test box passes ``agent_test``.
"""
settings = get_settings()
# Resolution order: explicit kwarg (for sandbox/test calls) → DB
# override → class default. Keeping the override read inside this
# method means a fresh DB row takes effect on the next request
# without any process restart.
system_prompt = (
system_prompt_override
if system_prompt_override is not None
else self.effective_system_prompt()
)
model = (
model_override
if model_override is not None
else self.effective_model()
)
use_deep = (
deep_reasoning_override
if deep_reasoning_override is not None
else self.effective_use_deep_reasoning()
)
user_content = query
if context:
user_content = f"<conversation_context>\n{context}\n</conversation_context>\n\n{query}"
if retrieved_knowledge:
user_content = (
f"<relevant_knowledge>\n{retrieved_knowledge}\n</relevant_knowledge>\n\n{user_content}"
)
if failure_cases:
user_content = (
f"<failure_cases>\n{failure_cases}\n</failure_cases>\n\n{user_content}"
)
if episodic_context:
user_content = (
f"<past_decisions>\n{episodic_context}\n</past_decisions>\n\n{user_content}"
)
if standing_facts:
# The principal's kept corrections (memory.facts), next to the
# institutional memory it overrides. User turn, never the cached
# specialist system prompt.
user_content = (
f"<standing_facts>\n{standing_facts}\n</standing_facts>\n\n{user_content}"
)
if department_memory:
# Placed adjacent to past_decisions so the specialist sees both
# forms of institutional context together: the structured ledger
# (past_decisions, from SQL) and the dept peer's synthesized
# voice (department_memory, from Honcho). Order is intentional —
# past_decisions stays closest to the query for cache stability
# across turns; department_memory wraps it.
user_content = (
f"<department_memory>\n{department_memory}\n</department_memory>\n\n{user_content}"
)
# Solo mode: what the principal does (kind, title, remit —
# router.principal_role_context). A VP inside a large company and a
# business owner need different advice for the same question; the
# tag rides in the USER turn for the same cache reason as the stage
# below, which sits just outside it.
role = principal_role.strip()
if role:
user_content = f"<principal_role>\n{role}\n</principal_role>\n\n{user_content}"
# The company's stage, from the profile. Specialists never see the
# company profile — it lives in the Executive's cached system block —
# and stage changes which benchmarks apply (venture metrics mislead a
# bootstrapped business). It rides in the USER turn, outermost, so the
# specialist's cached system prompt stays byte-identical whatever the
# profile says. Collapsed to one line: it is free text.
stage = " ".join(company_stage.split())
if stage:
user_content = f"<company_stage>\n{stage}\n</company_stage>\n\n{user_content}"
create_kwargs: dict = {
"model": model,
"max_tokens": 4096,
# Per-request timeout — keeps cancellation semantics aligned with
# the previous per-client timeout, but the provider singleton no
# longer needs to recreate the SDK client to set it.
"timeout": _SPECIALIST_TIMEOUT,
"system": [
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"},
}
],
"messages": [{"role": "user", "content": user_content}],
}
if use_deep and model_supports_deep_reasoning(model):
# Adaptive thinking with effort capped via
# output_config.effort. Default "low" — adaptive at default
# effort routinely burned 20k+ thinking tokens. "low" still
# leaves room for nuanced reasoning while being ~3x faster.
# Tune via SPECIALIST_EFFORT (low / medium / high / xhigh / max).
create_kwargs["thinking"] = {"type": "adaptive"}
create_kwargs["output_config"] = {"effort": settings.specialist_effort}
create_kwargs["max_tokens"] = 16000
# Resolve provider per-call by model so a Council UI override that
# flips this agent to a non-Anthropic slug routes correctly. Today
# the registry always returns the Anthropic provider; OpenRouter
# wiring lands in the next commit.
provider = get_provider(model)
message = await provider.messages_create(**create_kwargs)
log_model_usage(message, model=model, actor=actor)
text_blocks = [b for b in message.content if b.type == "text"]
if not text_blocks:
# A reasoning model can spend the whole max_tokens budget thinking
# and return no text; the Executive would then synthesize as if
# this specialist had nothing to say. Make that visible.
logger.warning(
"specialist %s (%s) returned no text block (stop_reason=%s, "
"deep_reasoning=%s); its analysis will be empty",
self.name,
model,
getattr(message, "stop_reason", None),
use_deep,
)
return text_blocks[0].text if text_blocks else ""
async def analyze_with_tools(
self,
user_content: str,
*,
tools: list[dict[str, Any]],
system_addendum: str = "",
max_tokens: int = 4096,
timeout_seconds: float = _SPECIALIST_TIMEOUT,
model_override: str | None = None,
deep_reasoning_override: bool | None = None,
actor: str = "specialist_tools",
) -> Any:
"""Tool-use variant of ``analyze`` — returns the raw provider Message.
Used by workflows that need structured output from a specialist
(e.g. the watchlist research workflow's
``propose_watchlist_entries`` tool). Differs from ``analyze``:
- ``tools`` is required; the model is expected to call one of
them rather than emit prose.
- The user_content is passed verbatim — no
``<conversation_context>`` / ``<retrieved_knowledge>`` /
``<past_decisions>`` wrappers (those are chat-time
primitives). The caller owns context formatting.
- Returns the raw ``Message`` instead of joined text so the
caller can pick out the tool_use block it expects.
Honours every per-instance effective_* override (system prompt,
model, deep-reasoning) so a Council override applies here too.
``model_override`` / ``deep_reasoning_override`` let a caller pin the
model and reasoning tier for this one turn (e.g. the executive_research
fan-out routes specialists to a cheaper RESEARCH_MODEL with deep
reasoning off) without disturbing the agent's chat-time defaults. When
None, the per-instance effective_* values apply, matching prior
behavior.
``actor`` names the caller on the ``cache_event`` usage row recorded
for the call (``specialist_research``, ``query_watch``, …), which is
what the per-source usage breakdown groups on.
"""
settings = get_settings()
system_prompt = self.effective_system_prompt() + (
system_addendum or ""
)
model = (
model_override
if model_override is not None
else self.effective_model()
)
use_deep = (
deep_reasoning_override
if deep_reasoning_override is not None
else self.effective_use_deep_reasoning()
)
create_kwargs: dict[str, Any] = {
"model": model,
"max_tokens": max_tokens,
"timeout": timeout_seconds,
"system": [
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"},
}
],
"tools": tools,
"messages": [{"role": "user", "content": user_content}],
}
if use_deep and model_supports_deep_reasoning(model):
create_kwargs["thinking"] = {"type": "adaptive"}
create_kwargs["output_config"] = {"effort": settings.specialist_effort}
create_kwargs["max_tokens"] = max(max_tokens, 16000)
provider = get_provider(model)
message = await provider.messages_create(**create_kwargs)
log_model_usage(message, model=model, actor=actor)
return message