agenta 0.68.0__py3-none-any.whl → 0.72.4__py3-none-any.whl

agenta/__init__.py

@@ -1,52 +1,50 @@
 from typing import Any, Callable, Optional
 
-from .sdk.utils.preinit import PreInitObject
-
-from agenta.client import AgentaApi, AsyncAgentaApi
 import agenta.client.backend.types as client_types  # pylint: disable=wrong-import-order
+from agenta.client import AgentaApi, AsyncAgentaApi
 
-from .sdk.types import (
-    MCField,
-    DictInput,
-    MultipleChoice,
-    FloatParam,
-    IntParam,
-    MultipleChoiceParam,
-    GroupedMultipleChoiceParam,
-    MessagesInput,
-    TextParam,
-    FileInputURL,
-    BinaryParam,
-    Prompt,
-    PromptTemplate,
-)
+from .sdk import assets as assets
 
-from .sdk.agenta_init import Config, AgentaSingleton, init as _init
-from .sdk.utils.logging import get_module_logger
-from .sdk.utils.costs import calculate_token_usage
-from .sdk.tracing import Tracing, get_tracer
-from .sdk.tracing.conventions import Reference
-from .sdk.decorators.tracing import instrument
+# evaluations
+from .sdk import testsets as testsets
+from .sdk import tracer
+from .sdk.agenta_init import AgentaSingleton, Config
+from .sdk.agenta_init import init as _init
+from .sdk.context.running import workflow_mode_enabled
 from .sdk.decorators.running import (
-    workflow,
     application,
     evaluator,
+    workflow,
 )
-from .sdk.decorators.serving import route, app
-from .sdk.context.running import workflow_mode_enabled
+from .sdk.decorators.serving import app, route
+from .sdk.decorators.tracing import instrument
 from .sdk.litellm import litellm as callbacks
 from .sdk.managers.apps import AppManager
-from .sdk.managers.vault import VaultManager
-from .sdk.managers.secrets import SecretsManager
 from .sdk.managers.config import ConfigManager
-from .sdk.managers.variant import VariantManager
 from .sdk.managers.deployment import DeploymentManager
-from .sdk import assets as assets
-from .sdk import tracer
-
-# evaluations
-from .sdk import testsets as testsets
-
+from .sdk.managers.secrets import SecretsManager
+from .sdk.managers.variant import VariantManager
+from .sdk.managers.vault import VaultManager
+from .sdk.tracing import Tracing, get_tracer
+from .sdk.tracing.conventions import Reference
+from .sdk.types import (
+    BinaryParam,
+    DictInput,
+    FileInputURL,
+    FloatParam,
+    GroupedMultipleChoiceParam,
+    IntParam,
+    MCField,
+    MessagesInput,
+    MultipleChoice,
+    MultipleChoiceParam,
+    Prompt,
+    PromptTemplate,
+    TextParam,
+)
+from .sdk.utils.costs import calculate_token_usage
+from .sdk.utils.logging import get_module_logger
+from .sdk.utils.preinit import PreInitObject
 
 config = PreInitObject("agenta.config", Config)
 DEFAULT_AGENTA_SINGLETON_INSTANCE = AgentaSingleton()
