Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

22.5 KB
Raw Blame
from __future__ import annotations

from typing import Any, Literal

from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator

from openexecutive.memory.workspace_settings import RoleKind


class PageFormField(BaseModel):
    """One field of a form currently on the user's screen (Ask OE panel).

    ``type`` is a UI-side hint, not a validation contract: "text" |
    "textarea" | "number" | "boolean" | "select" | "json". For ``json``
    fields the live structured value rides in ``value`` and ``description``
    documents the expected shape.
    """

    name: str = Field(..., max_length=100)
    label: str = Field(..., max_length=200)
    type: str = Field("text", max_length=20)
    # Generous cap — json-typed fields embed their schema documentation here
    # (e.g. the workflow builder's steps union + people roster).
    description: str = Field("", max_length=4000)
    options: list[str] | None = Field(None, max_length=100)
    value: Any = None
    required: bool = False


class PageFormDescriptor(BaseModel):
    form_id: str = Field(..., max_length=100)
    title: str = Field(..., max_length=200)
    description: str = Field("", max_length=1000)
    fields: list[PageFormField] = Field(default_factory=list, max_length=200)


class PageContext(BaseModel):
    """What the user is looking at when they message from the Ask OE panel.

    Rendered into the USER TURN (never a cached system block — see
    CLAUDE.md "Prompt Caching") so the Executive can explain the current
    page and, when ``form`` is present, propose values for it via the
    ``propose_form_values`` tool.
    """

    route: str = Field(..., max_length=500)
    title: str = Field(..., max_length=200)
    guide_section_id: str | None = Field(None, max_length=100)
    summary: str = Field("", max_length=2000)
    form: PageFormDescriptor | None = None


class ChatRequest(BaseModel):
    message: str = Field(..., min_length=1, max_length=32000)
    session_id: str | None = None
    # Per-message opt-in: when true, route through Committee adversarial
    # review before streaming the (revised) response to the client.
    committee_review: bool = False
    # Set by the Ask OE side panel only; absent on the main chat page.
    page_context: PageContext | None = None
    # Client-minted id for THIS turn, so the client can address it via
    # POST /chat/stop from the moment Send is pressed. It is deliberately not
    # the audit `turn_id` (that keeps its server-minted `t-` shape, which audit
    # queries filter on) — see `_clean_client_turn_id` in api/routes/chat.py.
    # Bounded, but deliberately NOT pattern-validated here: a malformed id only
    # means this turn can't be stopped, and 422-ing the whole chat turn over it
    # would contradict `_clean_client_turn_id`, which drops it and carries on.
    # The max_length is a size bound, not a format check.
    client_turn_id: str | None = Field(None, max_length=64)
    # The caller's own words for this turn, when `message` carries text the
    # caller did not write — a briefing handoff seeds the turn with the
    # Executive's own card body. Peer memory records it, and episodic
    # extraction and open loops quote commitments from it. Absent → `message`.
    # Recorded under the caller's own peer and, like `message` would be, in
    # the shared memory of each department consulted that turn; it is not in
    # the transcript, so the chat_turn audit row keeps it next to `message`.
    memory_text: str | None = Field(None, min_length=1, max_length=2000)


class BackgroundChatRequest(BaseModel):
    """Body of POST /chat/background: a new chat that runs to the end on the
    server, whether or not the caller stays to watch (a phone app approving
    a card, then closing). `message` and `memory_text` mean what they do on
    `ChatRequest`."""

    message: str = Field(..., min_length=1, max_length=32000)
    memory_text: str | None = Field(None, min_length=1, max_length=2000)


class BackgroundChatResponse(BaseModel):
    """Where the background turn's chat will be: open it from the chat list
    once the turn has answered."""

    session_id: str


class StopChatRequest(BaseModel):
    """Body of POST /chat/stop — the `client_turn_id` sent with the turn."""

    client_turn_id: str = Field(
        ..., min_length=8, max_length=64, pattern=r"^[A-Za-z0-9-]+$"
    )


class AddChatMessageRequest(BaseModel):
    """Body of POST /chat/add — a message for a turn that is still running."""

    client_turn_id: str = Field(
        ..., min_length=8, max_length=64, pattern=r"^[A-Za-z0-9-]+$"
    )
    # Client-minted, echoed back in the stream's `message_added` event.
    message_id: str = Field(
        ..., min_length=8, max_length=64, pattern=r"^[A-Za-z0-9-]+$"
    )
    message: str = Field(..., min_length=1, max_length=32000)


