pyrestkit 0.0.0__py3-none-any.whl

pyrestkit/ai/providers/ollama.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pyrestkit.ai.config import AIConfig
+from pyrestkit.ai.exceptions import AIProviderError
+from pyrestkit.ai.providers.base import BaseAIProvider
+
+
+class OllamaProvider(BaseAIProvider):
+    """
+    Local Ollama provider using the generate endpoint.
+    """
+
+    def __init__(
+        self,
+        session: Any | None = None,
+    ) -> None:
+        super().__init__(session=session)
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        config: AIConfig,
+        system_prompt: str | None = None,
+    ) -> str:
+        options: dict[str, Any] = {
+            "temperature": config.temperature,
+        }
+
+        if config.max_tokens is not None:
+            options["num_predict"] = config.max_tokens
+
+        payload: dict[str, Any] = {
+            "model": config.model,
+            "prompt": prompt,
+            "stream": False,
+            "options": options,
+        }
+
+        if system_prompt:
+            payload["system"] = system_prompt
+
+        response = self._session.post(
+            _generate_url(config.base_url),
+            json=payload,
+            headers=dict(config.headers),
+            timeout=config.timeout,
+        )
+
+        if response.status_code >= 400:
+            raise AIProviderError(
+                f"Ollama request failed with status {response.status_code}: "
+                f"{response.text}"
+            )
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise AIProviderError("Ollama response was not valid JSON.") from exc
+
+        if not isinstance(data, dict):
+            raise AIProviderError("Ollama response was not a JSON object.")
+
+        text = data.get("response")
+
+        if not isinstance(text, str):
+            raise AIProviderError("Ollama response did not include response text.")
+
+        return text
+
+
+def _generate_url(
+    base_url: str | None,
+) -> str:
+    base = (base_url or "http://localhost:11434").rstrip("/")
+
+    if base.endswith("/api/generate"):
+        return base
+
+    return f"{base}/api/generate"

pyrestkit/ai/providers/openai.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pyrestkit.ai.config import AIConfig
+from pyrestkit.ai.exceptions import AIConfigurationError, AIProviderError
+from pyrestkit.ai.providers.base import BaseAIProvider
+
+
+class OpenAIResponsesProvider(BaseAIProvider):
+    """
+    OpenAI provider backed by the Responses API.
+    """
+
+    def __init__(
+        self,
+        session: Any | None = None,
+    ) -> None:
+        super().__init__(session=session)
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        config: AIConfig,
+        system_prompt: str | None = None,
+    ) -> str:
+        if not config.api_key:
+            raise AIConfigurationError("OpenAI API key is required.")
+
+        payload: dict[str, Any] = {
+            "model": config.model,
+            "input": prompt,
+            "temperature": config.temperature,
+        }
+
+        if system_prompt:
+            payload["instructions"] = system_prompt
+
+        if config.max_tokens is not None:
+            payload["max_output_tokens"] = config.max_tokens
+
+        response = self._session.post(
+            _responses_url(config.base_url),
+            json=payload,
+            headers=_headers(config),
+            timeout=config.timeout,
+        )
+
+        if response.status_code >= 400:
+            raise AIProviderError(
+                f"OpenAI request failed with status {response.status_code}: "
+                f"{response.text}"
+            )
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise AIProviderError("OpenAI response was not valid JSON.") from exc
+
+        return _extract_text(data)
+
+
+def _responses_url(
+    base_url: str | None,
+) -> str:
+    base = (base_url or "https://api.openai.com/v1").rstrip("/")
+
+    if base.endswith("/responses"):
+        return base
+
+    return f"{base}/responses"
+
+
+def _headers(config: AIConfig) -> dict[str, str]:
+    headers = BaseAIProvider.json_headers(config)
+
+    if config.api_key is not None:
+        headers["Authorization"] = f"Bearer {config.api_key}"
+
+    if config.organization is not None:
+        headers["OpenAI-Organization"] = config.organization
+
+    return headers
+
+
+def _extract_text(
+    data: MappingLike,
+) -> str:
+    output_text = data.get("output_text")
+
+    if isinstance(output_text, str) and output_text.strip():
+        return output_text
+
+    output = data.get("output", [])
+
+    if isinstance(output, list):
+        chunks: list[str] = []
+
+        for item in output:
+            if not isinstance(item, dict):
+                continue
+
+            content = item.get("content", [])
+
+            if not isinstance(content, list):
+                continue
+
+            for part in content:
+                if not isinstance(part, dict):
+                    continue
+
+                text = part.get("text")
+
+                if isinstance(text, str):
+                    chunks.append(text)
+
+        if chunks:
+            return "\n".join(chunks)
+
+    raise AIProviderError("OpenAI response did not include output text.")
+
+
+MappingLike = dict[str, Any]

