{"id":22201724,"url":"https://github.com/the-swarm-corporation/clusterops","last_synced_at":"2025-08-22T22:22:22.122Z","repository":{"id":257815830,"uuid":"869869986","full_name":"The-Swarm-Corporation/ClusterOps","owner":"The-Swarm-Corporation","description":"ClusterOps is an enterprise-grade Python library developed and maintained by the Swarms Team to help you manage and execute agents on specific CPUs and GPUs across clusters. This tool enables advanced CPU and GPU selection, dynamic task allocation, and resource monitoring, making it ideal for high-performance distributed computing environments.","archived":false,"fork":false,"pushed_at":"2024-11-14T20:38:21.000Z","size":2310,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-14T21:29:45.613Z","etag":null,"topics":["a100","agents","ai","clusterops","cpus","gpus","gputils","llm-agents","ml","multi-agent","multi-agent-collaboration","rayserve","swarms","transformers"],"latest_commit_sha":null,"homepage":"https://discord.com/servers/agora-999382051935506503","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/The-Swarm-Corporation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["kyegomez"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2024-10-09T03:21:36.000Z","updated_at":"2024-11-14T20:38:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"cc2bb80b-42fa-4666-b9b3-885e66596ac1","html_url":"https://github.com/The-Swarm-Corporation/ClusterOps","commit_stats":null,"previous_names":["the-swarm-corporation/clusterops"],"tags_count":0,"template":false,"template_full_name":"kyegomez/Python-Package-Template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Swarm-Corporation%2FClusterOps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Swarm-Corporation%2FClusterOps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Swarm-Corporation%2FClusterOps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Swarm-Corporation%2FClusterOps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/The-Swarm-Corporation","download_url":"https://codeload.github.com/The-Swarm-Corporation/ClusterOps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227760018,"owners_count":17815626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a100","agents","ai","clusterops","cpus","gpus","gputils","llm-agents","ml","multi-agent","multi-agent-collaboration","rayserve","swarms","transformers"],"created_at":"2024-12-02T16:10:03.801Z","updated_at":"2025-07-27T04:30:55.641Z","avatar_url":"https://github.com/The-Swarm-Corporation.png","language":"Python","funding_links":["https://github.com/sponsors/kyegomez"],"categories":[],"sub_categories":[],"readme":"# ClusterOps\n\n[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white)](https://discord.gg/agora-999382051935506503) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge\u0026logo=youtube\u0026logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/kyegomezb)\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python Version](https://img.shields.io/badge/python-3.8%2B-brightgreen.svg)](https://python.org)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/swarms-team/clusterops/test.yml?branch=master)](https://github.com/swarms-team/clusterops/actions)\n[![Coverage Status](https://img.shields.io/codecov/c/github/swarms-team/clusterops)](https://codecov.io/gh/swarms-team/clusterops)\n\n\n**ClusterOps** is an enterprise-grade Python library developed and maintained by the **Swarms Team** to help you manage and execute agents on specific **CPUs** and **GPUs** across clusters. This tool enables advanced CPU and GPU selection, dynamic task allocation, and resource monitoring, making it ideal for high-performance distributed computing environments.\n\n\n\n---\n\n## Features\n\n- **CPU Execution**: Dynamically assign tasks to specific CPU cores.\n- **GPU Execution**: Execute tasks on specific GPUs or dynamically select the best available GPU based on memory usage.\n- **Fault Tolerance**: Built-in retry logic with exponential backoff for handling transient errors.\n- **Resource Monitoring**: Real-time CPU and GPU resource monitoring (e.g., free memory on GPUs).\n- **Logging**: Advanced logging configuration with customizable log levels (DEBUG, INFO, ERROR).\n- **Scalability**: Supports multi-GPU task execution with Ray for distributed computation.\n\n---\n\n\n## Installation\n\n\n```bash\npip3 install -U clusterops\n```\n\n---\n\n## Quick Start\n\nThe following example demonstrates how to use ClusterOps to run tasks on specific CPUs and GPUs.\n\n```python\nfrom clusterops import (\n   list_available_cpus,\n   execute_with_cpu_cores,\n   list_available_gpus,\n   execute_on_gpu,\n   execute_on_multiple_gpus,\n)\n\n# Example function to run\ndef sample_task(n: int) -\u003e int:\n    return n * n\n\n\n# List CPUs and execute on CPU 0\ncpus = list_available_cpus()\nexecute_on_cpu(0, sample_task, 10)\n\n# List CPUs and execute using 4 CPU cores\nexecute_with_cpu_cores(4, sample_task, 10)\n\n# List GPUs and execute on GPU 0\ngpus = list_available_gpus()\nexecute_on_gpu(0, sample_task, 10)\n\n# Execute across multiple GPUs\nexecute_on_multiple_gpus([0, 1], sample_task, 10)\n\n```\n\u003c!-- \n## GPU Scheduler\n\nThe GPU Scheduler is a Ray Serve deployment that manages job execution with fault tolerance, job retries, and scaling. It uses the GPUJobExecutor to execute tasks on available GPUs.\n\nSee the [GPU Scheduler](/clusterops/gpu_scheduler.py) for more details.\n\n```python\nfrom clusterops import gpu_scheduler\n\n\nasync def sample_task(n: int) -\u003e int:\n    return n * n\n\n\nprint(gpu_scheduler(sample_task, priority=1, n=10))\n\n``` --\u003e\n\n\n### Executing callables in parallel\n\nThis section demonstrates how to execute multiple callables in parallel using the `execute_parallel_optimized` function from the `clusterops.execute_callables_parallel` module.\n\n```python\nfrom clusterops.execute_callables_parallel import (\n   execute_parallel_optimized,\n)\n\n\ndef add(a, b):\n    return a + b\n\n\ndef multiply(a, b):\n    return a * b\n\n\ndef power(a, b):\n    return a**b\n\n\nif __name__ == \"__main__\":\n    # List of callables with their respective arguments\n    callables_with_args = [\n        (add, (2, 3)),\n        (multiply, (5, 4)),\n        (power, (2, 10)),\n    ]\n\n    # Execute the callables in parallel\n    results = execute_parallel_optimized(callables_with_args)\n\n    # Print the results\n    print(\"Results:\", results)\n\n```\n\n\n---\n\n## Configuration\n\nClusterOps provides configuration through environment variables, making it adaptable for different environments (development, staging, production).\n\n### Environment Variables\n\n- **`LOG_LEVEL`**: Configures logging verbosity. Options: `DEBUG`, `INFO`, `ERROR`. Default is `INFO`.\n- **`RETRY_COUNT`**: Number of times to retry a task in case of failure. Default is 3.\n- **`RETRY_DELAY`**: Initial delay in seconds before retrying. Default is 1 second.\n\nSet these variables in your environment:\n\n```bash\nexport LOG_LEVEL=DEBUG\nexport RETRY_COUNT=5\nexport RETRY_DELAY=2.0\n```\n\n-----\n\n## Docs\n\n---\n\n### `list_available_cpus() -\u003e List[int]`\n\n**Description:**  \nLists all available CPU cores on the system.\n\n**Returns:**  \n- `List[int]`: A list of available CPU core indices.\n\n**Raises:**  \n- `RuntimeError`: If no CPUs are found.\n\n**Example Usage:**\n\n```python\ncpus = list_available_cpus()\nprint(f\"Available CPUs: {cpus}\")\n```\n\n---\n\n### `select_best_gpu() -\u003e Optional[int]`\n\n**Description:**  \nSelects the GPU with the most free memory.\n\n**Returns:**  \n- `Optional[int]`: The GPU ID of the best available GPU, or `None` if no GPUs are available.\n\n**Example Usage:**\n\n```python\nbest_gpu = select_best_gpu()\nprint(f\"Best GPU ID: {best_gpu}\")\n```\n\n---\n\n### `execute_on_cpu(cpu_id: int, func: Callable, *args: Any, **kwargs: Any) -\u003e Any`\n\n**Description:**  \nExecutes a function on a specific CPU core.\n\n**Arguments:**  \n- `cpu_id (int)`: The CPU core to run the function on.\n- `func (Callable)`: The function to be executed.\n- `*args (Any)`: Positional arguments for the function.\n- `**kwargs (Any)`: Keyword arguments for the function.\n\n**Returns:**  \n- `Any`: The result of the function execution.\n\n**Raises:**  \n- `ValueError`: If the CPU core specified is invalid.\n- `RuntimeError`: If there is an error executing the function on the CPU.\n\n**Example Usage:**\n\n```python\nresult = execute_on_cpu(0, sample_task, 10)\nprint(f\"Result: {result}\")\n```\n\n---\n\n### `retry_with_backoff(func: Callable, retries: int = RETRY_COUNT, delay: float = RETRY_DELAY, *args: Any, **kwargs: Any) -\u003e Any`\n\n**Description:**  \nRetries a function with exponential backoff in case of failure.\n\n**Arguments:**  \n- `func (Callable)`: The function to execute with retries.\n- `retries (int)`: Number of retries. Defaults to `RETRY_COUNT`.\n- `delay (float)`: Delay between retries in seconds. Defaults to `RETRY_DELAY`.\n- `*args (Any)`: Positional arguments for the function.\n- `**kwargs (Any)`: Keyword arguments for the function.\n\n**Returns:**  \n- `Any`: The result of the function execution.\n\n**Raises:**  \n- `Exception`: After all retries fail.\n\n**Example Usage:**\n\n```python\nresult = retry_with_backoff(sample_task, retries=5, delay=2, n=10)\nprint(f\"Result after retries: {result}\")\n```\n\n---\n\n### `execute_with_cpu_cores(core_count: int, func: Callable, *args: Any, **kwargs: Any) -\u003e Any`\n\n**Description:**  \nExecutes a function using a specified number of CPU cores.\n\n**Arguments:**  \n- `core_count (int)`: The number of CPU cores to run the function on.\n- `func (Callable)`: The function to be executed.\n- `*args (Any)`: Positional arguments for the function.\n- `**kwargs (Any)`: Keyword arguments for the function.\n\n**Returns:**  \n- `Any`: The result of the function execution.\n\n**Raises:**  \n- `ValueError`: If the number of CPU cores specified is invalid or exceeds available cores.\n- `RuntimeError`: If there is an error executing the function on the specified CPU cores.\n\n**Example Usage:**\n\n```python\nresult = execute_with_cpu_cores(4, sample_task, 10)\nprint(f\"Result: {result}\")\n```\n\n---\n\n### `list_available_gpus() -\u003e List[str]`\n\n**Description:**  \nLists all available GPUs on the system.\n\n**Returns:**  \n- `List[str]`: A list of available GPU names.\n\n**Raises:**  \n- `RuntimeError`: If no GPUs are found.\n\n**Example Usage:**\n\n```python\ngpus = list_available_gpus()\nprint(f\"Available GPUs: {gpus}\")\n```\n\n---\n\n### `execute_on_gpu(gpu_id: int, func: Callable, *args: Any, **kwargs: Any) -\u003e Any`\n\n**Description:**  \nExecutes a function on a specific GPU using Ray.\n\n**Arguments:**  \n- `gpu_id (int)`: The GPU to run the function on.\n- `func (Callable)`: The function to be executed.\n- `*args (Any)`: Positional arguments for the function.\n- `**kwargs (Any)`: Keyword arguments for the function.\n\n**Returns:**  \n- `Any`: The result of the function execution.\n\n**Raises:**  \n- `ValueError`: If the GPU index is invalid.\n- `RuntimeError`: If there is an error executing the function on the GPU.\n\n**Example Usage:**\n\n```python\nresult = execute_on_gpu(0, sample_task, 10)\nprint(f\"Result: {result}\")\n```\n\n---\n\n### `execute_on_multiple_gpus(gpu_ids: List[int], func: Callable, *args: Any, **kwargs: Any) -\u003e List[Any]`\n\n**Description:**  \nExecutes a function across multiple GPUs using Ray.\n\n**Arguments:**  \n- `gpu_ids (List[int])`: The list of GPU IDs to run the function on.\n- `func (Callable)`: The function to be executed.\n- `*args (Any)`: Positional arguments for the function.\n- `**kwargs (Any)`: Keyword arguments for the function.\n\n**Returns:**  \n- `List[Any]`: A list of results from the execution on each GPU.\n\n**Raises:**  \n- `ValueError`: If any GPU index is invalid.\n- `RuntimeError`: If there is an error executing the function on the GPUs.\n\n**Example Usage:**\n\n```python\nresult = execute_on_multiple_gpus([0, 1], sample_task, 10)\nprint(f\"Results: {result}\")\n```\n\n---\n\n### `sample_task(n: int) -\u003e int`\n\n**Description:**  \nA sample task function that returns the square of a number.\n\n**Arguments:**  \n- `n (int)`: Input number to be squared.\n\n**Returns:**  \n- `int`: The square of the input number.\n\n**Example Usage:**\n\n```python\nresult = sample_task(10)\nprint(f\"Square of 10: {result}\")\n```\n\n---\n\nThis documentation provides a clear description of the function's purpose, arguments, return values, potential exceptions, and examples of how to use them.\n\n\n---\n\n## Contributing\n\nWe welcome contributions to ClusterOps! If you'd like to contribute, please follow these steps:\n\n1. **Fork the repository** on GitHub.\n2. **Clone your fork** locally:\n   ```bash\n   git clone https://github.com/The-Swarm-Corporation/ClusterOps.git\n   cd clusterops\n   ```\n3. **Create a feature branch** for your changes:\n   ```bash\n   git checkout -b feature/new-feature\n   ```\n4. **Install the development dependencies**:\n   ```bash\n   pip install -r dev-requirements.txt\n   ```\n5. **Make your changes**, and be sure to include tests.\n6. **Run tests** to ensure everything works:\n   ```bash\n   pytest\n   ```\n7. **Commit your changes** and push them to GitHub:\n   ```bash\n   git commit -m \"Add new feature\"\n   git push origin feature/new-feature\n   ```\n8. **Submit a pull request** on GitHub, and we’ll review it as soon as possible.\n\n### Reporting Issues\n\nIf you encounter any issues, please create a [GitHub issue](https://github.com/the-swarm-corporation/clusterops/issues).\n\n\n## Further Documentation\n\n[CLICK HERE](/DOCS.md)\n\n---\n\n## License\n\nClusterOps is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n---\n\n## Contact\n\nFor any questions, feedback, or contributions, please contact the **Swarms Team** at [kye@swarms.world](mailto:kye@swarms.world).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-swarm-corporation%2Fclusterops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-swarm-corporation%2Fclusterops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-swarm-corporation%2Fclusterops/lists"}