ehs-llm-client 0.1.15__tar.gz → 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/PKG-INFO +143 -4
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/README.md +140 -2
- ehs_llm_client-0.2.0/ehs_llm_client/__init__.py +12 -0
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client/client.py +79 -15
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client/config.py +1 -0
- ehs_llm_client-0.2.0/ehs_llm_client/decisions.py +254 -0
- ehs_llm_client-0.2.0/ehs_llm_client/exceptions.py +18 -0
- ehs_llm_client-0.2.0/ehs_llm_client/py.typed +0 -0
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client.egg-info/PKG-INFO +143 -4
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client.egg-info/SOURCES.txt +4 -1
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/pyproject.toml +28 -24
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/tests/test_client.py +54 -6
- ehs_llm_client-0.2.0/tests/test_decisions.py +323 -0
- ehs_llm_client-0.1.15/ehs_llm_client/__init__.py +0 -3
- ehs_llm_client-0.1.15/ehs_llm_client/exceptions.py +0 -9
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client/utils.py +0 -0
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client.egg-info/dependency_links.txt +0 -0
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client.egg-info/requires.txt +0 -0
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/ehs_llm_client.egg-info/top_level.txt +0 -0
- {ehs_llm_client-0.1.15 → ehs_llm_client-0.2.0}/setup.cfg +0 -0
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: ehs-llm-client
|
|
3
|
-
Version: 0.
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Async client for OpenAI, Azure OpenAI, Microsoft Foundry, Google Gemini and TypeSafe decision models
|
|
5
5
|
Author-email: Andersen Huang <andersen.huang@ehsanalytics.com>
|
|
6
6
|
License-Expression: MIT
|
|
7
|
+
Requires-Python: >=3.10
|
|
7
8
|
Description-Content-Type: text/markdown
|
|
8
9
|
Requires-Dist: openai>=1.97.0
|
|
9
10
|
Requires-Dist: httpx[http2]
|
|
@@ -16,8 +17,10 @@ Requires-Dist: python-dateutil
|
|
|
16
17
|
[](https://pypi.org/project/ehs-llm-client/)
|
|
17
18
|
[](https://www.python.org/downloads/)
|
|
18
19
|
|
|
19
|
-
`ehs-llm-client` is a unified **async Python client** for
|
|
20
|
-
|
|
20
|
+
`ehs-llm-client` is a unified **async Python client** for **OpenAI**, **Azure OpenAI**,
|
|
21
|
+
**Microsoft Foundry (AIF)**, **Google Gemini**, and **TypeSafe/Jev**.
|
|
22
|
+
It supports generative responses and native typed decisions. Provider batch APIs
|
|
23
|
+
remain available for supported generative deployments.
|
|
21
24
|
|
|
22
25
|
---
|
|
23
26
|
|
|
@@ -26,6 +29,7 @@ It supports **single calls**, **structured JSON outputs**, and **batch processin
|
|
|
26
29
|
- Async support for multiple LLM providers
|
|
27
30
|
- Unified interface across OpenAI, Azure, and Google Gemini
|
|
28
31
|
- Structured JSON responses via schemas
|
|
32
|
+
- Native `choice`, `noul` and `score` decisions via Foundry and TypeSafe
|
|
29
33
|
- Retry and timeout handling
|
|
30
34
|
- Batch processing support
|
|
31
35
|
- Environment variable configuration for API keys
|
|
@@ -141,6 +145,62 @@ v1 API; existing `api_version` settings are retained for compatibility and ignor
|
|
|
141
145
|
See [Azure Responses API documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/responses)
|
|
142
146
|
for supported models and regions.
|
|
143
147
|
|
|
148
|
+
### Microsoft Foundry (AIF) and TypeSafe
|
|
149
|
+
|
|
150
|
+
Version 0.2.0 adds two providers. Existing providers, credential precedence and
|
|
151
|
+
the `get_response_async()` positional arguments and return tuple are preserved.
|
|
152
|
+
|
|
153
|
+
| Provider | `api` | Method | Endpoint |
|
|
154
|
+
| --- | --- | --- | --- |
|
|
155
|
+
| `azure_foundry` | `responses` (default) | `get_response_async()` | `/openai/v1/responses` |
|
|
156
|
+
| `azure_foundry` | `systemone` | `decide_async()` | `/providers/microsoft/v1/systemone` |
|
|
157
|
+
| `typesafe` | `systemone` (default) | `decide_async()` | `https://api.typesafe.ai/v1/systemone` |
|
|
158
|
+
|
|
159
|
+
Select the API explicitly for Foundry decision deployments; deployment names do
|
|
160
|
+
not determine the protocol. This release supports these two APIs, rather than
|
|
161
|
+
every model/API in the Foundry catalog.
|
|
162
|
+
|
|
163
|
+
```ini
|
|
164
|
+
[foundry_gpt]
|
|
165
|
+
provider = azure_foundry
|
|
166
|
+
api = responses
|
|
167
|
+
model = gpt-6-luna
|
|
168
|
+
base_url = https://YOUR-RESOURCE.services.ai.azure.com
|
|
169
|
+
default_reasoning_effort = low
|
|
170
|
+
|
|
171
|
+
[foundry_decision]
|
|
172
|
+
provider = azure_foundry
|
|
173
|
+
api = systemone
|
|
174
|
+
model = decision-1
|
|
175
|
+
base_url = https://YOUR-RESOURCE.services.ai.azure.com
|
|
176
|
+
|
|
177
|
+
[typesafe_jev]
|
|
178
|
+
provider = typesafe
|
|
179
|
+
model = jev-latest
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
For Foundry, `model` is the **deployment name**. For TypeSafe, it is the model
|
|
183
|
+
name or alias. Foundry uses its own `AZURE_FOUNDRY_API_KEY` and
|
|
184
|
+
`AZURE_FOUNDRY_ENDPOINT`; it never falls back to Azure OpenAI credentials.
|
|
185
|
+
A configured `base_url` takes precedence over `LLM_BASE_URL`, then the
|
|
186
|
+
provider-specific endpoint variable. TypeSafe defaults to `https://api.typesafe.ai`;
|
|
187
|
+
an explicit `base_url` or environment-only `LLM_BASE_URL` can override it.
|
|
188
|
+
|
|
189
|
+
Foundry expects a resource endpoint, not an `/api/projects/...` URL. Responses
|
|
190
|
+
also accepts a full `/openai/v1/` endpoint. System One accepts the resource root,
|
|
191
|
+
its corresponding versioned API prefix, or its full System One endpoint.
|
|
192
|
+
These endpoints must use HTTPS and contain no query string, fragment or embedded
|
|
193
|
+
credentials. Selecting `azure_foundry` does not itself establish project billing
|
|
194
|
+
attribution; that depends on the Azure endpoint and service capabilities.
|
|
195
|
+
|
|
196
|
+
For environment-only configuration, set `LLM_PROVIDER`, `LLM_MODEL`, and
|
|
197
|
+
`LLM_API=systemone` for Foundry decision models, together with its endpoint/key.
|
|
198
|
+
TypeSafe needs `LLM_PROVIDER=typesafe`, `LLM_MODEL=jev-latest`, and
|
|
199
|
+
`TYPESAFE_API_KEY`.
|
|
200
|
+
|
|
201
|
+
See the [Microsoft Decision API](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/how-to/use-foundry-models-microsoft-decision)
|
|
202
|
+
and [TypeSafe System One API](https://docs.typesafe.ai/api/system-one).
|
|
203
|
+
|
|
144
204
|
---
|
|
145
205
|
|
|
146
206
|
## Usage
|
|
@@ -238,6 +298,76 @@ retry and timeout arguments. Prefer keyword arguments for clarity.
|
|
|
238
298
|
OpenAI/Azure JSON mode (`schema="return json"`) requires string message contents,
|
|
239
299
|
as in 0.1.10. Regular calls and schema-based output retain support for content arrays.
|
|
240
300
|
|
|
301
|
+
### Native typed decisions
|
|
302
|
+
|
|
303
|
+
Use the same questions with either a Foundry `systemone` section or a TypeSafe
|
|
304
|
+
section. State can be text, a JSON object or an array. Instructions and criteria
|
|
305
|
+
descriptions may also contain JSON structures.
|
|
306
|
+
|
|
307
|
+
```python
|
|
308
|
+
import asyncio
|
|
309
|
+
from ehs_llm_client import LLM, ChoiceAnswer
|
|
310
|
+
|
|
311
|
+
async def main():
|
|
312
|
+
async with LLM("typesafe_jev", config_file_path="llmconfig.cfg") as model:
|
|
313
|
+
result = await model.decide_async(
|
|
314
|
+
state="A worker suffered a minor cut and received first aid.",
|
|
315
|
+
questions={
|
|
316
|
+
"category": {
|
|
317
|
+
"type": "choice",
|
|
318
|
+
"instructions": "Classify the reported incident.",
|
|
319
|
+
"criteria": {
|
|
320
|
+
"injury": "An injury occurred.",
|
|
321
|
+
"near_miss": "An event occurred without injury.",
|
|
322
|
+
"unknown": "There is insufficient information.",
|
|
323
|
+
},
|
|
324
|
+
},
|
|
325
|
+
"injured": {"type": "noul", "instructions": "Was anyone injured?"},
|
|
326
|
+
"severity": {
|
|
327
|
+
"type": "score",
|
|
328
|
+
"instructions": "Rate the reported outcome.",
|
|
329
|
+
"criteria": ["No injury", "Minor injury", "Serious injury"],
|
|
330
|
+
},
|
|
331
|
+
},
|
|
332
|
+
max_retries=3,
|
|
333
|
+
timeout=30,
|
|
334
|
+
)
|
|
335
|
+
answer = result.answers["category"]
|
|
336
|
+
if isinstance(answer, ChoiceAnswer):
|
|
337
|
+
print(answer.choice, answer.probabilities, answer.confidence)
|
|
338
|
+
print(result.model, result.usage.input_tokens, result.usage.output_tokens)
|
|
339
|
+
|
|
340
|
+
asyncio.run(main())
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
`DecisionResult` contains typed `ChoiceAnswer`, `NoulAnswer` and `ScoreAnswer`
|
|
344
|
+
objects, a resolved `model`, `DecisionUsage`, an optional `request_id`, and the
|
|
345
|
+
complete provider JSON in `raw_response`. Choice/score probabilities, confidence
|
|
346
|
+
and score legends are preserved when supplied; absent optional fields are `None`.
|
|
347
|
+
Noul is a probability from 0 to 1, not a boolean. Score is a number between zero
|
|
348
|
+
and the last criterion's index and can fall between levels. The library does not
|
|
349
|
+
choose thresholds, turn uncertainty into labels, or translate answers for EIDA.
|
|
350
|
+
|
|
351
|
+
Input and answer shapes, allowed labels, numeric ranges and token usage are
|
|
352
|
+
validated. Malformed successful responses raise `LLMResponseError`. HTTP failures
|
|
353
|
+
raise `LLMAPIError` (a subclass) with `status_code` and optional `request_id`;
|
|
354
|
+
error messages exclude provider response bodies. Inspect `raw_response` carefully
|
|
355
|
+
before logging it because provider extensions can contain sensitive information.
|
|
356
|
+
|
|
357
|
+
Decision calls retry transport failures, timeouts and HTTP 408, 429, 500, 502,
|
|
358
|
+
503, 504 and 529, honoring `Retry-After` and `retry-after-ms` when valid. Other HTTP
|
|
359
|
+
failures and invalid answers are not retried. As with the existing library API,
|
|
360
|
+
`max_retries` means **total attempts**, including the first request; `1` disables
|
|
361
|
+
retries. `timeout` is the limit for each attempt, so retries and backoff can make
|
|
362
|
+
the complete call longer. Cancellation propagates to the caller.
|
|
363
|
+
|
|
364
|
+
System One clients reject generative calls, provider batch operations,
|
|
365
|
+
`model_batch`, and `default_reasoning_effort`. Use concurrent `decide_async()`
|
|
366
|
+
calls for application-level parallelism. Generative clients reject `decide_async()`.
|
|
367
|
+
|
|
368
|
+
All providers support `async with LLM(...)` and `await llm.aclose()` to release
|
|
369
|
+
their clients. Keep a client open across repeated calls to reuse connections.
|
|
370
|
+
|
|
241
371
|
---
|
|
242
372
|
|
|
243
373
|
### Batch request
|
|
@@ -275,10 +405,19 @@ Keep API keys **out of code**. Recommended environment variables:
|
|
|
275
405
|
| OpenAI | `OPENAI_API_KEY` | `openaiAPIkey`, `openaiAPIKey` |
|
|
276
406
|
| Azure OpenAI | `AZURE_OPENAI_API_KEY` | `azure_openaiAPIkey`, `azure_openaiAPIKey` |
|
|
277
407
|
| Google Gemini | `GOOGLE_API_KEY` | `googleAPIkey`, `googleAPIKey` |
|
|
408
|
+
| Microsoft Foundry | `AZURE_FOUNDRY_API_KEY` | `azure_foundryAPIkey`, `azure_foundryAPIKey` |
|
|
409
|
+
| TypeSafe | `TYPESAFE_API_KEY` | `typesafeAPIkey`, `typesafeAPIKey` |
|
|
278
410
|
|
|
279
411
|
The 0.1.10 `APIKey` spelling takes precedence, followed by the older `APIkey`
|
|
280
412
|
spelling and then the standard variable. Azure credentials must come from your Azure resource.
|
|
281
413
|
|
|
414
|
+
You can also inject an in-memory key using the new keyword-only argument
|
|
415
|
+
`LLM(..., api_key=secret_value)`. This takes precedence over all environment
|
|
416
|
+
variables and works for existing providers too. Retrieve Key Vault secrets in
|
|
417
|
+
your application or notebook and pass the value; this package has no dependency
|
|
418
|
+
on a particular vault, Azure identity configuration or DataTeam filesystem path.
|
|
419
|
+
Do not store keys in configuration files or commit them to source control.
|
|
420
|
+
|
|
282
421
|
---
|
|
283
422
|
|
|
284
423
|
## Development
|
|
@@ -3,8 +3,10 @@
|
|
|
3
3
|
[](https://pypi.org/project/ehs-llm-client/)
|
|
4
4
|
[](https://www.python.org/downloads/)
|
|
5
5
|
|
|
6
|
-
`ehs-llm-client` is a unified **async Python client** for
|
|
7
|
-
|
|
6
|
+
`ehs-llm-client` is a unified **async Python client** for **OpenAI**, **Azure OpenAI**,
|
|
7
|
+
**Microsoft Foundry (AIF)**, **Google Gemini**, and **TypeSafe/Jev**.
|
|
8
|
+
It supports generative responses and native typed decisions. Provider batch APIs
|
|
9
|
+
remain available for supported generative deployments.
|
|
8
10
|
|
|
9
11
|
---
|
|
10
12
|
|
|
@@ -13,6 +15,7 @@ It supports **single calls**, **structured JSON outputs**, and **batch processin
|
|
|
13
15
|
- Async support for multiple LLM providers
|
|
14
16
|
- Unified interface across OpenAI, Azure, and Google Gemini
|
|
15
17
|
- Structured JSON responses via schemas
|
|
18
|
+
- Native `choice`, `noul` and `score` decisions via Foundry and TypeSafe
|
|
16
19
|
- Retry and timeout handling
|
|
17
20
|
- Batch processing support
|
|
18
21
|
- Environment variable configuration for API keys
|
|
@@ -128,6 +131,62 @@ v1 API; existing `api_version` settings are retained for compatibility and ignor
|
|
|
128
131
|
See [Azure Responses API documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/responses)
|
|
129
132
|
for supported models and regions.
|
|
130
133
|
|
|
134
|
+
### Microsoft Foundry (AIF) and TypeSafe
|
|
135
|
+
|
|
136
|
+
Version 0.2.0 adds two providers. Existing providers, credential precedence and
|
|
137
|
+
the `get_response_async()` positional arguments and return tuple are preserved.
|
|
138
|
+
|
|
139
|
+
| Provider | `api` | Method | Endpoint |
|
|
140
|
+
| --- | --- | --- | --- |
|
|
141
|
+
| `azure_foundry` | `responses` (default) | `get_response_async()` | `/openai/v1/responses` |
|
|
142
|
+
| `azure_foundry` | `systemone` | `decide_async()` | `/providers/microsoft/v1/systemone` |
|
|
143
|
+
| `typesafe` | `systemone` (default) | `decide_async()` | `https://api.typesafe.ai/v1/systemone` |
|
|
144
|
+
|
|
145
|
+
Select the API explicitly for Foundry decision deployments; deployment names do
|
|
146
|
+
not determine the protocol. This release supports these two APIs, rather than
|
|
147
|
+
every model/API in the Foundry catalog.
|
|
148
|
+
|
|
149
|
+
```ini
|
|
150
|
+
[foundry_gpt]
|
|
151
|
+
provider = azure_foundry
|
|
152
|
+
api = responses
|
|
153
|
+
model = gpt-6-luna
|
|
154
|
+
base_url = https://YOUR-RESOURCE.services.ai.azure.com
|
|
155
|
+
default_reasoning_effort = low
|
|
156
|
+
|
|
157
|
+
[foundry_decision]
|
|
158
|
+
provider = azure_foundry
|
|
159
|
+
api = systemone
|
|
160
|
+
model = decision-1
|
|
161
|
+
base_url = https://YOUR-RESOURCE.services.ai.azure.com
|
|
162
|
+
|
|
163
|
+
[typesafe_jev]
|
|
164
|
+
provider = typesafe
|
|
165
|
+
model = jev-latest
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
For Foundry, `model` is the **deployment name**. For TypeSafe, it is the model
|
|
169
|
+
name or alias. Foundry uses its own `AZURE_FOUNDRY_API_KEY` and
|
|
170
|
+
`AZURE_FOUNDRY_ENDPOINT`; it never falls back to Azure OpenAI credentials.
|
|
171
|
+
A configured `base_url` takes precedence over `LLM_BASE_URL`, then the
|
|
172
|
+
provider-specific endpoint variable. TypeSafe defaults to `https://api.typesafe.ai`;
|
|
173
|
+
an explicit `base_url` or environment-only `LLM_BASE_URL` can override it.
|
|
174
|
+
|
|
175
|
+
Foundry expects a resource endpoint, not an `/api/projects/...` URL. Responses
|
|
176
|
+
also accepts a full `/openai/v1/` endpoint. System One accepts the resource root,
|
|
177
|
+
its corresponding versioned API prefix, or its full System One endpoint.
|
|
178
|
+
These endpoints must use HTTPS and contain no query string, fragment or embedded
|
|
179
|
+
credentials. Selecting `azure_foundry` does not itself establish project billing
|
|
180
|
+
attribution; that depends on the Azure endpoint and service capabilities.
|
|
181
|
+
|
|
182
|
+
For environment-only configuration, set `LLM_PROVIDER`, `LLM_MODEL`, and
|
|
183
|
+
`LLM_API=systemone` for Foundry decision models, together with its endpoint/key.
|
|
184
|
+
TypeSafe needs `LLM_PROVIDER=typesafe`, `LLM_MODEL=jev-latest`, and
|
|
185
|
+
`TYPESAFE_API_KEY`.
|
|
186
|
+
|
|
187
|
+
See the [Microsoft Decision API](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/how-to/use-foundry-models-microsoft-decision)
|
|
188
|
+
and [TypeSafe System One API](https://docs.typesafe.ai/api/system-one).
|
|
189
|
+
|
|
131
190
|
---
|
|
132
191
|
|
|
133
192
|
## Usage
|
|
@@ -225,6 +284,76 @@ retry and timeout arguments. Prefer keyword arguments for clarity.
|
|
|
225
284
|
OpenAI/Azure JSON mode (`schema="return json"`) requires string message contents,
|
|
226
285
|
as in 0.1.10. Regular calls and schema-based output retain support for content arrays.
|
|
227
286
|
|
|
287
|
+
### Native typed decisions
|
|
288
|
+
|
|
289
|
+
Use the same questions with either a Foundry `systemone` section or a TypeSafe
|
|
290
|
+
section. State can be text, a JSON object or an array. Instructions and criteria
|
|
291
|
+
descriptions may also contain JSON structures.
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
import asyncio
|
|
295
|
+
from ehs_llm_client import LLM, ChoiceAnswer
|
|
296
|
+
|
|
297
|
+
async def main():
|
|
298
|
+
async with LLM("typesafe_jev", config_file_path="llmconfig.cfg") as model:
|
|
299
|
+
result = await model.decide_async(
|
|
300
|
+
state="A worker suffered a minor cut and received first aid.",
|
|
301
|
+
questions={
|
|
302
|
+
"category": {
|
|
303
|
+
"type": "choice",
|
|
304
|
+
"instructions": "Classify the reported incident.",
|
|
305
|
+
"criteria": {
|
|
306
|
+
"injury": "An injury occurred.",
|
|
307
|
+
"near_miss": "An event occurred without injury.",
|
|
308
|
+
"unknown": "There is insufficient information.",
|
|
309
|
+
},
|
|
310
|
+
},
|
|
311
|
+
"injured": {"type": "noul", "instructions": "Was anyone injured?"},
|
|
312
|
+
"severity": {
|
|
313
|
+
"type": "score",
|
|
314
|
+
"instructions": "Rate the reported outcome.",
|
|
315
|
+
"criteria": ["No injury", "Minor injury", "Serious injury"],
|
|
316
|
+
},
|
|
317
|
+
},
|
|
318
|
+
max_retries=3,
|
|
319
|
+
timeout=30,
|
|
320
|
+
)
|
|
321
|
+
answer = result.answers["category"]
|
|
322
|
+
if isinstance(answer, ChoiceAnswer):
|
|
323
|
+
print(answer.choice, answer.probabilities, answer.confidence)
|
|
324
|
+
print(result.model, result.usage.input_tokens, result.usage.output_tokens)
|
|
325
|
+
|
|
326
|
+
asyncio.run(main())
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
`DecisionResult` contains typed `ChoiceAnswer`, `NoulAnswer` and `ScoreAnswer`
|
|
330
|
+
objects, a resolved `model`, `DecisionUsage`, an optional `request_id`, and the
|
|
331
|
+
complete provider JSON in `raw_response`. Choice/score probabilities, confidence
|
|
332
|
+
and score legends are preserved when supplied; absent optional fields are `None`.
|
|
333
|
+
Noul is a probability from 0 to 1, not a boolean. Score is a number between zero
|
|
334
|
+
and the last criterion's index and can fall between levels. The library does not
|
|
335
|
+
choose thresholds, turn uncertainty into labels, or translate answers for EIDA.
|
|
336
|
+
|
|
337
|
+
Input and answer shapes, allowed labels, numeric ranges and token usage are
|
|
338
|
+
validated. Malformed successful responses raise `LLMResponseError`. HTTP failures
|
|
339
|
+
raise `LLMAPIError` (a subclass) with `status_code` and optional `request_id`;
|
|
340
|
+
error messages exclude provider response bodies. Inspect `raw_response` carefully
|
|
341
|
+
before logging it because provider extensions can contain sensitive information.
|
|
342
|
+
|
|
343
|
+
Decision calls retry transport failures, timeouts and HTTP 408, 429, 500, 502,
|
|
344
|
+
503, 504 and 529, honoring `Retry-After` and `retry-after-ms` when valid. Other HTTP
|
|
345
|
+
failures and invalid answers are not retried. As with the existing library API,
|
|
346
|
+
`max_retries` means **total attempts**, including the first request; `1` disables
|
|
347
|
+
retries. `timeout` is the limit for each attempt, so retries and backoff can make
|
|
348
|
+
the complete call longer. Cancellation propagates to the caller.
|
|
349
|
+
|
|
350
|
+
System One clients reject generative calls, provider batch operations,
|
|
351
|
+
`model_batch`, and `default_reasoning_effort`. Use concurrent `decide_async()`
|
|
352
|
+
calls for application-level parallelism. Generative clients reject `decide_async()`.
|
|
353
|
+
|
|
354
|
+
All providers support `async with LLM(...)` and `await llm.aclose()` to release
|
|
355
|
+
their clients. Keep a client open across repeated calls to reuse connections.
|
|
356
|
+
|
|
228
357
|
---
|
|
229
358
|
|
|
230
359
|
### Batch request
|
|
@@ -262,10 +391,19 @@ Keep API keys **out of code**. Recommended environment variables:
|
|
|
262
391
|
| OpenAI | `OPENAI_API_KEY` | `openaiAPIkey`, `openaiAPIKey` |
|
|
263
392
|
| Azure OpenAI | `AZURE_OPENAI_API_KEY` | `azure_openaiAPIkey`, `azure_openaiAPIKey` |
|
|
264
393
|
| Google Gemini | `GOOGLE_API_KEY` | `googleAPIkey`, `googleAPIKey` |
|
|
394
|
+
| Microsoft Foundry | `AZURE_FOUNDRY_API_KEY` | `azure_foundryAPIkey`, `azure_foundryAPIKey` |
|
|
395
|
+
| TypeSafe | `TYPESAFE_API_KEY` | `typesafeAPIkey`, `typesafeAPIKey` |
|
|
265
396
|
|
|
266
397
|
The 0.1.10 `APIKey` spelling takes precedence, followed by the older `APIkey`
|
|
267
398
|
spelling and then the standard variable. Azure credentials must come from your Azure resource.
|
|
268
399
|
|
|
400
|
+
You can also inject an in-memory key using the new keyword-only argument
|
|
401
|
+
`LLM(..., api_key=secret_value)`. This takes precedence over all environment
|
|
402
|
+
variables and works for existing providers too. Retrieve Key Vault secrets in
|
|
403
|
+
your application or notebook and pass the value; this package has no dependency
|
|
404
|
+
on a particular vault, Azure identity configuration or DataTeam filesystem path.
|
|
405
|
+
Do not store keys in configuration files or commit them to source control.
|
|
406
|
+
|
|
269
407
|
---
|
|
270
408
|
|
|
271
409
|
## Development
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
from .client import LLM
|
|
2
|
+
from .decisions import (
|
|
3
|
+
ChoiceQuestion, NoulQuestion, ScoreQuestion, DecisionQuestion,
|
|
4
|
+
ChoiceAnswer, NoulAnswer, ScoreAnswer, DecisionAnswer,
|
|
5
|
+
DecisionResult, DecisionUsage,
|
|
6
|
+
)
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"LLM", "ChoiceQuestion", "NoulQuestion", "ScoreQuestion", "DecisionQuestion",
|
|
10
|
+
"ChoiceAnswer", "NoulAnswer", "ScoreAnswer", "DecisionAnswer",
|
|
11
|
+
"DecisionResult", "DecisionUsage",
|
|
12
|
+
]
|
|
@@ -8,12 +8,14 @@ from typing import Any
|
|
|
8
8
|
|
|
9
9
|
import httpx
|
|
10
10
|
import openai
|
|
11
|
+
import httpx
|
|
11
12
|
from google import genai
|
|
12
13
|
from dotenv import load_dotenv
|
|
13
14
|
|
|
14
15
|
from .config import load_llm_config
|
|
15
16
|
from .utils import to_timestamp
|
|
16
|
-
from .exceptions import LLMProviderError, LLMResponseError
|
|
17
|
+
from .exceptions import LLMConfigError, LLMProviderError, LLMResponseError
|
|
18
|
+
from .decisions import DecisionClient, DecisionQuestion, DecisionResult
|
|
17
19
|
|
|
18
20
|
load_dotenv()
|
|
19
21
|
|
|
@@ -84,6 +86,8 @@ class LLM:
|
|
|
84
86
|
config_section_name: str,
|
|
85
87
|
config_file_path: str | None = None,
|
|
86
88
|
config: dict | None = None,
|
|
89
|
+
*,
|
|
90
|
+
api_key: str | None = None,
|
|
87
91
|
):
|
|
88
92
|
self.config_section_name = config_section_name
|
|
89
93
|
|
|
@@ -99,6 +103,7 @@ class LLM:
|
|
|
99
103
|
self.base_url = cfg.get("base_url")
|
|
100
104
|
self.api_version = cfg.get("api_version")
|
|
101
105
|
self.default_reasoning_effort = cfg.get("default_reasoning_effort")
|
|
106
|
+
self.api = (cfg.get("api") or ("systemone" if self.provider == "typesafe" else "responses")).strip().lower()
|
|
102
107
|
|
|
103
108
|
if not self.provider or not self.model:
|
|
104
109
|
raise ValueError("provider and model are required")
|
|
@@ -107,20 +112,33 @@ class LLM:
|
|
|
107
112
|
"openai": "OPENAI_API_KEY",
|
|
108
113
|
"azure_openai": "AZURE_OPENAI_API_KEY",
|
|
109
114
|
"google": "GOOGLE_API_KEY",
|
|
115
|
+
"azure_foundry": "AZURE_FOUNDRY_API_KEY",
|
|
116
|
+
"typesafe": "TYPESAFE_API_KEY",
|
|
110
117
|
}
|
|
111
118
|
if self.provider not in standard_key_env:
|
|
112
119
|
raise LLMProviderError(f"Unsupported provider: {self.provider}")
|
|
113
120
|
|
|
121
|
+
allowed_apis = {
|
|
122
|
+
"azure_foundry": {"responses", "systemone"},
|
|
123
|
+
"typesafe": {"systemone"},
|
|
124
|
+
}.get(self.provider, {"responses"})
|
|
125
|
+
if self.api not in allowed_apis:
|
|
126
|
+
raise LLMConfigError(f"Unsupported API mode for {self.provider}: {self.api}")
|
|
127
|
+
if self.api == "systemone" and (self.default_reasoning_effort or self.model_batch):
|
|
128
|
+
raise LLMConfigError("System One does not support default_reasoning_effort or model_batch")
|
|
129
|
+
|
|
114
130
|
# Preserve 0.1.10 credentials when multiple variable names are configured.
|
|
115
131
|
key_envs = (
|
|
116
132
|
f"{self.provider}APIKey",
|
|
117
133
|
f"{self.provider}APIkey",
|
|
118
134
|
standard_key_env[self.provider],
|
|
119
135
|
)
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
136
|
+
self.api_key = api_key
|
|
137
|
+
if api_key is None:
|
|
138
|
+
for key_env in key_envs:
|
|
139
|
+
self.api_key = os.getenv(key_env)
|
|
140
|
+
if self.api_key:
|
|
141
|
+
break
|
|
124
142
|
|
|
125
143
|
if not self.api_key:
|
|
126
144
|
raise ValueError(f"Missing API key env var: {' or '.join(key_envs)}")
|
|
@@ -129,6 +147,8 @@ class LLM:
|
|
|
129
147
|
self.base_url = (
|
|
130
148
|
self.base_url or os.getenv("LLM_BASE_URL") or os.getenv("AZURE_OPENAI_ENDPOINT")
|
|
131
149
|
)
|
|
150
|
+
elif self.provider == "azure_foundry":
|
|
151
|
+
self.base_url = self.base_url or os.getenv("LLM_BASE_URL") or os.getenv("AZURE_FOUNDRY_ENDPOINT")
|
|
132
152
|
|
|
133
153
|
self.client = self._init_client()
|
|
134
154
|
|
|
@@ -160,10 +180,39 @@ class LLM:
|
|
|
160
180
|
self._client = value
|
|
161
181
|
self._client_loop = None
|
|
162
182
|
|
|
183
|
+
def _require_responses(self) -> None:
|
|
184
|
+
if self.api == "systemone":
|
|
185
|
+
raise LLMProviderError("System One supports decide_async(); generative responses and provider batch operations are not supported")
|
|
186
|
+
|
|
187
|
+
async def decide_async(
|
|
188
|
+
self, state: str | dict | list, questions: dict[str, DecisionQuestion], *,
|
|
189
|
+
max_retries: int = 3, timeout: float = LLM_TIMEOUT,
|
|
190
|
+
) -> DecisionResult:
|
|
191
|
+
"""Return native typed answers. max_retries counts total attempts, as in get_response_async."""
|
|
192
|
+
if self.api != "systemone":
|
|
193
|
+
raise LLMProviderError("decide_async requires typesafe or azure_foundry with api=systemone")
|
|
194
|
+
return await self.client.decide_async(self.model, state, questions, max_retries=max_retries, timeout=timeout)
|
|
195
|
+
|
|
196
|
+
async def aclose(self) -> None:
|
|
197
|
+
"""Close the provider client owned by this LLM instance."""
|
|
198
|
+
if self.api == "systemone":
|
|
199
|
+
await self.client.aclose()
|
|
200
|
+
elif self.provider == "google":
|
|
201
|
+
await self.client.aio.aclose()
|
|
202
|
+
self.client.close()
|
|
203
|
+
else:
|
|
204
|
+
await self.client.close()
|
|
205
|
+
|
|
206
|
+
async def __aenter__(self):
|
|
207
|
+
return self
|
|
208
|
+
|
|
209
|
+
async def __aexit__(self, exc_type, exc_value, traceback):
|
|
210
|
+
await self.aclose()
|
|
211
|
+
|
|
163
212
|
def _supports_reasoning_effort(self) -> bool:
|
|
164
213
|
# Azure deployment names do not identify the underlying model. An
|
|
165
214
|
# explicitly configured effort must be passed through to that deployment.
|
|
166
|
-
if self.provider
|
|
215
|
+
if self.provider in {"azure_openai", "azure_foundry"}:
|
|
167
216
|
return True
|
|
168
217
|
model = (self.model or "").lower()
|
|
169
218
|
if len(model) >= 2 and model[0] == "o" and model[1].isdigit():
|
|
@@ -177,12 +226,20 @@ class LLM:
|
|
|
177
226
|
return False
|
|
178
227
|
|
|
179
228
|
def _init_client(self):
|
|
229
|
+
if self.api == "systemone":
|
|
230
|
+
return DecisionClient(self.provider, self.base_url, self.api_key)
|
|
180
231
|
if self.provider == "openai":
|
|
181
232
|
return openai.AsyncOpenAI(api_key=self.api_key, http_client=_http_client())
|
|
182
233
|
|
|
183
|
-
if self.provider
|
|
234
|
+
if self.provider in {"azure_openai", "azure_foundry"}:
|
|
184
235
|
if not self.base_url:
|
|
185
|
-
|
|
236
|
+
endpoint_env = "AZURE_FOUNDRY_ENDPOINT" if self.provider == "azure_foundry" else "AZURE_OPENAI_ENDPOINT"
|
|
237
|
+
raise ValueError(f"{self.provider} requires base_url or {endpoint_env}")
|
|
238
|
+
if self.provider == "azure_foundry":
|
|
239
|
+
url = httpx.URL(self.base_url)
|
|
240
|
+
if (url.scheme != "https" or not url.host or url.username or url.password
|
|
241
|
+
or url.query or url.fragment or url.path.rstrip("/") not in {"", "/openai", "/openai/v1"}):
|
|
242
|
+
raise LLMConfigError("Foundry Responses requires an HTTPS resource root or /openai/v1/ endpoint; project URLs are not supported")
|
|
186
243
|
endpoint = self.base_url.rstrip("/")
|
|
187
244
|
if endpoint.endswith("/openai"):
|
|
188
245
|
endpoint += "/v1"
|
|
@@ -248,6 +305,7 @@ class LLM:
|
|
|
248
305
|
self, messages: list[dict[str, str]], schema: dict | str = None,
|
|
249
306
|
reasoning_effort: str | None = None,
|
|
250
307
|
) -> Any:
|
|
308
|
+
self._require_responses()
|
|
251
309
|
if reasoning_effort is None:
|
|
252
310
|
reasoning_effort = self.default_reasoning_effort
|
|
253
311
|
# 1. Handle Google Provider
|
|
@@ -282,7 +340,7 @@ class LLM:
|
|
|
282
340
|
)
|
|
283
341
|
|
|
284
342
|
# 2. Handle OpenAI / Azure Provider
|
|
285
|
-
elif self.provider in ['openai', 'azure_openai']:
|
|
343
|
+
elif self.provider in ['openai', 'azure_openai', 'azure_foundry']:
|
|
286
344
|
api_kwargs = self._response_payload(messages, schema, self.model)
|
|
287
345
|
if reasoning_effort and self._supports_reasoning_effort():
|
|
288
346
|
api_kwargs["reasoning"] = {"effort": reasoning_effort}
|
|
@@ -293,6 +351,7 @@ class LLM:
|
|
|
293
351
|
reasoning_effort: str | None = None, max_retries: int = 3,
|
|
294
352
|
timeout: int = LLM_TIMEOUT,
|
|
295
353
|
):
|
|
354
|
+
self._require_responses()
|
|
296
355
|
if reasoning_effort is None:
|
|
297
356
|
reasoning_effort = self.default_reasoning_effort
|
|
298
357
|
if max_retries < 1:
|
|
@@ -322,7 +381,7 @@ class LLM:
|
|
|
322
381
|
in_tokens = response.usage_metadata.prompt_token_count
|
|
323
382
|
out_tokens = response.usage_metadata.candidates_token_count
|
|
324
383
|
|
|
325
|
-
elif self.provider
|
|
384
|
+
elif self.provider in {"openai", "azure_openai", "azure_foundry"}:
|
|
326
385
|
# --- OPENAI PARSING ---
|
|
327
386
|
self._validate_response(response)
|
|
328
387
|
|
|
@@ -368,9 +427,10 @@ class LLM:
|
|
|
368
427
|
Generates a request dictionary for a Batch API JSONL file.
|
|
369
428
|
Matches the logic of call_async by supporting multi-turn messages and system instructions.
|
|
370
429
|
"""
|
|
430
|
+
self._require_responses()
|
|
371
431
|
provider = self.provider.lower()
|
|
372
432
|
|
|
373
|
-
if provider
|
|
433
|
+
if provider in {"openai", "azure_openai", "azure_foundry"}:
|
|
374
434
|
return {
|
|
375
435
|
"custom_id": custom_id,
|
|
376
436
|
"method": "POST",
|
|
@@ -426,6 +486,7 @@ class LLM:
|
|
|
426
486
|
Unified function to upload and start a batch job.
|
|
427
487
|
Returns the batch_id (OpenAI/Azure) or batch_name (Google).
|
|
428
488
|
"""
|
|
489
|
+
self._require_responses()
|
|
429
490
|
if not batch_lines:
|
|
430
491
|
return None
|
|
431
492
|
|
|
@@ -435,7 +496,7 @@ class LLM:
|
|
|
435
496
|
)
|
|
436
497
|
provider = self.provider.lower()
|
|
437
498
|
|
|
438
|
-
if provider in {"openai", "azure_openai"}:
|
|
499
|
+
if provider in {"openai", "azure_openai", "azure_foundry"}:
|
|
439
500
|
# 1. Upload a named JSONL file to OpenAI or Azure.
|
|
440
501
|
batch_file = await self.client.files.create(
|
|
441
502
|
file=("batch.jsonl", file_content_str.encode('utf-8'), "application/jsonl"),
|
|
@@ -446,7 +507,7 @@ class LLM:
|
|
|
446
507
|
# Azure determines the actual API from the URLs in the JSONL file.
|
|
447
508
|
batch_job = await self.client.batches.create(
|
|
448
509
|
input_file_id=file_id,
|
|
449
|
-
endpoint="/chat/completions" if provider
|
|
510
|
+
endpoint="/chat/completions" if provider in {"azure_openai", "azure_foundry"} else "/v1/responses",
|
|
450
511
|
completion_window="24h"
|
|
451
512
|
)
|
|
452
513
|
return batch_job.id
|
|
@@ -478,6 +539,7 @@ class LLM:
|
|
|
478
539
|
|
|
479
540
|
|
|
480
541
|
async def cancel_batch(self,batch_id):
|
|
542
|
+
self._require_responses()
|
|
481
543
|
try:
|
|
482
544
|
await self.client.batches.cancel(batch_id)
|
|
483
545
|
return True
|
|
@@ -491,9 +553,10 @@ class LLM:
|
|
|
491
553
|
Downloads the result file content as a string.
|
|
492
554
|
Works for OpenAI, Azure OpenAI and Google Gemini.
|
|
493
555
|
"""
|
|
556
|
+
self._require_responses()
|
|
494
557
|
provider = self.provider.lower()
|
|
495
558
|
|
|
496
|
-
if provider in {"openai", "azure_openai"}:
|
|
559
|
+
if provider in {"openai", "azure_openai", "azure_foundry"}:
|
|
497
560
|
# OpenAI returns a response object; we must read and decode it
|
|
498
561
|
result_content = await self.client.files.content(output_file_id)
|
|
499
562
|
# result_content.read() returns bytes
|
|
@@ -513,9 +576,10 @@ class LLM:
|
|
|
513
576
|
raise ValueError(f"Unsupported provider: {provider}")
|
|
514
577
|
|
|
515
578
|
async def get_batch_status(self, batch_id: str):
|
|
579
|
+
self._require_responses()
|
|
516
580
|
provider = self.provider.lower()
|
|
517
581
|
|
|
518
|
-
if provider in {"openai", "azure_openai"}:
|
|
582
|
+
if provider in {"openai", "azure_openai", "azure_foundry"}:
|
|
519
583
|
job = await self.client.batches.retrieve(batch_id)
|
|
520
584
|
# OpenAI property: job.request_counts
|
|
521
585
|
total = job.request_counts.total if job.request_counts else 0
|