diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 000000000..610a2485d --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,285 @@ +# Kili Python SDK Configuration Guide + +## Overview + +The Kili Python SDK supports multiple configuration methods with a clear priority order. Configuration can be set via: + +1. Function parameters (highest priority) +2. Environment variables +3. Configuration file (`sdk-config.json`) +4. Default values (lowest priority) + +## Configuration File + +### Location + +The SDK searches for `sdk-config.json` in the following locations (in order): + +1. Current working directory +2. Home directory (`~`) + +### Format + +Create `sdk-config.json` with the following structure: + +```json +{ + "api_key": "your-api-key-here", + "api_endpoint": "https://cloud.kili-technology.com/api/label/v2/graphql", + "verify_ssl": true, + "disable_tqdm": false +} +``` + +## Configuration Options + +### 1. API Key (`api_key`) + +Your Kili API key for authentication. + +**Configuration Methods:** +```python +# 1. Function parameter (highest priority) +kili = Kili(api_key="your-api-key") + +# 2. Environment variable +export KILI_API_KEY="your-api-key" + +# 3. Configuration file +{ + "api_key": "your-api-key" +} + +# 4. Interactive prompt (if not set and terminal is available) +# The SDK will prompt you to enter the API key +``` + +**Example:** +```python +from kili.client import Kili + +# Method 1: Direct parameter +kili = Kili(api_key="abc123") + +# Method 2: Environment variable +# $ export KILI_API_KEY="abc123" +kili = Kili() # Will use env var + +# Method 3: Config file (sdk-config.json) +kili = Kili() # Will use config file +``` + +--- + +### 2. API Endpoint (`api_endpoint`) + +The GraphQL endpoint URL for Kili API. + +**Configuration Methods:** +```python +# 1. Function parameter +kili = Kili(api_endpoint="https://custom.kili.com/api/label/v2/graphql") + +# 2. Environment variable +export KILI_API_ENDPOINT="https://custom.kili.com/api/label/v2/graphql" + +# 3. Configuration file +{ + "api_endpoint": "https://custom.kili.com/api/label/v2/graphql" +} + +# 4. Default value +# "https://cloud.kili-technology.com/api/label/v2/graphql" +``` + +**Example:** +```python +from kili.client import Kili + +# For on-premise installations +kili = Kili( + api_key="your-api-key", + api_endpoint="https://your-company.kili.com/api/label/v2/graphql" +) + +# Or via environment variable +# $ export KILI_API_ENDPOINT="https://your-company.kili.com/api/label/v2/graphql" +kili = Kili(api_key="your-api-key") +``` + +--- + +### 3. TLS Verification (`verify` / `verify_ssl`) + +Controls TLS certificate verification for HTTPS requests. + +**Values:** + +- `True` (default): Verify TLS certificates +- `False`: Disable verification (not recommended for production) +- `str`: Path to CA bundle file + +**Configuration Methods:** +```python +# 1. Function parameter (uses 'verify') +kili = Kili(verify=False) + +# 2. Environment variable +export KILI_VERIFY=false # or "true", "1", "yes" + +# 3. Configuration file (uses 'verify_ssl') +{ + "verify_ssl": false +} + +# Note: The config file also supports 'verify' for backward compatibility + +# 4. Default value: True +``` + +**Example:** +```python +from kili.client import Kili + +# Disable verification for local development (NOT RECOMMENDED FOR PRODUCTION) +kili = Kili( + api_key="your-api-key", + verify=False +) + +# Use custom CA bundle +kili = Kili( + api_key="your-api-key", + verify="/path/to/ca-bundle.crt" +) + +# Via environment variable for testing +# $ export KILI_VERIFY=false +kili = Kili(api_key="your-api-key") +``` + +--- + +### 4. Disable Progress Bars (`disable_tqdm`) + +Globally disable progress bars (tqdm) for all operations. Individual function calls can still override this setting. + +**Values:** + +- `None` (default): Use each function's default behavior +- `True`: Disable progress bars globally +- `False`: Enable progress bars globally + +**Configuration Methods:** +```python +# 1. Function parameter (highest priority) +kili = Kili(disable_tqdm=True) + +# 2. Environment variable +export KILI_DISABLE_TQDM=true # or "false", "1", "yes" + +# 3. Configuration file +{ + "disable_tqdm": true +} + +# 4. Default: None (each function uses its own default) +``` + +**Priority for Individual Operations:** + +1. Function parameter: `kili.assets(project_id="id", disable_tqdm=True)` +2. Client global setting: `Kili(disable_tqdm=True)` +3. Function default (usually `False` to show progress) + +**Example:** +```python +from kili.client import Kili + +# Disable progress bars globally for automated scripts +kili = Kili(api_key="your-api-key", disable_tqdm=True) + +# All operations will have progress bars disabled +assets = kili.assets(project_id="your-project-id") +projects = kili.projects() + +# Override for specific operations +labels = kili.labels( + project_id="your-project-id", + disable_tqdm=False # Show progress bar just for this call +) + +# Via environment variable for CI/CD +# $ export KILI_DISABLE_TQDM=true +kili = Kili(api_key="your-api-key") # Progress bars disabled +``` + +--- + +## Environment Variables Reference + +| Variable | Type | Default | Description | +|----------|------|---------|-------------| +| `KILI_API_KEY` | string | None | Your Kili API key | +| `KILI_API_ENDPOINT` | string | `https://cloud.kili-technology.com/api/label/v2/graphql` | GraphQL API endpoint | +| `KILI_VERIFY` | boolean/string | `true` | TLS certificate verification | +| `KILI_DISABLE_TQDM` | boolean | None | Disable progress bars globally | + +**Boolean Environment Variables:** + +- Truthy values: `"true"`, `"1"`, `"yes"` (case-insensitive) +- Falsy values: `"false"`, `"0"`, `"no"` (case-insensitive) + +--- + +## Example : Production Configuration + +```json +{ + "api_endpoint": "https://cloud.kili-technology.com/api/label/v2/graphql", + "verify_ssl": true, + "disable_tqdm": false +} +``` + +```bash +export KILI_API_KEY="your-production-key" +``` + +```python +from kili.client import Kili + +# Loads settings from env var and config file +kili = Kili() +``` + +## Configuration Priority Summary + +For each setting, the priority order is: + +1. **Function parameter** (highest) + ```python + Kili(api_key="key", verify=False, disable_tqdm=True) + ``` + +2. **Environment variable** + ```bash + export KILI_API_KEY="key" + export KILI_VERIFY=false + export KILI_DISABLE_TQDM=true + ``` + +3. **Configuration file** (`sdk-config.json`) + ```json + { + "api_key": "key", + "verify_ssl": false, + "disable_tqdm": true + } + ``` + +4. **Default value** (lowest) + + - `api_endpoint`: `https://cloud.kili-technology.com/api/label/v2/graphql` + - `verify`: `True` + - `disable_tqdm`: `None` diff --git a/docs/sdk/tutorials/plugins_library.md b/docs/sdk/tutorials/plugins_library.md index 0269fd512..c286b3e76 100644 --- a/docs/sdk/tutorials/plugins_library.md +++ b/docs/sdk/tutorials/plugins_library.md @@ -27,7 +27,6 @@ Let's imagine a project where we want to process images and detect some objects. Let's imagine another project where we process invoices. The project has two jobs and several transcription tasks associated with them. One of the jobs is about payment information and must contain a proper IBAN number as well as currency. The IBAN must start with FR, and the currency should be one of: *EURO* or *DOLLAR*. Kili's interface customization options are powerful and flexible, but won't help us in this specific situation so we have to turn to Kili plugins for help. We'll set up our Kili plugin to check these two rules when labelers click *Submit*. If the annotations don't match our predefined rules, our QA bot will add issues to the asset and send the asset back to the labeling queue. At the end, our script will calculate labeling accuracy and insert the accuracy metric in the json_metadata of the asset. All that with no need to engage a human reviewer. - Plugin file: [`plugin_document.py`](https://github.com/kili-technology/kili-python-sdk/blob/main/recipes/plugins_library/plugin_document.py){target=_blank} -- End-to-end notebook showcasing this example: [`plugins_example_document.ipynb`](https://github.com/kili-technology/kili-python-sdk/blob/main/recipes/plugins_example_document.ipynb){target=_blank} ### 2. Consensus resolution diff --git a/mkdocs.yml b/mkdocs.yml index 532f517d0..40df8b9d2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,6 +12,7 @@ edit_uri: "" #disables edit button nav: - Python SDK: - Getting Started: index.md + - Configuration: configuration.md - Tutorials: tutorials.md - Reference: - Asset: sdk/asset.md