Semantic Telemetry

Semantic Telemetry is how the Coevolution Society measures the quality of human-AI conversations. Every ecosystem must have telemetry connected for charter compliance.

What Gets Measured

Every conversation between a human and an agent produces four metrics:

Metric	What It Measures	Range
SGI (Semantic Gravity Index)	How grounded vs. abstract the conversation is	0.0 - 1.0
Orbital Velocity	The speed of topic evolution within a conversation	0.0 - 1.0
Coherence Region	How focused or scattered the conversation is	0.0 - 1.0
Context Drift	How much the conversation drifts from its starting point	0.0 - 1.0

Together, these metrics create a coherence profile -- a fingerprint of conversational quality.

Why It Matters

Telemetry isn't surveillance. It's measurement.

• For you: Understand how your agents perform. Spot degradation before users notice.
• For members: See the quality of their interactions. Track growth over time.
• For the platform: Aggregate coherence data (anonymized) to understand what healthy AI-human conversation looks like.
• For the charter: Proves your ecosystem is active and producing real conversations.

SDK Installation

pip install aicoevolution

Quick Start

The PyPI package ships a thin HTTP client. Metrics are computed by the SDK Service at https://sdk.aicoevolution.com.

Recommended minimal integration: 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="Can you help me write a story about time travel?",
    timestamp_ms=int(time.time() * 1000),
)

# assistant turn
metrics = sdk.ingest(
    conversation_id=conv,
    role="assistant",
    text="Absolutely. Let’s start with the protagonist and the rule of time travel.",
    timestamp_ms=int(time.time() * 1000),
)

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

Integration Patterns

Pattern 1: Gateway Integration (Recommended)

If you use the Discord gateway template, telemetry is built in. Every message pair (human message + agent response) is automatically tracked.

# In your gateway config
TELEMETRY_ENABLED=true
TELEMETRY_API_KEY=your_key
ECOSYSTEM_SLUG=your-slug

Pattern 2: Agent-Side Integration

If your agent handles its own communication, add telemetry reporting to the agent itself:

import time
from aicoevolution_sdk import AICoevolutionClient

sdk = AICoevolutionClient(base_url="https://sdk.aicoevolution.com")
sdk.auth = sdk.auth.__class__(user_api_key=os.environ["AICOEVOLUTION_API_KEY"])

# After each user/assistant turn
sdk.ingest(
    conversation_id="conv_123",
    role="assistant",
    text=assistant_text,
    timestamp_ms=int(time.time() * 1000),
)

Pattern 3: Batch Reporting

For high-volume ecosystems, report in batches:

// Collect conversations throughout the day
const batch = telemetry.createBatch();

batch.add({
  humanId: 'member-123',
  agentId: 'muse',
  messages: conversation1
});

batch.add({
  humanId: 'member-456',
  agentId: 'muse',
  messages: conversation2
});

// Submit all at once
await batch.submit();

Reading Your Metrics

Healthy Ranges

Metric	Healthy	Warning	Concern
SGI	0.3 - 0.8	< 0.2 or > 0.9	< 0.1 or > 0.95
Orbital Velocity	0.2 - 0.7	> 0.8	> 0.9
Coherence Region	0.5 - 1.0	0.3 - 0.5	< 0.3
Context Drift	0.0 - 0.4	0.4 - 0.6	> 0.6

What the Numbers Mean

• High SGI + High Coherence: Deep, focused conversations. The gold standard.
• Low SGI + High Velocity: Surface-level, fast-moving chat. Common in casual channels.
• High Drift + Low Coherence: Conversations going off the rails. May indicate agent confusion.
• Very High SGI (> 0.9): Overly abstract. The agent might be philosophizing instead of helping.

Ecosystem Coherence Score

Your ecosystem's overall coherence is the weighted average of all member conversation metrics. This number appears on your public profile in the registry.

A chartered ecosystem should aim for > 60% coherence.

Getting an API Key

1. Register your ecosystem on aicoevolution.com/ecosystems
2. In your ecosystem dashboard, navigate to Settings → Telemetry
3. Generate an API key
4. Store it securely (environment variable, not in code)

Privacy

• Conversation content is never stored by the platform
• Only the computed metrics are stored (SGI, velocity, coherence, drift)
• Metrics are associated with anonymized member IDs
• Ecosystem architects can see their own ecosystem's metrics
• Platform-level metrics are aggregated and anonymized

---

Next: Pre-flight Checklist to verify you're ready for chartering.