class ChatResponse(BaseModel):
    response: str
    session_id: str


# Wizard answers are a sentence or two, or a short one-per-line list. The
# free-text parsers in onboarding/wizard.py run regexes over this, so it is
# a safety bound on event-loop time, not only a UX choice — do not raise it
# without re-checking the parser benchmarks in test_onboarding_wizard_arr_parse.
ONBOARD_ANSWER_MAX_CHARS = 10_000


class OnboardAnswerRequest(BaseModel):
    session_id: str
    # Bounded to ONBOARD_ANSWER_MAX_CHARS in the route rather than with
    # Field(max_length=...): FastAPI's default validation error echoes the
    # rejected input back in the response body, and wizard answers include
    # financials the UI promises are stored locally only.
    answer: str


class OnboardStatusResponse(BaseModel):
    session_id: str
    # The step's place among the steps this wizard asks — a solo workspace
    # skips the team steps, so this is not an index into WIZARD_STEPS.
    current_step: int
    total_steps: int
    current_question: str | None
    progress_percent: int
    completed: bool
    # Whether the current step can be skipped.
    optional: bool = False


class DocumentUploadResponse(BaseModel):
    filename: str
    chunks_indexed: int
    domain: str
    status: str


class CompanyDocContent(BaseModel):
    filename: str
    content: str


class SyncedDocContent(BaseModel):
    """One Google Drive file or Notion page as the knowledge base stored it."""

    id: str
    name: str
    url: str | None = None
    content: str


class GatewayHealth(BaseModel):
    """The MCP gateway (orchestrator/gateway_boot.py): ``off`` (MCP not
    enabled), ``no_servers`` (enabled, config names none), ``starting`` (an
    attempt is running), ``up``, or ``down`` (every attempt failed so far;
    ``next_retry_at`` says when the next one is). ``attempts`` counts starts
    tried. The failure's text stays in the log and the owner's Setup notice:
    the route is open to anyone. ``email_poller`` is whether the poller that
    rides on the gateway runs."""

    state: str
    attempts: int = 0
    last_failed_at: str | None = None
    up_since: str | None = None
    next_retry_at: str | None = None
    email_poller: bool = False


class HealthResponse(BaseModel):
    status: str
    builtin_knowledge_chunks: int
    company_profile_loaded: bool
    company_name: str | None = None
    builtin_skills: int = 0
    company_skills: int = 0
    # The pinned Google tools startup priming could not find. `[]` is the only
    # value that asserts every one is present; `null` means no answer — Google
    # Workspace is not configured, or the probe has not finished, or it failed.
    # Setup status says which. A non-empty list means a workspace-mcp rename or
    # a tool the configured services and tier never loaded.
    google_tools_missing: list[str] | None = None
    # The MCP gateway's state (``GatewayHealth``). A hosted instance whose
    # gateway failed to start used to look healthy here while no email went
    # out or came in.
    gateway: GatewayHealth | None = None
    version: str = "0.6.7"  # x-release-please-version


class VersionResponse(BaseModel):
    """The running version and, when the update check is on, the latest release."""

    current: str
    latest: str | None = None
    update_available: bool = False
    release_url: str | None = None
    check_enabled: bool = True


class SkillWorkflowRef(BaseModel):
    name: str
    title: str
    is_custom: bool = False


class SkillMeta(BaseModel):
    name: str
    category: str
    description: str
    when_to_use: str
    source: str
    filename: str
    customized: bool = False
    hidden: bool = False
    # Workflows whose steps follow this playbook (switched-off custom ones too).
    used_by: list[SkillWorkflowRef] = []


class SkillDetail(SkillMeta):
    body: str


class SkillCreate(BaseModel):
    name: str
    category: str
    description: str
    when_to_use: str
    body: str


class SkillListResponse(BaseModel):
    skills: list[SkillMeta]


class SkillDeleteResponse(BaseModel):
    name: str
    # "deleted" (company skill removed), "reverted" (customization removed,
    # the built-in is back) or "hidden" (built-in hidden for this company).
    outcome: Literal["deleted", "reverted", "hidden"]


