embed-client-dev 4.0.78__py3-none-any.whl

embed_client/auth.py

@@ -0,0 +1,189 @@
+"""
+Authentication system for embed-client.
+
+This module provides authentication configuration validation for the embed-client.
+All actual authentication is handled by mcp_proxy_adapter JsonRpcClient,
+which uses mcp_security_framework internally.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import base64
+import logging
+from typing import Any, Dict, List, Optional
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails."""
+
+    def __init__(self, message: str, error_code: int = 401):
+        self.message = message
+        self.error_code = error_code
+        super().__init__(self.message)
+
+
+class AuthResult:
+    """Authentication result container."""
+
+    def __init__(
+        self,
+        success: bool,
+        user_id: Optional[str] = None,
+        roles: Optional[List[str]] = None,
+        error: Optional[str] = None,
+    ):
+        self.success = success
+        self.user_id = user_id
+        self.roles = roles or []
+        self.error = error
+
+
+class ClientAuthManager:
+    """
+    Client Authentication Manager.
+
+    This class provides ONLY configuration validation for the embed-client.
+    All actual authentication execution is handled by mcp_proxy_adapter JsonRpcClient,
+    which uses mcp_security_framework internally.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize authentication manager.
+
+        Args:
+            config: Authentication configuration dictionary
+
+        Note:
+            This class only validates configuration structure.
+            Actual authentication is handled by mcp_proxy_adapter JsonRpcClient.
+        """
+        self.config = config
+        self.logger = logging.getLogger(__name__)
+
+    def get_auth_headers(self, auth_method: str, **kwargs) -> Dict[str, str]:
+        """
+        Get authentication headers for requests.
+
+        Args:
+            auth_method: Authentication method
+            **kwargs: Additional authentication parameters
+
+        Returns:
+            Dictionary of headers
+        """
+        headers = {}
+
+        if auth_method == "api_key":
+            api_key = kwargs.get("api_key")
+            header_name = kwargs.get("header", "X-API-Key")
+            if api_key:
+                headers[header_name] = api_key
+
+        elif auth_method == "jwt":
+            token = kwargs.get("token")
+            if token:
+                headers["Authorization"] = f"Bearer {token}"
+
+        elif auth_method == "basic":
+            username = kwargs.get("username")
+            password = kwargs.get("password")
+            if username and password:
+                credentials = base64.b64encode(
+                    f"{username}:{password}".encode()
+                ).decode()
+                headers["Authorization"] = f"Basic {credentials}"
+
+        elif auth_method == "certificate":
+            # Certificate authentication is handled at SSL level
+            pass
+
+        return headers
+
+    def validate_auth_config(self) -> List[str]:
+        """
+        Validate authentication configuration.
+
+        Returns:
+            List of validation errors
+        """
+        errors = []
+        auth_config = self.config.get("auth", {})
+        auth_method = auth_config.get("method", "none")
+
+        if auth_method == "api_key":
+            api_keys = auth_config.get("api_keys", {})
+            if not api_keys:
+                errors.append("API keys not configured for api_key authentication")
+
+        elif auth_method == "jwt":
+            jwt_config = auth_config.get("jwt", {})
+            if not jwt_config.get("secret"):
+                errors.append("JWT secret not configured")
+            if not jwt_config.get("username"):
+                errors.append("JWT username not configured")
+            if not jwt_config.get("password"):
+                errors.append("JWT password not configured")
+
+        elif auth_method == "certificate":
+            cert_config = auth_config.get("certificate", {})
+            if not cert_config.get("cert_file"):
+                errors.append("Certificate file not configured")
+            if not cert_config.get("key_file"):
+                errors.append("Key file not configured")
+
+        elif auth_method == "basic":
+            basic_config = auth_config.get("basic", {})
+            if not basic_config.get("username"):
+                errors.append("Basic auth username not configured")
+            if not basic_config.get("password"):
+                errors.append("Basic auth password not configured")
+
+        return errors
+
+    def is_auth_enabled(self) -> bool:
+        """Check if authentication is enabled."""
+        return self.config.get("auth", {}).get("method", "none") != "none"
+
+    def get_auth_method(self) -> str:
+        """Get current authentication method."""
+        return self.config.get("auth", {}).get("method", "none")
+
+    def get_supported_methods(self) -> List[str]:
+        """Get list of supported authentication methods."""
+        return ["api_key", "jwt", "certificate", "basic"]
+
+
+def create_auth_manager(config: Dict[str, Any]) -> ClientAuthManager:
+    """
+    Create authentication manager from configuration.
+
+    Args:
+        config: Configuration dictionary
+
+    Returns:
+        ClientAuthManager instance
+
+    Note:
+        This manager only validates configuration structure.
+        Actual authentication is handled by mcp_proxy_adapter JsonRpcClient.
+    """
+    return ClientAuthManager(config)
+
+
+def create_auth_headers(auth_method: str, **kwargs) -> Dict[str, str]:
+    """
+    Create authentication headers for requests.
+
+    Args:
+        auth_method: Authentication method
+        **kwargs: Authentication parameters
+
+    Returns:
+        Dictionary of headers
+    """
+    # Create temporary auth manager for header generation
+    temp_config = {"auth": {"method": auth_method}}
+    auth_manager = ClientAuthManager(temp_config)
+    return auth_manager.get_auth_headers(auth_method, **kwargs)

