Tier 2 · AI Core

Shared Capability

AI Companion

dcc/maya/ai_panel.py — a dockable natural-language-to-reviewable-Python-script panel (AIPanel, WINDOW_OBJECT_NAME = "CF_AICompanionWindow") any application can plug into. Launch it standalone from Utilities > AI Companion, or have another application open and bind it to its own curated API (see Embedding in another app — AnimHub's ClipsAPI integration, documented fully in ClipsAPI, is the worked example). This is a shared capability, not a separate autonomous agent - one panel, reused by every application that wants it, each one scoping it down to its own domain.

Its Maya-menu/QuickLaunch icon sits next to its launcher module, separate from its in-app window/button icon (also used by AnimHub's own "Ask AI" corner toolbar button).

The human review step before Run is the entire safety mechanism - not a sandbox. The curated API is a separate, complementary layer that keeps common actions on a tested path.

The safety model

The model never touches the Maya scene directly:

1. You type a request.
2. The model returns text only — an explanation plus a proposed Python script.
3. You read the script.
4. Clicking Run executes it, wrapped in a single Maya undo chunk (so one Ctrl+Z reverts everything it did).

That review step is the entire safety mechanism — there's no sandboxing or restricted cmds allow-list underneath it. See ClipsAPI's Safety model section for the full mechanics (core/ai/execute.py's run_generated_code) and why a curated API object matters even though it isn't a hard sandbox boundary.

UI layout

The window can be resized down to 280px wide / 580px tall without cropping — deliberately narrow-dockable, since a Maya dock column is often much narrower than a comfortable floating-window default.

Script History

Opened via the Script History button in the header. Records every script actually executed (Run clicked, or Re-run from this dialog) — not scripts that were only proposed and then Discarded, and not just successful ones either, since a failed attempt is often exactly what's worth studying later.

Persistent across Maya sessions, not session-scoped — reverted from an earlier in-memory-only design once it became clear that losing everything the moment the panel closed made it useless as a "what did I actually run last week" reference. Backed by core/ai/script_history_store.py: a plain append-only JSON Lines file in a local per-user data directory (the same convention the application log file uses). JSON Lines specifically because it needs only an O(1) file append for a new entry (no read-modify-write of a whole array), and a single malformed/truncated trailing line (e.g. Maya closing mid-write) doesn't lose every entry before it.

Each entry: timestamp, the original request text, the model's explanation, the code, whether it succeeded, and the failure message if not.

Per-entry actions:

• Copy Code / Re-run (re-executes through the same run_generated_code path, recording a new history entry).
• Right-click Copy Prompt — copies just the original request text for that entry (distinct from Copy Code), handy for re-asking a variant of an old prompt.
• The list supports multi-select (Ctrl/Shift-click); right-click with more than one row selected shows Delete Selected (N) instead of Copy Prompt, removing the selected entries from both the in-memory list and the on-disk store (a full rewrite of the JSONL file, the only operation the store supports besides append).
• A search box above the list filters by request text, explanation, or code as you type, preserving the current selection across both typing and a live refresh (e.g. a new entry landing mid-search from a Re-run) rather than resetting the filter.

Embedding in another app

AIPanel.__init__ accepts three optional hooks, and set_context() lets an embedding app rebind them after construction — necessary because show_dockable() reuses an already-open panel instead of reconstructing it, so a constructor-only kwarg would only ever take effect on the very first launch:

def _on_ask_ai(self):
    window = ai_panel.show()
    if window is None:
        window = dcc_ui.find_dockable_instance(ai_panel.AIPanel)
    if window is not None:
        window.set_context(
            context_provider=self._ai_context_summary,
            extra_namespace_provider=lambda: {"clips": ClipsAPI(self.clips)},
            on_run_complete=self._rebuild_rows)

• context_provider — a zero-arg callable returning a plain-text "concepts primer" sent alongside every request. This is where you document your curated API's real method names, correct usage, and any disambiguation the model needs — see ClipsAPI's concepts primer section for three real bugs this mechanism exists to prevent.
• extra_namespace_provider — a zero-arg callable returning a dict merged into the exec namespace on top of cmds when running generated code. This is the actual capability boundary (see The safety model) — whatever you put here is what the AI can call.
• on_run_complete — a zero-arg callable invoked after a successful run, so the embedding app can refresh its own UI state.

All three default to None and are safe to omit — a plain, unbound AIPanel runs in "Full Scene" mode: just cmds, no context primer, no completion hook.

Provider / API key setup

Settings > AI (or the gear icon in the panel header) configures the provider (Anthropic / OpenAI / Gemini), model, and API key. Keys are stored in the OS keychain via core/ai/key_storage.py, never in a config file. If no key is set when you send a request, the panel prompts for one inline; keyring must be installed in Maya's Python for this to work at all (mayapy -m pip install keyring if the panel reports it's missing).