AI provider backend

Shape of a request/response

core/ai/schemas.py defines the one shape every provider client returns:

@dataclass
class AIResponse:
    explanation: str = ""
    python_code: str = ""
    error: str = ""

    @property
    def ok(self):
        return not self.error

error is set (with explanation/python_code left blank) only when the request itself failed — network, auth, or malformed model output. Callers must check error/ok first and never assume python_code is present otherwise.

The provider registry

core/ai/providers.py's PROVIDERS dict is the single source of truth for what providers exist:

DEFAULT_PROVIDER = "anthropic".

build_client(provider=None, model=None) -> AIClient

Falls back to DEFAULT_PROVIDER if provider is falsy; raises ValueError for an unknown provider id. Instantiates the concrete client class with model=model or entry["default_model"] — no API key is passed here; each client resolves its own key from key storage unless constructed with one directly.

Other functions in this module, mostly consumed by Settings > AI:

• is_installed(provider) — a cheap "is the SDK importable" check (importlib.util.find_spec, not a real import), with a disk-existence guard since a cached finder entry can lie after an external uninstall.
• install_command(provider, upgrade=False) — returns (mayapy_path, argv) for mayapy -m pip install <package>. Deliberately does not execute it — Settings runs it via a non-blocking QProcess so installing an SDK doesn't freeze Maya's UI.
• list_models(provider, api_key) — a live API call to list that provider's chat-capable model ids, for the model-refresh button in Settings.
• invalidate_import_cache() — importlib.invalidate_caches(), called after an install finishes so the freshly-installed SDK is importable without restarting Maya.

The client interface

core/ai/client_base.py — the entire abstract surface is one method:

class AIClient:
    def generate_code(self, user_request, context=""):
        raise NotImplementedError

context is a plain-text summary the caller assembles (current selection, a domain-specific "concepts primer" — see ai_panel.py's context_provider hook, documented in AI Companion). The client folds it into the prompt; it never fetches anything itself.

Each concrete client shares the same structural pattern:

• Lazy SDK import inside generate_code(), never at module load — a missing SDK on one provider never breaks the others or any other core/ai/ caller.
• __init__(self, model=DEFAULT_MODEL, api_key=None), resolving the key from a constructor arg first, then key storage.
• A forced tool/function call to a single propose_script function taking explanation (string) and python_code (string), both required — the model cannot respond with free text; every successful call returns a structured proposal.
• Any API failure is caught, logged (traceback.print_exc()), and returned as AIResponse(error=...) rather than raised.

Provider-specific notes

Each client's fallback path (if the model somehow doesn't return the forced tool call — "should be unreachable" per the code's own comments) returns whatever free text the model did produce as an AIResponse with error set, rather than crashing on a missing field.

The system prompt

core/ai/prompts.py — SYSTEM_PROMPT is sent (via system_prompt_for_scope(), currently a pass-through, kept as a hook for a future narrower per-domain scope) with every request, alongside build_user_message(user_request, context) (prefixes f"Current context:\n{context}\n\n" when context is non-empty).

What it instructs, in summary:

• Frames the model as the AI companion embedded in CoreTools, translating plain English into a maya.cmds Python script for the user to review and run. cmds is already available in the exec namespace — explicitly told not to import maya.cmds.
• No domain restriction on what nodes it can touch, but told to be precise (scope to a clear name pattern or the current selection) rather than acting broadly or guessing.
• Hard rules: always call propose_script (never respond with plain text); avoid unnecessary imports; never call cmds.file(save=True); never touch the filesystem outside Maya's own commands; never make network requests; write code that's readable/sanity-checkable by a lightly-technical user, since they have to approve it before it runs.
• Ambiguous requests still get a best-effort script that resolves context at runtime (e.g. cmds.ls(selection=True)) rather than a clarification round-trip — there's no back-and-forth mechanism in this UI, so the model doesn't get to ask a follow-up question.
• A non-actionable request (a general question, not a task) gets an empty python_code and the actual answer in explanation instead.

This is prompt-level safety framing, not a sandboxing mechanism — see AI Companion's safety model for what actually enforces the boundary (a human reading the code before clicking Run).

API key storage

core/ai/key_storage.py — keys live in the OS keychain via the keyring package, never in UserConfig's plain registry-backed store (unlike Perforce credentials, which do live there in plaintext — this is a deliberately stronger precedent for anything that's an actual secret). Namespaced per-provider (f"{provider}_api_key") under a service name distinct from any other CoreTools-family tool sharing the same machine, so switching provider never clobbers another provider's stored key, and two different tools' keys never collide.

keyring_available() -> bool
get_api_key(provider="anthropic") -> str | None
set_api_key(provider, value) -> bool
clear_api_key(provider="anthropic") -> bool

Every function degrades to a safe default (False/None) rather than raising if keyring isn't importable — Maya's bundled Python doesn't ship it by default. Settings > AI disables the key field entirely and shows an install hint (mayapy -m pip install keyring) when keyring_available() is false.