guardianhub 0.1.88__py3-none-any.whl

guardianhub/__init__.py

@@ -0,0 +1,29 @@
+"""GuardianHub SDK - Unified SDK for Local AI Guardian
+
+This package provides core functionality for the GuardianHub platform,
+including logging, metrics, and FastAPI utilities.
+"""
+
+# Version
+from ._version import __version__  # version exported for users
+# Core functionality
+from .logging import get_logger, setup_logging
+from .observability.instrumentation import configure_instrumentation
+from .utils.app_state import AppState
+from .utils.fastapi_utils import initialize_guardian_app
+from .utils.metrics import setup_metrics, get_metrics_registry
+
+# Public API
+__all__ = [
+    # Version
+    "__version__",
+    
+    # Logging
+    "get_logger",
+    "setup_logging",
+
+    "AppState",
+    "setup_metrics","get_metrics_registry",
+    "setup_middleware","setup_health_endpoint","setup_metrics_endpoint",
+    "configure_instrumentation",
+]

guardianhub/_version.py

@@ -0,0 +1 @@
+__version__ = '0.1.87'

guardianhub/agents/runtime.py

@@ -0,0 +1,12 @@
+# guardianhub_sdk/agents/runtime.py
+from typing import Any, Dict
+
+
+class AgentRuntime:
+    def __init__(self, clients: Dict[str, Any]):
+        self.clients = clients
+
+
+    async def run(self, spec: Dict[str, Any]):
+        # stub: execute agent spec using clients
+        return {"status": "ok", "spec": spec}

guardianhub/auth/token_provider.py

@@ -0,0 +1,22 @@
+# guardianhub_sdk/auth/token_provider.py
+from typing import Optional
+
+
+class TokenProvider:
+
+
+    """Simple token provider stub. Replace with your vault/service account integration."""
+
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key
+        self._cached_token = api_key
+        self._expires_at = None
+
+
+    async def get_token(self) -> str:
+    # For server-to-server use, you may want to implement JWT/service-account exchange
+        if self._cached_token:
+            return self._cached_token
+        # fallback placeholder
+        return "placeholder"

guardianhub/clients/__init__.py

@@ -0,0 +1,2 @@
+from .vector_client import VectorClient
+from .llm_client import LLMClient

guardianhub/clients/classification_client.py

@@ -0,0 +1,52 @@
+"""Minio client with graceful error handling and connection management."""
+import logging
+from datetime import timedelta
+from typing import Optional, Union, Dict, Any
+
+import httpx
+
+from guardianhub.config.settings import settings
+from guardianhub.logging import get_logger
+logger = get_logger(__name__)
+class ClassificationClient:
+    """Minio client wrapper with graceful error handling."""
+
+    def __init__(self, base_url:str, poll_interval: int = 5, poll_timeout: int = 300):
+        self.initialized = False
+        self.client = None
+
+        try:
+            self.api_url = base_url.rstrip('/')
+            self.headers = {
+                "Accept": "application/json",
+            }
+            self.poll_interval = poll_interval
+            self.poll_timeout = poll_timeout
+
+            # Initialize the persistent httpx client here.
+            # DO NOT use it in an 'async with' block in methods, or it will be closed.
+            self.client = httpx.AsyncClient(headers=self.headers, base_url=self.api_url,
+                                            timeout=self.poll_timeout + 60)
+            self.initialized = True
+            logger.info(f"✅ Classification client connected to {settings.endpoints.CLASSIFICATION_ENDPOINT}")
+
+        except Exception as e:
+            logger.warning(
+                f"⚠️ Failed to initialize Classification client: {str(e)}. "
+                "Classification operations will be disabled."
+            )
+            self.initialized = False
+
+    async def classify(self, text: str,metadata:Dict[str, Any]) -> Dict[str, Any]:
+        """Generate a presigned URL for uploading an object."""
+        if not self.initialized:
+            logger.warning("Classification client not initialized, cannot generate presigned URL")
+            return {}
+
+        try:
+            response = await self.client.post("/v1/document/classify", json={"text": text, "metadata":metadata})
+            return response.json()
+
+        except Exception as e:
+            logger.error(f"Failed to classify document: {str(e)}")
+            return {}

