CMCI Signal API

What the API does

The CMCI Signal API exposes Coherix's coherence engine as a stateful REST service. Your pipeline pushes a small observation vector at whatever cadence makes sense (1–10 Hz is typical for live monitoring). The engine maintains a Kalman-filtered coherence state per session and returns the current regime plus actionable defect values on every observation.

It is content-agnostic: your system owns the mapping from raw signals (message flow, tool calls, latencies, agent outputs, …) to the four-dimensional observation vector y = (C, S, R, A). The engine does the coherence math and tells you whether the system is healthy, drifting, or breaking down.

No LLM calls. Deterministic on identical inputs (bit-identical across runs). Production smoke test: 23/23 passing · p95 latency 143 ms · lock v6-7-validated.

30-second quick start

Three calls to get a coherence state back:

# 1. Create a session
curl -X POST https://coherix.ca/cmci/signal/session \
  -H "Authorization: Bearer sk_live_your_key"
# → {"session_id": "c1a4…", "attractor_order": ["C","S","R","A"], …}

# 2. Push an observation (Cohesion, Salience, Rigidity, Articulation ∈ [0,1])
curl -X POST https://coherix.ca/cmci/signal/session/c1a4.../observe \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"y": [0.85, 0.15, 0.85, 0.85]}'
# → {"mu_scalar": 0.72, "margin": +0.18, "regime": "COHERENT", "defects": {…}}

# 3. Close the session when done
curl -X DELETE https://coherix.ca/cmci/signal/session/c1a4... \
  -H "Authorization: Bearer sk_live_your_key"

That's the full REST loop. For continuous streaming, the /stream WebSocket keeps a persistent connection and accepts observations in either direction.

What comes back — understanding the response

Every /observe and /state call returns the same schema. Four top-line metrics plus five defect axes:

Top-line metrics

Five defect axes (defects.d1 … d5)

Each d_i ∈ [0, 1] localises a specific mode of multi-agent breakdown. A rising d_i tells you which aspect of coherence is failing, so mitigation can target the right dimension.

Per-axis thresholds (empirically calibrated). The five axes operate at very different numerical scales, so a single uniform cut-off is not appropriate. Each axis has its own warn and critical thresholds derived from the Method B calibration on the reference demo scenario:

These values are demo-calibrated on the reference scenario shipped with the public live demo. Your own pipeline may exhibit different empirical ranges — recalibrate on your own data before putting CMCI into an operational decision loop. The dashboard highlights each cell warn/critical using the warn-relative severity (value / axis_warn), so axes at different numerical scales are compared on a common footing.

Regime labels

• COHERENT / A1_STABLE — healthy, safe to continue
• METASTABLE / TRANSITIONAL — drifting, watch closely
• INCOHERENT / A3_CRITICAL — breakdown, intervene

Optional observation scalars

Beyond the four-dimensional y = (C, S, R, A) vector, /observe accepts three optional scalars that refine how the engine reads each observation. All three are floats on [0, 1]. They default to sensible values if omitted, but populating them deliberately gives the engine access to structural information it cannot infer from y alone — especially around self-awareness, undoability, and event-order disruption.

How to populate them — domain examples

These scalars are domain-specific. The mapper in your pipeline is responsible for deriving them from whatever signals exist in your system. Two representative cases below.

Multi-agent AI pipeline

Open-source project governance

Effect on engine output

These scalars modulate how the engine interprets the same (C, S, R, A) vector — they do not replace it. Concretely:

• High self_referentiality reduces the engine's tendency to treat a given defect trajectory as structurally alarming, because the system is demonstrably watching itself. Low self-referentiality does the opposite.
• High reversibility softens the regime severity for a given defect configuration, because recent damage can be undone. Low reversibility sharpens it.
• High seq_disruption expands the expected normal range of defect values during the disruption window, because some drift is expected when the temporal structure has been perturbed. Sustained high disruption without recovery is itself a structural signal.

If you leave all three at their defaults, the engine still works — it simply treats the pipeline as mildly self-aware (self_referentiality = 0.5), fully irreversible (reversibility = 0), and temporally undisturbed (seq_disruption = 0). Populating them deliberately yields noticeably more nuanced regime transitions, especially across long observation windows.

