get-systems 0.2.21__py3-none-any.whl

get_systems/__init__.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.util import find_spec
+from importlib.metadata import version, PackageNotFoundError
+from typing import Any
+
+try:
+    __version__ = version("get-systems")  # package name in pyproject
+except PackageNotFoundError:
+    # fallback for local/dev run (not installed via pip)
+    __version__ = "0.0.0"
+
+# Какие "пространства" сканируем.
+# Можешь расширять: plugins, integrations и т.п.
+_NAMESPACES = ("models", "llm", "http")
+
+# Здесь будет: name -> (module_path, attr_name)
+_EXPORTS: dict[str, tuple[str, str]] = {}
+
+
+def _discover_exports() -> None:
+    """
+    Discover exports from get_systems.<namespace> packages.
+
+    Strategy:
+    - For each namespace package (models/llm/http), import only its __init__
+      (not every submodule), read __all__ and register lazy exports.
+    - The heavy dependencies should be imported inside that namespace package,
+      or inside its submodules, not here.
+    """
+    pkg_root = "get_systems"
+
+    for ns in _NAMESPACES:
+        ns_mod_path = f"{pkg_root}.{ns}"
+
+        # Namespace may not exist if extra isn't installed or package not shipped
+        if find_spec(ns_mod_path) is None:
+            continue
+
+        try:
+            ns_mod = import_module(ns_mod_path)  # imports get_systems.<ns>.__init__
+        except ImportError:
+            # If optional deps of that namespace are missing, just skip.
+            # Real error will appear when user tries to access something.
+            continue
+
+        ns_all = getattr(ns_mod, "__all__", None)
+        if not ns_all:
+            continue
+
+        for name in ns_all:
+            # Detect collisions early
+            if name in _EXPORTS:
+                prev = _EXPORTS[name][0]
+                raise RuntimeError(
+                    f"Export name collision: '{name}' provided by both '{prev}' and '{ns_mod_path}'. "
+                    f"Rename one of them or avoid exporting it at top-level."
+                )
+
+            _EXPORTS[name] = (ns_mod_path, name)
+
+
+_discover_exports()
+
+# Public API is whatever we discovered
+__all__ = sorted(_EXPORTS.keys())
+
+
+def __getattr__(name: str) -> Any:
+    """
+    Lazy attribute resolver for dynamically discovered exports.
+    """
+    if name not in _EXPORTS:
+        raise AttributeError(f"module 'get_systems' has no attribute '{name}'")
+
+    module_name, attr_name = _EXPORTS[name]
+
+    # Optional nice hints based on namespace
+    if module_name.endswith(".llm"):
+        # if llm extra not installed, most likely it fails inside llm import
+        pass
+    if module_name.endswith(".http"):
+        pass
+    if module_name.endswith(".models"):
+        pass
+
+    mod = import_module(module_name)
+    value = getattr(mod, attr_name)
+
+    # Cache for next time
+    globals()[name] = value
+    return value

get_systems/http/__init__.py

@@ -0,0 +1,15 @@
+"""
+HTTP authentication and request module - Prefect blocks for HTTP operations
+
+Usage:
+    from get_systems.http import HttpAuth, HttpBlock
+    # or
+    from get_systems.http.http_block import HttpAuth
+"""
+
+from get_systems.http.http_block import HttpAuth, HttpBlock
+
+__all__ = [
+    "HttpAuth",
+    "HttpBlock",
+]

get_systems/http/http_block.py

