### Get Ironic Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Fetches a preconfigured client for the Ironic service, handling bare metal provisioning. An optional authentication session can be provided; a new one is created by default. Refer to the Ironic client API documentation for usage examples.

```python
from chi.clients import ironic

# Get an Ironic client
ironic_client = ironic()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# ironic_client = ironic(session=session)
```

--------------------------------

### Install python-chi

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/index.md

Installs the python-chi library using pip. This is the primary method for setting up the library for use.

```shell
pip install python-chi
```

--------------------------------

### Get Server by Name (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Retrieves a server object by its name. It takes the server's name as input and returns the corresponding Server object. Raises an exception if the server does not exist.

```python
from chi import server

try:
    server_obj = server.get_server(name='my_server_name')
    print(f"Server found: {server_obj}")
except Exception as e:
    print(f"Error retrieving server: {e}")
```

--------------------------------

### Get Devices

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/hardware.md

Retrieve a list of devices based on specified criteria like device type, reservation status, and authorization.

```APIDOC
## GET /chameleoncloud/python-chi/hardware/devices

### Description
Retrieve a list of devices based on the specified criteria.

### Method
GET

### Endpoint
/chameleoncloud/python-chi/hardware/devices

### Parameters
#### Query Parameters
- **device_type** (str) - Optional - The device type to filter by.
- **filter_reserved** (bool) - Optional - Flag to indicate whether to filter out reserved devices. Defaults to False.
- **filter_unauthorized** (bool) - Optional - Filter devices that the current project is not authorized to use. Defaults to True.

### Response
#### Success Response (200)
- **devices** (List[Device]) - A list of Device objects that match the specified criteria.

#### Response Example
```json
{
  "devices": [
    {
      "id": "device-123",
      "type": "gpu",
      "status": "available"
    }
  ]
}
```
```

--------------------------------

### Get Keystone Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Obtains a preconfigured client for the Keystone service, responsible for authentication. It can be initialized with an existing session or will create a new one. See the Keystone client documentation for usage details.

```python
from chi.clients import keystone

# Get a Keystone client
keystone_client = keystone()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# keystone_client = keystone(session=session)
```

--------------------------------

### Get Blazar Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Retrieves a preconfigured client for the Blazar service, which handles reservations. It requires an optional authentication session; otherwise, a new session is created. See Blazar client documentation for usage details.

```python
from chi.clients import blazar

# Get a Blazar client
blazar_client = blazar()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# blazar_client = blazar(session=session)
```

--------------------------------

### Get Glance Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Retrieves a preconfigured client for the Glance service, which manages images. It accepts an optional session object; otherwise, a new session is created. Consult the Glance client documentation for detailed usage instructions.

```python
from chi.clients import glance

# Get a Glance client
glance_client = glance()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# glance_client = glance(session=session)
```

--------------------------------

### Get Nova Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Fetches a preconfigured client for the Nova service, which manages compute resources. An optional session can be passed; otherwise, a new session is created. Consult the Nova client Python API documentation for usage.

```python
from chi.clients import nova

# Get a Nova client
ova_client = nova()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# nova_client = nova(session=session)
```

--------------------------------

### Create Network API

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Allows the creation of a new network. Supports configuration for OpenFlow controllers and virtual switches for advanced networking setups.

```APIDOC
## POST /v2.0/networks

### Description
Create a network. For an OpenFlow network, include the IP and port of an OpenFlow controller. Include a virtual switch name if you plan to add additional private VLANs to this switch.

### Method
POST

### Endpoint
/v2.0/networks

### Parameters
#### Query Parameters
- **network_name** (string) - Required - The new network name.
- **of_controller_ip** (string) - Optional - The IP of the optional OpenFlow controller. The IP must be accessible on the public Internet.
- **of_controller_port** (string) - Optional - The port of the optional OpenFlow controller.
- **vswitch_name** (string) - Optional - The virtual switch to use name.
- **provider** (string) - Optional - The provider network to use when specifying stitchable VLANs (i.e. ExoGENI). Default: ‘physnet1’

### Request Example
```json
{
  "network_name": "my_network",
  "of_controller_ip": "192.168.1.1",
  "of_controller_port": "6633",
  "vswitch_name": "vswitch0",
  "provider": "physnet1"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created network.
- **name** (string) - The name of the network.
- **status** (string) - The current status of the network.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "my_network",
  "status": "ACTIVE"
}
```
```

--------------------------------

### Get Chameleon Cloud Devices

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/hardware.md

Retrieves a list of devices from Chameleon Cloud, with options to filter by device type, reserved status, and authorization. This function is essential for understanding available hardware resources.

