sofias-sdk-lite 0.1.3__tar.gz → 0.1.5__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.

Potentially problematic release.


This version of sofias-sdk-lite might be problematic. Click here for more details.

Files changed (82) hide show
  1. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/PKG-INFO +52 -11
  2. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/README.md +50 -10
  3. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/pyproject.toml +2 -1
  4. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/pyproject.toml.orig +2 -1
  5. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/__init__.py +17 -0
  6. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/agent_builder.py +28 -4
  7. sofias_sdk_lite-0.1.5/src/sofias_sdk_lite/config/agent_settings.py +112 -0
  8. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/errors/__init__.py +6 -0
  9. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/errors/exceptions.py +60 -0
  10. sofias_sdk_lite-0.1.5/src/sofias_sdk_lite/llm/__init__.py +72 -0
  11. sofias_sdk_lite-0.1.5/src/sofias_sdk_lite/llm/bifrost.py +135 -0
  12. sofias_sdk_lite-0.1.5/src/sofias_sdk_lite/llm/factory.py +297 -0
  13. sofias_sdk_lite-0.1.5/src/sofias_sdk_lite/llm/openai_compatible.py +522 -0
  14. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/llm/protocol.py +14 -6
  15. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/llm_node.py +67 -0
  16. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/runner/runner.py +32 -1
  17. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/tools.py +39 -2
  18. sofias_sdk_lite-0.1.3/src/sofias_sdk_lite/config/agent_settings.py +0 -90
  19. sofias_sdk_lite-0.1.3/src/sofias_sdk_lite/llm/__init__.py +0 -27
  20. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/__init__.py +0 -0
  21. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/agent.py +0 -0
  22. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/agent_config.py +0 -0
  23. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/execution_context.py +0 -0
  24. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/middleware.py +0 -0
  25. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/response_workflow.py +0 -0
  26. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/agent/streaming.py +0 -0
  27. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/config/__init__.py +0 -0
  28. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/config/defaults.py +0 -0
  29. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/config/runtime_config.py +0 -0
  30. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/config/sdk_config.py +0 -0
  31. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/config/source.py +0 -0
  32. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/contracts/__init__.py +0 -0
  33. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/contracts/agent_contracts.py +0 -0
  34. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/contracts/base_contracts.py +0 -0
  35. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/contracts/node_contracts.py +0 -0
  36. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/contracts/strict_contract.py +0 -0
  37. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/errors/circuit_breaker.py +0 -0
  38. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/errors/error_handler.py +0 -0
  39. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/llm/tokens.py +0 -0
  40. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/llm/tools.py +0 -0
  41. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/messaging/__init__.py +0 -0
  42. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/messaging/models.py +0 -0
  43. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/__init__.py +0 -0
  44. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/aggregator_config.py +0 -0
  45. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/aggregator_node.py +0 -0
  46. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/base_node.py +0 -0
  47. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/delegation_config.py +0 -0
  48. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/delegation_node.py +0 -0
  49. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/delegation_transport.py +0 -0
  50. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/function_node.py +0 -0
  51. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/llm_node_config.py +0 -0
  52. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/plan_executor.py +0 -0
  53. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/planner_node.py +0 -0
  54. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/planning_models.py +0 -0
  55. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/nodes/prompt_assembler.py +0 -0
  56. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/observability/__init__.py +0 -0
  57. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/observability/_log.py +0 -0
  58. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/observability/events.py +0 -0
  59. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/observability/trace_context.py +0 -0
  60. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/observability/tracing.py +0 -0
  61. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/py.typed +0 -0
  62. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/__init__.py +0 -0
  63. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/client.py +0 -0
  64. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/config.py +0 -0
  65. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/consumer.py +0 -0
  66. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/delegation_transport.py +0 -0
  67. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/publisher.py +0 -0
  68. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/rpc_client.py +0 -0
  69. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/rabbitmq/types.py +0 -0
  70. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/routing/__init__.py +0 -0
  71. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/routing/router.py +0 -0
  72. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/routing/strategies.py +0 -0
  73. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/runner/__init__.py +0 -0
  74. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/runner/config.py +0 -0
  75. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/state/__init__.py +0 -0
  76. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/state/conversation_state.py +0 -0
  77. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/state/history.py +0 -0
  78. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/state/memory.py +0 -0
  79. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/workflows/__init__.py +0 -0
  80. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/workflows/chat.py +0 -0
  81. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/workflows/null.py +0 -0
  82. {sofias_sdk_lite-0.1.3 → sofias_sdk_lite-0.1.5}/src/sofias_sdk_lite/workflows/streaming_chat.py +0 -0