@@ -0,0 +1,69 @@
+from typing import Any, Literal, Optional
+
+import httpx
+from pydantic import Field, SecretStr
+from prefect.blocks.core import Block
+
+
+class HttpAuth(Block):
+    """HTTP authentication configuration and async client factory."""
+
+    auth_type: Literal["none", "basic", "token", "bearer"] = Field(
+        default="none",
+        description="Authentication type for HTTP requests",
+    )
+    username: Optional[str] = Field(default=None, description="Basic auth username")
+    password: Optional[SecretStr] = Field(default=None, description="Basic auth password")
+    token: Optional[SecretStr] = Field(default=None, description="Token or bearer value")
+    headers: dict[str, str] = Field(default_factory=dict, description="Extra headers")
+
+    def _auth(self) -> Optional[httpx.Auth]:
+        if self.auth_type != "basic":
+            return None
+        if not self.username or not self.password:
+            raise ValueError("Basic auth requires username and password.")
+        return httpx.BasicAuth(self.username, self.password.get_secret_value())
+
+    def _headers(self) -> dict[str, str]:
+        headers = dict(self.headers)
+        if self.auth_type in ("token", "bearer"):
+            if not self.token:
+                raise ValueError("Token auth requires token.")
+            prefix = "Token" if self.auth_type == "token" else "Bearer"
+            headers["Authorization"] = f"{prefix} {self.token.get_secret_value()}"
+        return headers
+
+    def get_async_client(
+        self,
+        base_url: Optional[str] = None,
+        timeout_s: float = 60.0,
+        extra_headers: Optional[dict[str, str]] = None,
+    ) -> httpx.AsyncClient:
+        headers = self._headers()
+        if extra_headers:
+            headers.update(extra_headers)
+
+        return httpx.AsyncClient(
+            base_url=base_url or "",
+            timeout=httpx.Timeout(timeout_s),
+            headers=headers,
+            auth=self._auth(),
+        )
+
+
+class HttpBlock(Block):
+    """Base class for HTTP-based blocks, providing common functionality for API interactions."""
+
+    url: str = "https://api.example.com"  # Default URL, can be overridden by subclasses
+    extract_token: bool = False  # Whether to extract token from response for chaining
+    auth: Optional[HttpAuth] = None
+    timeout_s: float = 60.0
+
+    def get_async_client(self) -> httpx.AsyncClient:
+        if self.auth:
+            return self.auth.get_async_client(base_url=self.url, timeout_s=self.timeout_s)
+        return httpx.AsyncClient(base_url=self.url, timeout=httpx.Timeout(self.timeout_s))
+
+    async def request(self, method: str, path: str = "", **kwargs: Any) -> httpx.Response:
+        async with self.get_async_client() as client:
+            return await client.request(method=method, url=path, **kwargs)

get_systems/llm/__init__.py

@@ -0,0 +1,22 @@
+"""
+LLM operations module - OpenAI and Azure OpenAI Prefect blocks
+
+Usage:
+    from get_systems.llm import GptCompletionBlock, GptAuth, LlmRuntime, LlmResult
+    # or
+    from get_systems.llm.gpt_blocks import GptCompletionBlock
+"""
+
+from get_systems.llm.gpt_blocks import (
+    GptAuth,
+    GptCompletionBlock,
+    LlmResult,
+    LlmRuntime,
+)
+
+__all__ = [
+    "GptAuth",
+    "GptCompletionBlock",
+    "LlmResult",
+    "LlmRuntime",
+]

get_systems/llm/gpt_blocks.py

