guardianhub 0.1.88__py3-none-any.whl

guardianhub/http/http_client.py

@@ -0,0 +1,26 @@
+# guardianhub_sdk/http/http_client.py
+import httpx
+from typing import Optional, Any, Dict
+
+
+class BaseHTTPClient:
+
+
+    def __init__(self, base_url: str, timeout: int = 30):
+
+        self.base_url = base_url.rstrip('/')
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+
+    async def request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        resp = await self._client.request(method, url, **kwargs)
+        resp.raise_for_status()
+        return resp
+
+
+    async def get(self, path: str, **kwargs) -> httpx.Response:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs) -> httpx.Response:
+        return await self.request("POST", path, **kwargs)

guardianhub/logging/__init__.py

@@ -0,0 +1,2 @@
+from .logging import setup_logging,get_logger
+__all__ = ["setup_logging","get_logger"]

guardianhub/logging/logging.py

@@ -0,0 +1,168 @@
+import logging
+import sys
+from typing import Optional, Dict, Any, Type, List, Union
+from guardianhub.config import settings
+
+# Lazy import to avoid circular imports
+HealthCheckFilter = None
+
+
+class LoggerFactory:
+    """Factory class for creating and managing logger instances with consistent configuration."""
+    _initialized = False
+    _loggers: Dict[str, logging.Logger] = {}
+
+    @classmethod
+    def initialize(cls) -> None:
+        """Initialize the logging configuration if not already done."""
+        if not cls._initialized:
+            setup_logging()
+            cls._initialized = True
+
+    @classmethod
+    def get_logger(
+        cls,
+        name: str,
+        level: Optional[int] = None,
+        extra: Optional[Dict[str, Any]] = None,
+        filters: Optional[List[Union[logging.Filter, Type[logging.Filter], dict]]] = None
+    ) -> logging.Logger:
+        """
+        Get or create a logger with the given name and optional configuration.
+
+        Args:
+            name: Logger name (usually __name__ of the calling module)
+            level: Optional log level (e.g., logging.INFO, logging.DEBUG)
+            extra: Optional dictionary with additional context to add to log records
+            filters: Optional list of filter instances, filter classes, or filter config dicts
+                    (for filters that require initialization)
+
+        Returns:
+            Configured logger instance
+        """
+        cls.initialize()
+        
+        if name not in cls._loggers:
+            logger = logging.getLogger(name)
+            if level is not None:
+                logger.setLevel(level)
+            
+            # Apply filters if any
+            if filters:
+                for f in filters:
+                    if isinstance(f, logging.Filter):
+                        logger.addFilter(f)
+                    elif isinstance(f, type) and issubclass(f, logging.Filter):
+                        logger.addFilter(f())
+                    elif isinstance(f, dict):
+                        # For filters that need initialization with parameters
+                        filter_class = f.pop('class')
+                        if isinstance(filter_class, type) and issubclass(filter_class, logging.Filter):
+                            logger.addFilter(filter_class(**f))
+            
+            if extra:
+                logger = logging.LoggerAdapter(logger, extra)
+            
+            cls._loggers[name] = logger
+        
+        return cls._loggers[name]
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Returns a pre-configured logger instance for a given name.
+    
+    This is a convenience wrapper around LoggerFactory.get_logger()
+    """
+    return LoggerFactory.get_logger(name)
+
+
+def setup_logging():
+    """
+    Configures the root logger and the uvicorn.access logger using a standard format.
+    Applies filters to reduce log noise.
+    """
+    # Lazy import to avoid circular imports
+    global HealthCheckFilter
+    if HealthCheckFilter is None:
+        from .logging_filters import HealthCheckFilter as _HealthCheckFilter
+        HealthCheckFilter = _HealthCheckFilter
+    
+    # Get log level from settings, default to INFO if not found
+    try:
+        log_level = settings.logging.level
+    except AttributeError:
+        log_level = 'INFO'
+    numeric_level = logging.getLevelName(log_level.upper())
+    
+    # Configure health check filter for uvicorn access logs
+    health_check_filters = []
+    health_check_path = getattr(settings, 'excluded_urls', '')
+    if health_check_path and HealthCheckFilter is not None:
+        health_check_filters.append({
+            'class': HealthCheckFilter,
+            'path': health_check_path
+        })
+
+    # 1. Define a standard Python Formatter
+    service_name = getattr(getattr(settings, 'service', None), 'name', 'guardianhub')
+    standard_formatter = logging.Formatter(
+        # Format: [2025-10-12 00:50:20] INFO: service_name.module_name - message
+        fmt=f"[%(asctime)s] %(levelname)s: {service_name}.%(name)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+    # 2. Setup the Root Logger (for ALL application logs, including lifespan)
+    root_logger = logging.getLogger()
+    root_logger.setLevel(numeric_level)
+
+    # Clear existing handlers (critical for clean reconfiguration)
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    # Add the main application handler
+    app_handler = logging.StreamHandler(sys.stdout)
+    app_handler.setFormatter(standard_formatter)
+    app_handler.setLevel(numeric_level)
+    root_logger.addHandler(app_handler)
+
+    # 3. Setup the Uvicorn Access Logger (for HTTP request logs)
+    uvicorn_access_logger = logging.getLogger("uvicorn.access")
+    uvicorn_access_logger.setLevel(numeric_level)
+    # This prevents uvicorn logs from being duplicated by propagating to the root_logger
+    uvicorn_access_logger.propagate = False
+
+    # Clear existing uvicorn handlers
+    for handler in uvicorn_access_logger.handlers[:]:
+        uvicorn_access_logger.removeHandler(handler)
+    
+    # Apply health check filters
+    for f in health_check_filters:
+        if isinstance(f, dict):
+            filter_class = f.pop('class')
+            uvicorn_access_logger.addFilter(filter_class(**f))
+        else:
+            uvicorn_access_logger.addFilter(f)
+
+    # Add the dedicated uvicorn handler
+    uvicorn_handler = logging.StreamHandler(sys.stdout)
+    uvicorn_handler.setFormatter(standard_formatter)
+
+    # Assuming HealthCheckFilter is defined and available
+    try:
+        from .logging_filters import HealthCheckFilter
+        uvicorn_handler.addFilter(HealthCheckFilter(path="/health"))
+    except ImportError:
+        # Fallback if the filter cannot be imported
+        pass
+
+    uvicorn_handler.setLevel(numeric_level)
+    uvicorn_access_logger.addHandler(uvicorn_handler)
+
+    # Get service name safely with fallback
+    service_name = getattr(getattr(settings, 'service', None), 'name', 'guardianhub')
+    
+    # Final log message
+    root_logger.info(
+        f"Logging for '{service_name}' configured at level {logging.getLevelName(numeric_level)} with standard format."
+    )

guardianhub/logging/logging_filters.py

@@ -0,0 +1,35 @@
+"""Custom logging filters to reduce log noise."""
+import logging
+
+class HealthCheckFilter(logging.Filter):
+    """A custom log filter to suppress successful health check endpoint logs."""
+
+    def __init__(self, path: str):
+        """Initialize the filter with the path of the health check endpoint."""
+        super().__init__()
+        self.path = path
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Filter out successful log records for the health check endpoint.
+
+        Args:
+            record: The log record to be processed.
+
+        Returns:
+            False if the record should be suppressed, True otherwise.
+        """
+        # --- CORRECTED FILTER LOGIC ---
+        # The args tuple from uvicorn.access is:
+        # (client_addr, method, path, protocol, status_code)
+        # We need to check if the tuple has enough elements to avoid an IndexError.
+        if record.name == "uvicorn.access" and isinstance(record.args, tuple) and len(record.args) >= 5:
+            # Extract the path (at index 2) and status_code (at index 4)
+            path = record.args[2]
+            status_code = record.args[4]
+
+            # Check for the specific health check path and a 200 status code
+            if path == self.path and status_code == 200:
+                return False
+
+        # Allow all other log records to pass
+        return True

