AI in Notebooks

What AI in Notebooks is for

AI can help you work inside a Notebook without becoming the owner of the project. Use it to explain code, draft a cell, revise a selected section, brainstorm an investigation, assemble a report, or propose a bounded research Job. The Notebook remains ordinary Python source that you can inspect, edit, accept, or reject.

Core Notebooks does not depend on AI Companion. You can create, edit, run, and export projects without connecting a model. AI-assisted Notebook features are available only after both the Notebook and AI permission systems pass their release gates.

Connect a model first

Configure a local or hosted model through Model Connections. The Notebook uses the same selected provider, credential storage, context disclosure, usage limits, and Trust Record system as AI Companion.

Marimo's own native AI integration remains disabled unless Arizmic can route it through those same controls. A second provider configuration or hidden key inside the editor would create a different privacy and permission boundary.

Ask about the current Notebook

Open the AI control from the Notebook interface and choose the smallest useful scope:

• one selected cell;
• a named group of cells;
• the current error or stale-state message;
• the Notebook's declared context and supported SDK methods; or
• a bounded output excerpt needed to explain a problem.

The context disclosure shows the project, source version, selected cells, bound Arizmic objects, provider, model, and excluded information. Review it before sending.

Useful questions include:

• “Explain what this cell calculates and which values are engine-reported.”
• “Why did this dependent cell become stale?”
• “Suggest a clearer chart for this bounded trade page.”
• “Find the likely cause of this SDK error without changing the project.”
• “What additional check would make this Result review more useful?”

An explanation is advice. Verify SDK behavior in the current documentation and verify Result values in the owning Results or Studies surface.

Brainstorm an investigation

Use AI before writing code when you have a question but not yet a structure. Describe the object you are investigating, what you want to understand, and the data or fidelity limitations that apply.

The Companion can propose:

• the smallest context and SDK reads needed;
• a sequence of identity, control, read, validation, calculation, and presentation cells;
• alternative explanations worth separating;
• charts or tables that match the available data;
• formulas for additional Notebook-derived statistics; and
• clear stopping conditions when the retained data cannot answer the question.

Keep the first plan bounded. A Notebook is easier to review when each request and calculation answers one question than when the model produces a large unstructured analysis.

Draft a new cell

1. Place the insertion point where the new cell belongs.
2. Choose Draft with AI.
3. State the intended input, output, units, bounds, and value origin.
4. Review the disclosed context and model.
5. Generate the proposal.
6. Inspect the exact source diff, required dependencies, SDK calls, and validation findings.
7. Accept, revise, or reject the proposal.
8. Run the accepted cell and inspect every dependent cell that reruns or becomes stale.

The proposal must use the public Notebook SDK and declared project dependencies. It cannot read private storage, construct arbitrary workstation requests, install undeclared packages, or place secrets in source.

Generated code receives the same trust and review as code copied from another person. Confirm timing, units, paging, null handling, formula assumptions, and the boundary between engine-reported and Notebook-derived values.

Revise existing code

Select the exact cells and ask for one bounded change. Examples include:

• add a committed date-window control;
• replace an unbounded read with paging;
• separate one calculation from presentation;
• improve an error state without hiding missing data;
• add a source table beneath a chart; or
• clarify the formula and assumptions for a Notebook-derived value.

AI produces a before-and-after diff against the current project hash. If the source changes before acceptance, the proposal becomes stale and must be regenerated or reviewed against the new version. It cannot overwrite changed source silently.

Draft a report

Ask AI to organize selected, verified Notebook content into a report project or report section. The proposal can arrange:

• purpose and selected object identities;
• data, Strategy, Study, and Result lineage;
• engine-reported findings;
• clearly labeled Notebook-derived calculations;
• charts and supporting bounded tables;
• missing, truncated, or unresolved information; and
• conclusions limited to what the retained inputs support.

Report drafting creates a normal manifested Notebook project. It does not create or promote an Arizmic Result, and it does not strengthen a validation label. Review the full source and preview before exporting.

