SPEC · GLYPHIR PROTOCOL v0.1 (DRAFT)

EarthCloud protocol & GlyphIR spec

EarthCloud is the meaning layer for multilingual AI. It is an open specification (GlyphIR) for describing what was said, what it means, and how it connects to trails and worlds—independent of any single language, model, or app. Any system can emit or consume GlyphIR objects as long as it honours this envelope.

Jump to data model See endpoints

Envelope

1. Request envelope

A request is the top-level object. It carries the raw turn, language hints, and options for how EarthCloud should process it. The goal is to preserve enough context so downstream services can build or update GlyphIR blocks deterministically.

{
  "request_id": "req_01HX...",
  "session_id": "sess_01ABC...",
  "turn": {
    "role": "user",
    "text": "Can you summarise this for my Chinese colleague?",
    "lang": "en",
    "tone_hint": "casual",
    "register_hint": "standard",
    "target_langs": ["zh-CN"]
  },
  "options": {
    "write_trail": true,
    "return_glyphir_only": false
  }
}

request_id and session_id let implementations deduplicate turns and thread related GlyphIR blocks.
turn stores the raw utterance plus any tone/register hints. Implementers can add custom fields; keep them namespaced.
options.write_trail signals whether a trail event should be emitted (e.g. to Tongbuku).

Message / utterance

2. Surface & segmentation

GlyphIR keeps the surface text alongside a canonical (Mandarin-centered in this draft) representation. Segments break a turn into smaller units so downstream models can attach slots, intents, or translations precisely.

{
  "glyphir_id": "gph_01HX...",
  "surface": {
    "text": "请帮我把这段内容总结一下给同事",
    "lang": "zh-CN",
    "source_lang": "en",
    "script": "Hans"
  },
  "segments": [
    {
      "segment_id": "seg_001",
      "type": "request",
      "canonical": "请帮我总结这段内容给中国同事",
      "slots": [
        { "name": "audience", "type": "person", "value": "Chinese colleague" }
      ]
    }
  ]
}

Surface text keeps the original language/script for auditability.
segments combine canonical text with optional slots so orchestration tools can reason over fine-grained meaning.

Meaning block

3. Normalised meaning & participants

This block is the core of GlyphIR. It records the interpreted intent, topics, tone, constraints, and who is involved. Everything in this section is language-agnostic so any model can act on it.

{
  "glyphir_id": "gph_01HX...",
  "meaning": {
    "intent": {
      "kind": "summarize_content",
      "domain": "documentation",
      "confidence": 0.92
    },
    "topics": ["product_docs"],
    "sentiment": "neutral",
    "stance": "helpful",
    "tone": {
      "politeness": "polite",
      "directness": "medium",
      "formality": "neutral"
    },
    "constraints": {
      "max_length": "short",
      "reading_level": "standard"
    }
  },
  "participants": {
    "speaker": { "role": "user", "card_id": "chatcard_875" },
    "audience": ["colleague"],
    "tools": ["llm:glyphd-2025-03"]
  }
}

The intent object is extensible—define domain-specific enums, but keep the top-level labels predictable.
participants can reference ChatCard IDs, agents, or tools. This keeps attribution aligned with trails.
Tone and constraints make it easy to realise consistent responses later.

Context & trails

4. Linking worlds, trails, and provenance

Trail events keep GlyphIR grounded in time and place. EarthCloud doesn't mandate Tongbuku, but we recommend an append-only, verifiable log that references the same IDs you see in the envelope.

{
  "trail_event": {
    "event_id": "evt_01JK...",
    "trail_id": "trail_conversation_abc",
    "timestamp": "2025-11-08T20:15:30Z",
    "request_id": "req_01HX...",
    "glyphir_id": "gph_01HX...",
    "realization_ids": ["rlz_zh_01"],
    "context_links": {
      "world": "funwae/buoychong",
      "room": "product-design",
      "message_id": "msg_4521"
    },
    "quality": {
      "confidence": 0.91,
      "source": "llm:glyphd-2025-03"
    }
  }
}

Trail events are append-only. They can be replayed or audited later.
Context links tie a turn back to worlds (Funwae, kiosks), rooms, or external systems.
Quality metadata records which model or human produced the meaning/realization.

Endpoints

Reference endpoints (optional)

You can expose EarthCloud as a REST-ish service. The contracts below are suggestions; the spec focuses on payload semantics rather than implementation details.

1. `POST /v1/parse`

Turn raw user text into a GlyphIR block.

POST /v1/parse
Content-Type: application/json
Authorization: Bearer <token>

{ "request": { ... ec_request ... } }

{
  "glyphir_block": { ... glyphir ... },
  "trail_event": { ... trail_event ... } // optional when write_trail = true
}

2. `POST /v1/realize`

Realise a GlyphIR block into natural language outputs.

POST /v1/realize
Content-Type: application/json

{ "glyphir_block": { ... }, "target_langs": ["zh-CN", "en"] }

{ "realization_result": { ... } }

3. `POST /v1/route`

Decide which models, tools, or agents should handle the block.

POST /v1/route
Content-Type: application/json

{ "glyphir_block": { ... }, "capabilities": ["llm:general_qa", "tool:search"] }

{
  "routing": {
    "primary": { "type": "agent", "id": "agent:summary_helper" },
    "fallbacks": [{ "type": "tool", "id": "tool:summary" }]
  }
}

Resilience

Error model & security

Error model

All endpoints should return a simple JSON error payload:

{
  "error": "invalid_request",
  "error_description": "Missing 'request' field in body."
}

Authentication & authorisation

Require bearer tokens or mTLS for API access.
Include ChatCard IDs or RP IDs when you need cross-system attribution.
Leverage safety_context to apply higher scrutiny in sensitive domains.

Status

Spec status & evolution

This is a draft specification intended to be iterated with real implementations. The immediate goals are to stabilise the GlyphIR envelope, align on minimal endpoint contracts, and prove trail interoperability with Tongbuku. Future revisions may add formal JSON Schemas, expanded language support, and pluggable safety policies.

Interested in co-designing or implementing? Reach out via the contact section on the home page.