```python
import chi

# Get all devices
devices = chi.hardware.get_devices()

# Get only GPU devices
gpu_devices = chi.hardware.get_devices(device_type='gpu')

# Get devices, filtering out reserved and unauthorized ones
filtered_devices = chi.hardware.get_devices(filter_reserved=False, filter_unauthorized=True)
```

--------------------------------

### Container Management with Python

Source: https://context7.com/chameleoncloud/python-chi/llms.txt

Deploy and manage containers on Chameleon edge devices. This involves creating, submitting, associating floating IPs, executing commands, uploading/downloading files, retrieving logs, listing, getting, and deleting containers.

```python
from chi.container import Container, get_container, list_containers

# Create a container on an edge device
container = Container(
    name="my-ml-container",
    image_ref="docker.io/nvidia/cuda:11.0-base",
    reservation_id=lease.device_reservations[0]["id"],
    exposed_ports=["8080/tcp", "22/tcp"],
    runtime="nvidia",  # For GPU access on Jetson devices
    environment={"MODEL_PATH": "/models/resnet50"},
    device_profiles=["gpu"],
    command=["python", "server.py"],
    workdir="/app"
)

# Launch the container
container.submit(
    wait_for_active=True,
    wait_timeout=5*60,
    show="widget",
    idempotent=True
)

# Associate floating IP for external access
fip = container.associate_floating_ip()

# Execute commands inside the container
output, exit_code = container.execute("nvidia-smi")
print(output)

# Upload and download files
container.upload("/local/model.pt", "/app/models/")
container.download("/app/results/output.json", "/local/results/")

# Get container logs
logs = container.logs(stdout=True, stderr=True)
print(logs)

# List all containers
containers = list_containers()

# Get a specific container
my_container = get_container("my-ml-container")

# Delete the container
container.delete()
```

--------------------------------

### Get OpenStack Connection Context using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Obtains a connection context for the OpenStack SDK, providing proxy modules for various services. This is useful for operations spanning multiple services, though direct clients are often simpler. See OpenStack SDK connection documentation for usage.

```python
from chi.clients import connection

# Get the connection context
conn = connection()

# Access services via the connection object, e.g., conn.compute.servers()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# conn = connection(session=session)
```

--------------------------------

### Get Neutron Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Provides a preconfigured client for the Neutron service, handling networking tasks. It accepts an optional session object; a new session is created by default if none is provided. See the Neutron client reference documentation for usage.

```python
from chi.clients import neutron

# Get a Neutron client
n_client = neutron()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# n_client = neutron(session=session)
```

--------------------------------

### Get Cinder Client using Python

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/clients.md

Provides a preconfigured client for the Cinder service, managing persistent volumes. An optional session object can be passed; if not provided, a new session is initiated. Refer to the Cinder client documentation for specific usage.

```python
from chi.clients import cinder

# Get a Cinder client
cinder_client = cinder()

# Alternatively, with a specific session
# from chi.session import Session
# session = Session()
# cinder_client = cinder(session=session)
```

--------------------------------

### Create Lease Arguments (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/lease.md

Constructs the arguments required for creating a lease. This function takes a neutronclient object and various optional parameters such as name, start time, end time, duration, node count, resource properties, and network configurations. It provides default values for many parameters, simplifying lease creation.

```python
def lease_create_args(neutronclient, name=None, start='now', end=None, length=None, nodes=1, node_resource_properties=None, fips=0, networks=0, network_resource_properties=['==', '$physical_network', 'physnet1']):
    pass
```

--------------------------------

### Example Import Declaration in Docstring (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/DEVELOPMENT.rst

This snippet shows the convention for declaring functions used within an example in the docstring. It uses a specific HTML structure within a code block to list imported functions and their documentation links, ensuring clarity and maintainability.

```python
.. code-block::

   <div class="alert alert-info">

   **Functions used in this example**

   * [name_of_function](../modules/function_module.html#name_of_function)

   </div>
```

--------------------------------

### Launch Server Instance

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Launches a new server instance with specified parameters. Supports launching multiple instances and uses reservation IDs for bare metal servers.

