guardianhub 0.1.88__py3-none-any.whl

guardianhub/observability/otel_middlewares.py

@@ -0,0 +1,73 @@
+from typing import Optional
+
+from fastapi import Request
+from opentelemetry import baggage
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.propagate import extract
+from opentelemetry.sdk.trace import SpanProcessor
+from opentelemetry.sdk.trace.sampling import (
+    Sampler,
+    SamplingResult,
+    Decision,
+)
+from opentelemetry.trace import Span
+
+
+async def bind_otel_context(request: Request, call_next):
+    # 1️⃣ Extract OTEL context from headers
+    ctx = extract(request.headers)
+
+    # 2️⃣ Attach context so downstream sees it
+    with trace.use_span(trace.get_current_span(ctx), end_on_exit=False):
+        return await call_next(request)
+
+
+class GuardianHubSampler(Sampler):
+    """
+    Drops low-level ASGI spans (http receive/send)
+    Keeps route, agent, and custom spans.
+    """
+
+    def should_sample(
+        self,
+        parent_context,
+        trace_id,
+        name,
+        kind=None,
+        attributes=None,
+        links=None,
+    ) -> SamplingResult:
+
+        lname = (name or "").lower()
+
+        if "http receive" in lname or "http send" in lname:
+            return SamplingResult(Decision.DROP)
+
+        return SamplingResult(Decision.RECORD_AND_SAMPLE)
+
+    def get_description(self) -> str:
+        return "GuardianHub Sampler (drop ASGI receive/send)"
+
+class BaggageToSpanProcessor(SpanProcessor):
+    """
+    Copies selected baggage values into span attributes
+    so they appear on every span.
+    """
+
+    BAGGAGE_KEYS = (
+        "user_id",
+        "session_id",
+    )
+
+    def on_start( self,
+        span: Span,
+        parent_context: Optional[Context] = None,
+    ) -> None:
+        for key in self.BAGGAGE_KEYS:
+            value = baggage.get_baggage(key, parent_context)
+            if value is not None:
+                span.set_attribute(key, str(value))
+
+    def on_end(self, span):
+        pass

guardianhub/prompts/base.py

@@ -0,0 +1,7 @@
+from typing import Optional, Dict, Any
+from abc import ABC, abstractmethod
+
+class PromptProvider(ABC):
+    @abstractmethod
+    async def get_prompt(self, name: str, version: Optional[str] = None) -> Dict[str, Any]:
+        pass

guardianhub/prompts/providers/langfuse_provider.py

@@ -0,0 +1,13 @@
+class Langfuse:
+    def __init__(self, secret_key: str, host: str):
+        self.secret_key = secret_key
+        self.host = host
+from typing import Optional, Dict, Any
+from ..base import PromptProvider
+class LangfusePromptProvider(PromptProvider):
+    def __init__(self, api_key: str, host: str):
+        self.client = Langfuse(secret_key=api_key, host=host)
+
+    async def get_prompt(self, name: str, version: Optional[str] = None) -> Dict[str, Any]:
+        prompt = self.client.get_prompt(name=name, version=version)
+        return prompt.to_dict()

guardianhub/prompts/providers/local_provider.py

