llama-index-tools-stackresolve 0.1.0__tar.gz

llama_index_tools_stackresolve-0.1.0/.gitignore

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

llama_index_tools_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.

llama_index_tools_stackresolve-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: llama-index-tools-stackresolve
+Version: 0.1.0
+Summary: LlamaIndex 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
+Author: StackResolve
+License: MIT
+License-File: LICENSE
+Keywords: agent-tools,agentready,ai-agents,llama-index,llamaindex,mcp,stackresolve
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: llama-index-core>=0.11.0
+Requires-Dist: stackresolve>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# llama-index-tools-stackresolve
+
+LlamaIndex tools for [StackResolve](https://stackresolve.dev): web intelligence for AI agents.
+
+Choose software for a task, compare vendors, audit agent-readiness, and pull structured
+company facts. One tool call instead of a search-and-scrape loop.
+
+```bash
+pip install llama-index-tools-stackresolve
+```
+
+## Quickstart
+
+```python
+from llama_index.tools.stackresolve import StackResolveToolSpec
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.anthropic import Anthropic
+
+agent = FunctionAgent(
+    tools=StackResolveToolSpec().to_tool_list(),
+    llm=Anthropic(model="claude-sonnet-5"),
+)
+
+print(await agent.run("I need to scrape javascript-heavy sites. What should I use, and what does it cost?"))
+```
+
+## Tools
+
+`find_tools`, `search_tools`, `compare_products`, `audit`, `get_company`, `get_pricing`,
+`find_competitors`, `research_company`.
+
+All of them work without a key, subject to an anonymous rate limit. A free key from
+[stackresolve.dev/developers](https://stackresolve.dev/developers) raises it, passed to
+the spec or set as `STACKRESOLVE_API_KEY`.
+
+```python
+StackResolveToolSpec(api_key="ar_...")
+```
+
+## Behavior worth knowing
+
+Tools return readable text on failure rather than raising, so a timeout or an exhausted
+allowance does not end the agent's run. Output is capped at 6,000 characters and stays
+valid JSON when truncated.
+
+## Also available
+
+Hosted MCP server: `https://mcp.stackresolve.dev/mcp`. LangChain: `pip install
+langchain-stackresolve`. CrewAI: `pip install crewai-stackresolve`. TypeScript: `npm
+install stackresolve`.
+
+## License
+
+MIT

llama_index_tools_stackresolve-0.1.0/README.md

@@ -0,0 +1,54 @@
+# llama-index-tools-stackresolve
+
+LlamaIndex tools for [StackResolve](https://stackresolve.dev): web intelligence for AI agents.
+
+Choose software for a task, compare vendors, audit agent-readiness, and pull structured
+company facts. One tool call instead of a search-and-scrape loop.
+
+```bash
+pip install llama-index-tools-stackresolve
+```
+
+## Quickstart
+
+```python
+from llama_index.tools.stackresolve import StackResolveToolSpec
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.anthropic import Anthropic
+
+agent = FunctionAgent(
+    tools=StackResolveToolSpec().to_tool_list(),
+    llm=Anthropic(model="claude-sonnet-5"),
+)
+
+print(await agent.run("I need to scrape javascript-heavy sites. What should I use, and what does it cost?"))
+```
+
+## Tools
+
+`find_tools`, `search_tools`, `compare_products`, `audit`, `get_company`, `get_pricing`,
+`find_competitors`, `research_company`.
+
+All of them work without a key, subject to an anonymous rate limit. A free key from
+[stackresolve.dev/developers](https://stackresolve.dev/developers) raises it, passed to
+the spec or set as `STACKRESOLVE_API_KEY`.
+
+```python
+StackResolveToolSpec(api_key="ar_...")
+```
+
+## Behavior worth knowing
+
+Tools return readable text on failure rather than raising, so a timeout or an exhausted
+allowance does not end the agent's run. Output is capped at 6,000 characters and stays
+valid JSON when truncated.
+
+## Also available
+
+Hosted MCP server: `https://mcp.stackresolve.dev/mcp`. LangChain: `pip install
+langchain-stackresolve`. CrewAI: `pip install crewai-stackresolve`. TypeScript: `npm
+install stackresolve`.
+
+## License
+
+MIT

llama_index_tools_stackresolve-0.1.0/llama_index/tools/stackresolve/__init__.py

@@ -0,0 +1,6 @@
+"""StackResolve tools for LlamaIndex."""
+
+from .base import StackResolveToolSpec
+
+__version__ = "0.1.0"
+__all__ = ["StackResolveToolSpec", "__version__"]

llama_index_tools_stackresolve-0.1.0/llama_index/tools/stackresolve/_common.py

@@ -0,0 +1,98 @@
+"""Shared plumbing for the StackResolve framework adapters.
+
+Vendored into each adapter package rather than published as a fourth PyPI package:
+one more dependency on every install is a worse trade than ~80 duplicated lines,
+and the adapters must be able to move independently of each other.
+
+Keep this file the single source and re-copy it, so a fix like the uncaught-timeout
+one lands everywhere at once.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, Optional
+
+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 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)
+
+
+def dump(payload: Any, max_chars: int = MAX_CHARS) -> str:
+    """Serialize to JSON, truncating on a character budget and staying valid JSON.
+
+    Slicing the serialized text mid-token would leave output a caller re-parsing tool
+    results cannot load, and that failure would only appear 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 call(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.
+    """
+    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."
+        )
+
+
+def requirements(**kwargs: Any) -> Optional[Dict[str, Any]]:
+    """Drop unset capability filters so the API sees only what the caller asked for."""
+    reqs = {k: v for k, v in kwargs.items() if v is not None}
+    return reqs or None

llama_index_tools_stackresolve-0.1.0/llama_index/tools/stackresolve/base.py

@@ -0,0 +1,148 @@
+"""LlamaIndex tool spec for StackResolve.
+
+    from llama_index.tools.stackresolve import StackResolveToolSpec
+    from llama_index.core.agent.workflow import FunctionAgent
+
+    agent = FunctionAgent(tools=StackResolveToolSpec().to_tool_list(), llm=llm)
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+from stackresolve import StackResolve
+
+from ._common import build_client, call, requirements
+
+
+class StackResolveToolSpec(BaseToolSpec):
+    """Web intelligence for agents: choose software, compare vendors, research companies.
+
+    Every tool works without a key, subject to an anonymous rate limit. A free key from
+    https://stackresolve.dev/developers raises it, passed here or as
+    STACKRESOLVE_API_KEY.
+    """
+
+    spec_functions: List[str] = [
+        "find_tools",
+        "search_tools",
+        "compare_products",
+        "audit",
+        "get_company",
+        "get_pricing",
+        "find_competitors",
+        "research_company",
+    ]
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        client: Optional[StackResolve] = None,
+    ) -> None:
+        self.client = client if client is not None else build_client(api_key, base_url)
+
+    def find_tools(self, task: str) -> str:
+        """Find the best software for an engineering task, ranked for AI agents.
+
+        Returns candidates with an AgentReady score (0-100), what each does, and why it
+        fits. Use this to choose a library, API, or service with current scored options
+        rather than recalling one from memory.
+
+        Args:
+            task: The task in plain English, e.g. "scrape javascript-heavy sites".
+        """
+        return call(self.client.find_tools, task)
+
+    def search_tools(
+        self,
+        query: str,
+        api: Optional[bool] = None,
+        mcp: Optional[bool] = None,
+        cli: Optional[bool] = None,
+        openapi: Optional[bool] = None,
+        self_serve: Optional[bool] = None,
+    ) -> str:
+        """Search the registry, filtering on capabilities an agent needs.
+
+        Use this when the requirement is concrete, e.g. "a payments provider with an MCP
+        server and self-serve signup".
+
+        Args:
+            query: Search query.
+            api: Require a public API.
+            mcp: Require an MCP server.
+            cli: Require a CLI.
+            openapi: Require a published OpenAPI spec.
+            self_serve: Require self-serve signup with no sales call.
+        """
+        return call(
+            self.client.search,
+            query,
+            requirements(
+                api=api, mcp=mcp, cli=cli, openapi=openapi, self_serve=self_serve
+            ),
+        )
+
+    def compare_products(self, slugs: List[str]) -> str:
+        """Compare products side by side on scores, capabilities, and pricing.
+
+        Args:
+            slugs: Registry slugs, e.g. ["firecrawl", "apify"], from find_tools or
+                search_tools.
+        """
+        return call(self.client.compare, slugs)
+
+    def audit(self, domain: str) -> str:
+        """Audit a domain for agent readiness.
+
+        Returns a 0-100 score, sub-scores for discovery, understanding, adoption, and
+        operability, and the checks that failed. Use it to judge whether an agent can
+        actually work with a vendor.
+
+        Args:
+            domain: Domain to audit, e.g. "stripe.com".
+        """
+        return call(self.client.audit, domain)
+
+    def get_company(self, domain: str) -> str:
+        """Get structured facts about a company: what it does, category, size, funding.
+
+        Prefer this over searching the web and reading pages, which costs many more tool
+        calls and returns unstructured text.
+
+        Args:
+            domain: Company domain, e.g. "vercel.com".
+        """
+        return call(self.client.get_company, domain)
+
+    def get_pricing(self, domain: str) -> str:
+        """Get a company's current pricing: plans, prices, period, and what each includes.
+
+        Pricing pages change often, so prefer this over recalling a price.
+
+        Args:
+            domain: Company domain, e.g. "vercel.com".
+        """
+        return call(self.client.get_pricing, domain)
+
+    def find_competitors(self, domain: str) -> str:
+        """Find a company's competitors, with a note on how each differs.
+
+        Args:
+            domain: Company domain, e.g. "vercel.com".
+        """
+        return call(self.client.get_competitors, domain)
+
+    def research_company(self, domain: str, question: Optional[str] = None) -> str:
+        """Run deep research on a company and get a synthesized answer with sources.
+
+        Use this when the answer needs current web evidence rather than a stored fact.
+        Slower and metered, so try get_company first for basic facts.
+
+        Args:
+            domain: Company domain, e.g. "anthropic.com".
+            question: Optional specific question. Omit for a general summary.
+        """
+        return call(self.client.research, domain, question)

llama_index_tools_stackresolve-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llama-index-tools-stackresolve"
+version = "0.1.0"
+description = "LlamaIndex 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 = ["llamaindex", "llama-index", "stackresolve", "agentready", "ai-agents", "agent-tools", "mcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+]
+dependencies = ["llama-index-core>=0.11.0", "stackresolve>=0.1.0"]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://stackresolve.dev"
+Repository = "https://github.com/autorevai/stackresolve"
+
+[tool.hatch.build.targets.wheel]
+packages = ["llama_index"]

llama_index_tools_stackresolve-0.1.0/tests/test_tool_spec.py

@@ -0,0 +1,129 @@
+"""Unit tests for the StackResolve LlamaIndex tool spec. No network."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from stackresolve import StackResolveError
+
+from llama_index.tools.stackresolve import StackResolveToolSpec
+from llama_index.tools.stackresolve._common import MAX_CHARS
+
+
+class FakeClient:
+    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 compare(self, slugs):
+        return self._handle("compare", slugs)
+
+    def audit(self, domain):
+        return self._handle("audit", domain)
+
+    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 spec(**kw):
+    return StackResolveToolSpec(client=FakeClient(**kw))
+
+
+def test_tool_list_exposes_every_spec_function():
+    s = spec()
+    tools = s.to_tool_list()
+    assert len(tools) == len(s.spec_functions) == 8
+    names = [t.metadata.name for t in tools]
+    assert len(set(names)) == len(names)
+
+
+def test_every_spec_function_exists_and_is_documented():
+    s = spec()
+    for fn_name in s.spec_functions:
+        fn = getattr(s, fn_name, None)
+        assert callable(fn), f"{fn_name} missing"
+        assert fn.__doc__ and len(fn.__doc__) > 60, f"{fn_name} needs a real docstring"
+
+
+def test_find_tools_passes_the_task_through():
+    client = FakeClient(payload={"results": [{"slug": "firecrawl"}]})
+    out = StackResolveToolSpec(client=client).find_tools("scrape a site")
+    assert client.calls == [("find_tools", ("scrape a site",), {})]
+    assert json.loads(out)["results"][0]["slug"] == "firecrawl"
+
+
+def test_search_drops_unset_requirement_flags():
+    client = FakeClient(payload=[])
+    StackResolveToolSpec(client=client).search_tools("payments", mcp=True, cli=False)
+    assert client.calls[0][1][1] == {"mcp": True, "cli": False}
+
+
+def test_search_sends_none_when_no_requirements_given():
+    client = FakeClient(payload=[])
+    StackResolveToolSpec(client=client).search_tools("email")
+    assert client.calls[0][1][1] is None
+
+
+def test_truncated_output_is_still_valid_json():
+    client = FakeClient(payload={"rows": [{"v": "x" * 200} for _ in range(200)]})
+    parsed = json.loads(StackResolveToolSpec(client=client).audit("stripe.com"))
+    assert parsed["truncated"] is True
+    assert parsed["omitted_characters"] > 0
+    assert len(parsed["partial"]) == MAX_CHARS
+
+
+@pytest.mark.parametrize(
+    "status,expected",
+    [
+        (401, "STACKRESOLVE_API_KEY"),
+        (402, "free allowance"),
+        (429, "rate limit"),
+        (500, "API error 500"),
+    ],
+)
+def test_api_errors_become_readable_text(status, expected):
+    client = FakeClient(error=StackResolveError(status, {"detail": "nope"}))
+    assert expected in StackResolveToolSpec(client=client).get_pricing("vercel.com")
+
+
+@pytest.mark.parametrize(
+    "exc",
+    [
+        ConnectionError("[Errno 61] Connection refused"),
+        TimeoutError("the read operation timed out"),
+    ],
+)
+def test_transport_failures_do_not_escape(exc):
+    client = FakeClient(error=exc)
+    out = StackResolveToolSpec(client=client).audit("stripe.com")
+    assert "StackResolve request failed" in out
+    assert type(exc).__name__ in out
+
+
+def test_research_forwards_the_optional_question():
+    client = FakeClient()
+    StackResolveToolSpec(client=client).research_company("anthropic.com", "SLA?")
+    assert client.calls[0] == ("research", ("anthropic.com", "SLA?"), {})