pyrestkit 1.2.0__py3-none-any.whl

pyrestkit/__init__.py

@@ -0,0 +1,35 @@
+"""
+PyRestKit
+
+Modern Python REST API Automation Toolkit.
+"""
+
+from pyrestkit.auth.strategies.api_key_auth import ApiKeyAuth
+from pyrestkit.auth.strategies.basic_auth import BasicAuth
+from pyrestkit.auth.strategies.bearer_auth import BearerAuth
+from pyrestkit.clients.user_client import UserClient
+from pyrestkit.config.config import ConfigManager
+from pyrestkit.core.api_client import APIClient
+from pyrestkit.core.session_manager import SessionManager
+from pyrestkit.factories.user_factory import UserFactory
+from pyrestkit.models.request.create_user_request import CreateUserRequest
+from pyrestkit.models.request.update_user_request import UpdateUserRequest
+from pyrestkit.validators.response_validator import ResponseValidator
+from pyrestkit.validators.schema_validator import SchemaValidator
+
+__version__ = "1.2.0"
+
+__all__ = [
+    "APIClient",
+    "SessionManager",
+    "ConfigManager",
+    "BearerAuth",
+    "BasicAuth",
+    "ApiKeyAuth",
+    "UserClient",
+    "CreateUserRequest",
+    "UpdateUserRequest",
+    "ResponseValidator",
+    "SchemaValidator",
+    "UserFactory",
+]

pyrestkit/ai/__init__.py

@@ -0,0 +1,17 @@
+from pyrestkit.ai.analyzer import FailureAnalyzer, parse_failure_analysis
+from pyrestkit.ai.client import AIClient, available_providers, register_provider
+from pyrestkit.ai.config import AIConfig
+from pyrestkit.ai.models import FailureAnalysis, FailureContext
+from pyrestkit.ai.provider import AIProvider
+
+__all__ = [
+    "AIClient",
+    "AIConfig",
+    "AIProvider",
+    "FailureAnalysis",
+    "FailureAnalyzer",
+    "FailureContext",
+    "available_providers",
+    "parse_failure_analysis",
+    "register_provider",
+]

pyrestkit/ai/analyzer.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pyrestkit.ai.client import AIClient
+from pyrestkit.ai.models import FailureAnalysis, FailureContext
+from pyrestkit.ai.utils.prompt_loader import PromptLoader
+
+FAILURE_ANALYZER_SYSTEM_PROMPT = (
+    "You are an expert Python API automation engineer. "
+    "Return concise, actionable failure analysis as JSON only."
+)
+
+
+class FailureAnalyzer:
+    """
+    Generates structured analysis and fix suggestions for test failures.
+    """
+
+    def __init__(
+        self,
+        client: AIClient,
+        prompt_loader: PromptLoader | None = None,
+    ) -> None:
+        self._client = client
+        self._prompt_loader = prompt_loader or PromptLoader.default()
+
+    def build_prompt(
+        self,
+        context: FailureContext,
+    ) -> str:
+        return self._prompt_loader.render(
+            "failure_analysis.md",
+            context=json.dumps(
+                context.to_dict(),
+                indent=2,
+                sort_keys=True,
+            ),
+        )
+
+    def analyze(
+        self,
+        context: FailureContext,
+    ) -> FailureAnalysis:
+        raw_response = self._client.complete(
+            self.build_prompt(context),
+            system_prompt=FAILURE_ANALYZER_SYSTEM_PROMPT,
+        )
+
+        return parse_failure_analysis(raw_response)
+
+
+def parse_failure_analysis(
+    raw_response: str,
+) -> FailureAnalysis:
+    try:
+        data = json.loads(_extract_json(raw_response))
+    except (json.JSONDecodeError, ValueError):
+        return FailureAnalysis(
+            summary=raw_response.strip(),
+            likely_cause="",
+            recommended_fix="",
+            raw_response=raw_response,
+        )
+
+    if not isinstance(data, dict):
+        return FailureAnalysis(
+            summary=str(data).strip(),
+            likely_cause="",
+            recommended_fix="",
+            raw_response=raw_response,
+        )
+
+    return FailureAnalysis(
+        summary=str(data.get("summary", "")).strip(),
+        likely_cause=str(data.get("likely_cause", "")).strip(),
+        recommended_fix=str(data.get("recommended_fix", "")).strip(),
+        suggested_patch=_optional_text(data.get("suggested_patch")),
+        confidence=_confidence(data.get("confidence", 0.0)),
+        raw_response=raw_response,
+    )
+
+
+def _extract_json(
+    value: str,
+) -> str:
+    text = value.strip()
+
+    if text.startswith("```"):
+        lines = text.splitlines()
+
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+
+        if lines and lines[-1].startswith("```"):
+            lines = lines[:-1]
+
+        text = "\n".join(lines).strip()
+
+    if text.startswith("{") and text.endswith("}"):
+        return text
+
+    start = text.find("{")
+    end = text.rfind("}")
+
+    if start == -1 or end == -1 or end <= start:
+        raise ValueError("No JSON object found.")
+
+    return text[start : end + 1]
+
+
+def _optional_text(
+    value: Any,
+) -> str | None:
+    if value is None:
+        return None
+
+    text = str(value).strip()
+    return text or None
+
+
+def _confidence(
+    value: Any,
+) -> float:
+    try:
+        confidence = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+    if confidence < 0.0:
+        return 0.0
+
+    if confidence > 1.0:
+        return 1.0
+
+    return confidence

