Spec · GlyphIREarthCloudIntent · Translation · Trails

Examples

Integration flows

These examples show how to use EarthCloud as a middle layer between your app and your models: for cross-language chat, support tooling, and trails.

Example 01

1. Cross-language chat (EN ↔ ZH)

A chat app (like Buoychong) wants to let English and Chinese speakers talk naturally while keeping a shared sense of intent and tone.

Flow

  1. User A sends a message in English.
  2. App calls /v1/parse to get a GlyphIR block.
  3. App stores a trail event for the conversation.
  4. App calls /v1/realize to produce a Chinese view for User B.
  5. Reverse for Chinese → English replies.

Why use GlyphIR?

  • Intent and tone remain stable across languages.
  • Trails contain structured meaning, not only raw text.
  • Models and tools can operate on GlyphIR instead of ad-hoc prompts.

Example: app calling /v1/parse

// Pseudo-code (TypeScript) for sending a turn to EarthCloud
const request = {
  request_id: "req_01HX...",
  session_id: "chat_abc",
  user_id: "user_en",
  turn: {
    role: "user",
    text: "Let's meet tomorrow at 3pm Beijing time.",
    lang: "en",
    tone_hint: "casual",
    target_langs: ["zh-CN"]
  }
};

const response = await fetch("https://earthcloud.example.com/v1/parse", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
  },
  body: JSON.stringify({ request })
});

const { glyphir_block, trail_event } = await response.json();
// Store trail_event and pass glyphir_block downstream for realization.

Example: realizing for the other side

// Using the glyphir_block from /parse
const realizeRes = await fetch("https://earthcloud.example.com/v1/realize", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    glyphir_block,
    target_langs: ["zh-CN"],
    tone_overrides: {
      "zh-CN": { politeness: "polite" }
    }
  })
});

const { realization_result } = await realizeRes.json();
const messageForChineseUser = realization_result.realizations[0].text;

Example 02

2. Support inbox triage & summarization

A support inbox tool wants to summarize incoming tickets and propose responses in the agent's language, while keeping a trail of what the model saw and proposed.

Flow

  1. New ticket arrives (any language).
  2. Tool calls /v1/parse with ticket text + metadata.
  3. Routing decision is made via /v1/route (e.g. use support-model, call specific tools).
  4. Model operates on GlyphIR block and produces a proposed response GlyphIR.
  5. Tool calls /v1/realize to produce a response in the agent's language.
  6. All steps are written as trail events.

Benefits

  • Agents can inspect intent and proposed actions at a structured level.
  • Auditors can see what models saw, not just final text.
  • Switching models or providers is easier because the interface is GlyphIR, not prompts.

Example: ticket parse request

const request = {
  request_id: "req_ticket_123",
  session_id: "ticket_123",
  user_id: "end_user_987",
  turn: {
    role: "user",
    text: "The app keeps crashing when I upload a file over 10MB.",
    lang: "en",
    tone_hint: "neutral",
    safety_context: ["support"]
  },
  context: {
    page_title: "Support ticket #123",
    tags: ["plan:pro", "platform:web"]
  }
};

Example 03

3. Using EarthCloud alongside ChatCard

A more advanced integration uses ChatCard for "who" (persona, preferences, permissions) and EarthCloud for "what" and "how" (intent, realizations, trails).

Combined inputs

  • ChatCard token → persona, tone, languages, permission level.
  • EarthCloud request → the actual text and context for this turn.
  • Trails → long-term history of interactions for analytics and replay.

Example wiring

On the RP side, the app verifies the ChatCard token, then forwards both the persona and the text to EarthCloud:

// Pseudo-code: using ChatCard + EarthCloud together
const chatcardProfile = verifyChatCardToken(chatcardToken);

const ecRequest = {
  request_id: "req_01HX...",
  session_id: "chat_earthcloud",
  user_id: chatcardProfile.sub,
  turn: {
    role: "user",
    text: userMessage,
    lang: chatcardProfile.persona.primary_language,
    tone_hint: chatcardProfile.persona.tone,
    target_langs: decideTargetLangs(chatcardProfile)
  },
  context: { ... }
};

const { glyphir_block } = await callEarthCloudParse(ecRequest);
// Downstream, you can also tag trail events with chatcardProfile.card_id.

Example 04

4. Storing trails in Tongbuku

If you use Tongbuku as your storage engine, EarthCloud's trail events can map directly onto Tongbuku's trails abstraction.

Mapping

  • trail_id → Tongbuku trail/document ID.
  • event_id → Tongbuku event ID.
  • payload → Tongbuku event payload.

Benefits

  • Append-only, merge-safe history of interactions.
  • Replayable behavior for debugging and analysis.
  • Model-ready slices of history for context construction.
// Pseudo-code: append trail event to Tongbuku
const trailEvent = {
  event_id: "evt_01JK...",
  trail_id: "conversation_abc",
  kind: "turn",
  timestamp: new Date().toISOString(),
  request_id: ecRequest.request_id,
  glyphir_id: glyphir_block.glyphir_id,
  actors: {
    user_id: ecRequest.user_id,
    app_id: ecRequest.app_id
  },
  summary: { ... },
  payload: { ... }
};

await tongbuku.append(trailEvent);

Patterns

Design patterns

Some patterns that work well with EarthCloud:

  • Operate on GlyphIR, not raw text. Keep models and tools targeting the structured block.
  • Use tone and register explicitly. Don't rely only on vague prompts for "be polite".
  • Write trails by default. You can always compress or archive later; you can't recreate history.
  • Keep endpoints small and composable. Parse, route, and realize can be chained in your own stack.

Questions about implementing EarthCloud?

Reach out to us at info@earthcloud.co