Trinity CLI

Ternary Computing Framework — VSA, BitNet LLM Inference, Mathematical Research
φ² + 1/φ² = 3 — The Trinity Identity

Installation • Quick Start • Commands • Architecture • Docs

---

Trinity S³AI DNA

Trinity Identity

    φ² + 1/φ² = 3 = TRINITY

Three Strands

• Strand I: Mathematical Foundation — Sacred constants, formulas, VSA
• Strand II: Cognitive Architecture — Brain modules, observability
• Strand III: Language & Hardware Bridge — TRI-27, FPGA backends

Full Architecture

---

For Scientific Collaborators

TRINITY is a unified research framework connecting fundamental physics through a single mathematical identity: φ² + φ⁻² = 3. From this root, candidate formulas for gravitational constant G, consciousness threshold C, temporal perception t_present, and fermion generations N_gen are derived.

φ² + φ⁻² = 3 (ROOT)
    ↓
γ = φ⁻³ (TRUNK)
    ↓
├── G = π³γ²/φ     → 0.09% accuracy ✅
├── C = φ⁻¹        → consciousness threshold
├── t = φ⁻²        → 382 ms ✅
└── N_gen = 3      → exact identity ✅

NOT: "Box of separate formulas" YES: "Tree with one root, many branches"

Each branch produces testable predictions; some confirmed (G: 0.09%), some rejected (γ = φ⁻³), all reproducible via open-source code.

Resource	Description
Scientific Status 2026	Unified framework overview with 13-level hierarchy, evidence ladder, and honest assessment of rejected hypotheses
README for Scientists	Mathematical framework without marketing terminology
DELTA-001 Final Report	Why γ ≠ φ⁻³: Honest negative result on Barbero-Immirzi parameter
LISA Prediction Roadmap	12 testable predictions for gravitational wave observations (2035+)

Evidence Ladder:

• ✅ Smoking Guns (4): G (0.09%), N_gen = 3, t_present (382 ms), T_cycles (~97 min)
• ✅ Consistent (3): C, Ω_Λ, Ω_DM
• ❌ Rejected (3): γ = φ⁻³, α family fit, √(8/3) ≈ φ

Reproducibility: zig build tri && tri constants

---

What is Trinity?

Trinity is a ternary computing framework with:

• Vector Symbolic Architecture (VSA) for cognitive computing
• BitNet LLM inference on ordinary CPUs (no GPU required)
• Mathematical research connecting φ (golden ratio) to fundamental constants
• VIBEE compiler for generating Zig/Verilog from specifications
• DePIN network for distributed inference

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

Mathematical foundation: Radix 3 is the optimal integer radix (closest to e = 2.718). The golden ratio encodes this: φ² + 1/φ² = 3 (Trinity Identity).

---

Mathematical Framework

The core identity φ² + φ⁻² = 3 generates numerical values for 30+ fundamental constants:

Constant	Formula	Value	Error
m_p / m_e	6π⁵	1836.15	0.002%
α_s(M_Z)	4φ²/(9π²)	0.1181	0.005%
sin²θ_W	2π³e/729	0.231	0.009%
Jarlskog J	21γ⁵/(π²φ⁴e²)	3.04×10⁻⁵	0.003%
γ (LQG)	φ⁻³	0.23607	0.617%

where γ = φ⁻³ ≈ 0.23607 is derived from φ.

See docs/papers/README_FOR_SCIENTISTS.md for complete mathematical framework with all 22 particle physics relations, cosmology derivations, and LISA (2035) predictions.

---

Quantum-Neuroanatomical Model

Trinity S³AI integrates quantum computation principles with brain-inspired architecture through three literature-backed bridges.

Bridge 1: Cortical Microcolumns = Local Coherence Domains

Research shows cortical microcolumns form coherent domains protected by energy gaps from thermal perturbations. This maps directly to Trinity brain modules.

Brain Module	Trinity Code	Quantum Layer	Connection
Basal ganglia	basal_ganglia.zig	measure() → ψ collapse	Collapse threshold = φ⁻¹ ≈ 0.618
Reticular formation	reticular_formation.zig	coherence tracking	Frequency ratio via φ

Reference: Frontiers in Physics 2023 - Coherent domains in microcolumns

Bridge 2: φ in Brain Oscillations → φ in Architecture

Brain waves synchronize at golden ratio frequencies. α, β, γ rhythms are connected through φ ≈ 1.618.

• QuantumMetrics.coherence = φ-coherence: degree to which oscillations between brain modules follow golden frequency relationships
• SacredWaveFunction ψ(θ) amplitudes = resonant modes of architecture

Reference: LinkedIn: Golden Ratio in Brain Waves

Bridge 3: Qutrits → Ternary Neurons → Connectome

