agentic-fabriq-sdk 0.1.3__py3-none-any.whl

af_sdk/exceptions.py

@@ -0,0 +1,140 @@
+"""
+Exception classes for the Agentic Fabric SDK.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class AFError(Exception):
+    """Base exception for all Agentic Fabric errors."""
+
+    def __init__(
+        self,
+        message: str,
+        error_code: str = "SERVER_ERROR",
+        request_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        self.message = message
+        self.error_code = error_code
+        self.request_id = request_id
+        self.details = details or {}
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"{self.error_code}: {self.message}"
+
+
+class AuthenticationError(AFError):
+    """Authentication failed - missing or invalid JWT or mTLS cert."""
+
+    def __init__(self, message: str = "Authentication failed", **kwargs):
+        super().__init__(message, error_code="AUTHENTICATION_FAILED", **kwargs)
+
+
+class AuthorizationError(AFError):
+    """Authorization failed - OPA policy denied or scope mismatch."""
+
+    def __init__(self, message: str = "Authorization denied", **kwargs):
+        super().__init__(message, error_code="FORBIDDEN", **kwargs)
+
+
+class NotFoundError(AFError):
+    """Resource or endpoint not found."""
+
+    def __init__(self, message: str = "Resource not found", **kwargs):
+        super().__init__(message, error_code="NOT_FOUND", **kwargs)
+
+
+class ValidationError(AFError):
+    """Request validation failed."""
+
+    def __init__(self, message: str = "Validation failed", **kwargs):
+        super().__init__(message, error_code="VALIDATION_ERROR", **kwargs)
+
+
+class ConflictError(AFError):
+    """Resource conflict - duplicate ID or version clash."""
+
+    def __init__(self, message: str = "Resource conflict", **kwargs):
+        super().__init__(message, error_code="CONFLICT", **kwargs)
+
+
+class RateLimitError(AFError):
+    """Rate limit exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded", **kwargs):
+        super().__init__(message, error_code="RATE_LIMITED", **kwargs)
+
+
+class UpstreamError(AFError):
+    """Error from upstream service."""
+
+    def __init__(self, message: str = "Upstream service error", **kwargs):
+        super().__init__(message, error_code="UPSTREAM_ERROR", **kwargs)
+
+
+class ServiceUnavailableError(AFError):
+    """Service temporarily unavailable."""
+
+    def __init__(self, message: str = "Service unavailable", **kwargs):
+        super().__init__(message, error_code="SERVICE_UNAVAILABLE", **kwargs)
+
+
+class ConnectorError(AFError):
+    """Error in connector implementation."""
+
+    def __init__(self, message: str = "Connector error", **kwargs):
+        super().__init__(message, error_code="CONNECTOR_ERROR", **kwargs)
+
+
+class TokenRefreshError(AFError):
+    """Failed to refresh OAuth token."""
+
+    def __init__(self, message: str = "Token refresh failed", **kwargs):
+        super().__init__(message, error_code="TOKEN_REFRESH_ERROR", **kwargs)
+
+
+class VaultError(AFError):
+    """Error accessing vault/secrets."""
+
+    def __init__(self, message: str = "Vault error", **kwargs):
+        super().__init__(message, error_code="VAULT_ERROR", **kwargs)
+
+
+class EventError(AFError):
+    """Error in event processing."""
+
+    def __init__(self, message: str = "Event error", **kwargs):
+        super().__init__(message, error_code="EVENT_ERROR", **kwargs)
+
+
+# Mapping from error codes to exception classes
+ERROR_CODE_TO_EXCEPTION = {
+    "AUTHENTICATION_FAILED": AuthenticationError,
+    "FORBIDDEN": AuthorizationError,
+    "NOT_FOUND": NotFoundError,
+    "VALIDATION_ERROR": ValidationError,
+    "CONFLICT": ConflictError,
+    "RATE_LIMITED": RateLimitError,
+    "UPSTREAM_ERROR": UpstreamError,
+    "SERVICE_UNAVAILABLE": ServiceUnavailableError,
+    "CONNECTOR_ERROR": ConnectorError,
+    "TOKEN_REFRESH_ERROR": TokenRefreshError,
+    "VAULT_ERROR": VaultError,
+}
+
+
+def create_exception_from_response(response_data: Dict[str, Any]) -> AFError:
+    """Create an exception from an API error response."""
+    error_code = response_data.get("error", "SERVER_ERROR")
+    message = response_data.get("message", "Unknown error")
+    request_id = response_data.get("request_id")
+    details = response_data.get("details", {})
+
+    exception_class = ERROR_CODE_TO_EXCEPTION.get(error_code, AFError)
+    return exception_class(
+        message=message,
+        request_id=request_id,
+        details=details,
+    ) 

