agentic-fabriq-sdk 0.1.3__tar.gz

agentic_fabriq_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: agentic-fabriq-sdk
+Version: 0.1.3
+Summary: Fabriq/Agentic Fabric Python SDK: high-level client, DX helpers, auth
+License: Apache-2.0
+Keywords: fabriq,agentic-fabric,sdk,ai,agents
+Author: Agentic Fabric Contributors
+Author-email: contributors@agentic-fabric.org
+Requires-Python: >=3.11,<3.13
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Dist: PyJWT (>=2.8.0)
+Requires-Dist: httpx (>=0.25)
+Requires-Dist: pydantic (>=2.4)
+Requires-Dist: stevedore (>=5.1.0)
+Requires-Dist: typing-extensions
+Project-URL: Documentation, https://docs.agentic-fabric.org
+Project-URL: Homepage, https://github.com/agentic-fabric/agentic-fabric
+Project-URL: Repository, https://github.com/agentic-fabric/agentic-fabric
+Description-Content-Type: text/markdown
+
+# Agentic Fabric SDK (Fabriq)
+
+`agentic-fabriq-sdk` provides a Python SDK for interacting with Fabriq/Agentic Fabric.
+
+- High-level client: `af_sdk.FabriqClient`
+- DX layer: `af_sdk.dx` (`ToolFabric`, `AgentFabric`, `MCPServer`, `Agent`, and `tool`)
+
+## Install
+
+```bash
+pip install agentic-fabriq-sdk
+```
+
+## Quickstart
+
+```python
+from af_sdk.fabriq_client import FabriqClient
+
+TOKEN = "..."  # Bearer JWT for the Fabriq Gateway
+BASE = "http://localhost:8000"
+
+async def main():
+    async with FabriqClient(base_url=BASE, auth_token=TOKEN) as af:
+        agents = await af.list_agents()
+        print(agents)
+```
+
+DX orchestration:
+
+```python
+from af_sdk.dx import ToolFabric, AgentFabric, Agent, tool
+
+slack = ToolFabric(provider="slack", base_url="http://localhost:8000", access_token=TOKEN, tenant_id=TENANT)
+agents = AgentFabric(base_url="http://localhost:8000", access_token=TOKEN, tenant_id=TENANT)
+
+@tool
+def echo(x: str) -> str:
+    return x
+
+bot = Agent(
+    system_prompt="demo",
+    tools=[echo],
+    agents=agents.get_agents(["summarizer"]),
+    base_url="http://localhost:8000",
+    access_token=TOKEN,
+    tenant_id=TENANT,
+    provider_fabrics={"slack": slack},
+)
+print(bot.run("Summarize my Slack messages"))
+```
+
+## License
+
+Apache-2.0
+

agentic_fabriq_sdk-0.1.3/README.md

@@ -0,0 +1,54 @@
+# Agentic Fabric SDK (Fabriq)
+
+`agentic-fabriq-sdk` provides a Python SDK for interacting with Fabriq/Agentic Fabric.
+
+- High-level client: `af_sdk.FabriqClient`
+- DX layer: `af_sdk.dx` (`ToolFabric`, `AgentFabric`, `MCPServer`, `Agent`, and `tool`)
+
+## Install
+
+```bash
+pip install agentic-fabriq-sdk
+```
+
+## Quickstart
+
+```python
+from af_sdk.fabriq_client import FabriqClient
+
+TOKEN = "..."  # Bearer JWT for the Fabriq Gateway
+BASE = "http://localhost:8000"
+
+async def main():
+    async with FabriqClient(base_url=BASE, auth_token=TOKEN) as af:
+        agents = await af.list_agents()
+        print(agents)
+```
+
+DX orchestration:
+
+```python
+from af_sdk.dx import ToolFabric, AgentFabric, Agent, tool
+
+slack = ToolFabric(provider="slack", base_url="http://localhost:8000", access_token=TOKEN, tenant_id=TENANT)
+agents = AgentFabric(base_url="http://localhost:8000", access_token=TOKEN, tenant_id=TENANT)
+
+@tool
+def echo(x: str) -> str:
+    return x
+
+bot = Agent(
+    system_prompt="demo",
+    tools=[echo],
+    agents=agents.get_agents(["summarizer"]),
+    base_url="http://localhost:8000",
+    access_token=TOKEN,
+    tenant_id=TENANT,
+    provider_fabrics={"slack": slack},
+)
+print(bot.run("Summarize my Slack messages"))
+```
+
+## License
+
+Apache-2.0

agentic_fabriq_sdk-0.1.3/af_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""
+Agentic Fabric SDK
+
+Official Python SDK for building connectors and interacting with Agentic Fabric.
+"""
+
+from .auth.oauth import oauth_required
+from .connectors.base import AgentConnector, ConnectorContext, ToolConnector
+from .exceptions import (
+    AFError,
+    AuthenticationError,
+    AuthorizationError,
+    ConnectorError,
+    NotFoundError,
+    ValidationError,
+)
+from .models.types import (
+    AgentInvokeRequest,
+    AgentInvokeResult,
+    ToolInvokeRequest,
+    ToolInvokeResult,
+)
+from .transport.http import HTTPClient
+from .fabriq_client import FabriqClient
+from .models.audit import AuditEvent
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "oauth_required",
+    "ToolConnector",
+    "AgentConnector",
+    "ConnectorContext",
+    "AFError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConnectorError",
+    "NotFoundError",
+    "ValidationError",
+    "AgentInvokeRequest",
+    "AgentInvokeResult",
+    "ToolInvokeRequest",
+    "ToolInvokeResult",
+    "HTTPClient",
+    "FabriqClient",
+    "AuditEvent",
+] 
+
+# Lazy expose dx submodule under af_sdk.dx
+from importlib import import_module as _import_module  # noqa: E402
+
+def __getattr__(name):
+    if name == "dx":
+        return _import_module("af_sdk.dx")
+    raise AttributeError(name)

agentic_fabriq_sdk-0.1.3/af_sdk/auth/__init__.py

@@ -0,0 +1,31 @@
+"""
+Authentication and authorization utilities for Agentic Fabric SDK.
+"""
+
+from .oauth import (
+    api_key_required,
+    mtls_required,
+    no_auth_required,
+    oauth_required,
+    ScopeValidator,
+    TokenValidator,
+)
+from .token_cache import TokenManager, VaultClient
+
+# DPoP helper will be provided from af_sdk.auth.dpop
+try:
+    from .dpop import create_dpop_proof
+except Exception:  # pragma: no cover - optional import if file missing
+    create_dpop_proof = None  # type: ignore
+
+__all__ = [
+    "oauth_required",
+    "api_key_required",
+    "mtls_required",
+    "no_auth_required",
+    "ScopeValidator",
+    "TokenValidator",
+    "TokenManager",
+    "VaultClient",
+    "create_dpop_proof",
+] 

agentic_fabriq_sdk-0.1.3/af_sdk/auth/dpop.py

@@ -0,0 +1,43 @@
+"""
+Client-side DPoP (Proof of Possession) helper for AF SDK.
+
+This provides a simple HMAC-signed JWT for development that matches the
+Gateway's mock PoP verifier semantics. In production, replace with a
+DPoP JWT signed using a private key corresponding to the client cert
+thumbprint per RFC 9449.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, Optional
+
+import jwt
+
+
+def create_dpop_proof(*, method: str, url: str, thumbprint: str = "dev-thumbprint", lifetime_s: int = 60, secret: Optional[str] = None) -> str:
+    """Create a development DPoP-like JWT for AF mock endpoints.
+
+    Args:
+        method: HTTP method, e.g., "POST".
+        url: Full request URL.
+        thumbprint: x5t#S256 thumbprint string (dev default).
+        lifetime_s: Token lifetime in seconds.
+        secret: HMAC secret for signing (dev only). If not provided, uses a default.
+
+    Returns:
+        A compact JWT string to send in the DPoP header.
+    """
+    now = int(time.time())
+    payload: Dict = {
+        "htm": method.upper(),
+        "htu": url,
+        "iat": now,
+        "exp": now + lifetime_s,
+        "cnf": {"x5t#S256": thumbprint},
+        "typ": "pop",
+    }
+    key = secret or "af-dev-pop-secret"
+    return jwt.encode(payload, key, algorithm="HS256")
+
+

