# API Documentation

Aether Framework provides several APIs for developers to interact with nodes, integrate LLMs, manage tasks, and enable decentralized collaboration.

***

#### **1. SwarmNode Class**

The `SwarmNode` class enables decentralized communication between nodes using IPFS.

**Methods**

* **`send_decentralized_message(message)`**\
  Send a message using IPFS.\
  **Example**:

  ```python
  node.send_decentralized_message("Hello, world!")
  ```
* **`retrieve_decentralized_message(ipfs_hash)`**\
  Retrieve a message from IPFS using its hash.\
  **Example**:

  ```python
  node.retrieve_decentralized_message("QmHashHere")
  ```

***

#### **2. TaskScheduler Class**

The `TaskScheduler` class manages task distribution and assignment within the swarm.

**Methods**

* **`add_task(node_id, task, priority)`**\
  Add a task to the scheduler.\
  **Example**:

  ```python
  scheduler.add_task(1, "Process data", priority=5)
  ```
* **`assign_task(nodes)`**\
  Assign tasks to nodes dynamically based on priority.\
  **Example**:

  ```python
  scheduler.assign_task(swarm.nodes)
  ```

***

#### **3. SwarmConsensus Class**

The `SwarmConsensus` class handles collaborative decision-making among agents.

**Methods**

* **`propose_task(task_description)`**\
  Propose a task to the swarm for consensus.\
  **Example**:

  ```python
  proposal_id = swarm.propose_task("Analyze data trends")
  ```
* **`vote(proposal_id)`**\
  Vote on a task proposal.\
  **Example**:

  ```python
  swarm.vote(proposal_id)
  ```
* **`get_consensus()`**\
  Check if consensus has been reached for a task.\
  **Example**:

  ```python
  consensus = swarm.get_consensus()
  print(consensus)
  ```

***

#### **4. IPFSClient Class**

The `IPFSClient` class enables decentralized storage and retrieval of data using IPFS.

**Methods**

* **`upload_file(file_path)`**\
  Upload a file to IPFS.\
  **Example**:

  ```python
  cid = ipfs_client.upload_file("data/task_data.json")
  print(f"Uploaded to IPFS with CID: {cid}")
  ```
* **`retrieve_file(cid, output_path)`**\
  Retrieve a file from IPFS using its CID.\
  **Example**:

  ```python
  ipfs_client.retrieve_file(cid, output_path="downloaded_data.json")
  ```

***

#### **5. Task Execution Examples**

**Example 1: Running a Swarm Simulation**

Simulate a swarm with 10 nodes:

```python
from src.swarm.advanced_swarm_behavior import Swarm

swarm = Swarm(10)
swarm.simulate(5)
```

**Example 2: Decentralized Messaging**

Send and retrieve messages using IPFS:

```python
# Send a message
node.send_decentralized_message("Task completed successfully.")

# Retrieve a message
message = node.retrieve_decentralized_message("QmHashHere")
print(f"Retrieved message: {message}")
```

**Example 3: Task Scheduling**

Add and assign tasks dynamically:

```python
scheduler.add_task(1, "Optimize reinforcement learning parameters", priority=5)
scheduler.assign_task(swarm.nodes)
```

***

#### **6. Integration Notes**

1. **Environment Variables**
   * Set wallet configurations securely for blockchain integration:

     ```plaintext
     SOLANA_WALLET_PATH=/path/to/solana-wallet.json
     ETHEREUM_WALLET_PRIVATE_KEY=your_private_key_here
     ```
2. **Modular Components**
   * All components (e.g., IPFSClient, SwarmConsensus) are designed to work independently or in combination.
3. **Extensibility**
   * Developers can extend core classes to customize workflows for specific use cases.

***

#### **Common Errors and Troubleshooting**

| **Error**                         | **Solution**                                                            |
| --------------------------------- | ----------------------------------------------------------------------- |
| `FileNotFoundError: Wallet path`  | Ensure the `SOLANA_WALLET_PATH` variable is set correctly.              |
| `ValueError: Private key missing` | Set the `ETHEREUM_WALLET_PRIVATE_KEY` variable in your environment.     |
| `Consensus not reached`           | Increase the threshold or verify voting agents are active in the swarm. |