feat(docs): introduce readthedocs documentation

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3"
+  # We recommend using a requirements file for reproducible builds.
+  # This is just a quick example to get started.
+  # https://docs.readthedocs.io/page/guides/reproducible-builds.html
+  jobs:
+    pre_install:
+      - pip install mkdocs-material
+
+mkdocs:
+  configuration: mkdocs.yml

docs/api/api_client.md

@@ -0,0 +1,19 @@
+## API Client
+
+The Scope3AI SDK provides both synchronous ([`Client`](#scope3ai.api.client.Client)) and
+asynchronous ([`AsyncClient`](#scope3ai.api.client.AsyncClient)) HTTP clients for interacting
+with the Scope3AI API.
+
+All the commands from the [`AsyncClient`](#scope3ai.api.client.AsyncClient) can be invoked with the `await`.
+
+
+::: scope3ai.api.client
+    options:
+      heading_level: 1
+      show_if_no_docstring: true
+      inherited_members: false
+      members:
+      - Client
+      - AsyncClient
+      - ClientBase
+      - ClientCommands

docs/api/api_types.md

@@ -0,0 +1,5 @@
+# API Types
+
+::: scope3ai.api.types
+    options:
+      show_if_no_docstring: true

docs/api/scope3ai.md

@@ -0,0 +1,11 @@
+# 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

docs/api/tracer.md

@@ -0,0 +1,8 @@
+# Tracer
+
+Tracer provides a convenient way to aggregate multiple library calls made within
+its context, automatically waiting for and aggregating impact data when
+accessed, unlike direct API calls which need to be handled individually - see
+our [complete guide](../tracer.md) for details and examples.
+
+::: scope3ai.api.tracer

docs/configuration.md

@@ -0,0 +1,51 @@
+# Configuration
+
+The SDK can be configured either through environment variables or when calling `Scope3AI.init()`.
+
+The following environment variables are supported:
+
+| Environment Variable | Description | Scope3AI.init | Tracer |
+|---------------------|-------------|---------------|--------------|
+| `SCOPE3AI_API_KEY` | Required. Your Scope3AI API key | [api_key](/scope3ai/#scope3ai.lib.Scope3AI.init) | |
+| `SCOPE3AI_API_URL` | The API endpoint URL | [api_url](/scope3ai/#scope3ai.lib.Scope3AI.init) | |
+| `SCOPE3AI_DEBUG_LOGGING` | Enable debug logging | [enable_debug_logging](/scope3ai/#scope3ai.lib.Scope3AI.init) | |
+| `SCOPE3AI_SYNC_MODE` | Enable synchronous mode | [sync_mode](/scope3ai/#scope3ai.lib.Scope3AI.init) | |
+| `SCOPE3AI_ENVIRONMENT` | User-defined environment name (e.g. "production", "staging") | [environment](/scope3ai/#scope3ai.lib.Scope3AI.init) | |
+| `SCOPE3AI_APPLICATION_ID` | User-defined application identifier | [application_id](/scope3ai/#scope3ai.lib.Scope3AI.init) | [application_id](/tracer/#scope3ai.api.tracer.Tracer) |
+| `SCOPE3AI_CLIENT_ID` | User-defined client identifier | [client_id](/scope3ai/#scope3ai.lib.Scope3AI.init) | [client_id](/tracer/#scope3ai.api.tracer.Tracer) |
+| `SCOPE3AI_PROJECT_ID` | User-defined project identifier | [project_id](/scope3ai/#scope3ai.lib.Scope3AI.init) | [project_id](/tracer/#scope3ai.api.tracer.Tracer) |
+
+Example using environment variables:
+
+```env
+SCOPE3AI_API_KEY=your_api_key_here
+SCOPE3AI_ENVIRONMENT=staging
+SCOPE3AI_APPLICATION_ID=my-app
+SCOPE3AI_PROJECT_ID=my-project
+```
+
+Example using initialization parameters in `Scope3AI.init()`:
+
+```python
+scope3 = Scope3AI.init(
+    api_key="your_api_key_here",
+    environment="staging",
+    application_id="my-app",
+    project_id="my-project",
+    sync_mode=True,
+    enable_debug_logging=True
+)
+```
+
+Example using initialization parameters in `Tracer`:
+
+```python
+scope3 = Scope3AI.init(
+    api_key="your_api_key_here",
+)
+
+# Override application ID for this specific trace
+with scope3.trace(application_id="my-specific-app") as tracer:
+    # Run operations with "my-specific-app" identifier
+    interact()
+```

docs/index.md

@@ -0,0 +1,24 @@
+# 👋 Welcome to Scope3AI Python SDK documentation
+
+Scope3AI is a Python SDK that integrates with popular AI and ML libraries like
+OpenAI, Anthropic, HuggingFace, etc. to track, measure, and report on the
+environmental impact of AI model usage. It provides an easy interface to the
+Scope3AI API for recording interactions and analyzing sustainability metrics
+like energy consumption, carbon emissions, and water usage.
+
+## 📖 Documentation
+
+- [Quickstart Guide](quickstart.md) - Get up and running quickly with Scope3AI
+- [Working with Tracers](tracer.md) - Learn how to work with tracers to measure AI impact
+- [API Reference](api/scope3ai.md) - Detailed API documentation
+
+# Supported libraries
+
+| 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           |

docs/quickstart.md

@@ -0,0 +1,115 @@
+# Quick Start
+
+The Scope3AI Python SDK helps you track, record and analyze the environmental
+impact of your AI model usage. It provides an easy-to-use interface to the
+Scope3AI API, which calculates metrics like energy consumption, CO2 emissions,
+and water usage for AI model inferences.
+
+The SDK automatically instruments popular AI libraries and platforms (OpenAI,
+Anthropic, Cohere, etc.) to capture metadata about model usage. This allows you
+to:
+
+- Track impact metrics across your AI applications
+- Analyze sustainability data by project, client, or environment
+- Get real-time feedback on resource consumption
+
+## Installation
+
+Install the Scope3AI Python SDK with pip:
+
+```bash
+pip install scope3ai
+```
+
+Or with uv:
+
+```bash
+uv add scope3ai
+```
+
+## Initialize the SDK
+
+Configure your credentials either in code or through environment variables:
+
+```python
+from scope3ai import Scope3AI
+
+# Initialize with API key
+scope3 = Scope3AI.init(
+    api_key="YOUR_API_KEY",
+    environment="production",
+    application_id="my-app"
+)
+```
+
+Or using environment variables:
+
+```bash
+export SCOPE3AI_API_KEY=YOUR_API_KEY
+export SCOPE3AI_ENVIRONMENT=production
+export SCOPE3AI_APPLICATION_ID=my-app
+```
+
+```python
+from scope3ai import Scope3AI
+
+scope3 = Scope3AI.init()
+```
+
+## Enable Specific Providers
+
+By default, all supported providers are enabled if found in available installed
+libraries. You can specify which ones to enable:
+
+```python
+scope3 = Scope3AI.init(
+    api_key="YOUR_API_KEY",
+    providers=["openai", "anthropic", "cohere"]
+)
+```
+
+## Using Tracers
+
+Use the context manager to trace API calls and get their impact:
+
+```python
+with scope3.trace() as tracer:
+    # Make your API calls here
+    response = openai.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+
+    # Get impact metrics for all calls in this trace
+    impact = tracer.impact()
+    print(f"Total Energy: {impact.total_energy_wh} Wh")
+    print(f"Total CO2: {impact.total_gco2e} gCO2e")
+    print(f"Total Water: {impact.total_mlh2o} mL")
+```
+
+You can also configure metadata per-trace:
+
+```python
+with scope3.trace(
+    client_id="my-client",
+    project_id="my-project",
+    session_id="user-123"
+) as tracer:
+    # Make API calls...
+```
+
+## Getting Impact Data Synchronously
+
+Enable sync mode to get impact data immediately:
+
+```python
+scope3.sync_mode = True
+
+response = openai.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+
+impact = response.scope3ai.impact
+print(f"Energy used: {impact.total_energy_wh} Wh")
+```