class SkillSearchHit(BaseModel):
    name: str
    category: str
    description: str
    when_to_use: str
    source: str
    score: float


class SkillSearchResponse(BaseModel):
    results: list[SkillSearchHit]


class SessionSummary(BaseModel):
    session_id: str
    title: str
    created_at: str
    updated_at: str
    message_count: int = 0
    # Set only on a search (`GET /sessions?q=`): how many messages contain the
    # words (0 when only the title does) and the newest one around the match.
    match_count: int | None = None
    snippet: str | None = None
    # Set on the plain list: the chat's last message as one line, "You: "
    # before the person's own words, for a list that says what each chat is.
    preview: str | None = None
    # When its owner pinned it to the top of their list; absent when not.
    pinned_at: str | None = None
    # The owner's topic this chat is filed under (`GET /sessions/topics`);
    # absent when none, and on a chat shared with the caller.
    topic_id: int | None = None
    # A chat someone shared with the caller (`GET /sessions/shared-with-me`,
    # or opened by id): they read it and write in it with its owner, but only
    # the owner renames, pins, shares or deletes it. `shared_by` names the
    # owner and `shared_at` says when.
    shared_with_you: bool | None = None
    shared_by: str | None = None
    shared_at: str | None = None


class TargetCustomerData(BaseModel):
    profile: str = ""
    pain_points: list[str] = Field(default_factory=list)


class CompetitiveLandscapeData(BaseModel):
    primary_competitors: list[str] = Field(default_factory=list)
    competitive_advantages: list[str] = Field(default_factory=list)


class OrgStructureData(BaseModel):
    departments: list[str] = Field(default_factory=list)
    leadership_team: list[str] = Field(default_factory=list)


class StrategicPrioritiesData(BaseModel):
    current_year: list[str] = Field(default_factory=list)
    north_star_metric: str = ""


class CultureData(BaseModel):
    values: list[str] = Field(default_factory=list)
    operating_principles: list[str] = Field(default_factory=list)


class FinancialsData(BaseModel):
    burn_rate_monthly: float | None = None
    runway_months: float | None = None
    key_metrics: dict = Field(default_factory=dict)


class CompanyProfileResponse(BaseModel):
    name: str
    website: str = ""
    industry: str
    stage: str
    founding_year: int | None
    headcount: int | None
    annual_revenue_arr: float | None
    mission: str
    vision: str
    target_customer: TargetCustomerData
    competitive_landscape: CompetitiveLandscapeData
    org_structure: OrgStructureData
    strategic_priorities: StrategicPrioritiesData
    culture: CultureData
    financials: FinancialsData
    vendors: list[str] = Field(default_factory=list)
    tickers: list[str] = Field(default_factory=list)


class CompanyProfileUpdateRequest(BaseModel):
    name: str | None = None
    website: str | None = Field(default=None, max_length=300)
    industry: str | None = None
    stage: str | None = None
    founding_year: int | None = None
    headcount: int | None = None
    annual_revenue_arr: float | None = None
    mission: str | None = None
    vision: str | None = None
    target_customer: TargetCustomerData | None = None
    competitive_landscape: CompetitiveLandscapeData | None = None
    org_structure: OrgStructureData | None = None
    strategic_priorities: StrategicPrioritiesData | None = None
    culture: CultureData | None = None
    financials: FinancialsData | None = None
    vendors: list[str] | None = None
    tickers: list[str] | None = None


# ── workspace settings (/workspace) ──────────────────────────────────────────


class WorkspaceResponse(BaseModel):
    mode: Literal["solo", "team"]
    # The zone the user set, or null when none is set.
    timezone: str | None
    # The zone in effect: `timezone`, else the USER_TIMEZONE setting, else UTC.
    effective_timezone: str
    # The principal's role (memory.workspace_settings.PrincipalRole); each is
    # null when not set. Read by solo mode only.
    role_kind: RoleKind | None = None
    role_title: str | None = None
    reports_to: str | None = None
    remit: str | None = None
    measured_on: str | None = None
    # The company's own email domains: on one of them an address matches a
    # teammate by its local part (people.identity). `company_domains_custom`
    # is false when they are derived from the principal's addresses. Returned
    # only to the principal, like the role; empty for anyone else.
    company_domains: list[str] = Field(default_factory=list)
    company_domains_custom: bool = False
    # Whether any department exists. The UI shows the Departments tab only
    # then: goals stand on their own, so a workspace may never need one.
    has_departments: bool = False