pyrestkit/ai/client.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pyrestkit.ai.config import AIConfig
+from pyrestkit.ai.exceptions import AIConfigurationError
+from pyrestkit.ai.provider import AIProvider
+from pyrestkit.ai.providers import (
+    AnthropicProvider,
+    AzureOpenAIProvider,
+    BedrockProvider,
+    CohereProvider,
+    GeminiProvider,
+    GroqProvider,
+    MistralProvider,
+    OllamaProvider,
+    OpenAIResponsesProvider,
+)
+
+ProviderFactory = Callable[[], AIProvider]
+
+_PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
+    "openai": OpenAIResponsesProvider,
+    "ollama": OllamaProvider,
+    "anthropic": AnthropicProvider,
+    "gemini": GeminiProvider,
+    "azure-openai": AzureOpenAIProvider,
+    "azure_openai": AzureOpenAIProvider,
+    "cohere": CohereProvider,
+    "mistral": MistralProvider,
+    "groq": GroqProvider,
+    "bedrock": BedrockProvider,
+}
+
+
+class AIClient:
+    """
+    Small facade that keeps framework code independent from provider details.
+    """
+
+    def __init__(
+        self,
+        config: AIConfig,
+        provider: AIProvider | None = None,
+    ) -> None:
+        self._config = config
+        self._provider = provider or create_provider(config.provider)
+
+    @property
+    def config(self) -> AIConfig:
+        return self._config
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        system_prompt: str | None = None,
+    ) -> str:
+        if not prompt.strip():
+            raise ValueError("Prompt cannot be empty.")
+
+        return self._provider.complete(
+            prompt,
+            config=self._config,
+            system_prompt=system_prompt,
+        )
+
+
+def create_provider(
+    provider_name: str,
+) -> AIProvider:
+    provider = provider_name.strip().lower()
+
+    if not provider:
+        raise AIConfigurationError("AI provider name cannot be empty.")
+
+    factory = _PROVIDER_FACTORIES.get(provider)
+
+    if factory is None:
+        raise AIConfigurationError(
+            f"No AI provider registered for '{provider_name}'. "
+            "Install the provider package or register a custom provider."
+        )
+
+    return factory()
+
+
+def register_provider(
+    provider_name: str,
+    factory: ProviderFactory,
+) -> None:
+    provider = provider_name.strip().lower()
+
+    if not provider:
+        raise AIConfigurationError("AI provider name cannot be empty.")
+
+    _PROVIDER_FACTORIES[provider] = factory
+
+
+def available_providers() -> tuple[str, ...]:
+    return tuple(sorted(_PROVIDER_FACTORIES))

pyrestkit/ai/config/__init__.py

@@ -0,0 +1,5 @@
+from pyrestkit.ai.config.ai_config import AIConfig
+
+__all__ = [
+    "AIConfig",
+]

