crewai-stackresolve 0.1.0__py3-none-any.whl

crewai_stackresolve/__init__.py

@@ -0,0 +1,29 @@
+"""StackResolve tools for CrewAI."""
+
+from .tools import (
+    ALL_TOOL_CLASSES,
+    StackResolveAudit,
+    StackResolveCompareProducts,
+    StackResolveFindCompetitors,
+    StackResolveFindTools,
+    StackResolveGetCompany,
+    StackResolveGetPricing,
+    StackResolveResearchCompany,
+    StackResolveSearchTools,
+    stackresolve_tools,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "stackresolve_tools",
+    "StackResolveFindTools",
+    "StackResolveSearchTools",
+    "StackResolveCompareProducts",
+    "StackResolveAudit",
+    "StackResolveGetCompany",
+    "StackResolveGetPricing",
+    "StackResolveFindCompetitors",
+    "StackResolveResearchCompany",
+    "ALL_TOOL_CLASSES",
+    "__version__",
+]

crewai_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

crewai_stackresolve/tools.py

@@ -0,0 +1,216 @@
+"""CrewAI tools for StackResolve.
+
+    from crewai import Agent
+    from crewai_stackresolve import stackresolve_tools
+
+    analyst = Agent(role="Tooling analyst", tools=stackresolve_tools())
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+from stackresolve import StackResolve
+
+from ._common import build_client, call, requirements
+
+
+class _StackResolveTool(BaseTool):
+    """Shared plumbing: one client, uniform error handling."""
+
+    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
+
+
+class FindToolsInput(BaseModel):
+    task: str = Field(
+        description="The engineering task in plain English, e.g. 'scrape javascript-heavy sites'."
+    )
+
+
+class StackResolveFindTools(_StackResolveTool):
+    name: str = "Find software for a task"
+    description: str = (
+        "Find the best software for an engineering task, ranked by how well it works "
+        "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_schema: Type[BaseModel] = FindToolsInput
+
+    def _run(self, task: str) -> str:
+        return call(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."
+    )
+
+
+class StackResolveSearchTools(_StackResolveTool):
+    name: str = "Search the software registry"
+    description: str = (
+        "Search the StackResolve registry, 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."
+    )
+    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,
+    ) -> str:
+        return call(
+            self.client.search,
+            query,
+            requirements(
+                api=api, mcp=mcp, cli=cli, openapi=openapi, self_serve=self_serve
+            ),
+        )
+
+
+class CompareInput(BaseModel):
+    slugs: List[str] = Field(
+        description="Registry slugs to compare, e.g. ['firecrawl', 'apify']."
+    )
+
+
+class StackResolveCompareProducts(_StackResolveTool):
+    name: str = "Compare products"
+    description: str = (
+        "Compare two or more registry products side by side on AgentReady scores, "
+        "capabilities, and pricing. Use after narrowing to a shortlist."
+    )
+    args_schema: Type[BaseModel] = CompareInput
+
+    def _run(self, slugs: List[str]) -> str:
+        return call(self.client.compare, slugs)
+
+
+class DomainInput(BaseModel):
+    domain: str = Field(description="Domain, e.g. 'stripe.com'.")
+
+
+class StackResolveAudit(_StackResolveTool):
+    name: str = "Audit agent readiness"
+    description: 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_schema: Type[BaseModel] = DomainInput
+
+    def _run(self, domain: str) -> str:
+        return call(self.client.audit, domain)
+
+
+class StackResolveGetCompany(_StackResolveTool):
+    name: str = "Get company facts"
+    description: str = (
+        "Get structured facts about a company from its domain: what it does, category, "
+        "size, funding, and location. Prefer this over 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) -> str:
+        return call(self.client.get_company, domain)
+
+
+class StackResolveGetPricing(_StackResolveTool):
+    name: str = "Get company pricing"
+    description: str = (
+        "Get a company's current pricing as structured data: plans, prices, billing "
+        "period, and what each tier includes. Pricing pages change often, so prefer "
+        "this over recalling a price from memory."
+    )
+    args_schema: Type[BaseModel] = DomainInput
+
+    def _run(self, domain: str) -> str:
+        return call(self.client.get_pricing, domain)
+
+
+class StackResolveFindCompetitors(_StackResolveTool):
+    name: str = "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."
+    )
+    args_schema: Type[BaseModel] = DomainInput
+
+    def _run(self, domain: str) -> str:
+        return call(self.client.get_competitors, domain)
+
+
+class ResearchInput(BaseModel):
+    domain: str = Field(description="Company domain, e.g. 'anthropic.com'.")
+    question: Optional[str] = Field(
+        default=None, description="Optional specific question. Omit for a summary."
+    )
+
+
+class StackResolveResearchCompany(_StackResolveTool):
+    name: str = "Research a company"
+    description: 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 the company facts tool first."
+    )
+    args_schema: Type[BaseModel] = ResearchInput
+
+    def _run(self, domain: str, question: Optional[str] = None) -> str:
+        return call(self.client.research, domain, question)
+
+
+ALL_TOOL_CLASSES = [
+    StackResolveFindTools,
+    StackResolveSearchTools,
+    StackResolveCompareProducts,
+    StackResolveAudit,
+    StackResolveGetCompany,
+    StackResolveGetPricing,
+    StackResolveFindCompetitors,
+    StackResolveResearchCompany,
+]
+
+
+def stackresolve_tools(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    client: Optional[StackResolve] = None,
+) -> List[BaseTool]:
+    """Every StackResolve tool, sharing one HTTP client."""
+    shared = client if client is not None else build_client(api_key, base_url)
+    return [cls(client=shared) for cls in ALL_TOOL_CLASSES]

crewai_stackresolve-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: crewai-stackresolve
+Version: 0.1.0
+Summary: CrewAI 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,crewai,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.14,>=3.10
+Requires-Dist: crewai>=0.100.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: stackresolve>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# crewai-stackresolve
+
+CrewAI 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 crewai-stackresolve
+```
+
+## Quickstart
+
+```python
+from crewai import Agent, Task, Crew
+from crewai_stackresolve import stackresolve_tools
+
+analyst = Agent(
+    role="Tooling analyst",
+    goal="Pick the right software for a task and justify the cost",
+    backstory="You evaluate vendors on agent-readiness, not marketing copy.",
+    tools=stackresolve_tools(),
+)
+
+task = Task(
+    description="We need to scrape javascript-heavy sites. Recommend a tool and its cost.",
+    expected_output="A recommendation with the AgentReady score and current pricing.",
+    agent=analyst,
+)
+
+print(Crew(agents=[analyst], tasks=[task]).kickoff())
+```
+
+## Tools
+
+Find software for a task, Search the software registry, Compare products, Audit agent
+readiness, Get company facts, Get company pricing, Find competitors, Research a 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:
+
+```python
+stackresolve_tools(api_key="ar_...")   # or set STACKRESOLVE_API_KEY
+```
+
+Import a single tool if you do not want the whole set:
+
+```python
+from crewai_stackresolve import StackResolveAudit
+agent = Agent(role="Auditor", tools=[StackResolveAudit()])
+```
+
+## Behavior worth knowing
+
+Tools return readable text on failure rather than raising, so a timeout or an exhausted
+allowance does not end the crew'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`. LlamaIndex: `pip install llama-index-tools-stackresolve`.
+TypeScript: `npm install stackresolve`.
+
+## License
+
+MIT

crewai_stackresolve-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+crewai_stackresolve/__init__.py,sha256=pgBy-UWZ9kKQCruFgUNJlfD3ml9lmfWF39o5JzAj4-Y,697
+crewai_stackresolve/_common.py,sha256=Tv_iE5JC6K4EM_0v6QIKEAojDum4ia4dCHwFGlbeUNg,3830
+crewai_stackresolve/tools.py,sha256=kfub1z1XSEtn-OvCJ6OooSw4mnwcGDJWKUY16nEw4vc,7417
+crewai_stackresolve-0.1.0.dist-info/METADATA,sha256=aIgdzF3jXJqc2LHC9ocGryRG0rU8FAPnw86icRtktjQ,2849
+crewai_stackresolve-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+crewai_stackresolve-0.1.0.dist-info/licenses/LICENSE,sha256=N2923vLEHEI8BVat-UciamBUfBDvrsQFf50qm4qmQjs,1069
+crewai_stackresolve-0.1.0.dist-info/RECORD,,

crewai_stackresolve-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

crewai_stackresolve-0.1.0.dist-info/licenses/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.