Integration patterns

Middleware, batch, event-driven, and retry architectures.

Four canonical shapes for integrating COHESION. Pick one.

1. Middleware

Synchronous wrapper around every AI provider call. Simplest. Highest fidelity (timing is accurate). Latency impact typically under 200 ms per call.

Recipes: Python cookbook, TypeScript cookbook.

2. Batch

Emit interactions to a queue (SQS, Kafka, Cloudflare Queues). Nightly worker drains and calls POST /v1/score/batch. Lowest synchronous latency. Slightly delayed JIS.

3. Event-driven

Publish a domain event (e.g. decision.finalized) and subscribe a COHESION scorer. Decouples COHESION from the hot path. Good for large, distributed architectures where the AI call and the operator’s final decision are separate events.

4. Retry and fail-open

Wrap COHESION calls in a try/catch. On transient failure (429, 5xx, timeout), log and continue. Never fail the primary AI workflow because the scoring API had a bad minute.

try {
  await cohesion.score({ /* ... */ });
} catch (err) {
  logger.warn("cohesion_score_failed", { request_id: err.requestId });
  // do not throw; let the primary flow continue
}

Which to pick