gatecore-langchain 0.1.0__py3-none-any.whl

gatecore_langchain/__init__.py

@@ -0,0 +1,18 @@
+from .config import GateCoreConfig
+from .exceptions import (
+    GateCoreConfigError,
+    GateCoreProcurementDenied,
+    GateCoreProcurementPending,
+)
+from .execution import aexecute_procured, execute_procured
+from .toolkit import GateCoreToolkit
+
+__all__ = [
+    "GateCoreConfig",
+    "GateCoreConfigError",
+    "GateCoreProcurementDenied",
+    "GateCoreProcurementPending",
+    "GateCoreToolkit",
+    "aexecute_procured",
+    "execute_procured",
+]

gatecore_langchain/config.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from .exceptions import GateCoreConfigError
+
+
+@dataclass(frozen=True)
+class GateCoreConfig:
+    mcp_url: str | None = None
+    mcp_key: str | None = field(default=None, repr=False)
+    gateway_url: str | None = None
+    bearer_token: str | None = field(default=None, repr=False)
+    agent_id: str | None = None
+    access_grant_id: str | None = None
+    key_id: str | None = None
+    private_key_pem: str | None = field(default=None, repr=False)
+    private_key_path: str | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_env(cls) -> "GateCoreConfig":
+        return cls(
+            mcp_url=os.getenv("GATECORE_MCP_URL"),
+            mcp_key=os.getenv("GATECORE_MCP_KEY"),
+            gateway_url=os.getenv("GATECORE_GATEWAY_URL"),
+            bearer_token=os.getenv("GATECORE_BEARER_TOKEN"),
+            agent_id=os.getenv("GATECORE_AGENT_ID"),
+            access_grant_id=os.getenv("GATECORE_ACCESS_GRANT_ID"),
+            key_id=os.getenv("GATECORE_KEY_ID"),
+            private_key_pem=os.getenv("GATECORE_PRIVATE_KEY_PEM"),
+            private_key_path=os.getenv("GATECORE_PRIVATE_KEY_PATH"),
+        )
+
+    def require_mcp(self) -> tuple[str, str]:
+        mcp_url = _url(self.mcp_url, "GATECORE_MCP_URL")
+        mcp_key = _required(self.mcp_key, "GATECORE_MCP_KEY")
+        if not mcp_key.startswith("gcmk_"):
+            raise GateCoreConfigError("GATECORE_MCP_KEY is invalid")
+        return mcp_url, mcp_key
+
+    def require_execute(self) -> tuple[str, str, str, str, str, str]:
+        gateway_url = _url(self.gateway_url, "GATECORE_GATEWAY_URL")
+        bearer_token = _required(self.bearer_token, "GATECORE_BEARER_TOKEN")
+        agent_id = _required(self.agent_id, "GATECORE_AGENT_ID")
+        access_grant_id = _required(self.access_grant_id, "GATECORE_ACCESS_GRANT_ID")
+        key_id = _required(self.key_id, "GATECORE_KEY_ID")
+
+        if bool(self.private_key_pem) == bool(self.private_key_path):
+            raise GateCoreConfigError(
+                "exactly one of GATECORE_PRIVATE_KEY_PEM or GATECORE_PRIVATE_KEY_PATH is required"
+            )
+        if self.private_key_pem:
+            private_key = self.private_key_pem
+        else:
+            try:
+                private_key = Path(self.private_key_path or "").read_text()
+            except (OSError, UnicodeError) as exc:
+                raise GateCoreConfigError("GATECORE_PRIVATE_KEY_PATH is invalid") from exc
+        if not private_key.strip():
+            variable = (
+                "GATECORE_PRIVATE_KEY_PEM"
+                if self.private_key_pem is not None
+                else "GATECORE_PRIVATE_KEY_PATH"
+            )
+            raise GateCoreConfigError(f"{variable} is invalid")
+        return gateway_url, bearer_token, agent_id, access_grant_id, key_id, private_key
+
+
+def _required(value: str | None, variable: str) -> str:
+    if value is None or not value.strip():
+        raise GateCoreConfigError(f"{variable} is required")
+    return value.strip()
+
+
+def _url(value: str | None, variable: str) -> str:
+    normalized = _required(value, variable)
+    parsed = urlsplit(normalized)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise GateCoreConfigError(f"{variable} is invalid")
+    return normalized

gatecore_langchain/exceptions.py

