kepler-insights 1.0.0__tar.gz

kepler_insights-1.0.0/.gitignore

@@ -0,0 +1,75 @@
+# --- Secrets (NEVER commit) ---
+.env
+.env.*
+!.env.example
+*.pem
+*.p8
+*.p12
+*.key
+secrets.json
+credentials.json
+
+# --- AWS / Lambda build artifacts ---
+zips/
+**/package/
+*.zip
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+
+# --- Node ---
+node_modules/
+npm-debug.log*
+yarn-error.log*
+
+# --- Netlify ---
+.netlify/
+
+# --- macOS ---
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# --- Editors ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# --- Logs / scratch ---
+*.log
+/tmp/
+scratch/
+
+# --- Ki_dev: keep website/ + api_site/ + docs/ + sdk-python/ + sdk-typescript/ in git, everything else (admin, outreach, PDFs) backed up separately ---
+Ki_dev/*
+!Ki_dev/website/
+!Ki_dev/api_site/
+!Ki_dev/docs/
+!Ki_dev/sdk-python/
+!Ki_dev/sdk-typescript/
+
+# Python SDK build artifacts
+Ki_dev/sdk-python/dist/
+Ki_dev/sdk-python/build/
+Ki_dev/sdk-python/*.egg-info/
+Ki_dev/sdk-python/.pytest_cache/
+Ki_dev/sdk-python/.venv/
+
+# TypeScript SDK build artifacts
+Ki_dev/sdk-typescript/node_modules/
+Ki_dev/sdk-typescript/dist/
+Ki_dev/sdk-typescript/.turbo/
+Ki_dev/sdk-typescript/coverage/
+
+# --- Claude Code worktrees ---
+.claude/worktrees/

kepler_insights-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kepler Insights
+
+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.

kepler_insights-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: kepler-insights
+Version: 1.0.0
+Summary: Official Python SDK for the Kepler Insights API — curated company-scoring intelligence over a 67-signal engine.
+Project-URL: Homepage, https://api.keplerinsights.us
+Project-URL: Documentation, https://docs.keplerinsights.us
+Project-URL: Support, https://console.keplerinsights.us
+Author-email: Kepler Insights <noah@keplerinsights.us>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,company-intelligence,kepler,scoring,vc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Kepler Insights — Python SDK
+
+Official Python SDK for the [Kepler Insights API](https://api.keplerinsights.us) — curated company-scoring intelligence over a 67-signal engine.
+
+## Install
+
+```bash
+pip install kepler-insights
+```
+
+Requires Python 3.10+. Depends on [httpx](https://www.python-httpx.org/) and [pydantic v2](https://docs.pydantic.dev/latest/).
+
+## Quickstart
+
+```python
+from kepler_insights import Kepler
+
+with Kepler(api_key="ki_live_...") as client:
+    score = client.score("stripe.com")
+    print(f"{score.domain}: {score.ki_rating} ({score.composite_score:.1f})")
+    print(f"  team: {score.buckets.team_structure:.1f}")
+    print(f"  market: {score.buckets.market_position:.1f}")
+```
+
+Sandbox keys (`ki_test_...`) accept only the 4 canned domains — `acme.test`, `unicorn.test`, `struggling.test`, `cohort.test`. See the [Sandbox guide](https://docs.keplerinsights.us/sandbox).
+
+## API surface
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `client.score(domain)` | POST `/v1/score` | `Score` |
+| `client.get_score(domain)` | GET `/v1/score/{domain}` | `Score` |
+| `client.start_score(domain)` | POST `/v1/score?wait=false` | `Job` (Growth+) |
+| `client.get_job(job_id)` | GET `/v1/jobs/{job_id}` | `JobResponse` |
+| `client.history(domain, limit=, cursor=)` | GET `/v1/score/{domain}/history` | `HistoryPage` |
+| `client.iter_history(domain, max_records=)` | (auto-paginates) | iterator of `HistoryRecord` |
+| `client.cohort(domain)` | GET `/v1/company/{domain}/cohort` | `Cohort` |
+| `client.confidence(domain)` | GET `/v1/company/{domain}/confidence` | `Confidence` |
+| `client.distribution()` | GET `/v1/distribution` | `Distribution` |
+| `client.movers(window)` | GET `/v1/movers` | `Movers` |
+| `client.signals()` | GET `/v1/signals` | `SignalsManifest` |
+| `client.usage()` | GET `/v1/usage` | `Usage` |
+
+## Async cold scoring
+
+Cold scoring takes 30–60 seconds. On Growth and above, you can start a job and poll without holding an HTTP connection open:
+
+```python
+job = client.start_score("stripe.com")    # returns immediately
+score = job.wait(timeout=180)             # blocks until complete; raises on timeout
+```
+
+If the API short-circuits to a cached-fresh response (no cold work needed), `start_score` returns a `Job` already in the `complete` state — `wait()` returns instantly. This mirrors Stripe's `payment_intent` "no action needed" pattern.
+
+## Error handling
+
+Every error inherits from `KeplerError`. Branch on the specific subclass or the stable `error.code` string:
+
+```python
+from kepler_insights import (
+    Kepler,
+    AuthError,
+    ColdBudgetExhausted,
+    FreeTierSandboxOnly,
+    NotFound,
+    RateLimitError,
+    ScoringTimeout,
+)
+
+try:
+    score = client.score("stripe.com")
+except FreeTierSandboxOnly:
+    print("Upgrade to Starter for live scoring.")
+except ColdBudgetExhausted as e:
+    print(f"Monthly cap hit. Resets in {e.retry_after}s. Upgrade for more.")
+except RateLimitError as e:
+    print(f"Rate limited. Retry in {e.retry_after}s.")
+except ScoringTimeout:
+    print("Cold scoring exceeded sync budget — use start_score() for async.")
+except NotFound:
+    print("Never scored. Trigger one with score(domain).")
+except AuthError:
+    print("Invalid or revoked API key.")
+```
+
+The SDK auto-retries on 5xx and network errors with exponential backoff (3 attempts by default). It never retries 4xx — those are caller errors.
+
+## Configuration
+
+```python
+client = Kepler(
+    api_key="ki_live_...",
+    base_url="https://api.keplerinsights.us",   # override only for testing
+    timeout=70.0,                                # per-request timeout (s)
+    retries=3,                                   # 5xx retry attempts
+)
+```
+
+For custom transports (proxies, mTLS, etc.) inject your own `httpx.Client`:
+
+```python
+import httpx
+custom = httpx.Client(timeout=120, transport=httpx.HTTPTransport(retries=0))
+client = Kepler(api_key="ki_live_...", http_client=custom)
+```
+
+## Development
+
+```bash
+git clone <repo>
+cd Ki_dev/sdk-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. The API itself is proprietary; the SDK wrapper is MIT-licensed so you can vendor it freely.

kepler_insights-1.0.0/PUBLISH.md

@@ -0,0 +1,128 @@
+# Publishing `kepler-insights` to PyPI
+
+Run this checklist at the **coordinated API launch event** (same window as Mintlify, Instatus, Stripe SKU creation, and the `api.keplerinsights.us` DNS flip). All code is pre-shipped (F1, 2026-05-12) — this checklist just publishes.
+
+## 0. Prereqs
+
+- A PyPI account on the Kepler Insights org (https://pypi.org). Reserve the `kepler-insights` name well before launch event by uploading version 0.0.1 placeholder, or check it's still available.
+- A TestPyPI account (https://test.pypi.org) for the dry run.
+- A PyPI API token scoped to `kepler-insights` (Account settings → API tokens → "scope to project").
+- A TestPyPI API token (separate token, separate account).
+- Python 3.11+ locally with `build` and `twine` available.
+
+## 1. Pre-flight checks
+
+```bash
+cd Ki_dev/sdk-python
+
+# Clean state
+rm -rf dist/ build/ *.egg-info src/*.egg-info
+
+# Run tests
+python3.13 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[dev]"
+pytest                                                     # expect 33 passing
+
+# Lint
+ruff check src tests
+
+# Confirm version is what you want to publish
+grep '__version__' src/kepler_insights/_version.py        # expect 1.0.0
+```
+
+## 2. Build artifacts
+
+```bash
+python -m build
+ls -la dist/
+# expect:
+#   kepler_insights-1.0.0-py3-none-any.whl
+#   kepler_insights-1.0.0.tar.gz
+```
+
+Inspect the sdist contents before uploading:
+```bash
+tar -tzf dist/kepler_insights-1.0.0.tar.gz | head -30
+```
+
+Should include `src/kepler_insights/*.py`, `pyproject.toml`, `README.md`, `LICENSE`. Should NOT include `.venv/`, `.pytest_cache/`, `tests/` (by hatchling default).
+
+## 3. Upload to TestPyPI first
+
+```bash
+pip install --upgrade twine
+twine upload --repository testpypi dist/*
+# username: __token__
+# password: <TestPyPI API token starting `pypi-...`>
+```
+
+Verify in a clean venv that the install works:
+
+```bash
+deactivate
+rm -rf /tmp/sdk-verify && python3.13 -m venv /tmp/sdk-verify
+/tmp/sdk-verify/bin/pip install --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  kepler-insights
+/tmp/sdk-verify/bin/python -c "from kepler_insights import Kepler; print(Kepler)"
+```
+
+The `--extra-index-url` to real PyPI is required because TestPyPI doesn't host httpx/pydantic.
+
+## 4. Upload to production PyPI
+
+```bash
+source .venv/bin/activate
+twine upload dist/*
+# username: __token__
+# password: <PyPI production API token>
+```
+
+## 5. Post-publish verification
+
+```bash
+# Fresh venv, no override
+rm -rf /tmp/sdk-prod-verify && python3.13 -m venv /tmp/sdk-prod-verify
+/tmp/sdk-prod-verify/bin/pip install kepler-insights
+/tmp/sdk-prod-verify/bin/python -c "
+from kepler_insights import Kepler, __version__
+print('version:', __version__)
+print('Kepler client class:', Kepler)
+"
+
+# Page check
+open https://pypi.org/project/kepler-insights/
+# expect: project page shows version 1.0.0, links to api.keplerinsights.us,
+# README rendered cleanly
+```
+
+## 6. Update downstream
+
+- [ ] Update [Ki_dev/docs/quickstart.mdx](../docs/quickstart.mdx) install instruction if needed.
+- [ ] Update [Ki_dev/api_site/index.html](../api_site/index.html) "Install the SDK" hero with the `pip install kepler-insights` snippet.
+- [ ] Announce in the launch blast email.
+
+## Rollback / yank
+
+If a release is broken:
+
+```bash
+# Yank the version (still installable by explicit pin, but no longer the default)
+twine yank kepler-insights 1.0.0
+```
+
+Yank is reversible. Don't `twine delete` — once deleted, the version number can never be reused.
+
+For a hotfix release: bump `_version.py` to `1.0.1`, re-test, re-build, re-upload. PyPI doesn't allow re-uploading a version that already exists.
+
+## Versioning policy
+
+Semantic versioning. The OpenAPI spec at `Ki_dev/docs/openapi.yaml` is the source of truth for breaking-change detection:
+
+- **Patch (1.0.x)** — bug fixes, no public-surface changes
+- **Minor (1.x.0)** — additive: new methods, new fields on response models (Pydantic `extra="allow"` keeps old code working)
+- **Major (x.0.0)** — removal or rename of a public method / model field
+
+If the API ships a v2, this SDK ships a `2.0.0` adding a `KeplerV2` client class alongside `Kepler` (which keeps targeting v1 endpoints) — same pattern as `openai.OpenAI` vs `openai.AzureOpenAI`. Don't break v1 callers when v2 lands.

kepler_insights-1.0.0/README.md

@@ -0,0 +1,120 @@
+# Kepler Insights — Python SDK
+
+Official Python SDK for the [Kepler Insights API](https://api.keplerinsights.us) — curated company-scoring intelligence over a 67-signal engine.
+
+## Install
+
+```bash
+pip install kepler-insights
+```
+
+Requires Python 3.10+. Depends on [httpx](https://www.python-httpx.org/) and [pydantic v2](https://docs.pydantic.dev/latest/).
+
+## Quickstart
+
+```python
+from kepler_insights import Kepler
+
+with Kepler(api_key="ki_live_...") as client:
+    score = client.score("stripe.com")
+    print(f"{score.domain}: {score.ki_rating} ({score.composite_score:.1f})")
+    print(f"  team: {score.buckets.team_structure:.1f}")
+    print(f"  market: {score.buckets.market_position:.1f}")
+```
+
+Sandbox keys (`ki_test_...`) accept only the 4 canned domains — `acme.test`, `unicorn.test`, `struggling.test`, `cohort.test`. See the [Sandbox guide](https://docs.keplerinsights.us/sandbox).
+
+## API surface
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `client.score(domain)` | POST `/v1/score` | `Score` |
+| `client.get_score(domain)` | GET `/v1/score/{domain}` | `Score` |
+| `client.start_score(domain)` | POST `/v1/score?wait=false` | `Job` (Growth+) |
+| `client.get_job(job_id)` | GET `/v1/jobs/{job_id}` | `JobResponse` |
+| `client.history(domain, limit=, cursor=)` | GET `/v1/score/{domain}/history` | `HistoryPage` |
+| `client.iter_history(domain, max_records=)` | (auto-paginates) | iterator of `HistoryRecord` |
+| `client.cohort(domain)` | GET `/v1/company/{domain}/cohort` | `Cohort` |
+| `client.confidence(domain)` | GET `/v1/company/{domain}/confidence` | `Confidence` |
+| `client.distribution()` | GET `/v1/distribution` | `Distribution` |
+| `client.movers(window)` | GET `/v1/movers` | `Movers` |
+| `client.signals()` | GET `/v1/signals` | `SignalsManifest` |
+| `client.usage()` | GET `/v1/usage` | `Usage` |
+
+## Async cold scoring
+
+Cold scoring takes 30–60 seconds. On Growth and above, you can start a job and poll without holding an HTTP connection open:
+
+```python
+job = client.start_score("stripe.com")    # returns immediately
+score = job.wait(timeout=180)             # blocks until complete; raises on timeout
+```
+
+If the API short-circuits to a cached-fresh response (no cold work needed), `start_score` returns a `Job` already in the `complete` state — `wait()` returns instantly. This mirrors Stripe's `payment_intent` "no action needed" pattern.
+
+## Error handling
+
+Every error inherits from `KeplerError`. Branch on the specific subclass or the stable `error.code` string:
+
+```python
+from kepler_insights import (
+    Kepler,
+    AuthError,
+    ColdBudgetExhausted,
+    FreeTierSandboxOnly,
+    NotFound,
+    RateLimitError,
+    ScoringTimeout,
+)
+
+try:
+    score = client.score("stripe.com")
+except FreeTierSandboxOnly:
+    print("Upgrade to Starter for live scoring.")
+except ColdBudgetExhausted as e:
+    print(f"Monthly cap hit. Resets in {e.retry_after}s. Upgrade for more.")
+except RateLimitError as e:
+    print(f"Rate limited. Retry in {e.retry_after}s.")
+except ScoringTimeout:
+    print("Cold scoring exceeded sync budget — use start_score() for async.")
+except NotFound:
+    print("Never scored. Trigger one with score(domain).")
+except AuthError:
+    print("Invalid or revoked API key.")
+```
+
+The SDK auto-retries on 5xx and network errors with exponential backoff (3 attempts by default). It never retries 4xx — those are caller errors.
+
+## Configuration
+
+```python
+client = Kepler(
+    api_key="ki_live_...",
+    base_url="https://api.keplerinsights.us",   # override only for testing
+    timeout=70.0,                                # per-request timeout (s)
+    retries=3,                                   # 5xx retry attempts
+)
+```
+
+For custom transports (proxies, mTLS, etc.) inject your own `httpx.Client`:
+
+```python
+import httpx
+custom = httpx.Client(timeout=120, transport=httpx.HTTPTransport(retries=0))
+client = Kepler(api_key="ki_live_...", http_client=custom)
+```
+
+## Development
+
+```bash
+git clone <repo>
+cd Ki_dev/sdk-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. The API itself is proprietary; the SDK wrapper is MIT-licensed so you can vendor it freely.

kepler_insights-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires      = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name        = "kepler-insights"
+dynamic     = ["version"]
+description = "Official Python SDK for the Kepler Insights API — curated company-scoring intelligence over a 67-signal engine."
+readme      = "README.md"
+license     = "MIT"
+license-files = ["LICENSE"]
+authors     = [{ name = "Kepler Insights", email = "noah@keplerinsights.us" }]
+requires-python = ">=3.10"
+keywords    = ["kepler", "scoring", "company-intelligence", "vc", "api-client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[project.urls]
+Homepage      = "https://api.keplerinsights.us"
+Documentation = "https://docs.keplerinsights.us"
+Support       = "https://console.keplerinsights.us"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21",
+    "ruff>=0.5",
+    "build>=1.0",
+]
+
+[tool.hatch.version]
+path = "src/kepler_insights/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kepler_insights"]
+
+[tool.pytest.ini_options]
+testpaths   = ["tests"]
+addopts     = "-ra --strict-markers"
+pythonpath  = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

kepler_insights-1.0.0/src/kepler_insights/__init__.py

@@ -0,0 +1,54 @@
+"""Kepler Insights API — official Python SDK.
+
+Quickstart
+----------
+
+>>> from kepler_insights import Kepler
+>>> with Kepler(api_key="ki_live_...") as client:
+...     score = client.score("stripe.com")
+...     print(score.ki_rating, score.composite_score)
+
+See https://docs.keplerinsights.us for the full guide.
+"""
+
+from ._version import __version__
+from .client import Kepler, Job
+from . import errors, models
+
+# Common error classes re-exported at the top level for ergonomic imports:
+#   from kepler_insights import KeplerError, RateLimitError, ColdBudgetExhausted
+from .errors import (
+    KeplerError,
+    AuthError,
+    FreeTierSandboxOnly,
+    Forbidden,
+    NotFound,
+    ValidationError,
+    RateLimitError,
+    ColdBudgetExhausted,
+    ServerError,
+    ScoringTimeout,
+    JobTimeout,
+    JobFailed,
+)
+
+__all__ = [
+    "__version__",
+    "Kepler",
+    "Job",
+    "errors",
+    "models",
+    # Error classes
+    "KeplerError",
+    "AuthError",
+    "FreeTierSandboxOnly",
+    "Forbidden",
+    "NotFound",
+    "ValidationError",
+    "RateLimitError",
+    "ColdBudgetExhausted",
+    "ServerError",
+    "ScoringTimeout",
+    "JobTimeout",
+    "JobFailed",
+]