Scope3AI Python SDK

Track the environmental impact of your use of AI !

The Scope3AI Python SDK provides an easy-to-use interface for interacting with Scope3AI's API.
It allow you to record, trace, and analyze the impact of interactions with a focus on sustainability metrics.

🚀 Installation

The package scope3ai SDK is published on pypi. You can install it using pip:

pip install scope3ai

We personally use uv:

uv add scope3ai

📚 Library and SDK support Matrix

Library/SDK	Text generation	TTS	STT	Image Generation	Translation	Multimodal input	Multimodal output
Anthropic	✅
Cohere	✅
OpenAI	✅	✅	✅	✅	✅	Images/Audio	Text/Audio
Huggingface	✅	✅	✅	✅	✅
LiteLLM	✅	✅	✅	✅		Images/Audio	Text/Audio
MistralAi	✅					Images
GoogleGenAi	✅

Roadmap:

• Google
• Langchain

✨ Getting Started

Initializing the SDK

The SDK can be initialized with the following parameters, from environemnt variable or when calling ScopeAI.init(...):

Attribute	Environment Variable	Description	Can be customized per tracer
api_key	SCOPE3AI_API_KEY	Your Scope3AI API key. Default: None	No
api_url	SCOPE3AI_API_URL	The API endpoint URL. Default: https://aiapi.scope3.com	No
enable_debug_logging	SCOPE3AI_DEBUG_LOGGING	Enable debug logging. Default: False	No
sync_mode	SCOPE3AI_SYNC_MODE	Enable synchronous mode. Default: False	No
environment	SCOPE3AI_ENVIRONMENT	The user-defined environment name, such as "production" or "staging". Default: None	No
application_id	SCOPE3AI_APPLICATION_ID	The user-defined application identifier. Default: default	✅ Yes
client_id	SCOPE3AI_CLIENT_ID	The user-defined client identifier. Default: None	✅ Yes
project_id	SCOPE3AI_PROJECT_ID	The user-defined project identifier. Default: None	✅ Yes
session_id	-	The user-defined session identifier, used to track user session. Default None. Available only at tracer() level.	✅ Yes

Here is an example of how to initialize the SDK:

from scope3ai import Scope3AI

scope3 = Scope3AI.init(
    api_key="YOUR_API_KEY",
    environment="staging",
    application_id="my-app",
    project_id="my-webinar-2024"
)

You could also use environment variables to initialize the SDK:

1. Create a .env file with the following content:

SCOPE3AI_API_KEY=YOUR_API_KEY
SCOPE3AI_ENVIRONMENT=staging
SCOPE3AI_APPLICATION_ID=my-app
SCOPE3AI_PROJECT_ID=my-webinar-2024

2. Use dotenv to load the environment variables:

from dotenv import load_dotenv
from scope3ai import Scope3AI

load_dotenv()
scope3 = Scope3AI.init()

Usage Examples

1. Using Context Management for Tracing

Within the context of a trace, all interactions are recorded and you can query the impact of the trace. As the interactions are captured and send to Scope3 AI for analysis, the impact is calculated and returned asynchronously. This will automatically wait for all traces to be processed and return the impact.

with scope3.trace() as tracer:
    # Perform your interactions
    interact()
    interact()

    # Print the impact of the recorded trace
    impact = tracer.impact()
    print(f"Total Energy Wh: {impact.total_energy_wh}")
    print(f"Total GCO2e: {impact.total_gco2e}")
    print(f"Total MLH2O: {impact.total_mlh2o}")

2. Configure per-tracer metadata

Some global metadata can be overridden per-tracer. This is useful when you want to mark a specific tracer with a different client_id or project_id.

with scope3.trace(client_id="my-client", project_id="my-project") as tracer:
    ...

You can track session with the session_id parameter of the tracer. This is only for categorizing the traces in the dashboard. but works at tracer level, not in global level like client_id or project_id or others.

with scope3.trace(session_id="my-session") as tracer:
    ...

2. Single interaction

For a single interaction, the response is augmented with a scope3ai attribute that contains the request and impact data. The impact data is calculated asynchronously so we need to wait for the impact to be calculated and for the attribute to be ready.

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello world"}],
    stream=False,
)

response.scope3ai.wait_impact()
impact = response.scope3ai.impact
print(f"Total Energy Wh: {impact.total_energy_wh}")
print(f"Total GCO2e: {impact.total_gco2e}")
print(f"Total MLH2O: {impact.total_mlh2o}")

3. Enabling Synchronous Mode for Immediate Impact Response

In synchronous mode, the SDK will include the impact data directly in the interaction response. This is useful when you want to get the impact data immediately after the interaction without waiting.

scope3.sync_mode = True

response = interact()
impact = response.scope3ai.impact
print(f"Total Energy Wh: {impact.total_energy_wh}")
print(f"Total GCO2e: {impact.total_gco2e}")
print(f"Total MLH2O: {impact.total_mlh2o}")

🛠️ Development

This project use conventional commits and semantic versioning.

Also:

• pre-commit for code formatting, linting and conventional commit checks
• uv for project and dependency management.

Initial setup

$ pre-commit install
$ pre-commit install --hook-type commit-msg

Using with specific env

You can use UV_ENV_FILE or --env-file to specify the environment file to use.

$ export UV_ENV_FILE=.env
$ uv sync --all-extras --all-groups
$ uv run python -m examples.openai-sync-chat

Update typesgen.py

The typesgen.py script is derivated from the aiapi.yaml. This script will download the latest YAML file, patch it if necessary and generate the typesgen.py file.

$ uv run -m tools.sync-api