runlet 0.1.0__py3-none-any.whl

runlet/__init__.py

@@ -0,0 +1,87 @@
+"""Runlet: a tiny observable runtime for Python agents."""
+
+from runlet.core import (
+    Agent,
+    CancellationError,
+    CompositeEventSink,
+    ContextOverflowError,
+    InMemoryObserver,
+    HookError,
+    InternalRuntimeError,
+    Message,
+    ModelCapabilities,
+    ModelError,
+    ModelRequest,
+    ModelResponse,
+    ModelStreamEvent,
+    ProviderStreamEvent,
+    PolicyStop,
+    RunContext,
+    RunResult,
+    RunletError,
+    RuntimeEvent,
+    StateError,
+    ToolCall,
+    ToolError,
+    ToolResult,
+    Usage,
+)
+from runlet.integrations import BaseHook, HookRunner, ToolContext, ToolSpec, execute_tool_call, tool
+from runlet.runtime import (
+    ContextManager,
+    ContextPolicy,
+    HookPolicy,
+    InMemoryStateStore,
+    RunPolicy,
+    Runtime,
+    SimpleTokenEstimator,
+    StateScope,
+    TokenEstimate,
+    ToolPolicy,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "CancellationError",
+    "CompositeEventSink",
+    "ContextManager",
+    "ContextPolicy",
+    "ContextOverflowError",
+    "BaseHook",
+    "HookError",
+    "HookRunner",
+    "HookPolicy",
+    "InMemoryObserver",
+    "InternalRuntimeError",
+    "Message",
+    "ModelCapabilities",
+    "ModelError",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelStreamEvent",
+    "ProviderStreamEvent",
+    "PolicyStop",
+    "RunContext",
+    "RunPolicy",
+    "RunResult",
+    "RunletError",
+    "Runtime",
+    "RuntimeEvent",
+    "SimpleTokenEstimator",
+    "StateScope",
+    "StateError",
+    "InMemoryStateStore",
+    "TokenEstimate",
+    "ToolCall",
+    "ToolContext",
+    "ToolError",
+    "ToolResult",
+    "ToolPolicy",
+    "ToolSpec",
+    "Usage",
+    "__version__",
+    "execute_tool_call",
+    "tool",
+]

runlet/core/__init__.py

@@ -0,0 +1,52 @@
+from runlet.core.agent import Agent
+from runlet.core.errors import (
+    CancellationError,
+    ContextOverflowError,
+    HookError,
+    InternalRuntimeError,
+    ModelError,
+    PolicyStop,
+    RunletError,
+    StateError,
+    ToolError,
+)
+from runlet.core.events import CompositeEventSink, EventSink, InMemoryObserver, RuntimeEvent
+from runlet.core.messages import Message, ToolCall, ToolResult
+from runlet.core.models import (
+    ModelCapabilities,
+    ModelProvider,
+    ModelRequest,
+    ModelResponse,
+    ModelStreamEvent,
+    ProviderStreamEvent,
+)
+from runlet.core.runs import RunContext, RunResult, Usage
+
+__all__ = [
+    "Agent",
+    "CancellationError",
+    "CompositeEventSink",
+    "ContextOverflowError",
+    "EventSink",
+    "HookError",
+    "InMemoryObserver",
+    "InternalRuntimeError",
+    "Message",
+    "ModelCapabilities",
+    "ModelError",
+    "ModelProvider",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelStreamEvent",
+    "ProviderStreamEvent",
+    "PolicyStop",
+    "RunContext",
+    "RunResult",
+    "RunletError",
+    "RuntimeEvent",
+    "StateError",
+    "ToolCall",
+    "ToolError",
+    "ToolResult",
+    "Usage",
+]