@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+import json
+import logging
+import random
+import time
+from typing import Any, Optional
+
+import httpx
+from openai import AsyncOpenAI, AsyncAzureOpenAI
+from pydantic import BaseModel, Field, SecretStr
+from prefect.blocks.core import Block
+from prefect.logging import get_run_logger
+from prefect.exceptions import MissingContextError
+
+from .utils import _env, _env_secret, _env_bool, _safe_preview, _hash_payload, ResolvedAuth
+
+
+# ----------------------------
+# Blocks
+# ----------------------------
+
+class GptAuth(Block):
+    """
+    Enterprise auth/config holder for OpenAI client.
+    Env fallback is supported by GptCompletionBlock.
+
+    Example:
+
+        ```python
+        from get_systems.llm import GptAuth
+
+        auth = GptAuth.load("BLOCK_NAME")
+        ```
+    """
+
+    _block_type_name = "GPT Auth"
+    _block_type_slug = "gpt-auth"
+    _logo_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/e/ef/ChatGPT-Logo.svg/960px-ChatGPT-Logo.svg.png?20240214002031"
+    _description = "Enterprise auth/config holder for OpenAI client with environment fallback support."
+    _code_example = """from get_systems.llm import GptAuth
+
+    auth = GptAuth.load("BLOCK_NAME")"""
+
+    api_key: Optional[SecretStr] = Field(default_factory=lambda: _env_secret("OPENAI_API_KEY"), description="OpenAI API key")
+    model: Optional[str] = Field(default_factory=lambda: _env("OPENAI_MODEL"), description="Default model")
+    base_url: Optional[str] = Field(default_factory=lambda: _env("OPENAI_BASE_URL"), description="Custom base URL (optional)")
+    organization: Optional[str] = Field(default_factory=lambda: _env("OPENAI_ORG"), description="OpenAI organization (optional)")
+    project: Optional[str] = Field(default_factory=lambda: _env("OPENAI_PROJECT"), description="OpenAI project (optional)")
+    api_version: Optional[str] = Field(default_factory=lambda: _env("OPENAI_API_VERSION"), description="Azure OpenAI API version (optional)")
+    is_azure: Optional[bool] = Field(default_factory=lambda: _env_bool("OPENAI_IS_AZURE"), description="Set to True for Azure OpenAI, False for standard OpenAI (auto-detected if None)")
+
+
+class LlmRuntime(Block):
+    """
+    Runtime policies: retry/backoff, timeouts, caching, concurrency hints.
+
+    Example:
+        ```python
+        from get_systems.llm import LlmRuntime
+
+        runtime = LlmRuntime.load("BLOCK_NAME")
+        ```
+    """
+
+    _block_type_name = "LLM Runtime Policy"
+    _block_type_slug = "llm-runtime"
+    _logo_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/e/ef/ChatGPT-Logo.svg/960px-ChatGPT-Logo.svg.png?20240214002031"
+    _description = "Runtime policies for LLM operations including retry logic, backoff strategy, timeouts, caching, and logging controls."
+    _code_example = """from get_systems.llm import LlmRuntime
+
+runtime = LlmRuntime.load("BLOCK_NAME")"""
+
+    request_timeout_s: float = Field(default=60.0, description="HTTP request timeout seconds")
+    max_retries: int = Field(default=5, description="Max retries on transient errors")
+    base_backoff_s: float = Field(default=0.5, description="Base backoff seconds")
+    max_backoff_s: float = Field(default=8.0, description="Max backoff seconds")
+
+    # Basic in-memory cache (per-process). Good for dev; for prod use Redis.
+    enable_cache: bool = Field(default=False, description="Enable in-memory response cache")
+    cache_ttl_s: int = Field(default=300, description="Cache TTL seconds")
+
+    # Logging controls
+    log_prompts_preview: bool = Field(default=True, description="Log prompt preview (redacted/trimmed)")
+    log_response_preview: bool = Field(default=True, description="Log response preview (trimmed)")
+
+
+class LlmResult(BaseModel):
+    """
+    Unified response shape (handy for orchestration).
+    """
+    content: Optional[str] = None
+    tool_calls: Optional[Any] = None
+    model: Optional[str] = None
+    request_id: Optional[str] = None
+    finish_reason: Optional[str] = None
+    usage: Optional[Any] = None
+
+    cached: bool = False
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+# Very small in-memory cache (process-local)
+_CACHE: dict[str, tuple[float, dict[str, Any]]] = {}
+
+
+class GptCompletionBlock(Block):
+    """
+    Enterprise-grade completion block:
+    - Auth from block OR env
+    - Retry with exponential backoff + jitter
+    - Timeouts via httpx
+    - Optional in-memory cache
+    - Safe logging (no api key leak)
+    [boto3 docs](https://github.com/get-systems/prefect_blocks)
+
+    Example:
+        Load GptCompletionBlock:
+        ```python
+        from get_systems.llm import GptCompletionBlock
+
+        block = GptCompletionBlock.load("BLOCK_NAME")
+        result = await block.run()
+        ```
+    """# noqa E501
+
+    _block_type_name = "GPT Completion"
+    _block_type_slug = "gpt-completion"
+    _logo_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/e/ef/ChatGPT-Logo.svg/960px-ChatGPT-Logo.svg.png?20240214002031"
+    _description = "Enterprise-grade OpenAI completion block with auth management, retry logic, caching, and safe logging."
+#     _code_example = """from get_systems.llm import GptCompletionBlock
+
+# block = GptCompletionBlock.load("BLOCK_NAME")
+# # Pass extra kwargs like top_p, frequency_penalty, etc.
+# result = await block.run(top_p=0.9, frequency_penalty=0.5)
+# print(result.content)"""
+
+    auth: GptAuth = Field(default_factory=GptAuth)
+    runtime: Optional[LlmRuntime] = None
+
+    # Input
+    system_prompt: Optional[str] = None
+    _messages: Optional[list[dict[str, Any]]] = None
+    tools: Optional[list[dict[str, Any]]] = None
+
+    # Model params
+    model: Optional[str] = None
+    temperature: Optional[float] = 0.7
+    max_tokens: Optional[int] = None
+
+    # Orchestration metadata
+    correlation_id: Optional[str] = Field(default=None, description="Trace/correlation id across systems")
+    tags: dict[str, Any] = Field(default_factory=dict)
+
+    def _resolve(self) -> tuple[ResolvedAuth, LlmRuntime]:
+        # Runtime defaults
+        rt = self.runtime or LlmRuntime()
+
+        # Block first
+        api_key = None
+        base_url = None
+        model = None
+        org = None
+        project = None
+        api_version = None
+        is_azure = None
+
+        if self.auth:
+            if self.auth.api_key:
+                api_key = self.auth.api_key.get_secret_value()
+            base_url = self.auth.base_url
+            model = self.auth.model
+            org = self.auth.organization
+            project = self.auth.project
+            api_version = self.auth.api_version
+            is_azure = self.auth.is_azure
+
+        # Model precedence: block -> field (required)
+        model = model or self.model
+
+        if not api_key:
+            raise ValueError("No API key provided. Set auth.api_key or OPENAI_API_KEY env.")
+
+        if not model:
+            raise ValueError("No model provided. Set auth.model or model on the block.")
+
+        return ResolvedAuth(
+            api_key=api_key,
+            base_url=base_url,
+            model=model,
+            organization=org,
+            project=project,
+            api_version=api_version,
+            is_azure=is_azure,
+        ), rt
+
+    def _build_messages(self, user_message: Optional[str] = None) -> list[dict[str, Any]]:
+        messages: list[dict[str, Any]] = []
+
+        # System prompt always first
+        if self.system_prompt:
+            messages.append({
+                "role": "system",
+                "content": self.system_prompt.strip()
+            })
+
+        # User message
+        if user_message:
+            messages.append({
+                "role": "user",
+                "content": user_message.strip()
+            })
+
+        if not messages:
+            raise ValueError("Provide either system_prompt or user_message")
+
+        return messages
+
+    def _client(self, ra: ResolvedAuth, rt: LlmRuntime) -> AsyncOpenAI:
+        # httpx timeout and pool config (safe baseline)
+        timeout = httpx.Timeout(rt.request_timeout_s)
+        http_client = httpx.AsyncClient(timeout=timeout)
+
+        if ra.is_azure:
+            # Azure OpenAI uses different client and parameters
+            logger = logging.getLogger(__name__)
+            logger.info(
+                f"Creating Azure OpenAI client: endpoint={ra.base_url}, api_version={ra.api_version}, model/deployment={ra.model}"
+            )
+            return AsyncAzureOpenAI(
+                api_key=ra.api_key,
+                azure_endpoint=ra.base_url,
+                api_version=ra.api_version or "2024-02-15-preview",
+                http_client=http_client,
+            )
+        else:
+            # Standard OpenAI
+            return AsyncOpenAI(
+                api_key=ra.api_key,
+                base_url=ra.base_url,
+                organization=ra.organization,
+                project=ra.project,
+                http_client=http_client,
+            )
+
+    def _should_retry(self, exc: Exception) -> bool:
+        # Conservative: retry on network/timeouts and OpenAI transient errors.
+        # openai-python raises different exception types; we do string-based fallback too.
+        name = exc.__class__.__name__.lower()
+        msg = str(exc).lower()
+
+        transient_markers = [
+            "timeout",
+            "temporarily",
+            "rate limit",
+            "429",
+            "503",
+            "502",
+            "connection",
+            "dns",
+            "server error",
+            "gateway",
+        ]
+        return any(m in name or m in msg for m in transient_markers)
+
+    def _backoff(self, attempt: int, rt: LlmRuntime) -> float:
+        # Exponential backoff with jitter
+        base = min(rt.max_backoff_s, rt.base_backoff_s * (2 ** attempt))
+        jitter = random.uniform(0, base * 0.2)
+        return min(rt.max_backoff_s, base + jitter)
+
+    def _cache_get(self, key: str, rt: LlmRuntime) -> Optional[dict[str, Any]]:
+        if not rt.enable_cache:
+            return None
+        item = _CACHE.get(key)
+        if not item:
+            return None
+        ts, val = item
+        if (time.time() - ts) > rt.cache_ttl_s:
+            _CACHE.pop(key, None)
+            return None
+        return val
+
+    def _cache_set(self, key: str, rt: LlmRuntime, value: dict[str, Any]) -> None:
+        if not rt.enable_cache:
+            return
+        _CACHE[key] = (time.time(), value)
+
+    async def run(self, user_message: Optional[str] = None, **extra_kwargs) -> LlmResult:
+        """
+        Execute LLM completion request.
+
+        Args:
+            **extra_kwargs: Additional parameters to pass to OpenAI API
+                (e.g., top_p, frequency_penalty, presence_penalty, response_format, etc.)
+
+        Returns:
+            LlmResult with completion response
+        """
+        # Try to get Prefect logger, fallback to standard Python logger
+        try:
+            logger = get_run_logger()
+        except MissingContextError:
+            logger = logging.getLogger(__name__)
+
+        ra, rt = self._resolve()
+        messages = self._build_messages(user_message)
+
+        # Payload for caching/idempotency-ish key (include extra_kwargs)
+        payload_fingerprint = {
+            "model": ra.model,
+            "messages": messages,
+            "tools": self.tools,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "extra": extra_kwargs,  # Include extra params in cache key
+        }
+        cache_key = _hash_payload(payload_fingerprint)
+
+        cached = self._cache_get(cache_key, rt)
+        if cached:
+            return LlmResult(**cached, cached=True)
+
+        # Safe previews for logs
+        if rt.log_prompts_preview:
+            preview = _safe_preview(self.system_prompt) if self.system_prompt else _safe_preview(json.dumps(messages, ensure_ascii=False))
+            logger.info(
+                "LLM request prepared",
+                extra={
+                    "correlation_id": self.correlation_id,
+                    "model": ra.model,
+                    "prompt_preview": preview,
+                    "tags": self.tags,
+                },
+            )
+
+        client = self._client(ra, rt)
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(rt.max_retries + 1):
+            try:
+                logger.debug(
+                    f"Attempting LLM call: model/deployment={ra.model}, is_azure={ra.is_azure}, attempt={attempt}"
+                )
+
+                # Build API call kwargs - only include non-None values
+                api_kwargs: dict[str, Any] = {
+                    "model": ra.model,
+                    "messages": messages,
+                }
+
+                if self.tools is not None:
+                    api_kwargs["tools"] = self.tools
+                if self.temperature is not None:
+                    api_kwargs["temperature"] = self.temperature
+                if self.max_tokens is not None:
+                    api_kwargs["max_tokens"] = self.max_tokens
+
+                # Add extra kwargs (e.g., top_p, frequency_penalty, response_format, etc.)
+                api_kwargs.update(extra_kwargs)
+
+                logger.debug(f"API call parameters: {', '.join(api_kwargs.keys())}")
+
+                resp = await client.chat.completions.create(**api_kwargs)
+
+                choice = resp.choices[0]
+                msg = choice.message
+
+                result = LlmResult(
+                    content=msg.content,
+                    tool_calls=getattr(msg, "tool_calls", None),
+                    model=resp.model,
+                    request_id=getattr(resp, "id", None),
+                    finish_reason=choice.finish_reason,
+                    usage=getattr(resp, "usage", None),
+                    meta={
+                        "correlation_id": self.correlation_id,
+                        "tags": self.tags,
+                    },
+                )
+
+                # Cache result as dict (avoid model_dump() issues with some Pydantic versions)
+                out_dict = {
+                    "content": result.content,
+                    "tool_calls": result.tool_calls,
+                    "model": result.model,
+                    "request_id": result.request_id,
+                    "finish_reason": result.finish_reason,
+                    "usage": result.usage,
+                    "meta": result.meta,
+                }
+                self._cache_set(cache_key, rt, out_dict)
+
+                if rt.log_response_preview:
+                    logger.info(
+                        "LLM response received",
+                        extra={
+                            "correlation_id": self.correlation_id,
+                            "request_id": result.request_id,
+                            "finish_reason": result.finish_reason,
+                            "response_preview": _safe_preview(result.content),
+                        },
+                    )
+
+                return result
+
+            except Exception as exc:
+                last_exc = exc
+                retry = self._should_retry(exc) and attempt < rt.max_retries
+                logger.warning(
+                    "LLM call failed",
+                    extra={
+                        "correlation_id": self.correlation_id,
+                        "attempt": attempt,
+                        "will_retry": retry,
+                        "error_type": exc.__class__.__name__,
+                        "error": str(exc)[:500],
+                    },
+                )
+                if not retry:
+                    break
+                time.sleep(self._backoff(attempt, rt))
+
+        raise RuntimeError(f"LLM call failed after retries: {last_exc}") from last_exc

get_systems/llm/utils.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from pydantic import SecretStr
+
+
+def _env(name: str, default: Optional[str] = None) -> Optional[str]:
+    v = os.getenv(name)
+    return v if v not in (None, "") else default
+
+
+def _env_secret(name: str) -> Optional[SecretStr]:
+    v = _env(name)
+    return SecretStr(v) if v else None
+
+
+def _env_bool(name: str) -> Optional[bool]:
+    v = _env(name)
+    if v is None:
+        return None
+    return v.lower() in ("true", "1", "yes")
+
+
+def _safe_preview(text: Optional[str], limit: int = 200) -> str:
+    if not text:
+        return ""
+    t = text.replace("\n", "\\n")
+    return t[:limit] + ("..." if len(t) > limit else "")
+
+
+def _hash_payload(payload: Any) -> str:
+    raw = json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
+
+
+@dataclass(frozen=True)
+class ResolvedAuth:
+    api_key: str
+    base_url: Optional[str]
+    model: str
+    organization: Optional[str] = None
+    project: Optional[str] = None
+    api_version: Optional[str] = None
+    is_azure: bool = False