Semantic Telemetry SDK — Integration Guide

Audience: developers integrating AICoevolution semantic telemetry into their own app/backend
Package: aicoevolution (thin client)
Service: https://sdk.aicoevolution.com

The PyPI package ships only an HTTP client. Metrics are computed by the SDK Service.

---

1) Prerequisites

• Python 3.9+ (or any HTTP client)
• A Telemetry API key (Profile → API Keys)

---

2) Install

pip install aicoevolution

---

3) Minimal integration (recommended)

Call /v0/ingest after each user message and each assistant reply.

import time
from aicoevolution_sdk import AICoevolutionClient

sdk = AICoevolutionClient(base_url="https://sdk.aicoevolution.com")
sdk.auth = sdk.auth.__class__(user_api_key="aic_your_key_here")

conv = "conv_123"

# user turn
sdk.ingest(
    conversation_id=conv,
    role="user",
    text="I'm trying to understand how meaning emerges in conversation.",
    timestamp_ms=int(time.time() * 1000),
)

# assistant turn
metrics = sdk.ingest(
    conversation_id=conv,
    role="assistant",
    text="Meaning emerges through the dynamic interplay between what’s said and accumulated context.",
    timestamp_ms=int(time.time() * 1000),
)

print("SGI mean:", metrics.get("sgi_mean"))
print("Velocity mean:", metrics.get("angular_velocity_mean"))

---

4) Interpretation (quick)

SGI (Semantic Grounding Index)

• SGI < 0.7: drifting
• SGI 0.8–1.5: coherent grounding (target range)
• SGI > 2.0: question-focused / clarification mode

Velocity (degrees/turn)

• Velocity < 25°: stable
• Velocity 25–45°: moderate exploration (upper bound of coherence region)
• Velocity > 45°: chaotic / topic jumping

---

5) Context fields (optional)

Some deployments may include additional context fields such as:

• context_state_latest (stable/protostar/split)
• active_context_mass
• attractor_count

Treat these as optional fields (they may change between releases).

---

6) Experimental endpoints (not part of v1 contract)

Some deployments may expose experimental endpoints (e.g. semantic decomposition). These are not part of the first public contract and may be disabled in production.

---

7) Batch runs (/v1/runs) — internal/platform only

/v1/runs is used by the AICoevolution platform backend for batch workflows and snapshot persistence. It requires the internal header X-SDK-API-Key and is not intended for public client-side use.

If you’re a partner and need access, contact: research@aicoevolution.com

---

Next steps

Resource	Link
SDK Manual	docs.aicoevolution.com
Semantic Telemetry (web app)	aicoevolution.com/baseline-generator