sofias-sdk-lite 0.1.2__tar.gz → 0.1.4__tar.gz

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/PKG-INFO

@@ -1,16 +1,19 @@
 Metadata-Version: 2.4
 Name: sofias-sdk-lite
-Version: 0.1.2
+Version: 0.1.4
 Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
 License-Expression: Apache-2.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: aio-pika>=9.0.0
 Requires-Dist: rstream>=1.0.0
 Requires-Dist: nh3>=0.3.6
+Requires-Dist: httpx>=0.27.0
 Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25 ; extra == 'docs'
+Requires-Dist: opentelemetry-api>=1.20.0 ; extra == 'otel'
 Requires-Python: >=3.11
 Provides-Extra: docs
+Provides-Extra: otel
 Description-Content-Type: text/markdown
 
 # sofias-sdk-lite
@@ -28,12 +31,14 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
 - **A runner** — `AgentRunner` consumes tasks from a queue, resolves per-request
   settings, executes your agent, and streams the response back — with graceful
   shutdown, retries, and circuit breakers built in.
-- **Bring your own LLM** — `LLMCallable` is a protocol. Wrap any HTTP client,
-  local model, or provider SDK in ~15 lines; no vendor lock-in.
+- **An LLM that is already wired** — LLM nodes talk to the Sofias Bifrost
+  gateway (or any OpenAI-compatible endpoint) using the model, URL and key
+  from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
+  builds the client when you need it explicitly; `LLMCallable` stays a protocol
+  for anything the bundled clients do not cover.
 
-Nothing here depends on a private backend, an internal config service, or a
-specific LLM vendor. Everything infrastructure-specific is a constructor
-argument or a protocol you implement yourself.
+Nothing here depends on a private backend or an internal config service.
+Where the model lives is deployment configuration, not agent code.
 
 ## Install
 
@@ -103,6 +108,44 @@ See [`examples/`](examples/) for a runner against a local RabbitMQ
 (`docker-compose.yml` included), tool loops, streaming, and agent-to-agent
 delegation.
 
+## Connecting to the LLM
+
+An agent declares *what* the model should do; *where* the model lives is
+resolved at `build()`:
+
+1. Under `AgentRunner`, from the per-task settings the platform sends
+   (`model_name`, `router_url`, `router_api_key` on `BaseAgentSettings`).
+2. Otherwise from the environment: `SOFIAS_LLM_MODEL`, `SOFIAS_LLM_BASE_URL`
+   (default `http://bifrost:8080/v1`), `SOFIAS_LLM_API_KEY`,
+   `SOFIAS_LLM_PROVIDER` (default `bifrost`). The `BIFROST_MODEL` /
+   `BIFROST_BASE_URL` / `BIFROST_API_KEY` variables the Sofias Developer
+   Portal injects into agent containers are accepted as fallbacks, so a
+   portal-deployed agent needs no LLM configuration at all.
+3. Or explicitly: `.with_llm(create_llm(model="default", api_key=...))`.
+
+```python
+from sofias_sdk_lite import AgentBuilder, LLMNodeConfig, NodeContract
+
+agent = (
+    AgentBuilder("qa_agent")
+    .with_settings_class(MySettings)
+    .with_contract(input_schema=Question, output_schema=Answer)
+    .add_llm_node(
+        "answerer",
+        LLMNodeConfig(name="answerer", input_contract=Question, output_contract=Answer,
+                      system_prompt="Answer in one sentence."),
+        NodeContract(input_schema=Question, output_schema=Answer),
+    )
+    .set_entry_node("answerer")
+    .set_terminal("answerer")
+    .build()          # no LLM client anywhere in this file
+)
+```
+
+See `examples/03_llm_agent.py` and the
+[LLM integration](docs/concepts/llm-integration.md) guide (streaming,
+retries, bringing your own client).
+
 ## Running an agent against RabbitMQ
 
 ```python
@@ -138,13 +181,20 @@ if __name__ == "__main__":
     ).run()
 ```
 
+## Optional extras
+
+- `sofias-sdk-lite[otel]` — installs `opentelemetry-api` so the runner opens
+  an `agent.handle` span per turn and response fragments carry the active
+  span's `traceparent`. Without it, the inbound `traceparent` is still echoed
+  end to end.
+
 ## Scope (v1)
 
