# Value Chains

Two value chains structure the dsviper ecosystem. **Toolchain** turns a data
model into runnable code; **Runtime** runs your typed Python application backed
by versioned, persistent storage. Each chain composes from independent
components — you can engage at any link without adopting the rest.

## The toolchain (code-generation side)

```
dsm  →  kibo  →  kibo-template-viper
```

**Goal.** Turn a data-model description into typed code that runs.

**dsm** — the modeling language. Standalone. Defines types, structures,
attachments, function pools. **No dependency on kibo, no dependency on
viper.** You can use dsm for spec-only purposes — sharing a typed data
contract between teams — without ever generating code from it.

**kibo** — the code generator. Reads a dsm model plus a template, emits code.
Kibo itself is template-agnostic: the target language and runtime are
determined by the template you give it.

**kibo-template-viper** — a kibo template pack that targets the viper runtime
(Python via dsviper, or C++ Viper directly). Choose this template when your
generated code needs to run inside a viper-based application. Other kibo
templates can target other runtimes — kibo is not viper-specific.

**dsviper-tools** also belongs to the toolchain side: CLI utilities
(`dsm_util`) and GUI editors (`cdbe.py`, `dbe.py`) that operate on dsm models
and dsviper databases throughout the development lifecycle. A QML variant
(`dsviper-tools-qml`) provides Qt Quick versions of the same database
browsers.

## The runtime (execution side)

```
dsviper  →  dsviper-components  →  reference applications
```

**Goal.** Run a typed Python application with versioned, persistent data.

**dsviper** — the Python runtime. Strong-typed Python API over the Viper C++
engine. The foundation: type system, value system, commit DAG, database tier.
Distributed exclusively on PyPI (`pip install dsviper`) — not bundled in the
DevKit ZIP.

**dsviper-components** — reusable building blocks built on top of dsviper.
Consumed by applications. Comes in two parallel tracks: `dsviper-components`
(Qt Widgets) and `dsviper-components-qml` (Qt Quick / QML). Most of the
runtime stack mirrors this split.

**Reference applications.** Several applications exist as canonical "putting
it all together" exemplars — they exercise the *whole* ecosystem end-to-end
(DSM modeling, Kibo code generation, the viper template, dsviper-components,
the dsviper runtime). They are not products in their own right:

- `ge-py` — Graph Editor, PySide6 desktop app.
- `ge-qml` — three QML desktop apps (`dbe`, `cdbe`, `graph_editor`).
- `dsviper-blender` — Blender 4.x add-on bundling the dsviper runtime from
  PyPI.
- `web-cdbe` — Flask web application demonstrating a Commit Database Editor
  (HTML5, no JavaScript).

About **Viper** itself — the C++ engine behind dsviper — see [naming](naming.md).
Viper is not currently distributed standalone.

## Where the chains meet

The two chains converge at the **artifact**: the toolchain produces a typed
Python package (and optionally a database schema); the runtime consumes it.

A typical project flow:

1. Author a `model.dsm` describing your data model.
2. Run `kibo` with `kibo-template-viper` to emit a typed Python package.
3. Build an application that imports that package and uses dsviper at runtime.
4. Throughout, use `dsviper-tools` (`cdbe`, `dbe`, `dsm_util`) to inspect,
   validate, and manage databases.

For the visual 3-step pipeline framing (Describe → Generate → Use), see
[pipeline](pipeline.md).

## Dependency rules

The arrows go one way. A change at a lower level can ripple up; a change at a
higher level cannot ripple down. Documentation, code, and tests for each
component must respect the same direction.

| Component                              | Depends on                  | Must not assume          |
|----------------------------------------|-----------------------------|--------------------------|
| dsm                                    | —                           | kibo, viper, dsviper     |
| kibo                                   | dsm                         | viper, dsviper           |
| kibo-template-viper                    | kibo, viper / dsviper       | applications             |
| dsviper-tools (Widgets and QML)        | dsm, dsviper                | applications             |
| dsviper                                | Viper (C++ engine)          | applications, components |
| dsviper-components (Widgets and QML)   | dsviper                     | applications             |
| reference applications                 | dsviper, dsviper-components | —                        |

This table is the contract per-component documentation must respect: a `dsm`
page may not assume kibo is in the picture; a `kibo` page may assume dsm but
not viper; and so on.

## When you only need part of the chain

You do not have to adopt the whole stack. Common partial uses:

- **Just a data-model spec.** Share `.dsm` files between teams as a typed
  contract. No kibo, no viper involved.
- **Generated code for a non-viper runtime.** Use `kibo` with a different
  template; viper and dsviper are out of the picture.
- **Versioned data without code generation.** Use `dsviper`'s dynamic API
  directly, loading dsm definitions at runtime — no static package needed.
- **Inspect a database.** `dsviper-tools` (`cdbe`, `dbe`,
  `dsm_util`) work standalone against any compatible database, regardless of
  whether you authored its schema in dsm yourself.