agent-connector-sdk 0.1.0__py3-none-any.whl

agent_connector_sdk/__init__.py

@@ -0,0 +1,10 @@
+"""agent-connector-sdk: the connector-facing SDK for the agent-packages fleet.
+
+Public modules are imported by their own path (``agent_connector_sdk.mcp.server``,
+``agent_connector_sdk.ports`` and so on); this package root deliberately exports
+only the version so that importing it never pulls in the MCP server stack.
+"""
+
+from agent_connector_sdk._version import __version__
+
+__all__ = ["__version__"]

agent_connector_sdk/_contract_fields.py

@@ -0,0 +1,92 @@
+"""Typed field readers for ``ac:AccessContract`` subjects."""
+
+from __future__ import annotations
+
+from ._turtle import AccessContractError, Term
+from .credentials.references import SecretReferenceError, parse_secret_reference
+
+AC = "https://knuckles-team.github.io/agent-connector-sdk/access#"
+ACCESS_KINDS = frozenset({"mcp_tool", "http_endpoint", "graphql_query", "a2a_skill"})
+PAGINATION_MODES = frozenset({"none", "cursor", "offset", "page"})
+PUSHDOWN_OPS = frozenset({"filter", "sort", "limit", "project"})
+COST_HINTS = frozenset({"low", "medium", "high"})
+
+Props = dict[str, list[Term]]
+
+
+def _one(props: Props, name: str, subject: str) -> Term | None:
+    values = props.get(AC + name, [])
+    if len(values) > 1:
+        raise AccessContractError(f"{subject}: ac:{name} appears more than once")
+    return values[0] if values else None
+
+
+def text(props: Props, name: str, subject: str) -> str:
+    """Return a required non-empty string property."""
+    value = _one(props, name, subject)
+    if not isinstance(value, str) or not value.strip():
+        raise AccessContractError(f"{subject}: missing ac:{name}")
+    return value
+
+
+def integer(props: Props, name: str, subject: str) -> int | None:
+    """Return an optional non-negative integer property."""
+    value = _one(props, name, subject)
+    if value is not None and (not isinstance(value, int) or value < 0):
+        raise AccessContractError(
+            f"{subject}: ac:{name} must be a non-negative integer"
+        )
+    return value
+
+
+def choice(
+    props: Props,
+    name: str,
+    subject: str,
+    *,
+    allowed: frozenset[str],
+    default: str | None = None,
+) -> str:
+    """Return a property constrained to ``allowed``; ``default`` makes it optional."""
+    raw = _one(props, name, subject) if default is not None else None
+    value = text(props, name, subject) if default is None else str(raw or default)
+    if value not in allowed:
+        raise AccessContractError(f"{subject}: unknown ac:{name} {value!r}")
+    return value
+
+
+def pushdown(props: Props, subject: str) -> frozenset[str]:
+    """Return the declared pushdown operations, refusing unknown ones."""
+    ops = frozenset(str(op) for op in props.get(AC + "pushdown", []))
+    unknown = sorted(ops - PUSHDOWN_OPS)
+    if unknown:
+        raise AccessContractError(f"{subject}: unknown ac:pushdown {unknown}")
+    return ops
+
+
+def parameters(props: Props) -> tuple[str, ...]:
+    """Return the declared operation parameters in sorted order."""
+    return tuple(sorted(str(p) for p in props.get(AC + "parameter", [])))
+
+
+def auth_ref(props: Props, subject: str) -> str | None:
+    """Return a rendered credential reference, refusing a literal secret."""
+    value = _one(props, "authRef", subject)
+    if value is None:
+        return None
+    try:
+        return parse_secret_reference(str(value)).render()
+    except SecretReferenceError:
+        raise AccessContractError(
+            f"{subject}: ac:authRef must be a credential reference, not a secret"
+        ) from None
+
+
+def bindings(graph: dict[str, Props], contract: str) -> tuple[tuple[str, str], ...]:
+    """Return the sorted (property, field) pairs bound to ``contract``."""
+    pairs = []
+    for subject, props in graph.items():
+        if contract in props.get(AC + "contract", []):
+            prop = text(props, "property", subject)
+            pairs.append((prop, text(props, "field", subject)))
+    return tuple(sorted(pairs))

agent_connector_sdk/_turtle.py

