arcade-core 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

arcade_core/catalog.py

@@ -217,7 +217,7 @@ class ToolCatalog(BaseModel):
             toolkit_name = toolkit_or_name
 
         if not toolkit_name:
-            raise ValueError("A toolkit name or toolkit must be provided.")
+            raise ValueError("A server name or server must be provided.")
 
         definition = ToolCatalog.create_tool_definition(
             tool_func,
@@ -230,7 +230,7 @@ class ToolCatalog(BaseModel):
 
         if fully_qualified_name in self._tools:
             raise ToolkitLoadError(
-                f"Tool '{definition.name}' in toolkit '{toolkit_name}' already exists in the catalog."
+                f"Tool '{definition.name}' in server '{toolkit_name}' already exists in the catalog."
             )
 
         if str(fully_qualified_name).lower() in self._disabled_tools:
@@ -238,7 +238,7 @@ class ToolCatalog(BaseModel):
             return
 
         if str(toolkit_name).lower() in self._disabled_toolkits:
-            logger.info(f"Toolkit '{toolkit_name!s}' is disabled and will not be cataloged.")
+            logger.info(f"Server '{toolkit_name!s}' is disabled and will not be cataloged.")
             return
 
         self._tools[fully_qualified_name] = MaterializedTool(
@@ -267,7 +267,7 @@ class ToolCatalog(BaseModel):
         """
 
         if str(toolkit).lower() in self._disabled_toolkits:
-            logger.info(f"Toolkit '{toolkit.name!s}' is disabled and will not be cataloged.")
+            logger.info(f"Server '{toolkit.name!s}' is disabled and will not be cataloged.")
             return
 
         for module_name, tool_names in toolkit.tools.items():

arcade_core/constants.py

@@ -0,0 +1,6 @@
+import os
+
+# The path to the directory containing the Arcade configuration files. Typically ~/.arcade
+ARCADE_CONFIG_PATH = os.path.join(os.path.expanduser(os.getenv("ARCADE_WORK_DIR", "~")), ".arcade")
+# The path to the file containing the user's Arcade-related credentials (e.g., ARCADE_API_KEY).
+CREDENTIALS_FILE_PATH = os.path.join(ARCADE_CONFIG_PATH, "credentials.yaml")

arcade_core/usage/__init__.py

@@ -0,0 +1,5 @@
+from arcade_core.usage.identity import UsageIdentity
+from arcade_core.usage.usage_service import UsageService
+from arcade_core.usage.utils import is_tracking_enabled
+
+__all__ = ["UsageIdentity", "UsageService", "is_tracking_enabled"]

arcade_core/usage/__main__.py

@@ -0,0 +1,63 @@
+"""Entry point for detached usage tracking subprocess.
+
+This module is invoked as `python -m arcade_core.usage` and expects
+event data to be passed via the ARCADE_USAGE_EVENT_DATA environment variable.
+"""
+
+import json
+import os
+import threading
+
+from posthog import Posthog
+
+from arcade_core.usage.constants import (
+    ARCADE_USAGE_EVENT_DATA,
+    MAX_RETRIES_POSTHOG,
+    PROP_PROCESS_PERSON_PROFILE,
+    TIMEOUT_POSTHOG_CAPTURE,
+    TIMEOUT_SUBPROCESS_EXIT,
+)
+
+
+def _timeout_exit() -> None:
+    """Force exit after timeout"""
+    os._exit(1)
+
+
+def main() -> None:
+    """Capture a PostHog event from environment variable."""
+
+    timeout_timer = threading.Timer(TIMEOUT_SUBPROCESS_EXIT, _timeout_exit)
+    timeout_timer.daemon = True
+    timeout_timer.start()
+
+    try:
+        event_data = json.loads(os.environ[ARCADE_USAGE_EVENT_DATA])
+
+        if event_data.get("is_anon", False):
+            event_data["properties"][PROP_PROCESS_PERSON_PROFILE] = False
+
+        posthog = Posthog(
+            project_api_key=event_data["api_key"],
+            host=event_data["host"],
+            timeout=TIMEOUT_POSTHOG_CAPTURE,
+            max_retries=MAX_RETRIES_POSTHOG,
+        )
+
+        posthog.capture(
+            event_data["event_name"],
+            distinct_id=event_data["distinct_id"],
+            properties=event_data["properties"],
+        )
+
+        posthog.flush()
+
+        timeout_timer.cancel()
+    except Exception:
+        # Silent failure. We don't want to disrupt anything
+        timeout_timer.cancel()
+        pass
+
+
+if __name__ == "__main__":
+    main()

arcade_core/usage/constants.py

@@ -0,0 +1,34 @@
+# Base (common) Property Names
+PROP_RUNTIME_LANGUAGE = "runtime_language"
+PROP_RUNTIME_VERSION = "runtime_version"
+PROP_OS_TYPE = "os_type"
+PROP_OS_RELEASE = "os_release"
+PROP_DURATION_MS = "duration_ms"
+PROP_ERROR_MESSAGE = "error_message"
+PROP_DEVICE_MONOTONIC_START = "device_start_timestamp"
+PROP_DEVICE_MONOTONIC_END = "device_end_timestamp"
+PROP_DEVICE_TIMESTAMP = "device_timestamp"
+# Only used for anonymous usage
+PROP_PROCESS_PERSON_PROFILE = "$process_person_profile"
+
+# Identity Keys
+KEY_ANON_ID = "anon_id"
+KEY_LINKED_PRINCIPAL_ID = "linked_principal_id"
+
+# File Names
+USAGE_FILE_NAME = "usage.json"
+
+# Environment Variables
+# how props are passed to the usage tracking subprocess
+ARCADE_USAGE_EVENT_DATA = "ARCADE_USAGE_EVENT_DATA"
+# whether usage tracking is enabled. 1 is enabled, 0 is disabled.
+ARCADE_USAGE_TRACKING = "ARCADE_USAGE_TRACKING"
+
+# Timeouts and Limits (in seconds)
+TIMEOUT_POSTHOG_ALIAS = 2
+TIMEOUT_POSTHOG_CAPTURE = 5
+TIMEOUT_ARCADE_API = 2.0
+TIMEOUT_SUBPROCESS_EXIT = 10.0
+
+# Retry Configuration
+MAX_RETRIES_POSTHOG = 1

arcade_core/usage/identity.py

@@ -0,0 +1,208 @@
+"""
+Identity management for PostHog analytics tracking.
+
+Handles anonymous/authenticated identity tracking with PostHog aliasing,
+supporting pre-login anonymous tracking, post-login identity stitching,
+and logout identity rotation.
+"""
+
+import fcntl
+import json
+import os
+import tempfile
+import uuid
+from typing import Any
+
+import httpx
+import yaml
+
+from arcade_core.constants import ARCADE_CONFIG_PATH, CREDENTIALS_FILE_PATH
+from arcade_core.usage.constants import (
+    KEY_ANON_ID,
+    KEY_LINKED_PRINCIPAL_ID,
+    TIMEOUT_ARCADE_API,
+    USAGE_FILE_NAME,
+)
+
+
+class UsageIdentity:
+    """Manages user identity for PostHog analytics tracking."""
+
+    def __init__(self) -> None:
+        self.usage_file_path = os.path.join(ARCADE_CONFIG_PATH, USAGE_FILE_NAME)
+        self._data: dict[str, Any] | None = None
+
+    def load_or_create(self) -> dict[str, Any]:
+        """Load or create usage.json file with atomic writes and file locking.
+
+        Returns:
+            dict: The usage data containing anon_id and optionally linked_email
+        """
+        if self._data is not None:
+            return self._data
+
+        os.makedirs(ARCADE_CONFIG_PATH, exist_ok=True)
+
+        if os.path.exists(self.usage_file_path):
+            try:
+                with open(self.usage_file_path) as f:
+                    # lock file
+                    if os.name != "nt":  # Unix-like systems
+                        fcntl.flock(f.fileno(), fcntl.LOCK_SH)
+                    try:
+                        data = json.load(f)
+                        if isinstance(data, dict) and KEY_ANON_ID in data:
+                            self._data = data
+                            return self._data
+                    finally:
+                        # unlock file
+                        if os.name != "nt":
+                            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+            except Exception:  # noqa: S110
+                pass
+
+        new_data = {KEY_ANON_ID: str(uuid.uuid4()), KEY_LINKED_PRINCIPAL_ID: None}
+
+        self._write_atomic(new_data)
+        self._data = new_data
+        return self._data
+
+    def _write_atomic(self, data: dict[str, Any]) -> None:
+        """Write data atomically to usage.json file
+
+        Args:
+            data: The data to write to the usage file
+        """
+        # Create temp file in same directory for atomic rename
+        temp_fd, temp_path = tempfile.mkstemp(
+            dir=ARCADE_CONFIG_PATH, prefix=".usage_", suffix=".tmp"
+        )
+
+        try:
+            with os.fdopen(temp_fd, "w") as f:
+                # lock file
+                if os.name != "nt":  # Unix-like systems
+                    fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+                try:
+                    json.dump(data, f, indent=2)
+                    f.flush()
+                    os.fsync(f.fileno())  # ensure data is written to disk
+                finally:
+                    if os.name != "nt":
+                        fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+            os.rename(temp_path, self.usage_file_path)
+        except Exception:
+            # clean up
+            import contextlib
+
+            with contextlib.suppress(OSError):
+                os.unlink(temp_path)
+            raise
+
+    def get_distinct_id(self) -> str:
+        """Get distinct_id based on authentication state.
+
+        We use principal_id for authenticated users and anon_id for anonymous users.
+
+        Returns:
+            str: Principal ID if authenticated, otherwise anon_id
+        """
+        data = self.load_or_create()
+
+        # Check if we have a persisted principal_id first
+        linked_principal_id = data.get(KEY_LINKED_PRINCIPAL_ID)
+        if linked_principal_id:
+            return str(linked_principal_id)
+
+        # Try to fetch principal_id from API if not persisted
+        principal_id = self.get_principal_id()
+        if principal_id:
+            return principal_id
+
+        # Fall back to anon_id if not authenticated
+        return str(data[KEY_ANON_ID])
+
+    def get_principal_id(self) -> str | None:
+        """Fetch principal_id from Arcade Cloud API.
+
+        Returns:
+            str | None: Principal ID if authenticated and API call succeeds, None otherwise
+        """
+        if not os.path.exists(CREDENTIALS_FILE_PATH):
+            return None
+
+        try:
+            with open(CREDENTIALS_FILE_PATH) as f:
+                config = yaml.safe_load(f)
+
+            cloud_config = config.get("cloud", {})
+            api_key = cloud_config.get("api", {}).get("key")
+
+            if not api_key:
+                return None
+
+            response = httpx.get(
+                "https://cloud.arcade.dev/api/v1/auth/validate",
+                headers={"accept": "application/json", "Authorization": f"Bearer {api_key}"},
+                timeout=TIMEOUT_ARCADE_API,
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                principal_id = data.get("data", {}).get("principal_id")
+                return str(principal_id) if principal_id else None
+
+        except Exception:  # noqa: S110
+            # Silent failure - don't disrupt CLI
+            pass
+
+        return None
+
+    def should_alias(self) -> bool:
+        """Check if PostHog alias is needed.
+
+        Alias is needed when the user is authenticated,
+        but the retrieved principal_id doesn't match the persisted linked_principal_id
+
+        Returns:
+            bool: True if user is authenticated but not yet aliased
+        """
+        data = self.load_or_create()
+        principal_id = self.get_principal_id()
+
+        return principal_id is not None and principal_id != data.get(KEY_LINKED_PRINCIPAL_ID)
+
+    def reset_to_anonymous(self) -> None:
+        """Generate new anonymous ID and clear linked principal_id.
+
+        Used after logout to prevent cross-contamination between multiple
+        accounts on the same machine
+        """
+        # Create fresh data with only anon_id
+        new_data = {KEY_ANON_ID: str(uuid.uuid4()), KEY_LINKED_PRINCIPAL_ID: None}
+
+        self._write_atomic(new_data)
+        self._data = new_data
+
+    def set_linked_principal_id(self, principal_id: str) -> None:
+        """Update linked_principal_id in usage.json.
+
+        Args:
+            principal_id: The principal_id to link to the current anon_id
+        """
+        data = self.load_or_create()
+        data[KEY_LINKED_PRINCIPAL_ID] = principal_id
+
+        self._write_atomic(data)
+        self._data = data
+
+    @property
+    def anon_id(self) -> str:
+        """Get the current anonymous ID.
+
+        Returns:
+            str: The anonymous ID
+        """
+        data = self.load_or_create()
+        return str(data[KEY_ANON_ID])

arcade_core/usage/usage_service.py

@@ -0,0 +1,104 @@
+import json
+import os
+import subprocess
+import sys
+
+from arcade_core.usage.constants import (
+    ARCADE_USAGE_EVENT_DATA,
+    MAX_RETRIES_POSTHOG,
+    TIMEOUT_POSTHOG_ALIAS,
+)
+from arcade_core.usage.utils import is_tracking_enabled
+
+
+class UsageService:
+    def __init__(self) -> None:
+        self.api_key = "phc_hIqUQyJpf2TP4COePO5jEpkGeUXipa7KqTEyDeRsTmB"
+        self.host = "https://us.i.posthog.com"
+
+    def alias(self, previous_id: str, distinct_id: str) -> None:
+        """Perform PostHog alias synchronously (blocking).
+
+        Must be called BEFORE the first event with the new distinct_id.
+        This is done synchronously to guarantee ordering.
+
+        Args:
+            previous_id: The previous distinct_id (usually anon_id)
+            distinct_id: The new distinct_id (usually email)
+        """
+        if not is_tracking_enabled():
+            return
+
+        try:
+            from posthog import Posthog
+
+            posthog = Posthog(
+                project_api_key=self.api_key,
+                host=self.host,
+                timeout=TIMEOUT_POSTHOG_ALIAS,
+                max_retries=MAX_RETRIES_POSTHOG,
+            )
+
+            posthog.alias(previous_id=previous_id, distinct_id=distinct_id)
+            posthog.flush()
+        except Exception:  # noqa: S110
+            # Silent failure - don't disrupt CLI
+            pass
+
+    def capture(
+        self, event_name: str, distinct_id: str, properties: dict, is_anon: bool = False
+    ) -> None:
+        """Capture event in a detached subprocess that is non-blocking.
+
+        Spawns a completely independent subprocess that continues running
+        even after the parent CLI process exits. Works cross-platform.
+
+        Args:
+            event_name: Name of the event to capture
+            distinct_id: The distinct_id for the user
+            properties: Event properties
+            is_anon: Whether this is an anonymous user (sets $process_person_profile to false)
+        """
+        if not is_tracking_enabled():
+            return
+
+        event_data = json.dumps({
+            "event_name": event_name,
+            "properties": properties,
+            "distinct_id": distinct_id,
+            "api_key": self.api_key,
+            "host": self.host,
+            "is_anon": is_anon,
+        })
+
+        cmd = [sys.executable, "-m", "arcade_core.usage"]
+
+        # Pass data via environment variable (works on all platforms)
+        env = os.environ.copy()
+        env[ARCADE_USAGE_EVENT_DATA] = event_data
+
+        if sys.platform == "win32":
+            # Windows: Use DETACHED_PROCESS to fully detach from parent console
+            DETACHED_PROCESS = 0x00000008
+            CREATE_NEW_PROCESS_GROUP = 0x00000200
+
+            subprocess.Popen(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                creationflags=DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP,
+                close_fds=True,
+                env=env,
+            )
+        else:
+            # Unix: Use start_new_session to detach from terminal
+            subprocess.Popen(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+                close_fds=True,
+                env=env,
+            )

arcade_core/usage/utils.py

@@ -0,0 +1,13 @@
+import os
+
+from arcade_core.usage.constants import ARCADE_USAGE_TRACKING
+
+
+def is_tracking_enabled() -> bool:
+    """Check if usage tracking is enabled via environment variable.
+
+    Returns:
+        bool: True if tracking is enabled (default), False if explicitly disabled.
+    """
+    value = os.environ.get(ARCADE_USAGE_TRACKING, "1")
+    return value.lower() not in ("false", "0", "no", "off")

{arcade_core-3.0.0.dist-info → arcade_core-3.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcade-core
-Version: 3.0.0
+Version: 3.1.0
 Summary: Arcade Core - Core library for Arcade platform
 Author-email: Arcade <dev@arcade.dev>
 License: MIT

{arcade_core-3.0.0.dist-info → arcade_core-3.1.0.dist-info}/RECORD

@@ -1,9 +1,10 @@
 arcade_core/__init__.py,sha256=1heu3AROAjpistehPzY2H-2nkj_IjQEh-vVlVOCRF1E,88
 arcade_core/annotations.py,sha256=Nst6aejLWXlpTu7GwzWETu1gQCG1XVAUR_qcFbNvyRc,198
 arcade_core/auth.py,sha256=On9sJPOxvHjKBxgKC1yqp7oijF6KYBsG6fG8KUw-9OY,5882
-arcade_core/catalog.py,sha256=QD7PLaKBW8eBaelj3_ax7s_pgKNnOYWEIsMLtqmbtjI,41819
+arcade_core/catalog.py,sha256=yuGYai8b-ruN4Ot5p8DyRMOSoxy-ciVgL56hQMJSZrk,41814
 arcade_core/config.py,sha256=e98XQAkYySGW9T_yrJg54BB8Wuq06GPVHp7xqe2d1vU,572
 arcade_core/config_model.py,sha256=78BR6Ch9BDuG4ddWGfpuEKqWcb1fyOF6kxiF4qLFogM,4481
+arcade_core/constants.py,sha256=wakdklI7TyJ0agq9n-Cmb2lbVa95D0oUaMGm30eiv9Y,375
 arcade_core/context.py,sha256=J2MgbVznhJC2qarHq3dTL72W4NGYOM1pjXdI_YwgkA4,3316
 arcade_core/discovery.py,sha256=PluKGhNtJ7RYjJuPDMB8LCNinQLKzlqoAtc3dwKb6IA,8397
 arcade_core/errors.py,sha256=fsi7m6TQQSsdSNHl4rBoSN_YH3ZV910gjvBFqB207f4,13326
@@ -16,6 +17,12 @@ arcade_core/toolkit.py,sha256=UcZ151pC8zfIFzVMYxaq31H7M0f-2qprU0PkVAzfRtI,13815
 arcade_core/utils.py,sha256=RxVIzURTtZ4nAWYB3FYGngqMMPmBBxf330Ez9eEoXaw,3109
 arcade_core/version.py,sha256=CpXi3jGlx23RvRyU7iytOMZrnspdWw4yofS8lpP1AJU,18
 arcade_core/converters/openai.py,sha256=4efdgTkvdwT44VGStBhdUmzCnoP5dysceIqPVVPG-vk,7408
-arcade_core-3.0.0.dist-info/METADATA,sha256=fmmbBziVqGMDsTf5jqBgfc6SU3CjUVknfIRr4S0simw,2383
-arcade_core-3.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arcade_core-3.0.0.dist-info/RECORD,,
+arcade_core/usage/__init__.py,sha256=SUR5mqF-bjdbl-P-OOHN6OFAjXZu4agXyPhr7xdVXCw,234
+arcade_core/usage/__main__.py,sha256=rSJkE1G9hlV3HRRA6EJE5Lmy3wKyan7rAxBXHX9A1cI,1577
+arcade_core/usage/constants.py,sha256=1FQIhkFFMZUhU-H4A7GvMb7KQ3qLFrNAZb2-LEvSF3k,1052
+arcade_core/usage/identity.py,sha256=2dP1iusI9pE_GrPlz3VXEdz51R5JlNo9_-OXbe6vn7I,6716
+arcade_core/usage/usage_service.py,sha256=xzWWSEktm58liiNYugBHRactSru8V5foriHcsoH0j1A,3407
+arcade_core/usage/utils.py,sha256=FqBOmlhwT68cbnpI5Vx9ZW6vLRYPVg4FJ0GaMEp8qEM,398
+arcade_core-3.1.0.dist-info/METADATA,sha256=KcL3pN8hxkmsFCcTcqqNMrQ_kDGI1EcrQ3Rr6Hk35Xw,2383
+arcade_core-3.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_core-3.1.0.dist-info/RECORD,,