guardianhub/models/agent_models.py

@@ -0,0 +1,153 @@
+# models/agent_models.py
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Any
+from pydantic import BaseModel, Field
+from .registry.registry import register_model
+
+@register_model
+class AgentCreateRequest(BaseModel):
+    """Request model for creating a new agent with flexible configuration.
+    
+    Example:
+    ```json
+    {
+        "agent_name": "social-media-ai",
+        "agent_type": "social_media",
+        "description": "AI assistant for managing social media presence",
+        "system_prompt": "You are a helpful social media assistant...",
+        "config": {
+            "target_platforms": ["LinkedIn", "Twitter", "Instagram"],
+            "posting_schedule": {
+                "Monday": ["10:00", "15:00"],
+                "Wednesday": ["11:00", "17:00"]
+            },
+            "content_themes": ["Industry news", "Company updates"]
+        }
+    }
+    """
+    agent_name: str = Field(
+        example="social-media-ai",
+        description="Unique identifier for the agent (e.g., 'social-media-ai', 'customer-support-bot')."
+    )
+    agent_type: str = Field(
+        example="social_media",
+        description="Type of the agent (e.g., 'social_media', 'customer_support', 'data_analyst')."
+    )
+    description: str = Field(
+        default="",
+        example="AI assistant for managing social media presence",
+        description="Brief description of the agent's purpose and functionality."
+    )
+    system_prompt: str = Field(
+        example="You are a helpful social media assistant that creates engaging content...",
+        description="The system prompt that defines the agent's behavior and capabilities."
+    )
+    config: Dict[str, Any] = Field(
+        default_factory=dict,
+        example={
+            "target_platforms": ["LinkedIn", "Twitter", "Instagram"],
+            "posting_schedule": {
+                "Monday": ["10:00", "15:00"],
+                "Wednesday": ["11:00"]
+            }
+        },
+        description="Agent-specific configuration parameters as key-value pairs."
+    )
+
+class AgentStatus(str, Enum):
+    DRAFT = "DRAFT"
+    ACTIVE = "ACTIVE"
+    INACTIVE = "INACTIVE"
+    TRAINING = "TRAINING"
+
+@register_model
+class AgentCreate(BaseModel):
+    name: str = Field(..., description="Name of the agent")
+    domain: str = Field(..., description="Domain of the agent")
+    description: Optional[str] = Field(None, description="Description of the agent")
+    system_prompt: str = Field(..., description="System prompt for the agent")
+    status: AgentStatus = Field(AgentStatus.DRAFT, description="Status of the agent")
+    tags: List[str] = Field(default_factory=list, description="Tags for the agent")
+    default_tools: List[str] = Field(default_factory=list, description="List of default tool IDs")
+    reflection_config: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Configuration for agent reflection and learning"
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata for the agent"
+    )
+
+@register_model
+class Agent(AgentCreate):
+    id: str = Field(..., description="Unique identifier for the agent")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    class Config:
+        from_attributes = True
+
+
+@register_model
+class AgentResponse(BaseModel):
+    """Response model for agent operations."""
+    id: str = Field(..., description="Unique identifier for the agent")
+    name: str = Field(..., description="Name of the agent")
+    agent_type: str = Field(..., description="Type of the agent")
+    status: AgentStatus = Field(..., description="Current status of the agent")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    system_prompt: str = Field(..., description="System prompt for the agent")
+    domain: str = Field(..., description="Domain of the agent")
+    description: str = Field(default="", description="Description of the agent")
+    message: Optional[str] = Field(None, description="Additional details about the operation")
+    config: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Agent-specific configuration parameters as key-value pairs."
+    )
+    class Config:
+        from_attributes = True
+
+
+# Wrapper model to ensure the LLM outputs a single JSON object.
+@register_model
+class SearchPhrasesResponse(BaseModel):
+    """The expected structure for the LLM output."""
+    search_phrases: List[str] = Field(
+        ...,
+        description="A list of 1 to 3 search phrases relevant to the agent's domain."
+    )
+
+@register_model
+class LLMReflectionConfig(BaseModel):
+    """Domain-specific reflection parameters to override defaults."""
+    enabled: Optional[bool] = Field(None, description="Whether ACE reflection should be enabled.")
+    optimization_types: List[str] = Field(default_factory=list,
+                                          description="List of domain-specific optimization types (e.g., DataQuality, Sentiment).")
+    synthesis_directives: Optional[Dict[str, Any]] = Field(None,
+                                                           description="Directives for semantic tool synthesis (e.g., concrete_tool_whitelist).")
+@register_model
+class LLMKnowledgeSuggestion(BaseModel):
+    """Suggestions for initial knowledge base articles or queries."""
+    type: str = Field(..., description="Type of knowledge (e.g., 'document', 'query').")
+    value: str = Field(..., description="The document ID, query text, or relevant URL.")
+
+@register_model
+class AgentLLMConfigSuggestion(BaseModel):
+    """
+    Structured configuration output generated by the LLM for a new agent.
+    This replaces the unreliable Dict[str, Any] response.
+    """
+    system_prompt: str = Field(...,
+                               description="The comprehensive, domain-specific system prompt and persona for the agent's core LLM.")
+
+    # Use the structured reflection config model
+    reflection_config: LLMReflectionConfig = Field(...,
+                                                   description="Structured parameters for the agent's ACE reflection process.")
+
+    # Suggestions for the warm-up phase (Initial query generation and knowledge seeding)
+    initial_warmup_query: str = Field(...,
+                                      description="The most effective synthetic query to run for the initial ACE warm-up.")
+    knowledge_suggestions: List[LLMKnowledgeSuggestion] = Field(default_factory=list,
+                                                                description="Suggestions for initial knowledge to pull or seed.")

