Semantic Telemetry SDK — Manual

Version: 1.0
Last updated: January 2026
Audience: Developers, researchers, integrators

---

1 Overview

The AICoevolution SDK provides real-time conversational coherence metrics for human–AI dialogue. It answers a simple question: Is this conversation grounded, exploratory, or drifting?

The SDK operates as a hosted telemetry service with a thin Python client.

Layer	Endpoint	Latency	Purpose
Fast Metrics	/v0/ingest	~500 ms	Live SGI + Velocity for real-time feedback
Snapshot	/v0/snapshot/{conversation_id}	~50 ms	Retrieve cached metrics for a conversation

All metrics are embedding-based and require no fine-tuning.

---

2 Core Concepts

2.1 SGI (Semantic Grounding Index)

SGI measures how well an assistant's response semantically grounds with the user's query, relative to recent context.

SGI Range	Interpretation
< 0.7	Drifting — assistant diverges from user topic
0.8 – 1.5	Coherent — healthy grounding
> 2.0	Question-focused — assistant asking clarifying questions

Equation (simplified):

SGI = cos_sim(user_embedding, assistant_embedding) / context_norm

where context_norm is the mean norm of the rolling context window (default 8 messages).

---

2.2 Angular Velocity

Velocity measures the rate of semantic movement between consecutive messages, expressed in degrees per turn.

Velocity	Interpretation
< 25°	Stable, on-topic
25° – 45°	Moderate exploration
> 45°	Chaotic, topic-jumping

Equation:

θ = arccos(cos_sim(message_t, message_{t-1})) × (180 / π)

---

2.3 Coherence Region (Paper 02)

Conversations that enter and remain in the following zone exhibit genuine transformational depth:

SGI:      0.5 – 2.0
Velocity: ≤ 45°

This region was validated across 500+ baseline conversations (see Paper 02, Zenodo 10.5281/zenodo.18149381).

---

3 API Reference

Base URL (public cloud): https://sdk.aicoevolution.com

Authentication: include your Telemetry API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Generate a key at aicoevolution.com/profile → API Keys.

---

3.1 POST /v0/ingest — Fast Metrics

Ingest a single message and receive instant geometric metrics.

Request:

{
  "conversation_id": "conv_abc123",
  "role": "user",
  "text": "I want to explore what's been holding me back.",
  "timestamp_ms": 1705234567890
}

Response (after ≥1 Q-A pair):

{
  "conversation_id": "conv_abc123",
  "message_count": 4,
  "sgi_mean": 1.02,
  "sgi_latest": 1.08,
  "angular_velocity_mean": 28.5,
  "angular_velocity_latest": 32.1,
  "per_turn_sgi": [0.95, 1.08],
  "per_turn_angular_velocities": [0, 32.1, 28.5],
  "context_phase": "stable",
  "context_id": "ctx_1",
  "context_mass": 4,
  "context_drift": 2.1,
  "attractor_count": 1,
  "processing_time_ms": 450
}

Response fields:

Field	Description
sgi_mean / sgi_latest	Semantic Grounding Index (cumulative mean / latest turn)
angular_velocity_mean / angular_velocity_latest	Semantic movement in degrees (mean / latest)
context_phase	stable / protostar / split — topic coherence state
context_id	Current topic identifier
context_mass	Accumulated turns in current topic
context_drift	How fast the context centroid is moving (degrees)
attractor_count	Number of competing topic centers

---

3.2 GET /v0/snapshot/{conversation_id}

Retrieve cached metrics for a conversation.

Response: Same shape as /v0/ingest.

---

4 Conversation Summary

A conversation summary is the rolling telemetry state for a conversation, computed from ingested turns and returned by /v0/ingest and /v0/snapshot:

{
  "conversation_id": "conv_abc123",
  "message_count": 16,
  "sgi_mean": 1.08,
  "sgi_latest": 0.97,
  "angular_velocity_mean": 28.5,
  "angular_velocity_latest": 31.2,
  "context_phase": "stable",
  "context_id": "ctx_2",
  "context_mass": 6,
  "context_drift": 2.1,
  "attractor_count": 1
}

Use summaries to monitor coherence in real time, detect drift, and export metrics for reports.

---

5 Performance & Latency

Endpoint	Cold Start	Incremental
/v0/ingest	~800 ms	~450 ms
/v0/snapshot	—	~50 ms

Embeddings are cached (24 h TTL).

---

6 Quick-start cURL Examples

Ingest a message:

curl -X POST https://sdk.aicoevolution.com/v0/ingest \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "demo",
    "role": "user",
    "text": "Hello, I want to talk about change.",
    "timestamp_ms": 1705234567890
  }'

More examples: See the docs site for additional copy/paste examples and a standalone script:

• https://docs.aicoevolution.com/SDK/SDK_FIRST_STEPS
• https://docs.aicoevolution.com/SDK/STANDALONE_SCRIPT_README

---

7 Further Reading

Resource	Link
Full Documentation	docs.aicoevolution.com
SDK Architecture	docs.aicoevolution.com/sdk/architecture
Integration Guide	docs.aicoevolution.com/sdk/integration
API Keys & Quotas	aicoevolution.com/profile?tab=api-keys
Paper 01 — S64 Framework	Zenodo 10.5281/zenodo.17784637 / SSRN
Paper 02 — Coherence Region	Zenodo 10.5281/zenodo.18149381
Paper 03 — Orbital Mechanics	Zenodo 10.5281/zenodo.18347569

---

Maintainer: AICoevolution Research
License: CC BY 4.0