databubble 0.2.0__tar.gz

databubble-0.2.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: databubble
+Version: 0.2.0
+Summary: Statistical Intelligence as a Service — rigorous analysis skills via API
+Author: DataBubble AI
+License: MIT
+Project-URL: Homepage, https://databubble.ai
+Project-URL: Documentation, https://api.databubble.ai
+Project-URL: Repository, https://github.com/sss828412/databubble-python
+Project-URL: Issues, https://github.com/sss828412/databubble-python/issues
+Keywords: statistics,data analysis,machine learning,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: recommended
+Requires-Dist: httpx>=0.24; extra == "recommended"
+Requires-Dist: pandas>=1.5; extra == "recommended"
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+
+# DataBubble SDK
+
+Statistical Intelligence as a Service.
+
+```bash
+pip install databubble httpx pandas
+```
+
+## Quick start
+
+```python
+from databubble import DataBubble
+import pandas as pd
+
+db = DataBubble(api_key="dbk_...")
+
+# Univariate analysis
+result = db.skills.univariate(df["price"])
+print(result.summary)
+print(result.warnings)
+
+# Missing value profiling
+result = db.skills.missing_values(df)
+
+# Export session memory for next session
+mem = db.memory.export(df, label="POS data June 2026")
+mem.save("pos_memory.json")
+```
+
+## Available skills
+
+| Skill | Input | What it does |
+|---|---|---|
+| `univariate` | Series or DataFrame + column= | Distribution analysis, skewness, bounded ordinal detection, MNAR flags |
+| `outliers` | Series or DataFrame + column= | IQR + Z-score outlier detection |
+| `missing_values` | DataFrame | MCAR/MAR/MNAR profiling, treatment recommendations |
+| `leakage` | DataFrame + outcome= | Post-outcome timing detection, correlation proxy check |
+| `bivariate` | DataFrame + x= + y= | Relationship analysis, linearity check |
+| `correlation` | DataFrame + x= + y= | Pearson + Spearman, non-linearity flag |
+
+## Tiers
+
+| Tier | Price | Calls/month | Skills |
+|---|---|---|---|
+| Developer | Free | 500 | Core analysis skills |
+| Pro | $49/month | 10,000 | All skills |
+| Business | $299/month | 100,000 | All skills + journey endpoints |
+| Enterprise | Custom | Unlimited | Everything |
+
+Get a key at [databubble.ai](https://databubble.ai).

databubble-0.2.0/README.md

@@ -0,0 +1,50 @@
+# DataBubble SDK
+
+Statistical Intelligence as a Service.
+
+```bash
+pip install databubble httpx pandas
+```
+
+## Quick start
+
+```python
+from databubble import DataBubble
+import pandas as pd
+
+db = DataBubble(api_key="dbk_...")
+
+# Univariate analysis
+result = db.skills.univariate(df["price"])
+print(result.summary)
+print(result.warnings)
+
+# Missing value profiling
+result = db.skills.missing_values(df)
+
+# Export session memory for next session
+mem = db.memory.export(df, label="POS data June 2026")
+mem.save("pos_memory.json")
+```
+
+## Available skills
+
+| Skill | Input | What it does |
+|---|---|---|
+| `univariate` | Series or DataFrame + column= | Distribution analysis, skewness, bounded ordinal detection, MNAR flags |
+| `outliers` | Series or DataFrame + column= | IQR + Z-score outlier detection |
+| `missing_values` | DataFrame | MCAR/MAR/MNAR profiling, treatment recommendations |
+| `leakage` | DataFrame + outcome= | Post-outcome timing detection, correlation proxy check |
+| `bivariate` | DataFrame + x= + y= | Relationship analysis, linearity check |
+| `correlation` | DataFrame + x= + y= | Pearson + Spearman, non-linearity flag |
+
+## Tiers
+
+| Tier | Price | Calls/month | Skills |
+|---|---|---|---|
+| Developer | Free | 500 | Core analysis skills |
+| Pro | $49/month | 10,000 | All skills |
+| Business | $299/month | 100,000 | All skills + journey endpoints |
+| Enterprise | Custom | Unlimited | Everything |
+
+Get a key at [databubble.ai](https://databubble.ai).

databubble-0.2.0/databubble/__init__.py

@@ -0,0 +1,33 @@
+# databubble/__init__.py
+"""
+DataBubble SDK — Statistical Intelligence as a Service.
+
+Quick start:
+    from databubble import DataBubble
+    db = DataBubble(api_key="dbk_...")
+    result = db.skills.univariate(df["price"])
+    print(result.summary)
+"""
+
+from databubble.client import DataBubble
+from databubble.models import SkillResult, MemoryResult, ReconciliationResult, JourneyResult
+from databubble.exceptions import (
+    DataBubbleError, AuthError, ForbiddenError,
+    RateLimitError, SkillError, ServerError, SDKUsageError,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "DataBubble",
+    "SkillResult",
+    "MemoryResult",
+    "ReconciliationResult",
+    "JourneyResult",
+    "DataBubbleError",
+    "AuthError",
+    "ForbiddenError",
+    "RateLimitError",
+    "SkillError",
+    "ServerError",
+    "SDKUsageError",
+]

databubble-0.2.0/databubble/client.py

@@ -0,0 +1,204 @@
+# databubble/client.py
+"""
+DataBubble — root client.
+
+Usage:
+    from databubble import DataBubble
+    db = DataBubble(api_key="dbk_...")
+    result = db.skills.univariate(df["price"])
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from databubble.exceptions import (
+    AuthError, ForbiddenError, RateLimitError,
+    SkillError, ServerError, DataBubbleError,
+)
+from databubble.skills import SkillsClient
+from databubble.memory import MemoryClient
+from databubble.journeys import JourneysClient
+
+
+DEFAULT_BASE_URL = "https://api.databubble.ai"
+
+
+class _HTTPClient:
+    """
+    Thin HTTP client. Uses httpx if available, falls back to urllib.
+    Handles auth header injection and error mapping.
+    """
+
+    def __init__(self, api_key: str, base_url: str, timeout: float):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = None
+        self._init_session()
+
+    def _init_session(self):
+        try:
+            import httpx
+            self._session = httpx.Client(
+                base_url=self._base_url,
+                headers={"X-API-Key": self._api_key},
+                timeout=self._timeout,
+            )
+            self._backend = "httpx"
+        except ImportError:
+            # Fall back to urllib — no session, headers injected per-request
+            self._backend = "urllib"
+
+    def _raise_for_status(self, status_code: int, body: dict):
+        # Route-level errors wrap in {"detail": {"error": ...}};
+        # middleware errors use flat {"error": ...}. Extract from both (M-9).
+        detail = body.get("detail") or {}
+        msg = (
+            (detail.get("error") if isinstance(detail, dict) else None)
+            or body.get("error")
+            or f"HTTP {status_code}"
+        )
+        if status_code == 401:
+            raise AuthError(msg, status_code, body)
+        if status_code == 403:
+            raise ForbiddenError(msg, status_code, body)
+        if status_code == 429:
+            raise RateLimitError(msg, status_code, body)
+        if status_code in (400, 422):  # 422 was falling through to generic DataBubbleError (D-4)
+            raise SkillError(msg, status_code, body)
+        if status_code >= 500:
+            raise ServerError(f"Server error ({status_code}): {msg}", status_code, body)
+        if status_code >= 400:
+            raise DataBubbleError(msg, status_code, body)
+
+    def post_json(self, path: str, payload: dict) -> dict:
+        """POST with JSON body. Returns parsed response dict."""
+        url = f"{self._base_url}{path}"
+
+        if self._backend == "httpx":
+            response = self._session.post(path, json=payload)
+            body = response.json()
+            self._raise_for_status(response.status_code, body)
+            return body
+        else:
+            import urllib.request, urllib.error
+            data = json.dumps(payload).encode()
+            req = urllib.request.Request(
+                url, data=data,
+                headers={
+                    "Content-Type": "application/json",
+                    "X-API-Key": self._api_key,
+                },
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    return json.loads(resp.read())
+            except urllib.error.HTTPError as e:
+                body = json.loads(e.read())
+                self._raise_for_status(e.code, body)
+                # _raise_for_status always raises for 4xx/5xx; this is a safety net
+                raise ServerError(f"Unexpected response ({e.code})", e.code, body)
+
+    def post_multipart(self, path: str, fields: dict, files) -> dict:
+        """
+        POST with multipart form data. Returns parsed response dict.
+
+        files may be:
+          - dict: {field_name: (filename, data, content_type)} — single file per field
+          - list of (field_name, (filename, data, content_type)) — supports repeated field names
+            for list[UploadFile] parameters (M-5: memory_files needs repeated "memory_files" key)
+        """
+        url = f"{self._base_url}{path}"
+
+        if self._backend == "httpx":
+            form_data = {k: v for k, v in fields.items() if v is not None}
+            # httpx accepts files as a list of (name, content) tuples for repeated keys
+            if isinstance(files, dict):
+                file_list = [(k, v) for k, v in files.items()]
+            else:
+                file_list = list(files)
+            response = self._session.post(path, data=form_data, files=file_list)
+            body = response.json()
+            self._raise_for_status(response.status_code, body)
+            return body
+        else:
+            raise DataBubbleError(
+                "Multipart upload requires httpx. "
+                "Install with: pip install httpx"
+            )
+
+    def close(self):
+        if self._backend == "httpx" and self._session:
+            self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class DataBubble:
+    """
+    DataBubble API client.
+
+    Args:
+        api_key:  Your API key (starts with dbk_). Get one at databubble.ai.
+        base_url: API base URL. Defaults to https://api.databubble.ai.
+                  Override for local development: http://localhost:8000
+        timeout:  Request timeout in seconds. Default 60.
+
+    Example:
+        from databubble import DataBubble
+        db = DataBubble(api_key="dbk_...")
+
+        # Single-column skill
+        result = db.skills.univariate(df["price"])
+        print(result.summary)
+        print(result.warnings)
+
+        # Whole-dataset skill
+        result = db.skills.missing_values(df)
+
+        # Memory workflow
+        mem = db.memory.export(df, label="POS data June 2026")
+        mem.save("pos_memory.json")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ):
+        import os
+        resolved_key = api_key or os.environ.get("DATABUBBLE_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "API key required. Pass api_key= or set DATABUBBLE_API_KEY env var. "
+                "Get a key at databubble.ai."
+            )
+        if not resolved_key.startswith("dbk_"):
+            raise ValueError(
+                f"Invalid API key format. Keys start with 'dbk_'. Got: {resolved_key[:8]}..."
+            )
+
+        self._http = _HTTPClient(resolved_key, base_url, timeout)
+        self.skills = SkillsClient(self._http)
+        self.memory = MemoryClient(self._http)
+        self.journeys = JourneysClient(self._http)
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __repr__(self):
+        return f"DataBubble(base_url='{self._http._base_url}')"

databubble-0.2.0/databubble/exceptions.py

@@ -0,0 +1,47 @@
+# databubble/exceptions.py
+"""
+Typed exceptions for the DataBubble SDK.
+Every HTTP error from the API maps to a specific exception class
+so callers can handle them explicitly without parsing status codes.
+"""
+
+
+class DataBubbleError(Exception):
+    """Base exception for all SDK errors."""
+    def __init__(self, message: str, status_code: int = 0, response_body: dict = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body or {}
+
+
+class AuthError(DataBubbleError):
+    """Invalid or missing API key. HTTP 401."""
+    pass
+
+
+class ForbiddenError(DataBubbleError):
+    """Skill not available on this tier. HTTP 403."""
+    pass
+
+
+class RateLimitError(DataBubbleError):
+    """Monthly call limit reached. HTTP 429."""
+    pass
+
+
+class SkillError(DataBubbleError):
+    """Skill executed but returned an error (bad input, halted, etc). HTTP 400."""
+    pass
+
+
+class ServerError(DataBubbleError):
+    """Unexpected server error. HTTP 5xx."""
+    pass
+
+
+class SDKUsageError(Exception):
+    """
+    Raised for incorrect SDK usage — wrong argument types, missing required args.
+    Not an API error — never reaches the server.
+    """
+    pass