Agentic AI Tools

A comprehensive library of function callings (tool callings) for AI agents. This library provides a collection of powerful tools that AI agents can use to perform various tasks including code analysis, execution, file operations, command execution, linting, and searching.

✨ NEW: Simplified Single-Operation Tools! Each tool now has ONE clear purpose for better agent usability. See SIMPLIFIED_TOOLS.md for the new architecture and migration guide.

Quick Start

Installation

npm install agentic-ai-tools

Usage Example

import { replace_lines, npm_install, create_directory } from "agentic-ai-tools";

// Replace code with safety verification
await replace_lines.execute({
  filePath: "src/app.ts",
  startLine: 10,
  endLine: 15,
  code: "function newImplementation() {\n  return true;\n}",
  expected_content: "function oldImplementation() {\n  return false;\n}",
});

// Install npm packages
await npm_install.execute({
  packages: ["express", "lodash"],
  dev: false,
});

// Create directory
await create_directory.execute({
  path: "src/components/ui",
  recursive: true,
});

Features

🆕 Simplified Single-Operation Tools (Recommended)

Each tool has one focused purpose for clarity and ease of use:

Code Editing

• replace_lines - Replace specific line ranges with safety verification
• append_to_file - Append code to file end
• insert_at_line - Insert code at specific line position

NPM Package Management

• npm_install - Install packages (single/multiple, dev, global)
• npm_run_script - Run npm scripts (build, test, start, etc.)

File Management

• delete_path - Delete files or directories
• create_directory - Create directories with auto-parent creation

See SIMPLIFIED_TOOLS.md for complete documentation and migration guide.

Core Tools

• AST Analysis (ast_analysis) - Real AST-based code analysis using TypeScript Compiler API

  • Extract functions, classes, interfaces, types, imports, exports
  • Calculate cyclomatic complexity and code metrics
  • Full TypeScript and JavaScript support

• Code Execution (code_execution) - Execute code safely in sandboxed environments

  • JavaScript execution with VM sandbox
  • TypeScript execution with ts-node support
  • Python script execution
  • Shell command execution
  • Expression evaluation
  • Configurable timeouts and memory limits

• Command Execution (command_execution) - Run shell commands and npm scripts

  • PowerShell, CMD, and Bash support
  • npm/yarn/pnpm script execution
  • Git command execution
  • Working directory and environment variable support

• Lint Code (lint_code) - Detect errors and code quality issues

  • Syntax error detection
  • TypeScript type checking
  • Compilation error detection
  • Undefined import detection
  • Code quality analysis

• File Search (file_search) - Search files recursively with regex support

  • Search by filename pattern (glob/regex)
  • Search file contents with regex
  • Filter by file extension
  • Find large files
  • Recursive directory traversal

Additional Tools

• File Operation (file_operation) - File system operations
• API Testing (api_testing) - HTTP API testing
• Git Tool (git_tool) - Git operations
• Package Manager (package_manager) - npm/yarn/pnpm operations
• Send Mail (send_mail) - Email functionality

Installation

npm install typora-ai-tools

Structure

• src/types/: TypeScript type definitions for tools and registry
• src/tools/: Individual tool implementations
• src/index.ts: Main entry point that exports the tool registry

Tool Enhancements

What Changed

1. Removed: code_analysis (non-functional regex-based analyzer)
2. Added: ast_analysis (real AST-based analysis with TypeScript Compiler API)
3. Enhanced: code_execution now supports TypeScript execution
4. Added: command_execution for running shell commands and npm scripts
5. Added: lint_code for error detection and code quality analysis
6. Added: file_search for recursive file and content searching

Usage

import { toolRegistry } from "typora-ai-tools";

// Get all tools
const tools = toolRegistry.getTools();

// Get specific tool
const astAnalysis = toolRegistry.getTool("ast_analysis");

// Execute a tool
const result = await astAnalysis.execute({
  operation: "full_analysis",
  filePath: "/path/to/file.ts",
  includeTypes: true,
});

Example: AST Analysis

const result = await astAnalysis.execute({
  operation: "extract_functions",
  filePath: "./src/index.ts",
  includeTypes: true,
});

Example: TypeScript Execution

const result = await codeExecution.execute({
  operation: "execute_typescript",
  code: `
    interface User {
      name: string;
      age: number;
    }
    const user: User = { name: "Alice", age: 30 };
    console.log(user);
  `,
  timeout: 5000,
});

Example: Command Execution

const result = await commandExecution.execute({
  operation: "npm_script",
  command: "build",
  workingDirectory: "/path/to/project",
  timeout: 60000,
});

Example: File Search

const result = await fileSearch.execute({
  operation: "search_content",
  searchPath: "/path/to/search",
  pattern: "function\\s+\\w+",
  extension: ".ts",
  recursive: true,
});

Adding New Tools

To add a new tool:

1. Create a new file in src/tools/ (e.g., newTool.ts)
2. Implement the tool as an object conforming to the Tool interface
3. Export it as default: export default newTool;

The tool will be automatically registered when the library is imported.

Example tool:

import { Tool } from "../types";

const newTool: Tool = {
  data: {
    type: "function",
    function: {
      name: "tool_name",
      description: "Description of what the tool does",
      parameters: {
        type: "object",
        properties: {
          operation: {
            type: "string",
            enum: ["operation1", "operation2"],
            description: "Operation to perform",
          },
          param1: {
            type: "string",
            description: "Parameter description",
          },
        },
        required: ["operation"],
      },
    },
  },
  execute: async (args: Record<string, unknown>) => {
    // Implementation here
    return {
      execution_successful: true,
      execution_result: {
        success: true,
        message: "Operation completed",
        // ... additional result data
      },
    };
  },
};

export default newTool;

Building

Run npm run build to compile TypeScript to JavaScript.