admin-valentin/arcade-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Toolkit docs generator command for Arcade CLI (#414)

Browse source
This commit is contained in:
Renato Byrro 2025-07-18 11:22:21 -03:00 committed by GitHub
parent 1843e411f3
commit d5ae347801
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 1198 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
libs/arcade-cli/arcade_cli/main.py
View file

@ -18,6 +18,7 @@ from rich.text import Text
from tqdm import tqdm
import arcade_cli.worker as worker
from arcade_cli import toolkit_docs
from arcade_cli.authn import LocalAuthCallbackServer, check_existing_login
from arcade_cli.constants import (
CREDENTIALS_FILE_PATH,
@ -738,6 +739,76 @@ def dashboard(
handle_cli_error("Failed to open dashboard", e, debug)
@cli.command(help="Generate Toolkit documentation", rich_help_panel="Tool Development")
def generate_toolkit_docs(
toolkit_name: str = typer.Option(
..., "--toolkit-name", "-n", help="The name of the toolkit to generate documentation for."
),
toolkit_dir: str = typer.Option(
...,
"--toolkit-dir",
"-t",
help="The path to the toolkit root directory.",
),
docs_dir: str = typer.Option(
...,
"--docs-dir",
"-r",
help="The path to the documentation root directory.",
),
docs_section: str = typer.Option(
"",
"--docs-section",
"-s",
help=(
"The section of the docs to generate documentation for. E.g. 'productivity', 'sales'. "
"Defaults to an empty string (generate the docs in the root of /pages/toolkits)"
),
),
openai_model: str = typer.Option(
"gpt-4o-mini",
"--openai-model",
"-m",
help=(
"A few parts of the documentation are generated using OpenAI API. "
"This argument controls which OpenAI model to use. "
"E.g. 'gpt-4o', 'gpt-4o-mini'."
),
show_default=True,
),
openai_api_key: str = typer.Option(
None,
"--openai-api-key",
"-o",
help="The OpenAI API key. If not provided, will get it from the `OPENAI_API_KEY` env var.",
),
tool_call_examples: bool = typer.Option(
False,
"--tool-call-examples",
"-e",
help="Whether to generate tool call examples",
show_default=True,
),
debug: bool = typer.Option(False, "--debug", "-d", help="Show debug information"),
) -> None:
toolkit_docs.generate_toolkit_docs(
console=console,
toolkit_name=toolkit_name,
toolkit_dir=toolkit_dir,
docs_dir=docs_dir,
docs_section=docs_section,
openai_model=openai_model,
openai_api_key=openai_api_key,
tool_call_examples=tool_call_examples,
debug=debug,
)
console.print(
f"Generated documentation for '{toolkit_name}' in '{docs_dir}'",
style="bold green",
)
@cli.callback()
def main_callback(
ctx: typer.Context,

87
libs/arcade-cli/arcade_cli/toolkit_docs/__init__.py Normal file
View file

@ -0,0 +1,87 @@
from functools import partial
import openai
from rich.console import Console
from arcade_cli.toolkit_docs.docs_builder import (
build_example_path,
build_examples,
build_reference_mdx_path,
build_toolkit_mdx,
build_toolkit_mdx_path,
)
from arcade_cli.toolkit_docs.utils import (
get_all_enumerations,
get_list_of_tools,
print_debug_func,
read_toolkit_metadata,
resolve_api_key,
standardize_dir_path,
write_file,
)
def generate_toolkit_docs(
console: Console,
toolkit_name: str,
toolkit_dir: str,
docs_section: str,
docs_dir: str,
openai_model: str,
openai_api_key: str | None = None,
tool_call_examples: bool = True,
debug: bool = False,
) -> None:
openai.api_key = resolve_api_key(openai_api_key, "OPENAI_API_KEY")
if not openai.api_key:
console.print(
"❌ Provide --openai-api-key argument or set the OPENAI_API_KEY environment variable",
style="red",
)
return
print_debug = partial(print_debug_func, debug, console)
docs_dir = standardize_dir_path(docs_dir)
toolkit_dir = standardize_dir_path(toolkit_dir)
print_debug("Reading toolkit metadata")
pip_package_name = read_toolkit_metadata(toolkit_dir)
print_debug(f"Getting list of tools for {toolkit_name} from the local Python environment")
tools = get_list_of_tools(toolkit_name)
print_debug(f"Found {len(tools)} tools")
print_debug("Getting all enumerations potentially used in tool argument specs")
enums = get_all_enumerations(toolkit_dir)
print_debug(f"Building /{toolkit_name.lower()}.mdx file")
reference_mdx, toolkit_mdx = build_toolkit_mdx(
toolkit_dir=toolkit_dir,
tools=tools,
docs_section=docs_section,
enums=enums,
pip_package_name=pip_package_name,
openai_model=openai_model,
)
toolkit_mdx_path = build_toolkit_mdx_path(docs_section, docs_dir, toolkit_name)
write_file(toolkit_mdx_path, toolkit_mdx)
if reference_mdx:
print_debug(f"Building /{toolkit_name.lower()}/reference.mdx file")
reference_mdx_path = build_reference_mdx_path(docs_section, docs_dir, toolkit_name)
write_file(reference_mdx_path, reference_mdx)
else:
print_debug("No Enums referenced by tool interfaces. Skipping reference.mdx file")
if tool_call_examples:
print_debug("Building tool-call examples in Python and JavaScript")
examples = build_examples(print_debug, tools, openai_model)
for filename, example in examples:
example_path = build_example_path(filename, docs_dir, toolkit_name)
write_file(example_path, example)
print_debug(f"Done generating docs for {toolkit_name}")

521
libs/arcade-cli/arcade_cli/toolkit_docs/docs_builder.py Normal file
View file

@ -0,0 +1,521 @@
import json
import os
import pprint
from enum import Enum
from typing import Any, Callable, cast
import openai
from arcade_core import auth as auth_module
from arcade_core.schema import (
ToolAuthRequirement,
ToolDefinition,
ToolInput,
ToolSecretRequirement,
)
from arcade_cli.toolkit_docs.templates import (
ENUM_ITEM,
ENUM_MDX,
ENUM_VALUE,
GENERIC_PROVIDER_CONFIG,
TABBED_EXAMPLES_LIST,
TABLE_OF_CONTENTS,
TABLE_OF_CONTENTS_ITEM,
TOOL_CALL_EXAMPLE_JS,
TOOL_CALL_EXAMPLE_PY,
TOOL_PARAMETER,
TOOL_SPEC,
TOOL_SPEC_SECRETS,
TOOLKIT_FOOTER,
TOOLKIT_FOOTER_OAUTH2,
TOOLKIT_HEADER,
TOOLKIT_PAGE,
WELL_KNOWN_PROVIDER_CONFIG,
)
from arcade_cli.toolkit_docs.utils import (
clean_fully_qualified_name,
find_enum_by_options,
get_toolkit_auth_type,
is_well_known_provider,
pascal_to_snake_case,
)
def build_toolkit_mdx_path(docs_section: str, docs_root_dir: str, toolkit_name: str) -> str:
return os.path.join(
docs_root_dir,
"pages",
"toolkits",
docs_section,
f"{toolkit_name.lower()}.mdx",
)
def build_reference_mdx_path(docs_section: str, docs_root_dir: str, toolkit_name: str) -> str:
return os.path.join(
docs_root_dir,
"pages",
"toolkits",
docs_section,
toolkit_name.lower(),
"reference.mdx",
)
def build_example_path(example_filename: str, docs_root_dir: str, toolkit_name: str) -> str:
return os.path.join(
docs_root_dir,
"public",
"examples",
"integrations",
"toolkits",
toolkit_name.lower(),
example_filename,
)
def build_toolkit_mdx(
toolkit_dir: str,
tools: list[ToolDefinition],
docs_section: str,
enums: dict[str, type[Enum]],
pip_package_name: str,
openai_model: str,
toolkit_header_template: str = TOOLKIT_HEADER,
toolkit_page_template: str = TOOLKIT_PAGE,
) -> tuple[str, str]:
sample_tool = tools[0]
toolkit_name = sample_tool.toolkit.name
toolkit_version = sample_tool.toolkit.version
auth_type = get_toolkit_auth_type(sample_tool.requirements.authorization)
toolkit_dirname = os.path.basename(os.path.dirname(toolkit_dir))
header = toolkit_header_template.format(
toolkit_title=toolkit_name,
description=generate_toolkit_description(
toolkit_name,
[(tool.name, tool.description) for tool in tools],
openai_model,
),
pip_package_name=pip_package_name,
toolkit_dirname=toolkit_dirname,
auth_type=auth_type,
version=toolkit_version,
)
table_of_contents = build_table_of_contents(tools)
footer = build_footer(toolkit_name, pip_package_name, sample_tool.requirements.authorization)
referenced_enums, tools_specs = build_tools_specs(tools, docs_section, enums)
reference_mdx = build_reference_mdx(toolkit_name, referenced_enums) if referenced_enums else ""
return reference_mdx, toolkit_page_template.format(
header=header,
table_of_contents=table_of_contents,
tools_specs=tools_specs,
footer=footer,
)
def build_reference_mdx(
toolkit_name: str,
referenced_enums: list[tuple[str, type[Enum]]],
enum_item_template: str = ENUM_ITEM,
enum_value_template: str = ENUM_VALUE,
enum_mdx_template: str = ENUM_MDX,
) -> str:
enum_items = ""
for enum_name, enum_class in referenced_enums:
enum_items += enum_item_template.format(
enum_name=enum_name,
enum_values=build_enum_values(
enum_class=enum_class,
enum_value_template=enum_value_template,
),
)
return enum_mdx_template.format(
toolkit_name=toolkit_name,
enum_items=enum_items,
)
def build_enum_values(
enum_class: type[Enum],
enum_value_template: str = ENUM_VALUE,
) -> str:
enum_values = ""
for enum_member in enum_class:
enum_values += (
enum_value_template.format(
enum_option_name=enum_member.name,
enum_option_value=enum_member.value,
)
+ "\n"
)
return enum_values
def build_table_of_contents(
tools: list[ToolDefinition],
table_of_contents_item_template: str = TABLE_OF_CONTENTS_ITEM,
table_of_contents_template: str = TABLE_OF_CONTENTS,
) -> str:
tools_items = ""
for tool in tools:
tools_items += table_of_contents_item_template.format(
tool_fully_qualified_name=clean_fully_qualified_name(tool.fully_qualified_name),
description=tool.description.split("\n")[0],
)
return table_of_contents_template.format(tool_items=tools_items)
def build_footer(
toolkit_name: str,
pip_package_name: str,
authorization: ToolAuthRequirement | None,
footer_template: str = TOOLKIT_FOOTER,
oauth2_footer_template: str = TOOLKIT_FOOTER_OAUTH2,
well_known_provider_config_template: str = WELL_KNOWN_PROVIDER_CONFIG,
generic_provider_config_template: str = GENERIC_PROVIDER_CONFIG,
) -> str:
if authorization and authorization.provider_type == "oauth2" and authorization.provider_id:
is_well_known = is_well_known_provider(
provider_id=authorization.provider_id,
auth_module=auth_module,
)
config_template = (
well_known_provider_config_template
if is_well_known
else generic_provider_config_template
)
provider_configuration = config_template.format(
toolkit_name=toolkit_name,
provider_id=authorization.provider_id,
provider_name=authorization.provider_id.capitalize(),
)
return oauth2_footer_template.format(
pip_package_name=pip_package_name,
provider_configuration=provider_configuration,
)
return footer_template.format(toolkit_name=toolkit_name, pip_package_name=pip_package_name)
def build_tools_specs(
tools: list[ToolDefinition],
docs_section: str,
enums: dict[str, type[Enum]],
tool_spec_template: str = TOOL_SPEC,
tool_parameter_template: str = TOOL_PARAMETER,
tool_spec_secrets_template: str = TOOL_SPEC_SECRETS,
) -> tuple[list[tuple[str, type[Enum]]], str]:
tools_specs = ""
referenced_enums = []
for tool in tools:
tool_referenced_enums, tool_spec = build_tool_spec(
tool=tool,
docs_section=docs_section,
enums=enums,
tool_spec_template=tool_spec_template,
tool_parameter_template=tool_parameter_template,
tool_spec_secrets_template=tool_spec_secrets_template,
)
tools_specs += tool_spec
referenced_enums.extend(tool_referenced_enums)
return referenced_enums, tools_specs
def build_tool_spec(
tool: ToolDefinition,
docs_section: str,
enums: dict[str, type[Enum]],
tool_spec_template: str = TOOL_SPEC,
tool_parameter_template: str = TOOL_PARAMETER,
tool_spec_secrets_template: str = TOOL_SPEC_SECRETS,
) -> tuple[list[tuple[str, type[Enum]]], str]:
tabbed_examples_list = TABBED_EXAMPLES_LIST.format(
toolkit_name=tool.toolkit.name.lower(),
tool_name=pascal_to_snake_case(tool.name),
)
referenced_enums, parameters = build_tool_parameters(
tool_input=tool.input,
docs_section=docs_section,
toolkit_name=tool.toolkit.name.lower(),
enums=enums,
tool_parameter_template=tool_parameter_template,
)
secrets = (
build_tool_secrets(
secrets=tool.requirements.secrets,
template=tool_spec_secrets_template,
)
if tool.requirements.secrets
else ""
)
return referenced_enums, tool_spec_template.format(
tool_fully_qualified_name=clean_fully_qualified_name(tool.fully_qualified_name),
tabbed_examples_list=tabbed_examples_list,
description=tool.description.split("\n")[0],
parameters=parameters,
secrets=secrets,
)
def build_tool_secrets(
secrets: list[ToolSecretRequirement],
template: str = TOOL_SPEC_SECRETS,
) -> str:
if not secrets:
return ""
secret_keys_str = "`, `".join([secret.key for secret in secrets])
return template.format(secrets=f"`{secret_keys_str}`")
def build_tool_parameters(
tool_input: ToolInput,
docs_section: str,
toolkit_name: str,
enums: dict[str, type[Enum]],
tool_parameter_template: str = TOOL_PARAMETER,
) -> tuple[list[tuple[str, type[Enum]]], str]:
referenced_enums = []
parameters = ""
for parameter in tool_input.parameters:
schema = parameter.value_schema
if schema.enum:
enum_name, enum_class = find_enum_by_options(enums, schema.enum)
referenced_enums.append((enum_name, enum_class))
param_definition = f"`Enum` [{enum_name}](/toolkits/{docs_section}/{toolkit_name}/reference#{enum_name})"
else:
if schema.inner_val_type:
param_definition = f"`{schema.val_type}[{schema.inner_val_type}]`"
else:
param_definition = f"`{schema.val_type}`"
if parameter.required:
param_definition += ", required"
else:
param_definition += ", optional"
parameters += (
tool_parameter_template.format(
param_name=parameter.name,
definition=param_definition,
description=parameter.description,
)
+ "\n"
)
return referenced_enums, parameters
def build_examples(
print_debug: Callable,
tools: list[ToolDefinition],
openai_model: str,
) -> list[tuple[str, str]]:
examples = []
for tool in tools:
print_debug(f"Generating tool-call examples for {tool.name}")
input_map = generate_tool_input_map(tool, openai_model)
fully_qualified_name = tool.fully_qualified_name.split("@")[0]
examples.append((
f"{pascal_to_snake_case(tool.name)}_example_call_tool.py",
build_python_example(fully_qualified_name, input_map),
))
examples.append((
f"{pascal_to_snake_case(tool.name)}_example_call_tool.js",
build_javascript_example(fully_qualified_name, input_map),
))
return examples
def build_python_example(
tool_fully_qualified_name: str,
input_map: dict[str, Any],
template: str = TOOL_CALL_EXAMPLE_PY,
) -> str:
input_map_str = pprint.pformat(
input_map,
indent=4,
width=100,
compact=False,
sort_dicts=False,
)
input_map_str = "{\n " + input_map_str.lstrip("{ ").rstrip("}") + "\n}" # noqa: B005
return template.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=input_map_str,
)
def build_javascript_example(
tool_fully_qualified_name: str,
input_map: dict,
template: str = TOOL_CALL_EXAMPLE_JS,
) -> str:
return template.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=json.dumps(input_map, indent=2, ensure_ascii=False),
)
def generate_toolkit_description(
toolkit_name: str,
tools: list[tuple[str, str]],
openai_model: str,
) -> str:
response = openai.chat.completions.create(
model=openai_model,
messages=[
{
"role": "system",
"content": (
"You are a helpful assistant. "
"When given a toolkit name and a list of tools, you will generate a "
"short, yet descriptive of the toolkit and the main actions a user "
"or LLM can perform with it.\n\n"
"As an example, here is the Asana toolkit description:\n\n"
"The Arcade Asana toolkit provides a pre-built set of tools for "
"interacting with Asana. These tools make it easy to build agents "
"and AI apps that can:\n\n"
"- Manage teams, projects, and workspaces.\n"
"- Create, update, and search for tasks.\n"
"- Retrieve data about tasks, projects, workspaces, users, etc.\n"
"- Manage task attachments.\n\n"
"And here is a JSON string with the list of tools in the Asana toolkit:\n\n"
"```json\n\n"
'[["AttachFileToTask", "Attaches a file to an Asana task\n\nProvide exactly '
"one of file_content_str, file_content_base64, or file_content_url, never "
"more\nthan one.\n\n- Use file_content_str for text files (will be encoded "
"using file_encoding)\n- Use file_content_base64 for binary files like images, "
'PDFs, etc.\n- Use file_content_url if the file is hosted on an external URL"], '
'["CreateTag", "Create a tag in Asana"], ["CreateTask", "Creates a task in '
"Asana\n\nThe task must be associated to at least one of the following: "
"parent_task_id, project, or\nworkspace_id. If none of these are provided and "
"the account has only one workspace, the task\nwill be associated to that "
"workspace. If the account has multiple workspaces, an error will\nbe raised "
'with a list of available workspaces."], ["GetProjectById", "Get an Asana '
'project by its ID"], ["GetSubtasksFromATask", "Get the subtasks of a task"], '
'["GetTagById", "Get an Asana tag by its ID"], ["GetTaskById", "Get a task by '
'its ID"], ["GetTasksWithoutId", "Search for tasks"], ["GetTeamById", "Get an '
'Asana team by its ID"], ["GetUserById", "Get a user by ID"], ["GetWorkspaceById", '
'"Get an Asana workspace by its ID"], ["ListProjects", "List projects in Asana"], '
'["ListTags", "List tags in an Asana workspace"], ["ListTeams", "List teams in '
'an Asana workspace"], ["ListTeamsTheCurrentUserIsAMemberOf", "List teams in '
'Asana that the current user is a member of"], ["ListUsers", "List users in '
'Asana"], ["ListWorkspaces", "List workspaces in Asana that are visible to the '
'authenticated user"], ["MarkTaskAsCompleted", "Mark a task in Asana as '
'completed"], ["UpdateTask", "Updates a task in Asana"]]\n\n```\n\n'
"Keep the description concise and to the point. The user will provide you with "
"the toolkit name and the list of tools. Generate the description according to "
"the instructions above."
),
},
{
"role": "user",
"content": (
f"The toolkit name is {toolkit_name} and the list of tools is:\n\n"
"```json\n\n"
f"{json.dumps(tools, ensure_ascii=False)}\n\n"
"```\n\n"
"Please generate a description for the toolkit."
),
},
],
temperature=0.0,
max_tokens=2048,
)
response_str = cast(str, response.choices[0].message.content)
return response_str.strip()
def generate_tool_input_map(
tool: ToolDefinition,
openai_model: str,
retries: int = 0,
max_retries: int = 3,
) -> dict[str, Any]:
interface_signature = build_tool_interface_signature(tool)
response = openai.chat.completions.create(
model=openai_model,
messages=[
{
"role": "system",
"content": (
"You are a helpful assistant expert in generating data for documenting "
"sample scripts to calling tools. A tool is a function that is used in "
"context of LLM tool-calling / function-calling.\n\n"
"When given a tool signature with typed arguments, "
"you must return exactly one JSON object (no markdown, no extra text) "
"where each key is an argument name, and each value is a sample value "
"for that argument that would make sense in a sample script to showcase "
"human software engineers how the tool may be called. Generate the "
"argument sample value based on its name and description\n\n"
"Not every single argument must always be present in the input map. "
"In some cases, the tool may require only one of two arguments to be "
"provided, for example. In such cases, an indication will be present "
"either/or in the tool description or the argument description. "
"Always follow such instructions when present in the tool interface.\n\n"
"Keep argument values as short as possible. Values don't have to always "
"be valid. For instance, for file content base64-encoded arguments, "
"you can use a short text or a placeholder like `[file_content]`, it is "
"not necessary that the value is a valid base64-encoded string.\n\n"
"Remember that you MUST RESPOND ONLY WITH A VALID JSON STRING, NO ADDED "
"TEXT. Your response will be json.load'ed, so it must be a valid JSON "
"string."
),
},
{
"role": "user",
"content": (
"Here is a tool interface:\n\n"
f"{interface_signature}\n\n"
"Please provide a sample input map as a JSON object."
),
},
],
temperature=0.0,
max_tokens=1024,
stop=["\n\n"],
)
response_str = cast(str, response.choices[0].message.content)
text = response_str.strip()
try:
return cast(dict[str, Any], json.loads(text))
except json.JSONDecodeError:
if retries < max_retries:
return generate_tool_input_map(tool, openai_model, retries + 1, max_retries)
raise ValueError(f"Failed to generate input map for tool {tool.name}: {text}")
def build_tool_interface_signature(tool: ToolDefinition) -> str:
args = []
for arg in tool.input.parameters:
data: dict[str, Any] = {
"arg_name": arg.name,
"arg_description": arg.description,
"is_arg_required": arg.required,
"arg_type": arg.value_schema.val_type,
}
if arg.value_schema.enum:
data["enum"] = {
"accepted_values": arg.value_schema.enum,
}
args.append(data)
return json.dumps({
"tool_name": tool.name,
"tool_description": tool.description,
"tool_args": args,
})

159
libs/arcade-cli/arcade_cli/toolkit_docs/templates.py Normal file
View file

@ -0,0 +1,159 @@
TOOLKIT_PAGE = """{header}
{table_of_contents}
{tools_specs}
{footer}
"""
TOOLKIT_HEADER = """# {toolkit_title}
import ToolInfo from "@/components/ToolInfo";
import Badges from "@/components/Badges";
import TabbedCodeBlock from "@/components/TabbedCodeBlock";
import TableOfContents from "@/components/TableOfContents";
import ToolFooter from "@/components/ToolFooter";
<ToolInfo
description="Enable agents to interact with {toolkit_title}"
author="Arcade"
codeLink="https://github.com/ArcadeAI/arcade-ai/tree/main/toolkits/{toolkit_dirname}"
{auth_type}
versions={{["{version}"]}}
/>
<Badges repo="arcadeai/{pip_package_name}" />
{description}"""
TABLE_OF_CONTENTS = """## Available Tools
<TableOfContents
headers={{["Tool Name", "Description"]}}
data={{
[{tool_items}
]
}}
/>
<Tip>
If you need to perform an action that's not listed here, you can [get in touch
with us](mailto:contact@arcade.dev) to request a new tool, or [create your
own tools](/home/build-tools/create-a-toolkit).
</Tip>"""
TABLE_OF_CONTENTS_ITEM = '\n ["{tool_fully_qualified_name}", "{description}"],'
TOOL_SPEC = """## {tool_fully_qualified_name}
<br />
{tabbed_examples_list}
{description}
**Parameters**
{parameters}
{secrets}
"""
TOOL_SPEC_SECRETS = """**Secrets**
This tool requires the following secrets: {secrets} (learn how to [configure secrets](/home/build-tools/create-a-tool-with-secrets#supplying-the-secret))
"""
TABBED_EXAMPLES_LIST = """<TabbedCodeBlock
tabs={{[
{{
label: "Call the Tool Directly",
content: {{
Python: ["/examples/integrations/toolkits/{toolkit_name}/{tool_name}_example_call_tool.py"],
JavaScript: ["/examples/integrations/toolkits/{toolkit_name}/{tool_name}_example_call_tool.js"],
}},
}},
]}}
/>"""
TOOL_PARAMETER = "- **{param_name}** ({definition}) {description}"
TOOLKIT_FOOTER = """<ToolFooter pipPackageName="{pip_package_name}" />"""
TOOLKIT_FOOTER_OAUTH2 = """## Auth
{provider_configuration}
<ToolFooter pipPackageName="{pip_package_name}" />
"""
WELL_KNOWN_PROVIDER_CONFIG = "The Arcade {toolkit_name} toolkit uses the [{provider_name} auth provider](/home/auth-providers/{provider_id}) to connect to users' {toolkit_name} accounts. Please refer to the [{provider_name} auth provider](/home/auth-providers/{provider_id}) documentation to learn how to configure auth."
GENERIC_PROVIDER_CONFIG = "The {toolkit_name} toolkit uses the Auth Provider with id `{provider_id}` to connect to users' {toolkit_name} accounts. In order to use the toolkit, you will need to configure the `{provider_id}` auth provider."
TOOL_CALL_EXAMPLE_JS = """import {{ Arcade }} from "@arcadeai/arcadejs";
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
const USER_ID = "{{arcade_user_id}}";
const TOOL_NAME = "{tool_fully_qualified_name}";
// Start the authorization process
const authResponse = await client.tools.authorize({{tool_name: TOOL_NAME}});
if (authResponse.status !== "completed") {{
console.log(`Click this link to authorize: ${{authResponse.url}}`);
}}
// Wait for the authorization to complete
await client.auth.waitForCompletion(authResponse);
const toolInput = {input_map};
const response = await client.tools.execute({{
tool_name: TOOL_NAME,
input: toolInput,
user_id: USER_ID,
}});
console.log(JSON.stringify(response.output.value, null, 2));
"""
TOOL_CALL_EXAMPLE_PY = """import json
from arcadepy import Arcade
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable
USER_ID = "{{arcade_user_id}}"
TOOL_NAME = "{tool_fully_qualified_name}"
auth_response = client.tools.authorize(tool_name=TOOL_NAME)
if auth_response.status != "completed":
print(f"Click this link to authorize: {{auth_response.url}}")
# Wait for the authorization to complete
client.auth.wait_for_completion(auth_response)
tool_input = {input_map}
response = client.tools.execute(
tool_name=TOOL_NAME,
input=tool_input,
user_id=USER_ID,
)
print(json.dumps(response.output.value, indent=2))
"""
ENUM_MDX = """# {toolkit_name} Reference
Below is a reference of enumerations used by some tools in the {toolkit_name} toolkit:
{enum_items}
"""
ENUM_ITEM = """## {enum_name}
{enum_values}
"""
ENUM_VALUE = "- **{enum_option_name}**: `{enum_option_value}`"

158
libs/arcade-cli/arcade_cli/toolkit_docs/utils.py Normal file
View file

@ -0,0 +1,158 @@
import importlib
import inspect
import os
import re
from enum import Enum
from pathlib import Path
from types import ModuleType
from arcade_core.auth import AuthProviderType
from arcade_core.catalog import ToolCatalog
from arcade_core.schema import ToolAuthRequirement, ToolDefinition
from rich.console import Console
from arcade_cli.utils import discover_toolkits
def print_debug_func(debug: bool, console: Console, message: str, style: str = "dim") -> None:
if not debug:
return
console.print(message, style=style)
def standardize_dir_path(dir_path: str) -> str:
dir_path = dir_path.rstrip("/") + "/"
return os.path.expanduser(dir_path)
def resolve_api_key(cli_input_value: str | None, env_var_name: str) -> str | None:
if cli_input_value:
return cli_input_value
elif os.getenv(env_var_name):
return os.getenv(env_var_name)
else:
return None
def write_file(path: str, content: str) -> None:
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
f.write(content)
def read_toolkit_metadata(toolkit_dir: str) -> str:
pyproject_path = os.path.join(toolkit_dir, "pyproject.toml")
with open(pyproject_path) as f:
content = f.read()
project_section_match = re.search(r"\[project\](.*?)(?=\n\[|$)", content, re.DOTALL)
if project_section_match:
project_content = project_section_match.group(1)
name_match = re.search(r'name\s*=\s*["\']([^"\']+)["\']', project_content)
if name_match:
return name_match.group(1).strip()
raise ValueError(f"Could not find package name in '{pyproject_path}'")
def pascal_to_snake_case(text: str) -> str:
return re.sub(r"(?<!^)(?=[A-Z])", "_", text).lower()
def get_list_of_tools(toolkit_name: str) -> list[ToolDefinition]:
tools = []
toolkits = discover_toolkits()
for toolkit in toolkits:
if toolkit.name.casefold() == toolkit_name.casefold():
for module_name, module_tools in toolkit.tools.items():
module = importlib.import_module(module_name)
for tool_name in module_tools:
tool_func = getattr(module, tool_name)
tool = ToolCatalog.create_tool_definition(
tool_func, toolkit.name, toolkit.version, toolkit.description
)
tools.append(tool)
if not tools:
raise ValueError(f"Tools not found for toolkit {toolkit_name}")
return tools
def get_all_enumerations(toolkit_root_dir: str) -> dict[str, type[Enum]]:
enums = {}
toolkit_path = Path(toolkit_root_dir)
for py_file in toolkit_path.rglob("*.py"):
if py_file.name == "__init__.py":
continue
if ".venv" in py_file.parts or "venv" in py_file.parts:
continue
module_name = py_file.stem
spec = importlib.util.spec_from_file_location(module_name, py_file)
if spec is None or spec.loader is None:
continue
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
for name, obj in inspect.getmembers(module):
if (
name not in enums
and inspect.isclass(obj)
and issubclass(obj, Enum)
and obj is not Enum
):
enums[name] = obj
return enums
def get_toolkit_auth_type(requirement: ToolAuthRequirement | None) -> str:
if requirement is None:
return ""
elif requirement.provider_type == AuthProviderType.oauth2.value:
return 'authType="OAuth2"'
elif requirement.provider_type:
return f'authType="{requirement.provider_type}"'
return ""
def find_enum_by_options(
enums: dict[str, type[Enum]], options: list[str]
) -> tuple[str, type[Enum]]:
options_set = set(options)
for enum_name, enum_class in enums.items():
enum_member_values = [member.value for member in enum_class]
if set(enum_member_values) == options_set:
return enum_name, enum_class
raise ValueError(f"No enum found for options: {options_set}")
def is_well_known_provider(
provider_id: str | None,
auth_module: ModuleType,
) -> bool:
if provider_id is None:
return False
for _, obj in inspect.getmembers(auth_module, inspect.isclass):
if not issubclass(obj, auth_module.OAuth2) or obj is auth_module.OAuth2:
continue
try:
instance = obj()
except AttributeError:
continue
provider_id_matches = (
hasattr(instance, "provider_id") and instance.provider_id == provider_id
)
if provider_id_matches:
return True
return False
def clean_fully_qualified_name(fully_qualified_name: str) -> str:
return fully_qualified_name.split("@")[0]

57
libs/tests/cli/toolkit_docs/test_docs_builder.py Normal file
View file

@ -0,0 +1,57 @@
import json
from arcade_cli.toolkit_docs.docs_builder import build_javascript_example, build_python_example
from arcade_cli.toolkit_docs.templates import TOOL_CALL_EXAMPLE_JS, TOOL_CALL_EXAMPLE_PY
def test_build_javascript_example():
tool_fully_qualified_name = "Toolkit.ToolName"
input_map = {
"str_arg": "str_value",
"fake_bool_value": "true",
"fake_bool_phrase": "this is not a true boolean",
"int_arg": 123,
"bool_arg": True,
"list_arg": ["item1", "item2"],
"dict_arg": {"key1": "value1", "key2": "value2"},
"list_of_bool": [True, False],
}
response = build_javascript_example(tool_fully_qualified_name, input_map, TOOL_CALL_EXAMPLE_JS)
assert response == TOOL_CALL_EXAMPLE_JS.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=json.dumps(input_map, indent=2, ensure_ascii=False),
)
def test_build_python_example():
tool_fully_qualified_name = "Toolkit.ToolName"
input_map = {
"str_arg": "str_value",
"fake_bool_value": "true",
"fake_bool_phrase": "this is not a true boolean",
"int_arg": 123,
"bool_arg": True,
"list_arg": ["item1", "item2"],
"dict_arg": {"key1": "value1", "key2": "value2"},
"list_of_bool": [True, False],
}
input_map_str = """{
'str_arg': 'str_value',
'fake_bool_value': 'true',
'fake_bool_phrase': 'this is not a true boolean',
'int_arg': 123,
'bool_arg': True,
'list_arg': ['item1', 'item2'],
'dict_arg': {'key1': 'value1', 'key2': 'value2'},
'list_of_bool': [True, False]
}"""
response = build_python_example(tool_fully_qualified_name, input_map, TOOL_CALL_EXAMPLE_PY)
assert response == TOOL_CALL_EXAMPLE_PY.format(
tool_fully_qualified_name=tool_fully_qualified_name,
input_map=input_map_str,
)

145
libs/tests/cli/toolkit_docs/test_docs_builder_utils.py Normal file
View file

@ -0,0 +1,145 @@
from types import ModuleType
from unittest.mock import MagicMock, patch
import pytest
from arcade_cli.toolkit_docs.utils import (
clean_fully_qualified_name,
get_toolkit_auth_type,
is_well_known_provider,
pascal_to_snake_case,
read_toolkit_metadata,
)
from arcade_core.auth import Asana, AuthProviderType, Google, OAuth2, Slack
from arcade_core.schema import ToolAuthRequirement
@patch("arcade_cli.toolkit_docs.utils.open")
def test_read_toolkit_metadata(mock_open):
sample_pyproject_toml = """
[build-system]
requires = [ "hatchling",]
build-backend = "hatchling.build"
[project]
name = "arcade_jira"
version = "0.1.2"
description = "Arcade.dev LLM tools for interacting with Atlassian Jira"
requires-python = ">=3.10"
dependencies = [
"arcade-tdk>=2.0.0,<3.0.0",
"httpx>=0.27.2,<1.0.0",
]
[[project.authors]]
name = "Arcade"
email = "dev@arcade.dev"
[project.optional-dependencies]
dev = [
"arcade-ai[evals]>=2.0.0,<3.0.0",
"arcade-serve>=2.0.0,<3.0.0",
"pytest>=8.3.0,<8.4.0",
"pytest-cov>=4.0.0,<4.1.0",
"pytest-asyncio>=0.24.0,<0.25.0",
"pytest-mock>=3.11.1,<3.12.0",
"mypy>=1.5.1,<1.6.0",
"pre-commit>=3.4.0,<3.5.0",
"tox>=4.11.1,<4.12.0",
"ruff>=0.7.4,<0.8.0",
]
# Use local path sources for arcade libs when working locally
[tool.uv.sources]
arcade-ai = {path = "../../", editable = true}
arcade-tdk = { path = "../../libs/arcade-tdk/", editable = true }
arcade-serve = { path = "../../libs/arcade-serve/", editable = true }
[tool.mypy]
files = [ "arcade_jira/**/*.py",]
python_version = "3.10"
disallow_untyped_defs = "True"
disallow_any_unimported = "True"
no_implicit_optional = "True"
check_untyped_defs = "True"
warn_return_any = "True"
warn_unused_ignores = "True"
show_error_codes = "True"
ignore_missing_imports = "True"
[tool.pytest.ini_options]
testpaths = [ "tests",]
[tool.coverage.report]
skip_empty = true
[tool.hatch.build.targets.wheel]
packages = [ "arcade_jira",]
"""
mock_open.return_value.__enter__.return_value.read.return_value = sample_pyproject_toml
assert read_toolkit_metadata("path/to/toolkits/jira") == "arcade_jira"
mock_open.assert_called_once_with("path/to/toolkits/jira/pyproject.toml")
@patch("arcade_cli.toolkit_docs.utils.open")
def test_read_toolkit_metadata_missing_project_name(mock_open):
sample_pyproject_toml = """
[build-system]
requires = [ "hatchling",]
build-backend = "hatchling.build"
[project]
version = "0.1.2"
description = "Arcade.dev LLM tools for interacting with Atlassian Jira"
requires-python = ">=3.10"
dependencies = [
"arcade-tdk>=2.0.0,<3.0.0",
"httpx>=0.27.2,<1.0.0",
]
[[project.authors]]
name = "Arcade"
email = "dev@arcade.dev"
"""
mock_open.return_value.__enter__.return_value.read.return_value = sample_pyproject_toml
with pytest.raises(ValueError):
print("\n\n\n", read_toolkit_metadata("path/to/toolkits/jira"))
def test_pascal_to_snake_case():
assert pascal_to_snake_case("PascalCase") == "pascal_case"
assert pascal_to_snake_case("PascalCase_abc") == "pascal_case_abc"
def test_get_toolkit_auth_type_none():
assert get_toolkit_auth_type(requirement=None) == ""
def test_get_toolkit_auth_type_with_provider_type():
requirement = ToolAuthRequirement(provider_type=AuthProviderType.oauth2.value)
assert get_toolkit_auth_type(requirement=requirement) == 'authType="OAuth2"'
requirement = ToolAuthRequirement(provider_type="another_type")
assert get_toolkit_auth_type(requirement=requirement) == 'authType="another_type"'
requirement = ToolAuthRequirement(provider_type="")
assert get_toolkit_auth_type(requirement=requirement) == ""
def test_is_well_known_provider_none():
assert not is_well_known_provider(provider_id=None, auth_module=MagicMock(spec=ModuleType))
def test_is_well_known_provider_matching_provider_id():
mock_auth_module = MagicMock(spec=ModuleType)
mock_auth_module.OAuth2 = OAuth2
mock_auth_module.Google = Google
mock_auth_module.Slack = Slack
assert is_well_known_provider(provider_id=Google().provider_id, auth_module=mock_auth_module)
assert is_well_known_provider(provider_id=Slack().provider_id, auth_module=mock_auth_module)
assert not is_well_known_provider(provider_id=Asana().provider_id, auth_module=mock_auth_module)
assert not is_well_known_provider(provider_id="another_provider", auth_module=mock_auth_module)
def test_clean_fully_qualified_name():
assert clean_fully_qualified_name("Outlook.ListEmails") == "Outlook.ListEmails"
assert clean_fully_qualified_name("Outlook.ListEmails@1.0.0") == "Outlook.ListEmails"