agenta 0.65.0__py3-none-any.whl → 0.70.1__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/client/backend/types/testset_output_response.py

@@ -13,6 +13,7 @@ class TestsetOutputResponse(UniversalBaseModel):
     name: str
     created_at: str
     updated_at: str
+    columns: typing.List[str]
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(

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,7 +80,11 @@ class AgentaSingleton:
 
         """
 
-        log.info("Agenta -  SDK ver: %s", version("agenta"))
+        # 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 = {}
         if config_fname:
@@ -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,7 +132,12 @@ class AgentaSingleton:
             or None  # NO FALLBACK
         )
 
-        log.info("Agenta -  API URL: %s", self.api_url)
+        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 = (
             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

@@ -28,6 +28,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 +65,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",

agenta/sdk/engines/tracing/tracing.py

@@ -114,7 +114,7 @@ class Tracing(metaclass=Singleton):
 
         # TRACE PROCESSORS -- OTLP
         try:
-            log.info("Agenta - OLTP URL: %s", self.otlp_url)
+            log.info("Agenta -    OTLP URL: %s", self.otlp_url)
 
             _otlp = TraceProcessor(
                 OTLPExporter(
@@ -127,7 +127,7 @@ class Tracing(metaclass=Singleton):
 
             self.tracer_provider.add_span_processor(_otlp)
         except:  # pylint: disable=bare-except
-            log.warning("Agenta - OLTP unreachable, skipping exports.")
+            log.warning("Agenta - OTLP unreachable, skipping exports.")
 
         # GLOBAL TRACER PROVIDER -- INSTRUMENTATION LIBRARIES
         set_tracer_provider(self.tracer_provider)

agenta/sdk/evaluations/metrics.py

@@ -13,15 +13,15 @@ async def arefresh(
     # timestamp: Optional[str] = None,
     # interval: Optional[float] = None,
 ) -> EvaluationMetrics:
-    payload = dict(
+    metrics = dict(
         run_id=str(run_id),
         scenario_id=str(scenario_id) if scenario_id else None,
     )
 
     response = authed_api()(
         method="POST",
-        endpoint=f"/preview/evaluations/metrics/refresh",
-        params=payload,
+        endpoint="/preview/evaluations/metrics/refresh",
+        json=dict(metrics=metrics),
     )
 
     try:

agenta/sdk/litellm/litellm.py

@@ -166,24 +166,27 @@ def litellm_handler():
                 namespace="metrics.unit.costs",
             )
 
+            # Handle both dict and object attribute access for usage, and safely handle None
+            usage = getattr(response_obj, "usage", None)
+            if isinstance(usage, dict):
+                prompt_tokens = usage.get("prompt_tokens")
+                completion_tokens = usage.get("completion_tokens")
+                total_tokens = usage.get("total_tokens")
+            elif usage is not None:
+                prompt_tokens = getattr(usage, "prompt_tokens", None)
+                completion_tokens = getattr(usage, "completion_tokens", None)
+                total_tokens = getattr(usage, "total_tokens", None)
+            else:
+                prompt_tokens = completion_tokens = total_tokens = None
+
             span.set_attributes(
                 attributes=(
                     {
-                        "prompt": (
-                            float(response_obj.usage.prompt_tokens)
-                            if response_obj.usage.prompt_tokens
-                            else None
-                        ),
-                        "completion": (
-                            float(response_obj.usage.completion_tokens)
-                            if response_obj.usage.completion_tokens
-                            else None
-                        ),
-                        "total": (
-                            float(response_obj.usage.total_tokens)
-                            if response_obj.usage.total_tokens
-                            else None
-                        ),
+                        "prompt": float(prompt_tokens) if prompt_tokens else None,
+                        "completion": float(completion_tokens)
+                        if completion_tokens
+                        else None,
+                        "total": float(total_tokens) if total_tokens else None,
                     }
                 ),
                 namespace="metrics.unit.tokens",
@@ -300,24 +303,29 @@ def litellm_handler():
                 namespace="metrics.unit.costs",
             )
 
+            # Handle both dict and object attribute access for usage
+            usage = getattr(response_obj, "usage", None)
+            if usage is None:
+                prompt_tokens = None
+                completion_tokens = None
+                total_tokens = None
+            elif isinstance(usage, dict):
+                prompt_tokens = usage.get("prompt_tokens")
+                completion_tokens = usage.get("completion_tokens")
+                total_tokens = usage.get("total_tokens")
+            else:
+                prompt_tokens = getattr(usage, "prompt_tokens", None)
+                completion_tokens = getattr(usage, "completion_tokens", None)
+                total_tokens = getattr(usage, "total_tokens", None)
+
             span.set_attributes(
                 attributes=(
                     {
-                        "prompt": (
-                            float(response_obj.usage.prompt_tokens)
-                            if response_obj.usage.prompt_tokens
-                            else None
-                        ),
-                        "completion": (
-                            float(response_obj.usage.completion_tokens)
-                            if response_obj.usage.completion_tokens
-                            else None
-                        ),
-                        "total": (
-                            float(response_obj.usage.total_tokens)
-                            if response_obj.usage.total_tokens
-                            else None
-                        ),
+                        "prompt": float(prompt_tokens) if prompt_tokens else None,
+                        "completion": float(completion_tokens)
+                        if completion_tokens
+                        else None,
+                        "total": float(total_tokens) if total_tokens else None,
                     }
                 ),
                 namespace="metrics.unit.tokens",

agenta/sdk/middleware/auth.py

@@ -17,14 +17,12 @@ import agenta as ag
 
 log = get_module_logger(__name__)
 
-AGENTA_RUNTIME_PREFIX = getenv("AGENTA_RUNTIME_PREFIX", "")
-
 
 _CACHE_ENABLED = (
     getenv("AGENTA_SERVICE_MIDDLEWARE_CACHE_ENABLED", "true").lower() in TRUTHY
 )
 
-_ALWAYS_ALLOW_LIST = [f"{AGENTA_RUNTIME_PREFIX}/health"]
+_ALWAYS_ALLOW_LIST = ["/health"]
 
 _cache = TTLLRUCache()
 
@@ -64,7 +62,7 @@ class AuthHTTPMiddleware(BaseHTTPMiddleware):
 
     async def dispatch(self, request: Request, call_next: Callable):
         try:
-            if request.url.path in _ALWAYS_ALLOW_LIST:
+            if _strip_service_prefix(request.url.path) in _ALWAYS_ALLOW_LIST:
                 request.state.auth = {}
 
             else:
@@ -253,3 +251,20 @@ class AuthHTTPMiddleware(BaseHTTPMiddleware):
                 status_code=500,
                 content=f"Could not verify credentials: unexpected error - {str(exc)}. Please try again later or contact support if the issue persists.",
             ) from exc
+
+
+def _strip_service_prefix(path: str) -> str:
+    if not path.startswith("/services/"):
+        return path
+
+    parts = path.split("/", 3)
+    if len(parts) < 4:
+        return "/"
+
+    service_name = parts[2]
+    remainder = parts[3]
+
+    if not service_name or not remainder or remainder.startswith("/"):
+        return path
+
+    return f"/{remainder}"

agenta/sdk/middleware/otel.py

@@ -3,9 +3,6 @@ from typing import Callable
 from starlette.middleware.base import BaseHTTPMiddleware
 from fastapi import Request, FastAPI
 
-from opentelemetry.baggage.propagation import W3CBaggagePropagator
-from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
-
 from agenta.sdk.utils.exceptions import suppress
 from agenta.sdk.tracing.propagation import extract
 

agenta/sdk/middleware/vault.py

@@ -21,11 +21,9 @@ import agenta as ag
 log = get_module_logger(__name__)
 
 
-AGENTA_RUNTIME_PREFIX = getenv("AGENTA_RUNTIME_PREFIX", "")
-
 _ALWAYS_ALLOW_LIST = [
-    f"{AGENTA_RUNTIME_PREFIX}/health",
-    f"{AGENTA_RUNTIME_PREFIX}/openapi.json",
+    "/health",
+    "/openapi.json",
 ]
 
 _PROVIDER_KINDS = [
@@ -116,7 +114,7 @@ class VaultMiddleware(BaseHTTPMiddleware):
         allow_secrets = True
 
         try:
-            if not request.url.path in _ALWAYS_ALLOW_LIST:
+            if _strip_service_prefix(request.url.path) not in _ALWAYS_ALLOW_LIST:
                 await self._allow_local_secrets(credentials)
 
             for provider_kind in _PROVIDER_KINDS:
@@ -331,3 +329,20 @@ class VaultMiddleware(BaseHTTPMiddleware):
                 status_code=500,
                 content=f"Could not verify credentials: unexpected error - {str(exc)}. Please try again later or contact support if the issue persists.",
             ) from exc
+
+
+def _strip_service_prefix(path: str) -> str:
+    if not path.startswith("/services/"):
+        return path
+
+    parts = path.split("/", 3)
+    if len(parts) < 4:
+        return "/"
+
+    service_name = parts[2]
+    remainder = parts[3]
+
+    if not service_name or not remainder or remainder.startswith("/"):
+        return path
+
+    return f"/{remainder}"

agenta/sdk/middlewares/running/vault.py

@@ -127,7 +127,7 @@ class VaultMiddleware:
         request: WorkflowServiceRequest,
         call_next: Callable[[WorkflowServiceRequest], Any],
     ):
-        api_url = f"{ag.DEFAULT_AGENTA_SINGLETON_INSTANCE.host}/api"
+        api_url = ag.DEFAULT_AGENTA_SINGLETON_INSTANCE.api_url
 
         with suppress():
             ctx = RunningContext.get()

agenta/sdk/models/evaluations.py

@@ -53,9 +53,17 @@ class EvaluationStatus(str, Enum):
 
 
 class EvaluationRunFlags(BaseModel):
-    is_closed: Optional[bool] = None  # Indicates if the run is immutable
-    is_live: Optional[bool] = None  # Indicates if the run is updated periodically
-    is_active: Optional[bool] = None  # Indicates if the run is currently active
+    is_live: bool = False  # Indicates if the run has live queries
+    is_active: bool = False  # Indicates if the run is currently active
+    is_closed: bool = False  # Indicates if the run is modifiable
+    #
+    has_queries: bool = False  # Indicates if the run has queries
+    has_testsets: bool = False  # Indicates if the run has testsets
+    has_evaluators: bool = False  # Indicates if the run has evaluators
+    #
+    has_custom: bool = False  # Indicates if the run has custom evaluators
+    has_human: bool = False  # Indicates if the run has human evaluators
+    has_auto: bool = False  # Indicates if the run has auto evaluators
 
 
 class SimpleEvaluationFlags(EvaluationRunFlags):

agenta/sdk/models/shared.py

@@ -88,7 +88,7 @@ class Slug(BaseModel):
     def check_url_safety(cls, v):
         if v is not None:
             if not match(r"^[a-zA-Z0-9_-]+$", v):
-                raise ValueError("slug must be URL-safe.")
+                raise ValueError("'slug' must be URL-safe.")
         return v
 
 

agenta/sdk/tracing/exporters.py

@@ -122,6 +122,7 @@ class OTLPExporter(OTLPSpanExporter):
                     #     "[SPAN]  [EXPORT]",
                     #     trace_id=UUID(int=trace_id).hex,
                     #     span_id=UUID(int=span_id).hex[-16:],
+                    #     span_attributes=_span.attributes,
                     # )
 
                 serialized_spans.append(super().export(_spans))