```APIDOC
## POST /servers

### Description
Launch a new server instance.

### Method
POST

### Endpoint
/servers

### Parameters
#### Query Parameters
- **server_name** (str) - Required - A name to give the server.
- **reservation_id** (str) - Required - The ID of the Blazar reservation that will be used to select a target host node. It is required to make a reservation for bare metal server instances.
- **key_name** (str) - Optional - A key pair name to associate with the server. Defaults to the key specified by the "key_name" context variable.
- **network_id** (str) - Optional - The network ID to connect the server to.
- **network_name** (str) - Optional - The name of the network to connect the server to. If `network_id` is also set, that takes priority.
- **nics** (list[dict]) - Optional - Network interface configuration.
- **image_id** (str) - Optional - The image ID to use for the server’s disk image. If `image_name` is also set, that takes priority.
- **image_name** (str) - Optional - The name of the image to user for the server’s disk image. If `image_id` is also set, that takes priority. (Default `DEFAULT_IMAGE`.)
- **flavor_id** (str) - Optional - The flavor ID to use when launching the server. If not set, and no `flavor_name` is set, the first flavor found is used.
- **flavor_name** (str) - Optional - The name of the flavor to use when launching the server. If `flavor_id` is also set, that takes priority. If not set, and no `flavor_id` is set, the first flavor found is used.
- **count** (int) - Optional - The number of instances to launch. Defaults to 1.

### Request Body
(Not specified in the provided text, typically empty for this type of operation)

### Response
#### Success Response (200)
- **server** (object) - The created server instance. If `count` was larger than 1, then a list of all created instances will be returned instead.

#### Response Example
```json
{
  "server": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "server-name",
    "status": "BUILD"
  }
}
```

### Deprecated
Deprecated since version 1.0.
```

--------------------------------

### Launch New Server Instance (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Launches a new server instance with specified parameters such as name, reservation ID, key name, network, image, and flavor. It can create multiple instances if the 'count' parameter is greater than 1. This function is deprecated.

```python
def launch_server_instance(
    server_name: str,
    reservation_id: str = None,
    key_name: str = None,
    network_id: str = None,
    network_name: str = None,
    nics: list[dict] = None,
    image_id: str = None,
    image_name: str = None,
    flavor_id: str = None,
    flavor_name: str = None,
    count: int = 1
):
    """Launch a new server instance.

    Deprecated since version 1.0.

    :param server_name: A name to give the server.
    :param reservation_id: The ID of the Blazar reservation that will be used to select a target host node.
    :param key_name: A key pair name to associate with the server.
    :param network_id: The network ID to connect the server to.
    :param network_name: The name of the network to connect the server to.
    :param nics: List of network interface configurations.
    :param image_id: The image ID to use for the server’s disk image.
    :param image_name: The name of the image to user for the server’s disk image.
    :param flavor_id: The flavor ID to use when launching the server.
    :param flavor_name: The name of the flavor to use when launching the server.
    :param count: The number of instances to launch.
    :return: The created server instance or a list of instances if count > 1.
    :raises ValueError: if an invalid count is provided.
    """
    pass
```

--------------------------------

### chi.context.choose_site()

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/context.md

Presents a dropdown menu for selecting a Chameleon site, intended for use within Jupyter Notebooks.

```APIDOC
## choose_site(default: str | None = None)

### Description
Displays a dropdown menu to select a chameleon site. Only works if running in a Ipynb notebook environment.

### Method
GET

### Endpoint
N/A (Interactive function)

### Parameters
#### Query Parameters
- **default** (str | None) - Optional. The site to default to in the selection menu.

### Request Example
None

### Response
#### Success Response (200)
- **Returns** (None) - This function does not return a value but triggers an interactive selection.

#### Response Example
(Interactive dropdown in notebook environment)
```

--------------------------------

### Get Flavor ID

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Looks up the ID of a flavor given its name.

```APIDOC
## GET /flavors

### Description
Look up a flavor’s ID from its name.

### Method
GET

### Endpoint
/flavors

### Parameters
#### Query Parameters
- **name** (str) - Required - The name of the flavor.

### Response
#### Success Response (200)
- **id** (str) - The ID of the found flavor.

#### Response Example
```json
{
  "id": "1"
}
```

#### Raises
- **NotFound** - If the flavor could not be found.
```

--------------------------------

### Server Class

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Represents a server instance, allowing configuration of name, image, flavor, keypair, and network.

```APIDOC
## Class: Server

### Description
Represents an instance (server) in the system, allowing for its creation and configuration with various parameters.

### Parameters
- **name** (str) - The name of the server. Required.
- **reservation_id** (str | None) - The reservation ID associated with the server. Optional. Defaults to None.
- **image_name** (str) - The name of the image to use for the server. Defaults to 'CC-Ubuntu22.04'.
- **image** (Image | None) - The image ID or name to use for the server. Optional. Defaults to None.
- **flavor_name** (str) - The name of the flavor to use for the server. Defaults to 'baremetal'.
- **key_name** (str | None) - The name of the keypair to use for the server. Optional. Defaults to None.
- **keypair** (Keypair | None) - The keypair object to use for the server. Optional. Defaults to None.
- **network_name** (str) - The name of the network to use for the server. Defaults to 'sharednet1'.

### Attributes
- **name** (str) - The name of the server.
- **reservation_id** (str | None) - The reservation ID associated with the server.
- **image_name** (str) - The name of the image used for the server.
- **flavor_name** (str) - The name of the flavor used for the server.
- **keypair** (Keypair | None) - The keypair object used for the server.
- **network_name** (str) - The name of the network used for the server.
- **id** (str | None) - The ID of the server.
```

