tools.write_python_tool module

Create new Python tool files in the tools/ directory.

This tool writes a new .py file into the tools/ directory and handles all downstream registration automatically:

  1. Syntax validation – parses the code with AST before writing.

  2. File creation – writes the .py file (optionally overwriting).

  3. Markdown docs – generates a Markdown doc from the source and indexes it into the stargazer_docs RAG store so it is immediately searchable. Also creates an RST stub for the next full Sphinx rebuild.

  4. Registry reload – hot-reloads the tool registry so the new tool is callable in the same conversation.

  5. Classifier embeddings – regenerates vector embeddings so the tool can be auto-selected by future prompts.

Requires the UNSANDBOXED_EXEC privilege.

What the LLM actually sees at tool-selection time

The OpenAI function-calling API sends exactly three fields per tool:

  • TOOL_NAME → function.name

  • TOOL_DESCRIPTION → function.description ← the ONLY prose the LLM reads when deciding whether to call a tool

  • TOOL_PARAMETERS → function.parameters

Module docstrings and run() docstrings are NOT sent to the LLM directly. They are auto-extracted into Markdown docs and indexed into the stargazer_docs RAG store, where the LLM can search them later with rag_search.

Documentation best practices

  • TOOL_DESCRIPTION must be self-contained and comprehensive. It is the ONLY text the LLM sees at tool-selection time. Write it so that any future instance of Stargazer can understand the tool’s purpose, constraints, and usage in any context.

  • Function docstrings feed the auto-generated Markdown docs in the stargazer_docs RAG store. Document every public function, parameter, and edge case for deeper reference.

async tools.write_python_tool.run(tool_code, tool_name, description=None, overwrite=False, ctx=None)[source]

Write a new Python tool file and run the full registration pipeline.

Entry point for the write_python_tool tool. It is admin-gated: it first requires the caller to hold UNSANDBOXED_EXEC, then validates and optionally docstring-wraps the source, writes the .py file under tools/, and performs the downstream wiring that makes the tool usable in the same conversation — manifest allow-listing, hot registry reload, Sphinx/RAG doc generation, and classifier-embedding refresh so the tool can be auto-selected later. Failures at any stage degrade gracefully and roll back the file when the manifest update fails.

Interactions and side effects: gates via tools.alter_privileges.has_privilege(); validates with _validate_python_code(); computes the path with _generate_filename() and writes the file with aiofiles; appends to the tool manifest via tool_loader.append_tool_manifest (unlinking the file on failure); generates docs and RAG-indexes them via _generate_docs_stub() (run in a thread); hot-reloads the registry by clearing and re-running tool_loader.load_tools under the registry lock; and regenerates vector embeddings via classifiers.refresh_tool_embeddings.refresh_tool_embeddings. It reads user_id, redis, config, and tool_registry off ctx. Dispatched by the tool loader, which resolves the module’s run attribute (tool_loader.py); no direct internal callers were found.

Parameters:

  • tool_code (str) – Complete Python source for the new tool file; must be non-empty and pass syntax validation.

  • tool_name (str) – Canonical tool name; used to derive the filename and doc paths.

  • description (str) – Optional human-readable description; when tool_code lacks a module docstring, one is auto-prepended from this value.

  • overwrite (bool) – When True, replace an existing file; otherwise an existing file is an error.

  • ctx (ToolContext | None) – Tool context providing user_id, redis, config, and tool_registry for the privilege check, write, and registration steps.

Returns:

A JSON string. On success it reports success, filename, filepath, functions_registered, and the reload_success/ embedding_success/docs_generated flags; on failure it reports success: false with an error (and validation_errors/ warnings when validation failed).

Return type:

str