guardianhub/models/base.py

@@ -0,0 +1,2 @@
+class BaseModel:
+    pass

guardianhub/models/registry/client.py

@@ -0,0 +1,16 @@
+# guardianhub_sdk/models/registry/client.py
+from typing import Optional
+from ...models.registry.loader import Loader
+
+
+class ModelRegistryClient:
+    def __init__(self, base_url: str, token: Optional[str] = None):
+        self.base_url = base_url.rstrip('/')
+        self.loader = Loader()
+
+    async def fetch_model(self, name: str, version: Optional[str] = None):
+        """Fetch remote model metadata and python artifact, return a loaded class or metadata."""
+        return await self.loader.load(name)
+
+# singleton-ish convenience
+client = ModelRegistryClient(base_url="https://registry.internal.local")

guardianhub/models/registry/dynamic_loader.py

@@ -0,0 +1,73 @@
+from typing import Dict, Any, Type, Optional, List
+from pydantic import BaseModel, create_model
+from pydantic.fields import Field
+
+_DYNAMIC_MODEL_CACHE: Dict[str, Type[BaseModel]] = {}
+
+class DynamicModelBuilder:
+
+    @staticmethod
+    def load_from_schema(
+        model_name: str,
+        schema_json: Dict[str, Any]
+    ) -> Type[BaseModel]:
+
+        # 1: Cache
+        if model_name in _DYNAMIC_MODEL_CACHE:
+            return _DYNAMIC_MODEL_CACHE[model_name]
+
+        # 2: Generate
+        model = DynamicModelBuilder._create_model(model_name, schema_json)
+        _DYNAMIC_MODEL_CACHE[model_name] = model
+        return model
+
+    @staticmethod
+    def _create_model(
+        model_name: str,
+        schema: Dict[str, Any]
+    ) -> Type[BaseModel]:
+
+        properties = schema.get("properties", {})
+        required_fields = schema.get("required", [])
+
+        model_fields = {}
+
+        for field_name, field_schema in properties.items():
+            field_type = DynamicModelBuilder._map_schema_to_type(field_schema)
+
+            default_value = ...
+            if field_name not in required_fields:
+                default_value = None
+
+            model_fields[field_name] = (field_type, default_value)
+
+        return create_model(model_name, **model_fields)
+
+    @staticmethod
+    def _map_schema_to_type(schema: Dict[str, Any]):
+        """Map JSON Schema types to Python."""
+        t = schema.get("type")
+
+        # Primitive
+        if t == "string":
+            return str
+        if t == "number":
+            return float
+        if t == "integer":
+            return int
+        if t == "boolean":
+            return bool
+
+        # Array
+        if t == "array":
+            item_schema = schema.get("items", {})
+            item_type = DynamicModelBuilder._map_schema_to_type(item_schema)
+            return List[item_type]
+
+        # Object
+        if t == "object":
+            inner_model_name = "NestedObject"
+            return DynamicModelBuilder._create_model(inner_model_name, schema)
+
+        # Fallback
+        return Any

