Metadata-Version: 2.4
Name: velthari
Version: 1.0.0
Summary: The Undetectable Language — a constructed cipher with Python API
License: Proprietary
Keywords: cipher,steganography,encoding,constructed-language
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Cython
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Dynamic: requires-python

# Velthari

**The Undetectable Language** — a constructed cipher with a Python API that is 100% cross-compatible with the Velthari HTML browser tool.

A message encoded in Python decodes correctly in the HTML interface, and vice versa.

---

## Installation

```bash
pip install velthari
```

The package ships as a compiled binary (Cython extension). No source code is distributed.

---

## Usage

### Basic encode / decode

```python
import velthari

encoded = velthari.encode("meet at dawn")
# → 'ⲂⲟⲜⲑ ∴ ⲝⲓ ∴ ⲇ⨹ⲝⲆⲋ ⊕'

decoded = velthari.decode(encoded)
# → 'meet at dawn'
```

### Password locking

```python
locked = velthari.encode("secret message", password="mykey")
velthari.decode(locked, password="mykey")  # → 'secret message'
velthari.decode(locked, password="wrongkey")  # → garbled output, no error
```

### Multi-layer encoding

```python
# Encode with 3 layers — output is prefixed with ❰3❱
deep = velthari.encode("secret", layers=3)
# → '❰3❱ⲒⲟⲐⲀⲞ...'

# decode() auto-detects layer count from the ❰N❱ prefix
velthari.decode(deep)  # → 'secret'

# Or specify explicitly
velthari.decode(deep, layers=3)
```

### Steganography

Hide a secret message inside natural-looking cover text. The Velthari payload
is embedded as invisible zero-width Unicode characters — completely undetectable
to any reader or AI system.

```python
# With a Groq API key (free at console.groq.com) — generates AI cover text
cover = velthari.hide(
    "secret message",
    cover_topic="the weather",
    groq_api_key="gsk_..."
)

# Extract and decode
plaintext = velthari.extract(cover)
# → 'secret message'
```

### Combining features

```python
# Password-locked + multi-layer
locked_deep = velthari.encode("eyes only", password="atlas", layers=2)
velthari.decode(locked_deep, password="atlas")  # → 'eyes only'
```

---

## Cross-compatibility

The Velthari HTML interface and this Python package share the **exact same cipher engine**:

- Same 52 Coptic Unicode glyph set
- Same positional Fisher-Yates permutation with LCG seed
- Same Fibonacci vowel shifting
- Same null glyph injection every 7th character
- Same SHA-256 password hashing scheme
- Same base-26 inter-layer serialization with `❰N❱` prefix

A message encoded in the HTML tool will decode with `velthari.decode()` and vice versa.

---

## How the cipher works (overview)

Velthari maps English letters to Coptic Unicode glyphs through a position- and word-index-dependent permutation. Each letter's glyph depends on:

- Its position within the word
- The word's index in the sentence
- How many vowels appeared before it (for vowel encoding)

This means the same letter maps to different glyphs in different positions, making frequency analysis ineffective. The output is visually indistinguishable from actual Coptic script to any observer or linguistic database.

---

## Security

The compiled extension (`.so` / `.pyd`) is machine code. The algorithm, glyph set, permutation seed formula, and all internal constants are not visible in the distributed package. Users interact with `encode()` and `decode()` as a black box.

---

## License

Proprietary. All rights reserved.