--------------------------------

### Get Flavor

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Retrieves details of a specific flavor by its ID or name.

```APIDOC
## GET /flavors/{ref}

### Description
Get a flavor by its ID or name.

### Method
GET

### Endpoint
/flavors/{ref}

### Parameters
#### Path Parameters
- **ref** (str) - Required - The ID or name of the flavor.

### Response
#### Success Response (200)
- **flavor** (object) - The flavor matching the ID or name.

#### Response Example
```json
{
  "flavor": {
    "id": "1",
    "name": "m1.small",
    "ram": 2048,
    "vcpus": 1,
    "disk": 20
  }
}
```

#### Raises
- **NotFound** - If the flavor could not be found.
```

--------------------------------

### chi.context.list_projects(show: str | None = None)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/context.md

Fetches a list of projects associated with the current user, with options to display them as a widget, plain text, or return as a list.

```APIDOC
## list_projects(show: str | None = None)

### Description
Retrieves a list of projects associated with the current user.

### Method
GET

### Endpoint
N/A (Local function)

### Parameters
#### Query Parameters
- **show** (str | None) - Optional. Determines how the project names should be displayed. Possible values: "widget", "text", or None.
  - "widget": Displays project names as a table widget.
  - "text": Prints project names as plain text.
  - None: Returns a list of project names.

### Request Example
```python
project_list = chi.context.list_projects()
chi.context.list_projects(show='text')
```

### Response
#### Success Response (200)
- **Returns** (List[str] or None) - If show is None, returns a list of project names. If show is 'text', prints to console. If show is 'widget', displays a widget.

#### Response Example (show=None)
```json
[
  "project-1",
  "project-2"
]
```

#### Error Response
- **ValueError** - If no projects are returned or an invalid value is provided for the show parameter.
```

--------------------------------

### Calculate Lease Duration (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/lease.md

Computes the start and end dates for a lease based on the desired duration specified in days and hours. The duration can be a sum of days and hours, or provided as a timedelta object. It returns a tuple containing the start and end dates.

```python
def lease_duration(days=1, hours=0, td=None):
    """Compute the start and end dates for a lease given its desired duration.

    When providing both `days` and `hours`, the duration is summed. So,
    the following would be a lease for one and a half days:

    ```python
    start_date, end_date = lease_duration(days=1, hours=12)
    ```

    * **Parameters:**
      * **days** ([*int*](https://docs.python.org/3.7/library/functions.html#int)) – The number of days the lease should be for.
      * **hours** ([*int*](https://docs.python.org/3.7/library/functions.html#int)) – The number of hours the lease should be for.
    """
    pass
```

--------------------------------

### chi.context.choose_project()

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/context.md

Allows users to select a project via a dropdown menu, primarily for use in Jupyter Notebook environments.

```APIDOC
## choose_project()

### Description
Displays a dropdown menu to select a project. Only works if running in a Ipynb notebook environment.

### Method
GET

### Endpoint
N/A (Interactive function)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Returns** (None) - This function does not return a value but triggers an interactive selection.

#### Response Example
(Interactive dropdown in notebook environment)
```

--------------------------------

### Get Port

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Retrieves a port by its name or ID.

```APIDOC
## GET /v2.0/ports?name={name} or GET /v2.0/ports/{port_id}

### Description
Gets a port by its name or ID.

### Method
GET

### Endpoint
/v2.0/ports
(Use query parameter `name` for name lookup)
/v2.0/ports/{port_id}
(Use path parameter `port_id` for ID lookup)

### Parameters
#### Query Parameters (for name lookup)
- **name** (string) - Required - The name of the port.

#### Path Parameters (for ID lookup)
- **port_id** (string) - Required - The ID of the port.

### Response
#### Success Response (200 OK)
- **ports** (array) - A list containing the port representation.
  - **id** (string) - The port ID.
  - **name** (string) - The port name.
  - **network_id** (string) - The ID of the network the port belongs to.
  - **device_id** (string) - The ID of the device attached to the port.
  - **fixed_ips** (array) - A list of fixed IPs assigned to the port.

#### Response Example
```json
{
  "ports": [
    {
      "id": "port_id_789",
      "name": "my_port",
      "network_id": "network_id_123",
      "device_id": "device_id_xyz",
      "fixed_ips": [
        {
          "ip_address": "192.168.1.10",
          "subnet_id": "subnet_id_abc"
        }
      ]
    }
  ]
}
```

#### Error Response (404 Not Found)
- **NeutronError** (object) - Details about the error.
  - **message** (string) - Error message indicating the port was not found.
  - **code** (integer) - HTTP status code (e.g., 404).

#### Error Response (Multiple Matches)
- **RuntimeError** - If multiple ports were returned for the search term.
```

