SDK Overview
============

The HCFS Python SDK provides a comprehensive, production-ready interface for interacting with the HCFS API. It offers both synchronous and asynchronous clients with built-in caching, retry mechanisms, and advanced features.

.. currentmodule:: hcfs.sdk

Features
--------

🚀 **Dual Client Support**
   - Synchronous client for traditional applications
   - Asynchronous client with full async/await support
   - WebSocket streaming capabilities

⚡ **Performance Optimized**
   - Built-in caching with configurable strategies
   - Connection pooling and keep-alive
   - Batch operations for high throughput
   - Smart retry mechanisms with backoff

🛡️ **Production Ready**
   - Comprehensive error handling
   - Rate limiting and timeout management
   - Request/response validation
   - Analytics and monitoring

🔧 **Developer Friendly**
   - Type hints throughout
   - Rich configuration options
   - Extensive examples and documentation
   - Decorator-based utilities

Installation
------------

Install from PyPI:

.. code-block:: bash

   pip install hcfs-sdk

Or install with all optional dependencies:

.. code-block:: bash

   pip install hcfs-sdk[all]

Quick Start
-----------

Synchronous Client
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from hcfs.sdk import HCFSClient, Context

   # Initialize client
   client = HCFSClient(
       base_url="https://api.hcfs.dev/v1",
       api_key="your-api-key"
   )

   # Create a context
   context = Context(
       path="/docs/quickstart",
       content="This is a quick start guide",
       summary="Getting started with HCFS"
   )

   created_context = client.create_context(context)
   print(f"Created context: {created_context.id}")

   # Search contexts
   results = client.search_contexts("quick start guide")
   for result in results:
       print(f"Found: {result.context.path} (score: {result.score:.3f})")

   # Clean up
   client.close()

Asynchronous Client
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import asyncio
   from hcfs.sdk import HCFSAsyncClient, Context

   async def main():
       async with HCFSAsyncClient(
           base_url="https://api.hcfs.dev/v1",
           api_key="your-api-key"
       ) as client:
           # Create multiple contexts concurrently
           contexts = [
               Context(path=f"/docs/guide-{i}", content=f"Guide {i}")
               for i in range(5)
           ]
           
           # Batch create
           result = await client.batch_create_contexts(contexts)
           print(f"Created {result.success_count} contexts")
           
           # Async iteration
           async for context in client.iterate_contexts():
               print(f"Context: {context.path}")
               if context.id > 100:  # Stop after some point
                   break

   asyncio.run(main())

Configuration
-------------

The SDK is highly configurable through the :class:`ClientConfig` class:

.. code-block:: python

   from hcfs.sdk import HCFSClient, ClientConfig, CacheConfig, RetryConfig

   config = ClientConfig(
       base_url="https://api.hcfs.dev/v1",
       api_key="your-api-key",
       timeout=30.0,
       
       # Cache configuration
       cache=CacheConfig(
           enabled=True,
           max_size=2000,
           ttl_seconds=3600,
           strategy="lru"
       ),
       
       # Retry configuration
       retry=RetryConfig(
           enabled=True,
           max_attempts=3,
           base_delay=1.0,
           strategy="exponential_backoff"
       ),
       
       # Connection settings
       max_connections=100,
       max_keepalive_connections=20
   )

   client = HCFSClient(config=config)

Core Classes
------------

.. autosummary::
   :toctree: generated/

   HCFSClient
   HCFSAsyncClient
   Context
   SearchResult
   ContextFilter
   PaginationOptions
   SearchOptions
   ClientConfig

Client Classes
~~~~~~~~~~~~~~

:class:`HCFSClient`
   Synchronous client for HCFS API operations. Best for traditional applications
   and when you don't need async/await support.

:class:`HCFSAsyncClient`
   Asynchronous client with full async/await support. Includes WebSocket 
   streaming capabilities and is ideal for high-performance applications.

Data Models
~~~~~~~~~~~

:class:`Context`
   Represents a context object with path, content, metadata, and other properties.
   Includes validation and conversion methods.

:class:`SearchResult`
   Contains a context and its relevance score from search operations.
   Supports sorting and comparison operations.

:class:`ContextFilter`
   Defines filtering criteria for listing contexts. Supports path prefixes,
   authors, status, date ranges, and custom filters.

Configuration Models
~~~~~~~~~~~~~~~~~~~~

:class:`ClientConfig`
   Main configuration class that combines all subsystem configurations.
   Supports environment variables and YAML configuration files.

:class:`CacheConfig`
   Cache configuration with support for multiple eviction strategies.

:class:`RetryConfig`
   Retry configuration with multiple backoff strategies and error handling.

Advanced Features
-----------------

Caching
~~~~~~~

The SDK includes intelligent caching with configurable strategies:

.. code-block:: python

   from hcfs.sdk import HCFSClient, CacheConfig
   from hcfs.sdk.decorators import cached_context

   # Configure caching
   cache_config = CacheConfig(
       enabled=True,
       strategy="lru",  # LRU, LFU, TTL, FIFO
       max_size=1000,
       ttl_seconds=3600
   )

   client = HCFSClient(
       base_url="https://api.hcfs.dev/v1",
       api_key="your-api-key",
       cache=cache_config
   )

   # Cache statistics
   stats = client.get_cache_stats()
   print(f"Cache hit rate: {stats.get('hit_rate', 0):.2%}")

