featrixevents 0.1.0__tar.gz

featrixevents-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: featrixevents
+Version: 0.1.0
+Summary: Post events to the Featrix platform.
+Home-page: https://github.com/Featrix/sphere
+Author: Featrix
+Author-email: support@featrix.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/plain
+Requires-Dist: requests>=2.20.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Post events to the Featrix platform. See https://docs.featrix.com

featrixevents-0.1.0/__init__.py

@@ -0,0 +1,29 @@
+#  -*- coding: utf-8 -*-
+#
+#  Copyright (c) 2023-2026 Featrix, Inc, All Rights Reserved
+#
+#  Proprietary and Confidential.  Unauthorized use, copying or dissemination
+#  of these materials is strictly prohibited.
+#
+
+"""
+Featrix Events - Post events to the Featrix platform.
+
+Usage:
+    from featrixevents import featrix_post_event
+
+    featrix_post_event(
+        auth_key_id="fx_...",
+        event_group_id="<uuid>",
+        event_payload={"action": "button_click", "page": "/dashboard"}
+    )
+"""
+
+__version__ = "0.1.0"
+__author__ = "Featrix"
+__email__ = "support@featrix.com"
+__license__ = "MIT"
+
+from ._post_event import featrix_post_event, FeatrixEventError
+
+__all__ = ["featrix_post_event", "FeatrixEventError"]

featrixevents-0.1.0/_post_event.py

@@ -0,0 +1,87 @@
+#  -*- coding: utf-8 -*-
+#
+#  Copyright (c) 2023-2026 Featrix, Inc, All Rights Reserved
+#
+#  Proprietary and Confidential.  Unauthorized use, copying or dissemination
+#  of these materials is strictly prohibited.
+#
+
+"""Core implementation of featrix_post_event."""
+
+import os
+
+import requests
+
+DEFAULT_BASE_URL = "https://sphere-api.featrix.com"
+
+
+class FeatrixEventError(Exception):
+    """Raised when posting an event fails."""
+
+    def __init__(self, message, status_code=None, response_body=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+def featrix_post_event(
+    auth_key_id: str,
+    event_group_id: str,
+    event_payload: dict,
+    base_url: str = None,
+    timeout: float = 30.0,
+) -> dict:
+    """
+    Post an event to the Featrix platform.
+
+    Args:
+        auth_key_id: API key (e.g. "fx_..."). NOT a JWT.
+        event_group_id: UUID string grouping related events.
+        event_payload: Arbitrary dict to store as the event payload.
+        base_url: Server URL. Defaults to FEATRIX_BASE_URL env var
+                  or "https://sphere-api.featrix.com".
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Dict with "success" (bool) and "event_id" (str UUID).
+
+    Raises:
+        FeatrixEventError: On auth failure, server error, or connection error.
+    """
+    if base_url is None:
+        base_url = os.getenv("FEATRIX_BASE_URL", DEFAULT_BASE_URL)
+
+    url = f"{base_url.rstrip('/')}/events/ingest"
+
+    headers = {
+        "X-Api-Key": auth_key_id,
+        "Content-Type": "application/json",
+    }
+
+    body = {
+        "event_group_id": event_group_id,
+        "event_payload": event_payload,
+    }
+
+    try:
+        resp = requests.post(url, json=body, headers=headers, timeout=timeout)
+    except requests.ConnectionError as e:
+        raise FeatrixEventError(f"Connection error: {e}") from e
+    except requests.Timeout as e:
+        raise FeatrixEventError(f"Request timed out after {timeout}s") from e
+
+    if resp.status_code in (200, 201):
+        return resp.json()
+
+    # Error path
+    try:
+        error_body = resp.json()
+        error_msg = error_body.get("error", resp.text)
+    except Exception:
+        error_msg = resp.text
+
+    raise FeatrixEventError(
+        f"Event post failed (HTTP {resp.status_code}): {error_msg}",
+        status_code=resp.status_code,
+        response_body=resp.text,
+    )

featrixevents-0.1.0/featrixevents.egg-info/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: featrixevents
+Version: 0.1.0
+Summary: Post events to the Featrix platform.
+Home-page: https://github.com/Featrix/sphere
+Author: Featrix
+Author-email: support@featrix.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/plain
+Requires-Dist: requests>=2.20.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Post events to the Featrix platform. See https://docs.featrix.com

featrixevents-0.1.0/featrixevents.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+__init__.py
+_post_event.py
+setup.py
+./__init__.py
+./_post_event.py
+featrixevents.egg-info/PKG-INFO
+featrixevents.egg-info/SOURCES.txt
+featrixevents.egg-info/dependency_links.txt
+featrixevents.egg-info/not-zip-safe
+featrixevents.egg-info/requires.txt
+featrixevents.egg-info/top_level.txt
+tests/test_e2e_collect_and_build.py

featrixevents-0.1.0/featrixevents.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

featrixevents-0.1.0/featrixevents.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

featrixevents-0.1.0/featrixevents.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.20.0

featrixevents-0.1.0/featrixevents.egg-info/top_level.txt

@@ -0,0 +1 @@
+featrixevents

featrixevents-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

featrixevents-0.1.0/setup.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+#  -*- coding: utf-8 -*-
+#
+#  Copyright (c) 2023-2026 Featrix, Inc, All Rights Reserved
+#
+#  Proprietary and Confidential.  Unauthorized use, copying or dissemination
+#  of these materials is strictly prohibited.
+#
+
+"""Setup script for featrixevents package."""
+
+from setuptools import setup
+from pathlib import Path
+
+this_directory = Path(__file__).parent
+
+
+def get_version():
+    init_file = this_directory / "__init__.py"
+    if init_file.exists():
+        for line in init_file.read_text().splitlines():
+            if line.startswith("__version__"):
+                return line.split('"')[1]
+    return "0.1.0"
+
+
+setup(
+    name="featrixevents",
+    version=get_version(),
+    author="Featrix",
+    author_email="support@featrix.com",
+    description="Post events to the Featrix platform.",
+    long_description="Post events to the Featrix platform. See https://docs.featrix.com",
+    long_description_content_type="text/plain",
+    url="https://github.com/Featrix/sphere",
+    packages=["featrixevents"],
+    package_dir={"featrixevents": "."},
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+    ],
+    python_requires=">=3.8",
+    install_requires=[
+        "requests>=2.20.0",
+    ],
+    zip_safe=False,
+)

