ppx-connectors

Outbound ingestion connectors for the Preference Profile Exchange (PPX).

Pull preference signals from services the user already uses, map them onto PPX claims, and propose updates through the provider — so writeback policy, review, and audit all apply uniformly.

Install

pip install ppx-connectors

Requires Python 3.11+. Published version: 0.1.0a1 (PyPI).

Alpha, tracking a draft specification. Expect breaking changes. The version is 0.1.0a1 on PyPI and 0.1.0-alpha.1 on npm — the same release in each ecosystem's required format.

Ship your own connector in three methods

from ppx_connectors import Connector, ConnectorContext, ProposedClaim, SourceSignal

class MyConnector(Connector):
    name = "my-source"
    writes_namespaces = ["my-domain"]
    interval_seconds = 60 * 60 * 12  # every 12h

    def fetch(self, ctx: ConnectorContext) -> list[SourceSignal]:
        # call the external API, return raw signals
        ...

    def to_claims(self, signals: list[SourceSignal]) -> list[ProposedClaim]:
        # map raw signals onto spec claims (pure function, no I/O)
        return [ProposedClaim(
            namespace="my-domain",
            key="some_preference",
            value=0.7,
            confidence=0.8,
            source={"kind": "imported", "origin": self.name},
        )]

Run a connector once (manual / cron-friendly)

from ppx_client import PpxClient
from ppx_connectors import ConnectorContext, run_once
from ppx_connectors.connectors import SpotifyConnector

client = PpxClient("https://api.provider.app")
ctx = ConnectorContext(
    client=client,
    grant_token=writeback_scoped_grant_token,
    credentials={"spotify_access_token": user_spotify_oauth_token},
)
result = run_once(SpotifyConnector(), ctx)
# → {"connector": "spotify", "signals": 150, "proposed": 6, "writeback": "proposal_created"}

Built-in connectors

Design notes

• Separation of concerns. fetch() does I/O; to_claims() is pure. This makes claim-mapping testable without hitting external services, and reusable for replay / dry-run.
• Spec-compliant writeback. All claims go through /v1/profile/propose-updates, so the user's writeback_policy is honored automatically. Under review_required the user sees every proposal before anything takes effect.
• Confidence by volume. Pull-based inference has an inherent signal count; the built-in _conf_from_volume helper scales confidence linearly with observation count.
• Every claim is attributed. source.kind = "imported" and source.origin = <connector-name> on every proposal. The user always knows who learned each claim.

License

Apache-2.0.