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

This guide covers installing HCFS and its SDK in various environments.

Quick Installation
------------------

The fastest way to get started is to install the HCFS SDK from PyPI:

.. code-block:: bash

   pip install hcfs-sdk

This installs the core SDK with basic dependencies.

Full Installation
-----------------

For all features including WebSocket support, monitoring, and development tools:

.. code-block:: bash

   pip install hcfs-sdk[all]

This includes optional dependencies for:

* WebSocket streaming (``websockets``)
* Advanced monitoring (``prometheus-client``, ``structlog``)
* Development tools (``pytest``, ``black``, ``mypy``)

Selective Installation
----------------------

You can install specific feature sets:

.. code-block:: bash

   # WebSocket streaming support
   pip install hcfs-sdk[websocket]

   # Monitoring and observability
   pip install hcfs-sdk[monitoring]

   # Development and testing
   pip install hcfs-sdk[dev]

   # Production deployment
   pip install hcfs-sdk[production]

Requirements
------------

System Requirements
~~~~~~~~~~~~~~~~~~~

* **Python**: 3.8 or higher
* **Operating System**: Linux, macOS, or Windows
* **Memory**: Minimum 512MB RAM, 2GB+ recommended for production
* **Storage**: 100MB for installation, varies by usage

Python Dependencies
~~~~~~~~~~~~~~~~~~~

Core dependencies (installed automatically):

* ``httpx >= 0.25.0`` - HTTP client
* ``pydantic >= 2.5.0`` - Data validation
* ``requests >= 2.31.0`` - HTTP library

Optional dependencies by feature:

**WebSocket Support**:
  * ``websockets >= 12.0``

**Monitoring**:
  * ``prometheus-client >= 0.19.0``
  * ``structlog >= 23.2.0``

**Development**:
  * ``pytest >= 7.4.0``
  * ``pytest-asyncio >= 0.21.0``
  * ``black >= 23.9.0``
  * ``mypy >= 1.6.0``

Virtual Environment Setup
--------------------------

We strongly recommend using a virtual environment:

Using venv
~~~~~~~~~~

.. code-block:: bash

   # Create virtual environment
   python -m venv hcfs-env

   # Activate (Linux/macOS)
   source hcfs-env/bin/activate

   # Activate (Windows)
   hcfs-env\\Scripts\\activate

   # Install HCFS
   pip install hcfs-sdk[all]

Using conda
~~~~~~~~~~~

.. code-block:: bash

   # Create conda environment
   conda create -n hcfs-env python=3.9

   # Activate environment
   conda activate hcfs-env

   # Install HCFS
   pip install hcfs-sdk[all]

Using Poetry
~~~~~~~~~~~~

.. code-block:: bash

   # Initialize project
   poetry init

   # Add HCFS dependency
   poetry add hcfs-sdk[all]

   # Install dependencies
   poetry install

Development Installation
------------------------

For development work on HCFS itself:

.. code-block:: bash

   # Clone the repository
   git clone https://github.com/hcfs/hcfs.git
   cd hcfs

   # Create virtual environment
   python -m venv venv
   source venv/bin/activate  # or venv\\Scripts\\activate on Windows

   # Install in development mode
   pip install -e .[dev]

   # Install pre-commit hooks
   pre-commit install

This installs HCFS in "editable" mode, so changes to the source code are immediately available.

Docker Installation
-------------------

Run HCFS API server using Docker:

.. code-block:: bash

   # Run with default settings
   docker run -p 8000:8000 hcfs/hcfs-api:latest

   # Run with custom configuration
   docker run -p 8000:8000 \
     -e HCFS_API_KEY=your-api-key \
     -e HCFS_DB_PATH=/data/hcfs.db \
     -v /host/data:/data \
     hcfs/hcfs-api:latest

Docker Compose
~~~~~~~~~~~~~~

For a complete setup with database and monitoring:

.. code-block:: yaml

   version: '3.8'
   services:
     hcfs-api:
       image: hcfs/hcfs-api:latest
       ports:
         - "8000:8000"
       environment:
         - HCFS_DB_PATH=/data/hcfs.db
         - HCFS_API_ENABLE_METRICS=true
       volumes:
         - hcfs_data:/data
       depends_on:
         - redis

     redis:
       image: redis:7-alpine
       ports:
         - "6379:6379"

   volumes:
     hcfs_data:

Verification
------------

Verify your installation:

.. code-block:: python

   import hcfs.sdk
   print(f"HCFS SDK version: {hcfs.sdk.__version__}")

   # Test basic functionality
   from hcfs.sdk import HCFSClient, Context

   # This will fail without a running server, but validates imports
   try:
       client = HCFSClient(base_url="http://localhost:8000", api_key="test")
       print("SDK imported successfully!")
   except Exception as e:
       print(f"SDK imported (server not running): {e}")

Command Line Interface
----------------------

HCFS includes a CLI for common operations:

.. code-block:: bash

   # Check version
   hcfs --version

   # Test API connection
   hcfs health --url http://localhost:8000 --api-key your-key

   # Run API server
   hcfs serve --port 8000 --workers 4

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

The SDK can be configured through:

1. **Environment Variables**:
   
   .. code-block:: bash

      export HCFS_BASE_URL=https://api.hcfs.dev/v1
      export HCFS_API_KEY=your-api-key
      export HCFS_TIMEOUT=30.0

2. **Configuration File** (``~/.hcfs/config.yaml``):

   .. code-block:: yaml

      base_url: https://api.hcfs.dev/v1
      api_key: your-api-key
      timeout: 30.0
      cache:
        enabled: true
        max_size: 1000
        ttl_seconds: 3600

3. **Programmatic Configuration**:

   .. code-block:: python

      from hcfs.sdk import HCFSClient, ClientConfig

      config = ClientConfig(
          base_url="https://api.hcfs.dev/v1",
          api_key="your-api-key",
          timeout=30.0
      )

      client = HCFSClient(config=config)

Troubleshooting
---------------

Common Issues
~~~~~~~~~~~~~

**ImportError: No module named 'hcfs'**
   Ensure you've activated your virtual environment and installed the package:
   
   .. code-block:: bash

      pip list | grep hcfs

**Connection errors**
   Verify the API server is running and accessible:
   
   .. code-block:: bash

      curl -I http://localhost:8000/health

**Permission errors on Windows**
   Run command prompt as administrator or use:
   
   .. code-block:: bash

      pip install --user hcfs-sdk

**SSL certificate errors**
   For development, you can disable SSL verification:
   
   .. code-block:: python

      import httpx
      client = HCFSClient(
          base_url="https://localhost:8000",
          api_key="test",
          verify=False
      )

Getting Help
~~~~~~~~~~~~

If you encounter issues:

1. Check this documentation
2. Search `GitHub Issues <https://github.com/hcfs/hcfs/issues>`_
3. Create a new issue with:
   
   * Python version (``python --version``)
   * HCFS version (``pip show hcfs-sdk``)
   * Operating system
   * Full error message and traceback
   * Minimal code example that reproduces the issue

Updating
--------

Keep your installation up to date:

.. code-block:: bash

   # Update to latest version
   pip install --upgrade hcfs-sdk

   # Update with all dependencies
   pip install --upgrade hcfs-sdk[all]

   # Check current version
   pip show hcfs-sdk

For development installations:

.. code-block:: bash

   # Pull latest changes
   git pull origin main

   # Update dependencies
   pip install -e .[dev] --upgrade

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

After installation:

1. Read the :doc:`quickstart` guide
2. Configure your :doc:`configuration` 
3. Explore the :doc:`examples`
4. Review the :doc:`sdk/overview` for advanced usage