npm package: @playra/tri
Description: Trinity v1.0.1 PURITY — Sacred Intelligence CLI
Author: Trinity Network
Latest version: 1.0.1

<p align="center">
  <img src="https://img.shields.io/badge/Trinity-Network-6366F1?style=for-the-badge" alt="Trinity Network">
</p>

<h1 align="center">Trinity Network</h1>

<p align="center">
  <strong>Decentralized Ternary AI Inference + Sacred Computing</strong><br>
  Run LLMs on your CPU. Earn $TRI tokens. No GPU required.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/KOSCHEI-v7.0.0-FFD700?style=for-the-badge" alt="KOSCHEI AWAKENS v7.0">
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> &bull;
  <a href="#-docker-node">Docker Node</a> &bull;
  <a href="#-tri-token">$TRI Token</a> &bull;
  <a href="#-architecture">Architecture</a> &bull;
  <a href="#-cli">CLI</a> &bull;
  <a href="#-documentation">Docs</a>
</p>

<p align="center">
  <a href="https://github.com/gHashTag/trinity/actions"><img src="https://img.shields.io/github/actions/workflow/status/gHashTag/trinity/docker-node.yml?label=Docker%20Build&style=flat-square" alt="Docker Build"></a>
  <a href="https://ghcr.io/ghashtag/trinity-node"><img src="https://img.shields.io/badge/GHCR-trinity--node-blue?style=flat-square&logo=docker" alt="GHCR"></a>
  <a href="https://sepolia.etherscan.io/address/0xef368e29FA3aB2eaf02BccD05438ED3bafE9f469"><img src="https://img.shields.io/badge/$TRI-Sepolia-green?style=flat-square&logo=ethereum" alt="$TRI Sepolia"></a>
  <img src="https://img.shields.io/badge/Zig-0.15.x-F7A41D?style=flat-square&logo=zig" alt="Zig 0.15.x">
  <img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="MIT License">
</p>

---

## What is Trinity?

Trinity is a **DePIN (Decentralized Physical Infrastructure Network)** for ternary AI inference and sacred computing. It uses balanced ternary arithmetic {-1, 0, +1} to run LLM inference on ordinary CPUs -- no GPU required.

### 🆕 KOSCHEI AWAKENS v7.0 — Sacred Computing Platform

**Cycle 110 Public Release — February 28, 2026**

KOSCHEI AWAKENS is the world's first sacred computing virtual machine with:

- **41 Sacred Opcodes** (0x80-0xFF) for mathematics, chemistry, and physics
- **Ternary Computing** {-1, 0, +1} with 1.58 bits/trit information density
- **Proven 603x Formula**: 7x (JIT) × 3x (AVX2) × 20x (Tables) × 1.4x (Large) = 588x
- **Production-Ready VM** available today

**Learn more:**
- [Investor Deck v1.0](docs/investor-deck-v1.0.md)
- [Sacred v7.0 Architecture](docs/sacred-v7.0.md)
- [Cycle 110 Announcements](docs/announcements/CYCLE110_PUBLIC.md)

**Why ternary?**

| | Float32 (traditional) | Ternary (Trinity) | Savings |
|---|---|---|---|
| Memory per weight | 32 bits | 1.58 bits | **20x** |
| Compute | Multiply + Add | Add only | **10x** |
| 70B model RAM | 280 GB | 14 GB | **20x** |

The mathematical foundation: **radix 3 is the optimal integer radix** (closest to *e* = 2.718). The golden ratio encodes this: **phi^2 + 1/phi^2 = 3** (Trinity Identity).

---

## Quick Start

### Docker (recommended)

```bash
docker pull ghcr.io/ghashtag/trinity-node:latest

docker run -d --name trinity-node \
  -p 8080:8080 -p 9090:9090 -p 9333:9333/udp -p 9334:9334 \
  -v ~/.trinity:/data \
  ghcr.io/ghashtag/trinity-node:latest
```

Check health:

```bash
curl http://localhost:8080/health
# {"status":"ok","model":"loaded"}
```

### Build from source

```bash
git clone https://github.com/gHashTag/trinity.git
cd trinity
zig build              # Build all targets
zig build tri          # Build the unified TRI CLI
zig build test         # Run all tests
```