pyrestkit/ai/utils/prompt_loader.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+from string import Template
+
+
+class PromptLoader:
+    """
+    Loads and renders prompt templates from a directory.
+    """
+
+    def __init__(
+        self,
+        base_path: str | Path,
+    ) -> None:
+        self._base_path = Path(base_path).resolve()
+
+    @classmethod
+    def default(cls) -> PromptLoader:
+        return cls(Path(__file__).resolve().parents[1] / "prompts")
+
+    def load(
+        self,
+        name: str,
+    ) -> str:
+        path = self._resolve(name)
+
+        if not path.exists():
+            raise FileNotFoundError(f"Prompt template '{name}' was not found.")
+
+        return path.read_text(encoding="utf-8")
+
+    def render(
+        self,
+        template_name: str,
+        **values: object,
+    ) -> str:
+        template = Template(self.load(template_name))
+        return template.substitute(values)
+
+    def _resolve(
+        self,
+        name: str,
+    ) -> Path:
+        path = (self._base_path / name).resolve()
+
+        try:
+            path.relative_to(self._base_path)
+        except ValueError as exc:
+            raise ValueError("Prompt template path cannot escape base path.") from exc
+
+        return path

pyrestkit/assertions/__init__.py

@@ -0,0 +1,7 @@
+from .assertion_exception import AssertionException
+from .response_assertions import ResponseAssertions
+
+__all__ = [
+    "AssertionException",
+    "ResponseAssertions",
+]

pyrestkit/assertions/assertion_exception.py

@@ -0,0 +1,4 @@
+class AssertionException(AssertionError):
+    """
+    Raised when a framework assertion fails.
+    """