af_sdk/fabriq_client.py

@@ -0,0 +1,198 @@
+"""
+FabriqClient: High-level async helper for Agentic Fabric Gateway.
+
+This client wraps common Gateway API flows so agent developers can:
+- List and invoke tools
+- Register and invoke MCP servers (via proxy)
+- Invoke agents (via proxy)
+- Manage per-user secrets via the Gateway-backed Vault API
+
+Usage:
+    from af_sdk.fabriq_client import FabriqClient
+
+    async with FabriqClient(base_url="http://localhost:8000", auth_token=JWT) as af:
+        tools = await af.list_tools()
+        result = await af.invoke_tool(tool_id, method="list_items", parameters={"limit": 10})
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .transport.http import HTTPClient
+
+
+class FabriqClient:
+    """Async helper around the Gateway REST API.
+
+    Args:
+        base_url: Gateway base URL (e.g., "http://localhost:8000").
+        auth_token: Bearer JWT with required scopes.
+        api_prefix: API root prefix. Defaults to "/api/v1".
+        timeout: Request timeout in seconds.
+        retries: Number of retry attempts for transient errors.
+        backoff_factor: Exponential backoff base delay in seconds.
+        trace_enabled: Enable OpenTelemetry HTTPX instrumentation.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth_token: Optional[str] = None,
+        api_prefix: str = "/api/v1",
+        timeout: float = 30.0,
+        retries: int = 3,
+        backoff_factor: float = 0.5,
+        trace_enabled: bool = True,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self._root = base_url.rstrip("/")
+        self._api = api_prefix if api_prefix.startswith("/") else f"/{api_prefix}"
+        self._extra_headers = extra_headers or {}
+        self._http = HTTPClient(
+            base_url=f"{self._root}{self._api}",
+            timeout=timeout,
+            retries=retries,
+            backoff_factor=backoff_factor,
+            auth_token=auth_token,
+            trace_enabled=trace_enabled,
+        )
+
+    async def __aenter__(self) -> "FabriqClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    # -----------------
+    # Tools
+    # -----------------
+    async def list_tools(self, *, page: int = 1, page_size: int = 20, search: Optional[str] = None) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        if search:
+            params["search"] = search
+        r = await self._http.get("/tools", params=params, headers=self._extra_headers)
+        return r.json()
+
+    async def invoke_tool(
+        self,
+        tool_id: str,
+        *,
+        method: str,
+        parameters: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        body = {"method": method}
+        if parameters is not None:
+            body["parameters"] = parameters
+        if context is not None:
+            body["context"] = context
+        r = await self._http.post(f"/tools/{tool_id}/invoke", json=body, headers=self._extra_headers)
+        return r.json()
+
+    # -----------------
+    # MCP Servers
+    # -----------------
+    async def register_mcp_server(
+        self,
+        *,
+        name: str,
+        base_url: str,
+        description: Optional[str] = None,
+        auth_type: str = "API_KEY",
+        source: str = "STATIC",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "name": name,
+            "base_url": base_url,
+            "auth_type": auth_type,
+            "source": source,
+        }
+        if description is not None:
+            body["description"] = description
+        if metadata is not None:
+            body["metadata"] = metadata
+        r = await self._http.post("/mcp/servers", json=body, headers=self._extra_headers)
+        return r.json()
+
+    async def list_mcp_servers(self, *, page: int = 1, page_size: int = 20, search: Optional[str] = None) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        if search:
+            params["search"] = search
+        r = await self._http.get("/mcp/servers", params=params, headers=self._extra_headers)
+        return r.json()
+
+    async def invoke_mcp(self, *, server_id: str, payload: Dict[str, Any], raw: bool = False) -> Dict[str, Any]:
+        r = await self._http.post(f"/proxy/mcp/{server_id}/invoke", json={"payload": payload, "raw": raw}, headers=self._extra_headers)
+        return r.json()
+
+    # -----------------
+    # Agents
+    # -----------------
+    async def list_agents(self, *, page: int = 1, page_size: int = 20, sort_by: str = "name", sort_order: str = "asc") -> Dict[str, Any]:
+        params: Dict[str, Any] = {"page": page, "page_size": page_size, "sort_by": sort_by, "sort_order": sort_order}
+        r = await self._http.get("/agents", params=params, headers=self._extra_headers)
+        return r.json()
+
+    async def invoke_agent(self, *, agent_id: str, params: Dict[str, Any], raw: bool = False) -> Dict[str, Any]:
+        r = await self._http.post(f"/proxy/agents/{agent_id}/invoke", json={"params": params, "raw": raw}, headers=self._extra_headers)
+        return r.json()
+
+    # -----------------
+    # Secrets (Gateway-backed Vault)
+    # -----------------
+    async def get_secret(self, *, path: str, version: Optional[int] = None) -> Dict[str, Any]:
+        params = {"version": version} if version is not None else None
+        r = await self._http.get(f"/secrets/{path}", params=params, headers=self._extra_headers)
+        return r.json()
+
+    async def create_secret(
+        self,
+        *,
+        path: str,
+        value: str,
+        description: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        ttl: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"value": value}
+        if description is not None:
+            body["description"] = description
+        if metadata is not None:
+            body["metadata"] = metadata
+        if ttl is not None:
+            body["ttl"] = ttl
+        r = await self._http.post(f"/secrets/{path}", json=body, headers=self._extra_headers)
+        return r.json()
+
+    async def update_secret(
+        self,
+        *,
+        path: str,
+        value: Optional[str] = None,
+        description: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        ttl: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if value is not None:
+            body["value"] = value
+        if description is not None:
+            body["description"] = description
+        if metadata is not None:
+            body["metadata"] = metadata
+        if ttl is not None:
+            body["ttl"] = ttl
+        r = await self._http.put(f"/secrets/{path}", json=body, headers=self._extra_headers)
+        return r.json()
+
+    async def delete_secret(self, *, path: str) -> Dict[str, Any]:
+        r = await self._http.delete(f"/secrets/{path}", headers=self._extra_headers)
+        return r.json() if r.content else {"status": "deleted"}
+
+

af_sdk/models/__init__.py

@@ -0,0 +1,47 @@
+"""
+Data models for Agentic Fabric SDK.
+"""
+
+from .types import (
+    Agent,
+    AgentCreate,
+    AgentInvokeRequest,
+    AgentInvokeResult,
+    ErrorResponse,
+    HealthResponse,
+    McpServer,
+    McpServerCreate,
+    MetricsResponse,
+    OAuthToken,
+    PaginatedResponse,
+    Secret,
+    SecretMetadata,
+    SecretPutRequest,
+    TokenExchangeRequest,
+    TokenExchangeResponse,
+    Tool,
+    ToolInvokeRequest,
+    ToolInvokeResult,
+)
+
+__all__ = [
+    "Agent",
+    "AgentCreate",
+    "AgentInvokeRequest",
+    "AgentInvokeResult",
+    "Tool",
+    "ToolInvokeRequest",
+    "ToolInvokeResult",
+    "McpServer",
+    "McpServerCreate",
+    "Secret",
+    "SecretMetadata",
+    "SecretPutRequest",
+    "TokenExchangeRequest",
+    "TokenExchangeResponse",
+    "OAuthToken",
+    "ErrorResponse",
+    "PaginatedResponse",
+    "HealthResponse",
+    "MetricsResponse",
+] 

af_sdk/models/audit.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, Field
+from uuid import uuid4
+
+
+class AuditEvent(BaseModel):
+    """Canonical audit event schema.
+
+    Designed to avoid storing sensitive values; callers should pre-redact.
+    """
+
+    event_id: str = Field(default_factory=lambda: str(uuid4()))
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    tenant_id: str
+    actor_id: Optional[str] = None
+    actor_scopes: Optional[list[str]] = None
+    source_service: str  # af-gateway | af-registry | other
+    action: str          # e.g., agent.create, tool.delete, auth.login
+    resource_type: Optional[str] = None
+    resource_id: Optional[str] = None
+    route: Optional[str] = None
+    method: Optional[str] = None
+    status: str = "success"  # success | failure | denied
+    request_id: Optional[str] = None
+    client_ip: Optional[str] = None
+    user_agent: Optional[str] = None
+    mtls_san: Optional[str] = None
+    pop_thumbprint: Optional[str] = None
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+
+def build_audit_subject(source_service: str, action: str, tenant_id: str) -> str:
+    """Generate audit subject aligned with AUDIT stream subjects.
+
+    Format: audit.<service>.<action>.<tenant>
+    """
+    service = source_service.replace("_", "-")
+    action_norm = action.replace("/", ".")
+    return f"audit.{service}.{action_norm}.{tenant_id}"
+
+

af_sdk/models/types.py

@@ -0,0 +1,242 @@
+"""
+Pydantic models for Agentic Fabric SDK.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class Agent(BaseModel):
+    """Agent model."""
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    owner: str
+    tenant_id: str
+    group_path: Optional[str] = None
+    endpoint_url: Optional[str] = None
+    auth_type: Optional[str] = None
+    scopes: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime
+    updated_at: datetime
+
+
+class AgentCreate(BaseModel):
+    """Request model for creating an agent."""
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    endpoint_url: Optional[str] = None
+    auth_type: Optional[str] = None
+    scopes: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    group_path: Optional[str] = None
+
+
+class AgentInvokeRequest(BaseModel):
+    """Request model for invoking an agent."""
+
+    input: str
+    params: Dict[str, Any] = Field(default_factory=dict)
+    max_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    stream: bool = False
+
+
+class AgentInvokeResult(BaseModel):
+    """Result model for agent invocation."""
+
+    output: str
+    logs: List[str] = Field(default_factory=list)
+    usage: Optional[Dict[str, Any]] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    status: str = "success"
+
+
+class Tool(BaseModel):
+    """Tool model."""
+
+    id: str
+    name: str
+    version: str
+    description: Optional[str] = None
+    protocol: str = "MCP"
+    auth_type: str = "OAuth2"
+    scopes: List[str] = Field(default_factory=list)
+    endpoints: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime
+    updated_at: datetime
+
+
+class ToolInvokeRequest(BaseModel):
+    """Request model for invoking a tool.
+
+    DX alignment: Gateway expects `parameters` and `context`.
+    For backward compatibility, we still accept `args` on input and map it to `parameters`.
+    """
+
+    method: str
+    parameters: Dict[str, Any] = Field(default_factory=dict)
+    context: Dict[str, Any] = Field(default_factory=dict)
+    # Back-compat input alias; not used in output
+    args: Optional[Dict[str, Any]] = None
+    timeout: Optional[int] = None
+
+    # Support pydantic v1 and v2 root validation to map args->parameters
+    @classmethod
+    def __get_validators__(cls):  # type: ignore[override]
+        # Pydantic v1 compatibility hook
+        yield cls._pre_root_validator
+
+    @classmethod
+    def _pre_root_validator(cls, values):
+        # When constructed from dict, map legacy `args` to `parameters` if provided
+        if isinstance(values, dict):
+            if "parameters" not in values and "args" in values and isinstance(values["args"], dict):
+                # Don't mutate original input dict unexpectedly
+                new_values = dict(values)
+                new_values["parameters"] = new_values.get("args", {}) or {}
+                return new_values
+        return values
+
+
+class ToolInvokeResult(BaseModel):
+    """Result model for tool invocation.
+
+    DX alignment: Gateway returns `{ result, metadata, logs }`.
+    We keep prior fields (`status`, `data`, `headers`) optional for back-compat.
+    """
+
+    # Gateway-aligned fields
+    result: Optional[Any] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    logs: Optional[list[str]] = None
+
+    # Back-compat fields
+    status: Optional[str] = None
+    data: Optional[Any] = None
+    headers: Dict[str, str] = Field(default_factory=dict)
+
+
+class McpServer(BaseModel):
+    """MCP Server model."""
+
+    id: UUID
+    base_url: str
+    auth_type: str = Field(description="One of: API_KEY, MTLS, OIDC")
+    source: str = Field(description="One of: STATIC, DISCOVERED, SLACK, CONFIG")
+    tenant_id: str
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime
+    updated_at: datetime
+
+
+class McpServerCreate(BaseModel):
+    """Request model for creating an MCP server."""
+
+    base_url: str
+    auth_type: str = Field(description="One of: API_KEY, MTLS, OIDC")
+    source: str = Field(description="One of: STATIC, DISCOVERED, SLACK, CONFIG")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class Secret(BaseModel):
+    """Secret model."""
+
+    path: str
+    data: Dict[str, Any]
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    version: int
+    created_at: datetime
+
+
+class SecretMetadata(BaseModel):
+    """Secret metadata model."""
+
+    path: str
+    version: int
+    created_at: datetime
+    updated_at: datetime
+    versions: List[int] = Field(default_factory=list)
+
+
+class SecretPutRequest(BaseModel):
+    """Request model for creating/updating a secret."""
+
+    path: str
+    data: Dict[str, Any]
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class TokenExchangeRequest(BaseModel):
+    """Request model for token exchange (RFC 8693)."""
+
+    subject_token: str
+    actor_token: Optional[str] = None
+    scope: Optional[str] = None
+    audience: Optional[str] = None
+
+
+class TokenExchangeResponse(BaseModel):
+    """Response model for token exchange."""
+
+    access_token: str
+    token_type: str = "Bearer"
+    expires_in: int
+    scope: Optional[str] = None
+
+
+class OAuthToken(BaseModel):
+    """OAuth token model."""
+
+    access_token: str
+    refresh_token: Optional[str] = None
+    token_type: str = "Bearer"
+    expires_at: datetime
+    scopes: List[str] = Field(default_factory=list)
+
+
+class ErrorResponse(BaseModel):
+    """Error response model."""
+
+    error: str
+    message: str
+    request_id: Optional[str] = None
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+
+class PaginatedResponse(BaseModel):
+    """Paginated response model."""
+
+    items: List[Any]
+    total: int
+    page: int = 1
+    page_size: int = 50
+    has_next: bool = False
+    has_prev: bool = False
+
+
+class HealthResponse(BaseModel):
+    """Health check response model."""
+
+    status: str
+    version: str
+    timestamp: datetime
+    components: Dict[str, str] = Field(default_factory=dict)
+
+
+class MetricsResponse(BaseModel):
+    """Metrics response model."""
+
+    requests_total: int
+    requests_per_second: float
+    avg_response_time: float
+    error_rate: float
+    active_connections: int 

af_sdk/transport/__init__.py

@@ -0,0 +1,7 @@
+"""
+Transport layer for Agentic Fabric SDK.
+"""
+
+from .http import HTTPClient
+
+__all__ = ["HTTPClient"]