featrixevents-0.1.0/tests/test_e2e_collect_and_build.py

@@ -0,0 +1,313 @@
+#  -*- coding: utf-8 -*-
+#
+#  Copyright (c) 2023-2026 Featrix, Inc, All Rights Reserved
+#
+#  Proprietary and Confidential.  Unauthorized use, copying or dissemination
+#  of these materials is strictly prohibited.
+#
+
+"""
+End-to-end test for the featrixevents library.
+
+Posts ~500 synthetic events with featrix_post_event(), then calls the
+new /events/build-model endpoint to confirm Featrix can:
+  1. Receive and store events via the public ingest API.
+  2. Materialize those events back into a training dataset.
+  3. Spin up a real foundational-model training session.
+
+This is a *real* network test — no mocks. It writes rows to the
+production user_events table under a namespaced event_group_id so the
+data is identifiable and harmless.
+
+Run with:
+    FEATRIX_API_KEY=fx_... pytest featrixevents/tests/test_e2e_collect_and_build.py -s
+
+Skips automatically if FEATRIX_API_KEY is not set.
+"""
+
+import os
+import random
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import pytest
+import requests
+
+from featrixevents import featrix_post_event, FeatrixEventError
+
+
+DEFAULT_BASE_URL = os.getenv("FEATRIX_BASE_URL", "https://sphere-api.featrix.com")
+API_KEY = os.getenv("FEATRIX_API_KEY")
+
+NUM_EVENTS = 500
+INGEST_WORKERS = 16  # well under the 100 events/sec/org rate limit at ~200ms latency
+INGEST_MAX_SECONDS = 120
+BUILD_POLL_INTERVAL = 15
+# Stall-detector: if no status/progress change for this many seconds, fail.
+TRAIN_STALL_TIMEOUT = 900
+# Hard wall-clock cap so a test run can't wedge a CI box forever.
+TRAIN_WALL_TIMEOUT = 3600
+
+# Columns we synthesize. `outcome` is the learnable target.
+EXPECTED_COLUMNS = {
+    "user_tier",
+    "pages_viewed",
+    "time_on_site",
+    "prior_purchases",
+    "source",
+    "outcome",
+}
+
+
+pytestmark = pytest.mark.skipif(
+    not API_KEY,
+    reason="FEATRIX_API_KEY not set — e2e test needs a real ingest key",
+)
+
+
+def _make_synthetic_event(rng: random.Random) -> dict:
+    """One synthetic page-session event with a learnable outcome.
+
+    `outcome` is biased by user_tier + prior_purchases + time_on_site so a
+    foundational model + SP should beat the class prior. We're not asserting
+    on model quality here, just on round-trip + training completion — but
+    we want the data to be non-degenerate so training has something to do.
+    """
+    tier = rng.choices(
+        ["free", "pro", "enterprise"],
+        weights=[0.6, 0.3, 0.1],
+    )[0]
+    source = rng.choice(["organic", "ads", "referral", "email", "social"])
+    pages = max(1, int(rng.gauss(4, 2)))
+    time_on_site = round(max(2.0, rng.gauss(45.0, 25.0)), 1)
+    prior_purchases = rng.choices(
+        [0, 1, 2, 3, 5, 10],
+        weights=[0.45, 0.25, 0.15, 0.08, 0.05, 0.02],
+    )[0]
+
+    # Bias the target so it's learnable.
+    score = 0.0
+    score += {"free": 0.0, "pro": 0.4, "enterprise": 0.7}[tier]
+    score += min(prior_purchases / 5.0, 1.0) * 0.5
+    score += (time_on_site / 120.0) * 0.3
+    score += rng.gauss(0, 0.2)
+    outcome = "converted" if score > 0.55 else "not_converted"
+
+    return {
+        "user_tier": tier,
+        "pages_viewed": pages,
+        "time_on_site": time_on_site,
+        "prior_purchases": prior_purchases,
+        "source": source,
+        "outcome": outcome,
+    }
+
+
+def _ingest_one(event_group_id: str, payload: dict) -> str:
+    """Post one event. Returns event_id. Re-raises on failure."""
+    result = featrix_post_event(
+        auth_key_id=API_KEY,
+        event_group_id=event_group_id,
+        event_payload=payload,
+        base_url=DEFAULT_BASE_URL,
+        timeout=30.0,
+    )
+    assert result.get("success") is True, f"ingest result missing success: {result}"
+    event_id = result.get("event_id")
+    assert event_id, f"ingest result missing event_id: {result}"
+    return event_id
+
+
+def _post_build_model(event_group_id: str, name: str) -> dict:
+    """Call /events/build-model and return the JSON response."""
+    url = f"{DEFAULT_BASE_URL.rstrip('/')}/events/build-model"
+    body = {
+        "event_group_id": event_group_id,
+        "name": name,
+        "max_events": NUM_EVENTS * 2,
+    }
+    resp = requests.post(
+        url,
+        headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"},
+        json=body,
+        timeout=1800,
+    )
+    if resp.status_code not in (200, 201, 202):
+        raise AssertionError(
+            f"build-model failed: HTTP {resp.status_code}: {resp.text[:1000]}"
+        )
+    return resp.json()
+
+
+def _get_session(session_id: str) -> dict:
+    url = f"{DEFAULT_BASE_URL.rstrip('/')}/compute/session/{session_id}"
+    resp = requests.get(
+        url,
+        headers={"X-Api-Key": API_KEY},
+        timeout=60,
+    )
+    if resp.status_code != 200:
+        raise AssertionError(
+            f"session lookup failed: HTTP {resp.status_code}: {resp.text[:500]}"
+        )
+    return resp.json()
+
+
+def _wait_for_training(session_id: str) -> dict:
+    """Poll /compute/session/{id} until status leaves the in-flight set.
+
+    Stall-detector: if neither status nor any job's status changes for
+    TRAIN_STALL_TIMEOUT seconds, fail. Also enforces TRAIN_WALL_TIMEOUT
+    as a hard cap.
+    """
+    in_flight = {"queued", "starting", "running", "training", "in_progress", None, ""}
+    success_states = {"done", "completed", "finished", "ready"}
+    failure_states = {"failed", "error", "aborted", "cancelled"}
+
+    started = time.time()
+    last_change = time.time()
+    last_fingerprint = None
+    last_seen = None
+
+    while True:
+        now = time.time()
+        if now - started > TRAIN_WALL_TIMEOUT:
+            pytest.fail(
+                f"Wall-clock timeout ({TRAIN_WALL_TIMEOUT}s) waiting on session "
+                f"{session_id}. Last seen: {last_seen}"
+            )
+        if now - last_change > TRAIN_STALL_TIMEOUT:
+            pytest.fail(
+                f"Stall timeout: no status change for {TRAIN_STALL_TIMEOUT}s on "
+                f"session {session_id}. Last seen: {last_seen}"
+            )
+
+        try:
+            payload = _get_session(session_id)
+        except AssertionError as e:
+            # 404 right after dispatch can happen if the session is still
+            # being registered. Tolerate a few before failing.
+            if now - started < 60:
+                time.sleep(BUILD_POLL_INTERVAL)
+                continue
+            raise
+
+        session = payload.get("session", payload)
+        status = (session.get("status") or "").lower()
+        jobs = payload.get("jobs") or {}
+        job_summary = tuple(
+            sorted(
+                (jid, (j.get("status") or "").lower())
+                for jid, j in jobs.items()
+            )
+        )
+        fingerprint = (status, job_summary)
+        last_seen = {"status": status, "jobs": dict(jobs)}
+
+        if fingerprint != last_fingerprint:
+            last_change = now
+            last_fingerprint = fingerprint
+            print(
+                f"[{int(now - started)}s] session={session_id[:12]}... "
+                f"status={status!r} jobs={len(jobs)}"
+            )
+
+        if status in failure_states:
+            pytest.fail(
+                f"Training failed: session={session_id}, status={status}, "
+                f"jobs={jobs}"
+            )
+
+        if status in success_states:
+            return payload
+
+        if status not in in_flight:
+            # Unknown status — surface it so we can learn what's happening.
+            print(f"[warn] unknown session status {status!r}; continuing to poll")
+
+        time.sleep(BUILD_POLL_INTERVAL)
+
+
+def test_e2e_collect_events_and_build_model():
+    """Post 500 events, fetch them back via /events/build-model, train an ES.
+
+    Asserts:
+      - All 500 events are accepted by the ingest endpoint.
+      - /events/build-model reports the right row count and column set.
+      - Training reaches a terminal success state without manual help.
+    """
+    assert API_KEY, "FEATRIX_API_KEY is required for this test"
+
+    event_group_id = str(uuid.uuid4())
+    run_label = f"featrixevents-e2e-{event_group_id[:8]}"
+    rng = random.Random(0xFEA72)  # deterministic synthetic data
+
+    print(f"\n==> e2e run: event_group_id={event_group_id} label={run_label}")
+    print(f"==> base url: {DEFAULT_BASE_URL}")
+    print(f"==> posting {NUM_EVENTS} events with {INGEST_WORKERS} workers")
+
+    # --- Phase 1: ingest events in parallel -------------------------------
+    payloads = [_make_synthetic_event(rng) for _ in range(NUM_EVENTS)]
+
+    ingest_start = time.time()
+    event_ids: list = []
+    errors: list = []
+    with ThreadPoolExecutor(max_workers=INGEST_WORKERS) as pool:
+        futures = [
+            pool.submit(_ingest_one, event_group_id, p) for p in payloads
+        ]
+        for fut in as_completed(futures, timeout=INGEST_MAX_SECONDS):
+            try:
+                event_ids.append(fut.result())
+            except (FeatrixEventError, AssertionError, Exception) as e:
+                errors.append(repr(e))
+
+    ingest_elapsed = time.time() - ingest_start
+    print(f"==> ingest done in {ingest_elapsed:.1f}s: "
+          f"{len(event_ids)} ok, {len(errors)} failed")
+    if errors:
+        # Show the first few errors so the failure mode is obvious.
+        for e in errors[:5]:
+            print(f"    err: {e}")
+    assert not errors, f"{len(errors)} ingest calls failed (first: {errors[0] if errors else None})"
+    assert len(event_ids) == NUM_EVENTS, (
+        f"Expected {NUM_EVENTS} event_ids, got {len(event_ids)}"
+    )
+    # All event_ids should be unique UUIDs.
+    assert len(set(event_ids)) == NUM_EVENTS, "Server returned duplicate event_ids"
+
+    # --- Phase 2: build a model from the collected events -----------------
+    print(f"==> calling /events/build-model")
+    build_result = _post_build_model(event_group_id, run_label)
+    print(f"==> build-model returned: "
+          f"session_id={build_result.get('session_id')} "
+          f"num_events={build_result.get('num_events')} "
+          f"queued={build_result.get('queued')} "
+          f"cols={build_result.get('columns')}")
+
+    assert build_result.get("success") is True, build_result
+    assert build_result.get("num_events") == NUM_EVENTS, (
+        f"Expected {NUM_EVENTS} events from build-model, "
+        f"got {build_result.get('num_events')}"
+    )
+    columns = set(build_result.get("columns") or [])
+    missing = EXPECTED_COLUMNS - columns
+    assert not missing, (
+        f"build-model flattened columns are missing {missing}; got {columns}"
+    )
+    session_id = build_result.get("session_id")
+    assert session_id, "build-model returned no session_id"
+
+    # --- Phase 3: wait for the foundational-model training to finish -----
+    print(f"==> waiting for training on session {session_id}")
+    final_payload = _wait_for_training(session_id)
+
+    session = final_payload.get("session", final_payload)
+    final_status = (session.get("status") or "").lower()
+    print(f"==> final session status: {final_status}")
+    print(f"==> session dump: {session}")
+    # _wait_for_training only returns on terminal success.
+    assert final_status in {"done", "completed", "finished", "ready"}, (
+        f"Unexpected terminal status: {final_status}"
+    )