praxicraft-shared 0.6.0__tar.gz

praxicraft_shared-0.6.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: praxicraft-shared
+Version: 0.6.0
+Summary: Stateless cross-product Python utilities for Praxicraft backends
+Author: Praxicraft
+License: Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Requires-Dist: boto3>=1.34.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# praxicraft-shared
+
+Stateless Python utilities shared by Praxicraft backends (Practice, auth, notifications, and future services). Products pin a **git tag**; no Django ORM, settings, or product business logic lives here.
+
+**Planning & milestones:** [`Gamified-Application/docs/praxicraft-shared/README.md`](https://github.com/praxicraft-platform/praxicraft-practice/blob/staging/docs/praxicraft-shared/README.md)
+
+## Prerequisites
+
+- Python 3.11+
+- GitHub access to this private repo (install via HTTPS + token)
+
+## Install (in a product)
+
+```text
+praxicraft-shared @ git+https://github.com/praxicraft-platform/praxicraft-shared@v0.6.0
+```
+
+Builds need a token with `contents:read` (CI: `PRAXICRAFT_GH_TOKEN`).
+
+Local editable (sibling checkout):
+
+```bash
+pip install -e ~/Desktop/praxicraft-shared
+```
+
+## Local development
+
+```bash
+cd ~/Desktop/praxicraft-shared
+pip install -e ".[dev]"
+ruff check src tests
+pytest
+```
+
+## What’s in the package
+
+| Module | Role |
+| --- | --- |
+| `jwt_utils` | Validate RS256 access JWTs (JWKS / PEM) |
+| `auth_client` | HTTP client for `praxicraft-auth` (token exchange, me, …) |
+| `billing_client` | HTTP client for `praxicraft-billing` (entitlements, checkout, cancel/resume) |
+| `s3_client` | Injectable MinIO/S3 helpers (`make_s3_client`, put/get/presign, prefix download) |
+| `notifications_client` | HTTP client for praxicraft-notifications internal send |
+| `service_token` | Parse `product:token` / JSON service-token maps (no DRF) |
+| `ai_service` | Thin client for `praxicraft-llm` (gateway + circuit-breaker fallback) |
+| `error_envelope` | Standard success/error dict shapes |
+| `events` | Event envelope helpers + `events/SCHEMA.md` |
+| `email/` | Shared HTML/text email templates (rendered by notifications) |
+| `secret_crypto` | Fernet encrypt/decrypt (inject key) |
+| `work_email` | Email normalize / consumer-domain helpers |
+| `hibp` | Have I Been Pwned password check |
+
+Not shipped yet (planned): `org_client` (after auth A7).
+
+## Hard rules
+
+1. Stateless — no Django models, ORM, Celery, or package-owned Redis singletons  
+2. No `django.conf.settings` — callers inject URLs and keys  
+3. No product logic (XP, Assess scoring, Tutor mastery)  
+4. Semver via git tags — breaking JWT/auth contracts = major bump  
+
+## Related
+
+- [praxicraft-auth](https://github.com/praxicraft-platform/praxicraft-auth)  
+- [praxicraft-notifications](https://github.com/praxicraft-platform/praxicraft-notifications)  
+- [praxicraft-llm](https://github.com/praxicraft-platform/praxicraft-llm)  

praxicraft_shared-0.6.0/README.md

@@ -0,0 +1,66 @@
+# praxicraft-shared
+
+Stateless Python utilities shared by Praxicraft backends (Practice, auth, notifications, and future services). Products pin a **git tag**; no Django ORM, settings, or product business logic lives here.
+
+**Planning & milestones:** [`Gamified-Application/docs/praxicraft-shared/README.md`](https://github.com/praxicraft-platform/praxicraft-practice/blob/staging/docs/praxicraft-shared/README.md)
+
+## Prerequisites
+
+- Python 3.11+
+- GitHub access to this private repo (install via HTTPS + token)
+
+## Install (in a product)
+
+```text
+praxicraft-shared @ git+https://github.com/praxicraft-platform/praxicraft-shared@v0.6.0
+```
+
+Builds need a token with `contents:read` (CI: `PRAXICRAFT_GH_TOKEN`).
+
+Local editable (sibling checkout):
+
+```bash
+pip install -e ~/Desktop/praxicraft-shared
+```
+
+## Local development
+
+```bash
+cd ~/Desktop/praxicraft-shared
+pip install -e ".[dev]"
+ruff check src tests
+pytest
+```
+
+## What’s in the package
+
+| Module | Role |
+| --- | --- |
+| `jwt_utils` | Validate RS256 access JWTs (JWKS / PEM) |
+| `auth_client` | HTTP client for `praxicraft-auth` (token exchange, me, …) |
+| `billing_client` | HTTP client for `praxicraft-billing` (entitlements, checkout, cancel/resume) |
+| `s3_client` | Injectable MinIO/S3 helpers (`make_s3_client`, put/get/presign, prefix download) |
+| `notifications_client` | HTTP client for praxicraft-notifications internal send |
+| `service_token` | Parse `product:token` / JSON service-token maps (no DRF) |
+| `ai_service` | Thin client for `praxicraft-llm` (gateway + circuit-breaker fallback) |
+| `error_envelope` | Standard success/error dict shapes |
+| `events` | Event envelope helpers + `events/SCHEMA.md` |
+| `email/` | Shared HTML/text email templates (rendered by notifications) |
+| `secret_crypto` | Fernet encrypt/decrypt (inject key) |
+| `work_email` | Email normalize / consumer-domain helpers |
+| `hibp` | Have I Been Pwned password check |
+
+Not shipped yet (planned): `org_client` (after auth A7).
+
+## Hard rules
+
+1. Stateless — no Django models, ORM, Celery, or package-owned Redis singletons  
+2. No `django.conf.settings` — callers inject URLs and keys  
+3. No product logic (XP, Assess scoring, Tutor mastery)  
+4. Semver via git tags — breaking JWT/auth contracts = major bump  
+
+## Related
+
+- [praxicraft-auth](https://github.com/praxicraft-platform/praxicraft-auth)  
+- [praxicraft-notifications](https://github.com/praxicraft-platform/praxicraft-notifications)  
+- [praxicraft-llm](https://github.com/praxicraft-platform/praxicraft-llm)  

praxicraft_shared-0.6.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "praxicraft-shared"
+version = "0.6.0"
+description = "Stateless cross-product Python utilities for Praxicraft backends"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+authors = [{ name = "Praxicraft" }]
+dependencies = [
+  "cryptography>=42.0.0",
+  "requests>=2.32.0",
+  "PyJWT[crypto]>=2.8.0",
+  "boto3>=1.34.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+praxicraft_shared = [
+  "events/SCHEMA.md",
+  "email/*.html",
+  "email/*.txt",
+  "email/partials/*.html",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

praxicraft_shared-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

praxicraft_shared-0.6.0/src/praxicraft_shared/__init__.py

@@ -0,0 +1,3 @@
+"""Praxicraft shared utilities — stateless only. No Django/ORM."""
+
+__version__ = "0.6.0"

praxicraft_shared-0.6.0/src/praxicraft_shared/ai_service.py

@@ -0,0 +1,478 @@
+"""Thin LLM client for products (P5 / S-ai).
+
+Gateway-first when ``llm_gateway_url`` is set (OpenAI-compatible LiteLLM).
+On gateway failure, opens a circuit and optionally calls an injectable
+``direct_fallback`` so products keep working without a central SPOF.
+
+Stateless: pass config; never import ``django.conf.settings``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = 120.0
+CIRCUIT_FAILURE_THRESHOLD = 3
+CIRCUIT_OPEN_SECONDS = 60.0
+
+DirectSync = Callable[..., str]
+DirectStream = Callable[..., Iterator[str]]
+DirectAssistant = Callable[..., dict[str, Any]]
+
+
+class AIDisabledError(Exception):
+    """AI features disabled or missing credentials."""
+
+
+class AIProviderError(Exception):
+    """Gateway or provider call failed."""
+
+
+@dataclass
+class AIConfig:
+    """Injectable AI routing config (no Django settings)."""
+
+    enabled: bool = True
+    llm_gateway_url: str = ""
+    llm_service_key: str = ""
+    provider: str = "openai"
+    model: str = "gpt-4o-mini"
+    api_key: str = ""
+    product: str = "practice"
+    timeout: float = DEFAULT_TIMEOUT
+    # Optional Redis-like get/set for shared circuit state across workers.
+    # Signatures: get(key) -> str|None ; set(key, value, ex=seconds)
+    circuit_get: Callable[[str], str | None] | None = None
+    circuit_set: Callable[..., None] | None = None
+    circuit_key: str = "praxicraft:circuit:llm-gateway"
+
+
+@dataclass
+class _CircuitState:
+    failures: int = 0
+    opened_at: float = 0.0
+
+
+_local_circuit = _CircuitState()
+
+
+def _circuit_is_open(cfg: AIConfig) -> bool:
+    if cfg.circuit_get is not None:
+        raw = cfg.circuit_get(cfg.circuit_key)
+        if not raw:
+            return False
+        try:
+            opened_at = float(raw)
+        except ValueError:
+            return False
+        # Wall-clock: monotonic cannot be shared across workers via Redis.
+        return (time.time() - opened_at) < CIRCUIT_OPEN_SECONDS
+    if _local_circuit.opened_at <= 0:
+        return False
+    if (time.monotonic() - _local_circuit.opened_at) >= CIRCUIT_OPEN_SECONDS:
+        _local_circuit.failures = 0
+        _local_circuit.opened_at = 0.0
+        return False
+    return True
+
+
+def _circuit_record_failure(cfg: AIConfig) -> None:
+    if cfg.circuit_get is not None and cfg.circuit_set is not None:
+        count_key = f"{cfg.circuit_key}:count"
+        raw = cfg.circuit_get(count_key) or "0"
+        try:
+            failures = int(raw) + 1
+        except ValueError:
+            failures = 1
+        cfg.circuit_set(count_key, str(failures), ex=int(CIRCUIT_OPEN_SECONDS))
+        if failures >= CIRCUIT_FAILURE_THRESHOLD:
+            cfg.circuit_set(
+                cfg.circuit_key,
+                str(time.time()),
+                ex=int(CIRCUIT_OPEN_SECONDS),
+            )
+            logger.warning("praxicraft-llm circuit opened (shared)")
+        return
+    _local_circuit.failures += 1
+    if _local_circuit.failures >= CIRCUIT_FAILURE_THRESHOLD:
+        _local_circuit.opened_at = time.monotonic()
+        logger.warning("praxicraft-llm circuit opened (local)")
+
+
+def _circuit_record_success(cfg: AIConfig) -> None:
+    _local_circuit.failures = 0
+    _local_circuit.opened_at = 0.0
+    if cfg.circuit_set is not None:
+        try:
+            cfg.circuit_set(cfg.circuit_key, "", ex=1)
+            cfg.circuit_set(f"{cfg.circuit_key}:count", "0", ex=1)
+        except Exception:
+            pass
+
+
+def _gateway_base(cfg: AIConfig) -> str:
+    return cfg.llm_gateway_url.rstrip("/")
+
+
+def _gateway_headers(
+    cfg: AIConfig,
+    *,
+    product: str,
+    user_id: str,
+    task_type: str,
+) -> dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {cfg.llm_service_key}",
+        "Content-Type": "application/json",
+        "X-Praxicraft-Product": product or cfg.product or "practice",
+        "X-Praxicraft-Task-Type": task_type or "default",
+    }
+    if user_id:
+        headers["X-Praxicraft-User-ID"] = user_id
+    return headers
+
+
+def _chat_url(cfg: AIConfig) -> str:
+    base = _gateway_base(cfg)
+    if base.endswith("/v1"):
+        return f"{base}/chat/completions"
+    return urljoin(base + "/", "v1/chat/completions")
+
+
+def _should_use_gateway(cfg: AIConfig) -> bool:
+    return bool(cfg.llm_gateway_url.strip() and cfg.llm_service_key.strip())
+
+
+def _gateway_misconfigured(cfg: AIConfig) -> bool:
+    """URL set without service key — fail closed (do not silently call providers)."""
+    return bool(cfg.llm_gateway_url.strip()) and not bool(cfg.llm_service_key.strip())
+
+
+# HTTP statuses that open the circuit (outage). Client errors like 401/429 do not.
+_CIRCUIT_STATUSES = frozenset({502, 503, 504})
+
+
+def _gateway_chat(
+    cfg: AIConfig,
+    *,
+    messages: list[dict[str, Any]],
+    model: str,
+    max_tokens: int,
+    temperature: float | None,
+    product: str,
+    user_id: str,
+    task_type: str,
+    tools: list[dict] | None = None,
+    stream: bool = False,
+) -> Any:
+    body: dict[str, Any] = {
+        "model": model,
+        "messages": messages,
+        "max_tokens": max_tokens,
+        "stream": stream,
+    }
+    if temperature is not None:
+        body["temperature"] = temperature
+    if tools:
+        body["tools"] = tools
+
+    try:
+        resp = requests.post(
+            _chat_url(cfg),
+            headers=_gateway_headers(
+                cfg, product=product, user_id=user_id, task_type=task_type
+            ),
+            json=body,
+            timeout=cfg.timeout,
+            stream=stream,
+        )
+    except requests.RequestException as exc:
+        _circuit_record_failure(cfg)
+        raise AIProviderError(f"llm gateway transport error: {exc}") from exc
+
+    if resp.status_code in _CIRCUIT_STATUSES:
+        _circuit_record_failure(cfg)
+        raise AIProviderError(f"llm gateway unavailable ({resp.status_code})")
+    if resp.status_code >= 400:
+        # 401/429/budget: surface error; do not open circuit (would force direct burn)
+        raise AIProviderError(f"llm gateway error ({resp.status_code}): {resp.text[:300]}")
+
+    _circuit_record_success(cfg)
+    return resp
+
+
+def get_ai_response(
+    cfg: AIConfig,
+    system_prompt: str,
+    user_prompt: str = "",
+    max_tokens: int = 1024,
+    messages: list | None = None,
+    model: str | None = None,
+    temperature: float | None = None,
+    cache_stable_system: str | None = None,
+    *,
+    product: str | None = None,
+    user_id: str = "",
+    task_type: str = "default",
+    direct_fallback: DirectSync | None = None,
+) -> str:
+    """Sync completion via gateway (preferred) or injectable direct fallback."""
+    if not cfg.enabled:
+        raise AIDisabledError("AI features are disabled.")
+
+    if _gateway_misconfigured(cfg):
+        raise AIDisabledError(
+            "LLM_GATEWAY_URL is set but PRAXICRAFT_LLM_SERVICE_KEY is missing."
+        )
+
+    resolved_model = (model or cfg.model).strip()
+    product_name = (product or cfg.product or "practice").strip()
+
+    if messages is None:
+        messages = [{"role": "user", "content": user_prompt}]
+
+    merged_system = (
+        f"{cache_stable_system}\n\n{system_prompt}" if cache_stable_system else system_prompt
+    )
+    openai_messages = [{"role": "system", "content": merged_system}, *messages]
+
+    use_gw = _should_use_gateway(cfg) and not _circuit_is_open(cfg)
+    if use_gw:
+        try:
+            resp = _gateway_chat(
+                cfg,
+                messages=openai_messages,
+                model=resolved_model,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                product=product_name,
+                user_id=user_id,
+                task_type=task_type,
+                stream=False,
+            )
+            data = resp.json()
+            return str(data["choices"][0]["message"]["content"] or "")
+        except (AIProviderError, KeyError, ValueError, TypeError) as exc:
+            logger.warning("gateway get_ai_response failed: %s", exc)
+            # Budget/auth client errors: do not burn direct key unless circuit/outage
+            msg = str(exc)
+            if "llm gateway error (429)" in msg or "llm gateway error (401)" in msg:
+                raise AIProviderError(msg) from exc
+            if direct_fallback is None:
+                raise AIProviderError(str(exc)) from exc
+            # fall through to direct
+        except Exception as exc:
+            _circuit_record_failure(cfg)
+            logger.warning("gateway get_ai_response unexpected: %s", exc)
+            if direct_fallback is None:
+                raise AIProviderError(str(exc)) from exc
+
+    if _should_use_gateway(cfg) and _circuit_is_open(cfg) and direct_fallback is not None:
+        logger.warning("praxicraft-llm circuit open; using direct fallback")
+
+    if direct_fallback is not None:
+        return direct_fallback(
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            max_tokens=max_tokens,
+            messages=messages,
+            model=resolved_model,
+            temperature=temperature,
+            cache_stable_system=cache_stable_system,
+        )
+
+    if not cfg.api_key:
+        raise AIDisabledError("AI_API_KEY is not configured and no gateway/fallback available.")
+    raise AIProviderError("no gateway response and no direct_fallback configured")
+
+
+def stream_ai_response(
+    cfg: AIConfig,
+    system_prompt: str,
+    user_prompt: str = "",
+    max_tokens: int = 1024,
+    messages: list | None = None,
+    model: str | None = None,
+    cache_stable_system: str | None = None,
+    *,
+    product: str | None = None,
+    user_id: str = "",
+    task_type: str = "default",
+    temperature: float | None = None,
+    direct_fallback: DirectStream | None = None,
+) -> Iterator[str]:
+    """Stream text deltas via gateway SSE or injectable direct fallback."""
+    if not cfg.enabled:
+        raise AIDisabledError("AI features are disabled.")
+
+    if _gateway_misconfigured(cfg):
+        raise AIDisabledError(
+            "LLM_GATEWAY_URL is set but PRAXICRAFT_LLM_SERVICE_KEY is missing."
+        )
+
+    resolved_model = (model or cfg.model).strip()
+    product_name = (product or cfg.product or "practice").strip()
+
+    if messages is None:
+        messages = [{"role": "user", "content": user_prompt}]
+
+    merged_system = (
+        f"{cache_stable_system}\n\n{system_prompt}" if cache_stable_system else system_prompt
+    )
+    openai_messages = [{"role": "system", "content": merged_system}, *messages]
+
+    use_gw = _should_use_gateway(cfg) and not _circuit_is_open(cfg)
+    if use_gw:
+        try:
+            resp = _gateway_chat(
+                cfg,
+                messages=openai_messages,
+                model=resolved_model,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                product=product_name,
+                user_id=user_id,
+                task_type=task_type,
+                stream=True,
+            )
+            yielded = False
+            for line in resp.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                if line.startswith("data: "):
+                    payload = line[6:].strip()
+                    if payload == "[DONE]":
+                        break
+                    try:
+                        chunk = json.loads(payload)
+                        delta = chunk["choices"][0].get("delta") or {}
+                        text = delta.get("content") or ""
+                        if text:
+                            yielded = True
+                            yield text
+                    except (KeyError, ValueError, TypeError, IndexError):
+                        continue
+            if yielded:
+                return
+            raise AIProviderError("gateway stream returned no content")
+        except AIProviderError as exc:
+            logger.warning("gateway stream failed: %s", exc)
+            msg = str(exc)
+            if "llm gateway error (429)" in msg or "llm gateway error (401)" in msg:
+                raise
+            if direct_fallback is None:
+                raise
+        except Exception as exc:
+            _circuit_record_failure(cfg)
+            logger.warning("gateway stream unexpected: %s", exc)
+            if direct_fallback is None:
+                raise AIProviderError(str(exc)) from exc
+
+    if direct_fallback is not None:
+        yield from direct_fallback(
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            max_tokens=max_tokens,
+            messages=messages,
+            model=resolved_model,
+            cache_stable_system=cache_stable_system,
+        )
+        return
+
+    raise AIProviderError("no gateway stream and no direct_fallback configured")
+
+
+def get_ai_assistant_turn(
+    cfg: AIConfig,
+    system_prompt: str,
+    messages: list[dict],
+    tools: list[dict] | None = None,
+    max_tokens: int = 1024,
+    model: str | None = None,
+    temperature: float | None = None,
+    *,
+    product: str | None = None,
+    user_id: str = "",
+    task_type: str = "assistant",
+    direct_fallback: DirectAssistant | None = None,
+) -> dict[str, Any]:
+    """Tool-capable chat turn via gateway or injectable fallback."""
+    if not cfg.enabled:
+        raise AIDisabledError("AI features are disabled.")
+
+    if _gateway_misconfigured(cfg):
+        raise AIDisabledError(
+            "LLM_GATEWAY_URL is set but PRAXICRAFT_LLM_SERVICE_KEY is missing."
+        )
+
+    resolved_model = (model or cfg.model).strip()
+    product_name = (product or cfg.product or "practice").strip()
+    openai_messages = [{"role": "system", "content": system_prompt}, *messages]
+
+    use_gw = _should_use_gateway(cfg) and not _circuit_is_open(cfg)
+    if use_gw:
+        try:
+            resp = _gateway_chat(
+                cfg,
+                messages=openai_messages,
+                model=resolved_model,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                product=product_name,
+                user_id=user_id,
+                task_type=task_type,
+                tools=tools,
+                stream=False,
+            )
+            data = resp.json()
+            choice = data["choices"][0]
+            msg = choice.get("message") or {}
+            finish = choice.get("finish_reason") or "stop"
+            payload = {
+                "role": msg.get("role") or "assistant",
+                "content": msg.get("content") or "",
+            }
+            if msg.get("tool_calls"):
+                payload["tool_calls"] = msg["tool_calls"]
+                if finish == "stop":
+                    finish = "tool_calls"
+            return {"message": payload, "finish_reason": finish}
+        except (AIProviderError, KeyError, ValueError, TypeError) as exc:
+            logger.warning("gateway assistant turn failed: %s", exc)
+            msg = str(exc)
+            if "llm gateway error (429)" in msg or "llm gateway error (401)" in msg:
+                raise AIProviderError(msg) from exc
+            if direct_fallback is None:
+                raise AIProviderError(str(exc)) from exc
+        except Exception as exc:
+            _circuit_record_failure(cfg)
+            if direct_fallback is None:
+                raise AIProviderError(str(exc)) from exc
+
+    if direct_fallback is not None:
+        return direct_fallback(
+            system_prompt=system_prompt,
+            messages=messages,
+            tools=tools,
+            max_tokens=max_tokens,
+            model=resolved_model,
+            temperature=temperature,
+        )
+
+    raise AIProviderError("no gateway assistant turn and no direct_fallback configured")
+
+
+# Test helper — reset process-local circuit
+def _reset_circuit_for_tests() -> None:
+    global _local_circuit
+    _local_circuit = _CircuitState()