@@ -0,0 +1,22 @@
+import yaml, os
+from typing import Optional, Dict, Any
+
+
+class LocalPromptProvider(PromptProvider):
+    def __init__(self, directory: str):
+        self.directory = directory
+
+    async def get_prompt(self, name: str, version: Optional[str] = None) -> Dict[str, Any]:
+        filename = f"{name}.yaml"
+        path = os.path.join(self.directory, filename)
+
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"Prompt '{name}' not found locally")
+
+        with open(path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if version and "versions" in data:
+            return data["versions"].get(version)
+
+        return data

guardianhub/prompts/registry.py

@@ -0,0 +1,14 @@
+from typing import Optional, List
+from .base import PromptProvider
+
+class PromptRegistry:
+    def __init__(self, providers: List[PromptProvider]):
+        self.providers = providers
+
+    async def get_prompt(self, name: str, version: Optional[str] = None):
+        for provider in self.providers:
+            try:
+                return await provider.get_prompt(name, version)
+            except:
+                continue
+        raise ValueError(f"Prompt '{name}' not found in any provider")

guardianhub/scripts/script.sh

@@ -0,0 +1,31 @@
+pip install hatch
+
+rm -rf dist
+poetry version 0.1.15
+hatch build
+git tag v0.1.15
+git push --tags
+
+
+
+poetry env remove python3.13
+rm -rf ~/.cache/pypoetry
+rm -rf ~/.local/share/pypoetry
+
+
+curl -sSL https://install.python-poetry.org | python3 -
+
+
+poetry config virtualenvs.in-project true
+poetry config virtualenvs.create true
+poetry config virtualenvs.prefer-active-python true
+
+python3.13 -m venv .venv
+source .venv/bin/activate
+
+poetry install
+
+
+
+
+./scripts/bump_version.sh patch

guardianhub/services/base.py

@@ -0,0 +1,15 @@
+# guardianhub_sdk/services/base.py
+from typing import Optional
+from guardianhub import get_logger
+
+class BaseServiceClient:
+    def __init__(self, base_url: str, token_provider=None, logger_name: Optional[str] = None):
+        self.base_url = base_url.rstrip('/')
+        self.token_provider = token_provider
+        self.logger = get_logger(logger_name or __name__)
+
+    async def _auth_headers(self) -> dict:
+        if not self.token_provider:
+            return {}
+        token = await self.token_provider.get_token()
+        return {"Authorization": f"Bearer {token}"}

guardianhub/tools/gh_registry_cli.py

@@ -0,0 +1,171 @@
+# guardianhub_sdk/tools/gh_registry_cli.py
+import argparse
+import json
+import os
+import sys
+import tempfile
+import shutil
+import hashlib
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+import httpx
+
+from ..models.registry.signing import generate_rsa_keypair, sign_metadata_dict
+from guardianhub import get_logger
+
+logger = get_logger(__name__)
+
+def compute_sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def pack_directory_to_zip(src: Path, dest: Path) -> None:
+    """
+    Create a zip artifact containing the src directory contents.
+    This is a lightweight 'wheel-like' artifact (not a proper wheel) but suitable
+    for the registry loader that accepts zipped source.
+    """
+    import zipfile
+    with zipfile.ZipFile(dest, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        base = src.resolve()
+        for p in sorted(src.rglob("*")):
+            arcname = p.relative_to(base)
+            zf.write(p, arcname)
+
+
+def pack_module_to_archive(source_path: Path, artifact_path: Path) -> None:
+    """
+    If source_path is a .py file -> zip it; if directory -> zip contents; if tar/wheel requested, you can extend.
+    """
+    if source_path.is_file() and source_path.suffix == ".py":
+        # create zip with single file at top-level
+        import zipfile
+        with zipfile.ZipFile(artifact_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            zf.write(source_path, source_path.name)
+    elif source_path.is_dir():
+        pack_directory_to_zip(source_path, artifact_path)
+    else:
+        raise ValueError("Unsupported source path for packing: %s" % source_path)
+
+
+def create_metadata(name: str, version: str, artifact_filename: str, sha256: str, module: Optional[str] = None, class_name: Optional[str] = None) -> Dict[str, Any]:
+    meta = {
+        "name": name,
+        "version": version,
+        "artifact_filename": artifact_filename,
+        "sha256": sha256,
+    }
+    if module:
+        meta["module"] = module
+    if class_name:
+        meta["class"] = class_name
+    return meta
+
+
+def upload_artifact(registry_base: str, artifact_path: Path, metadata_signed: Dict[str, Any], api_key: Optional[str] = None) -> httpx.Response:
+    """
+    POST artifact and metadata to registry. Assumes registry has an endpoint:
+       POST {registry_base}/models/{name}/{version}/upload
+    which accepts multipart/form-data:
+       - file -> artifact
+       - metadata -> metadata json
+    """
+    name = metadata_signed["name"]
+    version = metadata_signed["version"]
+    url = registry_base.rstrip("/") + f"/models/{name}/{version}/upload"
+    headers = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    with open(artifact_path, "rb") as af:
+        files = {
+            "file": (artifact_path.name, af, "application/octet-stream"),
+            "metadata": (None, json.dumps(metadata_signed), "application/json"),
+        }
+        resp = httpx.post(url, files=files, headers=headers, timeout=60)
+    resp.raise_for_status()
+    return resp
+
+
+def cli_pack_sign_publish(args):
+    src = Path(args.source).resolve()
+    if not src.exists():
+        logger.error("Source path does not exist: %s", src)
+        sys.exit(2)
+
+    tmpdir = Path(tempfile.mkdtemp(prefix="gh_pack_"))
+    try:
+        artifact_name = f"{args.name}-{args.version}.zip"
+        artifact_path = tmpdir / artifact_name
+        pack_module_to_archive(src, artifact_path)
+        sha256 = compute_sha256(artifact_path)
+        logger.info("Packed artifact at %s (sha256=%s)", artifact_path, sha256)
+
+        # load/generate signing key
+        if args.private_key:
+            private_key_path = Path(args.private_key)
+            private_pem = private_key_path.read_bytes()
+        else:
+            # generate ephemeral keys (not recommended for production)
+            private_pem, public_pem = generate_rsa_keypair()
+            logger.warning("Generated ephemeral RSA keypair (use persistent KMS key in prod)")
+        metadata = create_metadata(args.name, args.version, artifact_name, sha256, module=args.module, class_name=args.class_name)
+        metadata_signed = sign_metadata_dict(private_pem, metadata)
+
+        if args.registry:
+            resp = upload_artifact(args.registry, artifact_path, metadata_signed, api_key=args.api_key)
+            logger.info("Upload response: %s", resp.text)
+        else:
+            # local output: write artifact + metadata
+            out_dir = Path(args.out_dir or ".").resolve()
+            out_dir.mkdir(parents=True, exist_ok=True)
+            final_artifact = out_dir / artifact_name
+            shutil.copy(str(artifact_path), str(final_artifact))
+            meta_file = out_dir / f"{args.name}-{args.version}.metadata.json"
+            meta_file.write_text(json.dumps(metadata_signed, indent=2))
+            logger.info("Wrote artifact %s and metadata %s", final_artifact, meta_file)
+
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="gh-registry-cli")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    pack = sub.add_parser("publish", help="Pack, sign and publish artifact")
+    pack.add_argument("--source", required=True, help="Path to module file (.py) or package directory")
+    pack.add_argument("--name", required=True, help="Model logical name")
+    pack.add_argument("--version", required=True, help="Model version (semver recommended)")
+    pack.add_argument("--module", required=False, help="Module path inside artifact (optional)")
+    pack.add_argument("--class-name", dest="class_name", required=False, help="Class name exported (optional)")
+    pack.add_argument("--private-key", required=False, help="Path to private PEM to sign metadata (optional). If absent, ephemeral key is generated (unsafe).")
+    pack.add_argument("--registry", required=False, help="Registry base url to upload to. If omitted, write to --out-dir")
+    pack.add_argument("--api-key", required=False, help="Registry API key")
+    pack.add_argument("--out-dir", required=False, help="Local output directory when --registry omitted")
+
+    genkey = sub.add_parser("gen-keys", help="Generate RSA keypair for signing")
+    genkey.add_argument("--out-private", required=True)
+    genkey.add_argument("--out-public", required=True)
+    genkey.add_argument("--bits", type=int, default=4096)
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "publish":
+        cli_pack_sign_publish(args)
+    elif args.cmd == "gen-keys":
+        priv, pub = generate_rsa_keypair(bits=args.bits)
+        Path(args.out_private).write_bytes(priv)
+        Path(args.out_public).write_bytes(pub)
+        logger.info("Wrote keypair to %s / %s", args.out_private, args.out_public)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

guardianhub/utils/app_state.py

@@ -0,0 +1,74 @@
+# guardian/app_state.py
+#
+# A simple singleton class for managing application-wide state.
+# This ensures that all parts of the application can access a single,
+# consistent state object.
+
+class AppState:
+    """
+    Manages a global, application-wide state using the singleton pattern.
+    """
+    _instance = None
+    _state = {}
+
+    def __new__(cls):
+        """
+        Ensures only a single instance of AppState exists.
+        """
+        if cls._instance is None:
+            cls._instance = super(AppState, cls).__new__(cls)
+        return cls._instance
+
+    def set(self, key, value):
+        """
+        Sets a key-value pair in the global state.
+        """
+        self._state[key] = value
+
+    def get(self, key, default=None):
+        """
+        Retrieves a value from the global state.
+        """
+        return self._state.get(key, default)
+
+    def increment(self, key, value=1):
+        """
+        Increments a numeric value in the global state.
+        
+        Args:
+            key: The key of the value to increment
+            value: The amount to increment by (default: 1)
+            
+        Returns:
+            The new value after incrementing
+        """
+        current = self._state.get(key, 0)
+        if not isinstance(current, (int, float)):
+            current = 0
+        new_value = current + value
+        self._state[key] = new_value
+        return new_value
+
+    def decrement(self, key, value=1):
+        """
+        Decrements a numeric value in the global state.
+        
+        Args:
+            key: The key of the value to decrement
+            value: The amount to decrement by (default: 1)
+            
+        Returns:
+            The new value after decrementing
+        """
+        current = self._state.get(key, 0)
+        if not isinstance(current, (int, float)):
+            current = 0
+        new_value = current - value
+        self._state[key] = new_value
+        return new_value
+
+    def __repr__(self):
+        """
+        Provides a string representation of the current state.
+        """
+        return f"AppState(state={self._state})"

guardianhub/utils/fastapi_utils.py

@@ -0,0 +1,152 @@
+"""Standardized FastAPI utilities for GuardianHub Microservices."""
+import uuid
+import time
+from datetime import datetime
+from typing import Any, Dict
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+
+from guardianhub.config.settings import settings
+from guardianhub.logging.logging import get_logger
+from guardianhub.observability.instrumentation import configure_instrumentation
+from .app_state import AppState
+from .metrics import setup_metrics, get_metrics_registry
+
+logger = get_logger(__name__)
+
+def initialize_guardian_app(app: FastAPI) -> None:
+    """
+    The 'Golden Path' for service initialization.
+
+    This single call handles:
+    1. Settings & Env discovery
+    2. OpenTelemetry Tracing (Incoming & Outgoing)
+    3. Prometheus Metrics setup
+    4. Custom GuardianHub Middleware (Tracing, Timing, Logging)
+    5. Standardized Health & Metrics endpoints
+    """
+    # 1. Initialize App State
+    app_state = AppState()
+    app_state.set("startup_time", datetime.now())
+    app.state.app_state = app_state
+
+    # Add this "Gold Standard" Startup Log
+    banner = f"""
+        ╔════════════════════════════════════════════════════════════════╗
+        ║  GUARDIANHUB SDK INITIALIZED                                   ║
+        ╠════════════════════════════════════════════════════════════════╣
+        ║ SERVICE:     {settings.service.name:<49} ║
+        ║ ENVIRONMENT: {settings.endpoints.ENVIRONMENT:<49} ║
+        ║ OTEL ENDPT:  {settings.endpoints.OTEL_EXPORTER_OTLP_ENDPOINT:<49} ║
+        ║ LANGFUSE_OTLP_TRACES_ENDPOINT:  {settings.endpoints.LANGFUSE_OTLP_TRACES_ENDPOINT:<49} ║
+        ║ LANGFUSE_HOST:  {settings.endpoints.LANGFUSE_HOST:<49} ║
+        ╚════════════════════════════════════════════════════════════════╝
+        """
+    for line in banner.strip().split('\n'):
+        logger.info(line)
+
+    # 2. Configure OpenTelemetry (OTEL)
+    # Automatically uses settings.endpoints.OTEL_EXPORTER_OTLP_ENDPOINT
+    configure_instrumentation(app)
+
+    # 3. Setup Prometheus Metrics
+    metrics_map = setup_metrics(settings.service.name)
+
+    # 4. Add Standard Middleware
+    _add_standard_middleware(app, metrics_map, app_state)
+
+    # 5. Attach System Endpoints (/health, /metrics)
+    _attach_system_endpoints(app, app_state)
+
+    logger.info(f"GuardianHub Service [{settings.service.name}] successfully initialized.")
+
+def _add_standard_middleware(app: FastAPI, metrics: Dict[str, Any], app_state: AppState):
+    """Internal: Configures CORS and Observability logic."""
+
+    # CORS Logic - Pulling from our dynamic settings
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"], # Can be refined in settings.py later
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.middleware("http")
+    async def observability_middleware(request: Request, call_next):
+        # Skip logic for internal paths
+        if request.url.path in ["/health", "/metrics"]:
+            return await call_next(request)
+
+        # Start tracking
+        request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
+        start_time = time.time()
+
+        metrics['active_requests'].inc()
+        app_state.increment("active_requests")
+        app_state.increment("total_requests")
+
+        try:
+            response = await call_next(request)
+
+            # Calculate Duration
+            duration_ms = (time.time() - start_time) * 1000
+
+            # Update Prometheus
+            metrics['request_latency'].labels(
+                method=request.method,
+                endpoint=request.url.path
+            ).observe(duration_ms / 1000)
+
+            metrics['request_count'].labels(
+                method=request.method,
+                endpoint=request.url.path,
+                status_code=response.status_code
+            ).inc()
+
+            # Add Standard Headers
+            response.headers["X-Process-Time"] = f"{duration_ms:.2f}ms"
+            response.headers["X-Request-ID"] = request_id
+
+            logger.info(
+                f"{request.method} {request.url.path} | "
+                f"Status: {response.status_code} | "
+                f"Time: {duration_ms:.2f}ms"
+            )
+            return response
+
+        except Exception as e:
+            logger.error(f"Uncaught Exception in {request.url.path}: {str(e)}", exc_info=True)
+            raise
+        finally:
+            metrics['active_requests'].dec()
+            app_state.decrement("active_requests")
+
+def _attach_system_endpoints(app: FastAPI, app_state: AppState):
+    """Internal: Sets up the /health and /metrics routes."""
+
+    @app.get("/health", tags=["System"])
+    async def health():
+        startup_time = app_state.get("startup_time")
+        uptime = (datetime.now() - startup_time).total_seconds()
+        return {
+            "status": "healthy",
+            "service": settings.service.name,
+            "environment": settings.endpoints.ENVIRONMENT,
+            "version": settings.service.id.split('-')[-1], # Example version extraction
+            "uptime_seconds": int(uptime),
+            "stats": {
+                "active_requests": app_state.get("active_requests", 0),
+                "total_requests": app_state.get("total_requests", 0)
+            }
+        }
+
+    @app.get("/metrics", tags=["System"])
+    async def metrics():
+        registry = get_metrics_registry()
+        return Response(
+            content=generate_latest(registry),
+            media_type=CONTENT_TYPE_LATEST
+        )