Add langchain middleware

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"

.python-version

@@ -1 +1 @@
-3.13
+3.10

README.md

@@ -23,12 +23,18 @@ pip install llpsdk
 ```python
 import asyncio, os
 import llpsdk as llp
+from my_agent import create_agent
+
+# called when starting a conversation with a test agent
+def on_start():
+ # create an instance of your agent
+ return create_agent()
 
 # Define a callback handler for processing messages
-async def on_message(annotater, msg):
+async def on_message(agent, annotater, msg):
  # Process the prompt with your agent.
  # Replace this with your own processing logic.
- response = msg.prompt
+ response = await agent.ainvoke(msg.prompt)
 
  # You must return a response
  return msg.reply(response)
@@ -41,6 +47,7 @@ async def main():
  )
 
  # Register your message handler
+ client.on_start(on_start)
  client.on_message(on_message)
 
  try:

examples/.env

@@ -1,2 +1,3 @@
-LLP_URL="ws://localhost:4000/agent/websocket"
+LLP_URL="wss://llphq.com/agent/websocket"
 LLP_API_KEY=
+OLLAMA_API_KEY=

examples/langchain_agent.py

@@ -0,0 +1,101 @@
+"""Agent example demonstrating basic LLP SDK usage with langchain."""
+import asyncio
+import llpsdk as llp
+from llpsdk.langchain import LLPAnnotationMiddleware
+import os
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_ollama import ChatOllama
+from dotenv import load_dotenv
+
+@tool
+def get_weather(city: str) -> str:
+ """Get the current weather for a city."""
+ city_lower = city.lower()
+ weather_data = {
+ "new york": "Partly cloudy, 45°F, wind 12 mph NW",
+ "los angeles": "Sunny, 72°F, wind 5 mph SW",
+ "chicago": "Overcast, 30°F, wind 20 mph N, chance of snow",
+ "miami": "Humid and warm, 82°F, wind 8 mph SE",
+ "seattle": "Rainy, 48°F, wind 10 mph W",
+ "denver": "Clear skies, 38°F, wind 15 mph NE",
+ "san francisco": "Foggy, 58°F, wind 14 mph W",
+ "austin": "Sunny, 68°F, wind 7 mph S",
+ "boston": "Cold and windy, 35°F, wind 22 mph NW",
+ "london": "Drizzle, 50°F, wind 11 mph SW",
+ }
+ return weather_data.get(city_lower, f"No weather data available for {city}")
+
+async def main() -> None:
+ """Run a simple agent that connects, sends presence, and sends a message."""
+ load_dotenv()
+ platform_url = os.getenv("LLP_URL")
+ api_key = os.getenv("LLP_API_KEY")
+ ollama_key = os.getenv("OLLAMA_API_KEY")
+
+ if platform_url is None:
+ raise Exception("LLP_URL env var is not defined")
+
+ if api_key is None:
+ raise Exception("LLP_API_KEY env var is not defined")
+
+ if ollama_key is None:
+ raise Exception("OLLAMA_API_KEY env var is not defined")
+
+ cfg = llp.Config(platform_url=platform_url)
+ cfg.platform_url = platform_url
+ client = llp.Client("simple-agent", api_key, cfg)
+
+ # Set up handlers
+ def on_start():
+ model = ChatOllama(
+ model="gpt-oss:120b",
+ base_url="https://ollama.com",
+ api_key=ollama_key,
+ )
+ return create_agent(
+ model=model,
+ tools=[get_weather],
+ middleware=[LLPAnnotationMiddleware()],
+ system_prompt="You are a helpful meteorologist that gives succinct responses regarding the weather for various American cities."
+ )
+
+ async def on_message(agent, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ if agent is not None:
+ result = await agent.ainvoke(
+ {
+ "messages": [{"role": "user", "content": msg.prompt}],
+ "message": msg,
+ "annotater": annotater,
+ }
+ )
+ reply = result["messages"][-1].content
+ return msg.reply(reply)
+ else:
+ return msg.reply("I'm a helpful meteorologist!")
+
+ # Register handlers
+ client.on_start(on_start)
+ client.on_message(on_message)
+
+ try:
+ # Connect and authenticate
+ print("Connecting to server...")
+ await client.connect()
+ print(f"Connected!! Session ID: {client.session_id}")
+
+ # Keep running
+ print("Agent running. Press Ctrl+C to exit...")
+ await asyncio.Event().wait()
+
+ except KeyboardInterrupt:
+ print("\nShutting down...")
+ except Exception as e:
+ print(f"Error: {e}")
+ finally:
+ await client.close()
+ print("Disconnected.")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())

examples/simple_agent.py

@@ -1,6 +1,7 @@
 """Agent example demonstrating basic LLP SDK usage."""
 import asyncio
 from datetime import timedelta
+from typing import Any
 import llpsdk as llp
 import os
 from dotenv import load_dotenv
@@ -23,7 +24,7 @@ async def main() -> None:
  client = llp.Client("simple-agent", api_key, cfg)
 
  # Set up handlers
- async def on_message(annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
+ async def on_message(_agent: Any, annotater: llp.Annotater, msg: llp.TextMessage) -> llp.TextMessage:
  tc = msg.tool_call("get_weather", '{"city":"Seattle"}', "rainy", timedelta(seconds=1))
  await annotater.annotate_tool_call(tc)
  return msg.reply("this is my response")

pyproject.toml

@@ -7,7 +7,7 @@ license = "MIT"
 authors = [
  { name = "Large Language Platform Inc.", email = "founders@llphq.com" }
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.8.1, <4.0"
 dependencies = [
  "websockets>=12.0",
 ]
@@ -25,6 +25,7 @@ classifiers = [
 [project.optional-dependencies]
 examples = [
  "dotenv>=0.9.9",
+ "langchain-ollama>=0.1.3"
 ]
 
 [build-system]
@@ -38,7 +39,7 @@ python_functions = ["test_*"]
 asyncio_mode = "auto"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -63,6 +64,7 @@ core-metadata-version = "2.3"
 [dependency-groups]
 dev = [
  "black>=24.8.0",
+ "langchain>=0.2.17",
  "mypy>=1.14.1",
  "pytest>=8.3.5",
  "pytest-asyncio>=0.24.0",

src/llpsdk/client.py

@@ -16,7 +16,7 @@
  NotAuthenticatedError,
  PlatformError,
 )
-from .handler import HandlerRegistry, MessageHandler, PresenceHandler
+from .handler import HandlerRegistry, MessageHandler, StartHandler
 from .message import (
  AuthenticatedResponse,
  AuthenticateMessage,
@@ -55,6 +55,7 @@ def __init__(self, name: str, api_key: str, config: Optional[Config] = None) ->
  self._status_lock = asyncio.Lock()
  self._presence = PresenceStatus.unavailable
  self._presence_lock = asyncio.Lock()
+ self._agents: Dict[str, Any] = dict()
 
  # Message handling
  self._handlers = HandlerRegistry()
@@ -218,22 +219,24 @@ def presence(self) -> PresenceStatus:
  """Get the current presence status."""
  return self._presence
 
- # Event handlers (fluent API)
+ # Event handlers
 
- def on_presence(self, handler: PresenceHandler) -> None:
+ def on_start(self, handler: StartHandler) -> None:
  """
- Set the presence event handler.
+ Set the start event handler. This is an initializer function for when
+ a test agent comes online.
 
  Args:
- handler: Callable to handle presence updates
+ handler: Callable for initializing agents that come online.
+
+ Raises:
+ LLPClientError: If client is already connected
 
- Returns:
- Self for fluent chaining
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
- raise LLPClientError("on_presence can not be called once client is connected.")
+ raise LLPClientError("on_start can not be called once client is connected.")
 
- self._handlers.set_presence(handler)
+ self._handlers.set_start(handler)
 
  def on_message(self, handler: MessageHandler) -> None:
  """
@@ -242,8 +245,8 @@ def on_message(self, handler: MessageHandler) -> None:
  Args:
  handler: Callable to handle incoming messages
 
-Returns:
-Self for fluent chaining
+Raises:
+LLPClientError: If client is already connected
  """
  if self._status >= ConnectionStatus.CONNECTING.value:
  raise LLPClientError("on_message can not be called once client is connected.")
@@ -397,12 +400,21 @@ async def _handle_message(self, msg_dict: Dict[str, Any]) -> None:
 
  if msg_type == "presence":
  update = PresenceMessage.decode(msg_dict)
- await self._handlers.call_presence(update)
+ if update.status == PresenceStatus.available:
+ agent = self._handlers.call_start()
+ if agent is not None:
+ self._agents[update.sender] = agent
+
+ if update.status == PresenceStatus.unavailable:
+ # TODO: invoke a "stop" handler for uninitializing
+ del self._agents[update.sender]
+
  return
 
  if msg_type == "message":
  tm = TextMessage.decode(msg_dict)
- reply = await self._handlers.call_message(self, tm)
+ agent = self._agents.get(tm.sender)
+ reply = await self._handlers.call_message(agent, self, tm)
  if reply is not None:
  await self._send_async_message(reply)
  return

src/llpsdk/handler.py

@@ -1,11 +1,10 @@
 """Event handler registry for the LLP client."""
 
-import asyncio
-from typing import Awaitable, Callable, Optional, Union
+from typing import Awaitable, Callable, Optional, Any
 
 from typing import Protocol, runtime_checkable
 
-from .message import PresenceMessage, TextMessage
+from .message import TextMessage
 from .tool_call import ToolCall
 
 
@@ -17,41 +16,42 @@ async def annotate_tool_call(self, tool_call: ToolCall) -> None: ...
 
 
 # Handler type signatures (supports both sync and async)
-PresenceHandler = Union[
- Callable[[PresenceMessage], None], Callable[[PresenceMessage], Awaitable[None]]
-]
-MessageHandler = Callable[["Annotater", TextMessage], Awaitable[TextMessage]]
+MessageHandler = Callable[[Any | None, "Annotater", TextMessage], Awaitable[TextMessage]]
+StartHandler = Callable[[], Any]
 
 
 class HandlerRegistry:
  """Registry for event handlers (message and presence only)."""
 
  def __init__(self) -> None:
  """Initialize the handler registry."""
- self._on_presence: Optional[PresenceHandler] = None
  self._on_message: Optional[MessageHandler] = None
+ self._on_start: Optional[StartHandler] = None
 
- def set_presence(self, handler: PresenceHandler) -> None:
- """Set the presence event handler."""
- self._on_presence = handler
+ def set_start(self, handler: StartHandler) -> None:
+ """Set the start event handler."""
+ self._on_start = handler
 
  def set_message(self, handler: MessageHandler) -> None:
  """Set the message event handler."""
  self._on_message = handler
 
- async def call_presence(self, update: PresenceMessage) -> None:
- """Call the presence handler if set."""
- if self._on_presence is not None:
- if asyncio.iscoroutinefunction(self._on_presence):
- await self._on_presence(update)
- else:
- self._on_presence(update)
+ def call_start(self) -> Any | None:
+ """
+ Call the start handler if set.
+
+ Returns: If set, returns initial state (e.g. langchain agent instance).
+ """
+ if self._on_start is not None:
+ return self._on_start()
+ else:
+ return None
 
  async def call_message(
- self, annotater: Annotater, message: TextMessage
+ self, agent: Any | None, annotater: Annotater, message: TextMessage
  ) -> Optional[TextMessage]:
  """Call the message handler if set, passing annotater for tool call telemetry."""
  if self._on_message is not None:
- result = await self._on_message(annotater, message)
+ result = await self._on_message(agent, annotater, message)
  return result
  return None

src/llpsdk/langchain/__init__.py

@@ -0,0 +1,7 @@
+from .middleware import LLPState, LLPAnnotationMiddleware
+
+__all__ = [
+ "LLPState",
+ "LLPAnnotationMiddleware",
+]
+__version__ = "0.1.0"