refactor: rework the initial tracer and add parenting flow

Nothing is yet linked to the API per say, as it's still a proposal

README.md

@@ -24,6 +24,7 @@ scope3 = Scope3AI.init(
     api_key="YOUR_API_KEY",  # Replace "YOUR_API_KEY" with your actual key
     api_url="https://api.scope3.ai/v1",  # Optional: Specify the API URL
     include_impact_response=False,  # Include impact in responses (default: False)
+    enable_debug_logging=False,  # Enable debug logging (default: False)
 )
 ```
 
@@ -99,6 +100,19 @@ response = interact()
 print(response.scope3ai.impact)
 ```
 
+### 5. Specify name for grouping
+
+You can specify a name for grouping the interactions. This is useful for grouping interactions based on a specific context.
+
+```python
+with scope3.trace(name="my_workflow"):
+    interact()
+    with scope3.trace(name="image_generation"):
+        generate_image()
+        save_to_s3()
+    interact()
+```
+
 ## Development
 
 This project use conventional commits and semantic versioning.
@@ -113,3 +127,12 @@ Also:
 $ 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.
+
+```bash
+$ export UV_ENV_FILE=.env
+$ uv run python -m examples.openai-sync-chat
+```

examples/api-async.py

@@ -11,7 +11,7 @@
 ```
 """
 
-from scope3ai.v1.client import AsyncClient
+from scope3ai.api import AsyncClient
 
 # api_key is taken from the environment variable SCOPE3AI_API_KEY
 client = AsyncClient()
@@ -24,7 +24,7 @@ async def list_gpus():
 
 
 async def send_impact():
-    from scope3ai.v1.types import ImpactRequestRow, Model
+    from scope3ai.api.types import ImpactRequestRow, Model
 
     print("Sending impact")
     impact = ImpactRequestRow(

examples/api-sync.py

@@ -11,7 +11,7 @@
 ```
 """
 
-from scope3ai.v1.client import Client
+from scope3ai.api import Client
 
 # api_key is taken from the environment variable SCOPE3AI_API_KEY
 client = Client()
@@ -24,7 +24,7 @@ def list_gpus():
 
 
 def send_impact():
-    from scope3ai.v1.types import ImpactRequestRow, Model
+    from scope3ai.api.types import ImpactRequestRow, Model
 
     print("Sending impact")
     impact = ImpactRequestRow(

scope3ai/__init__.py

@@ -1,3 +1,4 @@
-__all__ = ["Scope3AI"]
-
+from .api.client import Client
 from .lib import Scope3AI
+
+__all__ = ["Client", "Scope3AI"]

scope3ai/api/__init__.py

@@ -0,0 +1,3 @@
+from .client import Client, AsyncClient
+
+__all__ = ["Client", "AsyncClient"]

scope3ai/api/client.py

@@ -54,6 +54,7 @@ class ClientCommands:
     def model(
         self,
         family: Optional[ModelFamily] = None,
+        with_response: Optional[bool] = True,
     ) -> ModelResponse:
         """
         List models
@@ -66,22 +67,28 @@ def model(
             method="GET",
             params=params,
             response_model=ModelResponse,
+            with_response=with_response,
         )
 
-    def gpu(self) -> GpuResponse:
+    def gpu(
+        self,
+        with_response: Optional[bool] = True,
+    ) -> GpuResponse:
         """
         List GPUs
         """
         return self.execute_request(
             "/gpu",
             method="GET",
             response_model=GpuResponse,
+            with_response=with_response,
         )
 
     def node(
         self,
         service: Optional[NodeService] = None,
         cloud: Optional[NodeCloud] = None,
+        with_response: Optional[bool] = True,
     ) -> NodeResponse:
         """
         List nodes
@@ -96,12 +103,14 @@ def node(
             method="GET",
             params=params,
             response_model=NodeResponse,
+            with_response=with_response,
         )
 
     def impact(
         self,
         rows: List[ImpactRequestRow],
         debug: Optional[bool] = None,
+        with_response: Optional[bool] = True,
     ) -> ImpactResponse:
         """
         Get impact metrics for a task
@@ -116,6 +125,7 @@ def impact(
             params=params,
             json=json_body,
             response_model=ImpactResponse,
+            with_response=with_response,
         )
 
 
@@ -134,6 +144,7 @@ def execute_request(
         params: Optional[dict] = None,
         json: Optional[dict] = None,
         response_model: Optional[BaseModel] = None,
+        with_response: Optional[bool] = True,
     ):
         full_url = self.api_url + url
         kwargs = {}
@@ -142,8 +153,11 @@ def execute_request(
         if json:
             kwargs["json"] = json
         response = self.client.request(method, full_url, **kwargs)
+        response.raise_for_status()
+        if not with_response:
+            return
         if response_model:
-            return response_model.parse_obj(response.json())
+            return response_model.model_validate(response.json())
         return response.json()
 
 
@@ -162,6 +176,7 @@ async def execute_request(
         params: Optional[dict] = None,
         json: Optional[dict] = None,
         response_model: Optional[BaseModel] = None,
+        with_response: Optional[bool] = True,
     ):
         full_url = self.api_url + url
         kwargs = {}
@@ -170,6 +185,9 @@ async def execute_request(
         if json:
             kwargs["json"] = json
         response = await self.client.request(method, full_url, **kwargs)
+        response.raise_for_status()
+        if not with_response:
+            return
         if response_model:
             return response_model.model_validate(response.json())
         return response.json()

scope3ai/api/types.py

@@ -1,6 +1,5 @@
 from pydantic import BaseModel, Field
 from typing import Optional, List
-from uuid import UUID
 from enum import Enum
 from datetime import datetime, timezone
 
@@ -163,8 +162,10 @@ class ImpactRequestRow(BaseModel):
         description="UTC timestamp for the request",
     )
     # Context of the request
-    session_id: Optional[UUID] = None
-    request_id: Optional[UUID] = None
+    session_id: Optional[str] = None
+    trace_id: Optional[str] = None  # not implemented in the API yet
+    parent_trace_id: Optional[str] = None  # not implemented in the API yet
+    request_id: Optional[str] = None
     client_id: Optional[str] = None
     project_id: Optional[str] = None
     application_id: Optional[str] = None