variably-sdk 2.12.0__tar.gz → 2.13.0__tar.gz

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variably-sdk
-Version: 2.12.0
+Version: 2.13.0
 Summary: Official Python SDK for Variably feature flags, LLM experimentation, and prompt optimization platform
 Author-email: Variably <support@variably.com>
 License: MIT
@@ -28,6 +28,11 @@ Requires-Dist: requests>=2.25.0
 Requires-Dist: typing-extensions>=3.7.4; python_version < "3.8"
 Provides-Extra: langgraph
 Requires-Dist: langgraph>=0.1; extra == "langgraph"
+Provides-Extra: adk
+Requires-Dist: google-adk<3,>=2.0; python_version >= "3.10" and extra == "adk"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.20; extra == "otel"
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
@@ -67,7 +72,7 @@ No experiment setup. No prompt migration. Just log and see scores.
 
 ```bash
 VARIABLY_API_KEY=vbl_your_key_here
-VARIABLY_BASE_URL=https://api.variably.tech
+VARIABLY_BASE_URL=https://api.variably.dev
 ```
 
 ### 2. Add one line after your LLM call

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/README.md

@@ -23,7 +23,7 @@ No experiment setup. No prompt migration. Just log and see scores.
 
 ```bash
 VARIABLY_API_KEY=vbl_your_key_here
-VARIABLY_BASE_URL=https://api.variably.tech
+VARIABLY_BASE_URL=https://api.variably.dev
 ```
 
 ### 2. Add one line after your LLM call

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "variably-sdk"
-version = "2.12.0"
+version = "2.13.0"
 description = "Official Python SDK for Variably feature flags, LLM experimentation, and prompt optimization platform"
 readme = "README.md"
 requires-python = ">=3.7"