Qutrit neural networks show 35-40% training speedup vs qubit networks, due to richer data representation.

• Each ternary weight {-1, 0, +1} = collapsed qutrit (not metaphor)
• Connectome topology scales: larger brains have stronger modular structure

Reference: PMC: Qutrit Neural Networks

Mathematical Foundation

φ = (1 + √5) / 2 = 1.61803398874989482
φ² + 1/φ² = 3 = TRINITY

Implementation

• QuantumMetrics: src/brain/evolution_simulation.zig — 4 formal metrics
• SacredWaveFunction: src/quantum/sacred_wave.zig — Bayesian prior over 6.75M configs
• Quantum VSA: src/vsa/core.zig — qbind, qbundle, measure, similarity_quantum

References:

• [arXiv 2510.27091] — Prioritized Policy Optimization
• [arXiv 2106.05268] — VSA fundamentals
• [PMLR Deshwal23a] — Bayesian optimization for categorical spaces

---

Installation

Trinity v1.0.2 "HEARTBEAT" — Install via your preferred package manager:

Method	Command
npm	npm install -g @playra/tri
Homebrew	brew tap gHashTag/trinity && brew install trinity
AUR	yay -S trinity-cli
Docker	docker pull ghcr.io/ghashtag/trinity:latest

Verify Installation

tri --version
# Output: TRI CLI v1.0.2

tri constants
# Shows all constants (φ, π, e, μ, χ, σ, ε...)

---

Quick Start

30-Second Install

# Clone and build (requires Zig 0.15.x)
git clone https://github.com/gHashTag/trinity.git && cd trinity
zig build tri

# Run TRI CLI
./zig-out/bin/tri --help

Interactive REPL

./zig-out/bin/tri      # Start interactive mode
# Type any message, use /quit to exit

Generate Code

tri code "create a REST API server in Zig"

Fix Bugs

tri fix src/main.zig
tri explain src/vsa.zig
tri test src/vsa.zig

Mathematical Commands

tri constants          # Show φ, π, e, Lucas, Fibonacci
tri phi 10             # Compute φ^10
tri lucas 10           # Lucas L(10)
tri spiral 5           # φ-spiral coordinates

All Commands (203 total)

tri help               # Show all commands by category
tri help --search test # Search commands
tri help fix           # Detailed command help

Build from Source

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

Requires Zig 0.15.x.

---

FPGA — Autoregressive Ternary LLM

First autoregressive ternary language model on FPGA with fully open-source toolchain.

Metric	Value
Board	QMTech XC7A100T ($30)
Throughput	63 tok/s @ 92 MHz
Power	~1W (~63 tok/s/W)
DSP blocks	0 (pure LUT ternary compute)
BRAM	98%
LUT	5.8%
Toolchain	openXC7 (Yosys + nextpnr-xilinx + prjxray)
Tokens	16 autoregressive from seed

Architecture

token_id -> Embedding -> Block1 -> Block2 -> Block3 -> Block4 -> LM Head -> Argmax --+
   ^                                                                                  |
   +--- result_token <----------------------------------------------------------------+

All weights use 2-bit ternary encoding (01=+1, 10=-1, 00=0). Multiplication reduces to conditional add/subtract/nop — zero DSP48 blocks required.

Quick Start

cd fpga/openxc7-synth
make hslm_full_top.bit        # Synthesize
sudo ../tools/flash.sh hslm_full_top.bit  # Flash

Design Variants

Variant	Blocks	Bitstream
hslm_2block_top	2	hslm_2block_top.bit
hslm_3block_top	3	hslm_3block_top.bit
hslm_4block_top	4	hslm_4block_top.bit
hslm_full_top	4 + autoregressive FSM	hslm_full_top.bit

See Research Report for full technical details.

---

Docker Node

The Trinity CLI Docker image is published to GitHub Container Registry.

Image	ghcr.io/ghashtag/trinity:latest
Version	ghcr.io/ghashtag/trinity:1.0.2
Platforms	linux/amd64
Base	Alpine 3.19
Size	~8 MB
Dockerfile	deploy/Dockerfile.tri

Run

docker run -it --rm ghcr.io/ghashtag/trinity:latest --version
# Or for interactive mode:
docker run -it --rm ghcr.io/ghashtag/trinity:latest

---

$TRI Token

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

Property	Value
Token	$TRI (Trinity Token)
Contract	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 for full details.

---

Architecture

📘 See ARCHITECTURE.md for comprehensive system design.

Repo layout: Verilog snapshots live in hardware/rtl-root/; agents follow AGENTS.md. Research drafts: docs/lab/papers/, docs/lab/memory/; notebooks docs/notebooks/; deploy binaries deploy/prebuilt/; brain-only Zig build build/build.brain.zig.