guardianhub/clients/graph_db_client.py

@@ -0,0 +1,161 @@
+# services/clients/neo4j_client.py (New File/Class)
+import datetime
+import json
+from typing import Dict, Any, Optional
+
+import httpx
+import yaml  # Must be imported for YAML output
+# Import all model classes to make them available at the package level
+from guardianhub.models.template.suggestion import TemplateSchemaSuggestion
+
+from guardianhub.config.settings import settings
+from guardianhub import get_logger
+logger = get_logger(__name__)
+
+# NOTE: The actual driver must be injected/managed by the calling service (doc-template service)
+class GraphDBClient:
+    def __init__(self, base_url: str, poll_interval: int = 5, poll_timeout: int = 300):
+        """
+        Initializes the Paperless client.
+        """
+        self.api_url = base_url.rstrip('/')
+        self.api_token = settings.endpoints.GRAPH_DB_URL
+        self.headers = {
+            "Accept": "application/json",
+        }
+        self.poll_interval = poll_interval
+        self.poll_timeout = poll_timeout
+
+        # Initialize the persistent httpx client here.
+        # DO NOT use it in an 'async with' block in methods, or it will be closed.
+        self.client = httpx.AsyncClient(headers=self.headers, base_url=self.api_url, timeout=self.poll_timeout + 60)
+        logger.info("PaperlessClient initialized for URL: %s", self.api_url)
+
+    async def save_document_template(self, template: TemplateSchemaSuggestion) -> bool:
+        """
+        Creates a new DocumentTemplate node and links it to the Doc-Template Service
+        node by submitting a YAML payload to the ingestion endpoint.
+        """
+
+        # 1. Prepare Node Properties
+        template_properties = {
+            "template_id": template.template_id,
+            "document_type": template.document_type,
+            "template_name": template.template_name,
+            "required_keywords": template.required_keywords,
+            # The ingestion endpoint requires the schema to be stored as a property value.
+            # We must serialize the JSON schema dictionary to a string/YAML-safe string.
+            "json_schema_str": json.dumps(template.json_schema)
+        }
+
+        # 2. Construct the Graph Ingestion Dictionary (The YAML Payload Structure)
+        ingestion_payload = {
+            "nodes": [
+                {
+                    "type": "DocumentTemplate",
+                    "properties": template_properties
+                }
+            ],
+            "relationships": [
+                {
+                    "from": {
+                        "type": "PlatformService",
+                        "property": "name",
+                        "value": "doc-template-service"  # Matching the service node created at startup
+                    },
+                    "to": {
+                        "type": "DocumentTemplate",
+                        "property": "template_id",
+                        "value": template.template_id
+                    },
+                    "type": "MANAGES_TEMPLATE",
+                    "properties": {
+                        "link_date": datetime.datetime.now()
+                    }
+                }
+            ]
+        }
+
+        # 3. Convert to YAML
+        yaml_payload = yaml.dump(ingestion_payload, sort_keys=False)
+
+        # 4. POST to the ingestion endpoint
+        try:
+            response = await self.client.post(
+                "/ingest-yaml-schema",
+                content=yaml_payload,
+                headers={'Content-Type': 'application/x-yaml'},
+                timeout=30.0
+            )
+            response.raise_for_status()
+
+            response_json = response.json()
+            if response_json.get("status") == "success":
+                logger.info(f"✅ Template {template.template_id} successfully persisted via YAML ingestion.")
+                return True
+            else:
+                logger.error(
+                    f"Graph DB Service returned non-success status for template {template.template_id}: {response_json.get('message')}")
+                return False
+
+        except httpx.HTTPStatusError as e:
+            logger.error(
+                f"HTTP error during YAML ingestion (Template {template.template_id}). Status: {e.response.status_code}. Detail: {e.response.text}",
+                exc_info=True
+            )
+            return False
+        except Exception as e:
+            logger.error(f"Failed to ingest template YAML for {template.template_id}: {e}", exc_info=True)
+            return False
+
+        # services/clients/neo4j_client.py (Corrected get_template_by_id)
+
+    async def get_template_by_id(self, template_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieves the properties of a DocumentTemplate node by its ID via the
+        /query-cypher endpoint.
+        """
+
+        # 1. Define the Cypher query
+        cypher_query = """
+        MATCH (t:DocumentTemplate {template_id: $template_id})
+        RETURN properties(t) as template
+        """
+
+        # 2. Prepare the JSON payload for the read endpoint
+        payload = {
+            "query": cypher_query,
+            "parameters": {"template_id": template_id}
+        }
+
+        try:
+            # 🛠️ FIX: Target the correct read endpoint and send JSON payload
+            response = await self.client.post(
+                "/query-cypher", # The correct read endpoint
+                json=payload,    # Send as JSON
+                timeout=30.0
+            )
+            response.raise_for_status()
+
+            response_json = response.json()
+
+            if response_json.get("status") == "success" and response_json.get("results"):
+                # The result is typically a list of dicts from Cypher execution
+                record = response_json["results"][0]
+                template_data = record["template"]
+
+                # Convert the stored JSON Schema string back to a dictionary
+                template_data['json_schema'] = json.loads(template_data.pop('json_schema_str'))
+
+                logger.info(f"✅ Template {template_id} successfully retrieved from GraphDB.")
+                return template_data
+            else:
+                logger.info(f"Template {template_id} not found or query failed: {response_json.get('message')}")
+                return None
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP error retrieving template {template_id}. Status: {e.response.status_code}")
+            return None
+        except Exception as e:
+            logger.error(f"Failed to retrieve template {template_id} from Neo4j: {e}", exc_info=True)
+            return None

guardianhub/clients/langfuse/dataset_client.py

@@ -0,0 +1,157 @@
+"""Langfuse dataset management client.
+
+This module provides a client for managing datasets in Langfuse.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from langfuse import Langfuse
+from langfuse._client.datasets import DatasetClient as LangfuseDatasetClient
+from langfuse.model import Dataset, DatasetItem, DatasetRun
+
+from guardianhub import get_logger
+from .manager import LangfuseManager
+
+LOGGER = get_logger(__name__)
+
+
+class DatasetClient:
+    """Client for Langfuse dataset management."""
+
+    def __init__(
+        self,
+        client: Optional[Langfuse] = None,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        host: Optional[str] = None,
+        **kwargs
+    ):
+        """Initialize the DatasetClient.
+        
+        Args:
+            client: Optional Langfuse client instance. If not provided, will use LangfuseManager.
+            public_key: Langfuse public key. If not provided, will use LANGFUSE_PUBLIC_KEY from environment.
+            secret_key: Langfuse secret key. If not provided, will use LANGFUSE_SECRET_KEY from environment.
+            host: Langfuse host URL. If not provided, will use LANGFUSE_HOST from environment or default.
+            **kwargs: Additional arguments to pass to Langfuse client initialization.
+        """
+        if client is not None:
+            self._client = client
+        else:
+            self._client = LangfuseManager.get_instance(
+                public_key=public_key,
+                secret_key=secret_key,
+                host=host,
+                **kwargs
+            )
+
+    def create_dataset(self, name: str) -> Dataset:
+        """Create a new dataset.
+        
+        Args:
+            name: Name of the dataset to create.
+            
+        Returns:
+            The created Dataset object.
+        """
+        return self._client.create_dataset(name=name)
+
+    def get_dataset(self, name: str) -> LangfuseDatasetClient:
+        """Get a dataset by name.
+        
+        Args:
+            name: Name of the dataset to retrieve.
+            
+        Returns:
+            The Dataset object if found, None otherwise.
+            
+        Raises:
+            ValueError: If the Langfuse client is not initialized.
+        """
+        if self._client is None:
+            raise ValueError("Langfuse client is not initialized")
+        return self._client.get_dataset(name=name)
+
+    def list_datasets(self) -> List[Dataset]:
+        """List all datasets.
+        
+        Returns:
+            List of Dataset objects.
+            
+        Raises:
+            ValueError: If the Langfuse client is not initialized.
+        """
+        if self._client is None:
+            raise ValueError("Langfuse client is not initialized")
+        return self._client.list_datasets()
+
+    def create_dataset_item(
+        self,
+        dataset_name: str,
+        input: Union[Dict[str, Any], List[Dict[str, Any]]],
+        expected_output: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
+        **kwargs
+    ) -> DatasetItem:
+        """Create a new item in a dataset.
+        
+        Args:
+            dataset_name: Name of the dataset to add the item to.
+            input: Input data for the dataset item.
+            expected_output: Expected output for the dataset item.
+            **kwargs: Additional arguments for the dataset item.
+            
+        Returns:
+            The created DatasetItem object.
+        """
+        return self._client.create_dataset_item(
+            dataset_name=dataset_name,
+            input=input,
+            expected_output=expected_output,
+            **kwargs
+        )
+
+    def get_dataset_items(self, dataset_name: str) -> List[DatasetItem]:
+        """Get all items in a dataset.
+        
+        Args:
+            dataset_name: Name of the dataset.
+            
+        Returns:
+            List of DatasetItem objects.
+        """
+        return self._client.get_dataset_items(dataset_name=dataset_name)
+
+    def create_dataset_run(
+        self,
+        dataset_name: str,
+        run_name: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> DatasetRun:
+        """Create a new dataset run.
+        
+        Args:
+            dataset_name: Name of the dataset.
+            run_name: Name for the run.
+            metadata: Optional metadata for the run.
+            
+        Returns:
+            The created DatasetRun object.
+        """
+        return self._client.create_dataset_run(
+            dataset_name=dataset_name,
+            run_name=run_name,
+            metadata=metadata or {}
+        )
+
+    def get_dataset_run(self, run_id: str) -> Optional[DatasetRun]:
+        """Get a dataset run by ID.
+        
+        Args:
+            run_id: ID of the run to retrieve.
+            
+        Returns:
+            The DatasetRun object if found, None otherwise.
+        """
+        return self._client.get_dataset_run(id=run_id)

guardianhub/clients/langfuse/manager.py

@@ -0,0 +1,118 @@
+"""Langfuse Manager for singleton connection management.
+
+This module provides a manager that ensures only one instance of the Langfuse
+client is created and used throughout the application.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import httpx
+from guardianhub import get_logger
+from langfuse import Langfuse
+
+LOGGER = get_logger(__name__)
+
+# TODO: For future reference - ThreadPool impl to handle multiple connection
+class LangfuseManager:
+    """Manages the singleton instance of the Langfuse client."""
+    _client: Optional[Langfuse] = None
+    _initialized = False
+
+    @classmethod
+    def get_instance(
+        cls,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        host: Optional[str] = None,
+        **kwargs
+    ) -> Optional[Langfuse]:
+        """
+        Get the singleton Langfuse client instance.
+
+        Initializes the client on the first call and returns the existing
+        instance on subsequent calls.
+
+        Args:
+            public_key: Langfuse public key.
+            secret_key: Langfuse secret key.
+            host: Langfuse host URL.
+            **kwargs: Additional arguments for the Langfuse client.
+
+        Returns:
+            The initialized Langfuse client instance, or None if initialization fails.
+        """
+        LOGGER.info("🔍 Initializing Langfuse Service...")
+
+        if cls._initialized:
+            return cls._client
+
+        cls._initialized = True  # Mark as initialized even if it fails, to prevent retries.
+
+        public_key = public_key or os.getenv("LANGFUSE_PUBLIC_KEY")
+        secret_key = secret_key or os.getenv("LANGFUSE_SECRET_KEY")
+        host = host or os.getenv("LANGFUSE_HOST")
+
+        if not public_key or not secret_key:
+            LOGGER.warning(
+                "Langfuse credentials not provided. Set LANGFUSE_PUBLIC_KEY and "
+                "LANGFUSE_SECRET_KEY. Langfuse client will not be initialized."
+            )
+            return None
+
+        try:
+            cls._client = Langfuse(
+                public_key=public_key,
+                secret_key=secret_key,
+                host=host,
+                **kwargs
+            )
+
+            if cls.check_langfuse_connection():
+                LOGGER.info("✅ Successfully initialized singleton Langfuse client.")
+            else:
+                LOGGER.warning("⚠️ Langfuse client initialization failed ")
+
+            return cls._client
+        except Exception as exc:
+            LOGGER.exception("Failed to initialize singleton Langfuse client: %s", exc)
+            cls._client = None
+            return None
+
+    @classmethod
+    def check_langfuse_connection(cls) -> bool:
+        """
+        Check if the Langfuse connection is valid by attempting to authenticate.
+
+        Returns:
+            bool: True if the connection is valid, False otherwise
+        """
+        if not cls._client:
+            LOGGER.warning("Langfuse client is not initialized")
+            return False
+
+        try:
+            # Test the connection with a timeout to prevent hanging
+            is_authenticated = cls._client.auth_check()
+            if is_authenticated:
+                LOGGER.info("✅ Successfully authenticated with Langfuse")
+                return True
+            else:
+                LOGGER.warning("❌ Failed to authenticate with Langfuse - Invalid credentials")
+                return False
+        except httpx.ConnectError as e:
+            LOGGER.error(f"❌ Could not connect to Langfuse server: {str(e)}. "
+                         "Please check your network connection and Langfuse server status.")
+            return False
+        except Exception as e:
+            LOGGER.error(f"❌ Error connecting to Langfuse: {str(e)}", exc_info=True)
+            return False
+
+    @classmethod
+    def flush(cls) -> None:
+        """Flushes the managed Langfuse client instance."""
+        if cls._client:
+            cls._client.flush()
+            LOGGER.info("Langfuse manager flushed the client.")

guardianhub/clients/langfuse/prompt_client.py

@@ -0,0 +1,68 @@
+"""Langfuse prompt management client.
+
+This module provides a client for managing prompts in Langfuse.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from langfuse import Langfuse
+
+from guardianhub import get_logger
+from .manager import LangfuseManager
+
+LOGGER = get_logger(__name__)
+
+
+class PromptClient:
+    """Client for Langfuse prompt management."""
+
+    def __init__(
+        self,
+        client: Optional[Langfuse] = None,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        host: Optional[str] = None,
+        **kwargs
+    ):
+        """Initialize the PromptClient.
+        
+        Args:
+            client: Optional Langfuse client instance. If not provided, will use LangfuseManager.
+            public_key: Langfuse public key. If not provided, will use LANGFUSE_PUBLIC_KEY from environment.
+            secret_key: Langfuse secret key. If not provided, will use LANGFUSE_SECRET_KEY from environment.
+            host: Langfuse host URL. If not provided, will use LANGFUSE_HOST from environment or default.
+            **kwargs: Additional arguments to pass to Langfuse client initialization.
+        """
+        if client is not None:
+            self._client = client
+        else:
+            self._client = LangfuseManager.get_instance(
+                public_key=public_key,
+                secret_key=secret_key,
+                host=host,
+                **kwargs
+            )
+
+    def get_prompt(self, name: str, version: Optional[int] = None) -> Optional[str]:
+        """
+        Retrieves a prompt from Langfuse.
+
+        Args:
+            name: The name of the prompt.
+            version: The version of the prompt (optional).
+
+        Returns:
+            The prompt string, or None if not found.
+        """
+        if not self._client:
+            LOGGER.warning("Langfuse client not initialized. Cannot fetch prompt.")
+            return None
+        
+        try:
+            prompt = self._client.get_prompt(name, version)
+            return prompt.prompt
+        except Exception as e:
+            LOGGER.error("Failed to retrieve prompt '%s': %s", name, e)
+            return None