PRISM

Contributing Connectors to Prism

This guide covers everything you need to build, validate, and submit a connector to the Prism registry.

---

1. What is a connector?

A Prism connector is a self-contained .prism directory package that streams or polls a data source

and emits PricePoint objects — normalized probability values in [0.0, 1.0]. Any source that produces

a time series (prediction markets, economic data, news sentiment) can be a connector.

---

2. Quickstart

pip install prism-signal

prism scaffold \
  --name "My Data Source" \
  --slug my_source \
  --type prediction_market \
  --transport rest

prism validate connectors/my_source.prism

This creates connectors/my_source.prism/ with a manifest, skeleton implementation, schema, README,

and test scaffold.

---

3. Directory structure

my_source.prism/
  connector.prism    # YAML manifest (required)
  __init__.py        # PrismConnector subclass (required)
  schema.json        # PricePoint JSON Schema
  README.md          # Documentation
  tests/
    test_my_source.py

---

4. The connector.prism manifest

prism_format_version: "1.0"
name: "My Data Source"
slug: "my_source"
version: "1.0.0"
author: "your_github_username"
source_type: "prediction_market"  # prediction_market | alternative_data | news | custom
transport: "rest"                  # websocket | rest | push
description: "Streams XYZ prices from ABC API."
auth_required: true
auth_fields:
  - MY_API_KEY
contract_slugs:
  - MY_CONTRACT_SLUG
tags:
  - macro
  - rates
homepage: "https://github.com/you/your-repo"

---

5. Implementing PrismConnector

Your __init__.py must define a class that inherits from PrismConnector and implements three methods:

from prism.base import PrismConnector, PrismMetadata, PricePoint
from datetime import datetime, timezone

class MySourceConnector(PrismConnector):
    metadata = PrismMetadata(
        name="My Data Source",
        slug="my_source",
        version="1.0.0",
        author="your_github_username",
        source_type="prediction_market",
        transport="rest",
        description="Streams XYZ prices from ABC API.",
        auth_required=True,
        auth_fields=["MY_API_KEY"],
        contract_slugs=["MY_CONTRACT_SLUG"],
        tags=["macro"],
    )

    async def start(self) -> None:
        """Open connections and begin emitting PricePoints."""
        ...

    async def stop(self) -> None:
        """Gracefully close connections and release resources."""
        ...

    async def health_check(self) -> bool:
        """Return True if the connector is healthy and streaming."""
        ...

---

6. The PricePoint contract

Every emission must be a valid PricePoint:

PricePoint(
    timestamp=datetime.now(timezone.utc),  # must be UTC-aware
    price=0.72,                             # MUST be in [0.0, 1.0]
    volume=1500,                            # optional: raw volume
    slug="MY_CONTRACT_SLUG",               # which contract this is for
    source="my_source",                    # your connector's slug
)

Normalization is your responsibility. If your source emits prices in cents, divide by 100.

If it emits a raw rate (e.g., 5.25%), normalize against a known range.

---

7. Writing tests

Every connector needs at least 5 tests in tests/test_{slug}.py:

def test_manifest_exists(): ...
def test_metadata_slug_matches(): ...
def test_health_check_false_when_not_running(): ...
def test_price_normalization(): ...
def test_no_auth_when_not_required(): ...

Run with: pytest connectors/my_source.prism/tests/

---

8. Validation

Before submitting, your connector must pass prism validate with zero failures:

prism validate connectors/my_source.prism

Warnings are acceptable (e.g., missing tests dir, undocumented auth fields), but failures block submission.

---

9. Submitting to the registry

  • Fork arpjw/prism on GitHub
  • Copy your .prism package to connectors/your_slug.prism/
  • Add an entry to registry/registry.json (see Section 10 below)
  • Open a PR — CI will automatically run prism validate on your connector
  • A maintainer will review and merge

    • CI checks:

  • registry/registry.json validates against registry/schema.json
  • prism validate passes with zero failures on your connector
  • No imports from private or non-prism packages

    • ---

    10. Registry entry

    When you submit a connector, add an entry to registry/registry.json:

    {
  "name": "My Data Source",
  "slug": "my_source",
  "version": "1.0.0",
  "author": "your_github_username",
  "source_type": "prediction_market",
  "transport": "rest",
  "description": "One sentence describing what this streams.",
  "auth_required": true,
  "auth_fields": ["MY_API_KEY"],
  "contract_slugs": ["MY_CONTRACT_SLUG"],
  "tags": ["macro", "rates"],
  "homepage": "https://github.com/you/your-repo",
  "source_url": "https://github.com/arpjw/prism/archive/refs/heads/main.tar.gz",
  "source_path": "connectors/my_source.prism",
  "downloads": 0,
  "verified": false
}

    Field reference:

    FieldRequiredDescription
    nameYesHuman-readable display name
    slugYessnake_case identifier, must match your package directory
    versionYessemver (e.g., 1.0.0)
    authorYesGitHub username of the connector author
    source_typeYesOne of: prediction_market, alternative_data, news, custom
    transportYesOne of: websocket, rest, push
    descriptionYesOne sentence, what this connector streams
    auth_requiredYestrue if the connector requires env vars to operate
    auth_fieldsYesList of required env var names
    contract_slugsYesList of contract/market identifiers this connector tracks
    tagsYesSearchable tags (e.g., fed, rates, macro, recession)
    homepageNoURL to your repo, docs, or source
    source_urlYesGitHub archive URL where the package can be downloaded
    source_pathYesPath within the archive to the .prism directory
    downloadsYesSet to 0 on submission (managed by maintainers)
    verifiedYesSet to false on submission. The maintainer sets this to true after review and live testing

    What does `"verified": true` mean?

    A maintainer has reviewed the code, confirmed it imports only from prism.*, run it against a live data source, and verified the normalization is correct. Community-submitted connectors default to false — use them at your own risk until they are verified.