# Runtime options (Python, Notebook, Function)

This package runs in three common contexts: Python scripts/REPL, notebooks, and Cognite Functions.
All local contexts use the same API; the difference is execution model and dependency management.

## Usage contexts

| Context | Install | Entry points | Typical use |
| --- | --- | --- | --- |
| **Python script / REPL** | `pip install cognite-data-quality` in a venv | `run_validation`, `deploy_validation_infrastructure`, `deploy_validation_pipeline`, `call_*` invoke helpers | Headless runs, CI, scheduled jobs, invoking deployed functions |
| **Notebook** | `%pip install cognite-data-quality` or venv | Same as above | Interactive exploration, inspecting `result.violations`, iterating over records |
| **Cognite Function** | `requirements.txt` or `[requirements]` tags | Handler imports from package | Event-driven or scheduled validation in CDF |

## Minimal examples

### Python script

```python
from cognite_data_quality import load_cognite_client_from_toml, run_validation

client = load_cognite_client_from_toml("config.toml")
result = run_validation(
    client=client,
    rules_path="config/environments/cog-ai/shacl_rules/equipment_shacl_rules.ttl",
    rules_format="ttl",
    instance_space="my_instances",
)
print(result.conforms, len(result.violations))
```

### Notebook

```python
%pip install cognite-data-quality
```

```python
from cognite_data_quality import load_cognite_client_from_toml, run_validation

client = load_cognite_client_from_toml("config.toml")
result = run_validation(
    client=client,
    rules_path="config/environments/cog-ai/shacl_rules/equipment_shacl_rules.ttl",
    rules_format="ttl",
    instance_space="my_instances",
)
result.violations[:5]
```

### Invoking deployed functions

```python
from cognite_data_quality import load_cognite_client_from_toml, call_validate_instances_shacl

client = load_cognite_client_from_toml("config.toml")
data = {
    "instances": {"items": {"n": [...]}},
    "shacl_rules_file_external_id": "my_shacl_rules",
    "datamodel_space": "space", "datamodel_external_id": "model", "datamodel_version": "v1",
    "records_config": {"stream_id": "dq_stream", "rule_set_id": "MyRuleSet", "rule_set_version": "1.0"},
}
result = call_validate_instances_shacl(client, data)
```

### Cognite Function

```python
def handle(client, data):
    """
    [requirements]
    cognite-data-quality
    [/requirements]
    """
    from cognite_data_quality import run_validation

    return run_validation(
        client=client,
        rules_path="rules/equipment_shacl_rules.ttl",
        rules_format="ttl",
        instance_space="my_instances",
    ).model_dump()
```

## Options per entry point

- **run_validation**: `rules_path`, `rules_format`, `datamodel`, `instance_space`, `verbose`, `records_config`,
  `post_to_records`, `namespace_base`
- **load_cognite_client_from_toml**: `config_path` (default `config.toml`)
- **deploy_validation_infrastructure**: `settings_path`, `views_dir`, `function_secrets`, `dry_run`, `force`
- **deploy_validation_pipeline**: `settings_path`, `view_external_id`, `wait`
- **Invoke helpers** (`call_validate_instances_shacl`, etc.): `client`, `data` (payload dict), `wait`, `external_id`
