robocorp[minor]: Add robocorp action server toolkit (#15766)

Co-authored-by: Rihards Gravis <[email protected]>
Co-authored-by: Mikko Korpela <[email protected]>

docs/docs/integrations/providers/robocorp.mdx

@@ -0,0 +1,28 @@
+# Robocorp
+
+>[Robocorp](https://robocorp.com/) helps build and operate Python workers that run seamlessly anywhere at any scale
+
+
+## Installation and Setup
+
+You need to install `langchain-robocorp` python package, as well as the `robocorp-action-server` package to run the action server locally.
+
+```bash
+pip install langchain-robocorp robocorp-action-server
+```
+
+You will need a running instance of Action Server to communicate with from your agent application. You can bootstrap a new project using Action Server `new` command.
+
+```bash
+action-server new
+cd ./your-project-name
+action-server start
+```
+
+## Toolkit
+
+See a [usage example](/docs/integrations/toolkits/robocorp).
+
+```python
+from langchain_robocorp import ActionServerToolkit
+```

docs/docs/integrations/toolkits/robocorp.ipynb

@@ -0,0 +1,132 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e49f1e0d",
+   "metadata": {},
+   "source": [
+    "# Robocorp\n",
+    "\n",
+    "This notebook covers how to get started with [Robocorp Action Server](https://github.com/robocorp/robo/tree/master/action_server/docs) action toolkit and LangChain.\n",
+    "\n",
+    "## Installation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4c3bef91",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Install package and Action Server\n",
+    "%pip install --upgrade --quiet langchain-robocorp robocorp-action-server"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8e2ca5c5",
+   "metadata": {},
+   "source": [
+    "## Action Server setup\n",
+    "\n",
+    "You will need a running instance of Action Server to communicate with from your agent application. You can bootstrap a new project using Action Server `new` command.\n",
+    "\n",
+    "```bash\n",
+    "!action-server new\n",
+    "cd ./your-project-name\n",
+    "action-server start\n",
+    "```\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2b4f3e15",
+   "metadata": {},
+   "source": [
+    "## Environment Setup\n",
+    "\n",
+    "Optionally you can set the following environment variables:\n",
+    "\n",
+    "- `LANGCHAIN_TRACING_V2=true`: To enable LangSmith log run tracing that can also be bind to respective Action Server action run logs. See [LangSmith documentation](https://docs.smith.langchain.com/tracing#log-runs) for more.\n",
+    "\n",
+    "## Usage"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "62e0dbc3",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "from langchain.agents import AgentExecutor, OpenAIFunctionsAgent\n",
+    "from langchain.chat_models import ChatOpenAI\n",
+    "from langchain_core.messages import SystemMessage\n",
+    "from langchain_robocorp import ActionServerToolkit\n",
+    "\n",
+    "# Initialize LLM chat model\n",
+    "llm = ChatOpenAI(model=\"gpt-4\", temperature=0)\n",
+    "\n",
+    "# Initialize Action Server Toolkit\n",
+    "toolkit = ActionServerToolkit(url=\"http://localhost:8080\", report_trace=True)\n",
+    "tools = toolkit.get_tools()\n",
+    "\n",
+    "# Initialize Agent\n",
+    "system_message = SystemMessage(content=\"You are a helpful assistant\")\n",
+    "prompt = OpenAIFunctionsAgent.create_prompt(system_message)\n",
+    "agent = OpenAIFunctionsAgent(llm=llm, prompt=prompt, tools=tools)\n",
+    "\n",
+    "executor = AgentExecutor(agent=agent, tools=tools, verbose=True)\n",
+    "\n",
+    "\n",
+    "executor.invoke(\"What is the current date?\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aa9fbbf5",
+   "metadata": {},
+   "source": [
+    "### Single input tools\n",
+    "\n",
+    "By default `toolkit.get_tools()` will return the actions as Structured Tools. To return single input tools, pass a Chat model to be used for processing the inputs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1dc7db86",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Initialize single input Action Server Toolkit\n",
+    "toolkit = ActionServerToolkit(url=\"http://localhost:8080\")\n",
+    "tools = toolkit.get_tools(llm=llm)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

libs/partners/robocorp/.gitignore

@@ -0,0 +1 @@
+__pycache__

libs/partners/robocorp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

libs/partners/robocorp/Makefile

@@ -0,0 +1,59 @@
+.PHONY: all format lint test tests integration_tests docker_tests help extended_tests
+
+# Default target executed when no arguments are given to make.
+all: help
+
+# Define a variable for the test file path.
+TEST_FILE ?= tests/unit_tests/
+
+test:
+	poetry run pytest $(TEST_FILE)
+
+tests:
+	poetry run pytest $(TEST_FILE)
+
+
+######################
+# LINTING AND FORMATTING
+######################
+
+# Define a variable for Python and notebook files.
+PYTHON_FILES=.
+MYPY_CACHE=.mypy_cache
+lint format: PYTHON_FILES=.
+lint_diff format_diff: PYTHON_FILES=$(shell git diff --relative=libs/partners/action-server --name-only --diff-filter=d master | grep -E '\.py$$|\.ipynb$$')
+lint_package: PYTHON_FILES=langchain_robocorp
+lint_tests: PYTHON_FILES=tests
+lint_tests: MYPY_CACHE=.mypy_cache_test
+
+lint lint_diff lint_package lint_tests:
+	poetry run ruff .
+	poetry run ruff format $(PYTHON_FILES) --diff
+	poetry run ruff --select I $(PYTHON_FILES)
+	mkdir $(MYPY_CACHE); poetry run mypy $(PYTHON_FILES) --cache-dir $(MYPY_CACHE)
+
+format format_diff:
+	poetry run ruff format $(PYTHON_FILES)
+	poetry run ruff --select I --fix $(PYTHON_FILES)
+
+spell_check:
+	poetry run codespell --toml pyproject.toml
+
+spell_fix:
+	poetry run codespell --toml pyproject.toml -w
+
+check_imports: $(shell find langchain_robocorp -name '*.py')
+	poetry run python ./scripts/check_imports.py $^
+
+######################
+# HELP
+######################
+
+help:
+	@echo '----'
+	@echo 'check_imports				- check imports'
+	@echo 'format                       - run code formatters'
+	@echo 'lint                         - run linters'
+	@echo 'test                         - run unit tests'
+	@echo 'tests                        - run unit tests'
+	@echo 'test TEST_FILE=<test_file>   - run all tests in file'

libs/partners/robocorp/README.md

@@ -0,0 +1,13 @@
+# langchain-robocorp
+
+This package contains the LangChain integrations for [Robocorp](https://github.com/robocorp/robocorp).
+
+## Installation
+
+```bash
+pip install -U langchain-robocorp
+```
+
+## Action Server Toolkit
+
+See [ActionServerToolkit](./docs/toolkit.ipynb) for detailed documentation.

libs/partners/robocorp/langchain_robocorp/__init__.py

@@ -0,0 +1,5 @@
+from langchain_robocorp.toolkits import ActionServerToolkit
+
+__all__ = [
+    "ActionServerToolkit",
+]

libs/partners/robocorp/langchain_robocorp/_common.py

@@ -0,0 +1,129 @@
+from dataclasses import dataclass
+from typing import List, Tuple
+
+from langchain_core.utils.json_schema import dereference_refs
+
+
+@dataclass(frozen=True)
+class ReducedOpenAPISpec:
+    """A reduced OpenAPI spec.
+
+    This is reduced representation for OpenAPI specs.
+
+    Attributes:
+        servers: The servers in the spec.
+        description: The description of the spec.
+        endpoints: The endpoints in the spec.
+    """
+
+    servers: List[dict]
+    description: str
+    endpoints: List[Tuple[str, dict]]
+
+
+def reduce_openapi_spec(url: str, spec: dict) -> ReducedOpenAPISpec:
+    """Simplify OpenAPI spec to only required information for the agent"""
+
+    # 1. Consider only GET and POST
+    endpoints = [
+        (route, docs)
+        for route, operation in spec["paths"].items()
+        for operation_name, docs in operation.items()
+        if operation_name in ["get", "post"]
+    ]
+
+    # 2. Replace any refs so that complete docs are retrieved.
+    # Note: probably want to do this post-retrieval, it blows up the size of the spec.
+
+    # 3. Strip docs down to required request args + happy path response.
+    def reduce_endpoint_docs(docs: dict) -> dict:
+        out = {}
+        if docs.get("summary"):
+            out["summary"] = docs.get("summary")
+        if docs.get("operationId"):
+            out["operationId"] = docs.get("operationId")
+        if docs.get("description"):
+            out["description"] = docs.get("description")
+        if docs.get("parameters"):
+            out["parameters"] = [
+                parameter
+                for parameter in docs.get("parameters", [])
+                if parameter.get("required")
+            ]
+        if "200" in docs["responses"]:
+            out["responses"] = docs["responses"]["200"]
+        if docs.get("requestBody"):
+            out["requestBody"] = docs.get("requestBody")
+        return out
+
+    endpoints = [
+        (name, reduce_endpoint_docs(dereference_refs(docs, full_schema=spec)))
+        for name, docs in endpoints
+    ]
+
+    return ReducedOpenAPISpec(
+        servers=[
+            {
+                "url": url,
+            }
+        ],
+        description=spec["info"].get("description", ""),
+        endpoints=endpoints,
+    )
+
+
+def get_required_param_descriptions(endpoint_spec: dict) -> str:
+    """Get an OpenAPI endpoint required parameter descriptions"""
+    descriptions = []
+
+    schema = (
+        endpoint_spec.get("requestBody", {})
+        .get("content", {})
+        .get("application/json", {})
+        .get("schema", {})
+    )
+    properties = schema.get("properties", {})
+
+    required_fields = schema.get("required", [])
+
+    for key, value in properties.items():
+        if "description" in value:
+            if value.get("required") or key in required_fields:
+                descriptions.append(value.get("description"))
+
+    return ", ".join(descriptions)
+
+
+type_mapping = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "object": dict,
+    "array": list,
+    "boolean": bool,
+    "null": type(None),
+}
+
+
+def get_param_fields(endpoint_spec: dict) -> dict:
+    """Get an OpenAPI endpoint parameter details"""
+    fields = {}
+
+    schema = (
+        endpoint_spec.get("requestBody", {})
+        .get("content", {})
+        .get("application/json", {})
+        .get("schema", {})
+    )
+    properties = schema.get("properties", {})
+    required_fields = schema.get("required", [])
+
+    for key, value in properties.items():
+        details = {
+            "description": value.get("description", ""),
+            "required": key in required_fields,
+        }
+        field_type = type_mapping[value.get("type", "string")]
+        fields[key] = (field_type, details)
+
+    return fields