Hero Models

Hero is a digital assistant — a personal AI assistant. This repository defines the models and serialization formats used by Hero.

Rather than using different database structures for various technology choices, this project standardizes on a unified set of models with deterministic serialization.

Core Principles

• Data is stored in any Redis-compatible database
• All models use canonical, deterministic formats
• Two serialization modes: human-readable (otoml) and binary-efficient (obin)
• All identifiers use SmartID (sid) for human-readable, collision-free uniqueness

Serialization

Hero Models support two serialization formats, following the o.... naming convention:

otoml — Human-Readable Format

otoml is a strict canonicalization discipline on top of standard TOML v1.0.

Key properties:

• Deterministic: Same data always produces identical bytes
• Self-describing: All meaning is explicit via keys
• AI-safe: Stable under round-trips, no ambiguity
• Human-readable: Easy to inspect and edit

Rules:

• All keys are lowercase snake_case, sorted alphabetically
• Structured sub-objects use inline tables: spec = { bus = "sxm", mem = 80 }
• Lists of objects use arrays of tables: [[item]]
• Time format: "YYYY-MM-DD HH:MM:SS" (string, not TOML datetime)
• IDs are always SmartID (sid)

[[gpu]]
id = "019234ab-7def-7000-8000-000000000001"
perf = { tps_128k = 120, tps_8k = 950 }
spec = { bus = "sxm", gen = "ampere", mem = 80, pwr = 400 }

obin — Binary Format

obin is a compact binary serialization for wire efficiency and storage optimization.

Key properties:

• Minimal size: Optimized for network transmission and storage
• Fast parsing: No text parsing overhead
• Deterministic: Canonical binary representation
• Type-preserving: Maintains full type information

Both formats are semantically equivalent — data can round-trip between otoml and obin without loss.

Serialization API

dump_otoml(model) -> String    # Serialize to otoml text format
dump_obin(model)  -> Bytes     # Serialize to obin binary format
load_otoml(text)  -> Model     # Deserialize from otoml text
load_obin(bytes)  -> Model     # Deserialize from obin binary

Use otoml for:

• Configuration files
• Human inspection and editing
• Debugging and logging
• Version control diffs

Use obin for:

• Network transmission
• Database storage
• High-performance scenarios
• Space-constrained environments

Primitive Types

Hero Models define canonical primitive types that work consistently across both serialization formats:

otime — Deterministic Time

• Binary: u32 (seconds since Unix epoch)
• Text: "YYYY-MM-DD HH:MM:SS" (UTC, no timezone)
• Range: 1970 – 2106
• Precision: seconds

2025-01-03 14:22:59

ocur — Lossless Currency

• Binary: [string, u64]
• Text: ["usdc", 1250000]
• Amount in micro-units (1/1,000,000)
• Asset codes: lowercase, 1-5 chars

["usdc", 1250000]   # = 1.25 USDC
["btc", 100000000]  # = 100 BTC

olocation — Geographic Position

• Binary: [i32, i32, u16] — 10 bytes
• Text: (lat,lon,radius)
• Coordinates in micro-degrees
• Radius in meters (uncertainty)

(47.376887,8.541694,1000)   # Zurich, 1km radius

oipaddress — Canonical IP Address

• Binary: [u8, u8[16]] — 17 bytes
• Text: dotted-decimal (IPv4) or RFC 5952 (IPv6)
• Supports IPv4 and IPv6
• No ports, no CIDR, no zones

192.168.1.1
2001:db8::1

Redis Storage

Models are stored in Redis with the following key structure:

${collection}:${type}:${name}_${sid}.toml

• Collection: Group of related items (namefixed)
• Type: Model type/structure
• ID: name_sid or just sid
• Value: otoml serialized content

Namefixed means: lowercase, snake_case, ASCII only, no special characters.

Directory Structure

specs/
  intro.md           # Project introduction
  redis_storage.md   # Redis key structure
  types/
    ocur_otime.md    # Time and currency primitives
    olocation.md     # Geographic location type
    oipaddress.md    # IP address type
    readme.md        # Types overview
  models/            # Model definitions

Design Philosophy

1. Exactly one representation — Same data produces identical bytes
2. All meaning is explicit — No positional interpretation
3. Integer-safe — No floating-point for money or coordinates
4. Honest precision — Explicit uncertainty (radius, time precision)
5. Language-agnostic — Works across Rust, Python, TypeScript, etc.