embed_client/cli.py

@@ -0,0 +1,483 @@
+#!/usr/bin/env python3
+"""
+CLI Application for Text Vectorization
+Command-line interface for embedding text using embed-client.
+
+This CLI is fully based on the embed-client library and uses:
+- ClientFactory for client creation
+- ClientConfig for configuration management
+- response_parsers for data extraction
+- All authentication methods (API Key, JWT, Basic, Certificate)
+- Queue management commands
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import argparse
+import asyncio
+import sys
+from typing import Any, Dict  # noqa: F401
+
+from embed_client.config import ClientConfig
+from embed_client.cli_core import VectorizationCLI, create_config_from_args
+from embed_client.constants import DEFAULT_POLL_INTERVAL
+
+
+async def main():
+    """Main CLI function."""
+    parser = argparse.ArgumentParser(
+        description="CLI Application for Text Vectorization (fully based on embed-client library)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Vectorize text from command line
+  python -m embed_client vectorize "hello world" "test text"
+
+  # Vectorize text from file
+  python -m embed_client vectorize --file texts.txt
+
+  # Server-side embed_file: local JSON array file (upload + json_array), not line-based embed
+  python -m embed_client embed-file-json ./blocks.json
+
+  # Markdown → json_array (YAML front matter strip; body split on \\n\\n; per-block UTF-8 cap); then embed-file-json
+  python -m embed_client prepare-embed-file-json ./doc.md -o ./doc_embed_file.json
+  python -m embed_client embed-file-json ./doc_embed_file.json --show-progress
+
+  # Use HTTPS with API key authentication
+  python -m embed_client vectorize "hello world" --host https://localhost --port 8443 --api-key your-key
+
+  # Use mTLS with client certificates
+  python -m embed_client vectorize "hello world" --ssl --cert-file client.crt --key-file client.key
+
+  # Use JWT authentication
+  python -m embed_client vectorize "hello" --jwt-secret secret --jwt-username user --jwt-password pass
+
+  # Use config file
+  python -m embed_client --config config.json vectorize "hello"
+
+  # Queue management
+  python -m embed_client queue-list
+  python -m embed_client queue-status JOB_ID
+  python -m embed_client queue-cancel JOB_ID
+  python -m embed_client queue-wait JOB_ID
+
+  # Get help from service
+  python -m embed_client help
+
+  # Check service health
+  python -m embed_client health
+
+  # List available models
+  python -m embed_client models
+
+  # Get timing statistics (when server has timing_registration enabled)
+  python -m embed_client timing-stats
+  python -m embed_client timing-stats --file-path /path/to/timings.jsonl
+        """,
+    )
+
+    # Global options
+    parser.add_argument(
+        "--config", "-c", help="Path to configuration file (JSON or YAML)"
+    )
+    parser.add_argument(
+        "--host",
+        default="http://localhost",
+        help="Server host (default: http://localhost)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=8001, help="Server port (default: 8001)"
+    )
+    parser.add_argument(
+        "--timeout", type=float, default=30.0, help="Request timeout in seconds"
+    )
+
+    # Authentication options
+    auth_group = parser.add_argument_group("authentication")
+    auth_group.add_argument("--api-key", help="API key for authentication")
+    auth_group.add_argument(
+        "--api-key-header", help="API key header name (default: X-API-Key)"
+    )
+    auth_group.add_argument("--jwt-secret", help="JWT secret for authentication")
+    auth_group.add_argument("--jwt-username", help="JWT username")
+    auth_group.add_argument("--jwt-password", help="JWT password")
+    auth_group.add_argument("--basic-username", help="Basic auth username")
+    auth_group.add_argument("--basic-password", help="Basic auth password")
+
+    # SSL/TLS options
+    ssl_group = parser.add_argument_group("ssl/tls")
+    ssl_group.add_argument("--ssl", action="store_true", help="Enable SSL/TLS")
+    ssl_group.add_argument("--cert-file", help="Client certificate file")
+    ssl_group.add_argument("--key-file", help="Client private key file")
+    ssl_group.add_argument("--ca-cert-file", help="CA certificate file")
+    ssl_group.add_argument(
+        "--insecure",
+        "--no-check-hostname",
+        dest="insecure",
+        action="store_true",
+        help=(
+            "Disable TLS certificate/hostname verification "
+            "(library check_hostname=False) for HTTPS and WebSocket (wss) "
+            "connections. Use for self-signed certificates. "
+            "Default: strict verification."
+        ),
+    )
+
+    # Commands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Vectorize command
+    vectorize_parser = subparsers.add_parser("vectorize", help="Vectorize text")
+    vectorize_parser.add_argument("texts", nargs="*", help="Texts to vectorize")
+    vectorize_parser.add_argument(
+        "--file", "-f", help="File containing texts (one per line)"
+    )
+    vectorize_parser.add_argument(
+        "--format",
+        choices=["json", "csv", "vectors"],
+        default="json",
+        help="Output format (default: json)",
+    )
+    vectorize_parser.add_argument(
+        "--full-data",
+        action="store_true",
+        help="Show full embedding data (body, embedding, tokens, bm25_tokens)",
+    )
+    vectorize_parser.add_argument(
+        "--model",
+        help="Model name (server-side, optional)",
+    )
+    vectorize_parser.add_argument(
+        "--dimension",
+        type=int,
+        help="Expected vector dimension (server-side, optional)",
+    )
+    vectorize_parser.add_argument(
+        "--error-policy",
+        choices=["continue", "fail_fast"],
+        default="continue",
+        help="Error policy: continue (per-item errors) or fail_fast (default: continue)",
+    )
+    vectorize_parser.add_argument(
+        "--device",
+        choices=["auto", "cpu", "cuda", "cuda:0"],
+        help="Device for embedding (server-side: auto, cpu, cuda, cuda:0)",
+    )
+    vectorize_parser.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=None,
+        metavar="SECS",
+        dest="wait_timeout",
+        help="Wait up to SECS seconds for job completion (default: no wait). Use 0 for unlimited.",
+    )
+
+    embed_file_json = subparsers.add_parser(
+        "embed-file-json",
+        help="Local JSON array file → adapter upload → embed_file (json_array)",
+    )
+    embed_file_json.add_argument(
+        "json_path",
+        help="Path to UTF-8 JSON file: non-empty array of strings (json_array)",
+    )
+    embed_file_json.add_argument(
+        "--max-block-bytes",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Max UTF-8 bytes per block (default: env EMBED_CLIENT_MAX_JSON_BLOCK_BYTES or 1 MiB)",
+    )
+    embed_file_json.add_argument(
+        "--upload-filename",
+        default=None,
+        help="Optional filename hint for the transfer (default: basename of json_path)",
+    )
+    embed_file_json.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=None,
+        metavar="SECS",
+        dest="embed_file_wait_timeout",
+        help="embed_file WebSocket wait timeout in seconds (omit for server default)",
+    )
+    embed_file_json.add_argument(
+        "--download-to",
+        default=None,
+        help="Write server result JSON to this path (omit for temp file)",
+    )
+    embed_file_json.add_argument(
+        "--skip-download",
+        action="store_true",
+        help="Skip HTTP download; still send transfer_ack when applicable",
+    )
+    embed_file_json.add_argument(
+        "--model",
+        help="Model name (server-side, optional)",
+    )
+    embed_file_json.add_argument(
+        "--dimension",
+        type=int,
+        help="Expected vector dimension (server-side, optional)",
+    )
+    embed_file_json.add_argument(
+        "--device",
+        choices=["auto", "cpu", "cuda", "cuda:0"],
+        help="Device for embedding (server-side)",
+    )
+    embed_file_json.add_argument(
+        "--error-policy",
+        choices=["continue", "fail_fast"],
+        default="continue",
+        help="Error policy for embed_file (default: continue)",
+    )
+    embed_file_json.add_argument(
+        "--show-progress",
+        action="store_true",
+        help="Print WebSocket/status JSON lines to stderr while waiting for embed_file",
+    )
+
+    prepare_embed = subparsers.add_parser(
+        "prepare-embed-file-json",
+        help="Markdown/text → UTF-8 json_array (split body on blank lines \\n\\n; per-block UTF-8 cap; no network)",
+    )
+    prepare_embed.add_argument(
+        "md_path",
+        help="Path to UTF-8 Markdown or plain text (.md) file",
+    )
+    prepare_embed.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        metavar="PATH",
+        help="Output JSON path (default: <input_stem>_embed_file.json beside input)",
+    )
+    prepare_embed.add_argument(
+        "--max-block-bytes",
+        type=int,
+        default=None,
+        metavar="N",
+        dest="max_block_bytes",
+        help="Max UTF-8 bytes per paragraph block after \\n\\n split (default: env or 1 MiB; error if exceeded)",
+    )
+    prepare_embed.add_argument(
+        "--max-chunks",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Emit at most N blocks (smoke tests on huge files; omit for full document)",
+    )
+    prepare_embed.add_argument(
+        "--no-strip-front-matter",
+        action="store_true",
+        help="Do not strip YAML front matter between first pair of --- lines",
+    )
+
+    # Health command
+    subparsers.add_parser("health", help="Check service health")
+
+    # Models command
+    subparsers.add_parser("models", help="List available embedding models")
+
+    # Timing stats command
+    timing_parser = subparsers.add_parser(
+        "timing-stats",
+        help="Get timing statistics (server must have timing_registration enabled)",
+    )
+    timing_parser.add_argument(
+        "--file-path",
+        help="Path to timing file on server (optional, uses server default if omitted)",
+    )
+
+    # Help command
+    help_parser = subparsers.add_parser("help", help="Get help from service")
+    help_parser.add_argument(
+        "--command",
+        dest="help_command",
+        help="Specific command to get help for",
+    )
+
+    # Commands command
+    subparsers.add_parser("commands", help="Get available commands")
+
+    # Queue commands
+    queue_list_parser = subparsers.add_parser("queue-list", help="List queued commands")
+    queue_list_parser.add_argument("--status", help="Filter by status")
+    queue_list_parser.add_argument("--limit", type=int, help="Limit number of results")
+
+    queue_status_parser = subparsers.add_parser("queue-status", help="Get job status")
+    queue_status_parser.add_argument("job_id", help="Job identifier")
+
+    queue_cancel_parser = subparsers.add_parser("queue-cancel", help="Cancel a job")
+    queue_cancel_parser.add_argument("job_id", help="Job identifier")
+
+    queue_wait_parser = subparsers.add_parser(
+        "queue-wait", help="Wait for job completion"
+    )
+    queue_wait_parser.add_argument("job_id", help="Job identifier")
+    queue_wait_parser.add_argument(
+        "--timeout", type=float, default=60.0, help="Timeout in seconds"
+    )
+    queue_wait_parser.add_argument(
+        "--poll-interval",
+        type=float,
+        default=DEFAULT_POLL_INTERVAL,
+        help=f"Poll interval in seconds (default: {DEFAULT_POLL_INTERVAL})",
+    )
+
+    queue_logs_parser = subparsers.add_parser("queue-logs", help="Get job logs")
+    queue_logs_parser.add_argument("job_id", help="Job identifier")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    if args.command == "prepare-embed-file-json":
+        from embed_client.md_embed_file_prep import prepare_markdown_cli_main
+
+        return prepare_markdown_cli_main(args)
+
+    # Load configuration
+    config = None
+    config_dict = None
+
+    if args.config:
+        # Load from config file using ClientConfig
+        config = ClientConfig(args.config)
+        config.load_config()
+        if getattr(args, "insecure", False):
+            # --insecure overrides config file: disable TLS hostname/cert
+            # verification for HTTPS and WebSocket connections.
+            config.set("ssl.check_hostname", False)
+    else:
+        # Create config from command line arguments
+        config_dict = create_config_from_args(args)
+
+    # Create CLI instance
+    cli = VectorizationCLI()
+
+    try:
+        # Connect to service
+        if not await cli.connect(config=config, config_dict=config_dict):
+            return 1
+
+        # Execute command
+        if args.command == "vectorize":
+            texts = args.texts
+            if args.file:
+                # Use async file reading to avoid blocking the event loop
+                # Read file in executor to avoid blocking
+                loop = asyncio.get_event_loop()
+
+                def read_file_sync(file_path: str) -> list[str]:
+                    """Read file synchronously in executor."""
+                    with open(file_path, "r", encoding="utf-8") as f:
+                        return [line.strip() for line in f if line.strip()]
+
+                file_texts = await loop.run_in_executor(None, read_file_sync, args.file)
+                texts.extend(file_texts)
+
+            if not texts:
+                print("❌ No texts provided", file=sys.stderr)
+                return 1
+
+            embeddings = await cli.vectorize_texts(
+                texts,
+                args.format,
+                args.full_data,
+                timeout=getattr(args, "wait_timeout", None),
+                model=getattr(args, "model", None),
+                dimension=getattr(args, "dimension", None),
+                error_policy=getattr(args, "error_policy", "continue"),
+                device=getattr(args, "device", None),
+            )
+            if embeddings is None:
+                return 1
+
+        elif args.command == "embed-file-json":
+            ok = await cli.embed_file_local_json(
+                args.json_path,
+                max_block_bytes=getattr(args, "max_block_bytes", None),
+                upload_filename=getattr(args, "upload_filename", None),
+                wait_timeout=getattr(args, "embed_file_wait_timeout", None),
+                download_to=getattr(args, "download_to", None),
+                skip_download=bool(getattr(args, "skip_download", False)),
+                model=getattr(args, "model", None),
+                dimension=getattr(args, "dimension", None),
+                device=getattr(args, "device", None),
+                error_policy=getattr(args, "error_policy", "continue"),
+                show_progress=bool(getattr(args, "show_progress", False)),
+            )
+            if not ok:
+                return 1
+
+        elif args.command == "health":
+            if not await cli.health_check():
+                return 1
+
+        elif args.command == "help":
+            if not await cli.get_help(getattr(args, "help_command", None)):
+                return 1
+
+        elif args.command == "commands":
+            if not await cli.get_commands():
+                return 1
+
+        elif args.command == "models":
+            if not await cli.get_models():
+                return 1
+
+        elif args.command == "timing-stats":
+            if not await cli.get_timing_stats(getattr(args, "file_path", None)):
+                return 1
+
+        elif args.command == "queue-list":
+            if not await cli.queue_list(
+                getattr(args, "status", None), getattr(args, "limit", None)
+            ):
+                return 1
+
+        elif args.command == "queue-status":
+            if not await cli.queue_status(args.job_id):
+                return 1
+
+        elif args.command == "queue-cancel":
+            if not await cli.queue_cancel(args.job_id):
+                return 1
+
+        elif args.command == "queue-wait":
+            if not await cli.queue_wait(
+                args.job_id,
+                timeout=getattr(args, "timeout", 60.0),
+                poll_interval=getattr(args, "poll_interval", DEFAULT_POLL_INTERVAL),
+            ):
+                return 1
+
+        elif args.command == "queue-logs":
+            if not await cli.queue_logs(args.job_id):
+                return 1
+
+        return 0
+
+    except KeyboardInterrupt:
+        print("\n🛑 Interrupted by user", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        import traceback
+
+        traceback.print_exc()
+        return 1
+    finally:
+        await cli.disconnect()
+
+
+def cli_main():
+    """Synchronous entry point for CLI command."""
+    return asyncio.run(main())
+
+
+if __name__ == "__main__":
+    sys.exit(cli_main())