synapse-adapter-sdk 0.1.2

The intelligence layer above the AI protocol layer — canonical IR and adapter framework for heterogeneous AI model pipelines

SYNAPSE Adapter SDK

SYNAPSE is a canonical intermediate representation (IR) protocol that lets AI models with incompatible schemas interoperate through a unified adapter interface.

Write two functions — connect your AI model to every other model in the ecosystem.

Without SYNAPSE: 4 models require 6 custom connectors. 10 models require 45. Each breaks when either model's schema changes.

With SYNAPSE: write one ingress and one egress adapter. Done. Your model is immediately composable with every other registered model.

Install

pip install synapse-adapter-sdk

Write your first adapter

from synapse_sdk import AdapterBase, CanonicalIR, ProvenanceEntry
from typing import Any

class MyModelAdapter(AdapterBase):
    MODEL_ID = "my-org/my-model-v1.0"
    ADAPTER_VERSION = "1.0.0"

    def ingress(self, ir: CanonicalIR) -> dict[str, Any]:
        return { "input": ir.payload.content }

    def egress(self, output: dict, original_ir: CanonicalIR, latency_ms: int) -> CanonicalIR:
        updated = original_ir.copy()
        updated.provenance.append(self.build_provenance(
            confidence=output["score"],
            latency_ms=latency_ms,
        ))
        return updated

Validate

# Run against the built-in minimal fixture
synapse-validate --adapter my_module.MyModelAdapter

# Run all 20 standard fixtures
synapse-validate --adapter my_module.MyModelAdapter --all-fixtures

# Validate and check whether your MODEL_ID is already registered
synapse-validate --adapter my_module.MyModelAdapter --check-registry

--check-registry hits the live SYNAPSE registry after validation and reports whether your MODEL_ID is already registered, what version is live, and the registration endpoint if it isn't. Use --registry-url to point at a self-hosted registry instead.

Register with the SYNAPSE registry

Once your adapter is working, register it with the public registry so the routing engine can discover and route requests to your model.

Two registration modes

Catalog entry (recommended for model specs and research adapters)

Omit heartbeat_endpoint. The registry treats the entry as always-available and never polls it. Use this when you are publishing a model specification or a reference adapter without a live inference endpoint.

import httpx

httpx.post(
    "https://registry-production-4b29.up.railway.app/v1/models",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "model_id":        "my-org/my-model-v1.0",
        "adapter_version": "1.0.0",
        "task_types":      ["classify"],
        "domain_tags":     ["general"],
        "input_schema":    {"type": "object", "properties": {"text": {"type": "string"}}},
        "output_schema":   {"type": "object", "properties": {"label": {"type": "string"}}},
    },
)

Live service (for deployed inference endpoints)

Provide heartbeat_endpoint. The registry polls it every 30 seconds and weights routing toward healthy instances. The endpoint must respond with {"status": "ok"} and HTTP 200 when the model is ready to serve requests.

httpx.post(
    "https://registry-production-4b29.up.railway.app/v1/models",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "model_id":           "my-org/my-model-v1.0",
        "adapter_version":    "1.0.0",
        "task_types":         ["classify"],
        "domain_tags":        ["general"],
        "input_schema":       {"type": "object", "properties": {"text": {"type": "string"}}},
        "output_schema":      {"type": "object", "properties": {"label": {"type": "string"}}},
        "heartbeat_endpoint": "https://my-model.example.com/health",
    },
)

The heartbeat endpoint should respond like:

{"status": "ok"}

Models whose heartbeat fails three consecutive polls are marked unavailable and excluded from routing until they recover.

Documentation

• Project homepage
• Getting started
• Writing adapters
• Validation rules
• Canonical IR specification
• Live registry
• Registry API docs

What SYNAPSE is not

SYNAPSE does not compete with MCP or A2A. It builds on top of them. MCP connects agents to tools. A2A connects agents to each other. SYNAPSE connects specialized models with incompatible schemas — and makes routing between them smarter over time.

Feedback and issues

Found a bug or have a feature request? Open an issue: https://github.com/synapse-ir/adapter-sdk/issues

For security vulnerabilities, see SECURITY.md instead of opening a public issue.

License

MIT. See LICENSE.