Metadata-Version: 2.4
Name: netorca-sdk
Version: 1.0.13
Summary: A Python SDK for interacting with the NetOrca API
Home-page: https://gitlab.com/netorca_public/netorca_sdk/
Author: Scott Rowlandson
Author-email: scott@netautomate.org
License: MIT
Keywords: netorca,orchestration,netautomate,network,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifultable>=1.0.0
Requires-Dist: ruamel.yaml>=0.17.0
Requires-Dist: gitpython>=3.1.50
Requires-Dist: pyyaml==6.0.3
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NetOrca SDK

The official Python SDK for the [NetOrca](https://netorca.io) API. Build automation pipelines, manage services, and integrate NetOrca into your CI/CD workflows with a clean, fully typed Python interface.

---

## Installation

```bash
pip install netorca-sdk
```

**Requirements:** Python 3.8+

---

## Client Initialisation

```python
from netorca_sdk import NetOrcaClient

client = NetOrcaClient(
    fqdn="https://your-instance.netorca.io/v1",
    api_key="YOUR_API_KEY",
)
```

The `context` parameter controls which point-of-view the client operates from:

```python
# Service owner context (default)
client = NetOrcaClient(fqdn="...", api_key="...", context="serviceowner")

# Consumer context
client = NetOrcaClient(fqdn="...", api_key="...", context="consumer")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `fqdn` | `str` | required | Base URL of your NetOrca instance |
| `api_key` | `str` | required | Your NetOrca API key |
| `context` | `str` | `"serviceowner"` | Point-of-view: `"serviceowner"` or `"consumer"` |
| `verify_ssl` | `bool` | `True` | Verify SSL certificates on requests |
| `verify_auth` | `bool` | `True` | Validate the API key on initialisation |

---

## Available Resources

### `client.services`

The definitions published in the NetOrca catalogue — what consumers can order. Each service has a name, JSON Schema, and lifecycle state.

```python
for service in client.services.list():
    print(service.name, service.state)
```

### `client.service_items`

A running instance of a service — what a consumer has requested and what the service owner delivers.

```python
item = client.service_items.get(123)
print(item.name, item.runtime_state)
```

### `client.deployed_items`

Records the provisioning output of a fulfilled change instance — connection strings, hostnames, credentials, or any structured data the consumer needs.

```python
item = client.deployed_items.create({
    "service_item": 123,
    "change_instance": 456,
    "data": {"host": "db-prod-01.internal", "port": 5432}
})
print(item.id)
```

### `client.change_instances`

A lifecycle event on a service item — a create, modify, or delete request. Automation pipelines watch these, process them, and update the state.

```python
for ci in client.change_instances.list(state="PENDING"):
    print(ci.id, ci.change_type)

client.change_instances.update(ci.id, {"state": "COMPLETED"})
```

### `client.service_configs`

A snapshot of a service's configuration at a specific version, recorded whenever it's provisioned or modified.

```python
config = client.service_configs.create({
    "service": 45,
    "config": {"engine": "postgres", "size": "medium"}
})
print(config.id, config.version)
```

### `client.charges`

Billing records attached to service items — either a one-time cost per change or a recurring monthly cost. Read-only.

```python
for charge in client.charges.list():
    print(charge.charge_type, charge.total_charge)
```

### `client.applications`

A named grouping that belongs to a consumer team; every service item belongs to one. Managed automatically by the platform, so it's read-only.

```python
for app in client.applications.list():
    print(app.name, app.owner_name)
```

### `client.submissions`

Direct access to submission records — each one is a payload a consumer team sent declaring the state of their applications. Immutable once created.

```python
submission = client.submissions.submit({
    "team_name": {
        "metadata": {"team_email": "team@example.com"},
        "my-application": {"services": {"DATABASE": {"engine": "postgres"}}}
    }
})
print(submission.id, submission.status)
```

### `client.healthchecks`

Verifies the availability of a service item by making an HTTP request to a configured URL. Results are stored and can be triggered on demand.

```python
result = client.healthchecks.trigger_service_item(service_item_id=123)
print(result)
```

### `client.webhooks`

Registers a URL for NetOrca to POST to whenever a change instance reaches a configured state.

```python
webhook = client.webhooks.create({
    "target_url": "https://your-service.example.com/netorca/events",
    "service": 45,
    "change_instance_state": "PENDING"
})
```

### `client.ai_processors`

Defines the prompts NetOrca uses to automate service operations — linked to a service, an LLM model, and an action type (`config`, `verify`, `execution`, etc).

```python
processor = client.ai_processors.create({
    "name": "database-service_config",
    "service": 45,
    "llm_model": 1,
    "action_type": "config",
    "prompt": "Given the consumer request, generate a valid database configuration...",
    "active": True
})
```

### `client.ai_documents`

Context files attached to a service that an AI processor can retrieve and query when generating a configuration — architecture notes, runbooks, policies.

```python
doc = client.ai_documents.create_for_service(
    service_id=45,
    data={"filename": "runbook.md", "raw_content": "# Runbook\n..."}
)
```

### `client.pack_profiles`

The configuration record that ties a service's AI pack together — linking processors, validators, and documents into a resolved configuration.

```python
profile = client.pack_profiles.create_for_service(
    service_id=45,
    data={"pack_enabled": True, "top_k": 5}
)
```

### `client.llm_models`

Language model connections registered in NetOrca — register a model once with its provider credentials, then reuse it across processors and validators.

```python
model = client.llm_models.create({
    "name": "gpt-4o",
    "provider": "openai",
    "model_name": "gpt-4o",
    "api_key": "sk-...",
    "active": True
})
```

---

## Full Documentation

[docs.netorca.io/sdk-guide/introduction](https://docs.netorca.io/sdk-guide/introduction/)

---

## License

[MIT License](https://gitlab.com/netorca_public/netorca_sdk/-/blob/main/LICENSE)
