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.
@@ -1,9 +1,10 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ehs-llm-client
3
- Version: 0.1.15
4
- Summary: Unified LLM client. Currently supports Openai, Azure Openai and Google Gemini
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
  [![PyPI version](https://img.shields.io/pypi/v/ehs-llm-client)](https://pypi.org/project/ehs-llm-client/)
17
18
  [![Python Version](https://img.shields.io/pypi/pyversions/ehs-llm-client)](https://www.python.org/downloads/)
18
19
 
19
- `ehs-llm-client` is a unified **async Python client** for interacting with multiple LLM providers, including **OpenAI**, **Azure OpenAI**, and **Google Gemini**.
20
- It supports **single calls**, **structured JSON outputs**, and **batch processing**, designed for **production-ready, reusable code** in applications, scripts, or pipelines.
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
  [![PyPI version](https://img.shields.io/pypi/v/ehs-llm-client)](https://pypi.org/project/ehs-llm-client/)
4
4
  [![Python Version](https://img.shields.io/pypi/pyversions/ehs-llm-client)](https://www.python.org/downloads/)
5
5
 
6
- `ehs-llm-client` is a unified **async Python client** for interacting with multiple LLM providers, including **OpenAI**, **Azure OpenAI**, and **Google Gemini**.
7
- It supports **single calls**, **structured JSON outputs**, and **batch processing**, designed for **production-ready, reusable code** in applications, scripts, or pipelines.
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
- for key_env in key_envs:
121
- self.api_key = os.getenv(key_env)
122
- if self.api_key:
123
- break
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 == "azure_openai":
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 == "azure_openai":
234
+ if self.provider in {"azure_openai", "azure_foundry"}:
184
235
  if not self.base_url:
185
- raise ValueError("Azure OpenAI requires base_url or AZURE_OPENAI_ENDPOINT")
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 == "openai" or self.provider == "azure_openai":
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 == "openai" or provider == "azure_openai":
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 == "azure_openai" else "/v1/responses",
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
@@ -39,6 +39,7 @@ def load_llm_config(
39
39
 
40
40
  return {
41
41
  "provider": provider,
42
+ "api": os.getenv("LLM_API"),
42
43
  "model": model,
43
44
  "model_batch": os.getenv("LLM_MODEL_BATCH"),
44
45
  "base_url": os.getenv("LLM_BASE_URL"),