pyrestkit/ai/config/ai_config.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class AIConfig:
+    """
+    Provider-agnostic configuration for AI integrations.
+    """
+
+    provider: str
+    model: str
+
+    api_key: str | None = None
+    base_url: str | None = None
+
+    temperature: float = 0.2
+    max_tokens: int | None = None
+
+    timeout: int = 60
+
+    organization: str | None = None
+
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        provider = self.provider.strip().lower()
+        model = self.model.strip()
+
+        object.__setattr__(self, "provider", provider)
+        object.__setattr__(self, "model", model)
+        object.__setattr__(self, "api_key", _blank_to_none(self.api_key))
+        object.__setattr__(self, "base_url", _blank_to_none(self.base_url))
+        object.__setattr__(self, "organization", _blank_to_none(self.organization))
+        object.__setattr__(self, "headers", dict(self.headers))
+
+        if not provider:
+            raise ValueError("Provider cannot be empty.")
+
+        if not model:
+            raise ValueError("Model cannot be empty.")
+
+        if not 0.0 <= self.temperature <= 2.0:
+            raise ValueError("Temperature must be between 0.0 and 2.0.")
+
+        if self.max_tokens is not None and self.max_tokens <= 0:
+            raise ValueError("max_tokens must be greater than zero.")
+
+        if self.timeout <= 0:
+            raise ValueError("timeout must be greater than zero.")
+
+    @classmethod
+    def from_mapping(
+        cls,
+        values: Mapping[str, Any],
+    ) -> AIConfig:
+        """
+        Build AI configuration from a flat mapping or an ``ai`` section.
+        """
+
+        if not isinstance(values, Mapping):
+            raise ValueError("AI configuration must be a mapping.")
+
+        source = values.get("ai", values)
+
+        if not isinstance(source, Mapping):
+            raise ValueError("AI configuration must be a mapping.")
+
+        provider = _required_str(source, "provider")
+        model = _required_str(source, "model")
+        timeout = _optional_int(source, "timeout", default=60)
+
+        if timeout is None:
+            raise ValueError("timeout is required.")
+
+        return cls(
+            provider=provider,
+            model=model,
+            api_key=_optional_str(source, "api_key"),
+            base_url=_optional_str(source, "base_url"),
+            temperature=_optional_float(source, "temperature", default=0.2),
+            max_tokens=_optional_int(source, "max_tokens"),
+            timeout=timeout,
+            organization=_optional_str(source, "organization"),
+            headers=_optional_headers(source),
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str = "PYRESTKIT_AI_",
+    ) -> AIConfig:
+        """
+        Build AI configuration from environment variables.
+
+        Expected variables:
+
+        - PYRESTKIT_AI_PROVIDER
+        - PYRESTKIT_AI_MODEL
+        - PYRESTKIT_AI_API_KEY
+        - PYRESTKIT_AI_BASE_URL
+        - PYRESTKIT_AI_TEMPERATURE
+        - PYRESTKIT_AI_MAX_TOKENS
+        - PYRESTKIT_AI_TIMEOUT
+        - PYRESTKIT_AI_ORGANIZATION
+        """
+
+        model = os.getenv(f"{prefix}MODEL")
+
+        if model is None:
+            raise ValueError(f"{prefix}MODEL is required.")
+
+        mapping: dict[str, Any] = {
+            "provider": os.getenv(f"{prefix}PROVIDER", "openai"),
+            "model": model,
+            "api_key": os.getenv(f"{prefix}API_KEY"),
+            "base_url": os.getenv(f"{prefix}BASE_URL"),
+            "temperature": os.getenv(f"{prefix}TEMPERATURE", "0.2"),
+            "max_tokens": os.getenv(f"{prefix}MAX_TOKENS"),
+            "timeout": os.getenv(f"{prefix}TIMEOUT", "60"),
+            "organization": os.getenv(f"{prefix}ORGANIZATION"),
+        }
+
+        return cls.from_mapping(mapping)
+
+
+def _blank_to_none(value: str | None) -> str | None:
+    if value is None:
+        return None
+
+    value = value.strip()
+    return value or None
+
+
+def _required_str(
+    values: Mapping[str, Any],
+    key: str,
+) -> str:
+    value = values.get(key)
+
+    if value is None:
+        raise ValueError(f"{key} is required.")
+
+    return str(value)
+
+
+def _optional_str(
+    values: Mapping[str, Any],
+    key: str,
+) -> str | None:
+    value = values.get(key)
+
+    if value is None:
+        return None
+
+    return str(value)
+
+
+def _optional_float(
+    values: Mapping[str, Any],
+    key: str,
+    default: float,
+) -> float:
+    value = values.get(key, default)
+
+    if value is None or value == "":
+        return default
+
+    return float(value)
+
+
+def _optional_int(
+    values: Mapping[str, Any],
+    key: str,
+    default: int | None = None,
+) -> int | None:
+    value = values.get(key, default)
+
+    if value is None or value == "":
+        return default
+
+    return int(value)
+
+
+def _optional_headers(
+    values: Mapping[str, Any],
+) -> Mapping[str, str]:
+    headers = values.get("headers", {})
+
+    if headers is None:
+        return {}
+
+    if not isinstance(headers, Mapping):
+        raise ValueError("headers must be a mapping.")
+
+    return {str(key): str(value) for key, value in headers.items()}