guardianhub/models/registry/loader.py

@@ -0,0 +1,37 @@
+from typing import Type, Dict, Any, Optional
+from pydantic import BaseModel
+from .registry import MODEL_REGISTRY, get_model
+from .dynamic_loader import DynamicModelBuilder
+
+
+class Loader:
+
+    @staticmethod
+    def load(
+            model_name: Optional[str] = None,
+            schema_json: Optional[Dict[str, Any]] = None
+    ) -> Type[BaseModel]:
+        """
+        Load a Pydantic model either by registry name or dynamically from schema.
+
+        Args:
+            model_name: Optional name of a registered model
+            schema_json: Optional JSON schema dict to build a dynamic model
+
+        Returns:
+            Pydantic model class
+        """
+        # 1. Try registry first
+        if model_name:
+            try:
+                return get_model(model_name)
+            except ValueError:
+                pass  # fallback to schema if provided
+
+        # 2. Generate dynamically from schema
+        if schema_json:
+            dynamic_name = model_name or "DynamicModel"
+            return DynamicModelBuilder.load_from_schema(dynamic_name, schema_json)
+
+        # 3. Neither provided → raise error
+        raise ValueError("Either a registered model name or schema JSON must be provided")

guardianhub/models/registry/registry.py

@@ -0,0 +1,17 @@
+from typing import Dict, Type
+from pydantic import BaseModel
+
+MODEL_REGISTRY: Dict[str, Type[BaseModel]] = {}
+
+def register_model(model: Type[BaseModel]):
+    """
+    Register a Pydantic model so it can be dynamically loaded across microservices.
+    """
+    MODEL_REGISTRY[model.__name__] = model
+    return model
+
+def get_model(name: str) -> Type[BaseModel]:
+    try:
+        return MODEL_REGISTRY[name]
+    except KeyError:
+        raise ValueError(f"Model '{name}' not found in registry")

