kodeagent.tools

---

This module defines a set of built-in tools for KodeAgent. All tools import necessary dependencies within their function bodies to ensure they are self-contained and can operate in isolated environments. Similarly, all variables are declared locally within the functions.

calculator	Evaluate a single arithmetic expression and return the numeric result.
download_file	Download a file from the internet and save it locally.
extract_as_markdown	Extract content from documents (PDF, DOCX, XLSX, PPTX) as Markdown text.
generate_image	Generate an image based on a text prompt using the specified model.
read_webpage	Fetch and return the main text content from an HTML webpage as clean Markdown.
search_arxiv	Search for academic papers on arXiv.org.
search_web	Search the web using DuckDuckGo and return top results with titles and URLs.
search_wikipedia	Search Wikipedia (only) and return the top search results as Markdown text.
transcribe_audio	Convert audio files to text using Fireworks AI Whisper API.
transcribe_youtube	Get the transcript or subtitles for a YouTube video by its video ID.

This module defines a set of built-in tools for KodeAgent. All tools import necessary dependencies within their function bodies to ensure they are self-contained and can operate in isolated environments. Similarly, all variables are declared locally within the functions.

kodeagent.tools.DEFAULT_TOOLS_IMPORTS = ['ast', 'operator', 're', 'time', 'random', 'ddgs', 'pathlib', 'tempfile', 'requests', 'markitdown', 'bs4', 'wikipedia', 'arxiv', 'youtube_transcript_api', 'urllib.parse', 'os', 'base64', 'litellm']

List of default modules (stdlib and third-party) to be available in tools.

kodeagent.tools.calculator(expression: str) → float | None

Evaluate a single arithmetic expression and return the numeric result. Call this tool once per arithmetic operation. Do NOT try to compute multi-step problems in one call; chain multiple calls instead. Supported operators: +, -, , /, * (exponent), parentheses.

Parameters:

expression – A single arithmetic expression, e.g. “7 + 5” or “12 * 4”. Use ** for exponents, not ^. Returns None for invalid input.

Returns:

The numeric result as a float, or None if the expression is invalid.

kodeagent.tools.download_file(url: str, save_name: str | None = None, save_dir: str | None = None) → dict

Download a file from the internet and save it locally. Use this for downloading images, PDFs, data files, or any binary content.

For reading webpage content as text, use ‘read_webpage’ instead. For extracting content from PDFs/DOCX/XLSX, use ‘extract_as_markdown’ instead.

Examples

• Download an image: url=”https://example.com/photo.jpg”

• Download a dataset: url=”https://example.com/data.csv”, save_dir=”./data”

• Download a PDF: url=”https://example.com/paper.pdf”, save_name=”research.pdf”

Parameters:

• url – The complete URL of the file to download (must start with http:// or https://).

• save_name – Optional filename to save with. If not provided, uses the filename from URL.

• save_dir – Optional directory (path) to save the file. If not provided, saves to a temporary file in a temporary directory. Recommended to specify absolute path.

Returns:

• path: str or None – Final path to the downloaded file.

• orig_name: str or None – Original filename.

• size: str or None – Formatted file size.

• content_type: str or None – Content type of the file.

• error: str or None – Error message if download fails (mutually exclusive with others).

Return type:

A dictionary with the following fields

kodeagent.tools.extract_as_markdown(url_or_path: str, max_length: int = 20000) → str

Extract content from documents (PDF, DOCX, XLSX, PPTX) as Markdown text. Works with both URLs and local file paths.

Supported formats: - PDF files (.pdf) - Word documents (.docx) - Excel spreadsheets (.xlsx) - PowerPoint presentations (.pptx)

For reading HTML web pages, use ‘read_webpage’ instead (faster and cleaner).

Examples

• Extract from PDF: “https://example.com/paper.pdf”

• Extract from local file: “/tmp/document.docx”

• Extract from Excel: “https://example.com/data.xlsx”

Parameters:

• url_or_path – URL or file path to a PDF, DOCX, XLSX, or PPTX file.

• max_length – Optional limit on output length in characters. Use this to truncate very long documents (may lose information).

Returns:

Document content as Markdown text, or an error message if extraction fails.

kodeagent.tools.generate_image(prompt: str, model_name: str) → str

Generate an image based on a text prompt using the specified model. It returns the image URL or the file path of the generated image.

Parameters:

• prompt – Text description of the desired image.

• model_name – The name of the image generation model to use.

Returns:

The file path or URL of the generated image or error message.

kodeagent.tools.read_webpage(url: str, max_length: int = 20000) → str

Fetch and return the main text content from an HTML webpage as clean Markdown. Use this after search_web to read articles, blogs, or documentation. For PDF, DOCX, or XLSX files, use extract_as_markdown tool instead.

Parameters:

• url – The complete URL of the webpage (must start with http:// or https://).

• max_length – Maximum characters to return (default 20000).

Returns:

Clean webpage content as Markdown text, or an error message.

kodeagent.tools.search_arxiv(query: str, max_results: int = 5) → str

Search for academic papers on arXiv.org. The input is a search query. This tool is highly specialized and should be used exclusively for finding scientific and academic papers. It returns the top search results with the title, authors, summary, and a link to the PDF.

Parameters:

• query – The search query string for the paper.

• max_results – The maximum number of search results to return (default is 5).

Returns:

The search results in Markdown format or a message indicating no results were found.

kodeagent.tools.search_web(query: str, max_results: int = 10) → str

Search the web using DuckDuckGo and return top results with titles and URLs. Use this to find current information, news, or general web content. To get full page content from a result URL, call read_webpage tool next (if available).

Parameters:

• query – Search terms (2-5 words work best).

• max_results – Number of results to return (default 10, min 1, max 20).

Returns:

Markdown formatted search results with titles, URLs, and snippets, or an error message.

kodeagent.tools.search_wikipedia(query: str, max_results: int = 3) → str

Search Wikipedia (only) and return the top search results as Markdown text. The input should be a search query. The output will contain the title, summary, and link to the Wikipedia page.

Parameters:

• query – The search query string.

• max_results – The max. no. of search results to consider (default 3).

Returns:

The search results in Markdown format.

kodeagent.tools.transcribe_audio(file_path: str) → str

Convert audio files to text using Fireworks AI Whisper API. The input should be a path to an audio file (e.g., .mp3, .wav, .flac).

Parameters:

file_path – Local file system path to the audio file.

Returns:

The transcript of the audio file as text, or an error message.

kodeagent.tools.transcribe_youtube(video_id: str) → str

Get the transcript or subtitles for a YouTube video by its video ID. The video ID is the part after ‘?v=’ in the URL. For example: https://www.youtube.com/watch?v=aBc4E has video ID ‘aBc4E’.

Parameters:

video_id – YouTube video ID (not the full URL).

Returns:

The transcript text of the video, or an error message if unavailable.