Using Zyra in Python Notebooks

Overview

  • Run Zyra stages directly in notebooks with create_session().

  • Register custom tools inline; they are exposed to the planner via a capabilities overlay.

  • Provenance is logged to SQLite; pipelines/CLI equivalents can be exported.

  • Narrate/swarm works in notebooks with provider selection and debug output.

Setup

  • Install: poetry install --with dev (or pip equivalents in your env).

  • Env vars:

    • ZYRA_NOTEBOOK_DIR (workspace), ZYRA_NOTEBOOK_PROVENANCE (provenance DB, defaults under workspace).

    • LLM: GOOGLE_API_KEY (Gemini), OPENAI_API_KEY, OLLAMA_BASE_URL. Fallback is mock if none set.

    • Verbose swarm logs: ZYRA_VERBOSITY=debug.

Quick start

from zyra.notebook import create_session
sess = create_session()  # uses ZYRA_NOTEBOOK_DIR or cwd

# Acquire/process example
data = sess.acquire.http(url="https://example.com/file.bin")

# Register an inline tool (with templates for planner)
def smooth(ns): ...
sess.process.register(
    "smooth",
    smooth,
    returns="object",
    args_template={"input": "frames_padded"},
    outputs_template={"output": "analysis.json"},
)

# Export
print(sess.to_pipeline())
print(sess.to_cli())

Inline tool overlay (planner integration)

  • Registration writes notebook_capabilities_overlay.json in the workspace.

  • Planner loads this overlay (env ZYRA_NOTEBOOK_OVERLAY set by session/notebook cells).

  • Inline suggestions are labeled (e.g., [inline: notebook_register]); consent prompts include the origin.

  • Overlays include templates (args/outputs) and inline serialization metadata; replay currently warns/skips if inline code is absent.

Interactive planner flow (from notebook)

  • sess.plan(...) wraps zyra plan with prompts enabled in notebooks; provenance goes to the session DB.

  • Inline planner demo cell:

    • Prompts for missing args (FTP path/pattern, etc.).

    • Runs value engine; prints accepted vs. remaining suggestions.

    • Ensures scan/pad/compose/local wiring; saves plan to plan_session_inline.json.

  • Replay example: poetry run zyra swarm --plan /app/data/drought_notebook/plan_session_inline.json --stage acquire,process,visualize,decimate.

Narrate/swarm in notebooks

  • Provider selector defaults to Gemini (if creds) β†’ OpenAI β†’ Ollama β†’ mock.

  • Narrate cell builds frame/location bullets, sets a rubric, runs sess.narrate.swarm, and logs pack/provenance.

  • Input preview and agent outputs live in narrate_pack.yaml; final narration prefers the edited output.

Provenance

  • Default DB: ${ZYRA_NOTEBOOK_DIR}/provenance.sqlite (configurable via ZYRA_NOTEBOOK_PROVENANCE).

  • Inspect via notebook cell (tables, last events) or zyra swarm --dump-memory <db>.

Notebook walkthrough highlights (drought example)

  • Registers a custom drought-frame analyzer (overlay makes it plannable).

  • Planner intent mentions analyzing frames; inline planner suggests the analyzer and wires dependencies.

  • Plan outputs: plan_session_inline.json, overlays, provenance DB, and narrate packs.

Security/guardrails

  • Inline tools must be serializable; overlays warn and skip inline replay if code isn’t available.

  • Consent prompts label inline origins before suggesting user code.