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(plusRunRef,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(pluscontract_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 withParquetEmitterdatasets 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.