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)
• Backend-agnostic (works with any embedding model)

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 (Paper 03)                        │
│                        Geometry-Only Telemetry                           │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      TelemetryEngine                              │   │
│  │   ┌─────────┐  ┌─────────┐  ┌─────────────┐  ┌──────────────┐    │   │
│  │   │   SGI   │  │Velocity │  │Context Phase│  │ Context Mass │    │   │
│  │   └─────────┘  └─────────┘  └─────────────┘  └──────────────┘    │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                   │                                      │
│                                   │ HTTP                                 │
│                                   ▼                                      │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                  Embedding Sidecar (Separate Service)                    │
├─────────────────────────────────────────────────────────────────────────┤
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐      │
│   │  Nomic  │  │ OpenAI  │  │ Google  │  │ Cohere  │  │  S128   │      │
│   │(default)│  │ ada-002 │  │ Gemini  │  │   v3    │  │(future) │      │
│   └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘      │
└─────────────────────────────────────────────────────────────────────────┘

Key decisions:

1. SDK = Geometry Only — all Paper 03 metrics use vector math.
2. Sidecar = External — embedding service is deployed separately, enabling independent scaling and backend switching.
3. No LLM Required — Paper 03 operates entirely on embedding geometry.

---

6 API Endpoints

Method	Endpoint	Purpose
POST	/v0/ingest	Ingest message → instant SGI + Velocity
GET	/v0/snapshot/{id}	Retrieve cached snapshot
POST	/v0/transducer	Decompose message → S64 coordinates
POST	/v0/transducer/batch	Batch decomposition
POST	/v1/runs	Full session analysis
GET	/v1/runs/{id}	Poll run status / results
GET	/v1/runs/{id}/stream	SSE logs

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)

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

Endpoint	Cold Start	Incremental
/v0/ingest	~800 ms	~200 ms
/v0/transducer	—	~3–5 s
/v0/transducer/batch (20)	—	~25 s
/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
Integration Guide	docs.aicoevolution.com/sdk/integration
Paper 03	Zenodo 10.5281/zenodo.18347569

---

Maintainer: AICoevolution Research
License: CC BY 4.0