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 and semantic decomposition for human–AI dialogue. It answers a simple question: Is this conversation grounded, exploratory, or drifting?

The SDK operates in three layers:

Layer	Endpoint	Latency	Purpose
Fast Metrics	`/v0/ingest`	~500 ms	Live SGI + Velocity for real-time feedback
Semantic Decomposition	`/v0/transducer`	~3–5 s	S64 symbol & path activation per message
Batch Analysis	`/v1/runs`	~10–15 s	Full session metrics with optional LLM reasoning

All layers are embedding-based and require no fine-tuning. Symbol and path projections use the S64 framework described in Papers 01–03.

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).

2.4 Symbol Activation & Path Detection

The SDK projects each message onto the S64 symbolic space:

180 symbols (e.g., curiosity, resilience, breakthrough)
64 transformation paths (e.g., M51: Resilience's Renewal)

Symbol activation uses cosine similarity + softmax (temperature 0.1) to produce a probability distribution over symbols.

Path detection computes:

Path centroid = mean of the five role embeddings (FROM, THROUGH, TO, OBSERVATION, RESULT).
Message projection onto the centroid.
Transformation and insight vectors to determine phase:
- pre-transformation
- in-transformation
- insight-reached

2.5 Transducer Confidence

Indicates whether a message contains transformationally meaningful content.

confidence = 0.3 × max_path_activation
           + 0.2 × phase_clarity
           + 0.2 × symbol_focus
           + 0.3 × role_alignment

Confidence	Interpretation
< 0.3	Surface / small-talk
0.3 – 0.6	Moderate depth
> 0.6	Transformational content

3 API Reference

Base URL (public cloud): https://api.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:

json

{
  "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):

json

{
  "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],
  "processing_time_ms": 450
}

3.2 GET `/v0/snapshot/{conversation_id}`

Retrieve cached metrics for a conversation.

Response: Same shape as /v0/ingest.

3.3 POST `/v0/transducer` — Semantic Decomposition

Analyze a single message for S64 content.

Request:

json

{
  "text": "I've been stuck in the same patterns for years, but today something clicked.",
  "backend": "nomic"
}

Response:

json

{
  "top_symbols": [
    ["resilience", 0.089],
    ["breakthrough", 0.082],
    ["stagnation", 0.076]
  ],
  "top_paths": [
    ["M51: Resilience's Renewal", 0.156],
    ["M27: Transformation's Growth", 0.089]
  ],
  "confidence": 0.72,
  "path_alignments": [
    {
      "path_id": "M51",
      "path_name": "Resilience's Renewal",
      "activation": 0.156,
      "phase": "insight-reached",
      "transformation_projection": 0.82,
      "insight_projection": 0.91
    }
  ]
}

3.4 POST `/v0/transducer/batch`

Analyze multiple messages in one call.

Request:

json

{
  "texts": ["Message 1...", "Message 2...", "Message 3..."],
  "backend": "nomic"
}

Response:

json

{
  "results": [ /* array of single-message responses */ ],
  "count": 3
}

3.5 POST `/v1/runs` — Batch Analysis

Submit a full conversation for comprehensive metrics (SGI, Velocity, symbol entropy, optional LLM path detection).

Request:

json

{
  "run_id": "optional-uuid",
  "messages": [
    { "role": "user", "text": "..." },
    { "role": "assistant", "text": "..." }
  ]
}

Response:

json

{
  "run_id": "abc123",
  "status": "queued",
  "created_at": "2026-01-24T12:00:00Z"
}

Poll /v1/runs/{run_id} for results.

3.6 GET `/v1/runs/{run_id}`

Response (when complete):

json

{
  "status": "completed",
  "result": {
    "summary": {
      "sgi_mean": 1.08,
      "velocity_mean_degrees": 28.5,
      "symbol_entropy_mean": 4.2,
      "message_count": 20,
      "processing_time_s": 12.4
    }
  }
}

3.7 GET `/v1/runs/{run_id}/stream` (SSE)

Stream processing logs in real time (Server-Sent Events).

data: {"ts":"2026-01-24T12:00:05Z","level":"INFO","message":"Computing SGI..."}

4 Conversation Signature

A conversation signature aggregates symbol and path activations across all messages:

json

{
  "symbol_scores": {
    "curiosity": 0.45,
    "seeking": 0.38,
    "possibility": 0.31
  },
  "path_scores": {
    "M22: Understanding's Conviction": 0.52,
    "M48: Seeking's Discovery": 0.41
  },
  "phase_distribution": {
    "pre-transformation": 3,
    "in-transformation": 8,
    "insight-reached": 5
  },
  "total_messages": 16
}

Use signatures to compare conversations, detect outliers, or cluster by semantic theme.

5 Performance & Latency

Endpoint	Cold Start	Incremental
`/v0/ingest`	~800 ms	~450 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.

6 Quick-start cURL Examples

Ingest a message:

bash

curl -X POST https://api.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
  }'

Semantic decomposition:

bash

curl -X POST https://api.aicoevolution.com/v0/transducer \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I have been stuck in the same patterns for years.",
    "backend": "nomic"
  }'

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

Semantic Telemetry SDK — Manual ​

1 Overview ​

2 Core Concepts ​

2.1 SGI (Semantic Grounding Index) ​

2.2 Angular Velocity ​

2.3 Coherence Region (Paper 02) ​

2.4 Symbol Activation & Path Detection ​

2.5 Transducer Confidence ​

3 API Reference ​

3.1 POST /v0/ingest — Fast Metrics ​

3.2 GET /v0/snapshot/{conversation_id} ​

3.3 POST /v0/transducer — Semantic Decomposition ​

3.4 POST /v0/transducer/batch ​

3.5 POST /v1/runs — Batch Analysis ​

3.6 GET /v1/runs/{run_id} ​

3.7 GET /v1/runs/{run_id}/stream (SSE) ​

4 Conversation Signature ​

5 Performance & Latency ​

6 Quick-start cURL Examples ​

7 Further Reading ​

Semantic Telemetry SDK — Manual

1 Overview

2 Core Concepts

2.1 SGI (Semantic Grounding Index)

2.2 Angular Velocity

2.3 Coherence Region (Paper 02)

2.4 Symbol Activation & Path Detection

2.5 Transducer Confidence

3 API Reference

3.1 POST `/v0/ingest` — Fast Metrics

3.2 GET `/v0/snapshot/{conversation_id}`

3.3 POST `/v0/transducer` — Semantic Decomposition

3.4 POST `/v0/transducer/batch`

3.5 POST `/v1/runs` — Batch Analysis

3.6 GET `/v1/runs/{run_id}`

3.7 GET `/v1/runs/{run_id}/stream` (SSE)

4 Conversation Signature

5 Performance & Latency

6 Quick-start cURL Examples

7 Further Reading