Endpoint reference

Base URL: https://coherix.ca

Integration examples

Pick your stack:

from cmci_agent_sdk import CMCISession

session = CMCISession(
    base_url="https://coherix.ca",
    api_key="sk_live_your_key",
    team_id="my_pipeline",
)

# Option A — you already have the (C, S, R, A) vector
state = session.observe(y=[0.85, 0.15, 0.85, 0.85])
print(f"Coherence: {state['mu_scalar']:.3f}  Margin: {state['margin']:+.3f}  Regime: {state['regime']}")

# Option B — feed in raw multi-agent messages, SDK maps them to y
messages = [{"role": "user", "content": "..."}, ...]
state = session.observe_from_messages(messages, goal="ship feature X")

if state["alert_level"] == "CRITICAL":
    worst = max(state["defects"].items(), key=lambda kv: kv[1])
    alert_ops(f"Worst axis: {worst[0]} = {worst[1]:.2f}")

session.close()

KEY="sk_live_your_key"
BASE="https://coherix.ca"

# Create session, capture the UUID
SID=$(curl -sX POST "$BASE/cmci/signal/session" \
      -H "Authorization: Bearer $KEY" | jq -r .session_id)

# Push observations in a loop
for i in {1..10}; do
  curl -sX POST "$BASE/cmci/signal/session/$SID/observe" \
    -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    -d '{"y":[0.85,0.15,0.85,0.85]}' | jq .margin
  sleep 1
done

# Clean up
curl -sX DELETE "$BASE/cmci/signal/session/$SID" \
     -H "Authorization: Bearer $KEY"

from autogen import GroupChat, GroupChatManager
from cmci_agent_sdk import CMCISession

cmci = CMCISession(
    base_url="https://coherix.ca",
    api_key="sk_live_your_key",
    team_id="autogen_research_team",
)

def cmci_observer(recipient, messages, sender, config):
    state = cmci.observe_from_messages(messages[-10:])
    if state["alert_level"] in ("WARNING", "CRITICAL"):
        print(f"[CMCI] {state['regime']} — margin={state['margin']:+.2f}")
    return False, None   # don't interrupt the chat

groupchat = GroupChat(agents=[...], messages=[], max_round=20)
manager   = GroupChatManager(groupchat=groupchat)
manager.register_reply([manager], reply_func=cmci_observer)

# Run the chat — CMCI observes every message asynchronously
user_proxy.initiate_chat(manager, message="Build plan for feature X")

cmci.close()

import json, urllib.request

BASE, KEY = "https://coherix.ca", "sk_live_your_key"

def call(method, path, body=None):
    req = urllib.request.Request(
        BASE + path,
        data=json.dumps(body).encode() if body else None,
        method=method,
    )
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("User-Agent", "my-app/1.0")   # required by Cloudflare
    if body: req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

sid   = call("POST", "/cmci/signal/session")["session_id"]
state = call("POST", f"/cmci/signal/session/{sid}/observe",
             {"y": [0.85, 0.15, 0.85, 0.85]})
print(state["regime"], state["mu_scalar"])
call("DELETE", f"/cmci/signal/session/{sid}")

Error codes

All errors return JSON {"detail": "…"}. Common codes:

Rate limits & performance

• Observations per minute per key: 60 (sliding 60-second window). Returns 429 with Retry-After header when exceeded.
• Concurrent sessions per key: 10. Close sessions you're done with to free slots.
• Session TTL: 2 hours of idle time → auto-cleanup.
• Latency (production, single-region): p50 109 ms · p95 143 ms · p99 151 ms. Fine for real-time monitoring at 1–10 Hz per agent.
• Determinism: Identical observation sequences produce bit-identical outputs (diff < 10⁻⁹). Audit-reproducible.

Need higher limits for a production load? Contact us — pilot keys can be provisioned with custom quotas.

Get an API key

The CMCI Signal API is currently in pilot phase. We're onboarding a small number of teams running multi-agent AI systems where structural coherence matters (research pipelines, autonomous operations, complex tool-use orchestration).

Keys are free during pilot. In exchange, we ask for honest feedback and permission to use anonymized latency/reliability metrics to validate the system.