@@ -0,0 +1,116 @@
+"""Flat Turtle reader used by the access-contract parser.
+
+It tokenizes one restricted profile (see :mod:`agent_connector_sdk.access_contract`)
+and raises :class:`AccessContractError` on anything outside it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+
+RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
+
+_TOKEN_RE = re.compile(
+    r"(?P<ws>\s+|#[^\n]*)"
+    r"|(?P<iri><[^<>\s]*>)"
+    r'|(?P<str>"(?:[^"\\\n]|\\.)*")'
+    r"|(?P<int>-?\d+)"
+    r"|(?P<prefix>@prefix)"
+    r"|(?P<pname>[A-Za-z_]?[\w-]*:(?:[\w-](?:[\w.-]*[\w-])?)?)"
+    r"|(?P<a>a(?=\s))"
+    r"|(?P<punct>[;,.])"
+)
+
+Term = str | int
+Triple = tuple[str, str, Term]
+
+
+class AccessContractError(ValueError):
+    """A connector ontology declares an invalid access contract."""
+
+
+def _tokens(text: str) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    pos = 0
+    while pos < len(text):
+        match = _TOKEN_RE.match(text, pos)
+        if match is None or match.end() == pos:
+            raise AccessContractError(f"unsupported Turtle at offset {pos}")
+        kind = match.lastgroup or ""
+        if kind != "ws":
+            out.append((kind, match.group()))
+        pos = match.end()
+    return out
+
+
+class _Reader:
+    def __init__(self, text: str) -> None:
+        self.toks = _tokens(text)
+        self.pos = 0
+        self.prefixes: dict[str, str] = {}
+        self.triples: list[Triple] = []
+
+    def next(self) -> tuple[str, str]:
+        if self.pos >= len(self.toks):
+            raise AccessContractError("unexpected end of Turtle")
+        self.pos += 1
+        return self.toks[self.pos - 1]
+
+    def expect(self, value: str) -> None:
+        if self.next()[1] != value:
+            raise AccessContractError(f"expected {value!r}")
+
+    def term(self) -> Term:
+        kind, value = self.next()
+        if kind == "iri":
+            return value[1:-1]
+        if kind == "a":
+            return RDF_TYPE
+        if kind == "pname":
+            prefix, _, local = value.partition(":")
+            if prefix not in self.prefixes:
+                raise AccessContractError(f"undeclared prefix {prefix!r}")
+            return self.prefixes[prefix] + local
+        if kind == "str":
+            return value[1:-1].replace('\\"', '"').replace("\\\\", "\\")
+        if kind == "int":
+            return int(value)
+        raise AccessContractError(f"unexpected token {value!r}")
+
+    def prefix(self) -> None:
+        kind, name = self.next()
+        iri = self.next()
+        if kind != "pname" or not name.endswith(":") or iri[0] != "iri":
+            raise AccessContractError("malformed @prefix")
+        self.prefixes[name[:-1]] = iri[1][1:-1]
+        self.expect(".")
+
+    def statement(self) -> None:
+        subject = str(self.term())
+        sep = ";"
+        while sep == ";":
+            predicate = str(self.term())
+            sep = ","
+            while sep == ",":
+                self.triples.append((subject, predicate, self.term()))
+                sep = self.next()[1]
+        if sep != ".":
+            raise AccessContractError("statement must end with '.'")
+
+    def read(self) -> list[Triple]:
+        while self.pos < len(self.toks):
+            if self.toks[self.pos][0] == "prefix":
+                self.pos += 1
+                self.prefix()
+            else:
+                self.statement()
+        return self.triples
+
+
+def parse_graph(text: str) -> dict[str, dict[str, list[Term]]]:
+    """Read flat Turtle into a subject -> predicate -> objects index."""
+    graph: dict[str, dict[str, list[Term]]] = defaultdict(lambda: defaultdict(list))
+    for subject, predicate, obj in _Reader(text).read():
+        graph[subject][predicate].append(obj)
+    return graph

agent_connector_sdk/_version.py

@@ -0,0 +1,3 @@
+"""Single source of the package version (read by setuptools and bump2version)."""
+
+__version__ = "0.1.0"

agent_connector_sdk/access_contract.py

@@ -0,0 +1,125 @@
+"""Connector access contracts: how each ontology class is answered live.
+
+A connector ontology declares ``ac:AccessContract`` subjects with the
+vocabulary in ``ontology/access_contract.ttl`` (SDK-CONNECTOR-CONTROL-R021).
+:func:`parse_access_contracts` reads them into typed :class:`AccessContract`
+values. It refuses a missing operation, an unknown access kind, pagination
+or pushdown operation, and an ``ac:authRef`` that is not a credential
+reference. A literal secret therefore never becomes a contract.
+
+The parser reads the flat Turtle profile: ``@prefix`` lines, prefixed names,
+``<IRIs>``, ``a``, string and integer literals, and ``;`` ``,`` ``.``.
+Blank nodes and collections are refused.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import resources
+
+from . import _contract_fields as f
+from ._contract_fields import (
+    AC,
+    ACCESS_KINDS,
+    COST_HINTS,
+    PAGINATION_MODES,
+    PUSHDOWN_OPS,
+)
+from ._turtle import RDF_TYPE, AccessContractError, parse_graph
+
+__all__ = [
+    "AC",
+    "ACCESS_KINDS",
+    "PAGINATION_MODES",
+    "PUSHDOWN_OPS",
+    "AccessContract",
+    "AccessContractError",
+    "access_contract_vocabulary",
+    "parse_access_contracts",
+]
+
+
+@dataclass(frozen=True)
+class AccessContract:
+    """One ontology class bound to one live source operation.
+
+    ``source_id``, ``entity``, ``class_iri``, ``key_field`` and ``predicates``
+    match the agent-utilities ``VirtualMapping`` fields of the same name.
+    """
+
+    contract_iri: str
+    class_iri: str
+    source_id: str
+    entity: str
+    key_field: str
+    access_kind: str
+    operation: str
+    parameters: tuple[str, ...] = ()
+    pagination: str = "none"
+    pushdown: frozenset[str] = field(default_factory=frozenset)
+    auth_ref: str | None = None
+    rate_limit_per_minute: int | None = None
+    freshness_seconds: int | None = None
+    cost_hint: str = "unknown"
+    predicates: tuple[tuple[str, str], ...] = ()
+
+    def virtual_mapping_fields(self) -> dict[str, object]:
+        """Return the keyword arguments of an unapproved ``VirtualMapping``."""
+        return {
+            "mapping_id": self.contract_iri,
+            "source_id": self.source_id,
+            "entity": self.entity,
+            "class_iri": self.class_iri,
+            "key_field": self.key_field,
+            "predicates": self.predicates,
+        }
+
+
+def access_contract_vocabulary() -> str:
+    """Return the packaged access-contract vocabulary as Turtle text."""
+    path = resources.files("agent_connector_sdk") / "ontology" / "access_contract.ttl"
+    return path.read_text(encoding="utf-8")
+
+
+def _contract(graph: dict[str, f.Props], subject: str) -> AccessContract:
+    props = graph[subject]
+    return AccessContract(
+        contract_iri=subject,
+        class_iri=f.text(props, "classIri", subject),
+        source_id=f.text(props, "sourceId", subject),
+        entity=f.text(props, "entity", subject),
+        key_field=f.text(props, "keyField", subject),
+        access_kind=f.choice(props, "accessKind", subject, allowed=ACCESS_KINDS),
+        operation=f.text(props, "operation", subject),
+        parameters=f.parameters(props),
+        pagination=f.choice(
+            props, "pagination", subject, allowed=PAGINATION_MODES, default="none"
+        ),
+        pushdown=f.pushdown(props, subject),
+        auth_ref=f.auth_ref(props, subject),
+        rate_limit_per_minute=f.integer(props, "rateLimitPerMinute", subject),
+        freshness_seconds=f.integer(props, "freshnessSeconds", subject),
+        cost_hint=f.choice(
+            props,
+            "costHint",
+            subject,
+            allowed=COST_HINTS | {"unknown"},
+            default="unknown",
+        ),
+        predicates=f.bindings(graph, subject),
+    )
+
+
+def parse_access_contracts(turtle: str) -> tuple[AccessContract, ...]:
+    """Parse every ``ac:AccessContract`` declared in one connector ontology.
+
+    Raises:
+        AccessContractError: for unsupported Turtle or an invalid contract.
+    """
+    graph = parse_graph(turtle)
+    subjects = sorted(
+        s
+        for s, props in graph.items()
+        if AC + "AccessContract" in props.get(RDF_TYPE, [])
+    )
+    return tuple(_contract(graph, s) for s in subjects)