Module Documentation

Domain	Docs	Status
Common	src/common/README.md	✅ Stable - Single source of truth for constants, protocol, errors
VSA	src/vsa/README.md	✅ Stable - Vector Symbolic Architecture (99.5% test pass)
UART/FPGA	fpga/openxc7-synth/UART_README.md	✅ v6.0 Current - FPGA communication protocol

Quick Reference

Module	Purpose
src/common/	Shared constants (φ, TRINITY), protocol definitions, unified errors
src/vsa/	Vector Symbolic Architecture: bind, unbind, bundle, similarity
src/vm.zig	Ternary Virtual Machine (stack-based bytecode)
src/needle/	Semantic search with Brute+SIMD backend (100% exact)
src/firebird/	BitNet LLM inference on CPU (20x memory efficiency)
fpga/openxc7-synth/	FPGA toolchain + UART host (v6 current, v5 legacy)
hardware/rtl-root/	Loose .v modules (historically in root); e.g. tri fpga build hardware/rtl-root/blink.v

Core VSA System

Module	Purpose
src/vsa.zig	Main VSA entry point (re-exports all submodules)
src/vsa/core.zig	Core operations: bind, unbind, bundle, similarity
src/vsa/10k_vsa.zig	10K-dimensional hypervectors
src/sdk.zig	High-level API (Hypervector, Codebook)

Needle Tier 3 — Semantic Search

Brute+SIMD — 100% Exact, Instant Build

Metric	Value
Build Time	0ms (instant, no training)
Search @ 5k	113ms (competitive)
Memory	~7.7KB
Accuracy	100% (exact)

Module	Purpose
src/needle/ann_brute_simd.zig	Brute+SIMD implementation
src/needle/ann_interface.zig	Unified ANN interface
src/needle/vsa.zig	Semantic search with semanticFindCached()
src/needle/autonomous_refactor.zig	AI-powered refactoring

Specs: specs/needle/ann_verdict.tri, specs/needle/ann_integration.tri

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:

# 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:

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

Kubernetes deployment:

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.

# 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 for full documentation.

---

TRI CLI

Single command for all Trinity features:

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
├── deploy/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
For Researchers	docs/papers/README_FOR_SCIENTISTS.md
Command Reference	docs/command_registry.md (auto-generated)
DePIN Overview	gHashTag.github.io/trinity/docs/depin
Quick Start	gHashTag.github.io/trinity/docs/depin/quickstart
Tokenomics	gHashTag.github.io/trinity/docs/depin/tokenomics
API Reference	gHashTag.github.io/trinity/docs/depin/api
Architecture	gHashTag.github.io/trinity/docs/depin/architecture
Research	gHashTag.github.io/trinity/docs/research
Website	gHashTag.github.io/trinity

---

Autonomous Development

Trinity includes built-in autonomous agents for sustained development, optimization, and code generation.

Built-in Agents

Binary	Purpose
ralph-agent	Sleep-wake daemon, picks GitHub issues
ralph-hook	Hook events → Telegram notifications
tri-api	Standalone agentic loop (Claude Code replacement)
tri-bot	Telegram bot with SSE streaming

Quick Start

# Build all agents
zig build

# Run Ralph agent
./zig-out/bin/ralph-agent --help

# Run tri-api (interactive agentic loop)
./zig-out/bin/tri-api

# Run Telegram bot
./zig-out/bin/tri-bot

Agent Workflow

1. Define: Edit or create a specification in specs/tri/*.tri
2. Plan: Update .ralph/fix_plan.md with your next objective
3. Run: Execute tri agent run <issue-number> for autonomous issue resolution
4. Verify: Agent generates code, runs tests, and checks performance
5. Commit: Upon success, agent updates .ralph/SUCCESS_HISTORY.md

For detailed protocols, see .ralph/RULES.md and docs/docs/development/ralph.md.

---

Build Commands

zig build                    # Build all 50+ binaries
zig build tri                # Unified TRI CLI (32 MB)
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 build libvsa             # Build libtrinity-vsa C API
zig build libqueen           # Build libtrinity-queen C API
zig fmt src/                 # Format code

---

Contributing

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

See CONTRIBUTING.md for guidelines.

---

Maintainer

Dmitrii Vasilev (@gHashTag)

Attribution for listed docs and packages is checked by src/tri/author_attribution_guard.zig and tools/config/author_attribution_guard.manifest. Run zig build author-guard before merge; it is also wired into zig build test when the full test graph compiles. Do not remove or bypass without maintainer approval.

---

License

MIT -- see LICENSE

---

Download v1.0.2 "HEARTBEAT" • Dashboard • Documentation

φ² + 1/φ² = 3 = TRINITY
v1.0.2 HEARTBEAT — 3 March 2026