Semantic Telemetry SDK — Architecture

Version: 2.0 (Paper 03 Release)
Last updated: January 2026
Audience: Engineers, researchers, auditors

---

1 Design Philosophy

Geometry Only — all Paper 03 metrics are computed with vector math on embeddings:

• Cosine similarity, angular distances, centroids
• No LLM inference required
• Fast (~50–200 ms per turn)
• Implementation-agnostic (the service may evolve internally without changing the client API)

The Semantic Transducer bridges geometry and meaning by projecting embeddings onto the S64 symbolic coordinate system. Paper 03 introduces the concept; Paper 04 will explore it in depth.

---

2 What It Measures

Metric	Type	Description	Typical Range
SGI	Geometric	Orbital radius from context	0.5 – 1.5
Velocity	Geometric	Angular movement per turn	0 – 180°
Context Phase	Geometric	Topic coherence state	stable / protostar / split
Context Mass	Geometric	Accumulated turns in topic	0 – N
Context Drift	Geometric	How the "sun" is moving	0 – 180°
S64 Coordinates	Transducer	Symbol & path activations	(Paper 04)

---

3 Semantic Orbital Mechanics

Conversations are modeled as orbital systems:

      ╭─────────────╮
     ╱               ╲
    │   ☀️ Context    │  ← The "sun" (accumulated topic)
    │     (Mass)      │
     ╲               ╱
      ╰──────○──────╯
             ↑
          Current
          Turn-Pair

• Context Mass — accumulated turns that form the gravitational center.
• SGI — how far the current turn is from the context center.
• Velocity — how fast the conversation moves through semantic space.
• Context Phase — is the topic stable, forming, or splitting?

---

4 Turn-Pair Model

Each "turn" is a user message + assistant response pair:

Turn N:
  User:      "What about X?"      → embedding U
  Assistant: "X means..."         → embedding A
  Turn-Pair: mean(U, A)           → embedding P

The SDK tracks:

• Per-message metrics (individual U and A)
• Turn-pair metrics (combined P)
• Context evolution (how the sun moves)

---

5 High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                      AICoevolution SDK Service (Paper 03)                │
│                    Hosted semantic telemetry + transducer                 │
├─────────────────────────────────────────────────────────────────────────┤
┌─────────────────────────────────────────────────────────────────────────┐
│                  Embedding Layer (internal service component)            │
├─────────────────────────────────────────────────────────────────────────┤
│     (implementation details are not part of the public SDK contract)     │
└─────────────────────────────────────────────────────────────────────────┘

Key decisions:

1. SDK = Geometry Only — all Paper 03 metrics use vector math.
2. Embedding layer is separate — enabling independent scaling and cost control.
3. No LLM required — Paper 03 telemetry operates entirely on embedding geometry.

---

6 API Endpoints (v1 public contract)

Method	Endpoint	Purpose
POST	/v0/ingest	Ingest message → instant SGI + Velocity
GET	/v0/snapshot/{id}	Retrieve cached snapshot
POST	/v1/runs	Batch analysis (internal/platform only)
GET	/v1/runs/{id}	Poll run status / results (internal/platform only)
GET	/v1/runs/{id}/stream	SSE logs (internal/platform only)

See the SDK Manual for request/response schemas.

---

7 Metrics Deep Dive

7.1 SGI (Semantic Grounding Index)

SGI = θ(response, query) / θ(response, context)

SGI Value	Interpretation
< 0.7	Over-generalizing (context-heavy)
0.7 – 1.3	Coherence Region
> 1.3	Narrow focus (query-heavy)

7.2 Velocity

Velocity = angular_distance(message_n, message_{n-1})

Velocity	Interpretation
< 15°	Stagnant
15 – 60°	Coherence Region
> 60°	Volatile

7.3 Context Phase Detection

State	Detection	Description
stable	Turn-pair within 45° of context centroid	Topic anchored
protostar	1-2 turns drifting	New topic forming
split	3+ consecutive drifts	Topic changed

7.4 Context Mass

Accumulated turns in the current context. Higher mass = more gravitational pull = harder to shift topic.

---

8 Semantic Transducer (Preview / experimental)

The Transducer bridges geometry and meaning.

Human Meaning                    Digital Representation
     ↓                                   ↓
"I finally understood"    ──→   [0.23, -0.45, 0.12, ...]
                                        768 dimensions

It decomposes embeddings into interpretable S64 coordinates:

Layer	Description
Symbol Layer	180 tokens (e.g., understanding, clarity)
Path Layer	64 transformations (e.g., M5: Confusion → Clarity)

Paper 04 will cover energy conversion, domain classification, and path detection in depth.

---

9 Performance Characteristics (v1)

Endpoint	Cold Start	Incremental
/v0/ingest	~800 ms	~200 ms
/v1/runs (20 msgs)	—	~10–15 s

Embeddings are cached (24 h TTL). Symbol and path matrices are lazy-loaded once per SDK instance.

---

10 Paper Series Roadmap

Paper	Focus	SDK Features
01	S64 Symbolic Framework	Symbol/path definitions
02	Embedding Space Geometry	S128 model, threshold calibration
03	Semantic Orbital Mechanics	SGI, Velocity, Context Phase (this release)
04	Semantic Depth Detection	Domain classification, path detection (protected)
05+	Applications	Governor, Neurodiversity, LRI

---

11 Further Reading

Resource	Link
SDK Manual	docs.aicoevolution.com/sdk/manual
Paper 03	Zenodo 10.5281/zenodo.18347569

---

Maintainer: AICoevolution Research
License: CC BY 4.0