Semantic Telemetry SDK — Integration Guide

Version: 1.0
Last updated: January 2026
Audience: Developers integrating the SDK into their own backend

---

1 Prerequisites

• Python 3.9+ (or any HTTP client for the REST API)
• An embedding endpoint (OpenAI, Cohere, Nomic, or self-hosted)
• A Telemetry API key — generate one at aicoevolution.com/profile → API Keys

---

2 Installation

Option A — pip (coming soon)

pip install aicoevolution-sdk

Option B — Source

git clone https://github.com/aicoevolution/semantic-telemetry.git
cd semantic-telemetry
pip install -e .

---

3 Initialize the Telemetry Engine

from aicoevolution_sdk import TelemetryEngine

# Cloud API (recommended)
engine = TelemetryEngine(
    api_key="YOUR_API_KEY",
    embedding_provider="nomic"   # or "openai", "cohere"
)

# Self-hosted sidecar
engine = TelemetryEngine(
    embedding_endpoint="http://localhost:8000/embed",
    embedding_dim=768
)

---

4 Ingest Messages

Call ingest() after each user or assistant turn:

# User message
user_result = engine.ingest(
    role="user",
    content="I'm trying to understand how meaning emerges in conversation"
)

# Assistant response
assistant_result = engine.ingest(
    role="assistant",
    content="Meaning emerges through the dynamic interplay between..."
)

---

5 Read Telemetry

Each ingest() returns real-time metrics:

print(f"SGI:           {assistant_result['sgi']:.3f}")
print(f"Velocity:      {assistant_result['velocity']:.1f}°")
print(f"Context Phase: {assistant_result['context_phase']}")
print(f"Context ID:    {assistant_result['context_id']}")

Available Fields

Key	Description	Typical Range
sgi	Orbital radius	0.5 – 1.5
velocity	Semantic movement (degrees)	0 – 180°
context_phase	stable / protostar / split	—
context_id	Current topic identifier	string
context_mass	Turns in current topic	0 – N
attractor_count	Competing topic centers	1+

---

6 Handle Context Shifts

When context_phase becomes split, a new topic has been detected:

if result['context_phase'] == 'split':
    print(f"Topic shifted! New context: {result['context_id']}")
    # Log, trigger webhook, update UI, etc.

---

7 Export Session Data

At the end of a conversation:

import json

session_data = engine.export_session()

with open('session.json', 'w') as f:
    json.dump(session_data, f, indent=2)

---

8 Integration Patterns

Pattern A — Middleware

class TelemetryMiddleware:
    def __init__(self):
        self.engine = TelemetryEngine(api_key=os.environ['AICOEVO_API_KEY'])

    def process(self, role: str, content: str) -> dict:
        return self.engine.ingest(role=role, content=content)

middleware = TelemetryMiddleware()
metrics = middleware.process("user", user_message)
# Continue with LLM call...

Pattern B — Async (non-blocking)

import asyncio

async def ingest_async(engine, role, content):
    loop = asyncio.get_event_loop()
    return await loop.run_in_executor(
        None,
        lambda: engine.ingest(role=role, content=content)
    )

Pattern C — Batch Processing

from aicoevolution_sdk import BatchProcessor

processor = BatchProcessor(api_key="YOUR_KEY")
results = processor.analyze_conversation([
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."},
])

---

9 Configuration Options

engine = TelemetryEngine(
    api_key="...",

    # Embedding
    embedding_provider="nomic",               # openai, cohere, nomic, local
    embedding_model="nomic-embed-text-v1.5",

    # Context detection
    context_split_threshold=0.4,              # lower = more sensitive
    protostar_threshold=0.25,

    # Velocity
    velocity_window=3,                        # rolling average

    # Debug
    verbose=False
)

---

10 Troubleshooting

Symptom	Cause	Fix
Metrics returning zeros	Embedding endpoint unreachable	Verify URL / API key
Slow first response	Model loading on cold start	Warm up with a test message
Context not detecting	Threshold too high	Lower context_split_threshold
422 errors	Payload mismatch	Check request schema in SDK Manual

---

11 Next Steps

Resource	Link
SDK Manual (API Reference)	docs.aicoevolution.com/sdk/manual
SDK Architecture	docs.aicoevolution.com/sdk/architecture
Semantic Telemetry (web app)	aicoevolution.com/baseline-generator
Paper 03 Research Repo	github.com/AICoevolution/paper03-orbital-mechanics

---

Maintainer: AICoevolution Research
License: MIT