Retry Logic
~~~~~~~~~~~

Automatic retry with configurable strategies:

.. code-block:: python

   from hcfs.sdk import RetryConfig, RetryStrategy

   retry_config = RetryConfig(
       enabled=True,
       max_attempts=5,
       strategy=RetryStrategy.EXPONENTIAL_BACKOFF,
       base_delay=1.0,
       max_delay=60.0,
       jitter=True,
       retry_on_status=[429, 500, 502, 503, 504]
   )

   client = HCFSClient(
       base_url="https://api.hcfs.dev/v1",
       api_key="your-api-key",
       retry=retry_config
   )

Batch Operations
~~~~~~~~~~~~~~~~

Efficient batch processing with error handling:

.. code-block:: python

   contexts = [
       Context(path=f"/batch/item-{i}", content=f"Content {i}")
       for i in range(100)
   ]

   # Batch create with automatic error handling
   result = client.batch_create_contexts(contexts)

   print(f"Success: {result.success_count}")
   print(f"Errors: {result.error_count}")
   print(f"Success rate: {result.success_rate:.2%}")

   # Handle failures
   for error in result.failed_items:
       print(f"Failed item {error['index']}: {error['error']}")

WebSocket Streaming
~~~~~~~~~~~~~~~~~~~

Real-time updates with the async client:

.. code-block:: python

   import asyncio
   from hcfs.sdk import HCFSAsyncClient

   async def handle_event(event):
       print(f"Received {event.event_type}: {event.data}")

   async def main():
       async with HCFSAsyncClient(
           base_url="https://api.hcfs.dev/v1",
           api_key="your-api-key"
       ) as client:
           # Connect to WebSocket
           await client.connect_websocket(
               path_prefix="/docs",
               event_types=["created", "updated", "deleted"]
           )
           
           # Add event listener
           client.add_event_listener(handle_event)
           
           # Keep connection alive
           await asyncio.sleep(60)

   asyncio.run(main())

Analytics and Monitoring
~~~~~~~~~~~~~~~~~~~~~~~~

Built-in analytics for monitoring SDK usage:

.. code-block:: python

   # Get usage analytics
   analytics = client.get_analytics()

   print("Operation counts:")
   for operation, count in analytics.operation_count.items():
       print(f"  {operation}: {count}")

   print(f"Cache hit rate: {analytics.get_cache_hit_rate():.2%}")
   print(f"Error rate: {analytics.get_error_rate():.2%}")

Decorators
~~~~~~~~~~

Utility decorators for common patterns:

.. code-block:: python

   from hcfs.sdk.decorators import cached_context, retry_on_failure, rate_limited

   @cached_context()
   @retry_on_failure()
   @rate_limited(requests_per_second=5.0)
   def expensive_operation(client, query):
       return client.search_contexts(query)

Error Handling
--------------

The SDK provides comprehensive error handling with specific exception types:

.. code-block:: python

   from hcfs.sdk.exceptions import (
       HCFSError, HCFSConnectionError, HCFSAuthenticationError,
       HCFSNotFoundError, HCFSValidationError, HCFSRateLimitError
   )

   try:
       context = client.get_context(999999)
   except HCFSNotFoundError:
       print("Context not found")
   except HCFSAuthenticationError:
       print("Authentication failed")
   except HCFSRateLimitError as e:
       print(f"Rate limited. Retry after {e.retry_after} seconds")
   except HCFSConnectionError:
       print("Connection failed")
   except HCFSError as e:
       print(f"HCFS error: {e.message}")

Best Practices
--------------

1. **Use Context Managers**
   Always use context managers (``with`` or ``async with``) to ensure proper cleanup:

   .. code-block:: python

      with HCFSClient(...) as client:
          # Use client
          pass

      async with HCFSAsyncClient(...) as client:
          # Use async client
          pass

2. **Configure Timeouts**
   Set appropriate timeouts for your use case:

   .. code-block:: python

      client = HCFSClient(
          base_url="...",
          api_key="...",
          timeout=30.0  # 30 second timeout
      )

3. **Enable Caching**
   Use caching for read-heavy workloads:

   .. code-block:: python

      cache_config = CacheConfig(
          enabled=True,
          max_size=2000,
          ttl_seconds=3600
      )

4. **Handle Errors Gracefully**
   Always handle potential errors:

   .. code-block:: python

      try:
          result = client.search_contexts(query)
      except HCFSError as e:
          logger.error(f"Search failed: {e}")
          result = []

5. **Use Batch Operations**
   For multiple operations, use batch methods:

   .. code-block:: python

      # Better than multiple individual creates
      result = client.batch_create_contexts(contexts)

6. **Monitor Performance**
   Regularly check analytics:

   .. code-block:: python

      analytics = client.get_analytics()
      if analytics.get_error_rate() > 0.05:  # 5% error rate
          logger.warning("High error rate detected")

Next Steps
----------

- Read the :doc:`clients` documentation for detailed client usage
- Explore :doc:`models` for data structure details  
- Check out :doc:`examples` for real-world usage patterns
- See :doc:`utilities` for helper functions and decorators