--------------------------------

### Snapshot Container (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/container.md

Creates a snapshot of a running container's file system and stores it as a new Image in Glance. Requires container reference, repository name, and an optional tag.

```python
def snapshot_container(container_ref: str, repository: str, tag: str = 'latest') -> str:
    """Create a snapshot of a running container.

    This will store the container’s file system in Glance as a new Image.
    You can then specify the Image ID in container create requests.

    Args:
        container_ref: The name or ID of the container.
        repository: The name to give the snapshot.
        tag: An optional version tag to give the snapshot. Defaults to “latest”.

    Returns:
        The ID of the created image snapshot.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Get Network

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Retrieves a network by its name or ID.

```APIDOC
## GET /v2.0/networks?name={name} or GET /v2.0/networks/{network_id}

### Description
Gets a network by its name or ID.

### Method
GET

### Endpoint
/v2.0/networks
(Use query parameter `name` for name lookup)
/v2.0/networks/{network_id}
(Use path parameter `network_id` for ID lookup)

### Parameters
#### Query Parameters (for name lookup)
- **name** (string) - Required - The name of the network.

#### Path Parameters (for ID lookup)
- **network_id** (string) - Required - The ID of the network.

### Response
#### Success Response (200 OK)
- **networks** (array) - A list containing the network representation.
  - **id** (string) - The network ID.
  - **name** (string) - The network name.
  - **tenant_id** (string) - The ID of the project (tenant) owning the network.
  - **subnets** (array) - A list of subnet IDs associated with the network.

#### Response Example
```json
{
  "networks": [
    {
      "id": "network_id_123",
      "name": "my_network",
      "tenant_id": "project_id_123",
      "subnets": ["subnet_id_abc"]
    }
  ]
}
```

#### Error Response (404 Not Found)
- **NeutronError** (object) - Details about the error.
  - **message** (string) - Error message indicating the network was not found.
  - **code** (integer) - HTTP status code (e.g., 404).

#### Error Response (Multiple Matches)
- **RuntimeError** - If multiple networks are returned for the search term.
```

--------------------------------

### Create Container API

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/container.md

Creates a new container with specified parameters including name, image, exposed ports, and startup behavior.

```APIDOC
## POST /container/create

### Description
Creates a new container.

### Method
POST

### Endpoint
/container/create

### Parameters
#### Request Body
- **name** (str) - Required - The name of the container.
- **image** (str | None) - Optional - The image to use for the container.
- **exposed_ports** (list[str] | None) - Optional - A list of ports to expose from the container.
- **reservation_id** (str | None) - Optional - An ID for reserving resources for the container.
- **start** (bool) - Optional - Whether to start the container after creation. Defaults to True.
- **start_timeout** (int | None) - Optional - The timeout in seconds for starting the container.
- **platform_version** (int) - Optional - The platform version to use. Defaults to 2.
- ****kwargs** - Additional keyword arguments for container creation.
```

--------------------------------

### Get Node Types

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/hardware.md

Retrieve a list of unique node types available in the system.

```APIDOC
## GET /chameleoncloud/python-chi/hardware/node_types

### Description
Retrieve a list of unique node types.

### Method
GET

### Endpoint
/chameleoncloud/python-chi/hardware/node_types

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **node_types** (List[str]) - A list of unique node types.

#### Response Example
```json
{
  "node_types": [
    "compute_thin",
    "gpu_k80"
  ]
}
```
```

--------------------------------

### Get Network ID

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Looks up a network's ID from its name.

```APIDOC
## GET /v2.0/networks?name={name}

### Description
Looks up a network’s ID from its name.

### Method
GET

### Endpoint
/v2.0/networks

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the network.

### Response
#### Success Response (200 OK)
- **networks** (array) - A list containing the network representation.
  - **id** (string) - The network ID.

#### Response Example
```json
{
  "networks": [
    {
      "id": "network_id_123",
      "name": "my_network"
    }
  ]
}
```

#### Error Response (404 Not Found)
- **RuntimeError** - If the network could not be found.

#### Error Response (Multiple Matches)
- **RuntimeError** - If multiple networks were returned for the search term.
```

--------------------------------

### List Servers (Python)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Returns a list of all servers currently in the project. This function can accept keyword arguments for filtering. It returns a list of Server objects.

```python
from chi import server

servers = server.list_servers()
for s in servers:
    print(f"Server Name: {s.name}, ID: {s.id}, Status: {s.status}")
```

--------------------------------

### Get Floating IP

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Retrieves the representation of a floating IP address.

```APIDOC
## GET /v2.0/floatingips?ipaddress={ip_address}

