Skip to content

Self-improving AI Employees for everyone

13.4 KB
Raw Blame
"""The apps an employee can use (``config/employee_apps.json``).

One entry per app a hire can name ("WhatsApp", "Gmail", "Google Calendar"):
the credential provider that decides whether it is connected, and how the
app maps onto workflow nodes (the trigger that starts the employee, the
node that replies to whoever wrote in, the node that reports to the owner,
the tools handed to the agent, and how the agent the owner talks to sends
through it). The graph builder reads the templates;
the summaries read connection state and phrases.

Names from the model's setup screen are matched by :func:`resolve_app`:
exact, then prefix, then word, then substring (3+ characters), preferring
a connected app within a tier. A name that matches nothing is kept as an
unsupported app: it never blocks a start and the employee's instructions
name it.

More apps come from what an owner saved rather than from the file: a
plugin registers a source (``register_app_source``) that gives one owner's
apps, such as each custom connector (nodes/mcp). Such an app exists only
while it is saved, so it is connected. Its tool's node type says which
parameter names the app (``BaseNode.app_field``), and that parameter holds
the app's id. ``Connections.apps`` reads both kinds.
"""

from __future__ import annotations

import json
import re
from dataclasses import dataclass, field
from pathlib import Path
from types import MappingProxyType
from typing import Any, Awaitable, Callable, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple

from core.logging import get_logger
from services.plugin.registry import IdempotentRegistry

logger = get_logger(__name__)

CONFIG_PATH = Path(__file__).resolve().parents[2] / "config" / "employee_apps.json"

#: Least to most dangerous. A tool's class is the worst thing any of its
#: operations can do, because a tool call lets the model pick the operation.
SIDE_EFFECTS: Tuple[str, ...] = ("read", "write", "send", "money")
AUDIENCES: Tuple[str, ...] = ("public", "owner")

_NON_ALNUM = re.compile(r"[^a-z0-9]+")


class AppRegistryError(RuntimeError):
    """Malformed employee_apps.json."""


@dataclass(frozen=True)
class NodeTemplate:
    type: str
    params: Mapping[str, Any]
    label: Optional[str] = None


@dataclass(frozen=True)
class TriggerTemplate(NodeTemplate):
    audience: str = "public"
    #: The agent's prompt for one firing, with ${trigger.<field>} placeholders.
    prompt: str = ""


@dataclass(frozen=True)
class ToolTemplate(NodeTemplate):
    side_effects: str = "read"
    #: Params that make the tool safe under ``ask first``. A tool that
    #: declares them stays attached for such an employee, with these
    #: merged over ``params`` (the browser turns read-only and hands any
    #: page change to the owner); a tool without them is left out.
    ask_first_params: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}))
    #: The key under which the builder records the tool's node id in the
    #: employee's ``node_roles``.
    role: Optional[str] = None


@dataclass(frozen=True)
class AppSpec:
    id: str
    name: str
    provider_id: str
    aliases: Tuple[str, ...]
    trigger: Optional[TriggerTemplate]
    reply: Optional[NodeTemplate]
    notify_owner: Optional[NodeTemplate]
    tools: Tuple[ToolTemplate, ...]
    side_effects: str
    phrases: Mapping[str, str]
    #: How the agent the owner talks to sends through this app when the
    #: owner asks it to (the model fills in who and what). Wired to that
    #: agent only, never to a worker strangers write to; every call waits
    #: for the owner while they ask first (services/approvals/tool_calls.py).
    talk_send: Optional[NodeTemplate] = None
    #: Slash commands this app adds to the employee's chat
    #: (``{command, description, fill, suggest}``; get_chat_context).
    commands: Tuple[Mapping[str, Any], ...] = ()
    #: Its icon, for an app whose provider has no entry of its own in the
    #: credential registry (an app from a source).
    icon_ref: Optional[str] = None

    @property
    def node_types(self) -> frozenset:
        types = {t.type for t in (self.trigger, self.reply, self.notify_owner, self.talk_send) if t is not None}
        types.update(tool.type for tool in self.tools)
        return frozenset(types)

    def phrase(self, key: str, default: str = "") -> str:
        return self.phrases.get(key) or default


def side_effect_rank(value: str) -> int:
    return SIDE_EFFECTS.index(value)


def allowed_when_asking_first(side_effects: str) -> bool:
    """Under the ``ask first`` ground rule nothing may send or spend on the
    owner's behalf without the approval step, so such tools stay off."""
    return side_effect_rank(side_effects) < side_effect_rank("send")


