saf-sdk 0.0.1__tar.gz

saf_sdk-0.0.1/.gitignore

@@ -0,0 +1 @@
+.ref/

saf_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: saf-sdk
+Version: 0.0.1
+Summary: SDK for wrapping third-party agent frameworks (Google ADK, etc.) for LangSmith deployment.
+Requires-Python: >=3.11
+Requires-Dist: langgraph>=0.4.10
+Provides-Extra: google-adk
+Requires-Dist: google-adk>=1.0.0; extra == 'google-adk'
+Requires-Dist: uuid-utils>=0.6; extra == 'google-adk'
+Requires-Dist: wrapt>=1.14; extra == 'google-adk'
+Description-Content-Type: text/markdown
+
+# saf-sdk
+
+> **Note:** `saf-sdk` is a temporary package name. It will be renamed to `deployments-wrap-sdk` later.
+
+SDK for wrapping third-party agent frameworks (Google ADK, Strands, etc.) for deployment on LangSmith.
+
+## Installation
+
+```bash
+pip install saf-sdk[google-adk]
+```
+
+## Quick Start
+
+```python
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from saf_sdk.adk import LangsmithSessionService, wrap
+
+agent = wrap(
+    Runner(
+        agent=Agent(name="my_agent", model="gemini-2.0-flash", instruction="..."),
+        app_name="my_app",
+        session_service=LangsmithSessionService(),
+    )
+)
+```
+
+Export `agent` from your graph module and deploy with `langgraph dev` or LangSmith.

saf_sdk-0.0.1/README.md

@@ -0,0 +1,29 @@
+# saf-sdk
+
+> **Note:** `saf-sdk` is a temporary package name. It will be renamed to `deployments-wrap-sdk` later.
+
+SDK for wrapping third-party agent frameworks (Google ADK, Strands, etc.) for deployment on LangSmith.
+
+## Installation
+
+```bash
+pip install saf-sdk[google-adk]
+```
+
+## Quick Start
+
+```python
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from saf_sdk.adk import LangsmithSessionService, wrap
+
+agent = wrap(
+    Runner(
+        agent=Agent(name="my_agent", model="gemini-2.0-flash", instruction="..."),
+        app_name="my_app",
+        session_service=LangsmithSessionService(),
+    )
+)
+```
+
+Export `agent` from your graph module and deploy with `langgraph dev` or LangSmith.

