Commit 8bbf5647 authored by Adrian Pino's avatar Adrian Pino Committed by GitHub
Browse files

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

Docs/improve readme
parents 4422c384 f70be58d
Loading
Loading
Loading
Loading
+134 −62
Original line number Diff line number Diff line
# 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.
+84 −11
Original line number Diff line number Diff line
# 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!
+6 −0
Original line number Diff line number Diff line
@@ -2,6 +2,12 @@

*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

examples/__init__.py

deleted100644 → 0
+0 −0

Empty file deleted.

+2 −2
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ from sunrise6g_opensdk import Sdk as sdkclient


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",
@@ -20,7 +20,7 @@ def main():
    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