Metadata-Version: 2.4
Name: seraph-db
Version: 0.2.8
Summary: SERAPH — deterministic semantic-geometry memory substrate (engine + licensing CLI)
Author-email: Tree D Interactive LLC <contact@tree-d-interactive.net>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://www.seraph-db.com
Project-URL: Source, https://github.com/Tree-D-Interactive-LLC/seraph
Keywords: semantic-memory,agent-memory,provenance,vector-database,mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Dynamic: license-file

# SERAPH

**A geometric substrate for structured knowledge.**

SERAPH is a storage and retrieval engine that organizes content through emergent geometric structure rather than explicit schemas. It provides cryptographic provenance, semantic search, and chain-of-custody guarantees from genesis to tip.

---

## Install

```bash
pip install seraph-db
```

The wheel includes the full engine with GPU-accelerated encoding (candle + CUDA). It installs and runs everywhere, falling back to CPU when the GPU cannot be used — whether there is no NVIDIA card, no CUDA toolkit, or an unsupported driver. GPU acceleration additionally needs an NVIDIA GPU of compute capability 7.0 or newer plus the CUDA runtime libraries (`cudart`, `cublas`, `curand`); the driver alone is not sufficient. For maximum encoder throughput, see [`seraph-db-onnx`](https://pypi.org/project/seraph-db-onnx/).

## Quick Start

### 1. Activate Your License

A license is required before the engine will accept operations:

```bash
# Browser-based (opens your default browser)
seraph license activate

# Headless (email verification with 6-digit code)
seraph license activate --email you@company.com
```

### 2. Verify

```bash
seraph license status
```

### 3. Use

```python
import seraph

cfg = seraph.StoreConfig(model_id="BAAI/bge-small-en-v1.5")
store = seraph.SeraphStore.create("my_store.sfg", cfg)

text = "The quick brown fox jumps over the lazy dog."
store.put(text.encode(), store.encode(text))    # content bytes + embedding

for hit in store.search_text("fast animal"):     # text query, encodes internally
    print(f"{hit.score:.3f}  {hit.snippet}")

store.close()
```

---

## What's Included

The `seraph-db` wheel contains:

| Component | Description |
|-----------|-------------|
| `seraph` Python module | Compiled Rust extension (PyO3) with GPU-accelerated encoder |
| `seraph` CLI | License management and store utilities |

The CLI is installed as a console entry point — run `seraph --help` after install.

## Variants

| Package | Backend | Best for |
|---------|---------|----------|
| **`seraph-db`** (this package) | candle + CUDA (CPU fallback) | Universal — GPU when available, CPU otherwise |
| [`seraph-db-onnx`](https://pypi.org/project/seraph-db-onnx/) | ONNX Runtime CUDA EP | Maximum encoder throughput (~3x faster) |

All variants expose the same API. Platform-specific archives with bundled runtimes are also available from [GitHub Releases](https://github.com/Tree-D-Interactive-LLC/seraph/releases).

## API Reference

Full API documentation:

- [Python API Reference](https://github.com/Tree-D-Interactive-LLC/seraph/blob/main/PYTHON_API.md)
- [C FFI API Reference](https://github.com/Tree-D-Interactive-LLC/seraph/blob/main/FFI_API.md)
- [Product overview](https://seraph-db.com)
- [API Reference](https://seraph-db.com/docs)

---

## CLI Reference

```
seraph license activate              Activate a free license (opens browser)
seraph license activate --email E    Headless activation via email verification
seraph license install [path]        Install a license file
seraph license status                Show current license details
```

---

## Licensing

SERAPH is proprietary software licensed by [Tree D Interactive LLC](https://tree-d-interactive.net).

| Tier | Eligibility | Fee | Scope |
|------|------------|-----|-------|
| **Free** | Annual revenue under $500K | $0 | Development, evaluation, prototyping, non-commercial research. No production deployment. |
| **Commercial** | Annual revenue $500K+ | $10,000/year | Production deployment on your own infrastructure. No multi-tenant SaaS, white-label, or redistribution. |
| **Enterprise** | Multi-tenant SaaS, embedded redistribution, third-party deployment | [Contact us](mailto:licensing@tree-d-interactive.net) | Per Order Form. |

See the [License Agreement](https://www.seraph-db.com/license-agreement) and [Pricing Schedule](https://www.seraph-db.com/pricing) for full terms.

For licensing inquiries: **licensing@tree-d-interactive.net**

---

## Support

- **Free & Commercial:** GitHub Issues on this repository
- **Enterprise:** Direct support channel per agreement

---

Copyright (c) 2025-2026 Tree D Interactive LLC. All rights reserved.
