Skip to content

keeper

resource_tracker.keeper #

Functions:

Name Description
keeper_request

Fetch data from a SC Keeper URL with a custom header.
get_instance_price

Get the on-demand price for a specific instance type in a region.
get_recommended_cloud_servers

Get the cheapest cloud servers for the given resources from Spare Cores.

keeper_request #

keeper_request(path, timeout=2, endpoint='https://keeper.sparecores.net')

Fetch data from a SC Keeper URL with a custom header.

Parameters:

Name Type Description Default
path str

The path to fetch data from.

 required
timeout int

The timeout for the request.

 2
endpoint str

The endpoint to fetch data from.

 'https://keeper.sparecores.net'

Returns:

Type Description
Optional[dict]

The JSON-decoded response data, or None if an error occurs.
Source code in resource_tracker/keeper.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
def keeper_request(
    path: str, timeout: int = 2, endpoint: str = "https://keeper.sparecores.net"
) -> Optional[dict]:
    """Fetch data from a SC Keeper URL with a custom header.

    Args:
        path: The path to fetch data from.
        timeout: The timeout for the request.
        endpoint: The endpoint to fetch data from.

    Returns:
        The JSON-decoded response data, or None if an error occurs.
    """
    try:
        request = Request(urljoin(endpoint, path))
        request.add_header("X-Application-ID", "resource-tracker")
        with urlopen(request, timeout=timeout) as response:
            return loads(response.read().decode("utf-8"))
    except Exception:
        return None

get_instance_price #

get_instance_price(vendor_id, region_id, instance_type)

Get the on-demand price for a specific instance type in a region.

Parameters:

Name Type Description Default
vendor_id

The ID of the vendor (e.g. "aws", "azure", "gcp")

 required
region_id

The ID of the region (e.g. "us-east-1", "us-west-2")

 required
instance_type

The type of instance (e.g. "t3.micro", "m5.large")

 required

Returns:

Type Description
Optional[float]

The on-demand price for the instance type in the region, or None if no price is found.
Source code in resource_tracker/keeper.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def get_instance_price(vendor_id, region_id, instance_type) -> Optional[float]:
    """Get the on-demand price for a specific instance type in a region.

    Args:
        vendor_id: The ID of the vendor (e.g. "aws", "azure", "gcp")
        region_id: The ID of the region (e.g. "us-east-1", "us-west-2")
        instance_type: The type of instance (e.g. "t3.micro", "m5.large")

    Returns:
        The on-demand price for the instance type in the region, or None if no price is found.
    """
    try:
        pricing_data = keeper_request(f"/server/{vendor_id}/{instance_type}/prices")

        for item in pricing_data:
            if (
                item.get("region_id") == region_id
                and item.get("allocation") == "ondemand"
                and item.get("operating_system") == "Linux"
            ):
                return item.get("price")

        # fallback to the first on-demand price in other regions
        for item in pricing_data:
            if (
                item.get("allocation") == "ondemand"
                and item.get("operating_system") == "Linux"
            ):
                return item.get("price")

        return None
    except Exception:
        return None

get_recommended_cloud_servers(cpu, memory, gpu=None, vram=None, n=10)

Get the cheapest cloud servers for the given resources from Spare Cores.

Parameters:

Name Type Description Default
cpu int

The minimum number of vCPUs.

 required
memory int

The minimum amount of memory in MB.

 required
gpu Optional[int]

The minimum number of GPUs.

 None
vram Optional[int]

The minimum amount of VRAM in GB.

 None
n int

The number of recommended servers to return.

 10

Returns:

Type Description
List[Dict]

A list of recommended server configurations ordered by price.
References
  • https://sparecores.com/servers
Source code in resource_tracker/keeper.py 
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def get_recommended_cloud_servers(
    cpu: int,
    memory: int,
    gpu: Optional[int] = None,
    vram: Optional[int] = None,
    n: int = 10,
) -> List[Dict]:
    """Get the cheapest cloud servers for the given resources from Spare Cores.

    Args:
        cpu: The minimum number of vCPUs.
        memory: The minimum amount of memory in MB.
        gpu: The minimum number of GPUs.
        vram: The minimum amount of VRAM in GB.
        n: The number of recommended servers to return.

    Returns:
        A list of recommended server configurations ordered by price.

    References:
        - https://sparecores.com/servers
    """
    try:
        params = {
            "vcpus_min": cpu,
            "memory_min": round(memory / 1024),  # convert MiB to GiB
            "order_by": "min_price_ondemand",
            "order_dir": "asc",
            "limit": n,
        }
        if gpu and gpu > 0:
            params["gpu_min"] = gpu
        if vram and vram > 0:
            params["gpu_memory_total"] = vram
        return keeper_request(f"/servers?{urlencode(params)}")
    except Exception:
        return []