Using Zyra in Python Notebooks

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.