Requires **Zig 0.15.x**.

---

## Docker Node

The Trinity node Docker image is published to GitHub Container Registry on every push to `main`.

| | |
|---|---|
| **Image** | `ghcr.io/ghashtag/trinity-node:latest` |
| **Platforms** | linux/amd64, linux/arm64 |
| **Base** | Alpine 3.19 |
| **Size** | ~15 MB |
| **Dockerfile** | [`deploy/Dockerfile.node`](deploy/Dockerfile.node) |

### Ports

| Port | Protocol | Purpose |
|------|----------|---------|
| 8080 | TCP | HTTP API (REST, OpenAI-compatible) |
| 9090 | TCP | Prometheus metrics |
| 9333 | UDP | Peer discovery |
| 9334 | TCP | Job distribution |

### Data volume

Mount `-v ~/.trinity:/data` to persist wallet, shards, and config across restarts.

### Stop / Restart

```bash
docker stop trinity-node     # Stop
docker start trinity-node    # Restart (keeps data)
docker rm trinity-node       # Remove container (data persists in ~/.trinity)
```

---

## $TRI Token

$TRI is deployed on **Ethereum Sepolia testnet**. Mainnet deployment is planned.

| Property | Value |
|----------|-------|
| **Token** | $TRI (Trinity Token) |
| **Contract** | [`0xef368e29FA3aB2eaf02BccD05438ED3bafE9f469`](https://sepolia.etherscan.io/address/0xef368e29FA3aB2eaf02BccD05438ED3bafE9f469) |
| **Network** | Ethereum Sepolia |
| **Total Supply** | 10,460,353,203 (3^21) |
| **Decimals** | 18 |
| **Standard** | ERC-20 + ERC-20Permit |

### Allocation

| Category | % | Amount | Purpose |
|----------|---|--------|---------|
| **Node Rewards** | 40% | 4,184,141,281 | Emitted to operators for useful work |
| **Founder** | 20% | 2,092,070,640 | Core team, 12-month cliff + 48-month vesting |
| **Community** | 20% | 2,092,070,640 | Grants, bounties, ecosystem growth |
| **Treasury** | 10% | 1,046,035,320 | Protocol development |
| **Liquidity** | 10% | 1,046,035,320 | DEX pools, available at TGE |

### Staking Tiers

Your staked $TRI determines your API tier. No API keys -- your wallet is your identity.

| Tier | Staked $TRI | Rate Limit | Reward Multiplier |
|------|------------|------------|-------------------|
| **Free** | 0 | 10 req/min | 1.0x |
| **Staker** | 100+ | 60 req/min | 1.5x |
| **Power** | 1,000+ | 300 req/min | 2.0x |
| **Whale** | 10,000+ | Unlimited | 3.0x |

Include `X-Wallet: 0xYOUR_ADDRESS` in HTTP headers. See [Tokenomics docs](https://gHashTag.github.io/trinity/docs/depin/tokenomics) for full details.

---

## Architecture

### Core VSA System

| Module | Purpose |
|--------|---------|
| `src/vsa.zig` | Vector Symbolic Architecture: bind, unbind, bundle, similarity |
| `src/vm.zig` | Ternary Virtual Machine (stack-based bytecode) |
| `src/hybrid.zig` | HybridBigInt: packed 1.58 bits/trit with unpacked cache |
| `src/packed_trit.zig` | Bit-packed ternary encoding |
| `src/sdk.zig` | High-level API (Hypervector, Codebook) |

### DePIN Node

| Module | Purpose |
|--------|---------|
| `src/firebird/depin.zig` | DePIN reward engine, Proof-of-Useful-Work |
| `src/trinity_node/http_api.zig` | REST API with stake-based tiers |
| `src/trinity_node/token_staking.zig` | Staking engine, slashing |
| `src/trinity_node/config.zig` | Network config, contract addresses |

### Firebird LLM Engine

| Module | Purpose |
|--------|---------|
| `src/firebird/cli.zig` | LLM command-line interface |
| `src/firebird/b2t_integration.zig` | BitNet-to-Ternary conversion |
| `src/firebird/wasm_parser.zig` | WebAssembly module loading |

### VIBEE Compiler

| Module | Purpose |
|--------|---------|
| `src/vibeec/vibee_parser.zig` | Parse .vibee specifications |
| `src/vibeec/zig_codegen.zig` | Generate Zig code from specs |
| `src/vibeec/verilog_codegen.zig` | Generate Verilog for FPGA |
| `src/vibeec/runtime_swarm.zig` | Production swarm runtime (32 agents) |

### Production Swarm (v8)

**One-command 32-agent Trinity cluster:**

```bash
# Run demo
./demo/v8_production_swarm.sh

# Or directly
zig build vibee -- gen specs/tri/vsa_swarm_production_32.vibee
zig build swarm
./zig-out/bin/swarm-runtime
```

**Features:**
- 32 agents with phi-spiral consensus (φ² + 1/φ² = 3)
- Self-healing with auto-recovery
- Prometheus metrics on `:9090`
- Self-improvement cycle (analyzes & regenerates patterns)

**Docker deployment:**

```bash
cd deploy && docker compose up -d
# Prometheus: :9091, Grafana: :3000
```

**Kubernetes deployment:**

```bash
kubectl apply -f deploy/k8s/
kubectl port-forward svc/trinity-swarm-metrics 9090:9090
```

---

## HTTP API

The node exposes an OpenAI-compatible API on port 8080.

```bash
# Chat completion
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Wallet: 0xYOUR_WALLET" \
  -d '{"model":"trinity-llm","messages":[{"role":"user","content":"Hello"}]}'

# Node stats
curl http://localhost:8080/v1/node/stats

# Storage
curl -X POST http://localhost:8080/v1/storage/put \
  -H "Content-Type: application/octet-stream" \
  --data-binary @myfile.bin

# Prometheus metrics
curl http://localhost:9090/metrics
```

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| GET | `/` | Server info and metrics |
| POST | `/v1/chat/completions` | Chat completion (OpenAI-compatible) |
| GET | `/v1/node/stats` | Node statistics and earnings |
| GET | `/v1/node/tier` | Current wallet tier info |
| POST | `/v1/node/claim` | Claim pending $TRI rewards |
| POST | `/v1/storage/put` | Store a data shard |
| GET | `/v1/storage/get/:hash` | Retrieve a data shard |
| GET | `/v1/storage/status` | Storage layer status |
| GET | `/metrics` | Prometheus metrics (port 9090) |

See [API Reference](https://gHashTag.github.io/trinity/docs/depin/api) for full documentation.

---

## TRI CLI

Single command for all Trinity features:

```bash
zig build tri

# Available commands
tri                    # Interactive REPL
tri code fibonacci     # Generate code
tri chat "hello"       # Chat
tri explain <file>     # Explain code
tri fix <file>         # Fix bugs
tri test <file>        # Generate tests
tri help               # Full help
```

Multilingual: Russian, English, Chinese -- auto-detected.

---

## DePIN Reward System

Nodes earn $TRI through **Proof-of-Useful-Work** -- every rewarded computation produces a real, verifiable result.

| Operation | Rate | Description |
|-----------|------|-------------|
| VSA Evolution | 0.001 TRI/generation | Evolving hypervector populations |
| Navigation | 0.0001 TRI/step | Navigating semantic vector spaces |
| WASM Conversion | 0.01 TRI/conversion | Compiling WASM to ternary bytecode |
| Benchmark | 0.005 TRI/run | Running reproducible benchmarks |
| Storage Hosting | 0.00005 TRI/shard/hour | Hosting data shards |
| Storage Retrieval | 0.0005 TRI/retrieval | Serving requested data |

Bonus multipliers: fitness > 0.9 grants +50%, similarity > 0.8 grants +100%, staking 100+ TRI grants 1.5x on all earnings.

---

## Project Structure

```
trinity/
├── src/                    # Core Zig source
│   ├── vsa.zig             # Vector Symbolic Architecture
│   ├── vm.zig              # Ternary Virtual Machine
│   ├── hybrid.zig          # HybridBigInt (1.58 bits/trit)
│   ├── trinity_node/       # DePIN node (HTTP API, staking, config)
│   ├── firebird/           # LLM engine + DePIN rewards
│   ├── vibeec/             # VIBEE compiler + IGLA agent
│   ├── b2t/                # BitNet inference
│   ├── phi-engine/         # Quantum-inspired computation
│   └── tvc/                # Ternary Vector Computing
├── deploy/                 # Docker configs
│   └── Dockerfile.node     # Multi-stage Alpine build
├── contracts/              # Solidity (TrinityToken.sol)
├── specs/                  # .vibee specifications
├── docsite/                # Documentation site (Docusaurus)
├── website/                # Landing page (Vite + React)
├── libs/                   # Multi-language VSA libraries
└── build.zig               # Build system
```

---

## Documentation

| Resource | URL |
|----------|-----|
| **DePIN Overview** | [gHashTag.github.io/trinity/docs/depin](https://gHashTag.github.io/trinity/docs/depin) |
| **Quick Start** | [gHashTag.github.io/trinity/docs/depin/quickstart](https://gHashTag.github.io/trinity/docs/depin/quickstart) |
| **Tokenomics** | [gHashTag.github.io/trinity/docs/depin/tokenomics](https://gHashTag.github.io/trinity/docs/depin/tokenomics) |
| **API Reference** | [gHashTag.github.io/trinity/docs/depin/api](https://gHashTag.github.io/trinity/docs/depin/api) |
| **Architecture** | [gHashTag.github.io/trinity/docs/depin/architecture](https://gHashTag.github.io/trinity/docs/depin/architecture) |
| **Rewards** | [gHashTag.github.io/trinity/docs/depin/rewards](https://gHashTag.github.io/trinity/docs/depin/rewards) |
| **Research** | [gHashTag.github.io/trinity/docs/research](https://gHashTag.github.io/trinity/docs/research) |
| **Website** | [gHashTag.github.io/trinity](https://gHashTag.github.io/trinity) |

---

## 🤖 Autonomous Development (Ralph)

Trinity uses the **Ralph Loop** for sustained autonomous development, optimization, and code generation. 

> [!TIP]
> **🐣 New to Ralph?** Read our [Beginner's Guide to Ralph](.ralph/README.md) to understand how to add tasks and use the autonomous workflow effectively.

### Installation
To use Ralph, you must first install it globally:

```bash
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh
```

### Quick Start
Navigate to the Trinity root and run:

```bash
ralph --monitor        # Recommended: Start Ralph with live monitor in tmux
```

### Custom Autonomy Tools
We've integrated specialized scripts in the `.ralph/` directory to ensure high-fidelity work:

| Script | Purpose |
|--------|---------|
| `.ralph/gate.sh` | **Quality Gate**: build + test + format + branch safety. |
| `.ralph/bench.sh` | **Performance Guard**: Prevents latency/throughput regressions. |
| `.ralph/sync_tree.sh` | **Tech Tree Sync**: Updates `TECH_TREE.md` from VIBEE specs. |
| `.ralph/audit.sh` | **Health Audit**: Checks modularity and unresolved markers. |

### Workflow (The Golden Chain)
1.  **Define**: Edit or create a specification in `specs/tri/*.vibee`.
2.  **Plan**: Update `.ralph/fix_plan.md` with your next objective and acceptance criteria.
3.  **Run**: Execute `ralph --monitor`. 
4.  **Verify**: Ralph will automatically generate code, run tests, and check performance via the quality gates.
5.  **Commit**: Upon success, Ralph updates `.ralph/SUCCESS_HISTORY.md` and proposes next Tech Tree nodes.

For detailed development protocols and constraints, see **[.ralph/RULES.md](.ralph/RULES.md)**.

---

## Build Commands

```bash
zig build                    # Build all targets
zig build tri                # Unified TRI CLI
zig build test               # Run ALL tests
zig build bench              # Run benchmarks
zig build release            # Cross-platform release builds
zig build vibee              # VIBEE Compiler CLI
zig build firebird           # Firebird LLM CLI
zig fmt src/                 # Format code
```

---

## Contributing

```bash
git clone https://github.com/gHashTag/trinity.git
cd trinity
zig build test               # Run all tests before submitting PRs
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT -- see [LICENSE](LICENSE)

---

<p align="center">
  <code>phi^2 + 1/phi^2 = 3 = Trinity</code><br>
  <code>3^21 = 10,460,353,203 $TRI</code>
</p>