@@ -88,3 +86,35 @@ def init(
 
     tracing = DEFAULT_AGENTA_SINGLETON_INSTANCE.tracing  # type: ignore
     tracer = get_tracer(tracing)
+
+
+def get_trace_url(trace_id: Optional[str] = None) -> str:
+    """
+    Build a URL to view the current trace in the Agenta UI.
+
+    Automatically extracts the trace ID from the current tracing context.
+    Can also accept an explicit trace_id if needed.
+
+    Args:
+        trace_id: Optional trace ID (hex string format). If not provided,
+                  it will be automatically extracted from the current trace context.
+
+    Returns:
+        The full URL to view the trace in the observability dashboard
+
+    Raises:
+        RuntimeError: If the SDK is not initialized, no active trace context exists,
+                      or scope info cannot be fetched
+
+    Example:
+        >>> import agenta as ag
+        >>> ag.init(api_key="xxx")
+        >>>
+        >>> @ag.instrument()
+        >>> def my_function():
+        >>>     # Get URL for the current trace
+        >>>     url = ag.tracing.get_trace_url()
+        >>>     print(url)
+        >>>     return "result"
+    """
+    return DEFAULT_AGENTA_SINGLETON_INSTANCE.tracing.get_trace_url(trace_id)

agenta/sdk/agenta_init.py

@@ -1,16 +1,15 @@
-import toml
-from os import getenv
-from typing import Optional, Callable, Any
 from importlib.metadata import version
+from os import getenv
+from typing import Any, Callable, Optional
 
-from agenta.sdk.utils.helpers import parse_url
-from agenta.sdk.utils.globals import set_global
-from agenta.sdk.utils.logging import get_module_logger
+import requests
+import toml
 from agenta.client.client import AgentaApi, AsyncAgentaApi
-
-from agenta.sdk.tracing import Tracing
 from agenta.sdk.contexts.routing import RoutingContext
-
+from agenta.sdk.tracing import Tracing
+from agenta.sdk.utils.globals import set_global
+from agenta.sdk.utils.helpers import parse_url
+from agenta.sdk.utils.logging import get_module_logger
 
 log = get_module_logger(__name__)
 
@@ -19,6 +18,7 @@ class AgentaSingleton:
     """Singleton class to save all the "global variables" for the sdk."""
 
     _instance = None
+    _initialized = False
     config = None
     tracing = None
 
@@ -26,6 +26,11 @@ class AgentaSingleton:
     async_api = None
 
     def __init__(self):
+        # Only initialize once
+        if AgentaSingleton._initialized:
+            return
+
+        AgentaSingleton._initialized = True
         self.host = None
         self.api_url = None
         self.api_key = None
@@ -33,6 +38,11 @@ class AgentaSingleton:
         self.scope_type = None
         self.scope_id = None
 
+        # Cached scope information for URL building
+        self.organization_id: Optional[str] = None
+        self.workspace_id: Optional[str] = None
+        self.project_id: Optional[str] = None
+
     def __new__(cls):
         if not cls._instance:
             cls._instance = super(AgentaSingleton, cls).__new__(cls)
@@ -70,6 +80,10 @@ class AgentaSingleton:
 
         """
 
+        # Idempotency check: if already initialized, skip re-initialization
+        if self.tracing and self.api and self.async_api:
+            return
+
         log.info("Agenta -     SDK ver: %s", version("agenta"))
 
         config = {}
@@ -100,7 +114,7 @@ class AgentaSingleton:
 
         try:
             assert _api_url and isinstance(_api_url, str), (
-                "API URL is required. Please provide a valid API URL or set AGENTA_API_URL environment variable."
+                "API URL is required. Please set AGENTA_API_URL environment variable or pass api_url parameter in ag.init()."
             )
             self.host = _host
             self.api_url = _api_url
@@ -118,6 +132,11 @@ class AgentaSingleton:
             or None  # NO FALLBACK
         )
 
+        if self.api_key is None:
+            log.error(
+                "API key is required. Please set AGENTA_API_KEY environment variable or pass api_key parameter in ag.init()."
+            )
+
         log.info("Agenta -     API URL: %s", self.api_url)
 
         self.scope_type = (
@@ -159,6 +178,65 @@ class AgentaSingleton:
             api_key=self.api_key,
         )
 
+        # Reset cached scope info on re-init
+        self.organization_id = None
+        self.workspace_id = None
+        self.project_id = None
+
+    def resolve_scopes(self) -> Optional[tuple[str, str, str]]:
+        """Fetch and cache workspace_id and project_id from the API."""
+        if (
+            self.organization_id is not None
+            and self.workspace_id is not None
+            and self.project_id is not None
+        ):
+            return
+
+        if self.api_url is None or self.api_key is None:
+            log.error("API URL or API key is not set. Please call ag.init() first.")
+            return
+
+        try:
+            response = requests.get(
+                f"{self.api_url}/projects/current",
+                headers={"Authorization": f"ApiKey {self.api_key}"},
+                timeout=10,
+            )
+            response.raise_for_status()
+
+            project_info = response.json()
+
+            if not project_info:
+                log.error(
+                    "No project context found. Please ensure your API key is valid."
+                )
+
+            self.organization_id = project_info.get("organization_id")
+            self.workspace_id = project_info.get("workspace_id")
+            self.project_id = project_info.get("project_id")
+
+            if (
+                not self.organization_id
+                and not self.workspace_id
+                or not self.project_id
+            ):
+                log.error(
+                    "Could not determine organization/workspace/project from API response."
+                )
+
+        except Exception as e:
+            log.error(f"Failed to fetch scope information: {e}")
+            return
+
+        if self.organization_id and self.workspace_id and self.project_id:
+            return (
+                self.organization_id,
+                self.workspace_id,
+                self.project_id,
+            )
+
+        return None
+
 
 class Config:
     def __init__(

agenta/sdk/assets.py

@@ -1,3 +1,8 @@
+from typing import Dict, Optional, Tuple
+
+from litellm import cost_calculator
+
+
 supported_llm_models = {
     "anthropic": [
         "anthropic/claude-sonnet-4-5",
@@ -28,6 +33,7 @@ supported_llm_models = {
     ],
     "gemini": [
         "gemini/gemini-3-pro-preview",
+        "gemini/gemini-3-flash-preview",
         "gemini/gemini-2.5-pro",
         "gemini/gemini-2.5-pro-preview-05-06",
         "gemini/gemini-2.5-flash",
@@ -64,21 +70,26 @@ supported_llm_models = {
         "mistral/mistral-large-latest",
     ],
     "openai": [
-        "gpt-5",
+        "gpt-5.2-pro",
+        "gpt-5.2-chat-latest",
+        "gpt-5.2",
+        "gpt-5.1-chat-latest",
         "gpt-5.1",
-        "gpt-5-mini",
+        "gpt-5-pro",
         "gpt-5-nano",
+        "gpt-5-mini",
+        "gpt-5",
+        "o4-mini",
         "gpt-4.5-preview",
-        "gpt-3.5-turbo-1106",
-        "gpt-3.5-turbo",
-        "gpt-4",
-        "gpt-4o",
+        "gpt-4.1-nano",
+        "gpt-4.1-mini",
+        "gpt-4.1",
         "gpt-4o-mini",
+        "gpt-4o",
         "gpt-4-1106-preview",
-        "gpt-4.1",
-        "gpt-4.1-mini",
-        "gpt-4.1-nano",
-        "o4-mini",
+        "gpt-4",
+        "gpt-3.5-turbo-1106",
+        "gpt-3.5-turbo",
     ],
     "openrouter": [
         "openrouter/qwen/qwen3-235b-a22b",
@@ -200,6 +211,58 @@ supported_llm_models = {
 
 providers_list = list(supported_llm_models.keys())
 
+
+def _get_model_costs(model: str) -> Optional[Tuple[float, float]]:
+    """
+    Get the input and output costs per 1M tokens for a model.
+
+    Uses litellm's cost_calculator (same as tracing/inline.py) for consistency.
+
+    Args:
+        model: The model name (e.g., "gpt-4o" or "anthropic/claude-3-opus-20240229")
+
+    Returns:
+        Tuple of (input_cost, output_cost) per 1M tokens, or None if not found.
+    """
+    try:
+        costs = cost_calculator.cost_per_token(
+            model=model,
+            prompt_tokens=1_000_000,
+            completion_tokens=1_000_000,
+        )
+        if costs:
+            input_cost, output_cost = costs
+            if input_cost > 0 or output_cost > 0:
+                return (input_cost, output_cost)
+    except Exception:
+        pass
+    return None
+
+
+def _build_model_metadata() -> Dict[str, Dict[str, Dict[str, float]]]:
+    """
+    Build metadata dictionary with costs for all supported models.
+
+    Returns:
+        Nested dict: {provider: {model: {"input": cost, "output": cost}}}
+    """
+    metadata: Dict[str, Dict[str, Dict[str, float]]] = {}
+
+    for provider, models in supported_llm_models.items():
+        metadata[provider] = {}
+        for model in models:
+            costs = _get_model_costs(model)
+            if costs:
+                metadata[provider][model] = {
+                    "input": costs[0],
+                    "output": costs[1],
+                }
+
+    return metadata
+
+
+model_metadata = _build_model_metadata()
+
 model_to_provider_mapping = {
     model: provider
     for provider, models in supported_llm_models.items()

agenta/sdk/decorators/serving.py

@@ -1,53 +1,51 @@
-from typing import Type, Any, Callable, Dict, Optional, Tuple, List
+from asyncio import sleep
+from functools import wraps
 from inspect import (
+    Parameter,
+    Signature,
+    isasyncgen,
     iscoroutinefunction,
     isgenerator,
-    isasyncgen,
     signature,
-    Signature,
-    Parameter,
 )
-from functools import wraps
+from os import environ
 from traceback import format_exception
-from asyncio import sleep
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type
 from uuid import UUID
-from pydantic import BaseModel, HttpUrl, ValidationError
-from os import environ
-
-from starlette.responses import (
-    Response as StarletteResponse,
-    StreamingResponse,
-)
-from fastapi import Body, FastAPI, HTTPException, Request
-
-from agenta.sdk.middleware.mock import MockMiddleware
-from agenta.sdk.middleware.inline import InlineMiddleware
-from agenta.sdk.middleware.vault import VaultMiddleware
-from agenta.sdk.middleware.config import ConfigMiddleware
-from agenta.sdk.middleware.otel import OTelMiddleware
-from agenta.sdk.middleware.auth import AuthHTTPMiddleware
-from agenta.sdk.middleware.cors import CORSMiddleware
 
+import agenta as ag
 from agenta.sdk.contexts.routing import (
-    routing_context_manager,
     RoutingContext,
+    routing_context_manager,
 )
 from agenta.sdk.contexts.tracing import (
-    tracing_context_manager,
     TracingContext,
+    tracing_context_manager,
 )
+from agenta.sdk.middleware.auth import AuthHTTPMiddleware
+from agenta.sdk.middleware.config import ConfigMiddleware
+from agenta.sdk.middleware.cors import CORSMiddleware
+from agenta.sdk.middleware.inline import InlineMiddleware
+from agenta.sdk.middleware.mock import MockMiddleware
+from agenta.sdk.middleware.otel import OTelMiddleware
+from agenta.sdk.middleware.vault import VaultMiddleware
 from agenta.sdk.router import router
-from agenta.sdk.utils.exceptions import suppress, display_exception
-from agenta.sdk.utils.logging import get_module_logger
-from agenta.sdk.utils.helpers import get_current_version
 from agenta.sdk.types import (
-    MultipleChoice,
     BaseResponse,
+    MultipleChoice,
     StreamResponse,
-    MCField,
 )
-
-import agenta as ag
+from agenta.sdk.utils.exceptions import display_exception, suppress
+from agenta.sdk.utils.helpers import get_current_version
+from agenta.sdk.utils.logging import get_module_logger
+from fastapi import Body, FastAPI, HTTPException, Request
+from pydantic import BaseModel, HttpUrl, ValidationError
+from starlette.responses import (
+    Response as StarletteResponse,
+)
+from starlette.responses import (
+    StreamingResponse,
+)
 
 log = get_module_logger(__name__)
 

agenta/sdk/decorators/tracing.py

@@ -1,36 +1,27 @@
 # /agenta/sdk/decorators/tracing.py
 
-from typing import Callable, Optional, Any, Dict, List, Union
-
-from opentelemetry import context as otel_context
-from opentelemetry.context import attach, detach
-
-
 from functools import wraps
-from itertools import chain
 from inspect import (
     getfullargspec,
+    isasyncgenfunction,
     iscoroutinefunction,
     isgeneratorfunction,
-    isasyncgenfunction,
 )
+from itertools import chain
+from typing import Any, Callable, Dict, List, Optional, Union
 
-from pydantic import BaseModel
-
-from opentelemetry import baggage
-from opentelemetry.context import attach, detach, get_current
-from opentelemetry.baggage import set_baggage, get_all
-
-from agenta.sdk.utils.logging import get_module_logger
-from agenta.sdk.utils.exceptions import suppress
+import agenta as ag
 from agenta.sdk.contexts.tracing import (
     TracingContext,
     tracing_context_manager,
 )
 from agenta.sdk.tracing.conventions import parse_span_kind
-
-import agenta as ag
-
+from agenta.sdk.utils.exceptions import suppress
+from agenta.sdk.utils.logging import get_module_logger
+from opentelemetry import context as otel_context
+from opentelemetry.baggage import get_all, set_baggage
+from opentelemetry.context import attach, detach, get_current
+from pydantic import BaseModel
 
 log = get_module_logger(__name__)
 
@@ -88,11 +79,12 @@ class instrument:  # pylint: disable=invalid-name
                 with tracing_context_manager(context=TracingContext.get()):
                     # debug_otel_context("[BEFORE STREAM] [BEFORE SETUP]")
 
-                    captured_ctx = otel_context.get_current()
-
                     self._parse_type_and_kind()
 
-                    self._attach_baggage()
+                    baggage_token = self._attach_baggage()
+
+                    # Capture AFTER baggage attach so we do not wipe it later.
+                    captured_ctx = otel_context.get_current()
 
                     ctx = self._get_traceparent()
 
@@ -141,6 +133,7 @@ class instrument:  # pylint: disable=invalid-name
                             otel_context.detach(otel_token)
 
                             # debug_otel_context("[WITHIN STREAM] [AFTER DETACH]")
+                            self._detach_baggage(baggage_token)
 
                 return wrapped_generator()
 
@@ -311,15 +304,43 @@ class instrument:  # pylint: disable=invalid-name
 
     def _attach_baggage(self):
         context = TracingContext.get()
+        otel_ctx = get_current()
+
+        # 1. Propagate any incoming `ag.*` baggage as-is (for example
+        # `ag.meta.session_id`) so all nested spans inherit it.
+        if context.baggage:
+            for k, v in context.baggage.items():
+                if not isinstance(k, str) or not k.startswith("ag."):
+                    continue
+                if v is None:
+                    continue
+                otel_ctx = set_baggage(name=k, value=str(v), context=otel_ctx)
+
+        # 2. Propagate Agenta references in baggage (used for linking traces to
+        # application/variant/environment).
+        if context.references:
+            for k, v in context.references.items():
+                if v is None:
+                    continue
+                if isinstance(v, BaseModel):
+                    try:
+                        v = v.model_dump(mode="json", exclude_none=True)
+                    except Exception:  # pylint: disable=bare-except
+                        pass
+                if isinstance(v, dict):
+                    for field, value in v.items():
+                        otel_ctx = set_baggage(
+                            name=f"ag.refs.{k}.{field}",
+                            value=str(value),
+                            context=otel_ctx,
+                        )
+                    continue
+                otel_ctx = set_baggage(
+                    name=f"ag.refs.{k}", value=str(v), context=otel_ctx
+                )
 
-        references = context.references
-
-        token = None
-        if references:
-            for k, v in references.items():
-                token = attach(baggage.set_baggage(f"ag.refs.{k}", v))
-
-        return token
+        # Attach once so we can reliably detach later.
+        return attach(otel_ctx)
 
     def _detach_baggage(
         self,

agenta/sdk/engines/tracing/processors.py

@@ -1,18 +1,17 @@
-from typing import Optional, Dict, List
 from threading import Lock
+from typing import Dict, List, Optional
 
+from agenta.sdk.models.tracing import BaseModel
+from agenta.sdk.utils.logging import get_module_logger
 from opentelemetry.baggage import get_all as get_baggage
 from opentelemetry.context import Context
 from opentelemetry.sdk.trace import Span, SpanProcessor
 from opentelemetry.sdk.trace.export import (
-    SpanExporter,
-    ReadableSpan,
     BatchSpanProcessor,
+    ReadableSpan,
+    SpanExporter,
 )
 
-from agenta.sdk.utils.logging import get_module_logger
-from agenta.sdk.engines.tracing.conventions import Reference
-
 log = get_module_logger(__name__)
 
 
@@ -51,15 +50,27 @@ class TraceProcessor(SpanProcessor):
         parent_context: Optional[Context] = None,
     ) -> None:
         for key in self.references.keys():
-            span.set_attribute(f"ag.refs.{key}", self.references[key])
+            ref = self.references[key]
+            if ref is None:
+                continue
+            if isinstance(ref, BaseModel):
+                try:
+                    ref = ref.model_dump(mode="json", exclude_none=True)
+                except Exception:  # pylint: disable=bare-except
+                    pass
+            if isinstance(ref, dict):
+                for field, value in ref.items():
+                    span.set_attribute(f"ag.refs.{key}.{field}", str(value))
+            else:
+                span.set_attribute(f"ag.refs.{key}", str(ref))
 
         baggage = get_baggage(parent_context)
 
-        for key in baggage.keys():
-            if key.startswith("ag.refs."):
-                _key = key.replace("ag.refs.", "")
-                if _key in [_.value for _ in Reference.__members__.values()]:
-                    span.set_attribute(key, baggage[key])
+        # Copy any `ag.*` baggage entries onto the span attributes so they can be
+        # used for filtering and grouping (for example `ag.meta.session_id`).
+        for key, value in baggage.items():
+            if key.startswith("ag."):
+                span.set_attribute(key, value)
 
         trace_id = span.context.trace_id
         span_id = span.context.span_id