pyrestkit/assertions/response_assertions.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyrestkit.assertions.assertion_exception import AssertionException
+from pyrestkit.validators.schema_validator import SchemaValidator
+
+if TYPE_CHECKING:
+    from pyrestkit.response.framework_response import FrameworkResponse
+
+
+class ResponseAssertions:
+    """
+    Fluent assertions for FrameworkResponse.
+    """
+
+    def __init__(
+        self,
+        response: FrameworkResponse,
+    ) -> None:
+        self._response = response
+
+    def have_status(
+        self,
+        expected: int,
+    ) -> ResponseAssertions:
+        actual = self._response.status_code
+
+        if actual != expected:
+            raise AssertionException(
+                f"Expected status code {expected}, but received {actual}."
+            )
+
+        return self
+
+    def be_successful(
+        self,
+    ) -> ResponseAssertions:
+        if not self._response.ok:
+            raise AssertionException(
+                f"Expected successful response "
+                f"but received {self._response.status_code}."
+            )
+
+        return self
+
+    def have_header(
+        self,
+        name: str,
+        expected: str | None = None,
+    ) -> ResponseAssertions:
+        headers = self._response.headers
+
+        if name not in headers:
+            raise AssertionException(f"Header '{name}' was not found.")
+
+        if expected is not None:
+            actual = headers[name]
+
+            if actual != expected:
+                raise AssertionException(
+                    f"Expected header '{name}' to be '{expected}', but was '{actual}'."
+                )
+
+        return self
+
+    def match_schema(
+        self,
+        schema_path: str,
+    ) -> ResponseAssertions:
+        SchemaValidator.validate(
+            self._response,
+            schema_path,
+        )
+
+        return self
+
+    def _get_json_value(
+        self,
+        path: str,
+    ) -> object:
+        """
+        Returns a nested JSON value using dot notation.
+
+        Example:
+
+            data.email
+            support.url
+        """
+
+        value: object = self._response.json()
+
+        for part in path.split("."):
+            if not isinstance(value, dict):
+                raise AssertionException(f"'{path}' does not exist.")
+
+            if part not in value:
+                raise AssertionException(f"Key '{part}' not found in '{path}'.")
+
+            value = value[part]
+
+        return value
+
+    def have_json(
+        self,
+        path: str,
+        expected: object,
+    ) -> ResponseAssertions:
+        actual = self._get_json_value(path)
+
+        if actual != expected:
+            raise AssertionException(
+                f"Expected '{path}' to be {expected!r}, but was {actual!r}."
+            )
+
+        return self
+
+    def respond_within(
+        self,
+        milliseconds: int,
+    ) -> ResponseAssertions:
+        """
+        Verifies that the response completed within the
+        specified number of milliseconds.
+        """
+
+        actual = self._response.elapsed.total_seconds() * 1000
+
+        if actual > milliseconds:
+            raise AssertionException(
+                f"Expected response within {milliseconds} ms, but took {actual:.2f} ms."
+            )
+
+        return self
+
+    def have_json_count(
+        self,
+        path: str,
+        expected: int,
+    ) -> ResponseAssertions:
+        """
+        Verifies the number of items
+        in a JSON array.
+        """
+
+        value = self._response.body.get(path)
+
+        if not isinstance(
+            value,
+            list,
+        ):
+            raise AssertionException(f"'{path}' is not a JSON array.")
+
+        actual = len(value)
+
+        if actual != expected:
+            raise AssertionException(
+                f"Expected {expected} items at '{path}', but found {actual}."
+            )
+
+        return self
+
+    def have_json_contains(
+        self,
+        path: str,
+        expected: object,
+    ) -> ResponseAssertions:
+        """
+        Verifies that a JSON array contains
+        the expected value.
+        """
+
+        value = self._response.body.get(path)
+
+        if not isinstance(value, list):
+            raise AssertionException(f"'{path}' is not a JSON array.")
+
+        if expected not in value:
+            raise AssertionException(f"{expected!r} not found in '{path}'.")
+
+        return self

pyrestkit/auth/__init__.py

@@ -0,0 +1,11 @@
+from .auth_strategy import AuthenticationStrategy
+from .authentication_manager import AuthenticationManager
+from .token_cache import TokenCache
+from .token_manager import TokenManager
+
+__all__ = [
+    "AuthenticationManager",
+    "AuthenticationStrategy",
+    "TokenCache",
+    "TokenManager",
+]

pyrestkit/auth/auth_strategy.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AuthenticationStrategy(ABC):
+    """Base interface for all authentication strategies.
+    This is the interface every authentication implementation must follow.
+    """
+
+    @abstractmethod
+    def get_headers(self) -> dict[str, str]:
+        """Return authentication headers."""
+        raise NotImplementedError

pyrestkit/auth/authentication_manager.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pyrestkit.auth.auth_strategy import AuthenticationStrategy
+
+
+class AuthenticationManager:
+    """
+    Responsible for providing authentication headers.
+
+    APIClient communicates only with this class and remains
+    unaware of the underlying authentication mechanism.
+    """
+
+    def __init__(
+        self,
+        strategy: AuthenticationStrategy | None = None,
+    ) -> None:
+        self._strategy = strategy
+
+    @property
+    def strategy(self) -> AuthenticationStrategy | None:
+        return self._strategy
+
+    @strategy.setter
+    def strategy(
+        self,
+        strategy: AuthenticationStrategy | None,
+    ) -> None:
+        self._strategy = strategy
+
+    def get_headers(self) -> dict[str, str]:
+        if self._strategy is None:
+            return {}
+
+        return self._strategy.get_headers()

pyrestkit/auth/strategies/__init__.py

@@ -0,0 +1,5 @@
+from .api_key_auth import ApiKeyAuth
+from .basic_auth import BasicAuth
+from .bearer_auth import BearerAuth
+
+__all__ = ["ApiKeyAuth", "BasicAuth", "BearerAuth"]

