stackresolve 0.1.0__tar.gz

stackresolve-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.next/
+.env*
+!.env.example
+.DS_Store
+*.log
+/.claude/worktrees/
+
+# prior-work semantic vector cache (machine-local)
+.claude/cache/

stackresolve-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: stackresolve
+Version: 0.1.0
+Summary: Official Python SDK for the StackResolve API (AgentReady + CompanyData).
+Project-URL: Homepage, https://stackresolve.dev
+Author: StackResolve
+License: MIT
+Keywords: agent,agentready,companydata,mcp,sdk,stackresolve
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# stackresolve
+
+Official Python SDK for the [StackResolve](https://stackresolve.dev) API.
+
+StackResolve helps agents discover, evaluate, select, install, and use software
+(AgentReady), and compresses web research into structured company data calls
+(CompanyData). This SDK is a thin wrapper over the live REST API.
+
+## Install
+
+```bash
+pip install stackresolve
+```
+
+Requires Python 3.9+. Depends on `httpx`.
+
+## Quickstart
+
+```python
+from stackresolve import StackResolve
+
+sr = StackResolve(api_key="ar_...")  # or set STACKRESOLVE_API_KEY
+
+# 1. Audit a domain: AgentReady scores, facts, and issues.
+report = sr.audit("stripe.com")
+print(report["scores"]["agentready"], report["issues"])
+
+# 2. Structured company data.
+company = sr.get_company("vercel.com")
+print(company["name"], company.get("description"))
+
+# 3. Task -> ranked, agent-ready tools.
+tools = sr.find_tools("send transactional email from a Python service")
+print(tools["results"])
+
+# 4. Run an Agent Discovery check (needs an API key).
+discovery = sr.run_discovery("firecrawl")
+print(discovery)
+```
+
+## Authentication
+
+Get an API key at [stackresolve.dev](https://stackresolve.dev). Pass it to the
+constructor, or set the `STACKRESOLVE_API_KEY` environment variable:
+
+```python
+sr = StackResolve(api_key="ar_...")
+# or, reading STACKRESOLVE_API_KEY from the environment:
+sr = StackResolve()
+```
+
+The key is sent as the `x-api-key` header on every request. Public endpoints
+(audit, search, profiles, company data, ...) work without a key, subject to an
+anonymous rate limit. Gated endpoints (monitors, usage, discovery runs) need one.
+
+Point the client at a different host with `base_url` or the
+`STACKRESOLVE_BASE_URL` environment variable:
+
+```python
+sr = StackResolve(api_key="ar_...", base_url="https://api.stackresolve.dev")
+```
+
+## Errors
+
+Any non-2xx response raises a `StackResolveError` carrying the HTTP `status` and
+the parsed `body`:
+
+```python
+from stackresolve import StackResolve, StackResolveError
+
+sr = StackResolve()
+try:
+    sr.get_usage()
+except StackResolveError as err:
+    print(err.status, err.body)
+```
+
+## Methods
+
+AgentReady:
+`audit(domain)`, `find_tools(task)`, `search(query, requirements=None)`,
+`compare(slugs)`, `get_profile(slug)`, `list_registry(...)`, `get_categories()`,
+`get_category(slug)`, `get_discovery(slug)`, `run_discovery(slug)`,
+`get_score_history(slug)`, `generate(domain, openapi_url=None)`,
+`deploy(domain, openapi_url=None)`.
+
+CompanyData:
+`get_company(domain)`, `get_pricing(domain)`, `get_competitors(domain)`,
+`research(domain, question=None)`, `compare_companies(domains)`.
+
+Monitors + account (API key required):
+`list_monitors()`, `add_monitor(slug, ...)`, `run_monitor_now(slug)`,
+`get_usage()`, `get_my_profile()`.
+
+## License
+
+MIT

stackresolve-0.1.0/README.md

@@ -0,0 +1,97 @@
+# stackresolve
+
+Official Python SDK for the [StackResolve](https://stackresolve.dev) API.
+
+StackResolve helps agents discover, evaluate, select, install, and use software
+(AgentReady), and compresses web research into structured company data calls
+(CompanyData). This SDK is a thin wrapper over the live REST API.
+
+## Install
+
+```bash
+pip install stackresolve
+```
+
+Requires Python 3.9+. Depends on `httpx`.
+
+## Quickstart
+
+```python
+from stackresolve import StackResolve
+
+sr = StackResolve(api_key="ar_...")  # or set STACKRESOLVE_API_KEY
+
+# 1. Audit a domain: AgentReady scores, facts, and issues.
+report = sr.audit("stripe.com")
+print(report["scores"]["agentready"], report["issues"])
+
+# 2. Structured company data.
+company = sr.get_company("vercel.com")
+print(company["name"], company.get("description"))
+
+# 3. Task -> ranked, agent-ready tools.
+tools = sr.find_tools("send transactional email from a Python service")
+print(tools["results"])
+
+# 4. Run an Agent Discovery check (needs an API key).
+discovery = sr.run_discovery("firecrawl")
+print(discovery)
+```
+
+## Authentication
+
+Get an API key at [stackresolve.dev](https://stackresolve.dev). Pass it to the
+constructor, or set the `STACKRESOLVE_API_KEY` environment variable:
+
+```python
+sr = StackResolve(api_key="ar_...")
+# or, reading STACKRESOLVE_API_KEY from the environment:
+sr = StackResolve()
+```
+
+The key is sent as the `x-api-key` header on every request. Public endpoints
+(audit, search, profiles, company data, ...) work without a key, subject to an
+anonymous rate limit. Gated endpoints (monitors, usage, discovery runs) need one.
+
+Point the client at a different host with `base_url` or the
+`STACKRESOLVE_BASE_URL` environment variable:
+
+```python
+sr = StackResolve(api_key="ar_...", base_url="https://api.stackresolve.dev")
+```
+
+## Errors
+
+Any non-2xx response raises a `StackResolveError` carrying the HTTP `status` and
+the parsed `body`:
+
+```python
+from stackresolve import StackResolve, StackResolveError
+
+sr = StackResolve()
+try:
+    sr.get_usage()
+except StackResolveError as err:
+    print(err.status, err.body)
+```
+
+## Methods
+
+AgentReady:
+`audit(domain)`, `find_tools(task)`, `search(query, requirements=None)`,
+`compare(slugs)`, `get_profile(slug)`, `list_registry(...)`, `get_categories()`,
+`get_category(slug)`, `get_discovery(slug)`, `run_discovery(slug)`,
+`get_score_history(slug)`, `generate(domain, openapi_url=None)`,
+`deploy(domain, openapi_url=None)`.
+
+CompanyData:
+`get_company(domain)`, `get_pricing(domain)`, `get_competitors(domain)`,
+`research(domain, question=None)`, `compare_companies(domains)`.
+
+Monitors + account (API key required):
+`list_monitors()`, `add_monitor(slug, ...)`, `run_monitor_now(slug)`,
+`get_usage()`, `get_my_profile()`.
+
+## License
+
+MIT

stackresolve-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stackresolve"
+version = "0.1.0"
+description = "Official Python SDK for the StackResolve API (AgentReady + CompanyData)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "StackResolve" }]
+keywords = ["stackresolve", "agentready", "companydata", "agent", "mcp", "sdk"]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://stackresolve.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["stackresolve"]

stackresolve-0.1.0/stackresolve/__init__.py

@@ -0,0 +1,6 @@
+"""StackResolve official Python SDK."""
+
+from .client import StackResolve, StackResolveError
+
+__version__ = "0.1.0"
+__all__ = ["StackResolve", "StackResolveError", "__version__"]

stackresolve-0.1.0/stackresolve/client.py

@@ -0,0 +1,243 @@
+"""StackResolve official Python SDK.
+
+A thin wrapper over the StackResolve REST API. It gives agents and developers
+Firecrawl/Exa-style ergonomics over AgentReady (discover, evaluate, select,
+install, and use software) and CompanyData (structured company research).
+
+    from stackresolve import StackResolve
+
+    sr = StackResolve(api_key="ar_...")
+    report = sr.audit("stripe.com")
+    print(report["scores"]["agentready"])
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.stackresolve.dev"
+
+JsonDict = Dict[str, Any]
+
+
+class StackResolveError(Exception):
+    """Raised on any non-2xx API response. Carries the HTTP status and parsed body."""
+
+    def __init__(self, status: int, body: Any, message: Optional[str] = None) -> None:
+        self.status = status
+        self.body = body
+        super().__init__(message or f"StackResolve API error {status}")
+
+
+class StackResolve:
+    """Client for the StackResolve API.
+
+    Args:
+        api_key: API key. Falls back to the STACKRESOLVE_API_KEY env var.
+            Optional for public endpoints, required for gated ones.
+        base_url: Base URL override. Falls back to STACKRESOLVE_BASE_URL,
+            then https://api.stackresolve.dev .
+        timeout: Per-request timeout in seconds (default 60).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("STACKRESOLVE_API_KEY")
+        base = base_url or os.environ.get("STACKRESOLVE_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = base.rstrip("/")
+        headers = {"accept": "application/json"}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        self._client = httpx.Client(base_url=self.base_url, headers=headers, timeout=timeout)
+
+    # ---- context manager + cleanup ----
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "StackResolve":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---- core transport ----
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[JsonDict] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        clean_params = None
+        if params:
+            clean_params = {k: v for k, v in params.items() if v is not None and v != ""}
+        resp = self._client.request(method, path, json=json, params=clean_params)
+        text = resp.text
+        parsed: Any = None
+        if text:
+            try:
+                parsed = resp.json()
+            except ValueError:
+                parsed = text
+        if resp.status_code < 200 or resp.status_code >= 300:
+            message = None
+            if isinstance(parsed, dict) and "error" in parsed:
+                message = str(parsed["error"])
+            raise StackResolveError(resp.status_code, parsed, message)
+        return parsed
+
+    # ---- AgentReady: discovery, evaluation, profiles ----
+
+    def audit(self, domain: str) -> JsonDict:
+        """Audit a domain: AgentReady scores, facts, and issues."""
+        return self._request("POST", "/v1/audit", json={"domain": domain})
+
+    def find_tools(self, task: str) -> JsonDict:
+        """Turn a natural-language task into ranked, agent-ready tool candidates."""
+        return self._request("POST", "/v1/find-tools", json={"task": task})
+
+    def search(self, query: str, requirements: Optional[JsonDict] = None) -> List[JsonDict]:
+        """Keyword search over the registry, optionally filtered by requirements."""
+        body: JsonDict = {"query": query}
+        if requirements:
+            body["requirements"] = requirements
+        return self._request("POST", "/v1/search", json=body)
+
+    def compare(self, slugs: List[str]) -> JsonDict:
+        """Compare products side by side by slug."""
+        return self._request("POST", "/v1/compare", json={"slugs": slugs})
+
+    def get_profile(self, slug: str) -> Optional[JsonDict]:
+        """Fetch a single product profile (scores + facts) by slug."""
+        return self._request("GET", f"/v1/profile/{slug}")
+
+    def list_registry(
+        self,
+        category: Optional[str] = None,
+        min_score: Optional[float] = None,
+        limit: Optional[int] = None,
+    ) -> List[JsonDict]:
+        """List registry rows, optionally filtered by category, minimum score, and limit."""
+        return self._request(
+            "GET",
+            "/v1/registry",
+            params={"category": category, "minScore": min_score, "limit": limit},
+        )
+
+    def get_categories(self) -> List[JsonDict]:
+        """List all categories."""
+        r = self._request("GET", "/v1/categories")
+        return r.get("categories", []) if isinstance(r, dict) else r
+
+    def get_category(self, slug: str) -> Optional[JsonDict]:
+        """Fetch one category and its products by slug."""
+        return self._request("GET", f"/v1/categories/{slug}")
+
+    # ---- CompanyData: structured company research ----
+
+    def get_company(self, domain: str) -> JsonDict:
+        """Structured company profile for a domain."""
+        return self._request("POST", "/v1/company", json={"domain": domain})
+
+    def get_pricing(self, domain: str) -> JsonDict:
+        """Structured pricing for a domain.
+
+        Note: the API reads ``domain`` from the query string for this endpoint,
+        not the body.
+        """
+        return self._request("POST", "/v1/pricing", params={"domain": domain})
+
+    def get_competitors(self, domain: str) -> JsonDict:
+        """Competitors and alternatives for a domain.
+
+        Note: the API reads ``domain`` from the query string for this endpoint,
+        not the body.
+        """
+        return self._request("POST", "/v1/competitors", params={"domain": domain})
+
+    def research(self, domain: str, question: Optional[str] = None) -> JsonDict:
+        """Grounded research answer about a domain, optionally scoped to a question."""
+        body: JsonDict = {"domain": domain}
+        if question:
+            body["question"] = question
+        return self._request("POST", "/v1/research", json=body)
+
+    def compare_companies(self, domains: List[str]) -> JsonDict:
+        """Compare multiple companies by domain."""
+        return self._request("POST", "/v1/compare-companies", json={"domains": domains})
+
+    # ---- Agent-native interface generation + hosting ----
+
+    def generate(self, domain: str, openapi_url: Optional[str] = None) -> JsonDict:
+        """Generate agent-native interfaces (MCP server, CLI, llms.txt, snippets)."""
+        body: JsonDict = {"domain": domain}
+        if openapi_url:
+            body["openapiUrl"] = openapi_url
+        return self._request("POST", "/v1/generate", json=body)
+
+    def deploy(self, domain: str, openapi_url: Optional[str] = None) -> JsonDict:
+        """Deploy a hosted MCP server for a domain."""
+        body: JsonDict = {"domain": domain}
+        if openapi_url:
+            body["openapiUrl"] = openapi_url
+        return self._request("POST", "/v1/deploy", json=body)
+
+    # ---- Agent Discovery + Score History ----
+
+    def get_discovery(self, slug: str) -> JsonDict:
+        """Read the latest Agent Discovery view for a slug."""
+        return self._request("GET", "/v1/discovery", params={"slug": slug})
+
+    def run_discovery(self, slug: str) -> JsonDict:
+        """Run an Agent Discovery check for a slug (requires an API key; spends credits)."""
+        return self._request("POST", "/v1/discovery/run", json={"slug": slug})
+
+    def get_score_history(self, slug: str) -> JsonDict:
+        """Read the score-history timeseries for a slug."""
+        return self._request("GET", "/v1/score-history", params={"slug": slug})
+
+    # ---- Monitors (require an API key) ----
+
+    def list_monitors(self) -> JsonDict:
+        """List monitors for the authenticated workspace."""
+        return self._request("GET", "/v1/monitors")
+
+    def add_monitor(
+        self,
+        slug: str,
+        cadence: Optional[str] = None,
+        kinds: Optional[List[str]] = None,
+        enabled: Optional[bool] = None,
+    ) -> JsonDict:
+        """Create or update a monitor for a slug."""
+        body: JsonDict = {"slug": slug}
+        if cadence is not None:
+            body["cadence"] = cadence
+        if kinds is not None:
+            body["kinds"] = kinds
+        if enabled is not None:
+            body["enabled"] = enabled
+        return self._request("POST", "/v1/monitors", json=body)
+
+    def run_monitor_now(self, slug: str) -> JsonDict:
+        """Run a monitor immediately for a slug."""
+        return self._request("POST", "/v1/monitors/run-now", json={"slug": slug})
+
+    # ---- Account (require an API key) ----
+
+    def get_usage(self) -> JsonDict:
+        """Usage for the authenticated workspace."""
+        return self._request("GET", "/v1/usage")
+
+    def get_my_profile(self) -> JsonDict:
+        """The authenticated workspace's own claimed profile (or null)."""
+        return self._request("GET", "/v1/me/profile")