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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sofias-sdk-lite
-Version: 0.1.2
+Version: 0.1.3
 Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
 License-Expression: Apache-2.0
 Requires-Dist: pydantic>=2.0
@@ -9,8 +9,10 @@ Requires-Dist: rstream>=1.0.0
 Requires-Dist: nh3>=0.3.6
 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
@@ -138,6 +140,13 @@ 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,

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

@@ -123,6 +123,13 @@ 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,

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

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.1.2"
+version = "0.1.3"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,6 +13,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+otel = ["opentelemetry-api>=1.20.0"]
 docs = [
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",
@@ -24,7 +25,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 +52,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.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.1.2"
+version = "0.1.3"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,6 +13,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+otel = [
+    "opentelemetry-api>=1.20.0",
+]
 docs = [
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",
@@ -34,10 +37,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.3}/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,
@@ -143,10 +146,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 +174,7 @@ __all__ = [
     "ExecutionContext",
     "get_execution_context",
     "set_execution_context",
+    "usage_state_from_list",
     "ResponseWorkflow",
     "StreamingResponseWorkflow",
     "BaseDelegationResponseWorkflow",
@@ -251,12 +265,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.3}/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.3}/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.3}/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

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.3}/src/sofias_sdk_lite/config/agent_settings.py

@@ -15,7 +15,7 @@ whatever fields their own agent actually needs:
 from __future__ import annotations
 
 import difflib
-from typing import Any
+from typing import Any, ClassVar
 
 from pydantic import ConfigDict, model_validator
 
@@ -41,6 +41,24 @@ class BaseAgentSettings(AgentSettings):
 
     model_config = ConfigDict(extra="ignore", validate_default=True)
 
+    CREDENTIAL_FIELDS: ClassVar[frozenset[str]] = frozenset()
+    """Names of fields that hold credentials (API keys, tokens, secrets).
+
+    Declare them on your subclass, ideally typed as ``pydantic.SecretStr`` so
+    ``repr``/``model_dump`` never leak the raw value. The SDK excludes these
+    fields wherever settings are dumped into a dict that reaches an LLM prompt
+    (``LLMNode`` template variables), so a ``{api_key}`` placeholder can never
+    inline a secret. Read them at the point of use with ``.get_secret_value()``.
+
+    Example::
+
+        class MySettings(BaseAgentSettings):
+            CREDENTIAL_FIELDS = frozenset({"api_key"})
+
+            model_name: str = "gpt-4o-mini"
+            api_key: SecretStr = SecretStr("")
+    """
+
     @model_validator(mode="before")
     @classmethod
     def _warn_on_typo_keys(cls, data: Any) -> Any:

{sofias_sdk_lite-0.1.2 → sofias_sdk_lite-0.1.3}/src/sofias_sdk_lite/config/defaults.py

@@ -29,6 +29,19 @@ DEFAULT_TOP_P: Final[float] = 1.0
 DEFAULT_MAX_ITERATIONS: Final[int] = 10
 """Default maximum iterations for a node's tool loop."""
 
+DEFAULT_MAX_TOOL_LOOP_TOKENS: Final[int] = 128_000
+"""Token budget for the WHOLE request of a tool-loop iteration.
+
+The budget means the model's context window, not "what is left for the
+history". The fixed prefix (system prompt + user prompt + tool schemas) is
+*measured* on every iteration and counted against this number, together with
+the accumulated tool-loop history. An agent running a model with a larger
+window should raise it via ``NodeToolLoopConfig.max_tool_loop_tokens``.
+"""
+
+DEFAULT_TOOL_LOOP_TOKEN_RESERVE: Final[int] = 16_384
+"""Tokens reserved for the final LLM response within the tool-loop budget."""
+
 DEFAULT_ITERATION_TIMEOUT_SECONDS: Final[float] = 60.0
 """Default timeout in seconds for a single tool loop iteration."""
 
@@ -68,6 +81,8 @@ __all__ = [
     "DEFAULT_MAX_TOKENS",
     "DEFAULT_TOP_P",
     "DEFAULT_MAX_ITERATIONS",
+    "DEFAULT_MAX_TOOL_LOOP_TOKENS",
+    "DEFAULT_TOOL_LOOP_TOKEN_RESERVE",
     "DEFAULT_ITERATION_TIMEOUT_SECONDS",
     "DEFAULT_MAX_RETRIES",
     "DEFAULT_RETRY_DELAY_SECONDS",