Skip to content

Commit 14bfa9a

Browse files
florianlegaflorianlega
committed
chore: update documentation to add configuration page
1 parent 816ec9e commit 14bfa9a

File tree

3 files changed

+286
-1
lines changed

3 files changed

+286
-1
lines changed

‎docs/configuration.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
# Kili Python SDK Configuration Guide
2+
3+
## Overview
4+
5+
The Kili Python SDK supports multiple configuration methods with a clear priority order. Configuration can be set via:
6+
7+
1. Function parameters (highest priority)
8+
2. Environment variables
9+
3. Configuration file (`sdk-config.json`)
10+
4. Default values (lowest priority)
11+
12+
## Configuration File
13+
14+
### Location
15+
16+
The SDK searches for `sdk-config.json` in the following locations (in order):
17+
18+
1. Current working directory
19+
2. Home directory (`~`)
20+
21+
### Format
22+
23+
Create `sdk-config.json` with the following structure:
24+
25+
```json
26+
{
27+
"api_key": "your-api-key-here",
28+
"api_endpoint": "https://cloud.kili-technology.com/api/label/v2/graphql",
29+
"verify_ssl": true,
30+
"disable_tqdm": false
31+
}
32+
```
33+
34+
## Configuration Options
35+
36+
### 1. API Key (`api_key`)
37+
38+
Your Kili API key for authentication.
39+
40+
**Configuration Methods:**
41+
```python
42+
# 1. Function parameter (highest priority)
43+
kili = Kili(api_key="your-api-key")
44+
45+
# 2. Environment variable
46+
export KILI_API_KEY="your-api-key"
47+
48+
# 3. Configuration file
49+
{
50+
"api_key": "your-api-key"
51+
}
52+
53+
# 4. Interactive prompt (if not set and terminal is available)
54+
# The SDK will prompt you to enter the API key
55+
```
56+
57+
**Example:**
58+
```python
59+
from kili.client import Kili
60+
61+
# Method 1: Direct parameter
62+
kili = Kili(api_key="abc123")
63+
64+
# Method 2: Environment variable
65+
# $ export KILI_API_KEY="abc123"
66+
kili = Kili() # Will use env var
67+
68+
# Method 3: Config file (sdk-config.json)
69+
kili = Kili() # Will use config file
70+
```
71+
72+
---
73+
74+
### 2. API Endpoint (`api_endpoint`)
75+
76+
The GraphQL endpoint URL for Kili API.
77+
78+
**Configuration Methods:**
79+
```python
80+
# 1. Function parameter
81+
kili = Kili(api_endpoint="https://custom.kili.com/api/label/v2/graphql")
82+
83+
# 2. Environment variable
84+
export KILI_API_ENDPOINT="https://custom.kili.com/api/label/v2/graphql"
85+
86+
# 3. Configuration file
87+
{
88+
"api_endpoint": "https://custom.kili.com/api/label/v2/graphql"
89+
}
90+
91+
# 4. Default value
92+
# "https://cloud.kili-technology.com/api/label/v2/graphql"
93+
```
94+
95+
**Example:**
96+
```python
97+
from kili.client import Kili
98+
99+
# For on-premise installations
100+
kili = Kili(
101+
api_key="your-api-key",
102+
api_endpoint="https://your-company.kili.com/api/label/v2/graphql"
103+
)
104+
105+
# Or via environment variable
106+
# $ export KILI_API_ENDPOINT="https://your-company.kili.com/api/label/v2/graphql"
107+
kili = Kili(api_key="your-api-key")
108+
```
109+
110+
---
111+
112+
### 3. TLS Verification (`verify` / `verify_ssl`)
113+
114+
Controls TLS certificate verification for HTTPS requests.
115+
116+
**Values:**
117+
118+
- `True` (default): Verify TLS certificates
119+
- `False`: Disable verification (not recommended for production)
120+
- `str`: Path to CA bundle file
121+
122+
**Configuration Methods:**
123+
```python
124+
# 1. Function parameter (uses 'verify')
125+
kili = Kili(verify=False)
126+
127+
# 2. Environment variable
128+
export KILI_VERIFY=false # or "true", "1", "yes"
129+
130+
# 3. Configuration file (uses 'verify_ssl')
131+
{
132+
"verify_ssl": false
133+
}
134+
135+
# Note: The config file also supports 'verify' for backward compatibility
136+
137+
# 4. Default value: True
138+
```
139+
140+
**Example:**
141+
```python
142+
from kili.client import Kili
143+
144+
# Disable verification for local development (NOT RECOMMENDED FOR PRODUCTION)
145+
kili = Kili(
146+
api_key="your-api-key",
147+
verify=False
148+
)
149+
150+
# Use custom CA bundle
151+
kili = Kili(
152+
api_key="your-api-key",
153+
verify="/path/to/ca-bundle.crt"
154+
)
155+
156+
# Via environment variable for testing
157+
# $ export KILI_VERIFY=false
158+
kili = Kili(api_key="your-api-key")
159+
```
160+
161+
---
162+
163+
### 4. Disable Progress Bars (`disable_tqdm`)
164+
165+
Globally disable progress bars (tqdm) for all operations. Individual function calls can still override this setting.
166+
167+
**Values:**
168+
169+
- `None` (default): Use each function's default behavior
170+
- `True`: Disable progress bars globally
171+
- `False`: Enable progress bars globally
172+
173+
**Configuration Methods:**
174+
```python
175+
# 1. Function parameter (highest priority)
176+
kili = Kili(disable_tqdm=True)
177+
178+
# 2. Environment variable
179+
export KILI_DISABLE_TQDM=true # or "false", "1", "yes"
180+
181+
# 3. Configuration file
182+
{
183+
"disable_tqdm": true
184+
}
185+
186+
# 4. Default: None (each function uses its own default)
187+
```
188+
189+
**Priority for Individual Operations:**
190+
191+
1. Function parameter: `kili.assets(project_id="id", disable_tqdm=True)`
192+
2. Client global setting: `Kili(disable_tqdm=True)`
193+
3. Function default (usually `False` to show progress)
194+
195+
**Example:**
196+
```python
197+
from kili.client import Kili
198+
199+
# Disable progress bars globally for automated scripts
200+
kili = Kili(api_key="your-api-key", disable_tqdm=True)
201+
202+
# All operations will have progress bars disabled
203+
assets = kili.assets(project_id="your-project-id")
204+
projects = kili.projects()
205+
206+
# Override for specific operations
207+
labels = kili.labels(
208+
project_id="your-project-id",
209+
disable_tqdm=False # Show progress bar just for this call
210+
)
211+
212+
# Via environment variable for CI/CD
213+
# $ export KILI_DISABLE_TQDM=true
214+
kili = Kili(api_key="your-api-key") # Progress bars disabled
215+
```
216+
217+
---
218+
219+
## Environment Variables Reference
220+
221+
| Variable | Type | Default | Description |
222+
|----------|------|---------|-------------|
223+
| `KILI_API_KEY` | string | None | Your Kili API key |
224+
| `KILI_API_ENDPOINT` | string | `https://cloud.kili-technology.com/api/label/v2/graphql` | GraphQL API endpoint |
225+
| `KILI_VERIFY` | boolean/string | `true` | TLS certificate verification |
226+
| `KILI_DISABLE_TQDM` | boolean | None | Disable progress bars globally |
227+
228+
**Boolean Environment Variables:**
229+
230+
- Truthy values: `"true"`, `"1"`, `"yes"` (case-insensitive)
231+
- Falsy values: `"false"`, `"0"`, `"no"` (case-insensitive)
232+
233+
---
234+
235+
## Example : Production Configuration
236+
237+
```json
238+
{
239+
"api_endpoint": "https://cloud.kili-technology.com/api/label/v2/graphql",
240+
"verify_ssl": true,
241+
"disable_tqdm": false
242+
}
243+
```
244+
245+
```bash
246+
export KILI_API_KEY="your-production-key"
247+
```
248+
249+
```python
250+
from kili.client import Kili
251+
252+
# Loads settings from env var and config file
253+
kili = Kili()
254+
```
255+
256+
## Configuration Priority Summary
257+
258+
For each setting, the priority order is:
259+
260+
1. **Function parameter** (highest)
261+
```python
262+
Kili(api_key="key", verify=False, disable_tqdm=True)
263+
```
264+
265+
2. **Environment variable**
266+
```bash
267+
export KILI_API_KEY="key"
268+
export KILI_VERIFY=false
269+
export KILI_DISABLE_TQDM=true
270+
```
271+
272+
3. **Configuration file** (`sdk-config.json`)
273+
```json
274+
{
275+
"api_key": "key",
276+
"verify_ssl": false,
277+
"disable_tqdm": true
278+
}
279+
```
280+
281+
4. **Default value** (lowest)
282+
283+
- `api_endpoint`: `https://cloud.kili-technology.com/api/label/v2/graphql`
284+
- `verify`: `True`
285+
- `disable_tqdm`: `None`

‎docs/sdk/tutorials/plugins_library.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,6 @@ Let's imagine a project where we want to process images and detect some objects.
2727
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.
2828

2929
- Plugin file: [`plugin_document.py`](https://github.com/kili-technology/kili-python-sdk/blob/main/recipes/plugins_library/plugin_document.py){target=_blank}
30-
- 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}
3130

3231
### 2. Consensus resolution
3332

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ edit_uri: "" #disables edit button
1212
nav:
1313
- Python SDK:
1414
- Getting Started: index.md
15+
- Configuration: configuration.md
1516
- Tutorials: tutorials.md
1617
- Reference:
1718
- Asset: sdk/asset.md

0 commit comments

Comments
 (0)