Jupyternaut

The AI assistant in your notebook quietly knows which datasets you have and which are worth using — suggesting them when relevant, staying out of the way otherwise.

Overview

Jupyternaut is the AI persona that lives in the JupyterLab side panel. Out of the box it's a general code assistant. When Auracle's Jupyternaut extension is loaded, every Jupyternaut session gets an AmbientContext — an immutable snapshot of "what the assistant knows about this install's data" — prepended to the system prompt and surfaced through every integration layer Jupyter AI exposes.

The result: when you ask "what's the realized vol of BTC over the last 30 days," the assistant already knows you have polygon.io/bars.daily and coinalyze/funding_rates in your catalog and can write code against them without you having to introduce them.

Ambient AI

AmbientContext is an immutable dataclass built per session and refreshed when the catalog changes (debounced ~5 s). It contains:

• install_uuid — opaque per-install identifier.
• tier — community or pro.
• enabled — the kill-switch value.
• catalog_summary — tuple of CatalogEntry rows with verdict useful.
• catalog_signature — a 16-hex-char SHA-256 used by consumers as a cache key.
• active_notebook — the notebook the user is focused on, with its imports and recent cells.

What gets injected

A compact ~15-line block is prepended to the assistant's system prompt. It looks like this:

─── Auracle ambient context (notebook: btc_research.ipynb) ───
The user has these RELEVANT datasets in their Auracle catalog:
  • polygon.io.bars.daily            equities       5.0y    useful
  • polygon.io.options.chains        equities       2.0y    useful
  • coinalyze.funding_rates          crypto         3.0y    useful
  • coingecko.market_chart           crypto         8.0y    useful
  • ibkr.bars.minute                 equities       1.0y    useful

Use these datasets ONLY when explicitly relevant to the user's code.
DO NOT call provider APIs without showing the user the call first;
ask 'Want me to use X for this?' when relevant.
The user can pin/exclude datasets via /use and /forget.
─── end Auracle context ───

Inspect the live injection at any time with auracle forge ambient.

The kill switch

Set AURACLE_FORGE_AMBIENT=0 in ~/auracle/.env and restart the Jupyter container to disable the injection entirely. The assistant returns to its stock behavior; no Auracle awareness.

Integration points

Auracle wires into every Jupyter AI extension point:

Slash commands

@-mentions

Typing @ opens a fuzzy-matched picker over every catalog entry with verdict useful. Pick one and it inserts a token like @polygon.bars.daily; the assistant treats that as a concrete reference and will write code that imports the right Auracle adapter.

Mention expansion

When you ask, "Plot @polygon.bars.daily for AAPL", the assistant rewrites the call to:

from auracle.adapters import polygon

bars = polygon.bars(symbol="AAPL", resolution="1d", lookback="2y")
bars["close"].plot(title="AAPL daily close — polygon.io")

The adapter is generated by the Forge at probe time. The mention contract is the same whether the adapter is generated or the assistant falls back to the raw HTTP route.

Mentioning excluded datasets

If you /forget a dataset, it still appears in the @-mention list (you can always explicitly call it back) but is no longer suggested ambiently. The kill switch affects both ambient suggestion and the @-list; a fully-disabled Forge shows no mentions at all.