pyrestkit/ai/exceptions.py

@@ -0,0 +1,22 @@
+class AIError(Exception):
+    """
+    Base exception for AI integration failures.
+    """
+
+
+class AIConfigurationError(AIError):
+    """
+    Raised when AI provider configuration is missing or invalid.
+    """
+
+
+class AIProviderError(AIError):
+    """
+    Raised when an AI provider request fails.
+    """
+
+
+class AIResponseParseError(AIError):
+    """
+    Raised when an AI response cannot be parsed into the expected shape.
+    """

pyrestkit/ai/models.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class FailureContext:
+    """
+    Normalized failure details that can be sent to an AI analyzer.
+    """
+
+    test_name: str
+    file_path: str | None = None
+    line_number: int | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    traceback: str | None = None
+    assertion: str | None = None
+    expected: str | None = None
+    actual: str | None = None
+    request_method: str | None = None
+    request_url: str | None = None
+    response_status: int | None = None
+    response_body: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class FailureAnalysis:
+    """
+    Structured AI output for a failing automation test.
+    """
+
+    summary: str
+    likely_cause: str
+    recommended_fix: str
+    suggested_patch: str | None = None
+    confidence: float = 0.0
+    raw_response: str | None = None

pyrestkit/ai/prompts/failure_analysis.md

@@ -0,0 +1,21 @@
+Analyze this API automation failure and identify the smallest useful fix.
+
+Return only a JSON object with this shape:
+
+{
+  "summary": "one sentence failure summary",
+  "likely_cause": "most likely root cause",
+  "recommended_fix": "specific next action",
+  "suggested_patch": "unified diff if a safe patch is obvious, otherwise null",
+  "confidence": 0.0
+}
+
+Rules:
+- Do not invent endpoint behavior that is not present in the context.
+- Prefer fixing test data, assertions, schemas, or client code only when the context supports it.
+- Keep suggested patches minimal and in unified diff format.
+- Do not include secrets or credentials in the response.
+
+Failure context:
+
+$context

pyrestkit/ai/provider.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from pyrestkit.ai.config import AIConfig
+
+
+class AIProvider(Protocol):
+    """
+    Contract implemented by concrete AI providers.
+    """
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        config: AIConfig,
+        system_prompt: str | None = None,
+    ) -> str:
+        """
+        Return a text completion for the given prompt.
+        """
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class AIProviderCall:
+    prompt: str
+    system_prompt: str | None
+    config: AIConfig
+
+
+@dataclass(slots=True)
+class StaticAIProvider:
+    """
+    Deterministic provider for tests and offline demos.
+    """
+
+    response: str
+    calls: list[AIProviderCall] = field(default_factory=list)
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        config: AIConfig,
+        system_prompt: str | None = None,
+    ) -> str:
+        self.calls.append(
+            AIProviderCall(
+                prompt=prompt,
+                system_prompt=system_prompt,
+                config=config,
+            )
+        )
+
+        return self.response

pyrestkit/ai/providers/__init__.py

@@ -0,0 +1,21 @@
+from pyrestkit.ai.providers.anthropic import AnthropicProvider
+from pyrestkit.ai.providers.azure_openai import AzureOpenAIProvider
+from pyrestkit.ai.providers.bedrock import BedrockProvider
+from pyrestkit.ai.providers.cohere import CohereProvider
+from pyrestkit.ai.providers.gemini import GeminiProvider
+from pyrestkit.ai.providers.groq import GroqProvider
+from pyrestkit.ai.providers.mistral import MistralProvider
+from pyrestkit.ai.providers.ollama import OllamaProvider
+from pyrestkit.ai.providers.openai import OpenAIResponsesProvider
+
+__all__ = [
+    "AnthropicProvider",
+    "AzureOpenAIProvider",
+    "BedrockProvider",
+    "CohereProvider",
+    "GeminiProvider",
+    "GroqProvider",
+    "MistralProvider",
+    "OllamaProvider",
+    "OpenAIResponsesProvider",
+]