-Core agent graph, RabbitMQ messaging, and the runner ship today. Memory,
-MCP tool discovery, and LLM adapter implementations are intentionally out
-of scope for v1 — the SDK ships the relevant protocols
-(`MemoryProvider`, `ToolProvider`, `LLMCallable`) so you can plug in your
-own, and these become optional extras in a later release.
+Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
+Bifrost gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
+tool discovery are intentionally out of scope for v1 — the SDK ships the
+relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
+your own, and these become optional extras in a later release.
 
 ## License
 

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/README.md

@@ -13,12 +13,14 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
 - **A runner** — `AgentRunner` consumes tasks from a queue, resolves per-request
   settings, executes your agent, and streams the response back — with graceful
   shutdown, retries, and circuit breakers built in.
-- **Bring your own LLM** — `LLMCallable` is a protocol. Wrap any HTTP client,
-  local model, or provider SDK in ~15 lines; no vendor lock-in.
+- **An LLM that is already wired** — LLM nodes talk to the Sofias Bifrost
+  gateway (or any OpenAI-compatible endpoint) using the model, URL and key
+  from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
+  builds the client when you need it explicitly; `LLMCallable` stays a protocol
+  for anything the bundled clients do not cover.
 
-Nothing here depends on a private backend, an internal config service, or a
-specific LLM vendor. Everything infrastructure-specific is a constructor
-argument or a protocol you implement yourself.
+Nothing here depends on a private backend or an internal config service.
+Where the model lives is deployment configuration, not agent code.
 
 ## Install
 
@@ -88,6 +90,44 @@ See [`examples/`](examples/) for a runner against a local RabbitMQ
 (`docker-compose.yml` included), tool loops, streaming, and agent-to-agent
 delegation.
 
+## Connecting to the LLM
+
+An agent declares *what* the model should do; *where* the model lives is
+resolved at `build()`:
+
+1. Under `AgentRunner`, from the per-task settings the platform sends
+   (`model_name`, `router_url`, `router_api_key` on `BaseAgentSettings`).
+2. Otherwise from the environment: `SOFIAS_LLM_MODEL`, `SOFIAS_LLM_BASE_URL`
+   (default `http://bifrost:8080/v1`), `SOFIAS_LLM_API_KEY`,
+   `SOFIAS_LLM_PROVIDER` (default `bifrost`). The `BIFROST_MODEL` /
+   `BIFROST_BASE_URL` / `BIFROST_API_KEY` variables the Sofias Developer
+   Portal injects into agent containers are accepted as fallbacks, so a
+   portal-deployed agent needs no LLM configuration at all.
+3. Or explicitly: `.with_llm(create_llm(model="default", api_key=...))`.
+
+```python
+from sofias_sdk_lite import AgentBuilder, LLMNodeConfig, NodeContract
+
+agent = (
+    AgentBuilder("qa_agent")
+    .with_settings_class(MySettings)
+    .with_contract(input_schema=Question, output_schema=Answer)
+    .add_llm_node(
+        "answerer",
+        LLMNodeConfig(name="answerer", input_contract=Question, output_contract=Answer,
+                      system_prompt="Answer in one sentence."),
+        NodeContract(input_schema=Question, output_schema=Answer),
+    )
+    .set_entry_node("answerer")
+    .set_terminal("answerer")
+    .build()          # no LLM client anywhere in this file
+)
+```
+
+See `examples/03_llm_agent.py` and the
+[LLM integration](docs/concepts/llm-integration.md) guide (streaming,
+retries, bringing your own client).
+
 ## Running an agent against RabbitMQ
 
 ```python
@@ -123,13 +163,20 @@ if __name__ == "__main__":
     ).run()
 ```
 
+## Optional extras
+
+- `sofias-sdk-lite[otel]` — installs `opentelemetry-api` so the runner opens
+  an `agent.handle` span per turn and response fragments carry the active
+  span's `traceparent`. Without it, the inbound `traceparent` is still echoed
+  end to end.
+
 ## Scope (v1)
 
-Core agent graph, RabbitMQ messaging, and the runner ship today. Memory,
-MCP tool discovery, and LLM adapter implementations are intentionally out
-of scope for v1 — the SDK ships the relevant protocols
-(`MemoryProvider`, `ToolProvider`, `LLMCallable`) so you can plug in your
-own, and these become optional extras in a later release.
+Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
+Bifrost gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
+tool discovery are intentionally out of scope for v1 — the SDK ships the
+relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
+your own, and these become optional extras in a later release.
 
 ## License
 

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.1.2"
+version = "0.1.4"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,9 +10,11 @@ dependencies = [
     "aio-pika>=9.0.0",
     "rstream>=1.0.0",
     "nh3>=0.3.6",
+    "httpx>=0.27.0",
 ]
 
 [project.optional-dependencies]