@@ -1,12 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sofias-sdk-lite
3
- Version: 0.1.3
3
+ Version: 0.1.5
4
4
  Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
5
5
  License-Expression: Apache-2.0
6
6
  Requires-Dist: pydantic>=2.0
7
7
  Requires-Dist: aio-pika>=9.0.0
8
8
  Requires-Dist: rstream>=1.0.0
9
9
  Requires-Dist: nh3>=0.3.6
10
+ Requires-Dist: httpx>=0.27.0
10
11
  Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
11
12
  Requires-Dist: mkdocstrings[python]>=0.25 ; extra == 'docs'
12
13
  Requires-Dist: opentelemetry-api>=1.20.0 ; extra == 'otel'
@@ -30,12 +31,14 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
30
31
  - **A runner** — `AgentRunner` consumes tasks from a queue, resolves per-request
31
32
  settings, executes your agent, and streams the response back — with graceful
32
33
  shutdown, retries, and circuit breakers built in.
33
- - **Bring your own LLM** — `LLMCallable` is a protocol. Wrap any HTTP client,
34
- local model, or provider SDK in ~15 lines; no vendor lock-in.
34
+ - **An LLM that is already wired** — LLM nodes talk to the Sofias Bifrost
35
+ gateway (or any OpenAI-compatible endpoint) using the model, URL and key
36
+ from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
37
+ builds the client when you need it explicitly; `LLMCallable` stays a protocol
38
+ for anything the bundled clients do not cover.
35
39
 
36
- Nothing here depends on a private backend, an internal config service, or a
37
- specific LLM vendor. Everything infrastructure-specific is a constructor
38
- argument or a protocol you implement yourself.
40
+ Nothing here depends on a private backend or an internal config service.
41
+ Where the model lives is deployment configuration, not agent code.
39
42
 
40
43
  ## Install
41
44
 
@@ -105,6 +108,44 @@ See [`examples/`](examples/) for a runner against a local RabbitMQ
105
108
  (`docker-compose.yml` included), tool loops, streaming, and agent-to-agent
106
109
  delegation.
107
110
 
111
+ ## Connecting to the LLM
112
+
113
+ An agent declares *what* the model should do; *where* the model lives is
114
+ resolved at `build()`:
115
+
116
+ 1. Under `AgentRunner`, from the per-task settings the platform sends
117
+ (`model_name`, `router_url`, `router_api_key` on `BaseAgentSettings`).
118
+ 2. Otherwise from the environment: `SOFIAS_LLM_MODEL`, `SOFIAS_LLM_BASE_URL`
119
+ (default `http://bifrost:8080/v1`), `SOFIAS_LLM_API_KEY`,
120
+ `SOFIAS_LLM_PROVIDER` (default `bifrost`). The `BIFROST_MODEL` /
121
+ `BIFROST_BASE_URL` / `BIFROST_API_KEY` variables the Sofias Developer
122
+ Portal injects into agent containers are accepted as fallbacks, so a
123
+ portal-deployed agent needs no LLM configuration at all.
124
+ 3. Or explicitly: `.with_llm(create_llm(model="default", api_key=...))`.
125
+
126
+ ```python
127
+ from sofias_sdk_lite import AgentBuilder, LLMNodeConfig, NodeContract
128
+
129
+ agent = (
130
+ AgentBuilder("qa_agent")
131
+ .with_settings_class(MySettings)
132
+ .with_contract(input_schema=Question, output_schema=Answer)
133
+ .add_llm_node(
134
+ "answerer",
135
+ LLMNodeConfig(name="answerer", input_contract=Question, output_contract=Answer,
136
+ system_prompt="Answer in one sentence."),
137
+ NodeContract(input_schema=Question, output_schema=Answer),
138
+ )
139
+ .set_entry_node("answerer")
140
+ .set_terminal("answerer")
141
+ .build() # no LLM client anywhere in this file
142
+ )
143
+ ```
144
+
145
+ See `examples/03_llm_agent.py` and the
146
+ [LLM integration](docs/concepts/llm-integration.md) guide (streaming,
147
+ retries, bringing your own client).
148
+
108
149
  ## Running an agent against RabbitMQ
