axonflow 0.4.0__py3-none-any.whl

axonflow/policies.py

@@ -0,0 +1,289 @@
+"""AxonFlow SDK Policy Types and Methods.
+
+Policy CRUD types and methods for the Unified Policy Architecture v2.0.0.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ============================================================================
+# Policy Categories and Tiers
+# ============================================================================
+
+
+class PolicyCategory(str, Enum):
+    """Policy categories for organization and filtering."""
+
+    SECURITY_SQLI = "security-sqli"
+    SECURITY_ADMIN = "security-admin"
+    PII_GLOBAL = "pii-global"
+    PII_US = "pii-us"
+    PII_EU = "pii-eu"
+    PII_INDIA = "pii-india"
+    DYNAMIC_RISK = "dynamic-risk"
+    DYNAMIC_COMPLIANCE = "dynamic-compliance"
+    DYNAMIC_SECURITY = "dynamic-security"
+    DYNAMIC_COST = "dynamic-cost"
+    DYNAMIC_ACCESS = "dynamic-access"
+    CUSTOM = "custom"
+
+
+class PolicyTier(str, Enum):
+    """Policy tiers determine where policies apply."""
+
+    SYSTEM = "system"
+    ORGANIZATION = "organization"
+    TENANT = "tenant"
+
+
+class OverrideAction(str, Enum):
+    """Override action for policy overrides."""
+
+    BLOCK = "block"
+    WARN = "warn"
+    LOG = "log"
+    REDACT = "redact"
+
+
+class PolicyAction(str, Enum):
+    """Action to take when policy matches."""
+
+    BLOCK = "block"
+    WARN = "warn"
+    LOG = "log"
+    REDACT = "redact"
+    ALLOW = "allow"
+
+
+class PolicySeverity(str, Enum):
+    """Policy severity levels."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+# ============================================================================
+# Static Policy Types
+# ============================================================================
+
+
+class PolicyOverride(BaseModel):
+    """Policy override configuration."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    policy_id: str = Field(..., alias="policyId")
+    action: OverrideAction
+    reason: str
+    created_by: str | None = Field(default=None, alias="createdBy")
+    created_at: datetime = Field(..., alias="createdAt")
+    expires_at: datetime | None = Field(default=None, alias="expiresAt")
+    active: bool = True
+
+
+class StaticPolicy(BaseModel):
+    """Static policy definition."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    name: str
+    description: str | None = None
+    category: PolicyCategory
+    tier: PolicyTier
+    pattern: str
+    severity: PolicySeverity = PolicySeverity.MEDIUM
+    enabled: bool = True
+    action: PolicyAction = PolicyAction.BLOCK
+    organization_id: str | None = Field(default=None, alias="organizationId")
+    tenant_id: str | None = Field(default=None, alias="tenantId")
+    created_at: datetime = Field(..., alias="createdAt")
+    updated_at: datetime = Field(..., alias="updatedAt")
+    version: int | None = None
+    has_override: bool | None = Field(default=None, alias="hasOverride")
+    override: PolicyOverride | None = None
+
+
+class ListStaticPoliciesOptions(BaseModel):
+    """Options for listing static policies."""
+
+    category: PolicyCategory | None = None
+    tier: PolicyTier | None = None
+    enabled: bool | None = None
+    limit: int | None = Field(default=None, ge=1)
+    offset: int | None = Field(default=None, ge=0)
+    sort_by: str | None = None
+    sort_order: str | None = None
+    search: str | None = None
+
+
+class CreateStaticPolicyRequest(BaseModel):
+    """Request to create a new static policy."""
+
+    name: str = Field(..., min_length=1)
+    description: str | None = None
+    category: PolicyCategory
+    tier: PolicyTier = PolicyTier.TENANT  # Default to tenant tier for custom policies
+    pattern: str = Field(..., min_length=1)
+    severity: PolicySeverity = PolicySeverity.MEDIUM
+    enabled: bool = True
+    action: PolicyAction = PolicyAction.BLOCK
+
+
+class UpdateStaticPolicyRequest(BaseModel):
+    """Request to update an existing static policy."""
+
+    name: str | None = None
+    description: str | None = None
+    category: PolicyCategory | None = None
+    pattern: str | None = None
+    severity: PolicySeverity | None = None
+    enabled: bool | None = None
+    action: PolicyAction | None = None
+
+
+class CreatePolicyOverrideRequest(BaseModel):
+    """Request to create a policy override."""
+
+    action: OverrideAction
+    reason: str = Field(..., min_length=1)
+    expires_at: datetime | None = Field(default=None, alias="expiresAt")
+
+
+# ============================================================================
+# Dynamic Policy Types
+# ============================================================================
+
+
+class DynamicPolicyCondition(BaseModel):
+    """Condition for dynamic policy evaluation."""
+
+    field: str
+    operator: str
+    value: Any
+
+
+class DynamicPolicyConfig(BaseModel):
+    """Configuration for a dynamic policy."""
+
+    type: str
+    rules: dict[str, Any] = Field(default_factory=dict)
+    conditions: list[DynamicPolicyCondition] | None = None
+    action: PolicyAction
+    parameters: dict[str, Any] | None = None
+
+
+class DynamicPolicy(BaseModel):
+    """Dynamic policy definition."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    name: str
+    description: str | None = None
+    category: PolicyCategory
+    tier: PolicyTier
+    enabled: bool = True
+    organization_id: str | None = Field(default=None, alias="organizationId")
+    tenant_id: str | None = Field(default=None, alias="tenantId")
+    config: DynamicPolicyConfig
+    created_at: datetime = Field(..., alias="createdAt")
+    updated_at: datetime = Field(..., alias="updatedAt")
+    version: int | None = None
+
+
+class ListDynamicPoliciesOptions(BaseModel):
+    """Options for listing dynamic policies."""
+
+    category: PolicyCategory | None = None
+    tier: PolicyTier | None = None
+    enabled: bool | None = None
+    limit: int | None = Field(default=None, ge=1)
+    offset: int | None = Field(default=None, ge=0)
+    sort_by: str | None = None
+    sort_order: str | None = None
+    search: str | None = None
+
+
+class CreateDynamicPolicyRequest(BaseModel):
+    """Request to create a dynamic policy."""
+
+    name: str = Field(..., min_length=1)
+    description: str | None = None
+    category: PolicyCategory
+    config: DynamicPolicyConfig
+    enabled: bool = True
+
+
+class UpdateDynamicPolicyRequest(BaseModel):
+    """Request to update a dynamic policy."""
+
+    name: str | None = None
+    description: str | None = None
+    category: PolicyCategory | None = None
+    config: DynamicPolicyConfig | None = None
+    enabled: bool | None = None
+
+
+# ============================================================================
+# Pattern Testing Types
+# ============================================================================
+
+
+class TestPatternMatch(BaseModel):
+    """Individual pattern match result."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    input: str
+    matched: bool
+    groups: list[str] | None = None
+
+
+class TestPatternResult(BaseModel):
+    """Result of testing a regex pattern."""
+
+    valid: bool
+    error: str | None = None
+    pattern: str = ""
+    inputs: list[str] = Field(default_factory=list)
+    matches: list[TestPatternMatch] = Field(default_factory=list)
+
+
+# ============================================================================
+# Policy Version Types
+# ============================================================================
+
+
+class PolicyVersion(BaseModel):
+    """Policy version history entry."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    version: int
+    changed_by: str | None = Field(default=None, alias="changedBy")
+    changed_at: datetime = Field(..., alias="changedAt")
+    change_type: str = Field(..., alias="changeType")
+    change_description: str | None = Field(default=None, alias="changeDescription")
+    previous_values: dict[str, Any] | None = Field(default=None, alias="previousValues")
+    new_values: dict[str, Any] | None = Field(default=None, alias="newValues")
+
+
+# ============================================================================
+# Effective Policies Types
+# ============================================================================
+
+
+class EffectivePoliciesOptions(BaseModel):
+    """Options for getting effective policies."""
+
+    category: PolicyCategory | None = None
+    include_disabled: bool = False
+    include_overridden: bool = False

axonflow/types.py

@@ -0,0 +1,214 @@
+"""AxonFlow SDK Type Definitions.
+
+All types are defined using Pydantic v2 for runtime validation
+and automatic JSON serialization/deserialization.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Mode(str, Enum):
+    """SDK operation mode."""
+
+    PRODUCTION = "production"
+    SANDBOX = "sandbox"
+
+
+class RetryConfig(BaseModel):
+    """Retry configuration with exponential backoff."""
+
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = Field(default=True, description="Enable retry logic")
+    max_attempts: int = Field(default=3, ge=1, le=10, description="Max retry attempts")
+    initial_delay: float = Field(default=1.0, gt=0, description="Initial delay (seconds)")
+    max_delay: float = Field(default=30.0, gt=0, description="Max delay (seconds)")
+    exponential_base: float = Field(default=2.0, gt=1, description="Backoff multiplier")
+
+
+class CacheConfig(BaseModel):
+    """Cache configuration."""
+
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = Field(default=True, description="Enable caching")
+    ttl: float = Field(default=60.0, gt=0, description="Cache TTL (seconds)")
+    max_size: int = Field(default=1000, gt=0, description="Max cache entries")
+
+
+class AxonFlowConfig(BaseModel):
+    """Configuration for AxonFlow client.
+
+    Attributes:
+        agent_url: AxonFlow Agent URL (required)
+        client_id: Client ID for authentication (required)
+        client_secret: Client secret for authentication (required)
+        license_key: Optional license key for organization-level auth
+        mode: Operation mode (production or sandbox)
+        debug: Enable debug logging
+        timeout: Request timeout in seconds
+        insecure_skip_verify: Skip TLS verification (dev only)
+        retry: Retry configuration
+        cache: Cache configuration
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    agent_url: str = Field(..., min_length=1, description="AxonFlow Agent URL")
+    client_id: str = Field(..., min_length=1, description="Client ID")
+    client_secret: str = Field(..., min_length=1, description="Client secret")
+    license_key: str | None = Field(default=None, description="License key")
+    mode: Mode = Field(default=Mode.PRODUCTION, description="Operation mode")
+    debug: bool = Field(default=False, description="Enable debug logging")
+    timeout: float = Field(default=60.0, gt=0, description="Request timeout (seconds)")
+    map_timeout: float = Field(default=120.0, gt=0, description="MAP operations timeout (seconds)")
+    insecure_skip_verify: bool = Field(default=False, description="Skip TLS verify")
+    retry: RetryConfig = Field(default_factory=RetryConfig)
+    cache: CacheConfig = Field(default_factory=CacheConfig)
+
+
+class ClientRequest(BaseModel):
+    """Request to AxonFlow Agent."""
+
+    query: str = Field(..., description="Query or prompt")
+    user_token: str = Field(..., description="User token for auth")
+    client_id: str = Field(..., description="Client ID")
+    request_type: str = Field(..., description="Request type")
+    context: dict[str, Any] = Field(default_factory=dict, description="Additional context")
+
+
+class PolicyEvaluationInfo(BaseModel):
+    """Policy evaluation metadata."""
+
+    policies_evaluated: list[str] = Field(default_factory=list)
+    static_checks: list[str] = Field(default_factory=list)
+    processing_time: str = Field(default="0ms")
+    tenant_id: str = Field(default="")
+
+
+class ClientResponse(BaseModel):
+    """Response from AxonFlow Agent."""
+
+    success: bool = Field(..., description="Whether request succeeded")
+    data: Any | None = Field(default=None, description="Response data")
+    result: str | None = Field(default=None, description="Result for planning")
+    plan_id: str | None = Field(default=None, description="Plan ID if applicable")
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = Field(default=None, description="Error message if failed")
+    blocked: bool = Field(default=False, description="Whether request was blocked")
+    block_reason: str | None = Field(default=None, description="Block reason")
+    policy_info: PolicyEvaluationInfo | None = Field(default=None)
+
+
+class ConnectorMetadata(BaseModel):
+    """MCP connector metadata."""
+
+    id: str
+    name: str
+    type: str
+    version: str = ""
+    description: str = ""
+    category: str = ""
+    icon: str = ""
+    tags: list[str] = Field(default_factory=list)
+    capabilities: list[str] = Field(default_factory=list)
+    config_schema: dict[str, Any] = Field(default_factory=dict)
+    installed: bool = False
+    healthy: bool = False
+
+
+class ConnectorInstallRequest(BaseModel):
+    """Request to install an MCP connector."""
+
+    connector_id: str
+    name: str
+    tenant_id: str
+    options: dict[str, Any] = Field(default_factory=dict)
+    credentials: dict[str, str] = Field(default_factory=dict)
+
+
+class ConnectorResponse(BaseModel):
+    """Response from MCP connector query."""
+
+    success: bool
+    data: Any | None = None
+    error: str | None = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlanStep(BaseModel):
+    """A step in a multi-agent plan."""
+
+    id: str
+    name: str
+    type: str
+    description: str = ""
+    depends_on: list[str] = Field(default_factory=list)
+    agent: str = ""
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlanResponse(BaseModel):
+    """Multi-agent plan response."""
+
+    plan_id: str
+    steps: list[PlanStep] = Field(default_factory=list)
+    domain: str = "generic"
+    complexity: int = 0
+    parallel: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlanExecutionResponse(BaseModel):
+    """Plan execution result."""
+
+    plan_id: str
+    status: str  # "running", "completed", "failed"
+    result: str | None = None
+    step_results: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+    duration: str | None = None
+
+
+# Gateway Mode Types
+
+
+class RateLimitInfo(BaseModel):
+    """Rate limiting status."""
+
+    limit: int
+    remaining: int
+    reset_at: datetime
+
+
+class PolicyApprovalResult(BaseModel):
+    """Pre-check result from Gateway Mode."""
+
+    context_id: str = Field(..., description="Context ID for audit linking")
+    approved: bool = Field(..., description="Whether request is approved")
+    approved_data: dict[str, Any] = Field(default_factory=dict)
+    policies: list[str] = Field(default_factory=list)
+    rate_limit_info: RateLimitInfo | None = None
+    expires_at: datetime
+    block_reason: str | None = None
+
+
+class TokenUsage(BaseModel):
+    """LLM token usage tracking."""
+
+    prompt_tokens: int = Field(ge=0)
+    completion_tokens: int = Field(ge=0)
+    total_tokens: int = Field(ge=0)
+
+
+class AuditResult(BaseModel):
+    """Audit confirmation."""
+
+    success: bool
+    audit_id: str

axonflow/utils/__init__.py

@@ -0,0 +1,12 @@
+"""AxonFlow SDK Utilities."""
+
+from axonflow.utils.cache import CacheManager
+from axonflow.utils.logging import configure_logging, get_logger
+from axonflow.utils.retry import RetryHandler
+
+__all__ = [
+    "CacheManager",
+    "RetryHandler",
+    "configure_logging",
+    "get_logger",
+]

axonflow/utils/cache.py

@@ -0,0 +1,102 @@
+"""Cache utilities for AxonFlow SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from cachetools import TTLCache
+
+T = TypeVar("T")
+
+
+class CacheManager(Generic[T]):
+    """Generic cache manager with TTL support.
+
+    Provides a simple interface for caching with automatic expiration.
+    """
+
+    def __init__(self, maxsize: int = 1000, ttl: float = 60.0) -> None:
+        """Initialize cache manager.
+
+        Args:
+            maxsize: Maximum number of entries
+            ttl: Time-to-live in seconds
+        """
+        self._cache: TTLCache[str, T] = TTLCache(maxsize=maxsize, ttl=ttl)
+        self._ttl = ttl
+        self._maxsize = maxsize
+
+    def get(self, key: str) -> T | None:
+        """Get a value from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found
+        """
+        result: T | None = self._cache.get(key)
+        return result
+
+    def set(self, key: str, value: T) -> None:
+        """Set a value in cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+        """
+        self._cache[key] = value
+
+    def delete(self, key: str) -> None:
+        """Delete a value from cache.
+
+        Args:
+            key: Cache key
+        """
+        self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all cached values."""
+        self._cache.clear()
+
+    def contains(self, key: str) -> bool:
+        """Check if key exists in cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if key exists
+        """
+        return key in self._cache
+
+    @property
+    def size(self) -> int:
+        """Get current cache size."""
+        return len(self._cache)
+
+    @property
+    def ttl(self) -> float:
+        """Get cache TTL."""
+        return self._ttl
+
+    @property
+    def maxsize(self) -> int:
+        """Get maximum cache size."""
+        return self._maxsize
+
+    def get_or_set(self, key: str, factory: Any) -> T:
+        """Get from cache or create using factory.
+
+        Args:
+            key: Cache key
+            factory: Callable to create value if not cached
+
+        Returns:
+            Cached or newly created value
+        """
+        value = self.get(key)
+        if value is None:
+            value = factory()
+            self.set(key, value)
+        return value

axonflow/utils/logging.py

@@ -0,0 +1,89 @@
+"""Logging utilities for AxonFlow SDK."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+import structlog
+
+
+def configure_logging(
+    level: int = logging.INFO,
+    json_format: bool = False,
+) -> None:
+    """Configure structured logging for AxonFlow SDK.
+
+    Args:
+        level: Logging level (default: INFO)
+        json_format: Use JSON format for logs (default: False)
+    """
+    # Configure structlog processors
+    processors: list[Any] = [
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if json_format:
+        processors.append(structlog.processors.JSONRenderer())
+    else:
+        processors.append(structlog.dev.ConsoleRenderer())
+
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    # Configure stdlib logging
+    logging.basicConfig(
+        format="%(message)s",
+        stream=sys.stdout,
+        level=level,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get a structured logger.
+
+    Args:
+        name: Logger name
+
+    Returns:
+        Configured structured logger
+    """
+    logger: structlog.stdlib.BoundLogger = structlog.get_logger(name)
+    return logger
+
+
+class LogContext:
+    """Context manager for adding log context."""
+
+    def __init__(self, logger: structlog.stdlib.BoundLogger, **context: Any) -> None:
+        """Initialize log context.
+
+        Args:
+            logger: Logger to bind context to
+            **context: Context key-value pairs
+        """
+        self._logger = logger
+        self._context = context
+        self._original_context: dict[str, Any] = {}
+
+    def __enter__(self) -> structlog.stdlib.BoundLogger:
+        """Enter context and bind values."""
+        self._original_context = dict(getattr(self._logger, "_context", {}))
+        return self._logger.bind(**self._context)
+
+    def __exit__(self, *args: Any) -> None:
+        """Exit context and restore original values."""
+        # Restore original context
+        self._logger._context = self._original_context  # noqa: B010, SLF001