def normalize_name(value: str) -> str:
    return _NON_ALNUM.sub(" ", str(value or "").lower()).strip()


# ----- loading -----


def _template(app_id: str, role: str, raw: Any, cls: type = NodeTemplate) -> Any:
    if raw is None:
        return None
    if not isinstance(raw, dict) or not isinstance(raw.get("type"), str) or not raw["type"]:
        raise AppRegistryError(f"{app_id}.{role}: needs a node `type`")
    params = raw.get("params") or {}
    if not isinstance(params, dict):
        raise AppRegistryError(f"{app_id}.{role}.params must be an object")
    fields: Dict[str, Any] = {"type": raw["type"], "params": MappingProxyType(dict(params)), "label": raw.get("label")}
    if cls is TriggerTemplate:
        audience = raw.get("audience", "public")
        if audience not in AUDIENCES:
            raise AppRegistryError(f"{app_id}.trigger.audience must be one of {AUDIENCES}")
        fields.update(audience=audience, prompt=str(raw.get("prompt") or ""))
    if cls is ToolTemplate:
        effect = raw.get("side_effects")
        if effect not in SIDE_EFFECTS:
            raise AppRegistryError(f"{app_id}.tools[{raw['type']}].side_effects must be one of {SIDE_EFFECTS}")
        fields["side_effects"] = effect
        ask_first = raw.get("ask_first_params") or {}
        if not isinstance(ask_first, dict):
            raise AppRegistryError(f"{app_id}.tools[{raw['type']}].ask_first_params must be an object")
        fields["ask_first_params"] = MappingProxyType(dict(ask_first))
        tool_role = raw.get("role")
        if tool_role is not None and (not isinstance(tool_role, str) or not tool_role):
            raise AppRegistryError(f"{app_id}.tools[{raw['type']}].role must be a non-empty string")
        fields["role"] = tool_role
    return cls(**fields)


def _parse(raw: Mapping[str, Any]) -> Dict[str, AppSpec]:
    apps_raw = raw.get("apps")
    if not isinstance(apps_raw, dict) or not apps_raw:
        raise AppRegistryError("employee_apps.json needs a non-empty `apps` object")
    apps: Dict[str, AppSpec] = {}
    for app_id, entry in apps_raw.items():
        if not isinstance(entry, dict):
            raise AppRegistryError(f"{app_id}: must be an object")
        for key in ("name", "provider_id"):
            if not isinstance(entry.get(key), str) or not entry[key]:
                raise AppRegistryError(f"{app_id}: needs `{key}`")
        effect = entry.get("side_effects")
        if effect not in SIDE_EFFECTS:
            raise AppRegistryError(f"{app_id}.side_effects must be one of {SIDE_EFFECTS}")
        tools = tuple(_template(app_id, "tools", tool, ToolTemplate) for tool in entry.get("tools") or [])
        apps[app_id] = AppSpec(
            id=app_id,
            name=entry["name"],
            provider_id=entry["provider_id"],
            aliases=tuple(str(alias) for alias in entry.get("aliases") or []),
            trigger=_template(app_id, "trigger", entry.get("trigger"), TriggerTemplate),
            reply=_template(app_id, "reply", entry.get("reply")),
            notify_owner=_template(app_id, "notify_owner", entry.get("notify_owner")),
            talk_send=_template(app_id, "talk_send", entry.get("talk_send")),
            tools=tools,
            side_effects=effect,
            phrases=MappingProxyType({str(k): str(v) for k, v in (entry.get("phrases") or {}).items()}),
            commands=_commands(app_id, entry.get("commands")),
        )
    return apps


_COMMAND = re.compile(r"^/[a-z0-9-]{1,30}$")


def _commands(app_id: str, raw: Any) -> Tuple[Mapping[str, Any], ...]:
    """An app's slash commands: ``{command, description, fill, suggest}``."""
    if raw is None:
        return ()
    if not isinstance(raw, list):
        raise AppRegistryError(f"{app_id}.commands must be a list")
    commands = []
    for item in raw:
        if not isinstance(item, dict) or not isinstance(item.get("command"), str) or not _COMMAND.match(item["command"]):
            raise AppRegistryError(f"{app_id}.commands: each needs a `command` like /schedule")
        commands.append(
            MappingProxyType(
                {
                    "command": item["command"],
                    "description": str(item.get("description") or ""),
                    "fill": str(item.get("fill") or ""),
                    "suggest": bool(item.get("suggest")),
                }
            )
        )
    return tuple(commands)


