# dsviper — Digital Substrate Viper Runtime

`dsviper` is the Python extension module for **Viper**, a C++ runtime built around
metadata-driven type and value systems. It provides a seamless bidirectional bridge
between Python and Viper's strong-typed data model.

## Key Features

- **DSM Language** — Define data models with the Digital Substrate Model DSL:
  concepts, keys, documents, attachments.
- **Type & Value System** — Dynamically construct types and instantiate strong-typed
  values with automatic Python ↔ C++ bridging.
- **Commit Database** — Versioned persistence with full mutation history (DAG of commits).
- **Code Generation** — Optional `kibo` code generator produces type-safe Python
  packages from DSM definitions.
- **Blob System** — BlobArray with zero-copy NumPy integration, BlobPack for structured
  binary data.
- **IDE Support** — JetBrains plugin and VS Code extension for `.dsm` files.

## Quick Start

```python
from dsviper import *

# Strong-typed value system
names = Value.create(TypeVector(Type.STRING))
names.extend(["alice", "bob"])
print(names)          # ['alice', 'bob']
print(names.type())   # vector<string>

names.append(42)      # ViperError: expected 'str', got 'int'
```

## Commit Database

A complete example — define a model, create a versioned database, commit and query:

```python
from dsviper import *

# Define a model dynamically
defs = Definitions()
ns = NameSpace(ValueUUId.create(), "App")
t_User = defs.create_concept(ns, "User")
d_Profile = TypeStructureDescriptor("Profile")
d_Profile.add_field("name", Type.STRING)
a_profile = defs.create_attachment(ns, "profile", t_User, defs.create_structure(ns, d_Profile))

# Create a versioned database and commit data
db = CommitDatabase.create_in_memory()
db.extend_definitions(defs.const())

key = a_profile.create_key()
doc = a_profile.create_document()
doc.name = "Alice"

mutable = CommitMutableState(db.initial_state())
mutable.attachment_mutating().set(a_profile, key, doc)
db.commit_mutations("Add Alice", mutable)

# Query
state = db.state(db.last_commit_id())
state.attachment_getting().get(a_profile, key)
# Optional({name='Alice'})
```

## Installation

```
pip install dsviper
```

Requires Python ≥ 3.10. Pre-built wheels are provided for all supported platforms.

## Supported Platforms

| Platform | 3.10 | 3.11 | 3.12 | 3.13 | 3.14 |
|---|---|---|---|---|---|
| Linux x86_64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux aarch64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| macOS arm64 (Apple Silicon) | ✅ | ✅ | ✅ | ✅ | ✅ |
| macOS x86_64 (Intel) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows x64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows arm64 | — | ✅ | ✅ | ✅ | ✅ |

## Documentation

Full documentation at [devkit.digitalsubstrate.io](https://devkit.digitalsubstrate.io)

## License

**Proprietary** — Commercial license required.
Contact [Digital Substrate](https://digitalsubstrate.io) for licensing information.

## Build Information

- **Version**: 1.2.0 LTS
- **Source**: commit `174b349e` (tag `LTS-1.2.0`)
- **Build date**: 2026-03-20
