Skip to content

Scope3AI Reference

The Scope3AI class is the central interface for tracking and analyzing the environmental impact of AI model interactions. It provides methods for tracing and logging interactions, as well as calculating key sustainability metrics like energy usage and emissions.

Core features: - Initialization with customizable tracking parameters - Context management for measuring impact across multiple interactions - Synchronous and asynchronous impact calculation modes - Metadata support for session, environment and project tracking

scope3ai.lib.Scope3AI 

Scope3AI()

Scope3AI tracer class

This class is a singleton that provides a context manager for tracing inference metadata and submitting impact requests to the Scope3 AI API.

Methods:

  • asubmit_impact –

    Async version of Scope3AI::submit_impact.

  • get_instance –

    Return the instance of the Scope3AI singleton.

  • init –

    Initialize the Scope3AI SDK with the provided configuration settings.

  • submit_impact –

    Submit an impact request to the Scope3 AI API.

Attributes:

current_tracer property 

current_tracer

Return the current tracer.

The current tracer is the last tracer in the current execution context (tracer stack). If no tracers are currently active, it returns None.

Returns:

  • Tracer –

    The current tracer if available, otherwise None.

root_tracer property 

root_tracer

Return the root tracer.

The root tracer is the first tracer in the current execution context (tracer stack). If no tracers are currently active, it returns None.

Returns:

  • Tracer –

    The root tracer if available, otherwise None.

asubmit_impact async 

asubmit_impact(impact_row: ImpactRow) -> Scope3AIContext

Async version of Scope3AI::submit_impact.

get_instance classmethod 

get_instance() -> Scope3AI

Return the instance of the Scope3AI singleton.

This method provides access to the default global state of the Scope3AI library. The returned instance can be used to trace inference metadata and submit impact requests to the Scope3 AI API from anywhere in the application.

Returns:

  • Scope3AI ( Scope3AI ) –

    The singleton instance of the Scope3AI class.

init classmethod 

init(api_key: Optional[str] = None, api_url: Optional[str] = None, sync_mode: bool = False, enable_debug_logging: bool = False, provider_clients: Optional[List[str]] = None, environment: Optional[str] = None, client_id: Optional[str] = None, project_id: Optional[str] = None, application_id: Optional[str] = None) -> Scope3AI

Initialize the Scope3AI SDK with the provided configuration settings.

Parameters:

  • api_key

    (str, default: None ) –

    The Scope3AI API key. Can be set via SCOPE3AI_API_KEY environment variable. Required for authentication.

  • api_url

    (str, default: None ) –

    The base URL for the Scope3AI API. Can be set via SCOPE3AI_API_URL environment variable. Defaults to standard API URL.

  • sync_mode

    (bool, default: False ) –

    If True, the SDK will operate synchronously. Can be set via SCOPE3AI_SYNC_MODE environment variable. Defaults to False.

  • enable_debug_logging

    (bool, default: False ) –

    Enable debug level logging. Can be set via SCOPE3AI_DEBUG_LOGGING environment variable. Defaults to False.

  • clients

    (List[str]) –

    List of provider clients to instrument. If None, all available provider clients will be instrumented.

  • environment

    (str, default: None ) –

    The environment name (e.g. "production", "staging"). Can be set via SCOPE3AI_ENVIRONMENT environment variable.

  • client_id

    (str, default: None ) –

    Client identifier for grouping traces. Can be set via SCOPE3AI_CLIENT_ID environment variable.

  • project_id

    (str, default: None ) –

    Project identifier for grouping traces. Can be set via SCOPE3AI_PROJECT_ID environment variable.

  • application_id

    (str, default: None ) –

    Application identifier. Can be set via SCOPE3AI_APPLICATION_ID environment variable. Defaults to "default".

Returns:

  • Scope3AI ( Scope3AI ) –

    The initialized Scope3AI instance.

Raises:

  • Scope3AIError –

    If the instance is already initialized or if required settings are missing.

submit_impact 

submit_impact(impact_row: ImpactRow) -> Scope3AIContext

Submit an impact request to the Scope3 AI API.

This function sends an impact request represented by the impact_row to the Scope3 AI API and optionally returns the response.

Parameters:

  • impact_row

    (ImpactRow) –

    The impact request data that needs to be submitted to the Scope3 AI API.

Returns: