docs: audit and improve public API surface (AGE-13)

packages/agents/src/keycardai/agents/__init__.py

@@ -30,16 +30,17 @@
     crewai = None
 
 __all__ = [
-    # Configuration
+    # === Configuration ===
     "AgentServiceConfig",
-    # Client
+    # === Client (Calling Agent Services) ===
     "AgentClient",
     "ServiceDiscovery",
-    # Server
+    # === Server (Building Agent Services) ===
     "AgentServer",
     "create_agent_card_server",
     "serve_agent",
+    # === Server-to-Server Delegation ===
     "DelegationClient",
-    # Integrations
-    "crewai",
+    # === Framework Integrations (Optional) ===
+    "crewai",  # May be None if crewai not installed
 ]

packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/__init__.py

@@ -9,6 +9,14 @@
 - Application credentials: ClientSecret, WebIdentity, EKSWorkloadIdentity for different authentication scenarios
 - Auth strategies: BasicAuth, MultiZoneBasicAuth, NoneAuth for HTTP client authentication
 
+Re-export Guide:
+    Local definitions (primary API): AuthProvider, AccessContext
+    From keycardai.mcp.server.auth: ApplicationCredential, ClientSecret, EKSWorkloadIdentity, WebIdentity
+    From keycardai.mcp.server.auth.client_factory: ClientFactory, DefaultClientFactory
+    From keycardai.oauth.http.auth: AuthStrategy, BasicAuth, MultiZoneBasicAuth, NoneAuth
+    From keycardai.mcp.server.exceptions: All exceptions
+    For canonical imports, use the source packages directly.
+
 Basic Usage:
 
     from fastmcp import FastMCP, Context
@@ -102,43 +110,41 @@ async def sync_calendar_to_drive(ctx: Context):
 from .testing import mock_access_context
 
 __all__ = [
-    # Core classes
+    # === Primary API (Local Definitions) ===
     "AuthProvider",
     "AccessContext",
-
-    # Application credentials
+    # === Application Credentials (re-exported from keycardai.mcp.server.auth) ===
     "ApplicationCredential",
     "ClientSecret",
     "EKSWorkloadIdentity",
     "WebIdentity",
-
-    # Client factory
+    # === Client Factory (Advanced - re-exported from keycardai.mcp.server.auth) ===
+    # Use ClientFactory protocol for custom implementations; DefaultClientFactory for defaults
     "ClientFactory",
     "DefaultClientFactory",
-
-    # Auth strategies
+    # === HTTP Auth Strategies (re-exported from keycardai.oauth.http.auth) ===
     "AuthStrategy",
     "BasicAuth",
     "MultiZoneBasicAuth",
     "NoneAuth",
-
-    # Exceptions - Base
+    # === Exceptions (re-exported from keycardai.mcp.server.exceptions) ===
+    # Base
     "MCPServerError",
-
-    # Exceptions - Specific
+    # Configuration
     "AuthProviderConfigurationError",
+    "OAuthClientConfigurationError",
+    "EKSWorkloadIdentityConfigurationError",
+    "ClientInitializationError",
+    # Runtime
     "AuthProviderInternalError",
     "AuthProviderRemoteError",
-    "ClientInitializationError",
-    "EKSWorkloadIdentityConfigurationError",
     "EKSWorkloadIdentityRuntimeError",
-    "JWKSValidationError",
-    "MissingContextError",
-    "OAuthClientConfigurationError",
-    "ResourceAccessError",
     "TokenExchangeError",
+    "ResourceAccessError",
+    "MissingContextError",
+    # Validation
+    "JWKSValidationError",
     "MetadataDiscoveryError",
-
-    # Testing utilities
+    # === Testing Utilities ===
     "mock_access_context",
 ]

packages/mcp/src/keycardai/mcp/client/__init__.py

@@ -1,3 +1,17 @@
+"""Keycard MCP Client.
+
+This module provides the MCP client for connecting to MCP servers with OAuth authentication.
+
+Primary API:
+    Client: High-level client for MCP operations
+    ClientManager: Manage multiple client instances
+    Context: Client context with auth state
+
+Advanced API (for custom implementations):
+    Session, SessionStatus, SessionStatusCategory: Low-level session management
+    AuthCoordinator subclasses: Custom auth coordination
+"""
+
 from .auth.coordinators import (
     AuthCoordinator,
     LocalAuthCoordinator,
@@ -20,35 +34,36 @@
 from .types import AuthChallenge, ToolInfo
 
 __all__ = [
-    # Core primitives
+    # === Primary API ===
     "Client",
     "ClientManager",
     "Context",
-    # Storage
+    # === Storage ===
     "StorageBackend",
     "InMemoryBackend",
     "SQLiteBackend",
     "NamespacedStorage",
-    # Auth coordination
+    # === Auth Coordination ===
     "AuthCoordinator",
     "LocalAuthCoordinator",
     "StarletteAuthCoordinator",
-    # Auth strategies
+    # === Auth Strategies ===
     "AuthStrategy",
     "OAuthStrategy",
     "ApiKeyStrategy",
     "NoAuthStrategy",
     "create_auth_strategy",
-    # Types
+    # === Types ===
     "AuthChallenge",
     "ToolInfo",
-    # Exceptions
-    "MCPClientError",
+    # === Exceptions ===
+    "MCPClientError",  # Base exception for MCP client errors
     "ClientConfigurationError",
-    # Logging
+    # === Logging ===
     "configure_logging",
     "get_logger",
-    # Lower-level primitives (advanced usage)
+    # === Advanced (Low-level Session Management) ===
+    # Use these only when building custom MCP client implementations
     "Session",
     "SessionStatus",
     "SessionStatusCategory",

packages/mcp/src/keycardai/mcp/server/auth/__init__.py

@@ -1,3 +1,15 @@
+"""Keycard MCP Server Authentication.
+
+This module provides authentication providers and token verification for MCP servers.
+
+Local Definitions:
+    AuthProvider, AccessContext, TokenVerifier: Core server auth components
+    ApplicationCredential, ClientSecret, WebIdentity, EKSWorkloadIdentity: Credential providers
+
+Re-exports (from keycardai.oauth):
+    AuthStrategy, BasicAuth, BearerAuth, MultiZoneBasicAuth, NoneAuth: HTTP auth strategies
+"""
+
 # Re-export auth strategies from keycardai.oauth for convenience
 from keycardai.oauth import (
     AuthStrategy,
@@ -27,24 +39,32 @@
 from .verifier import TokenVerifier
 
 __all__ = [
+    # === Core Authentication (Local) ===
     "AuthProvider",
     "AccessContext",
     "TokenVerifier",
+    # === Application Credentials (Local) ===
     "ApplicationCredential",
     "ClientSecret",
     "EKSWorkloadIdentity",
     "WebIdentity",
+    # === HTTP Auth Strategies (re-exported from keycardai.oauth) ===
     "AuthStrategy",
     "BasicAuth",
     "BearerAuth",
     "MultiZoneBasicAuth",
     "NoneAuth",
+    # === Exceptions (re-exported from ..exceptions) ===
+    # Configuration errors
     "AuthProviderConfigurationError",
     "EKSWorkloadIdentityConfigurationError",
+    # Runtime errors
     "EKSWorkloadIdentityRuntimeError",
+    "TokenExchangeError",
+    "ResourceAccessError",
+    # Context errors - MissingContextError is for FastMCP Context parameter,
+    # MissingAccessContextError is for Keycard AccessContext parameter
     "MissingAccessContextError",
     "MissingContextError",
-    "ResourceAccessError",
-    "TokenExchangeError",
     "MetadataDiscoveryError",
 ]

packages/oauth/src/keycardai/oauth/__init__.py

@@ -63,18 +63,18 @@
 from .utils.bearer import extract_bearer_token, validate_bearer_format
 
 __all__ = [
-    # Core clients
+    # === Core Clients ===
     "AsyncClient",
     "Client",
-    # Exceptions
-    "OAuthError",
+    # === Exceptions ===
+    "OAuthError",  # Base exception for all OAuth errors
     "OAuthHttpError",
     "OAuthProtocolError",
     "NetworkError",
     "ConfigError",
     "AuthenticationError",
     "TokenExchangeError",
-    # Models and types
+    # === Data Models ===
     "TokenResponse",
     "ClientRegistrationResponse",
     "PKCE",
@@ -83,21 +83,21 @@
     "ClientRegistrationRequest",
     "TokenExchangeRequest",
     "AuthorizationServerMetadata",
-    # Enums
+    # === OAuth Enums ===
     "GrantType",
     "ResponseType",
     "TokenEndpointAuthMethod",
     "TokenType",
     "TokenTypeHint",
     "PKCECodeChallengeMethod",
     "WellKnownEndpoint",
-    # Auth strategies
+    # === HTTP Auth Strategies ===
     "AuthStrategy",
     "BasicAuth",
     "BearerAuth",
     "NoneAuth",
     "MultiZoneBasicAuth",
-    # Utility functions
+    # === Utility Functions ===
     "extract_bearer_token",
     "validate_bearer_format",
 ]