saf_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# NOTE: "saf-sdk" is a temporary name. Will be renamed to "deployments-wrap-sdk" later.
+name = "saf-sdk"
+dynamic = ["version"]
+description = "SDK for wrapping third-party agent frameworks (Google ADK, etc.) for LangSmith deployment."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "langgraph>=0.4.10",
+]
+
+[project.optional-dependencies]
+google-adk = [
+    "google-adk>=1.0.0",
+    # wrapt is an undeclared transitive dep of langsmith's configure_google_adk;
+    # pinned here so users don't need to install it themselves.
+    "wrapt>=1.14",
+    "uuid-utils>=0.6",
+]
+
+[tool.hatch.version]
+path = "saf_sdk/__init__.py"
+
+[tool.hatch.build]
+include = ["saf_sdk"]
+exclude = ["tests/", "docs/"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "tests/",
+    "docs/",
+    ".github/",
+    "dist/",
+    "dist*/**",
+    ".venv*/**",
+]
+
+[tool.ruff]
+exclude = ["venv", "build", "dist"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "TID251",
+    "TID252",
+    "T20",
+    "TC",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+    "S101",
+    "PLC0415",
+]
+ignore = [
+    "E501",
+    "B006",
+    "B904",
+    "SIM102",
+]
+per-file-ignores = {"tests/**" = ["S101", "B017"]}
+
+[dependency-groups]
+dev = [
+    "ruff>=0.11.12",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.25.0",
+    "pytest-watcher>=0.4.3",
+    "saf-sdk[google-adk]",
+]
+
+[tool.pytest-watcher]
+now = true
+delay = 3
+patterns = ["*.py"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config --durations=5 -vv"
+asyncio_mode = "auto"

saf_sdk-0.0.1/saf_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""SAF SDK (temporary name — will be renamed to deployments-wrap-sdk).
+
+Provides lightweight wrappers for deploying agents from popular frameworks
+(Google ADK, Strands, etc.) to LangSmith without requiring knowledge of
+LangGraph internals.
+"""
+
+__version__ = "0.0.1"

saf_sdk-0.0.1/saf_sdk/adk.py

@@ -0,0 +1,331 @@
+"""Google ADK integration for LangSmith Deployments."""
+
+from __future__ import annotations
+
+import contextvars
+from typing import TYPE_CHECKING, Annotated, Any, Required, TypedDict
+
+from langchain_core.messages import (
+    AIMessage,
+    AIMessageChunk,
+    AnyMessage,
+    HumanMessage,
+)
+from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, LLMResult
+from langchain_core.runnables.config import (
+    RunnableConfig,
+    get_async_callback_manager_for_config,
+)
+from langgraph.config import get_config
+from langgraph.func import entrypoint
+from langgraph.graph.message import add_messages
+from uuid_utils.compat import uuid7
+
+try:
+    from langsmith.integrations.google_adk import configure_google_adk
+    from langsmith.utils import tracing_is_enabled
+except ImportError:
+    configure_google_adk = None  # type: ignore[assignment, misc]
+    tracing_is_enabled = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    from google.adk.agents.run_config import RunConfig, StreamingMode
+    from google.adk.runners import Runner
+    from google.adk.sessions import BaseSessionService, Session
+    from google.adk.sessions.base_session_service import ListSessionsResponse
+    from google.genai.types import Content, Part
+    from langgraph.pregel import Pregel
+
+# Runtime import guard — gives a clear error when google-adk is missing.
+try:
+    from google.adk.agents.run_config import RunConfig, StreamingMode
+    from google.adk.sessions import BaseSessionService, Session
+    from google.adk.sessions.base_session_service import (
+        ListSessionsResponse,
+    )
+    from google.genai.types import Content, Part
+except ImportError as _err:
+    raise ImportError(
+        "google-adk is required for ADK integration. "
+        "Install it with: pip install saf-sdk[google-adk]"
+    ) from _err
+
+__all__ = ["ADKInput", "LangsmithSessionService", "SessionData", "wrap"]
+
+_DEFAULT_USER_ID = "anonymous"
+
+
+class ADKInput(TypedDict, total=False):
+    """Default input schema for ADK agents wrapped with :func:`wrap`.
+
+    ``messages`` is required; ``state_delta`` is optional and passed directly
+    to ``runner.run_async(state_delta=...)`` to update ADK session state.
+    """
+
+    messages: Required[Annotated[list[AnyMessage], add_messages]]
+    state_delta: dict[str, Any]
+
+
+# Per-task session storage: each asyncio task (i.e. each concurrent invocation)
+# gets its own isolated session so concurrent requests don't clobber each other.
+_task_session: contextvars.ContextVar[Session | None] = contextvars.ContextVar(
+    "langsmith_adk_session", default=None
+)
+
+
+class SessionData(TypedDict, total=False):
+    """Serialized ADK session stored in the LangGraph checkpoint."""
+
+    id: str
+    app_name: str
+    user_id: str
+    state: dict[str, Any]
+    events: list[dict[str, Any]]
+    last_update_time: float
+
+
+class LangsmithSessionService(BaseSessionService):
+    """ADK SessionService backed by LangSmith's checkpoint system.
+
+    Use this as the ``session_service`` in your ``Runner``.  Session state is
+    persisted automatically by the deployment's storage backend and survives
+    server restarts.
+
+    Example::
+
+        from saf_sdk.adk import LangsmithSessionService, wrap
+
+        agent = wrap(Runner(
+            agent=my_agent,
+            app_name="my_app",
+            session_service=LangsmithSessionService(),
+        ))
+    """
+
+    # -- checkpoint bridge (called by wrap()) --------------------------------
+
+    def load(self, session_data: SessionData | None) -> None:
+        """Restore session for the current invocation from checkpoint state."""
+        if session_data:
+            _task_session.set(Session.model_validate(session_data))
+        else:
+            _task_session.set(None)
+
+    def dump(self) -> SessionData | None:
+        """Serialize the current session to a dict for checkpointing."""
+        session = _task_session.get()
+        if session is None:
+            return None
+        return session.model_dump(mode="json")
+
+    # -- BaseSessionService interface ----------------------------------------
+
+    async def get_session(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        config: Any = None,
+    ) -> Session | None:
+        session = _task_session.get()
+        if (
+            session is not None
+            and session.app_name == app_name
+            and session.user_id == user_id
+            and session.id == session_id
+        ):
+            return session
+        return None
+
+    async def create_session(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str | None = None,
+        state: dict | None = None,
+    ) -> Session:
+        session = Session(
+            id=session_id or "",
+            app_name=app_name,
+            user_id=user_id,
+            state=state or {},
+            events=[],
+        )
+        _task_session.set(session)
+        return session
+
+    async def delete_session(
+        self, *, app_name: str, user_id: str, session_id: str
+    ) -> None:
+        session = _task_session.get()
+        if (
+            session is not None
+            and session.app_name == app_name
+            and session.user_id == user_id
+            and session.id == session_id
+        ):
+            _task_session.set(None)
+
+    async def list_sessions(
+        self, *, app_name: str, user_id: str | None = None
+    ) -> ListSessionsResponse:
+        session = _task_session.get()
+        if (
+            session is not None
+            and session.app_name == app_name
+            and (user_id is None or session.user_id == user_id)
+        ):
+            return ListSessionsResponse(sessions=[session])
+        return ListSessionsResponse(sessions=[])
+
+
+async def _stream_runner_events(
+    runner: Runner,
+    *,
+    app_name: str,
+    user_id: str,
+    session_id: str,
+    new_message: Content,
+    user_msg_text: str,
+    state_delta: dict[str, Any] | None,
+    config: RunnableConfig,
+) -> tuple[str, str]:
+    """Run the ADK agent and stream token events through LangGraph's callback system.
+
+    Bridges ADK's event stream into ``stream_mode="messages"`` so tokens appear
+    in useStream / Studio.  Returns ``(response_text, msg_id)``.
+    """
+    cm = get_async_callback_manager_for_config(config)
+    msg_id = str(uuid7())
+    llm_runs = await cm.on_chat_model_start(
+        serialized={"name": app_name},
+        messages=[[HumanMessage(content=user_msg_text)]],
+        run_id=uuid7(),
+    )
+
+    _run_config = RunConfig(streaming_mode=StreamingMode.SSE)
+
+    response_parts: list[str] = []
+    final_parts: list[str] = []
+    async for event in runner.run_async(
+        user_id=user_id,
+        session_id=session_id,
+        new_message=new_message,
+        state_delta=state_delta,
+        run_config=_run_config,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    response_parts.append(part.text)
+                    chunk = ChatGenerationChunk(
+                        message=AIMessageChunk(content=part.text, id=msg_id)
+                    )
+                    for llm_run in llm_runs:
+                        await llm_run.on_llm_new_token(part.text, chunk=chunk)
+        else:
+            for part in event.content.parts:
+                if part.text:
+                    final_parts.append(part.text)
+
+    response_text = "".join(response_parts) or "".join(final_parts)
+
+    for llm_run in llm_runs:
+        await llm_run.on_llm_end(
+            LLMResult(
+                generations=[
+                    [
+                        ChatGeneration(
+                            message=AIMessageChunk(content=response_text, id=msg_id)
+                        )
+                    ]
+                ]
+            )
+        )
+
+    return response_text, msg_id
+
+
+def wrap(runner: Runner) -> Pregel:
+    """Wrap a Google ADK Runner for deployment on LangSmith.
+
+    The runner's ``session_service`` must be a ``LangsmithSessionService``.
+
+    Args:
+        runner: A configured ``google.adk.runners.Runner`` instance.
+
+    Returns:
+        A LangGraph-compatible agent ready to be exported from your graph module.
+    """
+    if tracing_is_enabled is not None and tracing_is_enabled():
+        configure_google_adk()
+
+    if not isinstance(runner.session_service, LangsmithSessionService):
+        raise TypeError(
+            f"runner.session_service must be a LangsmithSessionService, "
+            f"got {type(runner.session_service).__name__}. "
+            f"Replace it with: session_service=LangsmithSessionService()"
+        )
+
+    app_name = runner.app_name
+    output_key: str | None = getattr(runner.agent, "output_key", None)
+
+    async def _run(
+        payload: ADKInput,
+        previous: dict | None = None,
+    ) -> entrypoint.final[dict, dict]:
+        config = get_config()
+        configurable = config.get("configurable", {})
+        session_id = configurable.get("thread_id", "default")
+        user_id = configurable.get("langgraph_auth_user_id") or _DEFAULT_USER_ID
+
+        runner.session_service.load(previous or {})
+
+        session = await runner.session_service.get_session(
+            app_name=app_name, user_id=user_id, session_id=session_id
+        )
+        if session is None:
+            await runner.session_service.create_session(
+                app_name=app_name, user_id=user_id, session_id=session_id
+            )
+
+        if not payload["messages"]:
+            raise ValueError("messages must not be empty")
+        user_msg = HumanMessage(content=payload["messages"][-1]["content"]).text
+        new_message = Content(role="user", parts=[Part(text=user_msg)])
+
+        response_text, msg_id = await _stream_runner_events(
+            runner,
+            app_name=app_name,
+            user_id=user_id,
+            session_id=session_id,
+            new_message=new_message,
+            user_msg_text=user_msg,
+            state_delta=payload.get("state_delta"),
+            config=config,
+        )
+
+        session_data = runner.session_service.dump()
+        value: dict[str, Any] = {
+            "messages": [AIMessage(content=response_text, id=msg_id)],
+            "_adk_session": session_data,
+        }
+
+        if output_key and session_data:
+            output_val = session_data.get("state", {}).get(output_key)
+            if output_val is not None:
+                value[output_key] = output_val
+
+        return entrypoint.final(
+            value=value,
+            save=session_data,
+        )
+
+    _run.__name__ = app_name
+    _run.__annotations__["payload"] = ADKInput
+    _run.__annotations__["return"] = entrypoint.final[dict, dict]
+    return entrypoint(name=app_name)(_run)