pactspec-langchain 0.1.0__tar.gz

pactspec_langchain-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+/.test-build
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.env.local
+cli/node_modules/
+cli/dist/
+sdk/node_modules/
+sdk/dist/
+packages/*/dist/
+packages/*/node_modules/
+pactspec-py/dist/
+pactspec-py/*.egg-info/
+pactspec-py/__pycache__/
+cli/test-source.*

pactspec_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: pactspec-langchain
+Version: 0.1.0
+Summary: LangChain integration for PactSpec — discover and invoke verified AI agents as LangChain tools
+Project-URL: Homepage, https://pactspec.dev
+Project-URL: Repository, https://github.com/pactspec/pactspec
+Project-URL: Documentation, https://pactspec.dev/docs/integrations/langchain
+Author-email: PactSpec <hello@pactspec.dev>
+License-Expression: MIT
+Keywords: agents,ai,langchain,pactspec,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pactspec>=0.1.0
+Description-Content-Type: text/markdown
+
+# pactspec-langchain
+
+LangChain integration for [PactSpec](https://pactspec.dev) -- discover and invoke verified AI agents as LangChain tools with automatic pricing awareness.
+
+Each skill in a PactSpec agent becomes a LangChain `BaseTool` with its name, description, input schema, and pricing information derived from the spec. The LLM sees pricing in the tool description and can make cost-aware decisions.
+
+## Installation
+
+```bash
+pip install pactspec-langchain
+```
+
+## Quick start
+
+```python
+from pactspec_langchain import PactSpecToolkit
+
+# Discover verified agents for a task
+toolkit = PactSpecToolkit.from_registry(
+    query="invoice processing",
+    verified_only=True,
+    max_price=0.10,
+)
+
+# List what was found
+for tool in toolkit.get_tools():
+    print(f"{tool.name}: {tool.description}")
+```
+
+## Using with a LangChain agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain.agents import create_tool_calling_agent, AgentExecutor
+from pactspec_langchain import PactSpecToolkit
+
+# 1. Discover tools from the registry
+toolkit = PactSpecToolkit.from_registry(
+    query="document analysis",
+    verified_only=True,
+    max_price=0.25,
+)
+
+# 2. Set up the LLM and prompt
+llm = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant. Use the available tools to help the user. "
+               "Pay attention to tool costs and prefer cheaper options when quality is similar."),
+    ("human", "{input}"),
+    MessagesPlaceholder("agent_scratchpad"),
+])
+
+# 3. Create the agent
+agent = create_tool_calling_agent(llm, toolkit.get_tools(), prompt)
+executor = AgentExecutor(agent=agent, tools=toolkit.get_tools(), verbose=True)
+
+# 4. Run it
+result = executor.invoke({"input": "Extract line items from this invoice: ..."})
+print(result["output"])
+```
+
+## Load a specific agent
+
+If you know the exact agent you want, load it by spec ID:
+
+```python
+toolkit = PactSpecToolkit.from_agent(
+    "urn:pactspec:acme/invoice-agent@1.0.0",
+    auth_headers={"Authorization": "Bearer sk-your-api-key"},
+)
+```
+
+## Filtering
+
+### By price
+
+```python
+# Only tools that cost at most $0.05 per invocation
+toolkit = PactSpecToolkit.from_registry(
+    query="translation",
+    max_price=0.05,
+)
+```
+
+### By pricing model
+
+```python
+# Only free tools
+toolkit = PactSpecToolkit.from_registry(
+    query="summarization",
+    pricing_model="free",
+)
+
+# Only per-token pricing
+toolkit = PactSpecToolkit.from_registry(
+    query="summarization",
+    pricing_model="per-token",
+)
+```
+
+### Verified agents only
+
+```python
+# Only agents that have passed PactSpec verification
+toolkit = PactSpecToolkit.from_registry(
+    query="code review",
+    verified_only=True,
+)
+```
+
+### Combining filters
+
+```python
+toolkit = PactSpecToolkit.from_registry(
+    query="medical coding",
+    verified_only=True,
+    max_price=0.10,
+    pricing_model="per-invocation",
+)
+```
+
+## How pricing appears in tool descriptions
+
+Each tool's description includes pricing and verification status so the LLM can reason about costs:
+
+```
+Extract line items from invoices | Cost: 0.05 USD/per-invocation via stripe | [Verified] | Agent: InvoiceBot v2.1.0
+```
+
+For free tools:
+
+```
+Summarize text documents | Cost: Free | Agent: SummaryAgent v1.0.0
+```
+
+## Authentication
+
+Pass headers for authenticated agent endpoints:
+
+```python
+toolkit = PactSpecToolkit.from_registry(
+    query="invoice processing",
+    auth_headers={
+        "Authorization": "Bearer sk-your-key",
+        "X-API-Key": "your-api-key",
+    },
+)
+```
+
+## Using pre-fetched agents
+
+If you've already fetched agents via the PactSpec Python SDK, avoid a second network call:
+
+```python
+from pactspec import PactSpecClient
+from pactspec_langchain import PactSpecToolkit
+
+client = PactSpecClient()
+result = client.search(q="translation", verified_only=True)
+
+# Pass agent records directly
+toolkit = PactSpecToolkit.from_agents(
+    result.agents,
+    max_price=0.10,
+)
+```
+
+## API reference
+
+### `PactSpecToolkit`
+
+| Method | Description |
+|--------|-------------|
+| `from_registry(query, ...)` | Search the registry and create tools from matching agents |
+| `from_agent(spec_id, ...)` | Create tools from a specific agent by spec ID or UUID |
+| `from_agents(agents, ...)` | Create tools from pre-fetched `AgentRecord` objects |
+| `get_tools()` | Return all tools (standard LangChain toolkit interface) |
+| `get_tool(name)` | Look up a single tool by name |
+| `tool_names` | List of all tool names |
+
+### `PactSpecTool`
+
+Extends `langchain_core.tools.BaseTool`. Each instance wraps a single PactSpec agent skill.
+
+| Attribute | Description |
+|-----------|-------------|
+| `agent_meta` | `AgentMetadata` with agent ID, endpoint, verified status |
+| `skill_meta` | `SkillMetadata` with skill ID, description, pricing, input schema |
+| `timeout` | HTTP timeout in seconds (default: 30) |
+| `auth_headers` | Extra headers sent with every invocation |
+
+## License
+
+MIT

pactspec_langchain-0.1.0/README.md

@@ -0,0 +1,195 @@
+# pactspec-langchain
+
+LangChain integration for [PactSpec](https://pactspec.dev) -- discover and invoke verified AI agents as LangChain tools with automatic pricing awareness.
+
+Each skill in a PactSpec agent becomes a LangChain `BaseTool` with its name, description, input schema, and pricing information derived from the spec. The LLM sees pricing in the tool description and can make cost-aware decisions.
+
+## Installation
+
+```bash
+pip install pactspec-langchain
+```
+
+## Quick start
+
+```python
+from pactspec_langchain import PactSpecToolkit
+
+# Discover verified agents for a task
+toolkit = PactSpecToolkit.from_registry(
+    query="invoice processing",
+    verified_only=True,
+    max_price=0.10,
+)
+
+# List what was found
+for tool in toolkit.get_tools():
+    print(f"{tool.name}: {tool.description}")
+```
+
+## Using with a LangChain agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain.agents import create_tool_calling_agent, AgentExecutor
+from pactspec_langchain import PactSpecToolkit
+
+# 1. Discover tools from the registry
+toolkit = PactSpecToolkit.from_registry(
+    query="document analysis",
+    verified_only=True,
+    max_price=0.25,
+)
+
+# 2. Set up the LLM and prompt
+llm = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant. Use the available tools to help the user. "
+               "Pay attention to tool costs and prefer cheaper options when quality is similar."),
+    ("human", "{input}"),
+    MessagesPlaceholder("agent_scratchpad"),
+])
+
+# 3. Create the agent
+agent = create_tool_calling_agent(llm, toolkit.get_tools(), prompt)
+executor = AgentExecutor(agent=agent, tools=toolkit.get_tools(), verbose=True)
+
+# 4. Run it
+result = executor.invoke({"input": "Extract line items from this invoice: ..."})
+print(result["output"])
+```
+
+## Load a specific agent
+
+If you know the exact agent you want, load it by spec ID:
+
+```python
+toolkit = PactSpecToolkit.from_agent(
+    "urn:pactspec:acme/invoice-agent@1.0.0",
+    auth_headers={"Authorization": "Bearer sk-your-api-key"},
+)
+```
+
+## Filtering
+
+### By price
+
+```python
+# Only tools that cost at most $0.05 per invocation
+toolkit = PactSpecToolkit.from_registry(
+    query="translation",
+    max_price=0.05,
+)
+```
+
+### By pricing model
+
+```python
+# Only free tools
+toolkit = PactSpecToolkit.from_registry(
+    query="summarization",
+    pricing_model="free",
+)
+
+# Only per-token pricing
+toolkit = PactSpecToolkit.from_registry(
+    query="summarization",
+    pricing_model="per-token",
+)
+```
+
+### Verified agents only
+
+```python
+# Only agents that have passed PactSpec verification
+toolkit = PactSpecToolkit.from_registry(
+    query="code review",
+    verified_only=True,
+)
+```
+
+### Combining filters
+
+```python
+toolkit = PactSpecToolkit.from_registry(
+    query="medical coding",
+    verified_only=True,
+    max_price=0.10,
+    pricing_model="per-invocation",
+)
+```
+
+## How pricing appears in tool descriptions
+
+Each tool's description includes pricing and verification status so the LLM can reason about costs:
+
+```
+Extract line items from invoices | Cost: 0.05 USD/per-invocation via stripe | [Verified] | Agent: InvoiceBot v2.1.0
+```
+
+For free tools:
+
+```
+Summarize text documents | Cost: Free | Agent: SummaryAgent v1.0.0
+```
+
+## Authentication
+
+Pass headers for authenticated agent endpoints:
+
+```python
+toolkit = PactSpecToolkit.from_registry(
+    query="invoice processing",
+    auth_headers={
+        "Authorization": "Bearer sk-your-key",
+        "X-API-Key": "your-api-key",
+    },
+)
+```
+
+## Using pre-fetched agents
+
+If you've already fetched agents via the PactSpec Python SDK, avoid a second network call:
+
+```python
+from pactspec import PactSpecClient
+from pactspec_langchain import PactSpecToolkit
+
+client = PactSpecClient()
+result = client.search(q="translation", verified_only=True)
+
+# Pass agent records directly
+toolkit = PactSpecToolkit.from_agents(
+    result.agents,
+    max_price=0.10,
+)
+```
+
+## API reference
+
+### `PactSpecToolkit`
+
+| Method | Description |
+|--------|-------------|
+| `from_registry(query, ...)` | Search the registry and create tools from matching agents |
+| `from_agent(spec_id, ...)` | Create tools from a specific agent by spec ID or UUID |
+| `from_agents(agents, ...)` | Create tools from pre-fetched `AgentRecord` objects |
+| `get_tools()` | Return all tools (standard LangChain toolkit interface) |
+| `get_tool(name)` | Look up a single tool by name |
+| `tool_names` | List of all tool names |
+
+### `PactSpecTool`
+
+Extends `langchain_core.tools.BaseTool`. Each instance wraps a single PactSpec agent skill.
+
+| Attribute | Description |
+|-----------|-------------|
+| `agent_meta` | `AgentMetadata` with agent ID, endpoint, verified status |
+| `skill_meta` | `SkillMetadata` with skill ID, description, pricing, input schema |
+| `timeout` | HTTP timeout in seconds (default: 30) |
+| `auth_headers` | Extra headers sent with every invocation |
+
+## License
+
+MIT

pactspec_langchain-0.1.0/pactspec_langchain/__init__.py

@@ -0,0 +1,27 @@
+"""PactSpec LangChain integration — use PactSpec agents as LangChain tools.
+
+Quick start::
+
+    from pactspec_langchain import PactSpecToolkit
+
+    toolkit = PactSpecToolkit.from_registry(
+        query="invoice processing",
+        verified_only=True,
+        max_price=0.10,
+    )
+    tools = toolkit.get_tools()
+"""
+
+from .toolkit import PactSpecToolkit
+from .tools import PactSpecTool
+from .types import AgentMetadata, SkillMetadata, SkillPricing
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PactSpecToolkit",
+    "PactSpecTool",
+    "AgentMetadata",
+    "SkillMetadata",
+    "SkillPricing",
+]

pactspec_langchain-0.1.0/pactspec_langchain/toolkit.py

@@ -0,0 +1,272 @@
+"""PactSpec LangChain toolkit — discover agents from the registry and use them as tools."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Sequence
+
+from pactspec import PactSpecClient, AgentRecord
+
+from .tools import PactSpecTool
+from .types import AgentMetadata, SkillMetadata, SkillPricing
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_tools_from_agent(
+    agent: AgentRecord,
+    *,
+    max_price: Optional[float] = None,
+    pricing_model: Optional[str] = None,
+    auth_headers: Optional[Dict[str, str]] = None,
+    timeout: float = 30.0,
+) -> List[PactSpecTool]:
+    """Extract PactSpecTool instances from a single AgentRecord.
+
+    Applies pricing / model filters at the skill level.
+    """
+    spec = agent.spec or {}
+    skills: List[Dict[str, Any]] = spec.get("skills", [])
+
+    agent_meta = AgentMetadata(
+        agent_id=agent.id,
+        spec_id=agent.spec_id,
+        name=agent.name,
+        version=agent.version,
+        endpoint_url=agent.endpoint_url,
+        verified=agent.verified,
+        attestation_hash=agent.attestation_hash,
+        provider_name=agent.provider_name,
+    )
+
+    tools: List[PactSpecTool] = []
+    for skill in skills:
+        pricing_raw = skill.get("pricing", {})
+        pricing = SkillPricing.from_dict(pricing_raw)
+
+        # --- filters ---
+        if pricing_model is not None and pricing.model != pricing_model:
+            continue
+
+        if max_price is not None and pricing.model != "free":
+            if pricing.amount > max_price:
+                logger.debug(
+                    "Skipping skill %s: price %.4f > max_price %.4f",
+                    skill.get("id"),
+                    pricing.amount,
+                    max_price,
+                )
+                continue
+
+        skill_meta = SkillMetadata(
+            skill_id=skill.get("id", skill.get("name", "unknown")),
+            skill_name=skill.get("name", skill.get("id", "")),
+            description=skill.get("description", ""),
+            input_schema=skill.get("inputSchema", {}),
+            output_schema=skill.get("outputSchema", {}),
+            pricing=pricing,
+            tags=skill.get("tags", []),
+            examples=skill.get("examples", []),
+        )
+
+        tool = PactSpecTool(
+            agent_meta=agent_meta,
+            skill_meta=skill_meta,
+            timeout=timeout,
+            auth_headers=auth_headers or {},
+        )
+        tools.append(tool)
+
+    return tools
+
+
+class PactSpecToolkit:
+    """Discover PactSpec agents from the registry and expose them as LangChain tools.
+
+    Usage::
+
+        from pactspec_langchain import PactSpecToolkit
+
+        toolkit = PactSpecToolkit.from_registry(
+            query="invoice processing",
+            verified_only=True,
+            max_price=0.10,
+        )
+        tools = toolkit.get_tools()
+
+    Each skill in each matched agent becomes a separate :class:`PactSpecTool`.
+    Pricing information is embedded in the tool description so the LLM can make
+    cost-aware decisions.
+    """
+
+    def __init__(self, tools: List[PactSpecTool]) -> None:
+        self._tools = list(tools)
+
+    # ------------------------------------------------------------------
+    # Factory: search the registry
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_registry(
+        cls,
+        query: str = "",
+        *,
+        verified_only: bool = False,
+        max_price: Optional[float] = None,
+        pricing_model: Optional[str] = None,
+        registry: str = "https://pactspec.dev",
+        limit: int = 10,
+        auth_headers: Optional[Dict[str, str]] = None,
+        timeout: float = 30.0,
+    ) -> "PactSpecToolkit":
+        """Search the PactSpec registry and build tools from matching agents.
+
+        Args:
+            query: Free-text search query (e.g. ``"invoice processing"``).
+            verified_only: Only include agents that have passed verification.
+            max_price: Maximum price per invocation — skills above this are excluded.
+            pricing_model: Only include skills with this pricing model
+                (``"free"``, ``"per-invocation"``, ``"per-token"``, ``"per-second"``).
+            registry: PactSpec registry URL.
+            limit: Maximum number of agents to fetch.
+            auth_headers: Extra HTTP headers to send when invoking agent endpoints
+                (e.g. ``{"Authorization": "Bearer sk-..."}``).
+            timeout: HTTP timeout in seconds for agent invocations.
+
+        Returns:
+            A :class:`PactSpecToolkit` containing one tool per qualifying skill.
+        """
+        client = PactSpecClient(registry=registry)
+        result = client.search(q=query, verified_only=verified_only, limit=limit)
+
+        tools: List[PactSpecTool] = []
+        for agent in result.agents:
+            tools.extend(
+                _extract_tools_from_agent(
+                    agent,
+                    max_price=max_price,
+                    pricing_model=pricing_model,
+                    auth_headers=auth_headers,
+                    timeout=timeout,
+                )
+            )
+
+        logger.info(
+            "PactSpecToolkit.from_registry: query=%r, found %d agents, %d tools",
+            query,
+            len(result.agents),
+            len(tools),
+        )
+        return cls(tools)
+
+    # ------------------------------------------------------------------
+    # Factory: from a specific agent
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_agent(
+        cls,
+        spec_id: str,
+        *,
+        max_price: Optional[float] = None,
+        pricing_model: Optional[str] = None,
+        registry: str = "https://pactspec.dev",
+        auth_headers: Optional[Dict[str, str]] = None,
+        timeout: float = 30.0,
+    ) -> "PactSpecToolkit":
+        """Create tools from a specific agent by its spec ID or registry UUID.
+
+        Args:
+            spec_id: The agent's spec URN (e.g. ``"urn:pactspec:acme/invoice-agent@1.0.0"``)
+                or registry UUID.
+            max_price: Maximum price per invocation.
+            pricing_model: Only include skills with this pricing model.
+            registry: PactSpec registry URL.
+            auth_headers: Extra HTTP headers for agent invocations.
+            timeout: HTTP timeout in seconds for agent invocations.
+
+        Returns:
+            A :class:`PactSpecToolkit` containing one tool per qualifying skill.
+        """
+        client = PactSpecClient(registry=registry)
+        agent = client.get_agent(spec_id)
+
+        tools = _extract_tools_from_agent(
+            agent,
+            max_price=max_price,
+            pricing_model=pricing_model,
+            auth_headers=auth_headers,
+            timeout=timeout,
+        )
+
+        logger.info(
+            "PactSpecToolkit.from_agent: spec_id=%r, %d tools",
+            spec_id,
+            len(tools),
+        )
+        return cls(tools)
+
+    # ------------------------------------------------------------------
+    # Factory: from raw agent dicts (for advanced use)
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_agents(
+        cls,
+        agents: Sequence[AgentRecord],
+        *,
+        max_price: Optional[float] = None,
+        pricing_model: Optional[str] = None,
+        auth_headers: Optional[Dict[str, str]] = None,
+        timeout: float = 30.0,
+    ) -> "PactSpecToolkit":
+        """Create a toolkit from a pre-fetched list of :class:`AgentRecord` objects.
+
+        This is useful when you've already fetched agents and want to avoid
+        a second network call.
+        """
+        tools: List[PactSpecTool] = []
+        for agent in agents:
+            tools.extend(
+                _extract_tools_from_agent(
+                    agent,
+                    max_price=max_price,
+                    pricing_model=pricing_model,
+                    auth_headers=auth_headers,
+                    timeout=timeout,
+                )
+            )
+        return cls(tools)
+
+    # ------------------------------------------------------------------
+    # Tool access
+    # ------------------------------------------------------------------
+
+    def get_tools(self) -> List[PactSpecTool]:
+        """Return all tools in the toolkit.
+
+        This is the standard LangChain toolkit interface used by
+        ``create_tool_calling_agent`` and similar helpers.
+        """
+        return list(self._tools)
+
+    def get_tool(self, name: str) -> Optional[PactSpecTool]:
+        """Look up a single tool by name.
+
+        Returns ``None`` if no tool with that name exists.
+        """
+        for tool in self._tools:
+            if tool.name == name:
+                return tool
+        return None
+
+    @property
+    def tool_names(self) -> List[str]:
+        """List the names of all tools in the toolkit."""
+        return [t.name for t in self._tools]
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __repr__(self) -> str:
+        return f"PactSpecToolkit(tools={self.tool_names})"

pactspec_langchain-0.1.0/pactspec_langchain/tools.py

@@ -0,0 +1,193 @@
+"""PactSpec LangChain tool — wraps a single PactSpec agent skill as a LangChain BaseTool."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, Optional, Type
+
+import httpx
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForToolRun,
+    CallbackManagerForToolRun,
+)
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, model_validator
+
+from .types import AgentMetadata, SkillMetadata, SkillPricing
+
+logger = logging.getLogger(__name__)
+
+
+def _build_pydantic_model_from_json_schema(
+    schema: Dict[str, Any],
+    model_name: str = "DynamicInput",
+) -> Type[BaseModel]:
+    """Build a pydantic model from a JSON Schema dict.
+
+    This creates a model with fields derived from the JSON Schema ``properties``.
+    For properties without an explicit type we fall back to ``Any``.
+    """
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    field_definitions: Dict[str, Any] = {}
+    annotations: Dict[str, Any] = {}
+
+    type_map = {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+        "array": list,
+        "object": dict,
+    }
+
+    for prop_name, prop_schema in properties.items():
+        json_type = prop_schema.get("type", "string")
+        python_type = type_map.get(json_type, Any)
+        description = prop_schema.get("description", "")
+        default = prop_schema.get("default")
+
+        if prop_name in required and default is None:
+            field_definitions[prop_name] = Field(description=description)
+        else:
+            if python_type is Any:
+                annotations[prop_name] = Optional[Any]
+            else:
+                annotations[prop_name] = Optional[python_type]  # type: ignore[assignment]
+            field_definitions[prop_name] = Field(default=default, description=description)
+
+        if prop_name not in annotations:
+            annotations[prop_name] = python_type
+
+    namespace: Dict[str, Any] = {"__annotations__": annotations, **field_definitions}
+    model = type(model_name, (BaseModel,), namespace)
+    return model  # type: ignore[return-value]
+
+
+class PactSpecTool(BaseTool):
+    """A LangChain tool backed by a single PactSpec agent skill.
+
+    Each skill declared in a PactSpec becomes one ``PactSpecTool`` instance.
+    The tool name, description, and input schema are derived from the spec,
+    and the ``_run`` / ``_arun`` methods invoke the agent endpoint directly.
+
+    Pricing information is appended to the tool description so that the LLM
+    can make cost-aware decisions when selecting tools.
+    """
+
+    # --- metadata stored on the tool ---
+    agent_meta: AgentMetadata
+    skill_meta: SkillMetadata
+
+    # --- httpx settings ---
+    timeout: float = 30.0
+    auth_headers: Dict[str, str] = Field(default_factory=dict)
+
+    # These are set via model_validator from the metadata
+    name: str = ""  # type: ignore[assignment]
+    description: str = ""
+
+    args_schema: Optional[Type[BaseModel]] = None  # type: ignore[assignment]
+
+    @model_validator(mode="after")
+    def _set_derived_fields(self) -> "PactSpecTool":
+        # Tool name: use skill_id, sanitised for LangChain (alphanumeric + hyphens/underscores)
+        if not self.name:
+            self.name = self.skill_meta.skill_id.replace(" ", "_")
+
+        # Build a rich description with pricing and verification status
+        if not self.description:
+            parts = [self.skill_meta.description or self.skill_meta.skill_name]
+            pricing_display = self.skill_meta.pricing.display
+            if pricing_display:
+                parts.append(f"Cost: {pricing_display}")
+            if self.agent_meta.verified:
+                parts.append("[Verified]")
+            parts.append(f"Agent: {self.agent_meta.name} v{self.agent_meta.version}")
+            self.description = " | ".join(parts)
+
+        # Build args_schema from the skill's inputSchema
+        if self.args_schema is None and self.skill_meta.input_schema:
+            model_name = (
+                self.skill_meta.skill_id.replace("-", "_").replace(" ", "_").title().replace("_", "")
+                + "Input"
+            )
+            self.args_schema = _build_pydantic_model_from_json_schema(
+                self.skill_meta.input_schema,
+                model_name=model_name,
+            )
+
+        return self
+
+    # ------------------------------------------------------------------
+    # Invocation
+    # ------------------------------------------------------------------
+
+    def _build_url(self) -> str:
+        """Construct the invocation URL for the agent skill."""
+        base = self.agent_meta.endpoint_url.rstrip("/")
+        return base
+
+    def _build_headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        headers.update(self.auth_headers)
+        return headers
+
+    def _handle_response(self, response: httpx.Response) -> str:
+        """Process the HTTP response and return a string for the LLM."""
+        if response.status_code == 402:
+            try:
+                detail = response.json()
+            except Exception:
+                detail = response.text
+            return f"Payment required for this agent skill. Details: {detail}"
+
+        response.raise_for_status()
+
+        # Try to return formatted JSON; fall back to raw text
+        content_type = response.headers.get("content-type", "")
+        if "json" in content_type:
+            try:
+                return json.dumps(response.json(), indent=2)
+            except Exception:
+                pass
+        return response.text
+
+    def _run(
+        self,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Synchronously invoke the PactSpec agent skill."""
+        url = self._build_url()
+        headers = self._build_headers()
+        logger.debug("PactSpecTool %s: POST %s with %s", self.name, url, kwargs)
+
+        response = httpx.post(
+            url,
+            json=kwargs,
+            headers=headers,
+            timeout=self.timeout,
+        )
+        return self._handle_response(response)
+
+    async def _arun(
+        self,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Asynchronously invoke the PactSpec agent skill."""
+        url = self._build_url()
+        headers = self._build_headers()
+        logger.debug("PactSpecTool %s: async POST %s with %s", self.name, url, kwargs)
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                json=kwargs,
+                headers=headers,
+                timeout=self.timeout,
+            )
+        return self._handle_response(response)

pactspec_langchain-0.1.0/pactspec_langchain/types.py

@@ -0,0 +1,64 @@
+"""Type definitions for the PactSpec LangChain integration."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SkillPricing(BaseModel):
+    """Pricing information extracted from a PactSpec skill."""
+
+    model: str = "free"
+    amount: float = 0.0
+    currency: str = "USD"
+    protocol: Optional[str] = None
+
+    @property
+    def display(self) -> str:
+        """Human-readable pricing string for tool descriptions."""
+        if self.model == "free":
+            return "Free"
+        parts = [f"{self.amount} {self.currency}/{self.model}"]
+        if self.protocol and self.protocol != "none":
+            parts.append(f"via {self.protocol}")
+        return " ".join(parts)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SkillPricing":
+        """Parse pricing from a raw PactSpec skill pricing dict."""
+        if not data:
+            return cls()
+        return cls(
+            model=data.get("model", "free"),
+            amount=data.get("amount", 0.0),
+            currency=data.get("currency", "USD"),
+            protocol=data.get("protocol"),
+        )
+
+
+class SkillMetadata(BaseModel):
+    """Metadata about a PactSpec skill used to construct a LangChain tool."""
+
+    skill_id: str
+    skill_name: str
+    description: str
+    input_schema: Dict[str, Any] = Field(default_factory=dict)
+    output_schema: Dict[str, Any] = Field(default_factory=dict)
+    pricing: SkillPricing = Field(default_factory=SkillPricing)
+    tags: List[str] = Field(default_factory=list)
+    examples: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class AgentMetadata(BaseModel):
+    """Metadata about the parent PactSpec agent for a tool."""
+
+    agent_id: str
+    spec_id: str
+    name: str
+    version: str
+    endpoint_url: str
+    verified: bool = False
+    attestation_hash: Optional[str] = None
+    provider_name: str = ""

pactspec_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pactspec-langchain"
+version = "0.1.0"
+description = "LangChain integration for PactSpec — discover and invoke verified AI agents as LangChain tools"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "PactSpec", email = "hello@pactspec.dev" },
+]
+keywords = ["pactspec", "langchain", "agents", "tools", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pactspec>=0.1.0",
+    "langchain-core>=0.3.0",
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://pactspec.dev"
+Repository = "https://github.com/pactspec/pactspec"
+Documentation = "https://pactspec.dev/docs/integrations/langchain"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pactspec_langchain"]