agent-connector-sdk 0.3.1__tar.gz

agent_connector_sdk-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knuckles Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_connector_sdk-0.3.1/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: agent-connector-sdk
+Version: 0.3.1
+Summary: Connector SDK for the agent-packages fleet: MCP server scaffolding, connector manifests, and typed source/content extension ports
+Author-email: Repository Maintainers <maintainers@knuckles.team>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Knuckles-Team/agent-connector-sdk
+Project-URL: Documentation, https://knuckles-team.github.io/agent-connector-sdk/
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: epistemic-graph<3.0.0,>=2.27.3
+Requires-Dist: mcp-types<3,>=2.3.0
+Requires-Dist: pydantic<3,>=2.14.1
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx2>=2.13.1
+Requires-Dist: anyio>=4.15.1
+Requires-Dist: cryptography>=50.0.2
+Provides-Extra: integrity
+Requires-Dist: rdflib>=7.1.0; extra == "integrity"
+Provides-Extra: mcp
+Requires-Dist: fastmcp<5,>=4.1.0; extra == "mcp"
+Requires-Dist: mcp<3,>=2.3.0; extra == "mcp"
+Provides-Extra: a2a
+Requires-Dist: fasta2a[pydantic-ai]<1.0.0,>=0.6.1; extra == "a2a"
+Requires-Dist: starlette<2,>=1.8.0; extra == "a2a"
+Provides-Extra: feeds
+Requires-Dist: feedparser>=6.0.12; extra == "feeds"
+Provides-Extra: dataprep
+Requires-Dist: pyarrow>=24.0.0; extra == "dataprep"
+Provides-Extra: db
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "db"
+Requires-Dist: PyMySQL>=1.1.1; extra == "db"
+Requires-Dist: pymongo>=4.10.0; extra == "db"
+Requires-Dist: oracledb>=2.5.0; extra == "db"
+Provides-Extra: mssql
+Requires-Dist: pyodbc>=5.2.0; extra == "mssql"
+Provides-Extra: graphql
+Requires-Dist: graphql-core>=3.2.5; extra == "graphql"
+Provides-Extra: market
+Requires-Dist: pandas>=2.2.0; extra == "market"
+Requires-Dist: yfinance>=0.2.50; extra == "market"
+Provides-Extra: stream
+Requires-Dist: websockets>=14.0; extra == "stream"
+Dynamic: license-file
+
+# Agent Connector SDK
+
+<p align="center">
+  <img src="docs/assets/brands/agent-connector-sdk-logo-v1.png" alt="Agent Connector SDK logo" width="180">
+</p>
+
+<p align="center">
+  <b>Build secure connectors once. Serve, synchronize, and write back through one governed contract.</b><br>
+  <sub>The typed source-integration boundary for MCP services and Epistemic Graph.</sub>
+</p>
+
+[![PyPI - Version](https://img.shields.io/pypi/v/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![Build](https://github.com/Knuckles-Team/agent-connector-sdk/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-connector-sdk/actions/workflows/release.yml)
+[![Documentation](https://github.com/Knuckles-Team/agent-connector-sdk/actions/workflows/pages.yml/badge.svg)](https://knuckles-team.github.io/agent-connector-sdk/)
+[![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/forks)
+[![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/graphs/contributors)
+[![GitHub license](https://img.shields.io/github/license/Knuckles-Team/agent-connector-sdk)](LICENSE)
+[![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/commits/main)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/pulls)
+[![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/pulls?q=is%3Apr+is%3Aclosed)
+[![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/issues)
+[![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![PyPI - Downloads](https://img.shields.io/pypi/dd/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![PyPI - License](https://img.shields.io/pypi/l/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![PyPI - Wheel](https://img.shields.io/pypi/wheel/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![PyPI - Implementation](https://img.shields.io/pypi/implementation/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+
+<p align="center">
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/">Documentation</a> ·
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/capabilities/">Capabilities</a> ·
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/extension-ports/">Interfaces</a> ·
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/status/">Status</a>
+</p>
+
+---
+
+## Quick Start
+
+Create a project and install the SDK:
+
+```bash
+uv init --bare demo-connector
+cd demo-connector
+uv add agent-connector-sdk
+uv sync
+uv run connector-sync --help
+```
+
+The command prints the supervised synchronization options without opening a
+source session. Continue with the
+[connector tutorial](https://knuckles-team.github.io/agent-connector-sdk/tutorial/)
+to build and run a one-file MCP connector, observe its health response, add
+declarative content, certify the live schema, and join source synchronization.
+
+## Overview
+
+Agent Connector SDK is the ecosystem's source-integration boundary. It turns
+vendor APIs and domain tools into secure MCP connectors, transports bounded
+source evidence into Epistemic Graph, indexes immutable repository snapshots,
+and applies authorized changes back to source systems.
+
+Connector packages retain vendor behavior. The SDK owns transport, lifecycle,
+certification, and effect execution. Generated Epistemic Graph contracts own
+durable graph records, checkpoints, content identity, and receipts.
+
+Package version: 0.3.1.
+
+## Key Capabilities
+
+- Build FastMCP servers with authentication, safe exposure, health, visibility,
+  rate limits, change subscriptions, and consistent tool surfaces.
+- Publish skills, prompts, ontologies, SHACL shapes, and connector manifests as
+  typed MCP content.
+- Extract bounded source pages and advance checkpoints only from matching
+  durable Epistemic Graph receipts.
+- Import deterministic ConnectorPack archives without copying graph DTOs or
+  digest algorithms into connector packages.
+- Stream authenticated immutable repository snapshots into the generated
+  `IndexRepository` boundary without becoming a semantic writer.
+- Govern write-back through dry-run, authorization, source-version checks,
+  idempotency, and uncertain-effect reconciliation.
+- Certify extension identity, live MCP schemas, pagination, and safety behavior
+  before activation.
+
+## Documentation
+
+Start with [Build the operator's first connector](https://knuckles-team.github.io/agent-connector-sdk/tutorial/),
+then choose the reference that matches the work:
+
+- [Documentation home](https://knuckles-team.github.io/agent-connector-sdk/)
+- [Capabilities](https://knuckles-team.github.io/agent-connector-sdk/capabilities/)
+- [Architecture](https://knuckles-team.github.io/agent-connector-sdk/architecture/)
+- [Connector servers](https://knuckles-team.github.io/agent-connector-sdk/connector-servers/)
+- [Schema disclosure](https://knuckles-team.github.io/agent-connector-sdk/schema-disclosure/)
+- [Source synchronization](https://knuckles-team.github.io/agent-connector-sdk/connector-sync/)
+- [Repository ingestion](https://knuckles-team.github.io/agent-connector-sdk/repository-ingestion/)
+- [Extension interfaces](https://knuckles-team.github.io/agent-connector-sdk/extension-ports/)
+- [Current status](https://knuckles-team.github.io/agent-connector-sdk/status/)
+
+Sibling authorities: [Epistemic Graph](https://knuckles-team.github.io/epistemic-graph/)
+owns durable graph state and generated contracts; [Arbora](https://knuckles-team.github.io/arbora/)
+owns authenticated runtime composition.
+
+## Architecture
+
+![Runtime architecture: people and clients enter through Arbora. Source systems flow through Agent Connector SDK into Epistemic Graph.](https://raw.githubusercontent.com/Knuckles-Team/epistemic-graph/main/docs/assets/runtime-architecture.svg)
+
+| Boundary | Owned here | Owned elsewhere |
+|---|---|---|
+| Connector service | MCP lifecycle, exposure policy, content capture, certification | Vendor models and business semantics stay in the connector package. |
+| Source ingest | Discovery, bounded extraction, transport, receipt verification | Epistemic Graph owns mapping, checkpoints, provenance, and commit receipts. |
+| Repository ingest | Authenticated snapshots, stable manifests, bounded object transport | Epistemic Graph owns indexing, graph projection, and semantic interpretation. |
+| Write-back | Preview, source-version checks, apply, and reconciliation | Epistemic Graph owns change sets, authorization decisions, and durable outcomes. |
+| Runtime composition | Typed ports and checked dependency requirements | Arbora supplies authenticated identity, clients, and live authority. |
+
+The SDK depends directly on `epistemic-graph>=2.27.0`. Generated SourceIngest,
+ConnectorPack, IndexRepository, and WriteBack clients and models are the graph
+boundary; the SDK adds no parallel graph contract.
+
+## Contributing
+
+Issues and pull requests are welcome. Follow [AGENTS.md](AGENTS.md) for ownership,
+isolation, and validation rules, and run the affected tests and public-surface
+gates before submitting a change.
+
+## License
+
+Agent Connector SDK is released under the [MIT License](LICENSE).

agent_connector_sdk-0.3.1/README.md

@@ -0,0 +1,132 @@
+# Agent Connector SDK
+
+<p align="center">
+  <img src="docs/assets/brands/agent-connector-sdk-logo-v1.png" alt="Agent Connector SDK logo" width="180">
+</p>
+
+<p align="center">
+  <b>Build secure connectors once. Serve, synchronize, and write back through one governed contract.</b><br>
+  <sub>The typed source-integration boundary for MCP services and Epistemic Graph.</sub>
+</p>
+
+[![PyPI - Version](https://img.shields.io/pypi/v/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![Build](https://github.com/Knuckles-Team/agent-connector-sdk/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-connector-sdk/actions/workflows/release.yml)
+[![Documentation](https://github.com/Knuckles-Team/agent-connector-sdk/actions/workflows/pages.yml/badge.svg)](https://knuckles-team.github.io/agent-connector-sdk/)
+[![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/forks)
+[![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/graphs/contributors)
+[![GitHub license](https://img.shields.io/github/license/Knuckles-Team/agent-connector-sdk)](LICENSE)
+[![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/commits/main)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/pulls)
+[![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/pulls?q=is%3Apr+is%3Aclosed)
+[![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk/issues)
+[![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/agent-connector-sdk)](https://github.com/Knuckles-Team/agent-connector-sdk)
+[![PyPI - Downloads](https://img.shields.io/pypi/dd/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![PyPI - License](https://img.shields.io/pypi/l/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![PyPI - Wheel](https://img.shields.io/pypi/wheel/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+[![PyPI - Implementation](https://img.shields.io/pypi/implementation/agent-connector-sdk)](https://pypi.org/project/agent-connector-sdk/)
+
+<p align="center">
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/">Documentation</a> ·
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/capabilities/">Capabilities</a> ·
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/extension-ports/">Interfaces</a> ·
+  <a href="https://knuckles-team.github.io/agent-connector-sdk/status/">Status</a>
+</p>
+
+---
+
+## Quick Start
+
+Create a project and install the SDK:
+
+```bash
+uv init --bare demo-connector
+cd demo-connector
+uv add agent-connector-sdk
+uv sync
+uv run connector-sync --help
+```
+
+The command prints the supervised synchronization options without opening a
+source session. Continue with the
+[connector tutorial](https://knuckles-team.github.io/agent-connector-sdk/tutorial/)
+to build and run a one-file MCP connector, observe its health response, add
+declarative content, certify the live schema, and join source synchronization.
+
+## Overview
+
+Agent Connector SDK is the ecosystem's source-integration boundary. It turns
+vendor APIs and domain tools into secure MCP connectors, transports bounded
+source evidence into Epistemic Graph, indexes immutable repository snapshots,
+and applies authorized changes back to source systems.
+
+Connector packages retain vendor behavior. The SDK owns transport, lifecycle,
+certification, and effect execution. Generated Epistemic Graph contracts own
+durable graph records, checkpoints, content identity, and receipts.
+
+Package version: 0.3.1.
+
+## Key Capabilities
+
+- Build FastMCP servers with authentication, safe exposure, health, visibility,
+  rate limits, change subscriptions, and consistent tool surfaces.
+- Publish skills, prompts, ontologies, SHACL shapes, and connector manifests as
+  typed MCP content.
+- Extract bounded source pages and advance checkpoints only from matching
+  durable Epistemic Graph receipts.
+- Import deterministic ConnectorPack archives without copying graph DTOs or
+  digest algorithms into connector packages.
+- Stream authenticated immutable repository snapshots into the generated
+  `IndexRepository` boundary without becoming a semantic writer.
+- Govern write-back through dry-run, authorization, source-version checks,
+  idempotency, and uncertain-effect reconciliation.
+- Certify extension identity, live MCP schemas, pagination, and safety behavior
+  before activation.
+
+## Documentation
+
+Start with [Build the operator's first connector](https://knuckles-team.github.io/agent-connector-sdk/tutorial/),
+then choose the reference that matches the work:
+
+- [Documentation home](https://knuckles-team.github.io/agent-connector-sdk/)
+- [Capabilities](https://knuckles-team.github.io/agent-connector-sdk/capabilities/)
+- [Architecture](https://knuckles-team.github.io/agent-connector-sdk/architecture/)
+- [Connector servers](https://knuckles-team.github.io/agent-connector-sdk/connector-servers/)
+- [Schema disclosure](https://knuckles-team.github.io/agent-connector-sdk/schema-disclosure/)
+- [Source synchronization](https://knuckles-team.github.io/agent-connector-sdk/connector-sync/)
+- [Repository ingestion](https://knuckles-team.github.io/agent-connector-sdk/repository-ingestion/)
+- [Extension interfaces](https://knuckles-team.github.io/agent-connector-sdk/extension-ports/)
+- [Current status](https://knuckles-team.github.io/agent-connector-sdk/status/)
+
+Sibling authorities: [Epistemic Graph](https://knuckles-team.github.io/epistemic-graph/)
+owns durable graph state and generated contracts; [Arbora](https://knuckles-team.github.io/arbora/)
+owns authenticated runtime composition.
+
+## Architecture
+
+![Runtime architecture: people and clients enter through Arbora. Source systems flow through Agent Connector SDK into Epistemic Graph.](https://raw.githubusercontent.com/Knuckles-Team/epistemic-graph/main/docs/assets/runtime-architecture.svg)
+
+| Boundary | Owned here | Owned elsewhere |
+|---|---|---|
+| Connector service | MCP lifecycle, exposure policy, content capture, certification | Vendor models and business semantics stay in the connector package. |
+| Source ingest | Discovery, bounded extraction, transport, receipt verification | Epistemic Graph owns mapping, checkpoints, provenance, and commit receipts. |
+| Repository ingest | Authenticated snapshots, stable manifests, bounded object transport | Epistemic Graph owns indexing, graph projection, and semantic interpretation. |
+| Write-back | Preview, source-version checks, apply, and reconciliation | Epistemic Graph owns change sets, authorization decisions, and durable outcomes. |
+| Runtime composition | Typed ports and checked dependency requirements | Arbora supplies authenticated identity, clients, and live authority. |
+
+The SDK depends directly on `epistemic-graph>=2.27.0`. Generated SourceIngest,
+ConnectorPack, IndexRepository, and WriteBack clients and models are the graph
+boundary; the SDK adds no parallel graph contract.
+
+## Contributing
+
+Issues and pull requests are welcome. Follow [AGENTS.md](AGENTS.md) for ownership,
+isolation, and validation rules, and run the affected tests and public-surface
+gates before submitting a change.
+
+## License
+
+Agent Connector SDK is released under the [MIT License](LICENSE).

agent_connector_sdk-0.3.1/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-0.3.1/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-0.3.1/agent_connector_sdk/_extras.py

@@ -0,0 +1,22 @@
+"""Clear errors for features that need an optional extra of the base install."""
+
+from __future__ import annotations
+
+import importlib
+
+__all__ = ["require_mcp_extra"]
+
+
+def require_mcp_extra(feature: str) -> None:
+    """Raise ``ImportError`` naming the ``mcp`` extra when fastmcp or mcp is absent."""
+    missing = []
+    for name in ("fastmcp", "mcp"):
+        try:
+            importlib.import_module(name)
+        except ImportError:
+            missing.append(name)
+    if missing:
+        raise ImportError(
+            f"{feature} needs {' and '.join(missing)}, which the base install of "
+            'agent-connector-sdk leaves out; install "agent-connector-sdk[mcp]"'
+        )

agent_connector_sdk-0.3.1/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-0.3.1/agent_connector_sdk/_version.py

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

agent_connector_sdk-0.3.1/agent_connector_sdk/a2a/__init__.py

@@ -0,0 +1,46 @@
+"""Agent-to-Agent (A2A) protocol pieces any connector or host can reuse.
+
+CONCEPT:SDK-CONNECTOR-CONTROL-R014.21
+
+The base install carries the wire models and the JSON-RPC client (pydantic and
+httpx only). The server-side application factory needs the optional ``a2a``
+extra (fasta2a and starlette); a host such as arbora mounts it behind its own
+admission and authentication. Nothing here stores tasks or builds cards from a
+graph: durable task state and graph-derived cards belong to the host.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import A2AClient, A2AResult
+from .models import (
+    A2AMessage,
+    A2ATask,
+    A2ATaskStatus,
+    AgentCard,
+    AgentSkill,
+    TaskState,
+    TextPart,
+)
+
+__all__ = [
+    "A2AClient",
+    "A2AMessage",
+    "A2AResult",
+    "A2ATask",
+    "A2ATaskStatus",
+    "AgentCard",
+    "AgentSkill",
+    "TaskState",
+    "TextPart",
+    "create_a2a_app",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "create_a2a_app":
+        from .app import create_a2a_app
+
+        return create_a2a_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")