Viv Compiler

This package contains the reference compiler for the domain-specific language (DSL) at the heart of Viv, an engine for emergent narrative in games and simulations.

The Viv compiler accepts a Viv source file (.viv) and produces a Viv content bundle in a JSON-serializable format that is compatible with any Viv runtime, enabling character simulation and story sifting according to the constructs defined in the authored Viv code.

Once you've installed this package, you'll have access to two compiler interfaces:

A command-line interface (vivc) for invoking the compiler from the command line.
A Python API for invoking the compiler programmatically.

As for runtimes, currently there is a single option: the Viv JavaScript runtime.

Docs

Consult the compiler reference for documentation of the CLI, Python API, troubleshooting strategies, and more.

Requirements

Python 3.11+.

Installation

Install from PyPI:
```
pip install viv-compiler
```

Run a smoke test to confirm your installation looks good:

$ vivc --test

* Compiling sample file...

* Smoke test passed

* Viv compiler installation is operational

Running from Source

Here's how to work directly from a repo checkout:

Clone the Viv monorepo:

git clone https://github.com/siftystudio/viv

Install the compiler package and its dependencies via Poetry:
```
cd viv/compiler
poetry install
```
Use Poetry to invoke the CLI:
```
poetry run vivc --test
```

Changelog

See the changelog for a history of changes to this package.

Security and Privacy

The Viv compiler runs entirely on your machine. It collects no telemetry, makes no analytics calls, and sends no data to any third party. If you discover a security vulnerability in the compiler, please report it using the protocol described in the Viv security policy.

License

Viv is freely available for non-commercial use, while commercial use requires a license from Sifty. Check out LICENSE.txt for the full details.

Metadata

Release files for viv-compiler 0.12.2

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

Source distribution (sdist)

Source distribution for viv-compiler 0.12.2
File	Size	Uploaded	Provenance
viv_compiler-0.12.2.tar.gz	125.1 kB	May 15, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for viv-compiler 0.12.2
File	Interpreter	ABI	Platform	Reset
viv_compiler-0.12.2-py3-none-any.whl 153.9 kB May 15, 2026 With provenance	Python 3	none	any	Details

Total release size: 279.0 kB

Release files / viv_compiler-0.12.2.tar.gz

Download URL	viv_compiler-0.12.2.tar.gz
Size	125.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`9892ce99212447c2d59b50019befac4394229394e804369855b50ce9c865c384`
BLAKE2b-256 checksum How to use checksums	`0c920a46fce86282e0fa4481c144af0c4115af345f2450b911e5088539293539`
Upload date	May 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/siftystudio/viv
Publishing commit: github.com/siftystudio/viv/tree/48da32bc54ecbfe499dd286c0c0cc14a18b2eebb

Workflow

Publishing configuration: github.com/siftystudio/viv/blob/48da32bc54ecbfe499dd286c0c0cc14a18b2eebb/.github/workflows/cd-compiler.yml
Publishing logs: github.com/siftystudio/viv/actions/runs/25904100951/attempts/1

Artifact

Subject: viv_compiler-0.12.2.tar.gz
SHA-256 checksum: 9892ce99212447c2d59b50019befac4394229394e804369855b50ce9c865c384 Verifying attestations

Release files / viv_compiler-0.12.2-py3-none-any.whl

Download URL	viv_compiler-0.12.2-py3-none-any.whl
Size	153.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`281631c98d50ee550033925d9ad90d4559a0bd742dfd05eb1f9cbfc9aeb44697`
BLAKE2b-256 checksum How to use checksums	`a91a3f4c3b5872bf158104c9d61d7675100755b2071c67e51f7e275a2da46c5e`
Upload date	May 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/siftystudio/viv
Publishing commit: github.com/siftystudio/viv/tree/48da32bc54ecbfe499dd286c0c0cc14a18b2eebb

Workflow

Publishing configuration: github.com/siftystudio/viv/blob/48da32bc54ecbfe499dd286c0c0cc14a18b2eebb/.github/workflows/cd-compiler.yml
Publishing logs: github.com/siftystudio/viv/actions/runs/25904100951/attempts/1

Artifact

Subject: viv_compiler-0.12.2-py3-none-any.whl
SHA-256 checksum: 281631c98d50ee550033925d9ad90d4559a0bd742dfd05eb1f9cbfc9aeb44697 Verifying attestations

Security for viv-compiler 0.12.2

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for viv_compiler-0.12.2.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/siftystudio/viv
Publishing commit: github.com/siftystudio/viv/tree/48da32bc54ecbfe499dd286c0c0cc14a18b2eebb

Workflow

Publishing configuration: github.com/siftystudio/viv/blob/48da32bc54ecbfe499dd286c0c0cc14a18b2eebb/.github/workflows/cd-compiler.yml
Publishing logs: github.com/siftystudio/viv/actions/runs/25904100951/attempts/1

Artifact

Subject: viv_compiler-0.12.2.tar.gz
SHA-256 checksum: 9892ce99212447c2d59b50019befac4394229394e804369855b50ce9c865c384 Verifying attestations

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.