feat: LangGraph integration helpers and example (#33)

* feat(langgraph): add integration helpers, aligned example, and docs

- Add stackone_ai/integrations/langgraph with:

  - to_tool_node, to_tool_executor

  - bind_model_with_tools, create_react_agent

- Add examples/langgraph_tool_node.py matching README snippet (English comments)

- Update README with a minimal LangGraph agent loop (tools_condition) and prereqs

- examples now document installing langgraph and langchain-openai explicitly

* fix: update langgraph integration to use ToolNode instead of deprecated ToolExecutor

- Replace ToolExecutor import with ToolNode in TYPE_CHECKING block
- Update to_tool_executor function to return ToolNode instead of deprecated ToolExecutor
- Add mypy override to ignore missing imports for langgraph modules
- Fix linting issue with blank line whitespace in docstring

* fix: mcp mypy error

* fix: resolve mypy type errors for langgraph ToolNode fallback

- Use class-based fallback instead of assignment for ToolNode in TYPE_CHECKING block
- Add type: ignore for no-redef to handle the intentional redefinition
- This fixes compatibility with Python 3.9 mypy type checking

* fix: update CI to conditionally exclude server.py for Python 3.9

- Run mypy on server.py only for Python 3.10+ where MCP dependencies are available
- Exclude server.py for Python 3.9 to avoid MCP import errors
- This ensures type checking works correctly across all supported Python versions

* fix: configure mypy to handle MCP library syntax errors

- Add comprehensive mypy overrides for mcp module
- Configure mypy to install types automatically in CI
- Exclude .venv directory from type checking
- This resolves pattern matching syntax errors from mcp library dependencies

* fix: pin python 3.10 version

- Remove unused type: ignore comment for try block
- Add type: ignore for MCP decorator functions to handle untyped
decorators
- Set mypy python_version to 3.10 to properly handle pattern matching
syntax
- All mypy checks now pass successfully

Author: ryoppippi

.github/workflows/lint.yml

@@ -34,4 +34,9 @@ jobs:
           args: check .
 
       - name: Run Mypy
-        run: uv run mypy stackone_ai --exclude stackone_ai/server.py
+        run: |
+          if [[ "${{ matrix.python-version }}" == "3.9" ]]; then
+            uv run mypy stackone_ai --exclude stackone_ai/server.py
+          else
+            uv run mypy stackone_ai
+          fi

README.md

@@ -110,6 +110,58 @@ for tool_call in response.tool_calls:
 
 </details>
 
+<details>
+<summary>LangGraph Integration</summary>
+
+StackOne tools convert to LangChain tools, which LangGraph consumes via its prebuilt nodes:
+
+Prerequisites:
+
+```bash
+pip install langgraph langchain-openai
+```
+
+```python
+from langchain_openai import ChatOpenAI
+from typing import Annotated
+from typing_extensions import TypedDict
+
+from langgraph.graph import StateGraph, START, END
+from langgraph.graph.message import add_messages
+from langgraph.prebuilt import tools_condition
+
+from stackone_ai import StackOneToolSet
+from stackone_ai.integrations.langgraph import to_tool_node, bind_model_with_tools
+
+# Prepare tools
+toolset = StackOneToolSet()
+tools = toolset.get_tools("hris_*", account_id="your-account-id")
+langchain_tools = tools.to_langchain()
+
+class State(TypedDict):
+    messages: Annotated[list, add_messages]
+
+# Build a small agent loop: LLM -> maybe tools -> back to LLM
+graph = StateGraph(State)
+graph.add_node("tools", to_tool_node(langchain_tools))
+
+def call_llm(state: dict):
+    llm = ChatOpenAI(model="gpt-4o-mini")
+    llm = bind_model_with_tools(llm, langchain_tools)
+    resp = llm.invoke(state["messages"])  # returns AIMessage with optional tool_calls
+    return {"messages": state["messages"] + [resp]}
+
+graph.add_node("llm", call_llm)
+graph.add_edge(START, "llm")
+graph.add_conditional_edges("llm", tools_condition)
+graph.add_edge("tools", "llm")
+app = graph.compile()
+
+_ = app.invoke({"messages": [("user", "Get employee with id emp123") ]})
+```
+
+</details>
+
 <details>
 <summary>CrewAI Integration (Python 3.10+)</summary>
 

examples/langgraph_tool_node.py

@@ -53,6 +53,7 @@ mcp = [
 examples = [
     "crewai>=0.102.0; python_version>='3.10'",
     "langchain-openai>=0.3.6",
+    "langgraph>=0.2.0",
     "openai>=1.63.2",
     "python-dotenv>=1.0.1",
 ]
@@ -105,7 +106,7 @@ select = [
 ]
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 disallow_untyped_defs = true
 disallow_incomplete_defs = true
 check_untyped_defs = true
@@ -115,7 +116,19 @@ warn_redundant_casts = true
 warn_unused_ignores = true
 warn_return_any = true
 warn_unreachable = true
+exclude = [
+    "^.venv/",
+]
 
 [[tool.mypy.overrides]]
 module = "bm25s"
 ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "langgraph.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "mcp.*"
+ignore_missing_imports = true
+ignore_errors = true

pyproject.toml

@@ -0,0 +1,20 @@
+"""Integration helpers for external frameworks.
+
+Currently includes:
+
+- LangGraph helpers to turn StackOne tools into a `ToolNode` or `ToolExecutor`.
+"""
+
+from .langgraph import (
+    bind_model_with_tools,
+    create_react_agent,
+    to_tool_executor,
+    to_tool_node,
+)
+
+__all__ = [
+    "to_tool_node",
+    "to_tool_executor",
+    "bind_model_with_tools",
+    "create_react_agent",
+]

stackone_ai/integrations/__init__.py

@@ -0,0 +1,94 @@
+"""LangGraph integration helpers.
+
+These utilities convert StackOne tools into LangGraph prebuilt components.
+
+Usage:
+    from stackone_ai import StackOneToolSet
+    from stackone_ai.integrations.langgraph import to_tool_node
+
+    toolset = StackOneToolSet()
+    tools = toolset.get_tools("hris_*", account_id="...")
+    node = to_tool_node(tools)  # langgraph.prebuilt.ToolNode
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.tools import BaseTool
+
+from stackone_ai.models import Tools
+
+if TYPE_CHECKING:  # pragma: no cover - only for typing
+    try:
+        from langgraph.prebuilt import ToolNode
+    except Exception:  # pragma: no cover
+
+        class ToolNode:  # type: ignore[no-redef]
+            pass
+
+
+def _ensure_langgraph() -> None:
+    try:
+        from langgraph import prebuilt as _  # noqa: F401
+    except Exception as e:  # pragma: no cover
+        raise ImportError(
+            "LangGraph is not installed. Install with `pip install langgraph` or "
+            "`pip install 'stackone-ai[examples]'`"
+        ) from e
+
+
+def _to_langchain_tools(tools: Tools | Sequence[BaseTool]) -> Sequence[BaseTool]:
+    if isinstance(tools, Tools):
+        return tools.to_langchain()
+    return tools
+
+
+def to_tool_node(tools: Tools | Sequence[BaseTool], **kwargs: Any) -> Any:
+    """Create a LangGraph `ToolNode` from StackOne tools or LangChain tools.
+
+    Accepts either a `Tools` collection from this SDK or an existing sequence of
+    LangChain `BaseTool` instances and returns a LangGraph `ToolNode` suitable
+    for inclusion in a graph.
+    """
+    _ensure_langgraph()
+    from langgraph.prebuilt import ToolNode  # local import with helpful error
+
+    langchain_tools = _to_langchain_tools(tools)
+    return ToolNode(langchain_tools, **kwargs)
+
+
+def to_tool_executor(tools: Tools | Sequence[BaseTool], **kwargs: Any) -> Any:
+    """Create a LangGraph `ToolNode` from StackOne tools or LangChain tools.
+
+    Note: ToolExecutor has been deprecated in favor of ToolNode.
+    This function now returns a ToolNode for compatibility.
+    """
+    _ensure_langgraph()
+    from langgraph.prebuilt import ToolNode  # local import with helpful error
+
+    langchain_tools = _to_langchain_tools(tools)
+    return ToolNode(langchain_tools, **kwargs)
+
+
+def bind_model_with_tools(model: Any, tools: Tools | Sequence[BaseTool]) -> Any:
+    """Bind tools to an LLM that supports LangChain's `.bind_tools()` API.
+
+    This is a tiny helper that converts a `Tools` collection to LangChain tools
+    and calls `model.bind_tools(...)`.
+    """
+    langchain_tools = _to_langchain_tools(tools)
+    return model.bind_tools(langchain_tools)
+
+
+def create_react_agent(llm: Any, tools: Tools | Sequence[BaseTool], **kwargs: Any) -> Any:
+    """Create a LangGraph ReAct agent using StackOne tools.
+
+    Thin wrapper around `langgraph.prebuilt.create_react_agent` that accepts a
+    `Tools` collection from this SDK.
+    """
+    _ensure_langgraph()
+    from langgraph.prebuilt import create_react_agent as _create
+
+    return _create(llm, _to_langchain_tools(tools), **kwargs)

stackone_ai/integrations/langgraph.py

@@ -16,7 +16,7 @@
         )
     )
 
-try:  # type: ignore[unreachable]
+try:
     import mcp.types as types
     from mcp.server import NotificationOptions, Server
     from mcp.server.models import InitializationOptions
@@ -56,7 +56,7 @@ def tool_needs_account_id(tool_name: str) -> bool:
     return True
 
 
-@app.list_tools()
+@app.list_tools()  # type: ignore[misc]
 async def list_tools() -> list[Tool]:
     """List all available StackOne tools as MCP tools."""
     if not toolset:
@@ -114,7 +114,7 @@ async def list_tools() -> list[Tool]:
         ) from e
 
 
-@app.call_tool()
+@app.call_tool()  # type: ignore[misc]
 async def call_tool(
     name: str, arguments: dict[str, Any]
 ) -> list[TextContent | ImageContent | EmbeddedResource]: