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
