stkai 0.2.5__tar.gz → 0.3.0__tar.gz

{stkai-0.2.5/src/stkai.egg-info → stkai-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stkai
-Version: 0.2.5
+Version: 0.3.0
 Summary: Python SDK for StackSpot AI - Remote Quick Commands and more
 Author-email: Rafael Ponte <rponte@gmail.com>
 License: Apache-2.0

{stkai-0.2.5 → stkai-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stkai"
-version = "0.2.5"
+version = "0.3.0"
 description = "Python SDK for StackSpot AI - Remote Quick Commands and more"
 readme = "README.md"
 license = {text = "Apache-2.0"}

{stkai-0.2.5 → stkai-0.3.0}/src/stkai/__init__.py

@@ -80,6 +80,7 @@ from stkai._config import (
     STKAI,
     AgentConfig,
     AuthConfig,
+    ConfigEntry,
     RateLimitConfig,
     RateLimitStrategy,
     RqcConfig,
@@ -113,6 +114,7 @@ __all__ = [
     # Configuration
     "STKAI",
     "STKAIConfig",
+    "ConfigEntry",
     "AuthConfig",
     "RqcConfig",
     "AgentConfig",

stkai-0.3.0/src/stkai/_cli.py

@@ -0,0 +1,53 @@
+"""
+StackSpot CLI (oscli) integration.
+
+This module provides an abstraction layer for interacting with the StackSpot CLI,
+allowing the SDK to detect CLI mode and retrieve CLI-specific configuration.
+"""
+
+from __future__ import annotations
+
+
+class StkCLI:
+    """
+    Abstraction for StackSpot CLI (oscli) integration.
+
+    Provides methods to:
+    - Check if running in CLI mode (oscli available)
+    - Retrieve CLI-specific configuration values
+
+    Example:
+        >>> if StkCLI.is_available():
+        ...     base_url = StkCLI.get_codebuddy_base_url()
+    """
+
+    @staticmethod
+    def is_available() -> bool:
+        """
+        Check if StackSpot CLI (oscli) is available.
+
+        Returns:
+            True if oscli can be imported (CLI mode), False otherwise.
+        """
+        try:
+            import oscli  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    @staticmethod
+    def get_codebuddy_base_url() -> str | None:
+        """
+        Get CodeBuddy base URL from CLI if available.
+
+        Returns:
+            The CLI's __codebuddy_base_url__ if oscli is installed
+            and the attribute exists, None otherwise.
+        """
+        try:
+            from oscli import __codebuddy_base_url__
+
+            return __codebuddy_base_url__ if __codebuddy_base_url__ else None
+        except (ImportError, AttributeError):
+            return None

{stkai-0.2.5 → stkai-0.3.0}/src/stkai/_config.py

@@ -7,9 +7,10 @@ If not called, sensible defaults are used.
 
 Hierarchy of precedence (highest to lowest):
 1. *Options passed to client constructors
-2. Environment variables (STKAI_*) - when allow_env_override=True
-3. Values set via STKAI.configure()
-4. Hardcoded defaults (in dataclass fields)
+2. Values set via STKAI.configure()
+3. StackSpot CLI values (oscli) - if CLI is available
+4. Environment variables (STKAI_*) - when allow_env_override=True
+5. Hardcoded defaults (in dataclass fields)
 
 Example:
     >>> from stkai import STKAI
@@ -27,7 +28,9 @@ Example:
 from __future__ import annotations
 
 import os
+from collections.abc import Callable
 from dataclasses import dataclass, field, fields, replace
+from functools import wraps
 from typing import Any, Literal, Self
 
 # Type alias for rate limit strategies
@@ -330,6 +333,234 @@ class RateLimitConfig(OverridableConfig):
         return super().with_overrides(processed, allow_none_fields=merged_allow_none)
 
 
+@dataclass(frozen=True)
+class ConfigEntry:
+    """
+    A configuration field with its resolved value and source.
+
+    Represents a single configuration entry with metadata about where
+    the value came from. Used by explain_data() for structured output.
+
+    Attributes:
+        name: The field name (e.g., "request_timeout").
+        value: The resolved value.
+        source: Where the value came from:
+            - "default": Hardcoded default value
+            - "env:VAR_NAME": Environment variable
+            - "CLI": StackSpot CLI (oscli)
+            - "configure": Set via STKAI.configure()
+
+    Example:
+        >>> entry = ConfigEntry("request_timeout", 60, "configure")
+        >>> entry.name
+        'request_timeout'
+        >>> entry.value
+        60
+        >>> entry.source
+        'configure'
+        >>> entry.formatted_value
+        '60'
+    """
+
+    name: str
+    value: Any
+    source: str
+
+    @property
+    def formatted_value(self) -> str:
+        """
+        Return value formatted for display.
+
+        Masks sensitive fields (e.g., client_secret) showing only
+        first and last 4 characters, and truncates long strings.
+
+        Returns:
+            Formatted string representation of the value.
+
+        Examples:
+            >>> ConfigEntry("client_secret", "super-secret-key", "configure").formatted_value
+            'supe********-key'
+            >>> ConfigEntry("client_secret", "short", "configure").formatted_value
+            '********t'
+        """
+        # Mask sensitive fields
+        if self.name in ("client_secret",) and self.value is not None:
+            secret = str(self.value)
+            # Long secrets: show first 4 and last 4 chars
+            if len(secret) >= 12:
+                return f"{secret[:4]}********{secret[-4:]}"
+            # Short secrets: show last 1/3 of chars
+            if len(secret) >= 3:
+                visible = max(1, len(secret) // 3)
+                return f"********{secret[-visible:]}"
+            return "********"
+
+        # Handle None
+        if self.value is None:
+            return "None"
+
+        # Convert to string and truncate if needed
+        str_value = str(self.value)
+        max_length = 50
+        if len(str_value) > max_length:
+            return str_value[: max_length - 3] + "..."
+
+        return str_value
+
+
+@dataclass(frozen=True)
+class STKAIConfigTracker:
+    """
+    Tracks the source of config field values.
+
+    An immutable tracker that records where each configuration value came from
+    (default, env var, CLI, or configure()). Used internally by STKAIConfig
+    for debugging via STKAI.explain().
+
+    Attributes:
+        sources: Dict tracking source of each field value.
+            Structure: {"section": {"field": "source"}}
+            Source values: "default", "env:VAR_NAME", "CLI", "configure"
+
+    Example:
+        >>> tracker = STKAIConfigTracker()
+        >>> tracker = tracker.with_changes_tracked(old_cfg, new_cfg, "env")
+        >>> tracker.sources.get("rqc", {}).get("request_timeout")
+        'env:STKAI_RQC_REQUEST_TIMEOUT'
+    """
+
+    sources: dict[str, dict[str, str]] = field(default_factory=dict)
+
+    @staticmethod
+    def track_changes(
+        source_type: str,
+    ) -> Callable[[Callable[..., STKAIConfig]], Callable[..., STKAIConfig]]:
+        """
+        Decorator that tracks config changes made by the decorated method.
+
+        Wraps methods that return a new STKAIConfig, automatically detecting
+        changes between the original config (self) and the returned config,
+        then recording those changes in the tracker.
+
+        Args:
+            source_type: Source label for tracking ("env", "CLI", or "configure").
+
+        Returns:
+            Decorator function that wraps the method.
+
+        Example:
+            >>> @STKAIConfigTracker.track_changes("env")
+            ... def with_env_vars(self) -> STKAIConfig:
+            ...     return STKAIConfig(...)
+        """
+
+        def decorator(
+            method: Callable[..., STKAIConfig],
+        ) -> Callable[..., STKAIConfig]:
+            @wraps(method)
+            def wrapper(self: STKAIConfig, *args: Any, **kwargs: Any) -> STKAIConfig:
+                new_config = method(self, *args, **kwargs)
+                new_tracker = self._tracker.with_changes_tracked(
+                    self, new_config, source_type
+                )
+                return replace(new_config, _tracker=new_tracker)
+
+            return wrapper
+
+        return decorator
+
+    def with_changes_tracked(
+        self,
+        old_config: STKAIConfig,
+        new_config: STKAIConfig,
+        source_type: str,
+    ) -> STKAIConfigTracker:
+        """
+        Return new tracker with changes between configs tracked.
+
+        Compares old and new configs, detects changed fields, and returns
+        a new tracker with those changes recorded.
+
+        Args:
+            old_config: The config before changes.
+            new_config: The config after changes.
+            source_type: Source label ("env", "CLI", or "configure").
+
+        Returns:
+            New STKAIConfigTracker with detected changes tracked.
+        """
+        changes = self._detect_changes(old_config, new_config)
+        new_sources = self._merge_sources(changes, source_type)
+        return STKAIConfigTracker(sources=new_sources)
+
+    def _detect_changes(
+        self,
+        old_config: STKAIConfig,
+        new_config: STKAIConfig,
+    ) -> dict[str, list[str]]:
+        """
+        Detect which fields changed between two configs.
+
+        Args:
+            old_config: The config before changes.
+            new_config: The config after changes.
+
+        Returns:
+            Dict mapping section names to lists of changed field names.
+            Example: {"rqc": ["request_timeout", "base_url"]}
+        """
+        changes: dict[str, list[str]] = {}
+
+        for section_name in ("auth", "rqc", "agent", "rate_limit"):
+            old_section = getattr(old_config, section_name)
+            new_section = getattr(new_config, section_name)
+
+            changed_fields = []
+            for f in fields(old_section):
+                old_val = getattr(old_section, f.name)
+                new_val = getattr(new_section, f.name)
+                if old_val != new_val:
+                    changed_fields.append(f.name)
+
+            if changed_fields:
+                changes[section_name] = changed_fields
+
+        return changes
+
+    def _merge_sources(
+        self,
+        changes: dict[str, list[str]],
+        source_type: str,
+    ) -> dict[str, dict[str, str]]:
+        """
+        Merge detected changes into existing sources.
+
+        Args:
+            changes: Dict of section -> list of changed field names.
+            source_type: Source label ("env", "CLI", or "configure").
+
+        Returns:
+            New sources dict with changes merged in.
+        """
+        new_sources = self._copy_sources()
+
+        for section, field_names in changes.items():
+            section_sources = new_sources.setdefault(section, {})
+            for field_name in field_names:
+                if source_type == "env":
+                    # Generate env var name based on convention
+                    env_var = f"STKAI_{section.upper()}_{field_name.upper()}"
+                    section_sources[field_name] = f"env:{env_var}"
+                else:
+                    section_sources[field_name] = source_type
+
+        return new_sources
+
+    def _copy_sources(self) -> dict[str, dict[str, str]]:
+        """Create a deep copy of current sources."""
+        return {section: dict(flds) for section, flds in self.sources.items()}
+
+
 @dataclass(frozen=True)
 class STKAIConfig:
     """
@@ -358,7 +589,9 @@ class STKAIConfig:
     rqc: RqcConfig = field(default_factory=RqcConfig)
     agent: AgentConfig = field(default_factory=AgentConfig)
     rate_limit: RateLimitConfig = field(default_factory=RateLimitConfig)
+    _tracker: STKAIConfigTracker = field(default_factory=STKAIConfigTracker, repr=False)
 
+    @STKAIConfigTracker.track_changes("env")
     def with_env_vars(self) -> STKAIConfig:
         """
         Return a new config with environment variables applied on top.
@@ -382,6 +615,106 @@ class STKAIConfig:
             rate_limit=self.rate_limit.with_overrides(_get_rate_limit_from_env()),
         )
 
+    @STKAIConfigTracker.track_changes("CLI")
+    def with_cli_defaults(self) -> STKAIConfig:
+        """
+        Return a new config with CLI-provided values applied.
+
+        CLI values take precedence over env vars. When running in CLI mode,
+        the CLI knows the correct endpoints for the current environment.
+
+        Returns:
+            New STKAIConfig instance with CLI values applied.
+
+        Example:
+            >>> # Apply CLI defaults on top of env vars
+            >>> config = STKAIConfig().with_env_vars().with_cli_defaults()
+        """
+        from stkai._cli import StkCLI
+
+        cli_rqc_overrides: dict[str, Any] = {}
+        if cli_base_url := StkCLI.get_codebuddy_base_url():
+            cli_rqc_overrides["base_url"] = cli_base_url
+
+        return STKAIConfig(
+            auth=self.auth,
+            rqc=self.rqc.with_overrides(cli_rqc_overrides),
+            agent=self.agent,
+            rate_limit=self.rate_limit,
+        )
+
+    @STKAIConfigTracker.track_changes("user")
+    def with_section_overrides(
+        self,
+        *,
+        auth: dict[str, Any] | None = None,
+        rqc: dict[str, Any] | None = None,
+        agent: dict[str, Any] | None = None,
+        rate_limit: dict[str, Any] | None = None,
+    ) -> STKAIConfig:
+        """
+        Return a new config with overrides applied to nested sections.
+
+        Each section dict is merged with the existing section config,
+        only overriding the specified fields.
+
+        Args:
+            auth: Authentication config overrides.
+            rqc: RemoteQuickCommand config overrides.
+            agent: Agent config overrides.
+            rate_limit: Rate limiting config overrides.
+
+        Returns:
+            New STKAIConfig instance with overrides applied.
+
+        Example:
+            >>> config = STKAIConfig()
+            >>> custom = config.with_section_overrides(
+            ...     rqc={"request_timeout": 60},
+            ...     agent={"request_timeout": 120},
+            ... )
+        """
+        return STKAIConfig(
+            auth=self.auth.with_overrides(auth or {}),
+            rqc=self.rqc.with_overrides(rqc or {}),
+            agent=self.agent.with_overrides(agent or {}),
+            rate_limit=self.rate_limit.with_overrides(rate_limit or {}),
+        )
+
+    def explain_data(self) -> dict[str, list[ConfigEntry]]:
+        """
+        Return config data structured for explain output.
+
+        Provides a structured representation of all config values and their
+        sources, useful for debugging, testing, or custom formatting.
+
+        Returns:
+            Dict mapping section names to list of ConfigEntry objects.
+
+        Example:
+            >>> config = STKAIConfig().with_env_vars()
+            >>> data = config.explain_data()
+            >>> for entry in data["rqc"]:
+            ...     print(f"{entry.name}: {entry.value} ({entry.source})")
+            request_timeout: 30 (default)
+            ...
+        """
+        result: dict[str, list[ConfigEntry]] = {}
+
+        for section_name in ("auth", "rqc", "agent", "rate_limit"):
+            section_config = getattr(self, section_name)
+            section_sources = self._tracker.sources.get(section_name, {})
+            result[section_name] = [
+                ConfigEntry(
+                    name=f.name,
+                    value=getattr(section_config, f.name),
+                    source=section_sources.get(f.name, "default"),
+                )
+                for f in fields(section_config)
+            ]
+
+        return result
+
 
 # =============================================================================
 # Environment Variable Helpers
@@ -488,8 +821,8 @@ class _STKAI:
     """
 
     def __init__(self) -> None:
-        """Initialize with defaults and apply environment variables."""
-        self._config: STKAIConfig = STKAIConfig().with_env_vars()
+        """Initialize with defaults, environment variables, and CLI values."""
+        self._config: STKAIConfig = STKAIConfig().with_env_vars().with_cli_defaults()
 
     def configure(
         self,
@@ -499,6 +832,7 @@ class _STKAI:
         agent: dict[str, Any] | None = None,
         rate_limit: dict[str, Any] | None = None,
         allow_env_override: bool = True,
+        allow_cli_override: bool = True,
     ) -> STKAIConfig:
         """
         Configure SDK settings.
@@ -513,6 +847,8 @@ class _STKAI:
             rate_limit: Rate limiting config overrides (enabled, strategy, max_requests, etc.).
             allow_env_override: If True (default), env vars are used as fallback
                 for fields NOT provided. If False, ignores env vars entirely.
+            allow_cli_override: If True (default), CLI values (oscli) are used as fallback
+                for fields NOT provided. If False, ignores CLI values entirely.
 
         Returns:
             The configured STKAIConfig instance.
@@ -520,11 +856,14 @@ class _STKAI:
         Raises:
             ValueError: If any dict contains unknown field names.
 
-        Precedence (allow_env_override=True):
+        Precedence (both overrides True):
+            STKAI.configure() > CLI values > ENV vars > defaults
+
+        Precedence (allow_cli_override=False):
             STKAI.configure() > ENV vars > defaults
 
         Precedence (allow_env_override=False):
-            STKAI.configure() > defaults
+            STKAI.configure() > CLI values > defaults
 
         Example:
             >>> from stkai import STKAI
@@ -534,17 +873,19 @@ class _STKAI:
             ...     rate_limit={"enabled": True, "max_requests": 10},
             ... )
         """
-        # Start with defaults, apply env vars as base layer (if enabled)
-        base = STKAIConfig()  # only defaults
+        # Start with defaults, apply env vars and CLI values as base layer
+        base = STKAIConfig()
         if allow_env_override:
             base = base.with_env_vars()  # defaults + env vars
+        if allow_cli_override:
+            base = base.with_cli_defaults()  # CLI values take precedence over env vars
 
         # Apply user overrides on top - configure() always wins
-        self._config = STKAIConfig(
-            auth=base.auth.with_overrides(auth or {}),
-            rqc=base.rqc.with_overrides(rqc or {}),
-            agent=base.agent.with_overrides(agent or {}),
-            rate_limit=base.rate_limit.with_overrides(rate_limit or {}),
+        self._config = base.with_section_overrides(
+            auth=auth,
+            rqc=rqc,
+            agent=agent,
+            rate_limit=rate_limit,
         )
 
         return self._config
@@ -566,7 +907,7 @@ class _STKAI:
 
     def reset(self) -> STKAIConfig:
         """
-        Reset configuration to defaults + env vars.
+        Reset configuration to defaults + env vars + CLI values.
 
         Useful for testing to ensure clean state between tests.
 
@@ -577,9 +918,63 @@ class _STKAI:
             >>> from stkai import STKAI
             >>> STKAI.reset()
         """
-        self._config = STKAIConfig().with_env_vars()
+        self._config = STKAIConfig().with_env_vars().with_cli_defaults()
         return self._config
 
+    def explain(
+        self,
+        output: Callable[[str], None] = print,
+    ) -> None:
+        """
+        Print current configuration with sources.
+
+        Useful for debugging and troubleshooting configuration issues.
+        Shows each config value and where it came from:
+
+        - "default": Using hardcoded default value
+        - "env:VAR_NAME": Value from environment variable
+        - "CLI": Value from StackSpot CLI (oscli)
+        - "configure": Value set via STKAI.configure()
+
+        Args:
+            output: Callable to output each line. Defaults to print.
+                    Can be used with logging: `STKAI.explain(logger.info)`
+
+        Example:
+            >>> from stkai import STKAI
+            >>> STKAI.explain()
+            STKAI Configuration:
+            ====================
+            [rqc]
+              base_url .......... https://example.com (CLI)
+              request_timeout ... 60 (configure)
+            ...
+
+            >>> # Using with logging
+            >>> import logging
+            >>> STKAI.explain(logging.info)
+        """
+        name_width = 25  # field name + dots
+        value_width = 50  # max value width (matches truncation)
+        total_width = 2 + name_width + 2 + (value_width + 2) + 1 + 8  # matches separator
+
+        output("STKAI Configuration:")
+        output("=" * total_width)
+
+        # Header
+        output(f"  {'Field':<{name_width}} │ {'Value':<{value_width}} │ Source")
+        output(f"--{'-' * name_width}-+{'-' * (value_width + 2)}+--------")
+
+        for section_name, entries in self._config.explain_data().items():
+            output(f"[{section_name}]")
+            for entry in entries:
+                dots = "." * (name_width - len(entry.name))
+                value_padded = entry.formatted_value.ljust(value_width)
+                marker = "✎" if entry.source != "default" else " "
+                output(f"  {entry.name} {dots} {value_padded} {marker} {entry.source}")
+
+        output("=" * total_width)
+
     def __repr__(self) -> str:
         return f"STKAI(config={self._config!r})"
 

{stkai-0.2.5 → stkai-0.3.0}/src/stkai/_http.py

@@ -209,6 +209,7 @@ class StkCLIHttpClient(HttpClient):
             url=url,
             timeout=timeout,
             headers=headers,
+            use_cache=False, # disables client-side caching
         )
         return response
 
@@ -469,6 +470,14 @@ class EnvironmentAwareHttpClient(HttpClient):
                 "EnvironmentAwareHttpClient: StackSpot CLI (oscli) detected. "
                 "Using StkCLIHttpClient."
             )
+            # Warn if credentials are also configured (they will be ignored)
+            from stkai._config import STKAI
+
+            if STKAI.config.auth.has_credentials():
+                logger.warning(
+                    "⚠️ Auth credentials detected (via env vars or configure) but running in CLI mode. "
+                    "Authentication will be handled by oscli. Credentials will be ignored."
+                )
             return StkCLIHttpClient()
 
         # 2. Try standalone with credentials
@@ -556,12 +565,9 @@ class EnvironmentAwareHttpClient(HttpClient):
         Returns:
             True if oscli can be imported, False otherwise.
         """
-        try:
-            import oscli  # noqa: F401
+        from stkai._cli import StkCLI
 
-            return True
-        except ImportError:
-            return False
+        return StkCLI.is_available()
 
     @override
     def get(

{stkai-0.2.5 → stkai-0.3.0}/src/stkai/rqc/_remote_quick_command.py

@@ -578,8 +578,6 @@ class RemoteQuickCommand:
         assert context is not None, "🌀 Sanity check | Event context not provided to polling phase."
         assert request.execution_id, "🌀 Sanity check | Execution ID not provided to polling phase."
 
-        import random
-
         # Get options and assert for type narrowing
         opts = self.options.get_result
         assert opts is not None
@@ -591,14 +589,6 @@ class RemoteQuickCommand:
         start_time = time.time()
         execution_id = request.execution_id
 
-        # Build full URL using base_url
-        nocache_param = random.randint(0, 1000000)
-        url = f"{self.base_url}/v1/quick-commands/callback/{execution_id}?nocache={nocache_param}"
-        no_cache_headers = {
-            "Cache-Control": "no-cache, no-store",
-            "Pragma": "no-cache",
-        }
-
         last_status: RqcExecutionStatus = RqcExecutionStatus.CREATED  # Starts at CREATED since we notify PENDING → CREATED before polling
         created_since: float | None = None
 
@@ -614,8 +604,17 @@ class RemoteQuickCommand:
                     )
 
                 try:
+                    # Build full URL using base_url and prevents client-side caching
+                    import uuid
+                    nocache_param = str(uuid.uuid4())
+                    url = f"{self.base_url}/v1/quick-commands/callback/{execution_id}?nocache={nocache_param}"
+                    nocache_headers = {
+                        "Cache-Control": "no-cache, no-store",
+                        "Pragma": "no-cache",
+                    }
+
                     response = self.http_client.get(
-                        url=url, headers=no_cache_headers, timeout=opts.request_timeout
+                        url=url, headers=nocache_headers, timeout=opts.request_timeout
                     )
                     assert isinstance(response, requests.Response), \
                         f"🌀 Sanity check | Object returned by `get` method is not an instance of `requests.Response`. ({response.__class__})"

{stkai-0.2.5 → stkai-0.3.0/src/stkai.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stkai
-Version: 0.2.5
+Version: 0.3.0
 Summary: Python SDK for StackSpot AI - Remote Quick Commands and more
 Author-email: Rafael Ponte <rponte@gmail.com>
 License: Apache-2.0