agent_connector_sdk/adapters/__init__.py

@@ -0,0 +1 @@
+"""Reference source adapters (``agent_connector_sdk.source_adapters`` entry points)."""

agent_connector_sdk/adapters/event_envelope.py

@@ -0,0 +1,109 @@
+"""The operational event envelope (SDK-OBSERVABILITY-FEEDS-R001).
+
+RUM, security-audit and CI/CD events carry one standard envelope before they
+are mapped into a generated ``SourceRecord``: stable identity, a three-point
+time basis, actor/target references, a privacy label, retention metadata and
+a payload digest. Validating the envelope does not interpret the event as a
+verified incident, vulnerability, release, or user outcome; that conclusion
+belongs to graph-side policy and analysis.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from enum import StrEnum
+
+from pydantic import (
+    AwareDatetime,
+    BaseModel,
+    ConfigDict,
+    Field,
+    JsonValue,
+    model_validator,
+)
+
+__all__ = [
+    "EventEnvelope",
+    "FeedKind",
+    "VisibilityLabel",
+    "compute_payload_digest",
+]
+
+
+class FeedKind(StrEnum):
+    """The three operational feed kinds SDK-OBSERVABILITY-FEEDS-R001 admits."""
+
+    RUM = "rum"
+    SECURITY_AUDIT = "security_audit"
+    CI_CD = "ci_cd"
+
+
+class VisibilityLabel(StrEnum):
+    """The sensitivity label every event envelope must carry."""
+
+    PUBLIC = "public"
+    INTERNAL = "internal"
+    RESTRICTED = "restricted"
+    SENSITIVE = "sensitive"
+
+
+def compute_payload_digest(payload: Mapping[str, JsonValue]) -> str:
+    """The SDK-owned sha256 of an event payload's canonical JSON encoding.
+
+    The digest is always computed here, never trusted from the provider: it
+    is what makes a repeated event id with an unchanged payload idempotent
+    and a repeated id with a changed payload a detectable conflict.
+    """
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+class EventEnvelope(BaseModel):
+    """The standard shape every operational event carries into the pipeline.
+
+    Missing required identity or an impossible time order fails construction
+    instead of being patched with the current time.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    tenant_id: str = Field(min_length=1)
+    source: str = Field(min_length=1)
+    stream: str = Field(min_length=1)
+    feed_kind: FeedKind
+    event_kind: str = Field(min_length=1)
+    schema_version: str = Field(min_length=1)
+    provider_event_id: str | None = None
+    canonical_source_digest: str | None = None
+    event_time: AwareDatetime
+    source_observed_time: AwareDatetime
+    ingest_time: AwareDatetime
+    actor_ref: str = Field(min_length=1)
+    target_ref: str = Field(min_length=1)
+    trace_id: str | None = None
+    visibility_label: VisibilityLabel
+    license: str | None = None
+    retention_expires_at: AwareDatetime | None = None
+    payload: dict[str, JsonValue]
+    payload_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+    @property
+    def identity(self) -> str:
+        """The event's stable identity: its provider id, or its canonical digest."""
+        return self.provider_event_id or self.canonical_source_digest or ""
+
+    @model_validator(mode="after")
+    def _check_identity_and_time_basis(self) -> EventEnvelope:
+        if not (self.provider_event_id or self.canonical_source_digest):
+            raise ValueError(
+                "event envelope needs a provider_event_id or canonical_source_digest"
+            )
+        if self.event_time > self.source_observed_time:
+            raise ValueError("event_time is after source_observed_time")
+        if self.source_observed_time > self.ingest_time:
+            raise ValueError("source_observed_time is after ingest_time")
+        if self.payload_digest != compute_payload_digest(self.payload):
+            raise ValueError("payload_digest does not match its payload")
+        return self