_apps: Optional[Dict[str, AppSpec]] = None
_by_node_type: Optional[Dict[str, AppSpec]] = None


def get_apps() -> Mapping[str, AppSpec]:
    """Every app, in declaration order (which breaks ties in resolve_app)."""
    global _apps, _by_node_type
    if _apps is None:
        try:
            raw = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError) as exc:
            raise AppRegistryError(f"cannot read {CONFIG_PATH}: {exc}") from exc
        _apps = _parse(raw)
        index: Dict[str, AppSpec] = {}
        for app in _apps.values():
            for node_type in sorted(app.node_types):
                index.setdefault(node_type, app)
        _by_node_type = index
    return MappingProxyType(_apps)


def reload_apps() -> None:
    global _apps, _by_node_type
    _apps = None
    _by_node_type = None


def get_app(app_id: str) -> Optional[AppSpec]:
    return get_apps().get(app_id)


def app_for_node_type(node_type: str) -> Optional[AppSpec]:
    """The app a node type belongs to (reverse of the templates), if any."""
    get_apps()
    assert _by_node_type is not None
    return _by_node_type.get(node_type)


# ----- apps from what an owner saved -----

#: ``source(principal)``: the apps one owner saved (None: the install's).
AppSource = Callable[[Optional[str]], Awaitable[Iterable[AppSpec]]]

_SOURCES: Dict[str, AppSource] = {}
_SOURCE_REGISTRY: IdempotentRegistry[str, AppSource] = IdempotentRegistry("app_source", items=_SOURCES)


def register_app_source(kind: str, source: AppSource) -> None:
    """Idempotent on re-import; a different source for a kind raises."""
    _SOURCE_REGISTRY.register(kind, source)


async def source_apps(principal: Optional[str] = None) -> List[AppSpec]:
    """Every source's apps for one owner. A source that fails gives none."""
    apps: List[AppSpec] = []
    for kind, source in _SOURCES.items():
        try:
            apps.extend(await source(principal))
        except Exception:
            logger.warning("Could not read an app source", kind=kind, exc_info=True)
    return apps


def _keys(app: AppSpec) -> Iterable[Tuple[str, int]]:
    """(normalized key, preference): the id and name first, aliases after."""
    yield normalize_name(app.id.replace("_", " ")), 0
    yield normalize_name(app.name), 0
    for alias in app.aliases:
        yield normalize_name(alias), 1


def _score(query: str, key: str) -> Optional[Tuple[int, int]]:
    """(tier, within-tier order): lower is a better match."""
    if not key:
        return None
    if query == key:
        return (0, 0)
    if key.startswith(query):
        return (1, len(key) - len(query))  # the shortest completion
    if query.startswith(key + " "):
        return (2, -len(key))  # the longest leading word run
    if len(query) >= 3 and len(key) >= 3:
        if key in query:
            return (3, -len(key))
        if query in key:
            return (3, len(key))
    return None


def resolve_app(name: str, connected: Optional[Sequence[str]] = None, apps: Optional[Iterable[AppSpec]] = None) -> Optional[AppSpec]:
    """The app a free-text name refers to, or None when nothing matches.

    ``apps`` are the apps to choose from (``Connections.apps``); the
    registry's when not given. Within the best tier a connected app wins,
    then a name match over an alias match, then declaration order: "email"
    picks Gmail when Gmail is connected and IMAP is not, and "calendar"
    picks whichever calendar is connected."""
    query = normalize_name(name)
    if not query:
        return None
    connected_ids = set(connected or ())
    best: Optional[Tuple[Tuple[int, int, int, int, int], AppSpec]] = None
    for index, app in enumerate(get_apps().values() if apps is None else apps):
        for key, preference in _keys(app):
            score = _score(query, key)
            if score is None:
                continue
            rank = (score[0], 0 if app.id in connected_ids else 1, preference, score[1], index)
            if best is None or rank < best[0]:
                best = (rank, app)
    return best[1] if best else None


__all__ = [
    "AUDIENCES",
    "AppRegistryError",
    "AppSource",
    "AppSpec",
    "CONFIG_PATH",
    "NodeTemplate",
    "SIDE_EFFECTS",
    "ToolTemplate",
    "TriggerTemplate",
    "allowed_when_asking_first",
    "app_for_node_type",
    "get_app",
    "get_apps",
    "normalize_name",
    "register_app_source",
    "reload_apps",
    "resolve_app",
    "side_effect_rank",
    "source_apps",
]