{"id":4922,"library":"cua-core","title":"Cua Core Library","description":"cua-core is a Python library providing core utilities and telemetry functionality for the Cua ecosystem. It includes shared components for configuration, logging, versioning, and OpenTelemetry integration. Currently at version 0.1.19, it is designed primarily as a dependency for other Cua-related libraries and is explicitly not intended for direct end-user applications. Its release cadence is likely tied to the development cycles of other Cua projects.","status":"active","version":"0.1.19","language":"en","source_language":"en","source_url":"https://github.com/cua-bot/cua-core","tags":["utility","telemetry","core","gcp"],"install":[{"cmd":"pip install cua-core","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Configuration management for loading settings from various sources.","package":"pydantic-settings"},{"reason":"Integration with Google Cloud Logging services for structured logs.","package":"google-cloud-logging"},{"reason":"Integration with Google Cloud Monitoring for metrics and monitoring.","package":"google-cloud-monitoring"},{"reason":"Core OpenTelemetry SDK for distributed tracing and metrics.","package":"opentelemetry-sdk"},{"reason":"OpenTelemetry exporter for sending telemetry data to Google Cloud.","package":"opentelemetry-exporter-google-cloud"},{"reason":"OpenTelemetry instrumentation for Python's logging module.","package":"opentelemetry-instrumentation-logging"},{"reason":"OpenTelemetry instrumentation for the 'requests' HTTP library.","package":"opentelemetry-instrumentation-requests"},{"reason":"OpenTelemetry API for creating and managing traces and metrics.","package":"opentelemetry-api"},{"reason":"OpenTelemetry semantic conventions for standardized attribute names.","package":"opentelemetry-semantic-conventions"},{"reason":"OpenTelemetry instrumentation for asyncio applications.","package":"opentelemetry-instrumentation-asyncio"},{"reason":"HTTP client library, instrumented by OpenTelemetry.","package":"requests"},{"reason":"Asynchronous HTTP client library, likely used internally.","package":"httpx"}],"imports":[{"note":"A common utility function to retrieve the library's version.","symbol":"get_library_version","correct":"from cua_core.utils import get_library_version"},{"note":"The main class for managing OpenTelemetry client interactions, typically initialized by higher-level Cua libraries.","symbol":"TelemetryClient","correct":"from cua_core.telemetry import TelemetryClient"}],"quickstart":{"code":"from cua_core.utils import get_library_version\n\n# Retrieve the version of the cua-core library itself.\n# This function provides a simple, direct interaction with the library's utilities.\nlibrary_version = get_library_version()\nprint(f\"Cua Core Library Version: {library_version}\")\n\n# Further utilities exist in cua_core.utils and cua_core.telemetry,\n# but their direct usage is generally discouraged as cua-core is primarily a dependency.\n# For example, to instantiate a TelemetryClient:\n# from cua_core.telemetry import TelemetryClient\n# tele_client = TelemetryClient(project_id=os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id'), service_name=\"my-app\")\n# However, this requires a valid GCP project ID and is usually handled by higher-level Cua libraries.","lang":"python","description":"Demonstrates a basic interaction with `cua-core` by retrieving its version, highlighting its utility-centric nature. It also provides a commented example for `TelemetryClient` with a reminder about its dependency role and GCP requirements."},"warnings":[{"fix":"If directly depending on `cua-core`, pin exact versions for stability (e.g., `cua-core==0.1.19`). Prefer relying on higher-level Cua libraries for stable interfaces, as they manage `cua-core` internally.","message":"As a `0.x.x` version library, `cua-core` may introduce breaking changes without prior deprecation warnings between minor or patch releases. Its API is not considered stable for external use.","severity":"breaking","affected_versions":"All 0.x.x versions"},{"fix":"Prefer using higher-level Cua libraries that encapsulate `cua-core`'s functionality and provide a stable, user-facing API. Only use `cua-core` directly if building another library within the Cua ecosystem or if fully understanding its internal mechanics.","message":"`cua-core` is intended as an internal dependency for the Cua ecosystem and is explicitly \"not intended for direct use\" by end-user applications. Its public API may not be fully documented or user-friendly, and its design prioritizes internal consistency over external usability.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your environment has appropriate GCP credentials (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account key file) and necessary IAM permissions for Google Cloud Logging and Monitoring.","message":"Many core functionalities, especially telemetry and logging, are tightly integrated with Google Cloud Platform (GCP) services (e.g., Google Cloud Logging, Monitoring, OpenTelemetry Exporter for GCP). Direct use of these features requires a properly configured GCP environment.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}