Skip to main content

viva-emitters

Focused emitter library for process-bigraph composites. Hosts the heavy-dependency emitters out-of-tree so the process-bigraph core stays lean.

The zero-dependency built-ins — RAMEmitter, ConsoleEmitter, JSONEmitter — continue to live in process_bigraph.emitter. This package adds disk-backed emitters (each a process-bigraph Step), an emitter-agnostic reader, and a small per-agent emitter lifecycle registry.

What it provides

Emitter Extra What it does
SQLiteEmitter [sqlite] One row per tick into a single .db file (stdlib).
ParquetEmitter [parquet] Hive-partitioned Parquet dataset, batched writes.
LongFormParquetEmitter [parquet-lite] Lightweight single-file long-form Parquet (pyarrow only).
XArrayEmitter [xarray] Zarr-backed N-dimensional dataset via xarray, unit-aware.

Imports are lazy: importing viva_emitters never forces the heavy dependencies — each emitter only becomes available when its extra is installed.

Alongside the emitters the top-level package exports:

  • RunReader (plus RunRef, by_generation) — an emitter-agnostic reader that returns a uniform per-tick series for any observable across parquet / sqlite / xarray-zarr stores, auto-detecting the backend from the store path.
  • Emitter lifecycle registry — register_emitter, get_emitter, unregister_emitter, clear_registry, registered_agent_ids, finalize_emitter_for_agent: a pure-stdlib per-agent registry for tracking and finalizing emitters across a run.
  • EmitterContract (plus contract_for, register_contract) — a minimal self-description (output_kind, output_uri_config_key) that lets a consumer read back a finished run without knowing which emitter wrote it.
  • Parquet reader helpers re-exported from the top level (create_duckdb_conn, read_stacked_columns, named_idx, ndidx_to_duckdb_expr, ...) for working with ParquetEmitter datasets directly.

Install

Install only the extras you need:

pip install 'viva-emitters[sqlite]'          # SQLiteEmitter (stdlib only)
pip install 'viva-emitters[parquet]'         # ParquetEmitter (duckdb, polars, ...)
pip install 'viva-emitters[parquet-lite]'    # LongFormParquetEmitter (pyarrow only)
pip install 'viva-emitters[xarray]'          # XArrayEmitter (xarray, zarr, pint, ...)
pip install 'viva-emitters[sqlite,parquet]'  # multiple at once

The [sqlite] extra is empty (Python's stdlib sqlite3 is enough); it exists for symmetry. The [parquet] extra pulls in duckdb, polars, pyarrow, fsspec, and tqdm. The [parquet-lite] extra pulls in only pyarrow. The [xarray] extra pulls in xarray, zarr, zarrs, bottleneck, fsspec, pint, and unum.

From a checkout, for development:

uv pip install -e '.[parquet,dev]'   # or: pip install -e '.[parquet,dev]'

Usage

Wire an emitter as a step inside a process-bigraph Composite, e.g. via the usual emitter_from_wires helper:

from viva_emitters import SQLiteEmitter, ParquetEmitter  # registers the Steps
from process_bigraph.emitter import emitter_from_wires

spec = emitter_from_wires(wires, address='local:SQLiteEmitter')

To read a stored run back — independently of which emitter wrote it:

from viva_emitters import RunReader

reader = RunReader.open('path/to/run.db')   # or a .zarr dir / parquet hive dir
reader.observables()                        # available observables
reader.generations()                        # generation indices present
df = reader.series('mass')                  # uniform per-tick series (polars)

RunReader also exposes select(index_by=...), aggregate_series(...), catalog(...), resolve_id(...), and summary() for indexed / aggregated reads.

Back-compat

The import package was renamed from pbg_emitters to viva_emitters as part of the pbg → viva rebrand. A pbg_emitters shim still re-exports the public surface (emitting a one-time DeprecationWarning); update imports to viva_emitters.

Tests

uv pip install -e '.[parquet,dev]'
pytest

License

MIT. See LICENSE.

Metadata

Release files for viva-emitters 0.4.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for viva-emitters 0.4.4
File Size Uploaded Provenance Actions
viva_emitters-0.4.4.tar.gz 158.5 kB With provenance Details for viva_emitters-0.4.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for viva-emitters 0.4.4
File Interpreter ABI Platform Actions
viva_emitters-0.4.4-py3-none-any.whl Python 3 none any Details for viva_emitters-0.4.4-py3-none-any.whl

Total release size: 284.5 kB

Release files / viva_emitters-0.4.4.tar.gz

Download URL viva_emitters-0.4.4.tar.gz
Size 158.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8ce0d6c5dd32c37d4d3c913b5dc2c229d60a15095080cf849137576fb549fcf6
BLAKE2b-256 checksum
How to use checksums
841df33b0d6f54511b6e73d9262a983907eac5f489dd68c94ab30776942e7078
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / viva_emitters-0.4.4-py3-none-any.whl

Download URL viva_emitters-0.4.4-py3-none-any.whl
Size 126.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d39e4e396385c5d456a331db4dacf089551790ff869ddc8da09626e96b79e60b
BLAKE2b-256 checksum
How to use checksums
23377951e0e463dcc07fb8256ac970c974276faceeaa2f5a363a804549776bd7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for viva-emitters 0.4.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for viva_emitters-0.4.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page