### Description
Gets the floating IP representation for a given IP address.

### Method
GET

### Endpoint
/v2.0/floatingips

### Parameters
#### Query Parameters
- **ipaddress** (string) - Required - The IP address of the floating IP.

### Response
#### Success Response (200 OK)
- **floatingips** (array) - A list containing the floating IP representation.
  - **id** (string) - The floating IP ID.
  - **ip_address** (string) - The floating IP address.
  - **fixed_ip_address** (string) - The fixed IP address associated with the floating IP.
  - **port_id** (string) - The ID of the port the floating IP is associated with.
  - **router_id** (string) - The ID of the router the floating IP is associated with.
  - **tenant_id** (string) - The ID of the project (tenant) owning the floating IP.

#### Response Example
```json
{
  "floatingips": [
    {
      "id": "fip_id_xyz",
      "ip_address": "1.2.3.4",
      "fixed_ip_address": "192.168.0.10",
      "port_id": "port_id_789",
      "router_id": "router_id_abc",
      "tenant_id": "project_id_123"
    }
  ]
}
```

#### Error Response (404 Not Found)
- **NeutronError** (object) - Details about the error.
  - **message** (string) - Error message indicating the floating IP was not found.
  - **code** (integer) - HTTP status code (e.g., 404).
```

--------------------------------

### Get Keypair

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/server.md

Retrieves a keypair by its name. If no name is provided, it defaults to the JupyterHub keypair for the current user.

```APIDOC
## GET /os-keypairs

### Description
Retrieves a keypair by name.

### Method
GET

### Endpoint
/os-keypairs

### Parameters
#### Query Parameters
- **name** (str) - Optional - The name of the keypair to retrieve. If not provided, it will use the JupyterHub keypair for the current user.

### Response
#### Success Response (200)
- **keypair** (object) - An instance of the Keypair class representing the retrieved keypair.

#### Response Example
```json
{
  "keypair": {
    "name": "my-keypair",
    "public_key": "ssh-rsa AAAAB3NzaC1..."
  }
}
```
```

--------------------------------

### Manage Flavors with Chameleon Cloud Python SDK

Source: https://context7.com/chameleoncloud/python-chi/llms.txt

This code snippet shows how to query and retrieve information about available instance flavors for launching servers on Chameleon Cloud using the Python SDK. It covers listing all flavors, filtering by reservable or GPU availability, and fetching details of a specific flavor.

```python
from chi.server import list_flavors, get_flavor

# List all flavors
all_flavors = list_flavors()

# List reservable flavors (can be reserved via Blazar)
reservable = list_flavors(reservable=True)

# List GPU flavors
gpu_flavors = list_flavors(gpu=True)

# List flavors for a specific reservation
reserved_flavors = list_flavors(reservation_id="abc-123")

# Get a specific flavor
flavor = get_flavor("baremetal")
print(f"Name: {flavor.name}")
print(f"RAM: {flavor.ram} MB")
print(f"VCPUs: {flavor.vcpus}")
print(f"Disk: {flavor.disk} GB")
```

--------------------------------

### Get Python-CHI Session

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/context.md

Retrieves a Keystone Session object suitable for authenticating a client. This session object is of type keystoneauth1.session.Session.

```python
import chi

session = chi.context.session()
```

--------------------------------

### Hardware Discovery API

Source: https://context7.com/chameleoncloud/python-chi/llms.txt

Query and filter available hardware resources across Chameleon sites.

```APIDOC
## Hardware Discovery

### Description
Query and filter available hardware resources across Chameleon sites.

### Method
GET

### Endpoint
`/nodes`, `/node_types`, `/devices`, `/device_types`

### Parameters
#### Query Parameters (for `get_nodes`)
- **gpu** (boolean) - Optional - Filter for nodes with GPUs.
- **min_number_cpu** (integer) - Optional - Minimum number of CPUs.
- **node_type** (string) - Optional - Filter by specific node type (e.g., 'gpu_rtx_6000').
- **filter_reserved** (boolean) - Optional - If true, only show unreserved nodes.
- **all_sites** (boolean) - Optional - Search across all sites if true.

#### Query Parameters (for `get_devices`)
- **device_type** (string) - Optional - Filter by specific device type (e.g., 'raspberrypi4-64').
- **filter_reserved** (boolean) - Optional - If true, only show unreserved devices.
- **filter_unauthorized** (boolean) - Optional - If true, filter out unauthorized devices.

### Request Example (Get Nodes with Filters)
```python
gpu_nodes = hardware.get_nodes(
    gpu=True,
    min_number_cpu=32,
    node_type="gpu_rtx_6000",
    filter_reserved=True,
    all_sites=True
)
```