@@ -0,0 +1,14 @@
+class GateCoreConfigError(RuntimeError):
+    """GateCore adapter configuration is missing or invalid."""
+
+
+class GateCoreProcurementPending(RuntimeError):
+    """The procurement requires operator review before it can execute."""
+
+    def __init__(self, procurement_id: str | None):
+        self.procurement_id = procurement_id
+        super().__init__("GateCore procurement is pending review")
+
+
+class GateCoreProcurementDenied(RuntimeError):
+    """The procurement was denied or did not yield an executable delegation."""

gatecore_langchain/execution.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from typing import Any
+
+import httpx
+from gatecore_sdk._common.client import GateCoreClient
+
+from .config import GateCoreConfig
+from .exceptions import (
+    GateCoreConfigError,
+    GateCoreProcurementDenied,
+    GateCoreProcurementPending,
+)
+
+_CLAIM_FIELDS = ("target_type", "target_id", "operation", "max_price_cents", "currency")
+
+
+def execute_procured(
+    procure_result: dict,
+    payload: dict,
+    *,
+    context: dict | None = None,
+    config: GateCoreConfig | None = None,
+) -> dict:
+    """Execute a PROCURE decision once through the signed GateCore gateway path."""
+    client, request = _signed_request(procure_result, payload, context, config)
+    return client.execute(request)
+
+
+async def aexecute_procured(
+    procure_result: dict,
+    payload: dict,
+    *,
+    context: dict | None = None,
+    config: GateCoreConfig | None = None,
+) -> dict:
+    """Async twin of :func:`execute_procured`; performs one request and never retries."""
+    client, request = _signed_request(procure_result, payload, context, config)
+    async with httpx.AsyncClient(timeout=10.0) as http:
+        response = await http.post(
+            f"{client.base_url}/v1/execute",
+            json=request,
+            headers=client.headers,
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def _signed_request(
+    procure_result: dict,
+    payload: dict,
+    context: dict | None,
+    config: GateCoreConfig | None,
+) -> tuple[GateCoreClient, dict[str, Any]]:
+    delegation = procure_result.get("gateway_delegation") or {}
+    procurement_id = delegation.get("procurement_id") or procure_result.get("procurement_id")
+    if procure_result.get("action") == "REVIEW":
+        raise GateCoreProcurementPending(procurement_id)
+    token = delegation.get("delegation_token")
+    if procure_result.get("action") != "PROCURE" or not isinstance(token, str) or not token:
+        raise GateCoreProcurementDenied(
+            "GateCore procurement was denied or has no delegation token"
+        )
+
+    claims = _decode_claims(token)
+    cfg = config or GateCoreConfig.from_env()
+    (
+        gateway_url,
+        bearer_token,
+        agent_id,
+        access_grant_id,
+        key_id,
+        private_key,
+    ) = cfg.require_execute()
+    client = GateCoreClient(base_url=gateway_url, bearer_token=bearer_token)
+    request_context = dict(context or {})
+    request_context["delegation_token"] = token
+    request = client.build_request(
+        origin_entity_id=agent_id,
+        target_type=claims["target_type"],
+        target_id=claims["target_id"],
+        operation=claims["operation"],
+        payload=payload,
+        context=request_context,
+        max_price_cents=claims["max_price_cents"],
+        access_grant_id=access_grant_id,
+        key_id=key_id,
+    )
+    request["currency"] = claims["currency"]
+    try:
+        request = client.sign_request(request, private_key_pem=private_key)
+    except (TypeError, ValueError, RuntimeError) as exc:
+        variable = (
+            "GATECORE_PRIVATE_KEY_PEM"
+            if cfg.private_key_pem is not None
+            else "GATECORE_PRIVATE_KEY_PATH"
+        )
+        raise GateCoreConfigError(f"{variable} is invalid") from exc
+    return client, request
+
+
+def _decode_claims(token: str) -> dict[str, Any]:
+    try:
+        prefix, claims_part, _signature = token.split(".")
+        if prefix != "GCDT1":
+            raise ValueError
+        padding = "=" * (-len(claims_part) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(claims_part + padding))
+        if not isinstance(claims, dict) or any(field not in claims for field in _CLAIM_FIELDS):
+            raise ValueError
+        return claims
+    except (ValueError, TypeError, binascii.Error, json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise GateCoreProcurementDenied(
+            "GateCore procurement delegation token is malformed"
+        ) from exc

gatecore_langchain/toolkit.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, Type
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from .config import GateCoreConfig
+from .transport import _McpTransport, _sync
+
+
+class _DiscoverInput(BaseModel):
+    query: str | None = None
+    tags: list[str] | None = None
+    max_price_cents: int | None = None
+    min_trust: float | None = None
+
+
+class _GetListingInput(BaseModel):
+    listing_id: str
+
+
+class _ProcureInput(BaseModel):
+    listing_id: str
+    scopes: list[str] | None = None
+    max_price_cents: int | None = None
+
+
+class _GateCoreTool(BaseTool):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    transport: Any = Field(exclude=True, repr=False)
+
+
+class _DiscoverTool(_GateCoreTool):
+    name: str = "gatecore_discover_listings"
+    description: str = "Discover published governed capabilities in the GateCore marketplace."
+    args_schema: Type[BaseModel] = _DiscoverInput
+
+    async def _arun(
+        self,
+        query: str | None = None,
+        tags: list[str] | None = None,
+        max_price_cents: int | None = None,
+        min_trust: float | None = None,
+    ) -> list:
+        return await self.transport.call(
+            "discover_listings",
+            {
+                "query": query,
+                "tags": tags,
+                "max_price_cents": max_price_cents,
+                "min_trust": min_trust,
+            },
+        )
+
+    def _run(self, **kwargs: Any) -> list:
+        return _sync(self._arun(**kwargs))
+
+
+class _GetListingTool(_GateCoreTool):
+    name: str = "gatecore_get_listing"
+    description: str = "Fetch one published GateCore marketplace listing and its governed contract."
+    args_schema: Type[BaseModel] = _GetListingInput
+
+    async def _arun(self, listing_id: str) -> dict:
+        return await self.transport.call("get_listing", {"listing_id": listing_id})
+
+    def _run(self, **kwargs: Any) -> dict:
+        return _sync(self._arun(**kwargs))
+
+
+class _ProcureTool(_GateCoreTool):
+    name: str = "gatecore_procure"
+    description: str = (
+        "Request governed procurement from a public full-mode GateCore MCP endpoint. "
+        "Identity and trust are derived from the configured MCP key."
+    )
+    args_schema: Type[BaseModel] = _ProcureInput
+
+    async def _arun(
+        self,
+        listing_id: str,
+        scopes: list[str] | None = None,
+        max_price_cents: int | None = None,
+    ) -> dict:
+        return await self.transport.call(
+            "procure",
+            {
+                "listing_id": listing_id,
+                "requester_agent_id": "adapter:langchain",
+                "requester_trust": 0.0,
+                "scopes": scopes,
+                "max_price_cents": max_price_cents,
+            },
+        )
+
+    def _run(self, **kwargs: Any) -> dict:
+        return _sync(self._arun(**kwargs))
+
+
+class GateCoreToolkit:
+    """LangChain tools for a public full-mode GateCore MCP endpoint."""
+
+    def __init__(self, config: GateCoreConfig | None = None):
+        self._transport = _McpTransport(config or GateCoreConfig.from_env())
+
+    def get_tools(self) -> list[BaseTool]:
+        return [
+            _DiscoverTool(transport=self._transport),
+            _GetListingTool(transport=self._transport),
+            _ProcureTool(transport=self._transport),
+        ]

gatecore_langchain/transport.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Coroutine
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+from .config import GateCoreConfig
+
+
+class _McpTransport:
+    def __init__(self, config: GateCoreConfig):
+        self._url, self._key = config.require_mcp()
+
+    async def call(self, tool_name: str, arguments: dict[str, Any]) -> Any:
+        headers = {"X-GateCore-MCP-Key": self._key}
+        async with streamablehttp_client(self._url, headers=headers) as (read, write, _):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(tool_name, arguments)
+        blocks = _blocks(result)
+        if getattr(result, "isError", False):
+            message = blocks[0] if blocks else "GateCore MCP tool failed"
+            raise RuntimeError(message if isinstance(message, str) else json.dumps(message))
+        if tool_name == "discover_listings":
+            return blocks
+        return blocks[0] if blocks else None
+
+
+def _blocks(result: Any) -> list[Any]:
+    structured = getattr(result, "structuredContent", None)
+    if isinstance(structured, dict) and set(structured) == {"result"}:
+        value = structured["result"]
+        return value if isinstance(value, list) else [value]
+    blocks: list[Any] = []
+    for item in getattr(result, "content", []) or []:
+        text = getattr(item, "text", None)
+        if text is None:
+            continue
+        try:
+            blocks.append(json.loads(text))
+        except (TypeError, ValueError):
+            blocks.append(text)
+    return blocks
+
+
+def _sync(coro: Coroutine[Any, Any, Any]) -> Any:
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    coro.close()
+    raise RuntimeError("use the async LangChain tool API inside a running event loop")

gatecore_langchain-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: gatecore-langchain
+Version: 0.1.0
+Summary: LangChain tools for GateCore marketplace discovery, procurement, and governed execution
+Author-email: GateCore AI LLC <hello@gatecoreai.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gatecoreai.com
+Project-URL: Repository, https://github.com/GateCoreAI-com/GateCoreAI
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gatecore-sdk<0.2.0,>=0.1.0
+Requires-Dist: httpx<0.29.0,>=0.27.2
+Requires-Dist: langchain-core<1.5.0,>=1.4.9
+Requires-Dist: mcp==1.28.1
+Dynamic: license-file
+
+# gatecore-langchain
+
+`gatecore-langchain` provides three LangChain tools for GateCore marketplace discovery and
+procurement, plus helpers that execute a procured capability through GateCore's signed gateway.
+The adapter contains transport and configuration only; GateCore services enforce identity,
+policy, trust, pricing, funding, delegation, and settlement.
+
+The MCP tools support public `full`-mode GateCore endpoints only. `read` mode passes the server's
+fail-closed procurement error through unchanged. `off` mode is unsupported because it does not
+replace the adapter's legacy placeholder identity with the MCP credential identity.
+
+## Install from the GateCore monorepo
+
+```bash
+python -m pip install -e ./libs/sdk -e ./libs/adapters/gatecore-langchain
+```
+
+## Install from PyPI (effective on publish)
+
+*Effective once `gatecore-sdk` and this package have a real PyPI release — see
+`.github/workflows/publish-pypi.yml`. Until then, use the monorepo install above.*
+
+```bash
+python -m pip install gatecore-langchain
+```
+
+## Configuration
+
+Discovery and procurement require:
+
+```text
+GATECORE_MCP_URL=https://mcp.example.com/mcp
+GATECORE_MCP_KEY=gcmk_...
+```
+
+`execute_procured` and `aexecute_procured` validate these variables lazily on first use:
+
+```text
+GATECORE_GATEWAY_URL=https://api.example.com
+GATECORE_BEARER_TOKEN=...
+GATECORE_AGENT_ID=agent:example
+GATECORE_ACCESS_GRANT_ID=grant:example
+GATECORE_KEY_ID=key:example
+GATECORE_PRIVATE_KEY_PATH=/secure/path/agent-key.pem
+```
+
+Set exactly one of `GATECORE_PRIVATE_KEY_PATH` or `GATECORE_PRIVATE_KEY_PEM`.
+
+## Usage
+
+```python
+from gatecore_langchain import GateCoreToolkit, execute_procured
+
+tools = GateCoreToolkit().get_tools()
+procure_result = tools[2].invoke({"listing_id": "listing:example"})
+decision = execute_procured(procure_result, {"query": "example"})
+```
+
+All tools are async-native through LangChain's async invocation methods. Their synchronous bridge
+uses `asyncio.run()` and therefore must not be called from a thread that already owns a running
+event loop; use `ainvoke()` in async applications.

gatecore_langchain-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gatecore_langchain/__init__.py,sha256=Q4itQagK8Vhx9pnYZEucz85cXMHmlpoW6LbakErEVJw,450
+gatecore_langchain/config.py,sha256=7zvFMxZTb56HTMnP1AJHsUwsdQYz7Q7EF8T21l5M3dM,3408
+gatecore_langchain/exceptions.py,sha256=O6grBxCwfJybd2zcVh4dg1ICmfdCaY714Og0vTz_ydo,523
+gatecore_langchain/execution.py,sha256=IovVW6gQc57K4uoHm29yXl9uyQkvMPCof1rf6Oxkal0,3990
+gatecore_langchain/toolkit.py,sha256=zunZOsz5yoxiF2vDgUBgFcZ_TPtKUoZGz2pi0TqYSIU,3349
+gatecore_langchain/transport.py,sha256=Y9O7n_o9PApbD-dof8di5YkKoiqQcpkPrTVSYjkG3D4,1950
+gatecore_langchain-0.1.0.dist-info/licenses/LICENSE,sha256=B1WbsXkrxx8-VNkK_0d5z6DkwGlsEUBnQj6_ElW3BmE,1072
+gatecore_langchain-0.1.0.dist-info/METADATA,sha256=kXKpQu8Em4JMLAgSHQlKjeJNkuuzgBc6F-eBY7qD3UE,2987
+gatecore_langchain-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gatecore_langchain-0.1.0.dist-info/top_level.txt,sha256=npeyFSUqVoPm7twmpkEysHqcOB5fMDDD-0YL9bQX0Dc,19
+gatecore_langchain-0.1.0.dist-info/RECORD,,

gatecore_langchain-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gatecore_langchain-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GateCore AI LLC
+
+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.

gatecore_langchain-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gatecore_langchain