Metadata-Version: 2.4
Name: synapse-adapter-sdk
Version: 0.1.2
Summary: The intelligence layer above the AI protocol layer — canonical IR and adapter framework for heterogeneous AI model pipelines
Project-URL: Homepage, https://github.com/synapse-ir/adapter-sdk
Project-URL: Documentation, https://github.com/synapse-ir/spec
Project-URL: Repository, https://github.com/synapse-ir/adapter-sdk
Project-URL: Bug Tracker, https://github.com/synapse-ir/adapter-sdk/issues
Project-URL: Changelog, https://github.com/synapse-ir/adapter-sdk/blob/main/CHANGELOG.md
Author: SYNAPSE Contributors
License: MIT
License-File: LICENSE
Keywords: a2a,adapter,ai,canonical-ir,interoperability,llm,mcp,pipeline,synapse
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# SYNAPSE Adapter SDK

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12785/badge?criteria_level=1)](https://www.bestpractices.dev/projects/12785/silver)

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

```bash
pip install synapse-adapter-sdk
```

## Write your first adapter

```python
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

```bash
# 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.

```python
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.

```python
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:

```json
{"status": "ok"}
```

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

## Documentation

- [Project homepage](https://synapse-ir.github.io)
- [Getting started](https://synapse-ir.github.io/adapter-sdk/getting-started/installation/)
- [Writing adapters](https://synapse-ir.github.io/adapter-sdk/getting-started/first-adapter/)
- [Validation rules](https://synapse-ir.github.io/adapter-sdk/getting-started/validation/)
- [Canonical IR specification](https://github.com/synapse-ir/spec)
- [Live registry](https://registry-production-4b29.up.railway.app)
- [Registry API docs](https://registry-production-4b29.up.railway.app/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](SECURITY.md) instead
of opening a public issue.

## License

MIT. See [LICENSE](LICENSE).
