Skip to main content
syni-spec is the single source of truth for how Syni behaves across every platform and environment. It defines what Syni is allowed to do, how it is allowed to behave, what it must never do, and what it must always guarantee. Every Syni SDK (Dart, Swift, Kotlin) and the Syni Cloud Gateway conforms to this spec.
If it’s in syni-spec, it is a contract. If it’s not here, it is an implementation detail.

​
What syni-spec is

  • a behavioral contract, not an implementation
  • a versioned, immutable spec — released artifacts are append-only, never edited in place
  • the canonical source of personas, schemas, grammars, safety rules, and budgets consumed by every Syni SDK
  • distributed as signed, pinned artifacts via dist.synheart.ai

​
What syni-spec is not

  • not an SDK
  • not a runtime
  • not a place for feature flags, dynamic configuration, or anything that executes code

​
What you get on disk

After running synheart install spec, the spec payload lands under your project’s synheart/vendor/syni-spec/ tree: 
syni-spec/
├── VERSION
├── LICENSE
├── schemas/        # JSON Schemas for outputs and persona meta-schemas
├── personas/       # core / research / prod persona definitions
├── grammars/       # GBNF grammars bound to output schemas
├── rules/          # behavior rules referenced by personas
├── safety/         # global safety policies
├── budgets/        # per-persona resource budgets
├── registries/     # canonical id → file mappings
├── compatibility/  # version compatibility matrices
└── prompts/        # persona prompt fragments
Paths inside the payload are identical across language ecosystems — a persona at personas/prod/focus.coach.v1.json lives at the same relative path whether you consume the spec from Dart, Swift, Kotlin, or a backend service. Files released under personas/prod/, schemas/, and grammars/ are immutable once a version ships — behavior changes require a new persona / schema version and a new spec release.

​
Personas in the current spec

IdPurposeCapability tier
focus.coach.v1Proposes one tiny next action when the user is stuck; summarizes recent session state on requeststandard
stress.coach.v1Validates feelings; offers gentle regulation steps when the user is overwhelmedstandard
cognitive.companion.v1Adapts cognitive load to capacity and recovery signalsstandard
performance.coach.v1Schedules peak windows; prioritizes recovery when scores are lowstandard
wellness.guide.v1Favors rest under high stress / low recovery; nudges light movement when sedentarystandard
Every persona produces output conforming to the coach.response.v1 JSON Schema, with global.no_harmful_content and global.no_medical_diagnosis applied as safety constraints. The capability_tier column is the persona’s preferred cloud-model lane (fast / standard / deep). The Syni Cloud Gateway uses it to pick a route when the caller hasn’t pinned a model — each tier maps to a different model on the backend, with its own latency and per-day token budget. Empty / unknown tiers resolve to standard, so personas without the field stay on the default lane. Synheart ships additional app-specific personas (tuned to particular Synheart products) that aren’t part of the general persona catalog above. They follow the same spec contract — including capability_tier, safety rules, output schema — but their system prompts and rules are coupled to a single Synheart app’s surface, so they aren’t useful as generic building blocks for tenant apps. Tenants creating their own personas should model after the general personas in the table above.

​
Distribution

Releases are published to dist.synheart.ai/syni-spec/vX.Y.Z/ with:
  • spec.tar.gz — the canonical payload (the tree above, packed)
  • checksums.json — SHA-256 per file in the payload
  • manifest.json — release metadata
  • SHA256SUMS — top-level archive checksum
Same publishing pipeline used for the Synheart Runtime and the Syni Runtime. See Install for how to consume the spec from each language ecosystem.