langchain-stackresolve 0.1.0__tar.gz

langchain_stackresolve-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/

langchain_stackresolve-0.1.0/LICENSE

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

langchain_stackresolve-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: langchain-stackresolve
+Version: 0.1.0
+Summary: LangChain tools for StackResolve: find, compare, and audit software for AI agents, plus structured company research.
+Project-URL: Homepage, https://stackresolve.dev
+Project-URL: Repository, https://github.com/autorevai/stackresolve
+Project-URL: Documentation, https://stackresolve.dev/docs
+Author: StackResolve
+License: MIT
+License-File: LICENSE
+Keywords: agent-tools,agentready,ai-agents,companydata,langchain,mcp,stackresolve
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: stackresolve>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-stackresolve
+
+LangChain tools for [StackResolve](https://stackresolve.dev): web intelligence for AI agents.
+
+Pick software for a task, compare vendors, check whether a product is agent-ready, and
+pull structured company facts. One tool call instead of a search-and-scrape loop.
+
+```bash
+pip install langchain-stackresolve
+```
+
+## Quickstart
+
+Every tool works without a key, subject to an anonymous rate limit. A free key from
+[stackresolve.dev/developers](https://stackresolve.dev/developers) raises it.
+
+```python
+import os
+from langchain_stackresolve import StackResolveToolkit
+from langchain.agents import create_agent
+
+os.environ["STACKRESOLVE_API_KEY"] = "ar_..."  # optional, raises the rate limit
+
+agent = create_agent(
+    model="claude-sonnet-5",
+    tools=StackResolveToolkit().get_tools(),
+)
+
+result = agent.invoke({
+    "messages": [{
+        "role": "user",
+        "content": "I need to scrape javascript-heavy sites. What should I use, "
+                   "and what does it cost?",
+    }]
+})
+print(result["messages"][-1].content)
+```
+
+The agent calls `stackresolve_find_tools` to get scored candidates, then
+`stackresolve_get_pricing` on the winner. Two calls, structured answers, no scraping.
+
+## Single tools
+
+Import only what you need:
+
+```python
+from langchain_stackresolve import StackResolveAudit, StackResolveFindTools
+
+audit = StackResolveAudit()
+print(audit.invoke({"domain": "stripe.com"}))
+
+find = StackResolveFindTools()
+print(find.invoke({"task": "send transactional email from a Node service"}))
+```
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `stackresolve_find_tools` | "What should I use for this task?" Ranked, with AgentReady scores. |
+| `stackresolve_search_tools` | Registry search filtered on API, MCP, CLI, OpenAPI, or self-serve. |
+| `stackresolve_compare_products` | Side-by-side on scores, capabilities, and pricing. |
+| `stackresolve_audit` | 0-100 agent-readiness score for a domain, plus failing checks. |
+| `stackresolve_get_company` | Structured company facts from a domain. |
+| `stackresolve_get_pricing` | Current plans and prices as structured data. |
+| `stackresolve_find_competitors` | Competitors, with how each one differs. |
+| `stackresolve_research_company` | Deep research with sources, answering a question. |
+
+All eight work without a key, subject to an anonymous rate limit. A free key raises the
+limit and is required for account endpoints (monitors, usage, discovery runs), which this
+package does not expose.
+
+## Configuration
+
+The toolkit and every tool accept `api_key` and `base_url`, and otherwise read
+`STACKRESOLVE_API_KEY` and `STACKRESOLVE_BASE_URL` from the environment.
+
+```python
+toolkit = StackResolveToolkit(api_key="ar_...")
+```
+
+Pass an existing SDK client to share connection state:
+
+```python
+from stackresolve import StackResolve
+
+client = StackResolve(api_key="ar_...")
+tools = StackResolveToolkit(client=client).get_tools()
+```
+
+## Errors
+
+Tools return a readable message rather than raising, so a failed call does not end the
+agent's turn. A missing key, an exhausted allowance, and a rate limit each come back as
+text the model can act on.
+
+## Output size
+
+Tool output is capped at 6,000 characters and marked when truncated, so a large registry
+or research payload cannot flood the context window. Change it with
+`langchain_stackresolve.tools.MAX_CHARS`.
+
+## Also available
+
+- Hosted MCP server (no install): `https://mcp.stackresolve.dev/mcp`
+- TypeScript SDK and CLI: `npm install stackresolve`
+- Python SDK on its own: `pip install stackresolve`
+- REST API: `https://api.stackresolve.dev`, OpenAPI at `/openapi.json`
+
+## License
+
+MIT

langchain_stackresolve-0.1.0/README.md

@@ -0,0 +1,112 @@
+# langchain-stackresolve
+
+LangChain tools for [StackResolve](https://stackresolve.dev): web intelligence for AI agents.
+
+Pick software for a task, compare vendors, check whether a product is agent-ready, and
+pull structured company facts. One tool call instead of a search-and-scrape loop.
+
+```bash
+pip install langchain-stackresolve
+```
+
+## Quickstart
+
+Every tool works without a key, subject to an anonymous rate limit. A free key from
+[stackresolve.dev/developers](https://stackresolve.dev/developers) raises it.
+
+```python
+import os
+from langchain_stackresolve import StackResolveToolkit
+from langchain.agents import create_agent
+
+os.environ["STACKRESOLVE_API_KEY"] = "ar_..."  # optional, raises the rate limit
+
+agent = create_agent(
+    model="claude-sonnet-5",
+    tools=StackResolveToolkit().get_tools(),
+)
+
+result = agent.invoke({
+    "messages": [{
+        "role": "user",
+        "content": "I need to scrape javascript-heavy sites. What should I use, "
+                   "and what does it cost?",
+    }]
+})
+print(result["messages"][-1].content)
+```
+
+The agent calls `stackresolve_find_tools` to get scored candidates, then
+`stackresolve_get_pricing` on the winner. Two calls, structured answers, no scraping.
+
+## Single tools
+
+Import only what you need:
+
+```python
+from langchain_stackresolve import StackResolveAudit, StackResolveFindTools
+
+audit = StackResolveAudit()
+print(audit.invoke({"domain": "stripe.com"}))
+
+find = StackResolveFindTools()
+print(find.invoke({"task": "send transactional email from a Node service"}))
+```
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `stackresolve_find_tools` | "What should I use for this task?" Ranked, with AgentReady scores. |
+| `stackresolve_search_tools` | Registry search filtered on API, MCP, CLI, OpenAPI, or self-serve. |
+| `stackresolve_compare_products` | Side-by-side on scores, capabilities, and pricing. |
+| `stackresolve_audit` | 0-100 agent-readiness score for a domain, plus failing checks. |
+| `stackresolve_get_company` | Structured company facts from a domain. |
+| `stackresolve_get_pricing` | Current plans and prices as structured data. |
+| `stackresolve_find_competitors` | Competitors, with how each one differs. |
+| `stackresolve_research_company` | Deep research with sources, answering a question. |
+
+All eight work without a key, subject to an anonymous rate limit. A free key raises the
+limit and is required for account endpoints (monitors, usage, discovery runs), which this
+package does not expose.
+
+## Configuration
+
+The toolkit and every tool accept `api_key` and `base_url`, and otherwise read
+`STACKRESOLVE_API_KEY` and `STACKRESOLVE_BASE_URL` from the environment.
+
+```python
+toolkit = StackResolveToolkit(api_key="ar_...")
+```
+
+Pass an existing SDK client to share connection state:
+
+```python
+from stackresolve import StackResolve
+
+client = StackResolve(api_key="ar_...")
+tools = StackResolveToolkit(client=client).get_tools()
+```
+
+## Errors
+
+Tools return a readable message rather than raising, so a failed call does not end the
+agent's turn. A missing key, an exhausted allowance, and a rate limit each come back as
+text the model can act on.
+
+## Output size
+
+Tool output is capped at 6,000 characters and marked when truncated, so a large registry
+or research payload cannot flood the context window. Change it with
+`langchain_stackresolve.tools.MAX_CHARS`.
+
+## Also available
+
+- Hosted MCP server (no install): `https://mcp.stackresolve.dev/mcp`
+- TypeScript SDK and CLI: `npm install stackresolve`
+- Python SDK on its own: `pip install stackresolve`
+- REST API: `https://api.stackresolve.dev`, OpenAPI at `/openapi.json`
+
+## License
+
+MIT

langchain_stackresolve-0.1.0/langchain_stackresolve/__init__.py

@@ -0,0 +1,36 @@
+"""LangChain integration for StackResolve.
+
+Web intelligence for AI agents: find, compare, and audit software for a task, and pull
+structured company research, in one tool call instead of a search-and-scrape loop.
+"""
+
+from .toolkit import StackResolveToolkit
+from .tools import (
+    ALL_TOOL_CLASSES,
+    StackResolveAudit,
+    StackResolveBaseTool,
+    StackResolveCompareProducts,
+    StackResolveFindCompetitors,
+    StackResolveFindTools,
+    StackResolveGetCompany,
+    StackResolveGetPricing,
+    StackResolveResearchCompany,
+    StackResolveSearchTools,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StackResolveToolkit",
+    "StackResolveBaseTool",
+    "StackResolveFindTools",
+    "StackResolveSearchTools",
+    "StackResolveAudit",
+    "StackResolveCompareProducts",
+    "StackResolveGetCompany",
+    "StackResolveGetPricing",
+    "StackResolveFindCompetitors",
+    "StackResolveResearchCompany",
+    "ALL_TOOL_CLASSES",
+    "__version__",
+]

langchain_stackresolve-0.1.0/langchain_stackresolve/toolkit.py

@@ -0,0 +1,45 @@
+"""Toolkit that hands an agent every StackResolve tool with one shared client."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+from stackresolve import StackResolve
+
+from .tools import ALL_TOOL_CLASSES, _build_client
+
+
+class StackResolveToolkit(BaseModel):
+    """All StackResolve tools, sharing one HTTP client.
+
+    Registry reads work without a key. Metered tools (audit, research) need one, from
+    https://stackresolve.dev/developers, passed here or set as STACKRESOLVE_API_KEY.
+
+        from langchain_stackresolve import StackResolveToolkit
+
+        tools = StackResolveToolkit().get_tools()
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    _client: StackResolve = PrivateAttr()
+
+    def __init__(
+        self,
+        client: Optional[StackResolve] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._client = client if client is not None else _build_client(api_key, base_url)
+
+    @property
+    def client(self) -> StackResolve:
+        return self._client
+
+    def get_tools(self) -> List[BaseTool]:
+        """Every tool in the toolkit, each bound to the shared client."""
+        return [cls(client=self._client) for cls in ALL_TOOL_CLASSES]

langchain_stackresolve-0.1.0/langchain_stackresolve/tools.py

@@ -0,0 +1,417 @@
+"""LangChain tools over the StackResolve API.
+
+Each tool wraps one StackResolve SDK call and returns compact JSON, so an agent can
+pick a tool for a task, compare vendors, check whether a product is agent-ready, and
+pull structured company facts without running its own search-and-scrape loop.
+
+    from langchain_stackresolve import StackResolveToolkit
+
+    tools = StackResolveToolkit().get_tools()
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional, Type
+
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForToolRun,
+    CallbackManagerForToolRun,
+)
+from langchain_core.runnables.config import run_in_executor
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+from stackresolve import StackResolve, StackResolveError
+
+# Tool output goes straight into a prompt, so cap it. Registry and research payloads
+# can run to tens of kilobytes and the tail is rarely what the model needs.
+MAX_CHARS = 6000
+
+
+def _dump(payload: Any, max_chars: int = MAX_CHARS) -> str:
+    """Serialize a payload to JSON, truncating on a character budget.
+
+    Truncation stays valid JSON. Slicing the serialized text mid-token would leave
+    output that a caller re-parsing tool results cannot load, and that failure would
+    only show up on large payloads.
+    """
+    text = json.dumps(payload, indent=2, default=str, ensure_ascii=False)
+    if len(text) <= max_chars:
+        return text
+    return json.dumps(
+        {
+            "truncated": True,
+            "omitted_characters": len(text) - max_chars,
+            "note": (
+                f"Result exceeded {max_chars} characters. 'partial' holds the start of "
+                "the JSON payload. Narrow the query for a complete result."
+            ),
+            "partial": text[:max_chars],
+        },
+        indent=2,
+        ensure_ascii=False,
+    )
+
+
+def _build_client(
+    api_key: Optional[str] = None, base_url: Optional[str] = None
+) -> StackResolve:
+    """Construct an SDK client, falling back to the standard environment variables."""
+    opts: Dict[str, Any] = {}
+    key = api_key or os.environ.get("STACKRESOLVE_API_KEY")
+    if key:
+        opts["api_key"] = key
+    url = base_url or os.environ.get("STACKRESOLVE_BASE_URL")
+    if url:
+        opts["base_url"] = url
+    return StackResolve(**opts)
+
+
+class StackResolveBaseTool(BaseTool):
+    """Shared plumbing: one client, uniform error handling, async via executor.
+
+    Subclasses set ``name``, ``description``, and ``args_schema``, then call
+    ``self._call(self.client.<method>, ...)`` from ``_run``.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    _client: Optional[StackResolve] = PrivateAttr(default=None)
+
+    def __init__(
+        self,
+        client: Optional[StackResolve] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._client = client if client is not None else _build_client(api_key, base_url)
+
+    @property
+    def client(self) -> StackResolve:
+        if self._client is None:  # pragma: no cover - defensive
+            self._client = _build_client()
+        return self._client
+
+    def _call(self, fn: Any, *args: Any, **kwargs: Any) -> str:
+        """Run an SDK call and return JSON, converting any failure into readable text.
+
+        A tool that raises ends the agent's turn. A tool that explains what went wrong
+        lets the model recover, so a 402 becomes an instruction rather than a traceback.
+
+        The catch-all matters as much as the status branches: a read timeout, a refused
+        connection, or a DNS failure is an ordinary condition for a network tool, and
+        letting one escape would kill the turn just as surely as an API error.
+        """
+        try:
+            return _dump(fn(*args, **kwargs))
+        except StackResolveError as err:
+            if err.status in (401, 403):
+                return (
+                    "StackResolve rejected the credentials. Set STACKRESOLVE_API_KEY "
+                    "to a key from https://stackresolve.dev/developers and retry."
+                )
+            if err.status == 402:
+                return (
+                    "This StackResolve tool is metered and the free allowance is used "
+                    "up. Registry reads (search, profiles, compare) still work."
+                )
+            if err.status == 429:
+                return "StackResolve rate limit reached. Wait a moment and retry."
+            return f"StackResolve API error {err.status}: {err.body}"
+        except Exception as err:  # noqa: BLE001 - a tool must never end the agent's turn
+            return (
+                f"StackResolve request failed: {type(err).__name__}: {err}. "
+                "This is usually a timeout or a network problem. Retry, or check "
+                "STACKRESOLVE_BASE_URL if it is set."
+            )
+
+    async def _acall(self, fn: Any, *args: Any, **kwargs: Any) -> str:
+        return await run_in_executor(None, self._call, fn, *args, **kwargs)
+
+
+# --------------------------------------------------------------------------------
+# AgentReady: pick, compare, and vet software
+# --------------------------------------------------------------------------------
+
+
+class FindToolsInput(BaseModel):
+    task: str = Field(
+        description=(
+            "The engineering task in plain English, e.g. 'scrape javascript-heavy "
+            "sites' or 'send transactional email from a Node service'."
+        )
+    )
+
+
+class StackResolveFindTools(StackResolveBaseTool):
+    """Task in, ranked agent-ready tools out."""
+
+    name: str = "stackresolve_find_tools"
+    description: str = (
+        "Find the best software for an engineering task, ranked by how well it works "
+        "for AI agents. Returns candidate tools with an AgentReady score (0-100), what "
+        "each one does, and why it fits. Use this when you need to choose a library, "
+        "API, or service and want current, scored options rather than guessing from "
+        "memory. Input is a plain-English task description."
+    )
+    args_schema: Type[BaseModel] = FindToolsInput
+
+    def _run(
+        self, task: str, run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> str:
+        return self._call(self.client.find_tools, task)
+
+    async def _arun(
+        self, task: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None
+    ) -> str:
+        return await self._acall(self.client.find_tools, task)
+
+
+class SearchToolsInput(BaseModel):
+    query: str = Field(description="Search query for the StackResolve registry.")
+    api: Optional[bool] = Field(default=None, description="Require a public API.")
+    mcp: Optional[bool] = Field(default=None, description="Require an MCP server.")
+    cli: Optional[bool] = Field(default=None, description="Require a CLI.")
+    openapi: Optional[bool] = Field(
+        default=None, description="Require a published OpenAPI spec."
+    )
+    self_serve: Optional[bool] = Field(
+        default=None, description="Require self-serve signup with no sales call."
+    )
+
+
+def _requirements(**kwargs: Any) -> Optional[Dict[str, Any]]:
+    reqs = {k: v for k, v in kwargs.items() if v is not None}
+    return reqs or None
+
+
+class StackResolveSearchTools(StackResolveBaseTool):
+    """Registry search with hard requirements."""
+
+    name: str = "stackresolve_search_tools"
+    description: str = (
+        "Search the StackResolve registry for software, filtering on capabilities an "
+        "agent needs: a public API, an MCP server, a CLI, an OpenAPI spec, or self-serve "
+        "signup. Use this when the requirement is concrete, e.g. 'a payments provider "
+        "with an MCP server and self-serve signup'. Free, no API key needed."
+    )
+    args_schema: Type[BaseModel] = SearchToolsInput
+
+    def _run(
+        self,
+        query: str,
+        api: Optional[bool] = None,
+        mcp: Optional[bool] = None,
+        cli: Optional[bool] = None,
+        openapi: Optional[bool] = None,
+        self_serve: Optional[bool] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        reqs = _requirements(
+            api=api, mcp=mcp, cli=cli, openapi=openapi, self_serve=self_serve
+        )
+        return self._call(self.client.search, query, reqs)
+
+    async def _arun(
+        self,
+        query: str,
+        api: Optional[bool] = None,
+        mcp: Optional[bool] = None,
+        cli: Optional[bool] = None,
+        openapi: Optional[bool] = None,
+        self_serve: Optional[bool] = None,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> str:
+        reqs = _requirements(
+            api=api, mcp=mcp, cli=cli, openapi=openapi, self_serve=self_serve
+        )
+        return await self._acall(self.client.search, query, reqs)
+
+
+class AuditInput(BaseModel):
+    domain: str = Field(description="Domain to audit, e.g. 'stripe.com'.")
+
+
+class StackResolveAudit(StackResolveBaseTool):
+    """Agent-readiness score and failing checks for a domain."""
+
+    name: str = "stackresolve_audit"
+    description: str = (
+        "Audit a domain for agent readiness. Returns a 0-100 AgentReady score, "
+        "sub-scores for discovery, understanding, adoption, and operability, plus the "
+        "specific checks that failed. Use this to judge whether an agent can actually "
+        "work with a vendor before recommending it, or to check a site you are building."
+    )
+    args_schema: Type[BaseModel] = AuditInput
+
+    def _run(
+        self, domain: str, run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> str:
+        return self._call(self.client.audit, domain)
+
+    async def _arun(
+        self, domain: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None
+    ) -> str:
+        return await self._acall(self.client.audit, domain)
+
+
+class CompareInput(BaseModel):
+    slugs: List[str] = Field(
+        description="Registry slugs to compare side by side, e.g. ['firecrawl', 'apify']."
+    )
+
+
+class StackResolveCompareProducts(StackResolveBaseTool):
+    """Side-by-side product comparison."""
+
+    name: str = "stackresolve_compare_products"
+    description: str = (
+        "Compare two or more products from the StackResolve registry side by side on "
+        "AgentReady scores, capabilities, and pricing. Use this after narrowing to a "
+        "shortlist. Input is a list of registry slugs, which you can get from "
+        "stackresolve_find_tools or stackresolve_search_tools."
+    )
+    args_schema: Type[BaseModel] = CompareInput
+
+    def _run(
+        self, slugs: List[str], run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> str:
+        return self._call(self.client.compare, slugs)
+
+    async def _arun(
+        self,
+        slugs: List[str],
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> str:
+        return await self._acall(self.client.compare, slugs)
+
+
+# --------------------------------------------------------------------------------
+# CompanyData: structured research in one call
+# --------------------------------------------------------------------------------
+
+
+class DomainInput(BaseModel):
+    domain: str = Field(description="Company domain, e.g. 'vercel.com'.")
+
+
+class StackResolveGetCompany(StackResolveBaseTool):
+    """Structured company facts."""
+
+    name: str = "stackresolve_get_company"
+    description: str = (
+        "Get structured facts about a company from its domain: what it does, category, "
+        "size, funding, and location. Use this instead of searching the web and reading "
+        "pages, which costs many more tool calls and returns unstructured text."
+    )
+    args_schema: Type[BaseModel] = DomainInput
+
+    def _run(
+        self, domain: str, run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> str:
+        return self._call(self.client.get_company, domain)
+
+    async def _arun(
+        self, domain: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None
+    ) -> str:
+        return await self._acall(self.client.get_company, domain)
+
+
+class StackResolveGetPricing(StackResolveBaseTool):
+    """Current pricing for a vendor."""
+
+    name: str = "stackresolve_get_pricing"
+    description: str = (
+        "Get a company's current pricing as structured data: plans, prices, billing "
+        "period, and what each tier includes. Use this for cost questions and "
+        "build-vs-buy comparisons. Pricing pages change often, so prefer this over "
+        "recalling a price from memory."
+    )
+    args_schema: Type[BaseModel] = DomainInput
+
+    def _run(
+        self, domain: str, run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> str:
+        return self._call(self.client.get_pricing, domain)
+
+    async def _arun(
+        self, domain: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None
+    ) -> str:
+        return await self._acall(self.client.get_pricing, domain)
+
+
+class StackResolveFindCompetitors(StackResolveBaseTool):
+    """Competitors for a company."""
+
+    name: str = "stackresolve_find_competitors"
+    description: str = (
+        "Find a company's competitors from its domain, with a short note on how each "
+        "one differs. Use this to widen a shortlist or to answer 'what else is there'."
+    )
+    args_schema: Type[BaseModel] = DomainInput
+
+    def _run(
+        self, domain: str, run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> str:
+        return self._call(self.client.get_competitors, domain)
+
+    async def _arun(
+        self, domain: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None
+    ) -> str:
+        return await self._acall(self.client.get_competitors, domain)
+
+
+class ResearchInput(BaseModel):
+    domain: str = Field(description="Company domain to research, e.g. 'anthropic.com'.")
+    question: Optional[str] = Field(
+        default=None,
+        description=(
+            "Optional specific question, e.g. 'what is their enterprise SLA?'. Omit for "
+            "a general research summary."
+        ),
+    )
+
+
+class StackResolveResearchCompany(StackResolveBaseTool):
+    """Deep research on a company, answering a specific question."""
+
+    name: str = "stackresolve_research_company"
+    description: str = (
+        "Run deep research on a company and get a synthesized answer with sources. "
+        "Takes a domain and an optional question. Use this when the answer needs current "
+        "web evidence rather than a stored fact, for example recent funding, a policy "
+        "change, or a support commitment. Slower and metered, so try "
+        "stackresolve_get_company first for basic facts."
+    )
+    args_schema: Type[BaseModel] = ResearchInput
+
+    def _run(
+        self,
+        domain: str,
+        question: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        return self._call(self.client.research, domain, question)
+
+    async def _arun(
+        self,
+        domain: str,
+        question: Optional[str] = None,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> str:
+        return await self._acall(self.client.research, domain, question)
+
+
+ALL_TOOL_CLASSES = [
+    StackResolveFindTools,
+    StackResolveSearchTools,
+    StackResolveAudit,
+    StackResolveCompareProducts,
+    StackResolveGetCompany,
+    StackResolveGetPricing,
+    StackResolveFindCompetitors,
+    StackResolveResearchCompany,
+]

langchain_stackresolve-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-stackresolve"
+version = "0.1.0"
+description = "LangChain tools for StackResolve: find, compare, and audit software for AI agents, plus structured company research."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+authors = [{ name = "StackResolve" }]
+keywords = [
+  "langchain",
+  "stackresolve",
+  "agentready",
+  "companydata",
+  "ai-agents",
+  "agent-tools",
+  "mcp",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "langchain-core>=0.3.0",
+  "stackresolve>=0.1.0",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://stackresolve.dev"
+Repository = "https://github.com/autorevai/stackresolve"
+Documentation = "https://stackresolve.dev/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_stackresolve"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

langchain_stackresolve-0.1.0/tests/test_tools.py

@@ -0,0 +1,176 @@
+"""Unit tests for the StackResolve LangChain tools. No network."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from stackresolve import StackResolveError
+
+from langchain_stackresolve import (
+    ALL_TOOL_CLASSES,
+    StackResolveAudit,
+    StackResolveFindTools,
+    StackResolveGetPricing,
+    StackResolveSearchTools,
+    StackResolveToolkit,
+)
+from langchain_stackresolve.tools import MAX_CHARS
+
+
+class FakeClient:
+    """Records calls and returns canned payloads, so tests never hit the API."""
+
+    def __init__(self, payload=None, error=None):
+        self.payload = payload if payload is not None else {"ok": True}
+        self.error = error
+        self.calls = []
+
+    def _handle(self, name, *args, **kwargs):
+        self.calls.append((name, args, kwargs))
+        if self.error is not None:
+            raise self.error
+        return self.payload
+
+    def find_tools(self, task):
+        return self._handle("find_tools", task)
+
+    def search(self, query, requirements=None):
+        return self._handle("search", query, requirements)
+
+    def audit(self, domain):
+        return self._handle("audit", domain)
+
+    def compare(self, slugs):
+        return self._handle("compare", slugs)
+
+    def get_company(self, domain):
+        return self._handle("get_company", domain)
+
+    def get_pricing(self, domain):
+        return self._handle("get_pricing", domain)
+
+    def get_competitors(self, domain):
+        return self._handle("get_competitors", domain)
+
+    def research(self, domain, question=None):
+        return self._handle("research", domain, question)
+
+
+def test_toolkit_exposes_every_tool():
+    tools = StackResolveToolkit(client=FakeClient()).get_tools()
+    assert len(tools) == len(ALL_TOOL_CLASSES) == 8
+    names = [t.name for t in tools]
+    assert len(set(names)) == len(names), "tool names must be unique"
+    assert all(n.startswith("stackresolve_") for n in names)
+
+
+def test_toolkit_shares_one_client():
+    client = FakeClient()
+    tools = StackResolveToolkit(client=client).get_tools()
+    assert all(t.client is client for t in tools)
+
+
+def test_every_tool_has_a_usable_description():
+    for tool in StackResolveToolkit(client=FakeClient()).get_tools():
+        # The description is what the model routes on, so it must be substantial.
+        assert len(tool.description) > 80, tool.name
+        assert tool.args_schema is not None, tool.name
+
+
+def test_find_tools_passes_the_task_through():
+    client = FakeClient(payload={"results": [{"slug": "firecrawl", "agentready": 91}]})
+    out = StackResolveFindTools(client=client).invoke({"task": "scrape a site"})
+    assert client.calls == [("find_tools", ("scrape a site",), {})]
+    assert json.loads(out)["results"][0]["slug"] == "firecrawl"
+
+
+def test_search_builds_requirements_and_drops_unset_flags():
+    client = FakeClient(payload=[])
+    StackResolveSearchTools(client=client).invoke(
+        {"query": "payments", "mcp": True, "self_serve": False}
+    )
+    name, args, _ = client.calls[0]
+    assert name == "search"
+    assert args[0] == "payments"
+    assert args[1] == {"mcp": True, "self_serve": False}
+
+
+def test_search_sends_none_when_no_requirements_given():
+    client = FakeClient(payload=[])
+    StackResolveSearchTools(client=client).invoke({"query": "email"})
+    assert client.calls[0][1][1] is None
+
+
+def test_output_is_truncated_on_the_character_budget():
+    client = FakeClient(payload={"rows": [{"v": "x" * 200} for _ in range(200)]})
+    out = StackResolveAudit(client=client).invoke({"domain": "stripe.com"})
+    assert "truncated" in out
+
+
+def test_truncated_output_is_still_valid_json():
+    """A caller that re-parses tool output must not break on a large payload."""
+    client = FakeClient(payload={"rows": [{"v": "x" * 200} for _ in range(200)]})
+    out = StackResolveAudit(client=client).invoke({"domain": "stripe.com"})
+    parsed = json.loads(out)  # would raise before the envelope fix
+    assert parsed["truncated"] is True
+    assert parsed["omitted_characters"] > 0
+    assert parsed["partial"].startswith("{")
+
+
+@pytest.mark.parametrize(
+    "status,expected",
+    [
+        (401, "STACKRESOLVE_API_KEY"),
+        (403, "STACKRESOLVE_API_KEY"),
+        (402, "free allowance"),
+        (429, "rate limit"),
+        (500, "API error 500"),
+    ],
+)
+def test_api_errors_become_readable_text_instead_of_raising(status, expected):
+    client = FakeClient(error=StackResolveError(status, {"detail": "nope"}))
+    out = StackResolveGetPricing(client=client).invoke({"domain": "vercel.com"})
+    assert expected in out
+
+
+@pytest.mark.parametrize(
+    "exc",
+    [
+        ConnectionError("[Errno 61] Connection refused"),
+        TimeoutError("the read operation timed out"),
+        ValueError("malformed response body"),
+    ],
+)
+def test_transport_failures_do_not_escape_and_kill_the_agent_turn(exc):
+    """Regression: only StackResolveError was caught, so a timeout ended the turn."""
+    client = FakeClient(error=exc)
+    out = StackResolveAudit(client=client).invoke({"domain": "stripe.com"})
+    assert "StackResolve request failed" in out
+    assert type(exc).__name__ in out
+
+
+async def test_transport_failures_do_not_escape_on_the_async_path():
+    client = FakeClient(error=ConnectionError("[Errno 61] Connection refused"))
+    out = await StackResolveAudit(client=client).ainvoke({"domain": "stripe.com"})
+    assert "StackResolve request failed" in out
+
+
+async def test_async_path_reaches_the_client():
+    client = FakeClient(payload={"name": "Vercel"})
+    out = await StackResolveAudit(client=client).ainvoke({"domain": "vercel.com"})
+    assert client.calls == [("audit", ("vercel.com",), {})]
+    assert json.loads(out)["name"] == "Vercel"
+
+
+def test_research_forwards_the_optional_question():
+    client = FakeClient()
+    tools = {t.name: t for t in StackResolveToolkit(client=client).get_tools()}
+    tools["stackresolve_research_company"].invoke(
+        {"domain": "anthropic.com", "question": "what is the enterprise SLA?"}
+    )
+    assert client.calls[0] == (
+        "research",
+        ("anthropic.com", "what is the enterprise SLA?"),
+        {},
+    )