class WorkspaceUpdateRequest(BaseModel):
    """A partial update: only the fields present are changed. `timezone: null`
    (or blank) clears the stored zone; `mode` may be omitted but not null.
    The role fields work like `timezone`: null or blank clears one. Their
    length caps are checked after trimming (ROLE_TEXT_MAX)."""

    model_config = ConfigDict(extra="forbid")

    mode: Literal["solo", "team"] | None = None
    timezone: str | None = Field(default=None, max_length=64)
    role_kind: RoleKind | None = None
    role_title: str | None = None
    reports_to: str | None = None
    remit: str | None = None
    measured_on: str | None = None
    # null (or []) goes back to deriving them from the principal's addresses.
    company_domains: list[str] | None = None

    @field_validator("company_domains", mode="before")
    @classmethod
    def _domains(cls, v: object) -> object:
        from openexecutive.memory.workspace_settings import validate_company_domains

        # Runs only when sent; the message never quotes the value.
        return validate_company_domains(v)

    @field_validator("mode", mode="before")
    @classmethod
    def _mode_not_null(cls, v: object) -> object:
        # Runs only when the field is sent (defaults are not validated).
        if v is None:
            raise ValueError("mode must be 'solo' or 'team'")
        return v

    @field_validator("timezone")
    @classmethod
    def _known_zone(cls, v: str | None) -> str | None:
        from openexecutive.memory.workspace_settings import validate_timezone

        return validate_timezone(v)

    @field_validator("role_kind", "role_title", "reports_to", "remit", "measured_on", mode="before")
    @classmethod
    def _role_field(cls, v: object, info: ValidationInfo) -> object:
        from openexecutive.memory.workspace_settings import validate_role_field

        # Runs only for fields that were sent; the message never quotes `v`.
        assert info.field_name is not None
        return validate_role_field(info.field_name, v)



# ── conversational onboarding (/onboard/interview/*) ─────────────────────────

# A free-text business description is longer than a wizard answer — people
# paste a whole one-pager. Bounded in the ROUTE rather than with
# Field(max_length=...), for the same reason as OnboardAnswerRequest above:
# FastAPI's validation error echoes the rejected input, and these messages
# carry the financials the UI promises are stored locally only.
ONBOARD_MESSAGE_MAX_CHARS = 20_000
# The question and transcript budgets live in onboarding/interview.py, which is
# what actually enforces them — a second copy here would silently drift from
# the value the interview uses.


class OnboardMessageRequest(BaseModel):
    session_id: str
    # No Field(max_length=...) — see ONBOARD_MESSAGE_MAX_CHARS above.
    message: str


class OnboardUnderstandingResponse(BaseModel):
    """What the free-text description already says (see onboarding/understand.py)."""

    mode: str | None = None
    role_kind: str | None = None
    role_title: str | None = None
    reports_to: str | None = None
    company: str | None = None
    focus: str | None = None


class OnboardSessionRequest(BaseModel):
    session_id: str


class OnboardReviseRequest(BaseModel):
    """Change one of the person's earlier answers and carry on from there."""

    session_id: str
    # Which of the person's own answers, oldest first: 0 is the description.
    # Defaulted so a missing one gets the route's fixed 404, not a 422 that
    # echoes the whole body (message included).
    answer: int = -1
    # No Field(max_length=...) — see ONBOARD_MESSAGE_MAX_CHARS above.
    message: str


# No Field(max_length=...) on any of the draft models below, for the same
# reason as ONBOARD_MESSAGE_MAX_CHARS above: FastAPI's 422 body echoes the
# rejected value, and a commit body carries the company's financials. Lengths
# are bounded by the CompanyProfile/PersonDraft validation the commit route
# runs, which reports fixed strings.
class OnboardPersonDraft(BaseModel):
    # extra="ignore" mirrors interview.PersonDraft: an email or chat handle
    # that reaches this boundary is dropped, never persisted.
    model_config = ConfigDict(extra="ignore")

    full_name: str
    role: str = ""
    is_principal: bool = False


