{"id":10277,"library":"tabpfn-common-utils","title":"TabPFN Common Utilities","description":"TabPFN Common Utilities (tabpfn-common-utils) provides shared helper functions, primarily focusing on telemetry and logging, used across various TabPFN codebases. It is currently at version 0.2.19 and maintains a frequent release cadence, often with minor updates and bug fixes.","status":"active","version":"0.2.19","language":"en","source_language":"en","source_url":"https://github.com/priorlabs/tabpfn_common_utils","tags":["utility","telemetry","logging","tabpfn"],"install":[{"cmd":"pip install tabpfn-common-utils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for telemetry functionality to send events.","package":"posthog","optional":false}],"imports":[{"symbol":"TelemetryClient","correct":"from tabpfn_common_utils.telemetry.client import TelemetryClient"},{"symbol":"TabPFNLogger","correct":"from tabpfn_common_utils.telemetry.logger import TabPFNLogger"},{"symbol":"TelemetryEvent","correct":"from tabpfn_common_utils.telemetry.events import TelemetryEvent"}],"quickstart":{"code":"import os\nfrom tabpfn_common_utils.telemetry.client import TelemetryClient\nfrom tabpfn_common_utils.telemetry.logger import TabPFNLogger\n\n# Initialize TelemetryClient (API key can be passed directly or via POSTHOG_API_KEY env var)\n# For local testing, set POSTHOG_API_KEY in your environment, or pass a dummy string.\n# Data won't be sent if API key is invalid or not set in a production context.\ntelemetry_client = TelemetryClient(\n    api_key=os.environ.get('POSTHOG_API_KEY', 'phc_dummy_key_for_dev'),\n    project_group=\"quickstart\",\n    project_name=\"example\"\n)\n\n# Initialize TabPFNLogger\nlogger = TabPFNLogger(telemetry_client=telemetry_client)\n\n# Log a message\nlogger.info(\"Quickstart example executed.\")\n\n# Capture a custom event\ntelemetry_client.capture(\n    event_name=\"quickstart_event\",\n    properties={\n        \"data_point_count\": 100,\n        \"model_type\": \"test_model\"\n    }\n)\n\nprint(\"Telemetry client and logger initialized and events captured (if API key is valid).\")","lang":"python","description":"This quickstart demonstrates how to initialize the `TelemetryClient` and `TabPFNLogger`. The `TelemetryClient` is configured to use an environment variable for the PostHog API key, falling back to a dummy key for development. It then logs an informational message and captures a custom telemetry event."},"warnings":[{"fix":"Consult the source code or documentation for specific environment variables or constructor arguments to disable or configure telemetry. For instance, setting `POSTHOG_API_KEY` to an empty string might effectively disable it, or checking for an explicit 'disable' flag in future versions.","message":"Telemetry data is sent to PostHog by default. If you need to disable or control this for privacy or compliance, ensure you configure the `TelemetryClient` appropriately or set environment variables like `TABPFN_DISABLE_TELEMETRY`.","severity":"gotcha","affected_versions":"All versions with telemetry."},{"fix":"Ensure `POSTHOG_API_KEY` is set correctly in your environment, or pass the `api_key` explicitly when initializing `TelemetryClient`. Verify network access if events are still not reaching PostHog.","message":"The `TelemetryClient` relies on the `POSTHOG_API_KEY` environment variable or direct `api_key` argument for proper functioning. If not provided or incorrect, telemetry events may not be sent, or the client might fail silently.","severity":"gotcha","affected_versions":"All versions with `TelemetryClient`."},{"fix":"Upgrade to version `0.2.14` or newer to ensure correct timezone handling for telemetry events. If on older versions, ensure all timestamps are explicitly timezone-aware before passing them to the utility functions.","message":"Older versions (prior to v0.2.14) had an issue with timezone awareness for timestamps. This could lead to incorrect timestamps in telemetry data if not handled carefully.","severity":"breaking","affected_versions":"< 0.2.14"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the required dependency: `pip install posthog` or `pip install tabpfn-common-utils` which should pull it in.","cause":"The 'posthog' library, a core dependency for telemetry, is not installed.","error":"ModuleNotFoundError: No module named 'posthog'"},{"fix":"Verify that the `POSTHOG_API_KEY` environment variable is correctly set and is a valid key for your PostHog instance. Alternatively, ensure you pass a valid `api_key` argument during `TelemetryClient` initialization. Check network connectivity and PostHog server status.","cause":"The `TelemetryClient` might not be initialized with a valid `POSTHOG_API_KEY`, or there could be network issues preventing data transmission.","error":"Telemetry events are not appearing in PostHog dashboard."},{"fix":"Double-check the `TelemetryClient` initialization. Ensure no exceptions occurred during its creation and that it's being used after a successful instantiation. If using `TabPFNLogger`, ensure it's provided with a valid `telemetry_client` instance.","cause":"This usually indicates that the `TelemetryClient` object was not successfully instantiated, or was perhaps inadvertently assigned `None`.","error":"AttributeError: 'NoneType' object has no attribute 'capture'"}]}