agent_connector_sdk/adapters/event_errors.py

@@ -0,0 +1,51 @@
+"""Typed failures specific to operational event feeds (SDK-OBSERVABILITY-FEEDS-R001).
+
+These sit beside the generic :mod:`agent_connector_sdk.ports.errors` taxonomy:
+a conflicting duplicate is still malformed source data, and backpressure or an
+expired retention window are still the live source failing its contract, but
+callers need to distinguish them from the generic cases to log and retry
+correctly.
+"""
+
+from __future__ import annotations
+
+from agent_connector_sdk.ports.errors import (
+    MalformedSourceDataError,
+    SourceContractError,
+)
+
+__all__ = [
+    "EventIdentityConflictError",
+    "FeedBackpressureError",
+    "FeedRetentionExpiredError",
+]
+
+
+class EventIdentityConflictError(MalformedSourceDataError):
+    """A repeated event id arrived with a changed payload digest.
+
+    A conflict is refused rather than silently overwriting the earlier
+    version: the provider must emit a new identity for a changed event.
+    """
+
+
+class FeedBackpressureError(SourceContractError):
+    """The provider signaled rate limiting (HTTP 429) or an outage.
+
+    ``retry_after_seconds`` is advisory and is never used to fabricate a
+    completed page or to advance the checkpoint.
+    """
+
+    def __init__(
+        self, message: str, *, retry_after_seconds: float | None = None
+    ) -> None:
+        super().__init__(message)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class FeedRetentionExpiredError(SourceContractError):
+    """The checkpoint position fell outside the provider's retention window.
+
+    The checkpoint cannot resume from where it left off; the stream needs an
+    explicit re-baseline, which is outside this adapter's authority.
+    """