agentic_fabriq_sdk-0.1.3/af_sdk/auth/oauth.py

@@ -0,0 +1,247 @@
+"""
+OAuth authentication decorator and helpers.
+"""
+
+import time
+from functools import wraps
+from typing import Any, Awaitable, Callable, List, Optional
+
+from ..exceptions import AuthenticationError, TokenRefreshError
+
+
+def oauth_required(*, scopes: List[str], refresh_if_expired: bool = True):
+    """
+    Decorator that injects a valid OAuth2 Bearer token for the current user.
+
+    Automatically:
+    1. Pulls access token from TokenManager (refreshes if expired)
+    2. Populates `Authorization` header
+    3. Enforces that requested scopes ⊆ granted scopes
+
+    Args:
+        scopes: List of required OAuth scopes
+        refresh_if_expired: Whether to attempt token refresh if expired
+
+    Raises:
+        AuthenticationError: If token is invalid or missing
+        TokenRefreshError: If token refresh fails
+    """
+
+    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            ctx = getattr(self, "ctx", None)
+            if not ctx:
+                raise AuthenticationError("Connector context not available")
+
+            tool_id = getattr(self, "TOOL_ID", None)
+            if not tool_id:
+                raise AuthenticationError("TOOL_ID not set in connector")
+
+            try:
+                # Get OAuth token from token manager
+                token = await ctx.token_manager.get_oauth_token(
+                    tool_id=tool_id,
+                    user_id=ctx.user_id,
+                    scopes=scopes,
+                    refresh_if_expired=refresh_if_expired,
+                )
+
+                # Inject Authorization header
+                headers = kwargs.setdefault("headers", {})
+                headers.setdefault("Authorization", f"Bearer {token}")
+
+                # Log the request (without token)
+                ctx.logger.info(
+                    f"Making OAuth request to {tool_id}",
+                    extra={"scopes": scopes, "user_id": ctx.user_id},
+                )
+
+                return await fn(self, *args, **kwargs)
+
+            except Exception as e:
+                ctx.logger.error(f"OAuth authentication failed: {e}")
+                if isinstance(e, (AuthenticationError, TokenRefreshError)):
+                    raise
+                raise AuthenticationError(f"OAuth authentication failed: {e}")
+
+        return wrapper
+
+    return decorator
+
+
+def api_key_required(*, key_name: str = "api_key", header_name: str = "X-API-Key"):
+    """
+    Decorator that injects an API key for the current user.
+
+    Args:
+        key_name: Name of the API key in the vault
+        header_name: HTTP header name for the API key
+
+    Raises:
+        AuthenticationError: If API key is missing or invalid
+    """
+
+    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            ctx = getattr(self, "ctx", None)
+            if not ctx:
+                raise AuthenticationError("Connector context not available")
+
+            tool_id = getattr(self, "TOOL_ID", None)
+            if not tool_id:
+                raise AuthenticationError("TOOL_ID not set in connector")
+
+            try:
+                # Get API key from vault
+                secret_path = f"af/{ctx.tenant_id}/{ctx.user_id}/api_keys/{tool_id}/{key_name}"
+                secret = await ctx.token_manager.vault_client.read_secret(secret_path)
+                
+                if not secret or "value" not in secret:
+                    raise AuthenticationError(f"API key not found: {key_name}")
+
+                api_key = secret["value"]
+
+                # Inject API key header
+                headers = kwargs.setdefault("headers", {})
+                headers.setdefault(header_name, api_key)
+
+                # Log the request
+                ctx.logger.info(
+                    f"Making API key request to {tool_id}",
+                    extra={"key_name": key_name, "user_id": ctx.user_id},
+                )
+
+                return await fn(self, *args, **kwargs)
+
+            except Exception as e:
+                ctx.logger.error(f"API key authentication failed: {e}")
+                if isinstance(e, AuthenticationError):
+                    raise
+                raise AuthenticationError(f"API key authentication failed: {e}")
+
+        return wrapper
+
+    return decorator
+
+
+def mtls_required(*, cert_path: Optional[str] = None, key_path: Optional[str] = None):
+    """
+    Decorator that configures mutual TLS authentication.
+
+    Args:
+        cert_path: Path to client certificate (optional, uses default if not provided)
+        key_path: Path to client private key (optional, uses default if not provided)
+
+    Raises:
+        AuthenticationError: If mTLS configuration fails
+    """
+
+    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            ctx = getattr(self, "ctx", None)
+            if not ctx:
+                raise AuthenticationError("Connector context not available")
+
+            try:
+                # Configure mTLS for the HTTP client
+                # This would typically be done at the session level
+                # For now, we'll add it to the kwargs
+                cert_config = (cert_path, key_path) if cert_path and key_path else None
+                kwargs.setdefault("cert", cert_config)
+
+                ctx.logger.info(
+                    "Making mTLS request",
+                    extra={"cert_path": cert_path, "user_id": ctx.user_id},
+                )
+
+                return await fn(self, *args, **kwargs)
+
+            except Exception as e:
+                ctx.logger.error(f"mTLS authentication failed: {e}")
+                raise AuthenticationError(f"mTLS authentication failed: {e}")
+
+        return wrapper
+
+    return decorator
+
+
+def no_auth_required(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+    """
+    Decorator that marks a method as not requiring authentication.
+    Useful for public endpoints or health checks.
+    """
+
+    @wraps(fn)
+    async def wrapper(self, *args, **kwargs):
+        ctx = getattr(self, "ctx", None)
+        if ctx:
+            ctx.logger.info("Making unauthenticated request")
+        return await fn(self, *args, **kwargs)
+
+    return wrapper
+
+
+class ScopeValidator:
+    """Helper class for validating OAuth scopes."""
+
+    @staticmethod
+    def validate_scopes(required_scopes: List[str], granted_scopes: List[str]) -> bool:
+        """
+        Validate that all required scopes are granted.
+
+        Args:
+            required_scopes: List of required scopes
+            granted_scopes: List of granted scopes
+
+        Returns:
+            True if all required scopes are granted, False otherwise
+        """
+        return set(required_scopes).issubset(set(granted_scopes))
+
+    @staticmethod
+    def missing_scopes(required_scopes: List[str], granted_scopes: List[str]) -> List[str]:
+        """
+        Get list of missing scopes.
+
+        Args:
+            required_scopes: List of required scopes
+            granted_scopes: List of granted scopes
+
+        Returns:
+            List of missing scopes
+        """
+        return list(set(required_scopes) - set(granted_scopes))
+
+
+class TokenValidator:
+    """Helper class for validating OAuth tokens."""
+
+    @staticmethod
+    def is_expired(expires_at: float) -> bool:
+        """
+        Check if a token is expired.
+
+        Args:
+            expires_at: Expiration timestamp
+
+        Returns:
+            True if token is expired, False otherwise
+        """
+        return time.time() >= expires_at
+
+    @staticmethod
+    def expires_soon(expires_at: float, buffer_seconds: int = 300) -> bool:
+        """
+        Check if a token expires soon.
+
+        Args:
+            expires_at: Expiration timestamp
+            buffer_seconds: Buffer time in seconds
+
+        Returns:
+            True if token expires within buffer time, False otherwise
+        """
+        return time.time() + buffer_seconds >= expires_at