+otel = ["opentelemetry-api>=1.20.0"]
 docs = [
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",
@@ -24,7 +26,10 @@ url = "https://pypi.org/simple"
 default = true
 
 [tool.pytest.ini_options]
-pythonpath = ["src"]
+pythonpath = [
+    "src",
+    ".",
+]
 addopts = "-ra"
 asyncio_mode = "auto"
 markers = ["integration: requires a running RabbitMQ broker"]
@@ -48,4 +53,6 @@ dev = [
     "pytest-cov>=5.0",
     "ruff>=0.4.0",
     "pyright>=1.1.408",
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
 ]

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.1.2"
+version = "0.1.4"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,9 +10,13 @@ dependencies = [
     "aio-pika>=9.0.0",
     "rstream>=1.0.0",
     "nh3>=0.3.6",
+    "httpx>=0.27.0",
 ]
 
 [project.optional-dependencies]
+otel = [
+    "opentelemetry-api>=1.20.0",
+]
 docs = [
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",
@@ -34,10 +38,13 @@ dev = [
     "pytest-cov>=5.0",
     "ruff>=0.4.0",
     "pyright>=1.1.408",
+    # Exercise the optional OpenTelemetry path (the `[otel]` extra) in tests.
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
 ]
 
 [tool.pytest.ini_options]
-pythonpath = ["src"]
+pythonpath = ["src", "."]
 addopts = "-ra"
 asyncio_mode = "auto"
 markers = ["integration: requires a running RabbitMQ broker"]

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/src/sofias_sdk_lite/__init__.py

@@ -30,6 +30,8 @@ against RabbitMQ, streaming, delegation, and testing.
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
+
 from sofias_sdk_lite.agent import (
     Agent,
     AgentBuildError,
@@ -45,6 +47,7 @@ from sofias_sdk_lite.agent import (
     StreamingResponseWorkflow,
     get_execution_context,
     set_execution_context,
+    usage_state_from_list,
 )
 from sofias_sdk_lite.config import (
     AgentSettings,
@@ -73,6 +76,9 @@ from sofias_sdk_lite.errors import (
     AgentSDKError,
     CircuitBreakerConfig,
     ConfigSourceError,
+    EmptyLLMResponseError,
+    LLMConfigurationError,
+    LLMRequestError,
     ContractValidationError,
     ErrorHandler,
     ErrorHandlerConfig,
@@ -85,9 +91,14 @@ from sofias_sdk_lite.errors import (
     ToolExecutionError,
 )
 from sofias_sdk_lite.llm import (
+    BifrostLLM,
     LLMCallable,
+    LLMGatewayConfig,
     LLMResponse,
+    OpenAICompatibleLLM,
     StreamableLLMCallable,
+    create_llm,
+    default_llm,
     TokenUsage,
     ToolCall,
     ToolSpec,
@@ -143,10 +154,20 @@ from sofias_sdk_lite.state import (
     InMemoryStateProvider,
     MemoryProvider,
     Message,
+    SummarizingHistoryProvider,
+)
+from sofias_sdk_lite.workflows import (
+    BaseStreamingResponseWorkflow,
+    ChatResponseWorkflow,
+    NullWorkflow,
 )
-from sofias_sdk_lite.workflows import ChatResponseWorkflow, NullWorkflow
 
-__version__ = "0.1.0"
+try:
+    # Derived from the installed distribution so it never drifts from
+    # pyproject.toml (CI rewrites the version there on tagged releases).
+    __version__ = version("sofias-sdk-lite")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0"
 
 __all__ = [
     "__version__",
@@ -161,6 +182,7 @@ __all__ = [
     "ExecutionContext",
     "get_execution_context",
     "set_execution_context",
+    "usage_state_from_list",
     "ResponseWorkflow",
     "StreamingResponseWorkflow",
     "BaseDelegationResponseWorkflow",
@@ -196,6 +218,9 @@ __all__ = [
     "ToolExecutionError",
     "GraphExecutionError",
     "ConfigSourceError",
+    "EmptyLLMResponseError",
+    "LLMConfigurationError",
+    "LLMRequestError",
     "ErrorHandler",
     "ErrorHandlerConfig",
     "RetryPolicy",
@@ -204,6 +229,12 @@ __all__ = [
     "LLMCallable",
     "StreamableLLMCallable",
     "LLMResponse",
+    # LLM clients + factory
+    "BifrostLLM",
+    "OpenAICompatibleLLM",
+    "LLMGatewayConfig",
+    "create_llm",
+    "default_llm",
     "TokenUsage",
     "ToolCall",
     "ToolSpec",
@@ -251,12 +282,14 @@ __all__ = [
     "RunnerConfig",
     # Workflows
     "ChatResponseWorkflow",
+    "BaseStreamingResponseWorkflow",
     "NullWorkflow",
     # State
     "ConversationStateProvider",
     "InMemoryStateProvider",
     "MemoryProvider",
     "HistoryProvider",
+    "SummarizingHistoryProvider",
     "InMemoryHistory",
     "Message",
 ]

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/src/sofias_sdk_lite/agent/__init__.py

@@ -8,6 +8,7 @@ from sofias_sdk_lite.agent.execution_context import (
     TokenAccumulator,
     get_execution_context,
     set_execution_context,
+    usage_state_from_list,
 )
 from sofias_sdk_lite.agent.middleware import (
     AgentMiddleware,
@@ -39,6 +40,7 @@ __all__ = [
     "set_execution_context",
     "ExecutionContext",
     "TokenAccumulator",
+    "usage_state_from_list",
     # Builder
     "AgentBuilder",
     "AgentBuildError",

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/src/sofias_sdk_lite/agent/agent_builder.py

@@ -24,6 +24,7 @@ from sofias_sdk_lite.errors.error_handler import (
 )
 from sofias_sdk_lite.errors.exceptions import AgentSDKError
 from sofias_sdk_lite.llm import LLMCallable
+from sofias_sdk_lite.llm.factory import ENV_LLM_MODEL, resolve_default_llm
 from sofias_sdk_lite.nodes.aggregator_config import AggregatorNodeConfig
 from sofias_sdk_lite.nodes.base_node import BaseNode
 from sofias_sdk_lite.nodes.delegation_config import DelegationNodeConfig
@@ -230,9 +231,21 @@ class AgentBuilder:
         self._output_schema = output_schema
         return self
 
+    _MISSING_LLM_MESSAGE = (
+        "No LLM available for LLM nodes. Either call with_llm(), run the agent through "
+        "AgentRunner with model_name/router_url/router_api_key in its settings, or export "
+        f"{ENV_LLM_MODEL} (plus SOFIAS_LLM_BASE_URL / SOFIAS_LLM_API_KEY)."
+    )
+
     def with_llm(self, llm: LLMCallable) -> AgentBuilder:
         """Set the LLM callable for all LLM nodes.
 
+        Optional. When omitted, `build()` uses the LLM installed by
+        `sofias_sdk_lite.llm.default_llm` (what `AgentRunner` does with the
+        per-task settings) or, failing that, one built from the
+        ``SOFIAS_LLM_*`` environment variables via
+        `sofias_sdk_lite.llm.create_llm`.
+
         Args:
             llm: LLM implementation for making completions.
 
@@ -242,6 +255,12 @@ class AgentBuilder:
         self._llm = llm
         return self
 
+    def _needs_agent_llm(self) -> bool:
+        """Whether any node still to be built relies on the agent-level LLM."""
+        if self._llm_node_configs:
+            return True
+        return any(cfg["llm"] is None for cfg in self._planner_node_configs.values())
+
     def with_agent_llm_config(self, config: AgentLLMConfig) -> AgentBuilder:
         """Set agent-level LLM configuration.
 
@@ -899,9 +918,9 @@ class AgentBuilder:
             )
             errors.extend(graph_errors)
 
-        # LLM must be provided if there are LLM nodes to be built (not pre-built)
+        # LLM must be resolvable if there are LLM nodes to be built (not pre-built)
         if self._llm_node_configs and self._llm is None:
-            errors.append("LLM not provided but LLM nodes need to be built. Use with_llm() to set the LLM callable.")
+            errors.append(self._MISSING_LLM_MESSAGE)
 
         # Delegation transport must be provided if there are delegation nodes
         if self._delegation_node_configs and self._delegation_transport is None:
@@ -941,8 +960,8 @@ class AgentBuilder:
             for name, config in self._planner_node_configs.items():
                 if config["llm"] is None and self._llm is None:
                     errors.append(
-                        f"PlannerNode '{name}' has no LLM and no agent-level LLM is set. "
-                        "Use with_llm() or provide llm to add_planner_node()."
+                        f"PlannerNode '{name}' has no LLM and no agent-level LLM could be "
+                        f"resolved. {self._MISSING_LLM_MESSAGE}"
                     )
 
                 # Validate available_nodes references
@@ -1016,6 +1035,11 @@ class AgentBuilder:
         # Apply default routes before validation
         self._apply_default_routes()
 
+        # Resolve the agent-level LLM when none was given explicitly: the
+        # runner's per-task default (from settings) first, then the environment.
+        if self._llm is None and self._needs_agent_llm():
+            self._llm = resolve_default_llm()
+
         # Validate configuration
         errors = self._validate()
         if errors:

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/src/sofias_sdk_lite/agent/execution_context.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from contextvars import ContextVar
 from dataclasses import dataclass
 from datetime import datetime
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -22,6 +22,7 @@ __all__ = [
     "ExecutionContext",
     "get_execution_context",
     "set_execution_context",
+    "usage_state_from_list",
 ]
 
 
@@ -136,6 +137,48 @@ class TokenAccumulator:
         return result
 
 
+def _usage_entry(entry: Any, key: str, default: Any = 0) -> Any:
+    """Read *key* off a usage entry that may be a dict or an object.
+
+    ``AgentResponse.usage`` entries are typed as ``dict`` (built by
+    ``TokenAccumulator.to_usage_list``), but callers are free to set the
+    field directly with plain objects, so both shapes must work.
+    """
+    if isinstance(entry, dict):
+        return cast(dict[str, Any], entry).get(key, default)
+    return getattr(entry, key, default)
+
+
+def _usage_entry_int(entry: Any, key: str) -> int:
+    try:
+        return int(_usage_entry(entry, key, 0) or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def usage_state_from_list(usage: list[Any] | None) -> dict[str, Any] | None:
+    """Collapse an ``AgentResponse.usage`` list into a single ``StreamFragment``
+    ``state.usage`` object, or ``None`` when there is nothing to report.
+
+    Every response workflow that publishes a terminal fragment should call
+    this and merge the result into ``state``: it is the one place a billing
+    consumer reads token usage from. Sums tokens across every LLM call in the
+    turn (a turn can invoke several models: the main chat call plus e.g. an
+    embedding call for RAG), and names the entry with the most completion
+    tokens as ``model``, which picks the actual generation call over
+    near-zero-completion side calls.
+    """
+    if not usage:
+        return None
+
+    primary = max(usage, key=lambda e: _usage_entry_int(e, "completion_tokens"))
+    return {
+        "prompt_tokens": sum(_usage_entry_int(e, "prompt_tokens") for e in usage),
+        "completion_tokens": sum(_usage_entry_int(e, "completion_tokens") for e in usage),
+        "model": _usage_entry(primary, "model_requested", ""),
+    }
+
+
 class ExecutionContext(BaseModel):
     """Structured execution context propagated via ContextVar.
 

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.4}/src/sofias_sdk_lite/config/__init__.py

@@ -6,12 +6,14 @@ from sofias_sdk_lite.config.defaults import (
     DEFAULT_MAX_ITERATIONS,
     DEFAULT_MAX_RETRIES,
     DEFAULT_MAX_TOKENS,
+    DEFAULT_MAX_TOOL_LOOP_TOKENS,
     DEFAULT_MODEL,
     DEFAULT_RETRY_BACKOFF_MULTIPLIER,
     DEFAULT_RETRY_DELAY_SECONDS,
     DEFAULT_RETRY_MAX_DELAY_SECONDS,
     DEFAULT_STRICT_VALIDATION,
     DEFAULT_TEMPERATURE,
+    DEFAULT_TOOL_LOOP_TOKEN_RESERVE,
     DEFAULT_TOP_P,
     DEFAULT_VERBOSE_LOGGING,
 )
@@ -38,12 +40,14 @@ __all__ = [
     "DEFAULT_MAX_ITERATIONS",
     "DEFAULT_MAX_RETRIES",
     "DEFAULT_MAX_TOKENS",
+    "DEFAULT_MAX_TOOL_LOOP_TOKENS",
     "DEFAULT_MODEL",
     "DEFAULT_RETRY_BACKOFF_MULTIPLIER",
     "DEFAULT_RETRY_DELAY_SECONDS",
     "DEFAULT_RETRY_MAX_DELAY_SECONDS",
     "DEFAULT_STRICT_VALIDATION",
     "DEFAULT_TEMPERATURE",
+    "DEFAULT_TOOL_LOOP_TOKEN_RESERVE",
     "DEFAULT_TOP_P",
     "DEFAULT_VERBOSE_LOGGING",
     # SDK Config