### Response
#### Success Response (200)
- **nodes** (list) - A list of node objects matching the criteria.
- **node_types** (list) - A list of available node type strings.
- **devices** (list) - A list of device objects matching the criteria.
- **device_types** (list) - A list of available device type strings.

#### Response Example (Get Nodes)
```json
[
  {
    "id": "node-id-123",
    "name": "gpu-node-01",
    "status": "available",
    "gpu_count": 1
  }
]
```

#### Response Example (Get Node Types)
```json
["compute_skylake", "gpu_rtx_6000", ...]
```

---

## Node Operations (Methods on Node Object)

### Description
Perform operations on individual node objects, such as checking availability.

### Methods
- **next_free_timeslot(minimum_hours)**: Checks for the next available time slot for the node.

### Parameters
- **next_free_timeslot()**: `minimum_hours` (integer) - The minimum duration required in hours.

### Request Example (Check Next Timeslot)
```python
node = gpu_nodes[0]
start_time, end_time = node.next_free_timeslot(minimum_hours=4)
```

### Response
- **start_time** (datetime string) - The start time of the next available slot.
- **end_time** (datetime string) - The end time of the next available slot.

---

## Hardware Reservation

### Description
Use hardware objects directly in lease reservations.

### Methods
- **Lease.add_node_reservation(nodes)**: Adds a reservation for specified nodes.
- **Lease.submit()**: Submits the lease reservation.

### Parameters
- **add_node_reservation()**: `nodes` (list of node objects) - The nodes to reserve.

### Request Example (Hardware Reservation)
```python
lease = Lease(name="gpu-lease", duration=timedelta(hours=8))
lease.add_node_reservation(nodes=gpu_nodes[:2])
lease.submit()
```

### Response
Indicates the success or failure of the lease submission.
```

--------------------------------

### chi.context.list_sites(show: str | None = None)

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/context.md

Retrieves a list of Chameleon sites, with options to display them as a widget, plain text, or return as a dictionary.

```APIDOC
## list_sites(show: str | None = None)

### Description
Retrieves a list of Chameleon sites.

### Method
GET

### Endpoint
N/A (Local function)

### Parameters
#### Query Parameters
- **show** (str | None) - Optional. Determines how the site names should be displayed. Possible values: "widget", "text", or None.
  - "widget": Displays site names as a table widget.
  - "text": Prints site names as plain text.
  - None: Returns a dictionary of site names to their properties.

### Request Example
```python
site_dict = chi.context.list_sites()
chi.context.list_sites(show='widget')
```

### Response
#### Success Response (200)
- **Returns** (dict or None) - If show is None, returns a dictionary of site names to properties. If show is 'text', prints to console. If show is 'widget', displays a widget.

#### Response Example (show=None)
```json
{
  "site1": {
    "region": "us-east-1"
  },
  "site2": {
    "region": "eu-west-1"
  }
}
```

#### Error Response
- **ValueError** - If no sites are returned or if an invalid value is provided for the show parameter.
```

--------------------------------

### Get or Create Floating IP

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Retrieves the first unallocated floating IP or allocates one to the project if none are available.

```APIDOC
## GET /v2.0/floatingips?status=DOWN (and potentially POST to allocate)

### Description
Gets the first unallocated floating IP or allocates one to the project. This is a convenience function that combines the logic of finding and allocating.

### Method
GET / POST (internal implementation)

### Endpoint
Internal endpoint logic, typically interacts with /v2.0/floatingips.

### Response
#### Success Response (200 OK)
- **floating_ip_info** (dict) - The floating IP representation.
  - **ip_address** (string) - The floating IP address.
  - **allocated** (boolean) - True if the IP was dynamically allocated, False otherwise.

#### Response Example
```json
{
  "ip_address": "1.2.3.4",
  "allocated": false
}
```

#### Error Response (Conflict)
- **Conflict** - Raised if there are no free floating IPs and there are no more available to allocate.
```

--------------------------------

### Get Image Name by ID

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/image.md

Looks up an image's name using its ID. Raises a CHIValueError if the image is not found.

```APIDOC
## GET /chi.image.get_image_name

### Description
Look up an image’s name from its ID. Raises a CHIValueError if the image is not found.

### Method
GET

### Endpoint
/chi.image.get_image_name

### Parameters
#### Query Parameters
- **id** (str) - Required - The ID of the image.

### Response
#### Success Response (200)
- **name** (str) - The name of the found image.

#### Error Response
- **CHIValueError** - If the image could not be found.
```

--------------------------------

### Hardware Discovery with Python

Source: https://context7.com/chameleoncloud/python-chi/llms.txt

Query and filter available hardware resources across Chameleon sites. This includes fetching nodes with various filters, displaying nodes interactively, retrieving node types, checking availability, and discovering edge/IoT devices.

```python
from chi import hardware
from datetime import timedelta