pyrestkit/auth/strategies/api_key_auth.py

@@ -0,0 +1,18 @@
+from pyrestkit.auth.auth_strategy import AuthenticationStrategy
+
+
+class ApiKeyAuth(AuthenticationStrategy):
+    """API Key Authentication."""
+
+    def __init__(
+        self,
+        api_key: str,
+        header_name: str = "x-api-key",
+    ) -> None:
+        self._api_key = api_key
+        self._header_name = header_name
+
+    def get_headers(self) -> dict[str, str]:
+        return {
+            self._header_name: self._api_key,
+        }

pyrestkit/auth/strategies/basic_auth.py

@@ -0,0 +1,24 @@
+import base64
+
+from pyrestkit.auth.auth_strategy import AuthenticationStrategy
+
+
+class BasicAuth(AuthenticationStrategy):
+    """HTTP Basic Authentication."""
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+    ) -> None:
+        self._username = username
+        self._password = password
+
+    def get_headers(self) -> dict[str, str]:
+        credentials = (f"{self._username}:{self._password}").encode()
+
+        encoded = base64.b64encode(credentials).decode("utf-8")
+
+        return {
+            "Authorization": f"Basic {encoded}",
+        }

pyrestkit/auth/strategies/bearer_auth.py

@@ -0,0 +1,17 @@
+from pyrestkit.auth.auth_strategy import AuthenticationStrategy
+from pyrestkit.auth.token_manager import TokenManager
+
+
+class BearerAuth(AuthenticationStrategy):
+    def __init__(
+        self,
+        token_manager: TokenManager,
+    ) -> None:
+        self._token_manager = token_manager
+
+    def get_headers(self) -> dict[str, str]:
+        token = self._token_manager.get_token()
+
+        return {
+            "Authorization": f"Bearer {token}",
+        }

pyrestkit/auth/token_cache.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from threading import Lock
+
+from pyrestkit.auth.token_response import TokenResponse
+
+
+class TokenCache:
+    """
+    Thread-safe cache for authentication tokens.
+    """
+
+    def __init__(self) -> None:
+        self._response: TokenResponse | None = None
+        self._expires_at: datetime | None = None
+        self._lock = Lock()
+
+    def get(self) -> TokenResponse | None:
+        if self._response is None:
+            return None
+
+        if self._expires_at is None:
+            return None
+
+        if datetime.now(UTC) >= self._expires_at:
+            return None
+
+        return self._response
+
+    def set(
+        self,
+        response: TokenResponse,
+    ) -> None:
+        with self._lock:
+            self._response = response
+            self._expires_at = datetime.now(UTC) + timedelta(
+                seconds=response.expires_in,
+            )
+
+    def clear(self) -> None:
+        with self._lock:
+            self._response = None
+            self._expires_at = None

pyrestkit/auth/token_manager.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pyrestkit.auth.token_cache import TokenCache
+from pyrestkit.auth.token_provider import TokenProvider
+
+
+class TokenManager:
+    """
+    Responsible for retrieving access tokens.
+
+    Caching and refresh logic will be added in later modules.
+    """
+
+    def __init__(
+        self,
+        provider: TokenProvider,
+        cache: TokenCache,
+    ) -> None:
+        self._provider = provider
+        self._cache = cache
+
+    def get_token(self) -> str:
+        cached = self._cache.get()
+
+        if cached is not None:
+            return cached.access_token
+
+        response = self._provider.get_token()
+
+        self._cache.set(response)
+
+        return response.access_token

pyrestkit/auth/token_provider.py

@@ -0,0 +1,12 @@
+from abc import ABC, abstractmethod
+
+from pyrestkit.auth.token_response import TokenResponse
+
+
+class TokenProvider(ABC):
+    @abstractmethod
+    def get_token(self) -> TokenResponse:
+        """
+        Fetch a new token.
+        """
+        raise NotImplementedError

pyrestkit/auth/token_response.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class TokenResponse:
+    """
+    Represents an authentication token returned by the auth server.
+    """
+
+    access_token: str
+    expires_in: int