stkai 0.2.5__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stkai
-Version: 0.2.5
+Version: 0.3.2
 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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stkai"
-version = "0.2.5"
+version = "0.3.2"
 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.2}/src/stkai/__init__.py

@@ -80,9 +80,11 @@ from stkai._config import (
     STKAI,
     AgentConfig,
     AuthConfig,
+    ConfigEntry,
     RateLimitConfig,
     RateLimitStrategy,
     RqcConfig,
+    SdkConfig,
     STKAIConfig,
 )
 from stkai._http import (
@@ -113,6 +115,8 @@ __all__ = [
     # Configuration
     "STKAI",
     "STKAIConfig",
+    "SdkConfig",
+    "ConfigEntry",
     "AuthConfig",
     "RqcConfig",
     "AgentConfig",

stkai-0.3.2/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.2}/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
@@ -100,6 +103,46 @@ class OverridableConfig:
 # =============================================================================
 
 
+@dataclass(frozen=True)
+class SdkConfig:
+    """
+    SDK metadata (read-only, not configurable).
+
+    Provides information about the SDK version and runtime environment.
+    These values are automatically detected and cannot be overridden.
+
+    Attributes:
+        version: The installed SDK version.
+        cli_mode: Whether StackSpot CLI (oscli) is available.
+
+    Example:
+        >>> from stkai import STKAI
+        >>> STKAI.config.sdk.version
+        '0.2.8'
+        >>> STKAI.config.sdk.cli_mode
+        True
+    """
+
+    version: str
+    cli_mode: bool
+
+    @classmethod
+    def detect(cls) -> SdkConfig:
+        """
+        Detect SDK metadata from the runtime environment.
+
+        Returns:
+            SdkConfig with version and cli_mode auto-detected.
+        """
+        from stkai import __version__
+        from stkai._cli import StkCLI
+
+        return cls(
+            version=__version__,
+            cli_mode=StkCLI.is_available(),
+        )
+
+
 @dataclass(frozen=True)
 class AuthConfig(OverridableConfig):
     """
@@ -330,15 +373,244 @@ 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:
     """
     Global configuration for the stkai SDK.
 
-    Aggregates all configuration sections: auth, rqc, agent, and rate_limit.
+    Aggregates all configuration sections: sdk, auth, rqc, agent, and rate_limit.
     Access via the global `STKAI.config` property.
 
     Attributes:
+        sdk: SDK metadata (version, cli_mode). Read-only.
         auth: Authentication configuration.
         rqc: RemoteQuickCommand configuration.
         agent: Agent configuration.
@@ -346,6 +618,10 @@ class STKAIConfig:
 
     Example:
         >>> from stkai import STKAI
+        >>> STKAI.config.sdk.version
+        '0.2.8'
+        >>> STKAI.config.sdk.cli_mode
+        True
         >>> STKAI.config.rqc.request_timeout
         30
         >>> STKAI.config.auth.has_credentials()
@@ -354,11 +630,14 @@ class STKAIConfig:
         False
     """
 
+    sdk: SdkConfig = field(default_factory=SdkConfig.detect)
     auth: AuthConfig = field(default_factory=AuthConfig)
     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.
@@ -376,12 +655,121 @@ class STKAIConfig:
             >>> final = custom.with_env_vars()
         """
         return STKAIConfig(
+            sdk=self.sdk,
             auth=self.auth.with_overrides(_get_auth_from_env()),
             rqc=self.rqc.with_overrides(_get_rqc_from_env()),
             agent=self.agent.with_overrides(_get_agent_from_env()),
             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(
+            sdk=self.sdk,
+            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(
+            sdk=self.sdk,
+            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]] = {}
+
+        # SDK section (read-only, not tracked)
+        result["sdk"] = [
+            ConfigEntry(name=f.name, value=getattr(self.sdk, f.name), source="-")
+            for f in fields(self.sdk)
+        ]
+
+        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 +876,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 +887,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 +902,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 +911,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 +928,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 +962,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 +973,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 not in ("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})"