Configuration
=============

The Community DevOps Agent API supports flexible configuration through environment variables, configuration files, and programmatic setup.

Environment Variables
---------------------

The library supports configuration through environment variables for flexible deployment:

.. list-table:: Configuration Options
   :header-rows: 1
   :widths: 20 30 15 15

   * - Variable
     - Description
     - Default
     - Required
   * - ``AGENT_SPACE_ID``
     - Your DevOps Agent space UUID
     - None
     - Yes (for API calls)
   * - ``AWS_REGION``
     - AWS region for API calls
     - ``us-east-1``
     - No
   * - ``AWS_PROFILE``
     - AWS CLI profile to use
     - Default profile
     - No
   * - ``USER_ID``
     - User ID for chat messages UUID
     - ``4be32b4a-9675-4dc0-97ff-7126ad28457c``
     - No
   * - ``POLL_INTERVAL``
     - Polling interval in seconds
     - ``2``
     - No
   * - ``DEFAULT_LIMIT``
     - Default pagination limit
     - ``10``
     - No
   * - ``TIMEOUT_SECONDS``
     - Default timeout in seconds
     - ``60``
     - No
   * - ``MAX_CHECKS``
     - Maximum number of status checks
     - ``10``
     - No

Configuration Module
---------------------

All examples use a centralized configuration module (``examples/config.py``) that provides:

- **Dynamic service discovery**: Automatically detects available waiters, paginators, and operations
- **Environment variable support**: All configuration values can be overridden via environment variables
- **Validation**: Checks for required settings and service registration
- **Consistent defaults**: Sensible defaults for all configuration options

Usage:

.. code-block:: python

   from examples.config import get_config

   config = get_config()
   config.print_configuration()  # Shows current settings

   client = config.get_client()  # Creates configured boto3 client

Configuration Class
-------------------

.. autoclass:: examples.config.Config
   :members:
   :undoc-members:
   :show-inheritance:

AWS Credentials
---------------

The library uses standard AWS credential resolution:

1. **Environment variables**: ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``
2. **Shared credentials file**: ``~/.aws/credentials``
3. **AWS CLI configuration**: ``~/.aws/config``
4. **IAM roles**: For EC2 instances, Lambda functions, etc.
5. **Boto3 credential providers**: Custom credential providers

Service Registration
--------------------

The library automatically registers the ``community-devops-agent`` service with boto3 on import. You can check if registration was successful:

.. code-block:: python

   import devopsagent_api

   if devopsagent_api.is_service_registered():
       print("Service registered successfully")
   else:
       print("Service registration failed")

Advanced Configuration
----------------------

For advanced use cases, you can configure boto3 directly:

.. code-block:: python

   import boto3
   import devopsagent_api

   # Configure boto3 session
   session = boto3.Session(
       region_name='us-west-2',
       profile_name='dev'
   )

   # Create client with custom session
   client = session.client('community-devops-agent')

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

**Configuration Not Found**

If configuration values are not being picked up:

.. code-block:: bash

   # Check environment variables
   env | grep -E "(AGENT_SPACE_ID|AWS_REGION)"

   # Check AWS credentials
   aws sts get-caller-identity

**Service Registration Issues**

If the service fails to register:

.. code-block:: python

   import devopsagent_api
   import logging

   logging.basicConfig(level=logging.DEBUG)
   import devopsagent_api  # This will show debug logs

**Permission Issues**

Ensure your AWS credentials have the necessary permissions for the DevOps Agent API.