runlet/core/agent.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _metadata_map() -> dict[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class Agent:
+    name: str
+    instructions: str
+    model: Any
+    tools: tuple[Any, ...] = ()
+    hooks: tuple[Any, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=_metadata_map)

runlet/core/errors.py

@@ -0,0 +1,34 @@
+class RunletError(Exception):
+    code = "runlet_error"
+
+
+class ModelError(RunletError):
+    code = "model_error"
+
+
+class ToolError(RunletError):
+    code = "tool_error"
+
+
+class ContextOverflowError(RunletError):
+    code = "context_overflow"
+
+
+class HookError(RunletError):
+    code = "hook_error"
+
+
+class PolicyStop(RunletError):
+    code = "policy_stop"
+
+
+class StateError(RunletError):
+    code = "state_error"
+
+
+class CancellationError(RunletError):
+    code = "cancelled"
+
+
+class InternalRuntimeError(RunletError):
+    code = "internal_runtime_error"

runlet/core/events.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Protocol
+from uuid import uuid4
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _event_map() -> dict[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class RuntimeEvent:
+    type: str
+    run_id: str
+    id: str = field(default_factory=lambda: f"evt_{uuid4().hex}")
+    timestamp: datetime = field(default_factory=utc_now)
+    step_id: str | None = None
+    span_id: str | None = None
+    parent_span_id: str | None = None
+    agent_name: str | None = None
+    severity: str = "info"
+    payload: dict[str, Any] = field(default_factory=_event_map)
+    attributes: dict[str, Any] = field(default_factory=_event_map)
+
+
+class EventSink(Protocol):
+    async def emit(self, event: RuntimeEvent) -> None:
+        ...
+
+
+class InMemoryObserver:
+    def __init__(self) -> None:
+        self.events: list[RuntimeEvent] = []
+
+    async def emit(self, event: RuntimeEvent) -> None:
+        self.events.append(event)
+
+
+class CompositeEventSink:
+    def __init__(self, sinks: list[EventSink] | tuple[EventSink, ...]) -> None:
+        self.sinks = tuple(sinks)
+
+    async def emit(self, event: RuntimeEvent) -> None:
+        for sink in self.sinks:
+            await sink.emit(event)

runlet/core/messages.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _string_map() -> dict[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class Message:
+    role: str
+    text: str
+    metadata: dict[str, Any] = field(default_factory=_string_map)
+
+    @classmethod
+    def system(cls, text: str, metadata: dict[str, Any] | None = None) -> "Message":
+        return cls(role="system", text=text, metadata=metadata or {})
+
+    @classmethod
+    def user(cls, text: str, metadata: dict[str, Any] | None = None) -> "Message":
+        return cls(role="user", text=text, metadata=metadata or {})
+
+    @classmethod
+    def assistant(cls, text: str, metadata: dict[str, Any] | None = None) -> "Message":
+        return cls(role="assistant", text=text, metadata=metadata or {})
+
+    @classmethod
+    def tool(cls, text: str, metadata: dict[str, Any] | None = None) -> "Message":
+        return cls(role="tool", text=text, metadata=metadata or {})
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict[str, Any] = field(default_factory=_string_map)
+    metadata: dict[str, Any] = field(default_factory=_string_map)
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    call_id: str
+    name: str
+    content: str
+    metadata: dict[str, Any] = field(default_factory=_string_map)

runlet/core/models.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from runlet.core.messages import Message, ToolCall
+from runlet.core.runs import Usage
+
+
+def _tool_list() -> list[Any]:
+    return []
+
+
+def _metadata_map() -> dict[str, Any]:
+    return {}
+
+
+def _tool_call_list() -> list[ToolCall]:
+    return []
+
+
+@dataclass(frozen=True)
+class ModelCapabilities:
+    model_name: str
+    context_window: int
+    supports_tools: bool = True
+    supports_parallel_tool_calls: bool = False
+    supports_streaming: bool = False
+
+
+@dataclass(frozen=True)
+class ModelRequest:
+    messages: list[Message]
+    tools: list[Any] = field(default_factory=_tool_list)
+    metadata: dict[str, Any] = field(default_factory=_metadata_map)
+    options: dict[str, Any] = field(default_factory=_metadata_map)
+
+
+@dataclass(frozen=True)
+class ModelResponse:
+    message: Message
+    tool_calls: list[ToolCall] = field(default_factory=_tool_call_list)
+    usage: Usage = field(default_factory=Usage)
+    final: bool = True
+    raw: Any = None
+
+
+@dataclass(frozen=True)
+class ModelStreamEvent:
+    delta: str = ""
+    tool_call: ToolCall | None = None
+    usage: Usage | None = None
+    final: bool = False
+    raw: Any = None
+
+
+def _arguments_map() -> dict[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class ProviderStreamEvent:
+    kind: str
+    delta: str = ""
+    call_id: str | None = None
+    name: str | None = None
+    arguments_delta: str = ""
+    arguments: dict[str, Any] = field(default_factory=_arguments_map)
+    usage: Usage | None = None
+    raw: Any = None
+
+    @classmethod
+    def text_delta(cls, delta: str, raw: Any = None) -> "ProviderStreamEvent":
+        return cls(kind="text_delta", delta=delta, raw=raw)
+
+    @classmethod
+    def tool_call_delta(
+        cls,
+        call_id: str,
+        name: str | None,
+        arguments_delta: str,
+        raw: Any = None,
+    ) -> "ProviderStreamEvent":
+        return cls(
+            kind="tool_call_delta",
+            call_id=call_id,
+            name=name,
+            arguments_delta=arguments_delta,
+            raw=raw,
+        )
+
+    @classmethod
+    def tool_call_completed(
+        cls,
+        call_id: str,
+        name: str,
+        arguments: dict[str, Any],
+        raw: Any = None,
+    ) -> "ProviderStreamEvent":
+        return cls(
+            kind="tool_call_completed",
+            call_id=call_id,
+            name=name,
+            arguments=dict(arguments),
+            raw=raw,
+        )
+
+    @classmethod
+    def message_completed(cls, raw: Any = None) -> "ProviderStreamEvent":
+        return cls(kind="message_completed", raw=raw)
+
+    @classmethod
+    def usage_event(cls, usage: Usage, raw: Any = None) -> "ProviderStreamEvent":
+        return cls(kind="usage", usage=usage, raw=raw)
+
+    @classmethod
+    def completed(cls, raw: Any = None) -> "ProviderStreamEvent":
+        return cls(kind="completed", raw=raw)
+
+
+class ModelProvider(Protocol):
+    async def complete(self, request: ModelRequest) -> ModelResponse:
+        ...
+
+    async def stream(self, request: ModelRequest) -> AsyncIterator[ProviderStreamEvent | ModelStreamEvent]:
+        ...
+
+    async def capabilities(self) -> ModelCapabilities:
+        ...

runlet/core/runs.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from runlet.core.agent import Agent
+from runlet.core.messages import Message
+
+
+def _message_list() -> list[Message]:
+    return []
+
+
+def _metadata_map() -> dict[str, Any]:
+    return {}
+
+
+def _state_map() -> dict[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    source: str = "actual"
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass
+class RunContext:
+    run_id: str
+    agent: Agent
+    messages: list[Message] = field(default_factory=_message_list)
+    metadata: dict[str, Any] = field(default_factory=_metadata_map)
+    state: dict[str, Any] = field(default_factory=_state_map)
+    usage: Usage = field(default_factory=Usage)
+
+
+@dataclass(frozen=True)
+class RunResult:
+    run_id: str
+    status: str
+    output: str | None = None
+    messages: tuple[Message, ...] = ()
+    usage: Usage = field(default_factory=Usage)
+    error: str | None = None
+
+    @classmethod
+    def completed(
+        cls,
+        run_id: str,
+        output: str,
+        usage: Usage | None = None,
+        messages: tuple[Message, ...] = (),
+    ) -> "RunResult":
+        return cls(
+            run_id=run_id,
+            status="completed",
+            output=output,
+            usage=usage or Usage(),
+            messages=messages,
+        )
+
+    @classmethod
+    def failed(
+        cls,
+        run_id: str,
+        error: str,
+        usage: Usage | None = None,
+        messages: tuple[Message, ...] = (),
+    ) -> "RunResult":
+        return cls(
+            run_id=run_id,
+            status="failed",
+            usage=usage or Usage(),
+            error=error,
+            messages=messages,
+        )

runlet/integrations/__init__.py

@@ -0,0 +1,13 @@
+from runlet.integrations.hooks import BaseHook, HookRunner
+from runlet.integrations.tools import ToolContext, ToolHandler, ToolSpec, execute_tool_call, tool, validate_arguments
+
+__all__ = [
+    "BaseHook",
+    "HookRunner",
+    "ToolContext",
+    "ToolHandler",
+    "ToolSpec",
+    "execute_tool_call",
+    "tool",
+    "validate_arguments",
+]

runlet/integrations/hooks.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class BaseHook:
+    enabled = True
+
+    def is_enabled(self, context: Any) -> bool:
+        return bool(self.enabled)
+
+    async def before_model_request(self, request: Any, context: Any) -> Any:
+        return request
+
+    async def after_model_response(self, response: Any, context: Any) -> Any:
+        return response
+
+    async def before_tool_call(self, call: Any, context: Any) -> Any:
+        return call
+
+    async def after_tool_result(self, result: Any, context: Any) -> Any:
+        return result
+
+
+class HookRunner:
+    def __init__(self, hooks: list[BaseHook] | tuple[BaseHook, ...]) -> None:
+        self.hooks = tuple(hooks)
+
+    def _enabled_hooks(self, context: Any) -> list[BaseHook]:
+        return [hook for hook in self.hooks if hook.is_enabled(context)]
+
+    async def before_model_request(self, request: Any, context: Any) -> Any:
+        for hook in self._enabled_hooks(context):
+            request = await hook.before_model_request(request, context)
+        return request
+
+    async def after_model_response(self, response: Any, context: Any) -> Any:
+        for hook in self._enabled_hooks(context):
+            response = await hook.after_model_response(response, context)
+        return response
+
+    async def before_tool_call(self, call: Any, context: Any) -> Any:
+        for hook in self._enabled_hooks(context):
+            call = await hook.before_tool_call(call, context)
+        return call
+
+    async def after_tool_result(self, result: Any, context: Any) -> Any:
+        for hook in self._enabled_hooks(context):
+            result = await hook.after_tool_result(result, context)
+        return result

runlet/integrations/tools.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+from runlet.core.messages import ToolCall, ToolResult
+
+
+ToolHandler = Callable[[dict[str, Any], "ToolContext"], Awaitable[str]]
+
+
+def _metadata_map() -> dict[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class ToolContext:
+    run_id: str
+    metadata: dict[str, Any] = field(default_factory=_metadata_map)
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: ToolHandler
+
+
+def _annotation_to_schema(annotation: Any) -> dict[str, str]:
+    if annotation is int:
+        return {"type": "integer"}
+    if annotation is float:
+        return {"type": "number"}
+    if annotation is bool:
+        return {"type": "boolean"}
+    return {"type": "string"}
+
+
+def tool(func: Callable[..., Awaitable[str]]) -> ToolSpec:
+    signature = inspect.signature(func)
+    properties: dict[str, dict[str, str]] = {}
+    required: list[str] = []
+    for name, parameter in signature.parameters.items():
+        required.append(name)
+        properties[name] = _annotation_to_schema(parameter.annotation)
+
+    async def handler(arguments: dict[str, Any], context: ToolContext) -> str:
+        del context
+        return await func(**arguments)
+
+    return ToolSpec(
+        name=func.__name__,
+        description=(func.__doc__ or "").strip(),
+        input_schema={"type": "object", "required": required, "properties": properties},
+        handler=handler,
+    )
+
+
+def validate_arguments(schema: dict[str, Any], arguments: dict[str, Any]) -> None:
+    for name in schema.get("required", []):
+        if name not in arguments:
+            raise ValueError(f"Missing required tool argument: {name}")
+
+
+async def execute_tool_call(
+    call: ToolCall,
+    tools: dict[str, ToolSpec],
+    context: ToolContext,
+) -> ToolResult:
+    if call.name not in tools:
+        raise ValueError(f"Tool not found: {call.name}")
+    spec = tools[call.name]
+    validate_arguments(spec.input_schema, call.arguments)
+    content = await spec.handler(call.arguments, context)
+    return ToolResult(call_id=call.id, name=call.name, content=str(content))

runlet/providers/__init__.py

@@ -0,0 +1,5 @@
+from runlet.providers.openai import OpenAIResponsesProvider
+
+__all__ = [
+    "OpenAIResponsesProvider",
+]