Merge pull request #86 from SunriseOpenOperatorPlatform/docs/improve-readme

# OpenSDK

Open source SDK to abstract CAMARA/GSMA Transformation Functions (TFs) for Edge Cloud platforms & 5G network cores

Open source SDK to abstract CAMARA/GSMA Transformation Functions (TFs) for Edge Cloud platforms, 5G network cores and O-RAN solutions.

## Contributing Guidelines

Thank you for contributing to this project. Please follow the guidelines below to ensure a smooth collaboration.

## Features

### Directory Structure

Each contribution should be made in the appropriate directory:

- **EdgeCloud Adapters** → `src/sunrise6g-opendk/edgecloud/clients/`

- **Network Adapters** → `src/sunrise6g-opendk/network/clients/`

- **O-RAN Adapters** → `src/sunrise6g-opendk/oran/clients/`

- Unified SDK for interacting with Edge Cloud platforms, 5G Core solutions, and O-RAN solutions.

- Modular and extensible adapter structure

- Conforms to CAMARA/GSMA API standards.

### Testing (Mandatory)

To merge a feature branch into `main`, the adapter **must pass the unit tests**. Instructions to do so available at [TESTING.md](docs/TESTING.md)

---

### Contributing

1. **Check Guidelines at [CONTRIBUTING.md](docs/CONTRIBUTING.md).**

2. **Create a New Branch** following the naming convention.

3. **Develop Your Feature** inside the correct directory.

4. **Ensure All Tests Pass**  before the merge.

5. **Submit a Merge Request (MR)** to the `main` branch.

## API & Platform Support Matrix

### Branch Naming Convention

Each partner should create a feature branch following the naming convention based on the type of adapter they are contributing:

### CAMARA APIs

#### ☁️ EdgeCloud Adapters

Branch Name Format:

```

feature/add-edgecloud-<EDGE_CLOUD_PLATFORM_NAME>

```

Example:

```

feature/add-edgecloud-i2edge

```

| API Name             | Version      |

|----------------------|--------------|

| Edge Application Management            | v0.9.3-wip   |

| Quality-on-Demand    | v1.0.0       |

| Location Retrieval   | v1.0.0       |

| Traffic Influence    | v0.8.1       |

#### 🌐 Network Adapters

Branch Name Format:

```

feature/add-network-<5G_CORE_NAME>

```

Example:

```

feature/add-network-open5gs

```

### EdgeCloud Platforms

| Platform   | Status     |

|------------|------------|

| Kubernetes | To be supported soon |

| i2Edge     | Supported  |

| aerOS      | Supported  |

#### 📶 O-RAN Adapters

Branch Name Format:

```

feature/add-oran-<SOLUTION_NAME>

### Network Adapters

| Platform     | NEF Version | QoD | Location Retrieval | Traffic Influence |

|--------------|-------------|-----|---------------------|--------------------|

| Open5GS      | v1.2.3      | ✅  | ✅                  | ❌                 |

| Open5GCore   | v1.2.3      | ✅  | ❌                  | ❌                 |

| OAI          | v1.2.3      | ✅  | ❌                  | ✅                 |

---

## How to Use

### Option 1: Install via PyPI

For end users:

```bash

pip install sunrise6g-opensdk

```

Example:

### Option 2: Development Mode

If you plan to modify the SDK:

```bash

git clone https://github.com/<your-org>/sunrise6g-opensdk.git

cd sunrise6g-opensdk

pip install -r requirements.txt

```

feature/add-oran-juniper

### Basic Usage

You can use the SDK by simply specifying the adapters to be used. E.g. i2Edge and Open5gs

```python

from sunrise6g_opensdk import Sdk as sdkclient

def main():

    client_specs = {

        "edgecloud": {

            "client_name": "i2edge",

            "base_url": "http://IP:PORT",

        },

        "network": {

            "client_name": "open5gs",

            "base_url": "http://IP:PORT",

            "scs_as_id": "id_example",

        },

    }

    clients = sdkclient.create_clients_from(client_specs)

    edgecloud_client = clients.get("edgecloud")

    network_client = clients.get("network")

    print(edgecloud_client.get_edge_cloud_zones())

    print(network_client.get_qod_session(session_id="example_session_id"))

if __name__ == "__main__":

    main()

```

## Sequence Diagram Example

Refer to the sequence diagram example from `docs/workflows/edgecloud/get_av_zones.md` for guidance on workflow structure:

Example available in [`/examples/example.py`](examples/example.py)

---

## How to Contribute

We welcome contributions to OpenSDK!

To get started:

1. Fork the repository and create a branch from `main`.

2. Add your changes in the appropriate adapter directory.

3. Write or update tests for your changes.

4. Ensure all tests and pre-commit checks pass.

5. Submit a pull request with a clear description.

Please follow our full [Contributing Guidelines](docs/CONTRIBUTING.md) for details on:

- Directory structure

- Branch naming conventions

- Coding standards (PEP8, docstrings)

- Pre-commit setup

- Reporting issues

---

## Example Workflow (Mermaid)

```mermaid

sequenceDiagram

title Retrieve Edge Cloud Zones

actor AP as App Vertical Provider

participant CE as Capabilities Exposure

box Service Resource Manager

    participant API

    participant SDK as EdgeCloudSDK

title Application Deployment using the Open SDK

actor AP as Application Vertical Provider

box Module implementing CAMARA APIs

    participant API as CAMARA Edge Application Management API

    participant SDK as Open SDK

end

participant i2Edge

participant PiEdge

note over AP,CE: CAMARA EdgeCloud API

AP ->> CE: GET /edge-cloud-zones

CE ->> API: GET /av. zones

API ->> SDK: sbi = EdgeCloudFactory.create_edgecloud_client(i2Edge)

API ->> SDK: sbi.get_edge_cloud_zones()

SDK ->> i2Edge: GET /zones/list

API ->> SDK: sbi = EdgeCloudFactory.create_edgecloud_client(PiEdge)

API ->> SDK: sbi.get_edge_cloud_zones()

SDK ->> PiEdge: GET /nodes

participant K8s as Kubernetes

note over SDK: [configuration] Edge Cloud platform: Kubernetes

API ->> SDK: edgecloud_client = clients.get("edgecloud")

API ->> SDK: sdkclient.create_clients_from(configuration)

AP ->> API: POST /app (APP_ONBOARD_MANIFEST)

API ->> SDK: edgecloud_client.onboard_app(APP_ONBOARD_MANIFEST)

SDK ->> K8s: POST /onboard

AP ->> API: POST /appinstances (APP_ID, APP_ZONES)

API ->> SDK: edgecloud_client.deploy_app(APP_ID, APP_ZONES)

SDK ->> K8s: POST /deploy

```

---

## Roadmap

- [ ] Add support to GSMA OPG.02 TFs (WIP)

- [ ] Include JUNIPER O-RAN adapter (WIP)

---

## License

Apache 2.0 License – see [`LICENSE`](LICENSE) file for details.

# Contributing

# Contributing to OpenSDK

To contribute with code, follow the instructions below to enforce automatic syntax formatting and linting.

Configuration is taken from https://www.pre-commit.com/#2-add-a-pre-commit-configuration and from git-hooks.

Thank you for considering contributing to OpenSDK! This guide outlines how to contribute code, report issues, and ensure consistency across submissions.

*Note*: apply commands from the root of the repository.

---

## Getting Started

To contribute:

1. Fork the repository and create a feature branch from `main`.

2. Develop your changes in the appropriate adapter directory:

   - `src/sunrise6g_opensdk/edgecloud/clients/`

   - `src/sunrise6g_opensdk/network/clients/`

   - `src/sunrise6g_opensdk/oran/clients/`

3. Follow the coding guidelines below.

4. Write or update unit tests for your changes.

5. Ensure all tests pass.

6. Set up and run `pre-commit` hooks before pushing changes.

7. Submit a pull request with a clear and concise description.

---

## Branch Naming Convention

Choose a branch name that reflects the adapter type and your feature:

- `feature/add-edgecloud-<platform>`

- `feature/add-network-<5gcore>`

- `feature/add-oran-<solution>`

Examples:

```bash

feature/add-edgecloud-i2edge

feature/add-network-open5gs

feature/add-oran-juniper

```

---

## Coding Guidelines

- Write meaningful commit messages.

- Keep pull requests focused and concise.

- Document public methods and classes using docstrings.

---

## Pre-commit Hook Setup

We use `pre-commit` to enforce formatting and static analysis. Apply these commands from the root of the repository:

### Initial Setup

```bash

# Required: install the pre-commit hooks

pip3 install pre-commit

pre-commit install

```

### Optional (Run hooks manually or before commit)

# Optional: manual trigger (to know how validation will be applied or to force it manually on files before/after commit)

```bash

pre-commit run --all-files

```

# Optional: to keep the pre-commit versions of validation up-to-date

pre-commit autoupdate

---

# Optional: to remove the pre-commit git-hook binding

pre-commit uninstall

```

## Testing

Before submitting your contribution, ensure all unit tests pass.

See [TESTING.md](TESTING.md) for instructions.

---

## Reporting Issues

Please use the [Issue Tracker](https://github.com/SunriseOpenOperatorPlatform/sunrise6g-opensdk/issues) for bug reports or feature requests.

When reporting a bug, include:

- A clear description of the problem

- Steps to reproduce it

- Relevant logs or error messages (if any)

---

## Code of Conduct

We are committed to maintaining a welcoming and respectful environment for all contributors.

---

Thank you for helping improve OpenSDK!

*Note*: apply commands from the root of the repository.

To test that the adapters can be instantiated:

```bash

pytest tests/common/

```

To run tests for the Edge Cloud adapters:

```bash

def main():

    # The module that imports the SDK library, must specify "client_specs"

    # The module that imports the SDK package, must specify which adapters will be used:

    client_specs = {

        "edgecloud": {

            "client_name": "i2edge",

    network_client = clients.get("network")

    print("EdgeCloud client ready to be used:", edgecloud_client)

    print("EdgeCloud client ready to be used:", network_client)

    print("Network client ready to be used:", network_client)

    # Examples:

    # EdgeCloud