Ask AI to explain a Result

Bind the exact Run Output or Study Result through the Notebook context picker. AI may then explain the verified fields and bounded artifact excerpts available to the project, or help relate a Notebook-derived view back to those sources.

It may not recompute authoritative KPIs, invent missing artifacts, treat a sampled window as a complete run, or describe a simulated fill as live. Follow every consequential statement back to the exact Results field or retained artifact.

Request a Strategy improvement investigation

AI can help turn a Result observation into a Notebook investigation before you change the Strategy. Ask it to identify:

• the exact behavior or failure to inspect;
• the retained fields needed to distinguish possible causes;
• a bounded table or chart for that question;
• any new Notebook-derived statistic and its assumptions; and
• the follow-up Study that would test a proposed change.

The Notebook can support the diagnosis, but it does not save a Strategy change. Use AI Companion or the Strategy authoring workflow to create a separate, reviewed Strategy proposal.

Run a bounded research Job

Where the Notebook SDK exposes an approved Job operation, AI may propose its typed request. Before acceptance, Arizmic shows the operation, inputs, resource estimate, limits, destination, and cancellation behavior.

The normal path is:

1. AI drafts the typed Job request;
2. the Notebook SDK and owning Job service validate it;
3. you review and accept the estimate;
4. the Job owner queues and runs it;
5. the Notebook follows its queued, running, failed, canceled, or completed state; and
6. the action receipt records the exact effect.

AI permission cannot widen the Notebook token or turn a closed Job list into a generic execution tool.

Review permission and receipts

AI begins with read-and-propose access. Without a matching autonomy profile, every source or Job effect waits for your acceptance.

A limited autonomy profile must name the exact Notebook operation, project, resources, limits, expiry, and revocation control. Before applying it, Notebooks rechecks the project version, source hash, context, environment, and current permission. AI records an immutable receipt containing the proposal, approval or grant, affected version, outcome, and any partial effect.

The model cannot approve its own proposal or expand its grant.

What AI cannot do

AI in Notebooks cannot:

• write outside the selected Notebook root;
• overwrite changed or unreviewed source;
• install undeclared dependencies silently;
• access raw credentials or session tokens;
• use unrestricted shell, filesystem, network, or generic-code tools;
• bypass SDK paging, estimates, or domain permissions;
• mutate canonical Data, Results, Signals, Strategies, or Portfolios directly;
• place, modify, or cancel Live orders;
• arm, pause, resume, flatten, or kill a deployment; or
• convert a Notebook calculation into engine-reported evidence.

Local Notebook code you accept may still be powerful Python. The AI harness controls what Arizmic proposes and applies; it is not a hostile-code sandbox for the source you choose to run.

Protect private information

The provider receives only the prompt and context shown in the disclosure. Notebook source, outputs, paths, and bound records are not automatically sent in full. Credentials, tokens, unrestricted datasets, account details, and excluded fields remain outside the prompt.

A local model remains local only while its endpoint does not forward requests. A hosted model follows the selected provider's retention and processing terms. Conversation history, Trust Records, and action receipts have separate local retention purposes.

Recover from a failed AI action

• The proposal no longer matches the source: keep the current file and regenerate against its new hash.
• Validation rejects the code: review the exact SDK, dependency, bound, or type finding; do not bypass it with a private import.
• A dependency is missing: add it through the environment's reviewed requirements and lock workflow, then recreate the proposal.
• The provider times out: inspect the Trust Record before repeating the request. A timeout does not prove an accepted Job or source effect was canceled.
• A Job outcome is unknown: reconcile the owning Job and receipt before retrying.
• The response invents a value: reject it and narrow the question to a verified SDK field or artifact.
• Sensitive content was disclosed: stop using the route, preserve the disclosure and Trust Record, rotate exposed credentials if applicable, and follow the provider's incident process.

Next

Use Python Notebooks for the project, environment, SDK, and Marimo workflow. Use Notebook Templates when a shipped investigation already matches your task.