@@ -39,6 +39,15 @@ dependencies = [
 langgraph = [
     "langgraph>=0.1",
 ]
+# Google ADK / Vertex AI Agent Engine plugin (#102). ADK itself needs Python >= 3.10.
+adk = [
+    "google-adk>=2.0,<3; python_version>='3.10'",
+]
+# OpenTelemetry exporter: send existing OTel traces to be evaluated.
+otel = [
+    "opentelemetry-sdk>=1.20,<2",
+    "opentelemetry-exporter-otlp-proto-http>=1.20,<2",
+]
 dev = [
     "pytest>=6.0",
     "pytest-asyncio>=0.18.0",

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/src/variably/__init__.py

@@ -8,6 +8,7 @@ from .client import VariablyClient
 from .config import VariablyConfig
 from .types import UserContext, Event, FlagResult, PromptVariant, EvaluateResponse, StreamingEvaluateResponse, SubmitResponseResult
 from .errors import (
+    FlagNotFoundError,
     VariablyError,
     NetworkError,
     AuthenticationError,
@@ -20,6 +21,7 @@ from .observe import observe
 from .version import __version__
 
 __all__ = [
+    "FlagNotFoundError",
     "VariablyClient",
     "VariablyConfig",
     "UserContext",

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/src/variably/client.py

@@ -7,7 +7,7 @@ from typing import Any, Dict, List, Optional, Union
 
 from .cache import CacheManager, NoOpCache
 from .config import VariablyConfig
-from .errors import ConfigurationError, VariablyError
+from .errors import ConfigurationError, FlagNotFoundError, VariablyError
 from .http_client import HTTPClient
 from .logger import VariablyLogger, create_logger
 from .prompt_config import PromptConfigStore, http_config_fetcher
@@ -24,6 +24,10 @@ from .types import (
 )
 
 
+#: Reason the API returns when a project has no such flag.
+FLAG_NOT_FOUND_REASON = "gate_not_found"
+
+
 class VariablyClient:
     """Main Variably SDK client for feature flags and experimentation."""
     
@@ -155,10 +159,10 @@ class VariablyClient:
                 raise ConfigurationError(
                     "Flag key must be a non-empty string", "flag_key"
                 )
-            if not user_context.get("user_id"):
-                raise ConfigurationError(
-                    "User context must include user_id", "user_context.user_id"
-                )
+            # A user id is optional. Server-rendered callers evaluate before a user
+            # is known and expect the flag's default rather than an exception; the API
+            # accepts an anonymous context, so rejecting it here would make the SDK
+            # stricter than the service it wraps.
             
             # Check cache first
             cache_key = self._generate_cache_key(flag_key, user_context)
@@ -167,7 +171,7 @@ class VariablyClient:
                 self.metrics.cache_hits += 1
                 self.logger.debug(
                     "Flag evaluation cache hit",
-                    {"flag_key": flag_key, "user_id": user_context["user_id"]},
+                    {"flag_key": flag_key, "user_id": user_context.get("user_id", "")},
                 )
                 cached.cache_hit = True
                 return cached
@@ -176,10 +180,15 @@ class VariablyClient:
             
             # Evaluate via API
             response = self.http_client.evaluate_flag(flag_key, user_context)
-            
+
+            if response.get("reason") == FLAG_NOT_FOUND_REASON:
+                raise FlagNotFoundError(flag_key)
+
+            value = response["value"]
+
             result = FlagResult(
                 key=flag_key,
-                value=response["value"],
+                value=value,
                 reason=response.get("reason", "api_evaluation"),
                 rule_id=response.get("rule_id"),
                 cache_hit=False,
@@ -193,13 +202,17 @@ class VariablyClient:
                 "Flag evaluation successful",
                 {
                     "flag_key": flag_key,
-                    "value": response["value"],
-                    "user_id": user_context["user_id"],
+                    "value": value,
+                    "user_id": user_context.get("user_id", ""),
                 },
             )
             
             return result
         
+        except FlagNotFoundError:
+            # A missing flag is a configuration error and must reach the caller.
+            # Only transient failures below degrade to the default.
+            raise
         except Exception as error:
             self.logger.error(
                 "Flag evaluation failed",
@@ -306,10 +319,10 @@ class VariablyClient:
                 raise ConfigurationError(
                     "Gate key must be a non-empty string", "gate_key"
                 )
-            if not user_context.get("user_id"):
-                raise ConfigurationError(
-                    "User context must include user_id", "user_context.user_id"
-                )
+            # A user id is optional. Server-rendered callers evaluate before a user
+            # is known and expect the flag's default rather than an exception; the API
+            # accepts an anonymous context, so rejecting it here would make the SDK
+            # stricter than the service it wraps.
             
             # Check cache first
             cache_key = self._generate_gate_cache_key(gate_key, user_context)
@@ -318,7 +331,7 @@ class VariablyClient:
                 self.metrics.cache_hits += 1
                 self.logger.debug(
                     "Gate evaluation cache hit",
-                    {"gate_key": gate_key, "user_id": user_context["user_id"]},
+                    {"gate_key": gate_key, "user_id": user_context.get("user_id", "")},
                 )
                 return cached.value
             
@@ -342,8 +355,8 @@ class VariablyClient:
                 "Gate evaluation successful",
                 {
                     "gate_key": gate_key,
-                    "value": response["value"],
-                    "user_id": user_context["user_id"],
+                    "value": value,
+                    "user_id": user_context.get("user_id", ""),
                 },
             )
             
@@ -359,7 +372,67 @@ class VariablyClient:
                 },
             )
             return False  # Default to false for gates
-    
+
+    def evaluate_gates(
+        self, gate_keys: List[str], user_context: UserContext
+    ) -> Dict[str, bool]:
+        """
+        Evaluate multiple feature gates.
+
+        Mirrors the Go SDK's ``EvaluateGates`` so both SDKs expose the same
+        feature-flag surface.
+
+        Args:
+            gate_keys: Feature gate keys
+            user_context: User context for access control
+
+        Returns:
+            Mapping of gate key to whether access is granted. A gate that fails to
+            evaluate is False, matching ``evaluate_gate``.
+        """
+        results: Dict[str, bool] = {}
+        for gate_key in gate_keys:
+            results[gate_key] = self.evaluate_gate(gate_key, user_context)
+        return results
+
+    def all_flags(self, user_context: UserContext) -> Dict[str, FlagResult]:
+        """
+        Evaluate every flag in the project for one user context.
+
+        The caller does not supply flag keys: the server discovers them, so a newly
+        created flag reaches the SDK without a release. This is what a process should
+        call on start-up, and what a server-side renderer should use to build the
+        snapshot it hands to a browser client.
+
+        A flag missing from the result has no definition in this project. Callers
+        should treat that as "unset" rather than False, so a not-yet-created flag is
+        distinguishable from one deliberately turned off.
+        """
+        response = self.http_client.evaluate_all_flags(user_context)
+
+        results: Dict[str, FlagResult] = {}
+        for flag_key, result in (response.get("flags") or {}).items():
+            results[flag_key] = FlagResult(
+                key=flag_key,
+                value=result.get("value"),
+                reason=result.get("reason", "api_evaluation"),
+                rule_id=result.get("rule_id"),
+                variation=result.get("variant_id"),
+                cache_hit=False,
+            )
+        return results
+
+    def validate_flags(
+        self, expected_keys: List[str], user_context: Optional[UserContext] = None
+    ) -> List[str]:
+        """Report which of ``expected_keys`` the project does not define.
+
+        Call this at start-up: it surfaces every missing flag at once, before a
+        request path can hit whichever one happens to be read first.
+        """
+        defined = self.all_flags(user_context or {"user_id": ""})
+        return [key for key in expected_keys if key not in defined]
+
     def track(self, event: Event) -> None:
         """
         Track an analytics event.
@@ -921,7 +994,7 @@ class VariablyClient:
         # Create a stable hash of user context
         context_str = json.dumps(
             {
-                "user_id": user_context["user_id"],
+                "user_id": user_context.get("user_id", ""),
                 "attributes": user_context.get("attributes", {}),
             },
             sort_keys=True,

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/src/variably/config.py

@@ -25,7 +25,9 @@ class VariablyConfig:
         
         Args:
             api_key: API key for authentication
-            base_url: Base URL for the API (default: http://localhost:8080)
+            base_url: Base URL for the API. REQUIRED — no default (e.g. your
+                self-hosted https://api.your-domain.com). Fail-closed by design so
+                evaluation data is never sent to an unintended host.
             environment: Environment name (development, staging, production)
             timeout: Request timeout in milliseconds (default: 5000)
             retry_attempts: Number of retry attempts (default: 3)
@@ -35,9 +37,14 @@ class VariablyConfig:
         """
         if not api_key:
             raise ValueError("API key is required")
-        
+        if not base_url:
+            raise ValueError(
+                "base_url is required — set VARIABLY_BASE_URL to your API endpoint. "
+                "No default, so evaluation data is never sent to an unintended host."
+            )
+
         self.api_key = api_key
-        self.base_url = base_url or "http://localhost:8080"
+        self.base_url = base_url
         self.environment = environment or "development"
         self.timeout = timeout / 1000.0  # Convert to seconds
         self.retry_attempts = retry_attempts

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/src/variably/errors.py

@@ -58,4 +58,22 @@ class ConfigurationError(VariablyError):
     
     def __init__(self, message: str, parameter: str, cause: Exception = None):
         super().__init__(message, cause)
-        self.parameter = parameter
+        self.parameter = parameter
+
+class FlagNotFoundError(VariablyError):
+    """Raised when a flag is not defined in the project.
+
+    This is a configuration error, not a value. Returning the caller's default
+    here would make a typo, an unseeded flag, or a half-finished migration look
+    exactly like a flag that is deliberately off — the application would run on
+    defaults and appear healthy. Network failures are different and still fall
+    back to the default: those are transient, this one is not.
+    """
+
+    def __init__(self, flag_key: str):
+        self.flag_key = flag_key
+        super().__init__(
+            f'Variably: flag "{flag_key}" is not defined in this project. '
+            "Create it, or check the key for a typo — a missing flag is not "
+            'treated as "off".'
+        )

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/src/variably/http_client.py

@@ -31,6 +31,40 @@ from .types import (
 )
 
 
+
+def to_sdk_context(context: UserContext) -> Dict[str, Any]:
+    """Map a UserContext onto the wire shape the API expects.
+
+    UserContext is snake_case (``user_id``) but the API binds camelCase
+    (``userId``). Passing the dict through unmapped drops the user id silently:
+    every evaluation then looks anonymous, so overrides and targeting rules are
+    ignored and the caller gets a plausible-but-wrong answer rather than an error.
+    """
+    mapping = {
+        "user_id": "userId",
+        "email": "email",
+        "country": "country",
+        "language": "language",
+        "platform": "platform",
+        "version": "version",
+        "ip_address": "ipAddress",
+        "user_agent": "userAgent",
+        "session_id": "sessionId",
+    }
+
+    payload: Dict[str, Any] = {}
+    for snake, camel in mapping.items():
+        value = context.get(snake)
+        if value:
+            payload[camel] = value
+
+    attributes = context.get("attributes")
+    if attributes:
+        payload["attributes"] = attributes
+
+    return payload
+
+
 class HTTPClient:
     """HTTP client for Variably API with retry logic and error handling."""
     
@@ -69,7 +103,7 @@ class HTTPClient:
         """Evaluate a single feature flag."""
         request_data: FlagEvaluationRequest = {
             "flag_key": flag_key,
-            "context": context,
+            "context": to_sdk_context(context),
         }
         
         response = self._make_request(
@@ -87,7 +121,7 @@ class HTTPClient:
         """Evaluate multiple feature flags in batch."""
         request_data: BatchFlagEvaluationRequest = {
             "flag_keys": flag_keys,
-            "context": context,
+            "context": to_sdk_context(context),
         }
         
         response = self._make_request(
@@ -99,11 +133,24 @@ class HTTPClient:
         
         return response
     
+    def evaluate_all_flags(self, context: UserContext) -> Dict[str, Any]:
+        """Evaluate every flag in the project for one context.
+
+        No flag keys are sent: the server discovers them, so a newly created flag
+        reaches the SDK without a client release.
+        """
+        return self._make_request(
+            "POST",
+            "/api/v1/sdk/evaluate/all",
+            json={"context": to_sdk_context(context)},
+            retryable=True,
+        )
+
     def evaluate_gate(self, gate_key: str, context: UserContext) -> GateEvaluationResponse:
         """Evaluate a feature gate."""
         request_data: GateEvaluationRequest = {
             "gate_key": gate_key,
-            "context": context,
+            "context": to_sdk_context(context),
         }
         
         response = self._make_request(

{variably_sdk-2.12.0 → variably_sdk-2.13.0}/src/variably/integrations/__init__.py

@@ -6,10 +6,17 @@ deterministic cross-step evaluation with little or no per-node code:
     from variably.integrations.langgraph import instrument
     instrument(graph, session_id_key="session_id")
 
+    from variably.integrations.adk import VariablyPlugin      # Google ADK / Agent Engine
+    Runner(agent=root_agent, ..., plugins=[VariablyPlugin()])
+
+    from variably.integrations.otel import instrument         # any OpenTelemetry tracing
+    instrument()
+
 Each integration maps the framework's node/agent identity to ``agent_name``,
 detects the terminal node(s) as ``is_aggregator``, pulls session id + context
 from the framework's state, and logs via ``variably.observe`` — always
 best-effort, never raising into the customer's workflow.
 
-Install extras per framework, e.g. ``pip install variably-sdk[langgraph]``.
+Install extras per framework, e.g. ``pip install variably-sdk[langgraph]`` or
+``pip install "variably-sdk[adk]"`` or ``pip install "variably-sdk[otel]"``.
 """