Skip to content
Marivo

First agent-guided analysis

Start the analysis

Section titled “Start the analysis”

Use a project metric whose business meaning is approved and that the current catalog can load. If the metric is missing or disputed, typed analysis stops; the agent may use md.raw_sql(...) with read-only credentials, query size controlled in SQL, and disclosed temporary semantics, but hands a reusable gap to semantic authoring and asks only about unresolved business meaning.

You do not need to write Python, select operators, or prescribe checks. State the question, metric, comparison, and initial investigation focus:

Use marivo-analysis to explain why revenue decreased in 2026 Q4 compared with the same period in 2025. Use the approved sales.revenue metric, compare by month, and inspect region first. Finish with the conclusion, key evidence, and limitations.

What Marivo handles

Section titled “What Marivo handles”

The agent reads the relevant definitions, resolves and validates the live semantic inputs, performs appropriate typed analysis in one analysis session, and preserves the material results and evidence. A semantic gap never permits the agent to change definitions during analysis. Terminal raw SQL may provide a provisional answer, but it remains separate from canonical Marivo evidence; the agent hands the smallest reusable gap to marivo-semantic automatically and resumes the affected analysis branch after readiness.

Catalog navigation returns current typed entries that qualifying semantic and analysis runtime calls accept directly; exact refs remain valid for configuration and recovery. Marivo normalizes either form to the ref before planning, evidence, persistence, or replay.

The agent selects a project interpreter and verifies the live environment once with <selected-python> -m marivo doctor. A conventional project-local installation uses .venv/bin/python on macOS, Linux, and WSL or .venv/Scripts/python.exe on Windows. After entry, it works from the public object already in hand: .show() reports current state, .contract() guides unfamiliar composition, and focused marivo.help(...) after import marivo is needed only when that contract is insufficient or before first use of an unfamiliar capability. After a failure, the agent follows the structured repair. Focused help is not a prerequisite for every API call.

The typed boundary (session.observe in, frame.to_pandas() / md.raw_sql out) keeps custom analysis from breaking the evidence chain. RawSqlResult.shape and .row_count describe complete returned query rows only; the result has no .contract() or typed re-entry. Typed regression is not a Marivo capability yet and remains explicit terminal custom analysis.

Those mechanics are owned by live help, frames, and structured errors — they do not need to appear in your prompt.

What to review

Section titled “What to review”

Before accepting the conclusion or asking for a deeper investigation, confirm that:

  • the metric meaning matches the business outcome you intended;
  • the period and population, including exclusions, are correct;
  • the comparison and initial investigation focus are meaningful;
  • each material claim is supported by Marivo results or evidence;
  • limitations, quality issues, and unresolved questions are explicit; and
  • the agent did not silently change the semantic layer.

Next steps

Section titled “Next steps”