BlackAnt SDK Documentation
==========================

Welcome to the BlackAnt SDK documentation. BlackAnt SDK is an enterprise-grade Python framework
for building distributed, containerized applications with comprehensive Docker integration,
secure authentication, and high-performance HTTP operations.

The SDK provides a complete toolkit for modern microservice architectures, including service
discovery, configuration management, logging, and monitoring capabilities.

.. toctree::
   :maxdepth: 2
   :caption: Core Modules:

   modules/blackant
   modules/auth
   modules/docker
   modules/http
   modules/api
   modules/services
   modules/config
   modules/utils
   modules/patterns

Key Features
============

**Authentication & Security**
   - OAuth 2.0 / OpenID Connect integration with Keycloak
   - Automatic token refresh and lifecycle management
   - Thread-safe credential storage
   - Admin API access for user management

**Docker Integration**
   - Full Docker Engine API support
   - Docker Swarm orchestration capabilities
   - Container lifecycle management
   - Image building and registry operations

**HTTP Client**
   - High-performance HTTP client with connection pooling
   - Automatic retry mechanisms with exponential backoff
   - Built-in authentication token injection
   - Comprehensive error handling and logging

**Service Management**
   - Service discovery and registration
   - Health monitoring and automatic recovery
   - Namespace-based multi-tenancy
   - Load balancing and traffic routing

**Configuration**
   - Multi-source configuration loading (YAML, environment, CLI)
   - Runtime validation and type checking
   - Environment-specific profiles
   - Secure credential management

Installation
============

Install the BlackAnt SDK using pip::

   pip install blackant-sdk

Or install from source::

   git clone https://github.com/your-org/blackant-sdk.git
   cd blackant-sdk
   pip install -e .

Quick Start Guide
=================

Authentication
--------------

Authenticate with the BlackAnt platform using your credentials::

   from blackant.auth.blackant_auth import BlackAntAuth

   # Initialize authentication
   auth = BlackAntAuth(
       user="your_username",
       password="your_password",
       login_url="https://your-blackant-instance.com/api/auth/login"
   )

   # Get access token
   token = auth.get_token()
   print(f"Authenticated successfully: {token[:30]}...")

Docker Operations
-----------------

Manage Docker containers and services::

   from blackant.docker.client import BlackAntDockerClient

   # Initialize Docker client with authentication
   docker_client = BlackAntDockerClient(
       auth=auth,
       base_url="https://your-blackant-instance.com"
   )

   # Get Docker information
   version = docker_client.get_version()
   print(f"Docker version: {version}")

   # List running containers
   containers = docker_client.get_containers()
   print(f"Running containers: {len(containers)}")

   # List available images
   images = docker_client.get_images()
   print(f"Available images: {len(images)}")

HTTP Client
-----------

Make authenticated HTTP requests::

   from blackant.http.client import HTTPClient

   # Create HTTP client with automatic authentication
   http_client = HTTPClient(
       base_url="https://your-api-endpoint.com",
       auth=auth
   )

   # Make GET request
   response = http_client.get("/api/data")
   data = response.json()

   # Make POST request
   response = http_client.post("/api/create", json={"name": "example"})

Service Management
------------------

Register and discover services::

   from blackant.services.registry import ServiceRegistry

   # Initialize service registry
   registry = ServiceRegistry(auth=auth)

   # Register a service
   service_id = registry.register_service({
       "name": "my-service",
       "version": "1.0.0",
       "health_check_url": "/health"
   })

   # Discover services
   services = registry.discover_services("my-service")

Configuration Management
------------------------

Load and manage configuration::

   from blackant.config.manager import ConfigManager

   # Initialize configuration
   config = ConfigManager()
   config.load_from_yaml("config.yaml")
   config.load_from_environment()

   # Access configuration values
   database_url = config.get("database.url")
   api_timeout = config.get("api.timeout", default=30)

Architecture Overview
=====================

The BlackAnt SDK follows a modular architecture with clear separation of concerns:

**Core Layer**
   - Authentication and authorization (``blackant.auth``)
   - Configuration management (``blackant.config``)
   - Utilities and helpers (``blackant.utils``)

**Integration Layer**
   - Docker operations (``blackant.docker``)
   - HTTP client (``blackant.http``)
   - API client (``blackant.api``)

**Service Layer**
   - Service discovery and management (``blackant.services``)
   - Design patterns and best practices (``blackant.patterns``)

Error Handling
==============

The SDK provides comprehensive error handling with specific exception types::

   from blackant.exceptions import BlackAntAuthenticationError, BlackAntDockerError

   try:
       auth.authenticate()
   except BlackAntAuthenticationError as e:
       print(f"Authentication failed: {e}")

   try:
       docker_client.get_containers()
   except BlackAntDockerError as e:
       print(f"Docker operation failed: {e}")

Logging
=======

Enable comprehensive logging for debugging and monitoring::

   from blackant.utils.logging import init_logging, get_logger

   # Initialize logging with custom settings
   init_logging(
       app_name="MyApp",
       log_level="DEBUG",
       enable_colors=True,
       enable_request_tracking=True
   )

   # Get logger for your module
   logger = get_logger("my_module")
   logger.info("Application started")

Best Practices
==============

**Security**
   - Always use environment variables for sensitive credentials
   - Enable request ID tracking for audit trails
   - Use the built-in sensitive data filtering in logs

**Performance**
   - Reuse HTTP client instances to benefit from connection pooling
   - Configure appropriate timeout values for your environment
   - Use caching for frequently accessed configuration values

**Reliability**
   - Implement proper error handling and retry logic
   - Monitor service health and implement circuit breakers
   - Use structured logging for better observability

API Reference
=============

For detailed API documentation, see the module reference pages linked in the table of contents.
Each module provides comprehensive documentation of classes, methods, and usage examples.

Contributing
============

Contributions are welcome! Please see the project repository for contribution guidelines
and development setup instructions.

Support
=======

For support and questions:

- Documentation: This site
- Issues: GitHub Issues


Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

