File size: 4,484 Bytes
8ef3a6b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | ---
icon: lucide/rocket
description: Install iscc-sct, generate your first Semantic Text-Code, and match a translation across languages.
---
# Getting started
Install `iscc-sct`, generate your first Semantic Text-Code, and watch two languages produce
near-identical codes.
## Prerequisites
- Python 3.10 or later
- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
## Install
`iscc-sct` needs an ONNX runtime, selected through an install extra. The `cpu` extra works
everywhere:
=== "uv"
```bash
uv add "iscc-sct[cpu]"
```
=== "pip"
```bash
pip install "iscc-sct[cpu]"
```
!!! warning "Choose exactly one runtime"
Install the `cpu` extra, or the `gpu` extra for NVIDIA CUDA acceleration — never both. The
`onnxruntime` and `onnxruntime-gpu` packages unpack into the same directory and overwrite each
other. A plain `pip install iscc-sct` installs no runtime, and the first code generation then fails
with install instructions. If you are unsure which extra fits your machine, run `iscc-sct doctor`
(see the [command-line guide](../howto/command-line.md)).
### Verify the installation
```python
import iscc_sct
print(iscc_sct.__version__)
```
## Generate your first code
Pass any text to `create()`. The first call downloads the embedding model (about 450 MB) to your
user data directory; later calls reuse it.
```python
import iscc_sct as sct
text = "This is some sample text. It can be a longer document or even an entire book."
print(sct.create(text, bits=256).iscc)
# ISCC:CADV3GG6JH3XEVRNSVYGCLJ7AAV3BOT5J7EHEZKPFXEGRJ2CTWACGZI
```
The `bits` argument sets the code length. Longer codes carry more detail; 64 bits is the library
default, and 256 bits is the most precise. See [comparing texts](../howto/compare-texts.md) for how
length affects matching.
## Match a translation
The point of a Semantic Text-Code is that meaning survives translation. Generate codes for the same
passage in English and German, then measure their distance:
```python
import iscc_sct as sct
english = (
"An ISCC applies to a specific digital asset and is a data-descriptor deterministically "
"constructed from multiple hash digests using the algorithms and rules in this document. "
"This document does not provide information on registration of ISCCs."
)
german = (
"Ein ISCC bezieht sich auf ein bestimmtes digitales Gut und ist ein Daten-Deskriptor, der "
"deterministisch aus mehreren Hash-Digests unter Verwendung der Algorithmen und Regeln in "
"diesem Dokument erstellt wird. Dieses Dokument enthält keine Informationen über die "
"Registrierung von ISCCs."
)
a = sct.create(english)
b = sct.create(german)
print(sct.iscc_distance(a.iscc, b.iscc))
# 3
```
A distance of `3` bits out of 64 means the translation is a near-match. For contrast, an unrelated
sentence lands far away:
```python
import iscc_sct as sct
unrelated = (
"The recipe calls for two cups of flour, a pinch of salt, and three ripe bananas mashed "
"until smooth before folding the mixture into the buttered baking tin."
)
print(sct.iscc_distance(a.iscc, sct.create(unrelated).iscc))
# 33
```
Low distance means similar meaning; high distance means unrelated content. Translation matching is
the behavior that lexical (word-based) codes cannot provide.
## Look inside the text
Set `granular=True` to get per-chunk features alongside the document code. Each chunk carries its
own offset, size, similarity-preserving fingerprint (simprint), and text:
```python
import iscc_sct as sct
text = "This is some sample text. It can be a longer document or even an entire book."
meta = sct.create(text, bits=256, granular=True)
feature = meta.features[0].simprints[0]
print(feature.offset, feature.size, feature.simprint)
# 0 77 XZjeSfdyVi0
```
Granular features let you match individual passages across documents, even when the surrounding text
differs. The [granular features guide](../howto/granular-features.md) covers chunk-level matching
and content reconstruction.
## Next steps
- **[Compare texts](../howto/compare-texts.md)** — Measure semantic and cross-lingual similarity.
- **[Granular features](../howto/granular-features.md)** — Work with per-chunk simprints and
offsets.
- **[Configuration](../howto/configuration.md)** — Tune bit-length, chunking, and output options.
- **[How it works](../explanation/how-it-works.md)** — Understand why the codes match across
languages.
|