ensemblai 0.1.0__tar.gz

ensemblai-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# build + dependency artifacts for the SDK packages
+python/.venv/
+python/dist/
+python/build/
+python/*.egg-info/
+python/**/__pycache__/
+node/node_modules/
+node/dist/
+node/package-lock.json

ensemblai-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: ensemblai
+Version: 0.1.0
+Summary: Client + CLI for EnsemblAI — download analytics, growth, dependencies, and ownership for PyPI and npm.
+Project-URL: Homepage, https://www.ensemblai.com
+Project-URL: Documentation, https://www.ensemblai.com/docs/agents
+Project-URL: API Reference, https://api.ensemblai.com/openapi.json
+Author: EnsemblAI
+License: MIT
+Keywords: analytics,dependencies,downloads,ecosystem,mcp,npm,package,pypi
+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
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# ensemblai
+
+Python client and CLI for [EnsemblAI](https://www.ensemblai.com) — software
+ecosystem intelligence for **PyPI and npm**: download analytics, month-over-month
+growth, dependency structure, and corporate ownership across millions of
+packages with multi-year daily history.
+
+> **Requires a Pro-plan API key.** Create an account, subscribe, and mint a key
+> at <https://www.ensemblai.com/settings/api-keys>. Prefer an AI agent? Connect
+> Claude Code, Cursor, or Codex to the MCP server instead — see
+> <https://www.ensemblai.com/docs/agents>.
+
+## Install
+
+```bash
+pip install ensemblai        # or: uv pip install ensemblai
+```
+
+## Quickstart
+
+```python
+from ensemblai import Client
+
+ea = Client()  # reads ENSEMBLAI_API_KEY from the environment
+
+numpy = ea.package("numpy")
+print(numpy["package_name"], numpy.get("latest_downloads"))
+
+for row in ea.top(limit=10, ecosystem="npm"):
+    print(row)
+
+trend = ea.time_series(["requests", "httpx"], granularity="monthly")
+```
+
+Pass the key explicitly if you'd rather not use the environment:
+
+```python
+ea = Client(api_key="ek_live_...", ecosystem="npm")
+```
+
+## CLI
+
+```bash
+export ENSEMBLAI_API_KEY=ek_live_...
+
+ensemblai pkg numpy
+ensemblai top --eco npm --limit 10
+ensemblai search "http client"
+ensemblai compare requests httpx aiohttp
+ensemblai companies --limit 20
+```
+
+## Methods
+
+| Method | REST endpoint | Returns |
+|---|---|---|
+| `package(name)` | `GET /v1/packages/{name}` | one package's full profile |
+| `search(query, limit=)` | `GET /v1/packages` | matching packages |
+| `top(limit=)` | `GET /v1/leaderboards/downloads` | 30-day download leaderboard |
+| `compare(names)` | `POST /v1/packages/batch` | side-by-side metrics |
+| `time_series(packages, granularity=)` | `GET /v1/analytics/time-series` | download history (weekly is Pro+) |
+| `companies(limit=)` | `GET /v1/companies` | corporate owners by footprint |
+| `reference(kind)` | `GET /v1/reference/{kind}` | valid filter values |
+| `get(path, **params)` | any | escape hatch for the full API |
+
+The full surface is documented in the [OpenAPI schema](https://api.ensemblai.com/openapi.json).
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `ENSEMBLAI_API_KEY` | — | your Pro API key (required) |
+| `ENSEMBLAI_BASE_URL` | `https://api.ensemblai.com` | override the API host |
+
+## License
+
+MIT

ensemblai-0.1.0/README.md

@@ -0,0 +1,77 @@
+# ensemblai
+
+Python client and CLI for [EnsemblAI](https://www.ensemblai.com) — software
+ecosystem intelligence for **PyPI and npm**: download analytics, month-over-month
+growth, dependency structure, and corporate ownership across millions of
+packages with multi-year daily history.
+
+> **Requires a Pro-plan API key.** Create an account, subscribe, and mint a key
+> at <https://www.ensemblai.com/settings/api-keys>. Prefer an AI agent? Connect
+> Claude Code, Cursor, or Codex to the MCP server instead — see
+> <https://www.ensemblai.com/docs/agents>.
+
+## Install
+
+```bash
+pip install ensemblai        # or: uv pip install ensemblai
+```
+
+## Quickstart
+
+```python
+from ensemblai import Client
+
+ea = Client()  # reads ENSEMBLAI_API_KEY from the environment
+
+numpy = ea.package("numpy")
+print(numpy["package_name"], numpy.get("latest_downloads"))
+
+for row in ea.top(limit=10, ecosystem="npm"):
+    print(row)
+
+trend = ea.time_series(["requests", "httpx"], granularity="monthly")
+```
+
+Pass the key explicitly if you'd rather not use the environment:
+
+```python
+ea = Client(api_key="ek_live_...", ecosystem="npm")
+```
+
+## CLI
+
+```bash
+export ENSEMBLAI_API_KEY=ek_live_...
+
+ensemblai pkg numpy
+ensemblai top --eco npm --limit 10
+ensemblai search "http client"
+ensemblai compare requests httpx aiohttp
+ensemblai companies --limit 20
+```
+
+## Methods
+
+| Method | REST endpoint | Returns |
+|---|---|---|
+| `package(name)` | `GET /v1/packages/{name}` | one package's full profile |
+| `search(query, limit=)` | `GET /v1/packages` | matching packages |
+| `top(limit=)` | `GET /v1/leaderboards/downloads` | 30-day download leaderboard |
+| `compare(names)` | `POST /v1/packages/batch` | side-by-side metrics |
+| `time_series(packages, granularity=)` | `GET /v1/analytics/time-series` | download history (weekly is Pro+) |
+| `companies(limit=)` | `GET /v1/companies` | corporate owners by footprint |
+| `reference(kind)` | `GET /v1/reference/{kind}` | valid filter values |
+| `get(path, **params)` | any | escape hatch for the full API |
+
+The full surface is documented in the [OpenAPI schema](https://api.ensemblai.com/openapi.json).
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `ENSEMBLAI_API_KEY` | — | your Pro API key (required) |
+| `ENSEMBLAI_BASE_URL` | `https://api.ensemblai.com` | override the API host |
+
+## License
+
+MIT

ensemblai-0.1.0/ensemblai/__init__.py

@@ -0,0 +1,8 @@
+"""EnsemblAI — software ecosystem intelligence for PyPI and npm.
+
+Download analytics, growth trends, dependency structure, and corporate
+ownership. Requires a Pro-plan API key: https://www.ensemblai.com/settings/api-keys
+"""
+from .client import Client, EnsemblAIError, __version__
+
+__all__ = ["Client", "EnsemblAIError", "__version__"]

ensemblai-0.1.0/ensemblai/cli.py

@@ -0,0 +1,86 @@
+"""Command-line interface for EnsemblAI.
+
+    export ENSEMBLAI_API_KEY=ek_live_...        # Pro plan
+    ensemblai pkg numpy
+    ensemblai top --eco npm --limit 10
+    ensemblai search "http client"
+    ensemblai compare requests httpx aiohttp
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .client import Client, EnsemblAIError, __version__
+
+
+def _emit(obj: Any) -> None:
+    json.dump(obj, sys.stdout, indent=2, default=str)
+    sys.stdout.write("\n")
+
+
+def _client(args: argparse.Namespace) -> Client:
+    return Client(ecosystem=args.eco)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ensemblai",
+        description="EnsemblAI — PyPI & npm ecosystem intelligence. "
+                    "Set ENSEMBLAI_API_KEY (Pro plan). Docs: https://www.ensemblai.com/docs/agents",
+    )
+    p.add_argument("--version", action="version", version=f"ensemblai {__version__}")
+
+    # Shared options every subcommand inherits, so `ensemblai top --eco npm`
+    # works (a top-level --eco would have to precede the subcommand).
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--eco", default="pypi", choices=["pypi", "npm"], help="Ecosystem (default: pypi)")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("pkg", parents=[common], help="Full profile for one package")
+    sp.add_argument("name")
+
+    sp = sub.add_parser("search", parents=[common], help="Search packages")
+    sp.add_argument("query")
+    sp.add_argument("--limit", type=int, default=20)
+
+    sp = sub.add_parser("top", parents=[common], help="Download leaderboard")
+    sp.add_argument("--limit", type=int, default=25)
+
+    sp = sub.add_parser("compare", parents=[common], help="Compare packages side by side")
+    sp.add_argument("names", nargs="+")
+
+    sp = sub.add_parser("companies", parents=[common], help="Corporate owners by footprint")
+    sp.add_argument("--limit", type=int, default=25)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        with _client(args) as ea:
+            if args.cmd == "pkg":
+                _emit(ea.package(args.name))
+            elif args.cmd == "search":
+                _emit(ea.search(args.query, limit=args.limit))
+            elif args.cmd == "top":
+                _emit(ea.top(limit=args.limit))
+            elif args.cmd == "compare":
+                _emit(ea.compare(args.names))
+            elif args.cmd == "companies":
+                _emit(ea.companies(limit=args.limit))
+    except ValueError as e:  # missing key
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    except EnsemblAIError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ensemblai-0.1.0/ensemblai/client.py

@@ -0,0 +1,134 @@
+"""Thin, typed client for the EnsemblAI REST API.
+
+The API base defaults to https://api.ensemblai.com and can be overridden with
+ENSEMBLAI_BASE_URL. Authentication uses a Pro-plan API key (``ek_live_…``),
+read from the ``api_key`` argument or the ENSEMBLAI_API_KEY environment
+variable. Get a key at https://www.ensemblai.com/settings/api-keys.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Optional, Sequence
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.ensemblai.com"
+__version__ = "0.1.0"
+
+
+class EnsemblAIError(RuntimeError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str, request_id: Optional[str] = None):
+        self.status = status
+        self.request_id = request_id
+        super().__init__(f"[{status}] {message}" + (f" (request_id={request_id})" if request_id else ""))
+
+
+class Client:
+    """A synchronous EnsemblAI API client.
+
+    >>> from ensemblai import Client
+    >>> ea = Client()                     # key from ENSEMBLAI_API_KEY
+    >>> ea.package("numpy")["package_name"]
+    'numpy'
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        ecosystem: str = "pypi",
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key or os.environ.get("ENSEMBLAI_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "No API key. Pass api_key= or set ENSEMBLAI_API_KEY. "
+                "Get one (Pro plan) at https://www.ensemblai.com/settings/api-keys"
+            )
+        self.base_url = (base_url or os.environ.get("ENSEMBLAI_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.ecosystem = ecosystem
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": f"ensemblai-python/{__version__}",
+            },
+        )
+
+    # -- low-level --------------------------------------------------------
+    def _request(self, method: str, path: str, *, params: Optional[dict] = None, json: Any = None) -> Any:
+        params = {k: v for k, v in (params or {}).items() if v is not None}
+        params.setdefault("ecosystem", self.ecosystem)
+        resp = self._http.request(method, path, params=params, json=json)
+        if resp.status_code >= 400:
+            body: dict = {}
+            try:
+                body = resp.json()
+            except Exception:
+                pass
+            err = body.get("error", {}) if isinstance(body, dict) else {}
+            meta = body.get("meta", {}) if isinstance(body, dict) else {}
+            raise EnsemblAIError(
+                resp.status_code,
+                (err.get("message") if isinstance(err, dict) else None) or resp.text[:200] or "request failed",
+                meta.get("request_id") if isinstance(meta, dict) else None,
+            )
+        payload = resp.json()
+        # The API wraps successes as {"data": ..., "meta": ...}; return data.
+        return payload.get("data", payload) if isinstance(payload, dict) else payload
+
+    def get(self, path: str, **params: Any) -> Any:
+        """Escape hatch: GET any endpoint from the OpenAPI schema."""
+        return self._request("GET", path, params=params)
+
+    # -- typed convenience methods ---------------------------------------
+    def package(self, name: str, *, ecosystem: Optional[str] = None) -> dict:
+        """Full profile for one package by its exact (lowercase) name."""
+        return self._request("GET", f"/v1/packages/{name}", params={"ecosystem": ecosystem})
+
+    def search(self, query: str, *, limit: int = 20, ecosystem: Optional[str] = None) -> Any:
+        """Search packages by name, summary, tags, or description."""
+        return self._request("GET", "/v1/packages", params={"q": query, "limit": limit, "ecosystem": ecosystem})
+
+    def top(self, *, limit: int = 25, ecosystem: Optional[str] = None) -> Any:
+        """The download leaderboard — packages ranked by 30-day downloads."""
+        return self._request("GET", "/v1/leaderboards/downloads", params={"limit": limit, "ecosystem": ecosystem})
+
+    def compare(self, names: Sequence[str], *, ecosystem: Optional[str] = None) -> Any:
+        """Compare packages side by side (30-day downloads, stars, quality)."""
+        return self._request("POST", "/v1/packages/batch", params={"ecosystem": ecosystem},
+                             json={"packages": list(names)})
+
+    def time_series(self, packages: Sequence[str] | str, *, granularity: str = "monthly",
+                    start_date: Optional[str] = None, end_date: Optional[str] = None,
+                    ecosystem: Optional[str] = None) -> Any:
+        """Download history for one or more packages over a window.
+
+        Weekly granularity requires Pro+ (monthly always available).
+        """
+        pkgs = packages if isinstance(packages, str) else ",".join(packages)
+        return self._request("GET", "/v1/analytics/time-series", params={
+            "packages": pkgs, "granularity": granularity,
+            "start_date": start_date, "end_date": end_date, "ecosystem": ecosystem,
+        })
+
+    def companies(self, *, limit: int = 25, ecosystem: Optional[str] = None) -> Any:
+        """Corporate owners ranked by their open-source footprint."""
+        return self._request("GET", "/v1/companies", params={"limit": limit, "ecosystem": ecosystem})
+
+    def reference(self, kind: str) -> Any:
+        """Valid filter values for a dimension (domains, categories, licenses, …)."""
+        return self._request("GET", f"/v1/reference/{kind}")
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

ensemblai-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ensemblai"
+version = "0.1.0"
+description = "Client + CLI for EnsemblAI — download analytics, growth, dependencies, and ownership for PyPI and npm."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "EnsemblAI" }]
+keywords = ["pypi", "npm", "analytics", "downloads", "dependencies", "package", "ecosystem", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://www.ensemblai.com"
+Documentation = "https://www.ensemblai.com/docs/agents"
+"API Reference" = "https://api.ensemblai.com/openapi.json"
+
+[project.scripts]
+ensemblai = "ensemblai.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ensemblai"]

ensemblai-0.1.0/tests/test_client.py

@@ -0,0 +1,60 @@
+"""Offline unit tests — no network, no key required (mock transport)."""
+import httpx
+import pytest
+
+from ensemblai import Client, EnsemblAIError
+
+
+def _client(handler):
+    ea = Client(api_key="ek_live_test", base_url="https://api.example.invalid")
+    ea._http = httpx.Client(
+        base_url="https://api.example.invalid",
+        transport=httpx.MockTransport(handler),
+        headers={"Authorization": "Bearer ek_live_test"},
+    )
+    return ea
+
+
+def test_requires_key(monkeypatch):
+    monkeypatch.delenv("ENSEMBLAI_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        Client()
+
+
+def test_unwraps_data_envelope():
+    def handler(req):
+        assert req.url.path == "/v1/packages/numpy"
+        assert req.url.params.get("ecosystem") == "pypi"
+        return httpx.Response(200, json={"data": {"package_name": "numpy"}, "meta": {"request_id": "req_1"}})
+
+    assert _client(handler).package("numpy") == {"package_name": "numpy"}
+
+
+def test_ecosystem_override_flows_through():
+    def handler(req):
+        assert req.url.params.get("ecosystem") == "npm"
+        return httpx.Response(200, json={"data": []})
+
+    _client(handler).top(ecosystem="npm")
+
+
+def test_compare_posts_body():
+    def handler(req):
+        assert req.method == "POST"
+        assert req.url.path == "/v1/packages/batch"
+        import json
+        assert json.loads(req.content)["packages"] == ["requests", "httpx"]
+        return httpx.Response(200, json={"data": [{"package_name": "requests"}]})
+
+    _client(handler).compare(["requests", "httpx"])
+
+
+def test_error_surfaces_message_and_request_id():
+    def handler(req):
+        return httpx.Response(403, json={"error": {"message": "Pro plan required"}, "meta": {"request_id": "req_x"}})
+
+    with pytest.raises(EnsemblAIError) as e:
+        _client(handler).package("numpy")
+    assert e.value.status == 403
+    assert "Pro plan required" in str(e.value)
+    assert e.value.request_id == "req_x"