guardianhub/models/registry/signing.py

@@ -0,0 +1,70 @@
+# guardianhub_sdk/models/registry/signing.py
+from pathlib import Path
+from typing import Tuple, Dict, Any
+import base64
+import json
+
+from Crypto.PublicKey import RSA
+from Crypto.Signature import pkcs1_15
+from Crypto.Hash import SHA256
+
+
+def generate_rsa_keypair(bits: int = 4096) -> Tuple[bytes, bytes]:
+    """
+    Generate RSA keypair (private_pem, public_pem).
+    In production use: KMS or offline secure key generation.
+    """
+    key = RSA.generate(bits)
+    private_pem = key.export_key(format="PEM")
+    public_pem = key.publickey().export_key(format="PEM")
+    return private_pem, public_pem
+
+
+def sign_bytes(private_pem: bytes, payload: bytes) -> str:
+    """
+    Sign arbitrary bytes with RSA-SHA256, return base64 signature string.
+    """
+    key = RSA.import_key(private_pem)
+    h = SHA256.new(payload)
+    signature = pkcs1_15.new(key).sign(h)
+    return base64.b64encode(signature).decode("ascii")
+
+
+def verify_bytes(public_pem: bytes, payload: bytes, signature_b64: str) -> bool:
+    """
+    Verify a base64 signature over payload bytes using public key.
+    """
+    key = RSA.import_key(public_pem)
+    h = SHA256.new(payload)
+    signature = base64.b64decode(signature_b64.encode("ascii"))
+    try:
+        pkcs1_15.new(key).verify(h, signature)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+def sign_metadata_dict(private_pem: bytes, metadata: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Attach a signature to the metadata dict and return augmented metadata.
+    Uses canonical JSON encoding (sorted keys, no whitespace).
+    """
+    payload = json.dumps(metadata, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    sig = sign_bytes(private_pem, payload)
+    metadata_signed = dict(metadata)
+    metadata_signed["_signature"] = sig
+    return metadata_signed
+
+
+def verify_metadata_dict(public_pem: bytes, metadata_signed: Dict[str, Any]) -> bool:
+    """
+    Verify `_signature` in metadata_signed.
+    Returns True if valid, False otherwise.
+    """
+    sig = metadata_signed.get("_signature")
+    if not sig:
+        return False
+    md = dict(metadata_signed)
+    md.pop("_signature", None)
+    payload = json.dumps(md, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return verify_bytes(public_pem, payload, sig)

guardianhub/models/template/agent_plan.py

@@ -0,0 +1,65 @@
+from typing import List, Dict, Any, Optional, Literal
+from pydantic import BaseModel, Field, conlist
+from ..registry.registry import register_model
+
+
+# --- STEP 1: Define the individual tool-call step model ---
+class PlanStep(BaseModel):
+    """A single step in the agent's overall macro-plan."""
+
+    # The exact name of the tool to be called (must match a registered tool)
+    tool_name: str = Field(..., description="The exact name of the tool to execute.")
+
+    # A unique name for this step, used as the key to store the result in macro_context.
+    step_name: str = Field(...,
+                           description="A unique identifier for this plan step. Its result will be stored under this name in the macro_context.")
+
+    # The arguments for the tool call, passed as a dictionary.
+    tool_args: Dict[str, Any] = Field(..., description="The dictionary of arguments required for the tool call.")
+
+    # The list of results (by step_name) this step requires before it can be executed.
+    dependencies: List[str] = Field(
+        default_factory=list,
+        description="List of step_name strings whose results must be available in macro_context before this step can run."
+    )
+
+    # Internal status, handled by the graph executor.
+    status: Literal["pending", "running", "complete", "error"] = Field(
+        default="pending",
+        description="The current status of the step (pending, running, complete, error). Must be 'pending' initially."
+    )
+
+
+# --- STEP 2: Define the Macro Plan model ---
+@register_model
+class MacroPlan(BaseModel):
+    """The complete structured plan generated by the LLM."""
+
+    # Must be an array of PlanStep objects.
+    plan: conlist(PlanStep, min_length=0) = Field(
+        default_factory=list,  # Use default_factory for mutable types
+        description="The sequence of PlanStep objects required to fulfill the user request. Can be empty if no tools are needed."
+    )
+
+    # A final reflection or thought process before synthesis/execution.
+    # 🟢 FIX: Make 'reflection' Optional and provide an empty string default.
+    # This allows the model to validate even if the key is missing from the LLM's JSON.
+    reflection: Optional[str] = Field(
+        default="",
+        description="A brief thought process explaining why this plan was chosen and how it addresses the user's input."
+    )
+    metadata: Dict[str, Any] = Field(
+        ...,
+        description=(
+            "Additional metadata about the plan in a Pydantic-compatible JSON Schema format. "
+            "This can include configuration parameters, execution context, or any other "
+            "plan-specific metadata needed for execution or analysis."
+        )
+    )
+
+
+
+class MacroPlanResponse(BaseModel):
+    """Response model for the LLM's planning output."""
+    plan: List[PlanStep] = Field(default_factory=list, description="List of plan steps")
+    reflection: Optional[str] = Field(default="", description="Reasoning behind the plan")