# Get all nodes at the current site
nodes = hardware.get_nodes()

# Get nodes with filters
gpu_nodes = hardware.get_nodes(
    gpu=True,
    min_number_cpu=32,
    node_type="gpu_rtx_6000",
    filter_reserved=True,  # Only show unreserved nodes
    all_sites=True  # Search across all sites
)

# Display interactive node table (Jupyter)
hardware.show_nodes(gpu_nodes)

# Get available node types
node_types = hardware.get_node_types()
# Returns: ['compute_skylake', 'compute_cascadelake', 'gpu_rtx_6000', ...]

# Check next available timeslot for a specific node
node = gpu_nodes[0]
start_time, end_time = node.next_free_timeslot(minimum_hours=4)
print(f"Available from {start_time} to {end_time}")

# Get edge/IoT devices
devices = hardware.get_devices(
    device_type="raspberrypi4-64",
    filter_reserved=True,
    filter_unauthorized=True
)

# Get device types
device_types = hardware.get_device_types()
# Returns: ['raspberrypi4-64', 'jetson-nano', 'jetson-tx2', ...]

# Use hardware objects directly in lease reservations
lease = Lease(name="gpu-lease", duration=timedelta(hours=8))
lease.add_node_reservation(nodes=gpu_nodes[:2])  # Reserve specific nodes
lease.submit()
```

--------------------------------

### Get Free Floating IP

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/network.md

Retrieves the first available unallocated floating IP. Optionally allocates a new one if none are free.

```APIDOC
## GET /v2.0/floatingips?status=DOWN

### Description
Gets the first unallocated floating IP available to your project. If `allocate` is true (default), a new floating IP will be allocated if none are currently free.

### Method
GET

### Endpoint
/v2.0/floatingips

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status, typically 'DOWN' to find unallocated IPs.
- **allocate** (boolean) - Optional - Whether to allocate a new floating IP if none are free. Defaults to true.

### Response
#### Success Response (200 OK)
- **floatingips** (array) - A list containing the free floating IP representation.
  - **id** (string) - The floating IP ID.
  - **ip_address** (string) - The floating IP address.
  - **tenant_id** (string) - The ID of the project (tenant) owning the floating IP.

#### Response Example
```json
{
  "floatingips": [
    {
      "id": "fip_id_xyz",
      "ip_address": "1.2.3.4",
      "tenant_id": "project_id_123"
    }
  ]
}
```

#### Error Response (404 Not Found)
- **NeutronError** (object) - Details about the error.
  - **message** (string) - Error message indicating no free floating IPs could be found or allocated.
  - **code** (integer) - HTTP status code (e.g., 404).

#### Error Response (Conflict)
- **Conflict** - Raised if there are no free floating IPs and no more are available to allocate.
```

--------------------------------

### chi.context.params()

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/context.md

Lists all parameters currently set within the context.

```APIDOC
## params()

### Description
List all parameters currently set on the context.

### Method
GET

### Endpoint
N/A (Local function)

### Parameters
None

### Request Example
```python
context_params = chi.context.params()
```

### Response
#### Success Response (200)
- **Returns** (List[str]) - A list of parameter names currently set in the context.

#### Response Example
```json
[
  "project_id",
  "user_id",
  "site"
]
```
```

--------------------------------

### Get Nodes

Source: https://github.com/chameleoncloud/python-chi/blob/master/docs/modules/hardware.md

Retrieve a list of nodes based on various filtering criteria including site, reservation status, GPU availability, CPU count, and node type.

```APIDOC
## GET /chameleoncloud/python-chi/hardware/nodes

### Description
Retrieve a list of nodes based on the specified criteria.

### Method
GET

### Endpoint
/chameleoncloud/python-chi/hardware/nodes

### Parameters
#### Query Parameters
- **all_sites** (bool) - Optional - Flag to indicate whether to retrieve nodes from all sites. Defaults to False.
- **filter_reserved** (bool) - Optional - Flag to indicate whether to filter out reserved nodes. Defaults to False.
- **gpu** (bool) - Optional - Flag to indicate whether to filter nodes based on GPU availability. Defaults to None.
- **min_number_cpu** (int) - Optional - Minimum number of CPU logical cores per node. Defaults to None.
- **node_type** (str) - Optional - The node type to filter by.

### Response
#### Success Response (200)
- **nodes** (List[Node]) - A list of Node objects that match the specified criteria.

#### Response Example
```json
{
  "nodes": [
    {
      "id": "node-abc",
      "type": "compute_thin",
      "cpu_cores": 16,
      "gpu_available": false
    }
  ]
}
```
```