109
150
 
110
151
  ```python
@@ -149,11 +190,11 @@ if __name__ == "__main__":
149
190
 
150
191
  ## Scope (v1)
151
192
 
152
- Core agent graph, RabbitMQ messaging, and the runner ship today. Memory,
153
- MCP tool discovery, and LLM adapter implementations are intentionally out
154
- of scope for v1 — the SDK ships the relevant protocols
155
- (`MemoryProvider`, `ToolProvider`, `LLMCallable`) so you can plug in your
156
- own, and these become optional extras in a later release.
193
+ Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
194
+ Bifrost gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
195
+ tool discovery are intentionally out of scope for v1 — the SDK ships the
196
+ relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
197
+ your own, and these become optional extras in a later release.
157
198
 
158
199
  ## License
159
200
 
@@ -13,12 +13,14 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
13
13
  - **A runner** — `AgentRunner` consumes tasks from a queue, resolves per-request
14
14
  settings, executes your agent, and streams the response back — with graceful
15
15
  shutdown, retries, and circuit breakers built in.
16
- - **Bring your own LLM** — `LLMCallable` is a protocol. Wrap any HTTP client,
17
- local model, or provider SDK in ~15 lines; no vendor lock-in.
16
+ - **An LLM that is already wired** — LLM nodes talk to the Sofias Bifrost
17
+ gateway (or any OpenAI-compatible endpoint) using the model, URL and key
18
+ from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
19
+ builds the client when you need it explicitly; `LLMCallable` stays a protocol
20
+ for anything the bundled clients do not cover.
18
21
 
19
- Nothing here depends on a private backend, an internal config service, or a
20
- specific LLM vendor. Everything infrastructure-specific is a constructor
21
- argument or a protocol you implement yourself.
22
+ Nothing here depends on a private backend or an internal config service.
23
+ Where the model lives is deployment configuration, not agent code.
22
24
 
23
25
  ## Install
24
26
 
@@ -88,6 +90,44 @@ See [`examples/`](examples/) for a runner against a local RabbitMQ
88
90
  (`docker-compose.yml` included), tool loops, streaming, and agent-to-agent
89
91
  delegation.
90
92
 
93
+ ## Connecting to the LLM
94
+
95
+ An agent declares *what* the model should do; *where* the model lives is
96
+ resolved at `build()`:
97
+
98
+ 1. Under `AgentRunner`, from the per-task settings the platform sends
99
+ (`model_name`, `router_url`, `router_api_key` on `BaseAgentSettings`).
100
+ 2. Otherwise from the environment: `SOFIAS_LLM_MODEL`, `SOFIAS_LLM_BASE_URL`
101
+ (default `http://bifrost:8080/v1`), `SOFIAS_LLM_API_KEY`,
102
+ `SOFIAS_LLM_PROVIDER` (default `bifrost`). The `BIFROST_MODEL` /
103
+ `BIFROST_BASE_URL` / `BIFROST_API_KEY` variables the Sofias Developer
104
+ Portal injects into agent containers are accepted as fallbacks, so a
105
+ portal-deployed agent needs no LLM configuration at all.
106
+ 3. Or explicitly: `.with_llm(create_llm(model="default", api_key=...))`.
107
+
108
+ ```python
109
+ from sofias_sdk_lite import AgentBuilder, LLMNodeConfig, NodeContract
110
+
111
+ agent = (
112
+ AgentBuilder("qa_agent")
113
+ .with_settings_class(MySettings)
114
+ .with_contract(input_schema=Question, output_schema=Answer)
115
+ .add_llm_node(
116
+ "answerer",
117
+ LLMNodeConfig(name="answerer", input_contract=Question, output_contract=Answer,
118
+ system_prompt="Answer in one sentence."),
119
+ NodeContract(input_schema=Question, output_schema=Answer),
120
+ )
121
+ .set_entry_node("answerer")
122
+ .set_terminal("answerer")
123
+ .build() # no LLM client anywhere in this file
124
+ )
125
+ ```
126
+
127
+ See `examples/03_llm_agent.py` and the
128
+ [LLM integration](docs/concepts/llm-integration.md) guide (streaming,
129
+ retries, bringing your own client).
130
+
91
131
  ## Running an agent against RabbitMQ
