toolstream 0.1.0__py3-none-any.whl

toolstream/_tools.py

@@ -0,0 +1,109 @@
+"""Tool registration system for toolstream.
+
+Provides the @tool decorator for marking functions as LLM-callable tools,
+and collect_tools() for discovering decorated functions across modules.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Callable
+
+from ._schema import _generate_schema
+
+
+@dataclass(frozen=True)
+class Tool:
+    """Metadata for a registered tool function."""
+
+    name: str
+    description: str
+    input_schema: dict
+    handler: Callable
+    inject: list[str]
+
+
+def tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    inject: list[str] | None = None,
+) -> Callable:
+    """Decorator factory that attaches Tool metadata to a function.
+
+    Usage:
+        @tool()
+        def my_func(x: int) -> str:
+            ...
+
+        @tool(inject=["ctx"])
+        def my_func(ctx, x: int) -> str:
+            ...
+
+    The decorated function is returned unchanged -- this decorator only
+    attaches a _tool attribute, it does not wrap the function.
+    """
+    inject_list = inject or []
+
+    def decorator(fn: Callable) -> Callable:
+        # Validate that every injected param exists in the signature
+        sig = inspect.signature(fn)
+        for param_name in inject_list:
+            if param_name not in sig.parameters:
+                raise ValueError(
+                    f"inject parameter {param_name!r} not found in "
+                    f"signature of {fn.__name__}(). "
+                    f"Available: {list(sig.parameters.keys())}"
+                )
+
+        # Resolve name
+        tool_name = name if name is not None else fn.__name__
+
+        # Resolve description from first line of docstring
+        if description is not None:
+            tool_description = description
+        elif fn.__doc__:
+            tool_description = fn.__doc__.strip().split("\n")[0].strip()
+        else:
+            tool_description = ""
+
+        # Generate input schema, excluding injected params
+        input_schema = _generate_schema(fn, inject=set(inject_list))
+
+        fn._tool = Tool(
+            name=tool_name,
+            description=tool_description,
+            input_schema=input_schema,
+            handler=fn,
+            inject=inject_list,
+        )
+
+        return fn
+
+    return decorator
+
+
+def collect_tools(*modules) -> list[Tool]:
+    """Discover all @tool-decorated functions across the given modules.
+
+    Raises ValueError if two tools share the same name.
+    """
+    tools: list[Tool] = []
+    seen_names: dict[str, str] = {}  # name -> module name for error messages
+
+    for module in modules:
+        module_name = getattr(module, "__name__", repr(module))
+        for attr_name in dir(module):
+            obj = getattr(module, attr_name)
+            if callable(obj) and hasattr(obj, "_tool"):
+                t: Tool = obj._tool
+                if t.name in seen_names:
+                    raise ValueError(
+                        f"Tool name collision: {t.name!r} found in both "
+                        f"{seen_names[t.name]} and {module_name}"
+                    )
+                seen_names[t.name] = module_name
+                tools.append(t)
+
+    return tools

toolstream/config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._agent import AgentSandbox
+    from ._context import ToolContext
+    from ._tools import Tool
+
+
+@dataclass
+class SessionConfig:
+    model: str
+    api_key: str
+    base_url: str
+    system_prompt: str
+    cwd: str | None = None
+    env: dict[str, str] = field(default_factory=dict)
+    agent: str | None = None
+    tools: list[Tool] | None = None
+    tool_context: ToolContext | None = None
+    tool_env: dict[str, str] = field(default_factory=dict)
+    max_completion_tokens: int = 16384
+    sandbox: AgentSandbox | None = None
+    metadata: dict[str, str] | None = None

toolstream/events.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class StepStart:
+    session_id: str
+    message_id: str
+    timestamp: int
+
+
+@dataclass(frozen=True)
+class Text:
+    session_id: str
+    message_id: str
+    text: str
+    timestamp: int
+
+
+@dataclass(frozen=True)
+class ToolUse:
+    session_id: str
+    message_id: str
+    tool: str
+    call_id: str
+    status: str  # "completed", "error", etc.
+    input: dict
+    output: str
+    title: str
+    timestamp: int
+
+
+@dataclass(frozen=True)
+class StepFinish:
+    session_id: str
+    message_id: str
+    reason: str  # "stop", "tool-calls"
+    input_tokens: int
+    output_tokens: int
+    reasoning_tokens: int
+    cache_read_tokens: int
+    cache_write_tokens: int
+    cost: float
+    timestamp: int
+
+
+@dataclass(frozen=True)
+class Error:
+    session_id: str
+    name: str
+    message: str
+    data: dict
+    timestamp: int
+
+
+@dataclass(frozen=True)
+class Result:
+    session_id: str
+    total_input_tokens: int
+    total_output_tokens: int
+    total_cost: float
+    steps: int

toolstream-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: toolstream
+Version: 0.1.0
+Summary: Typed streaming SDK for LLM tool-calling loops
+Keywords: rlsbl
+Requires-Python: >=3.11
+Requires-Dist: httpx

toolstream-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+toolstream/__init__.py,sha256=Lt50_6y_ZOnxWSSQEsoRPbbfBau_ZPAKvR5MqAxrABU,915
+toolstream/_agent.py,sha256=l3FipLcg_0QszIcekBrq-ORzGbnl2vBcu3fgGOZE7Ls,6550
+toolstream/_builtin_tools.py,sha256=tGYC0iteb1_F_X4iNW20frtucwkBwGCyP7PREk1FCTA,4107
+toolstream/_context.py,sha256=KMFlPW5xqHDLAyps_UfnZOhHA_3lNsWT4UfRxkhNUts,366
+toolstream/_direct.py,sha256=qBCfBjCVLyeFUiCUpo4UP62Jagn453x70kR-r1ny6ho,10300
+toolstream/_invoke.py,sha256=pmvprfovXhzWOWVh0j7ArvAU122HESEmEWohCDT2LW4,3912
+toolstream/_protocol.py,sha256=-hqqJX-xCg7bqQXMCHrjZ4FnWGKsiQ4QdLFQKdXBBII,2514
+toolstream/_schema.py,sha256=qG2zLGXGFU5IYfF6YJRoV-TPEkjjJFQ016DWmNFBuxo,8382
+toolstream/_session.py,sha256=ka5EKQloyYvnQO9_UarVWWWK5HY1brx_f7LOlRDb__0,5724
+toolstream/_tools.py,sha256=nmNKs9l9FwY6v0FTXB1J2gd841pYQafOExbNLADOp2A,3201
+toolstream/config.py,sha256=Gmt_0BTaymbdtQAZaYM_C0LtN9J1l44e4VIMFUE1yB0,711
+toolstream/events.py,sha256=1ECr9gKTBX5JW7XfvuKFNkMABuAk3N9a2yMi3TdNSxQ,1070
+toolstream/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+toolstream-0.1.0.dist-info/METADATA,sha256=zcA1Lg05a1mZhCva9-AoYUvOinJjnbDsvC82nL2PVI4,171
+toolstream-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+toolstream-0.1.0.dist-info/RECORD,,

toolstream-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any