class OnboardDepartmentDraft(BaseModel):
    model_config = ConfigDict(extra="ignore")

    title: str
    mission: str = ""
    head_person_name: str = ""
    authority_level: str = "propose_only"


class OnboardGoalDraft(BaseModel):
    """One of this year's goals: saved with an owner (a drafted person's
    name, empty = the owner of the workspace) and, when departments were
    drafted, optionally inside one."""

    model_config = ConfigDict(extra="ignore")

    title: str
    target: str = ""
    owner_name: str = ""
    department_title: str = ""


class OnboardTranscriptTurn(BaseModel):
    role: str
    text: str


class OnboardTurnResponse(BaseModel):
    session_id: str
    # "question" while interviewing, "draft" once a reviewable draft exists.
    phase: str
    questions_asked: int
    max_questions: int
    question: str | None = None
    question_hint: str | None = None
    # Suggested answers to the question, shown as buttons to tap.
    question_options: list[str] = Field(default_factory=list)
    draft: CompanyProfileResponse | None = None
    draft_people: list[OnboardPersonDraft] = Field(default_factory=list)
    draft_departments: list[OnboardDepartmentDraft] = Field(default_factory=list)
    draft_goals: list[OnboardGoalDraft] = Field(default_factory=list)
    confidence_notes: list[str] = Field(default_factory=list)
    summary: str | None = None
    # The website pages setup read for this session (e.g. "example.com/team"),
    # on the opening turn only. Empty with a website given: it couldn't be read.
    website_pages: list[str] = Field(default_factory=list)


class OnboardSessionResponse(OnboardTurnResponse):
    turns: list[OnboardTranscriptTurn] = Field(default_factory=list)
    saved: bool = False


class OnboardCommitRequest(BaseModel):
    session_id: str
    # Reuses the PATCH model: all-optional fields merged onto a fresh
    # CompanyProfile(), so the client never has to send a complete profile.
    profile: CompanyProfileUpdateRequest
    people: list[OnboardPersonDraft] = Field(default_factory=list)
    departments: list[OnboardDepartmentDraft] = Field(default_factory=list)
    goals: list[OnboardGoalDraft] = Field(default_factory=list)
    # The principal's sign-in email, confirmed by the user on the review
    # screen (pre-filled from their own login). The one contact detail setup
    # saves: without it the signed-in owner matches no Person, so their chat
    # history stays empty until they add it on the People page. Never taken
    # from the model's draft — the people drafts above still drop emails.
    owner_email: str | None = None


# ── /workflows/designer/* (conversational "New workflow" wizard) ─────────────
# Bounded in the route, not with Field(max_length=...), so a rejection is a
# fixed string instead of FastAPI's 422 echo of the whole message. The question
# and transcript budgets live in workflows/designer.py, which enforces them.
WORKFLOW_DESIGNER_MESSAGE_MAX_CHARS = 8_000


class WorkflowDesignerStartRequest(BaseModel):
    message: str


class WorkflowDesignerEditRequest(BaseModel):
    # A saved custom workflow's name (the same bound the definition enforces).
    name: str = Field(max_length=64)


class WorkflowDesignerMessageRequest(BaseModel):
    session_id: str
    message: str


class WorkflowDesignerSessionRequest(BaseModel):
    session_id: str


class WorkflowDesignerTranscriptTurn(BaseModel):
    role: str
    text: str


class WorkflowDesignerDraftResponse(BaseModel):
    # A DynamicWorkflowDef dump — the exact body POST /workflows/custom takes.
    definition: dict[str, Any]
    summary: str = ""
    assumptions: list[str] = Field(default_factory=list)


class WorkflowDesignerTurnResponse(BaseModel):
    session_id: str
    # "question" while designing, "draft" once a reviewable draft exists.
    phase: str
    questions_asked: int
    max_questions: int
    question: str | None = None
    hint: str | None = None
    options: list[str] = Field(default_factory=list)
    draft: WorkflowDesignerDraftResponse | None = None
    transcript: list[WorkflowDesignerTranscriptTurn] = Field(default_factory=list)
    # Set when the session changes a saved workflow: its name, and the stored
    # definition as it was when the session opened (what the draft is compared
    # with). The draft is then saved with POST /workflows/custom/{editing}/save-edit.
    editing: str | None = None
    original: dict[str, Any] | None = None