92
132
 
93
133
  ```python
@@ -132,11 +172,11 @@ if __name__ == "__main__":
132
172
 
133
173
  ## Scope (v1)
134
174
 
135
- Core agent graph, RabbitMQ messaging, and the runner ship today. Memory,
136
- MCP tool discovery, and LLM adapter implementations are intentionally out
137
- of scope for v1 — the SDK ships the relevant protocols
138
- (`MemoryProvider`, `ToolProvider`, `LLMCallable`) so you can plug in your
139
- own, and these become optional extras in a later release.
175
+ Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
176
+ Bifrost gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
177
+ tool discovery are intentionally out of scope for v1 — the SDK ships the
178
+ relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
179
+ your own, and these become optional extras in a later release.
140
180
 
141
181
  ## License
142
182
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "sofias-sdk-lite"
3
- version = "0.1.3"
3
+ version = "0.1.5"
4
4
  description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -10,6 +10,7 @@ dependencies = [
10
10
  "aio-pika>=9.0.0",
11
11
  "rstream>=1.0.0",
12
12
  "nh3>=0.3.6",
13
+ "httpx>=0.27.0",
13
14
  ]
14
15
 
15
16
  [project.optional-dependencies]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "sofias-sdk-lite"
3
- version = "0.1.3"
3
+ version = "0.1.5"
4
4
  description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -10,6 +10,7 @@ dependencies = [
10
10
  "aio-pika>=9.0.0",
11
11
  "rstream>=1.0.0",
12
12
  "nh3>=0.3.6",
13
+ "httpx>=0.27.0",
13
14
  ]
14
15
 
15
16
  [project.optional-dependencies]
@@ -76,6 +76,9 @@ from sofias_sdk_lite.errors import (
76
76
  AgentSDKError,
77
77
  CircuitBreakerConfig,
78
78
  ConfigSourceError,
79
+ EmptyLLMResponseError,
80
+ LLMConfigurationError,
81
+ LLMRequestError,
79
82
  ContractValidationError,
80
83
  ErrorHandler,
81
84
  ErrorHandlerConfig,
@@ -88,9 +91,14 @@ from sofias_sdk_lite.errors import (
88
91
  ToolExecutionError,
89
92
  )
90
93
  from sofias_sdk_lite.llm import (
94
+ BifrostLLM,
91
95
  LLMCallable,
96
+ LLMGatewayConfig,
92
97
  LLMResponse,
98
+ OpenAICompatibleLLM,
93
99
  StreamableLLMCallable,
100
+ create_llm,
101
+ default_llm,
94
102
  TokenUsage,
95
103
  ToolCall,
96
104
  ToolSpec,
@@ -210,6 +218,9 @@ __all__ = [
210
218
  "ToolExecutionError",
211
219
  "GraphExecutionError",
212
220
  "ConfigSourceError",
221
+ "EmptyLLMResponseError",
222
+ "LLMConfigurationError",
223
+ "LLMRequestError",
213
224
  "ErrorHandler",
214
225
  "ErrorHandlerConfig",
215
226
  "RetryPolicy",
@@ -218,6 +229,12 @@ __all__ = [
218
229
  "LLMCallable",
219
230
  "StreamableLLMCallable",
220
231
  "LLMResponse",
232
+ # LLM clients + factory
233
+ "BifrostLLM",
234
+ "OpenAICompatibleLLM",
235
+ "LLMGatewayConfig",
236
+ "create_llm",
237
+ "default_llm",
221
238
  "TokenUsage",
222
239
  "ToolCall",
223
240
  "ToolSpec",
@@ -24,6 +24,7 @@ from sofias_sdk_lite.errors.error_handler import (
24
24
  )
25
25
  from sofias_sdk_lite.errors.exceptions import AgentSDKError
26
26
  from sofias_sdk_lite.llm import LLMCallable
27
+ from sofias_sdk_lite.llm.factory import ENV_LLM_MODEL, resolve_default_llm
27
28
  from sofias_sdk_lite.nodes.aggregator_config import AggregatorNodeConfig
28
29
  from sofias_sdk_lite.nodes.base_node import BaseNode
29
30
  from sofias_sdk_lite.nodes.delegation_config import DelegationNodeConfig
@@ -230,9 +231,21 @@ class AgentBuilder:
230
231
  self._output_schema = output_schema
231
232
  return self
232
233
 
234
+ _MISSING_LLM_MESSAGE = (
235
+ "No LLM available for LLM nodes. Either call with_llm(), run the agent through "
236
+ "AgentRunner with model_name/router_url/router_api_key in its settings, or export "
237
+ f"{ENV_LLM_MODEL} (plus SOFIAS_LLM_BASE_URL / SOFIAS_LLM_API_KEY)."
238
+ )
239
+
233
240
  def with_llm(self, llm: LLMCallable) -> AgentBuilder:
234
241
  """Set the LLM callable for all LLM nodes.
235
242
 
243
+ Optional. When omitted, `build()` uses the LLM installed by
244
+ `sofias_sdk_lite.llm.default_llm` (what `AgentRunner` does with the
245
+ per-task settings) or, failing that, one built from the
246
+ ``SOFIAS_LLM_*`` environment variables via
247
+ `sofias_sdk_lite.llm.create_llm`.
248
+
236
249
  Args:
237
250
  llm: LLM implementation for making completions.
238
251
 
@@ -242,6 +255,12 @@ class AgentBuilder:
242
255
  self._llm = llm
243
256
  return self
244
257
 
258
+ def _needs_agent_llm(self) -> bool:
259
+ """Whether any node still to be built relies on the agent-level LLM."""
260
+ if self._llm_node_configs:
261
+ return True
262
+ return any(cfg["llm"] is None for cfg in self._planner_node_configs.values())
263
+
245
264
  def with_agent_llm_config(self, config: AgentLLMConfig) -> AgentBuilder:
246
265
  """Set agent-level LLM configuration.
247
266
 
@@ -899,9 +918,9 @@ class AgentBuilder:
899
918
  )
900
919
  errors.extend(graph_errors)
901
920
 
902
- # LLM must be provided if there are LLM nodes to be built (not pre-built)
921
+ # LLM must be resolvable if there are LLM nodes to be built (not pre-built)
903
922
  if self._llm_node_configs and self._llm is None:
904
- errors.append("LLM not provided but LLM nodes need to be built. Use with_llm() to set the LLM callable.")
923
+ errors.append(self._MISSING_LLM_MESSAGE)
905
924
 
906
925
  # Delegation transport must be provided if there are delegation nodes
907
926
  if self._delegation_node_configs and self._delegation_transport is None:
@@ -941,8 +960,8 @@ class AgentBuilder:
941
960
  for name, config in self._planner_node_configs.items():
942
961
  if config["llm"] is None and self._llm is None:
943
962
  errors.append(
944
- f"PlannerNode '{name}' has no LLM and no agent-level LLM is set. "
945
- "Use with_llm() or provide llm to add_planner_node()."
963
+ f"PlannerNode '{name}' has no LLM and no agent-level LLM could be "
964
+ f"resolved. {self._MISSING_LLM_MESSAGE}"
946
965
  )
947
966
 
948
967
  # Validate available_nodes references
@@ -1016,6 +1035,11 @@ class AgentBuilder:
1016
1035
  # Apply default routes before validation
1017
1036
  self._apply_default_routes()
1018
1037
 
1038
+ # Resolve the agent-level LLM when none was given explicitly: the
1039
+ # runner's per-task default (from settings) first, then the environment.
1040
+ if self._llm is None and self._needs_agent_llm():
1041
+ self._llm = resolve_default_llm()
1042
+
1019
1043
  # Validate configuration
1020
1044
  errors = self._validate()
1021
1045
  if errors:
@@ -0,0 +1,112 @@
1
+ """Base class for agent runtime settings.
2
+
3
+ `BaseAgentSettings` carries the platform's LLM gateway keys (``model_name``,
4
+ ``router_url``, ``router_api_key``) so `AgentRunner` can build the LLM
5
+ client for each task without the agent author wiring anything. Every other
6
+ concern (embeddings, vector stores, object storage, search backends) is left
7
+ to the concrete agent, which subclasses and declares what it needs:
8
+
9
+ class MyAgentSettings(BaseAgentSettings):
10
+ custom_field: str = "default"
11
+
12
+ The gateway fields are optional: an agent made only of function nodes never
13
+ touches an LLM, and `AgentBuilder` falls back to the environment
14
+ (``SOFIAS_LLM_MODEL`` & co.) when settings do not name a model.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import difflib
20
+ from typing import Any, ClassVar
21
+
22
+ from pydantic import ConfigDict, SecretStr, model_validator
23
+
24
+ from sofias_sdk_lite.config.runtime_config import AgentSettings
25
+ from sofias_sdk_lite.observability._log import get_logger
26
+
27
+ logger = get_logger("config.agent_settings")
28
+
29
+
30
+ class BaseAgentSettings(AgentSettings):
31
+ """Runtime settings shared by all agents.
32
+
33
+ Carries the LLM gateway keys the Sofias platform injects per task
34
+ (``model_name``, ``router_url``, ``router_api_key``). `AgentRunner` reads
35
+ them through `sofias_sdk_lite.llm.create_llm` and installs the resulting
36
+ client as the default for `AgentBuilder.build()`, so agent code only
37
+ declares LLM nodes and never constructs a client.
38
+
39
+ All three are optional here so function-only agents validate with an
40
+ empty payload; `has_llm_gateway` tells whether a model was supplied.
41
+
42
+ Subclass to add agent-specific fields — feature flags, downstream
43
+ service URLs, or anything else a given agent depends on.
44
+ """
45
+
46
+ model_config = ConfigDict(extra="ignore", validate_default=True)
47
+
48
+ CREDENTIAL_FIELDS: ClassVar[frozenset[str]] = frozenset({"router_api_key"})
49
+ """Names of fields that hold credentials (API keys, tokens, secrets).
50
+
51
+ Extend on your subclass (``BaseAgentSettings.CREDENTIAL_FIELDS | {...}``),
52
+ typing the fields as ``pydantic.SecretStr`` so ``repr``/``model_dump``
53
+ never leak the raw value. The SDK excludes these fields wherever settings
54
+ are dumped into a dict that reaches an LLM prompt (``LLMNode`` template
55
+ variables), so a ``{api_key}`` placeholder can never inline a secret. Read
56
+ them at the point of use with ``.get_secret_value()``.
57
+
58
+ Example::
59
+
60
+ class MySettings(BaseAgentSettings):
61
+ CREDENTIAL_FIELDS = BaseAgentSettings.CREDENTIAL_FIELDS | {"search_api_key"}
62
+
63
+ search_api_key: SecretStr = SecretStr("")
64
+ """
65
+
66
+ # --- LLM gateway (canonical platform keys) ---
67
+ model_name: str = ""
68
+ """Model identifier or gateway alias. Empty means "no LLM configured here"."""
69
+
70
+ router_url: str = ""
71
+ """OpenAI-compatible gateway root. Empty falls back to the in-cluster Bifrost URL."""
72
+
73
+ router_api_key: SecretStr = SecretStr("")
74
+ """Gateway bearer token. Empty sends unauthenticated requests."""
75
+
76
+ router_provider: str = ""
77
+ """Adapter flavour: ``"bifrost"`` (default when empty) or an OpenAI-compatible label."""
78
+
79
+ @property
80
+ def has_llm_gateway(self) -> bool:
81
+ """Whether these settings name a model (and therefore can build an LLM)."""
82
+ return bool(self.model_name)
83
+
84
+ @model_validator(mode="before")
85
+ @classmethod
86
+ def _warn_on_typo_keys(cls, data: Any) -> Any:
87
+ """Emit a warning for unknown keys that look like typos of declared fields.
88
+
89
+ `extra="ignore"` silently drops misspelled keys (e.g. `mdoel_name`
90
+ instead of `model_name`), which can lead to confusing "missing
91
+ configuration" errors later on. `extra="ignore"` is kept for
92
+ forward-compatibility with unrelated payload keys, but a warning is
93
+ logged whenever an unknown key is suspiciously close to a field
94
+ declared on the concrete subclass.
95
+ """
96
+ if not isinstance(data, dict):
97
+ return data
98
+ known = set(cls.model_fields.keys())
99
+ for key in data:
100
+ if not isinstance(key, str) or key in known:
101
+ continue
102
+ close = difflib.get_close_matches(key, known, n=1, cutoff=0.85)
103
+ if close:
104
+ logger.warning(
105
+ "Unknown settings key is being ignored; possible typo",
106
+ key=key,
107
+ suggestion=close[0],
108
+ )
109
+ return data
110
+
111
+
112
+ __all__ = ["BaseAgentSettings"]
@@ -24,8 +24,11 @@ from sofias_sdk_lite.errors.exceptions import (
24
24
  DelegationPlanError,
25
25
  DelegationStepError,
26
26
  DelegationTimeoutError,
27
+ EmptyLLMResponseError,
27
28
  GraphExecutionError,
28
29
  InputValidationError,
30
+ LLMConfigurationError,
31
+ LLMRequestError,
29
32
  MaxIterationsError,
30
33
  MCPConnectionError,
31
34
  MCPToolExecutionError,
@@ -47,8 +50,11 @@ __all__ = [
47
50
  "DelegationPlanError",
48
51
  "DelegationStepError",
49
52
  "DelegationTimeoutError",
53
+ "EmptyLLMResponseError",
50
54
  "GraphExecutionError",
51
55
  "InputValidationError",
56
+ "LLMConfigurationError",
57
+ "LLMRequestError",
52
58
  "MaxIterationsError",
53
59
  "MCPConnectionError",
54
60
  "MCPToolExecutionError",
@@ -406,3 +406,63 @@ class ConfigSourceError(AgentSDKError):
406
406
  super().__init__(message, source=source, agent_name=agent_name)
407
407
  if cause:
408
408
  self.__cause__ = cause
409
+
410
+
411
+ class LLMConfigurationError(AgentSDKError):
412
+ """Error when no usable LLM gateway configuration can be resolved.
413
+
414
+ Raised by `sofias_sdk_lite.llm.create_llm` when neither the explicit
415
+ arguments, the agent settings, nor the environment provide enough
416
+ information (at minimum a model identifier) to build an LLM client.
417
+ """
418
+
419
+ def __init__(self, message: str, *, missing: list[str] | None = None) -> None:
420
+ self.missing = missing or []
421
+ super().__init__(message, missing=self.missing)
422
+
423
+
424
+ class LLMRequestError(AgentSDKError):
425
+ """Error when an LLM gateway request fails after exhausting retries.
426
+
427
+ Carries the HTTP status (``None`` for transport-level failures) and a
428
+ truncated response body so callers can log or branch on it.
429
+ """
430
+
431
+ def __init__(
432
+ self,
433
+ message: str,
434
+ *,
435
+ provider: str,
436
+ model: str,
437
+ status_code: int | None = None,
438
+ body: str | None = None,
439
+ cause: Exception | None = None,
440
+ ) -> None:
441
+ self.provider = provider
442
+ self.model = model
443
+ self.status_code = status_code
444
+ self.body = body
445
+ self.cause = cause
446
+ super().__init__(
447
+ message,
448
+ provider=provider,
449
+ model=model,
450
+ status_code=status_code,
451
+ )
452
+
453
+
454
+ class EmptyLLMResponseError(AgentSDKError):
455
+ """Error when the LLM returns neither text content nor tool calls.
456
+
457
+ `LLMNode` treats this like any other invocation failure and retries the
458
+ call, so a transient empty completion does not end the turn.
459
+ """
460
+
461
+ def __init__(self, *, provider: str, model: str) -> None:
462
+ self.provider = provider
463
+ self.model = model
464
+ super().__init__(
465
+ "LLM returned empty response (no content, no tool_calls)",
466
+ provider=provider,
467
+ model=model,
468
+ )
@@ -0,0 +1,72 @@
1
+ """LLM protocol, gateway clients, and the zero-config factory.
2
+
3
+ Two layers:
4
+
5
+ - **Protocol** (`LLMCallable`, `StreamableLLMCallable`, `LLMResponse`,
6
+ `TokenUsage`, `ToolSpec`, ...): the contract `LLMNode` drives. Wrap any
7
+ client in it if you need something the bundled adapters do not cover.
8
+ - **Batteries** (`create_llm`, `BifrostLLM`, `OpenAICompatibleLLM`,
9
+ `LLMGatewayConfig`): a ready-made client for the Sofias Bifrost gateway (or
10
+ any OpenAI-compatible endpoint) resolved from settings or the environment,
11
+ so agent code never constructs an LLM client by hand.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from sofias_sdk_lite.llm.bifrost import (
17
+ DEFAULT_BIFROST_BASE_URL,
18
+ DEFAULT_BIFROST_MAX_TOKENS,
19
+ BifrostLLM,
20
+ normalize_bifrost_base_url,
21
+ )
22
+ from sofias_sdk_lite.llm.factory import (
23
+ ENV_LLM_API_KEY,
24
+ ENV_LLM_BASE_URL,
25
+ ENV_LLM_MODEL,
26
+ ENV_LLM_PROVIDER,
27
+ LLMGatewayConfig,
28
+ create_llm,
29
+ default_llm,
30
+ gateway_config_from_env,
31
+ gateway_config_from_settings,
32
+ get_default_llm,
33
+ resolve_default_llm,
34
+ )
35
+ from sofias_sdk_lite.llm.openai_compatible import OpenAICompatibleLLM
36
+ from sofias_sdk_lite.llm.protocol import (
37
+ LLMCallable,
38
+ LLMResponse,
39
+ LLMStreamEvent,
40
+ StreamableLLMCallable,
41
+ )
42
+ from sofias_sdk_lite.llm.tokens import TokenUsage
43
+ from sofias_sdk_lite.llm.tools import ToolCall, ToolSpec
44
+
45
+ __all__ = [
46
+ # Protocol
47
+ "LLMCallable",
48
+ "LLMResponse",
49
+ "LLMStreamEvent",
50
+ "StreamableLLMCallable",
51
+ "TokenUsage",
52
+ "ToolCall",
53
+ "ToolSpec",
54
+ # Clients
55
+ "BifrostLLM",
56
+ "OpenAICompatibleLLM",
57
+ "DEFAULT_BIFROST_BASE_URL",
58
+ "DEFAULT_BIFROST_MAX_TOKENS",
59
+ "normalize_bifrost_base_url",
60
+ # Factory
61
+ "LLMGatewayConfig",
62
+ "create_llm",
63
+ "default_llm",
64
+ "get_default_llm",
65
+ "resolve_default_llm",
66
+ "gateway_config_from_env",
67
+ "gateway_config_from_settings",
68
+ "ENV_LLM_MODEL",
69
+ "ENV_LLM_BASE_URL",
70
+ "ENV_LLM_API_KEY",
71
+ "ENV_LLM_PROVIDER",
72
+ ]