{"id":46055686,"url":"https://github.com/mesopelagique/aikitagenttools","last_synced_at":"2026-03-01T10:01:51.796Z","repository":{"id":341268257,"uuid":"1169501990","full_name":"mesopelagique/AIKitAgentTools","owner":"mesopelagique","description":"A collection of ready-to-use AI tools for \"4D AIKit\", demonstrating how to give LLMs access to external capabilities using the `OpenAIChatHelper` tool registration system.","archived":false,"fork":false,"pushed_at":"2026-02-28T20:21:40.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T22:53:29.563Z","etag":null,"topics":["4d-component","agent"],"latest_commit_sha":null,"homepage":"","language":"4D","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mesopelagique.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["phimage"]}},"created_at":"2026-02-28T19:32:40.000Z","updated_at":"2026-02-28T20:53:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mesopelagique/AIKitAgentTools","commit_stats":null,"previous_names":["mesopelagique/aikitagenttools"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mesopelagique/AIKitAgentTools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mesopelagique%2FAIKitAgentTools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mesopelagique%2FAIKitAgentTools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mesopelagique%2FAIKitAgentTools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mesopelagique%2FAIKitAgentTools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mesopelagique","download_url":"https://codeload.github.com/mesopelagique/AIKitAgentTools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mesopelagique%2FAIKitAgentTools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29966684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T09:33:09.965Z","status":"ssl_error","status_checked_at":"2026-03-01T09:25:48.915Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["4d-component","agent"],"created_at":"2026-03-01T10:01:49.317Z","updated_at":"2026-03-01T10:01:51.785Z","avatar_url":"https://github.com/mesopelagique.png","language":"4D","funding_links":["https://github.com/sponsors/phimage"],"categories":[],"sub_categories":[],"readme":"# AI Kit Agent Tools\n\nA collection of ready-to-use AI tools for [4D AIKit](https://github.com/4d/4D-AIKit), demonstrating how to give LLMs access to external capabilities using the `OpenAIChatHelper` tool registration system.\n\n\u003e **⚠️ These tools interact with real systems (network, file system, shell, database). Read the [Security Guide](Documentation/tools-security.md) before deploying.**\n\n## Tools\n\n| Tool | Class | Description | 4D API |\n|------|-------|-------------|--------|\n| **Web Fetch** | `AIToolWebFetch` | Fetch web page content | `4D.HTTPRequest` |\n| **Search** | `AIToolSearch` | DuckDuckGo web search | `4D.HTTPRequest` |\n| **File System** | `AIToolFileSystem` | Read/write/list files and folders | `4D.File`, `4D.Folder` |\n| **Command** | `AIToolCommand` | Execute shell commands | `4D.SystemWorker` |\n| **Data** | `AIToolData` | Query 4D database via ORDA | `ds`, `dataClass.query()` |\n| **Image** | `AIToolImage` | Generate images from text prompts | `OpenAI.images.generate()` |\n| **Calculator** | `AIToolCalculator` | Evaluate math expressions safely | `ExpressionLanguage` |\n| **Memory** | `AIToolMemory` | Key-value memory store for agents | In-memory / ORDA |\n| **Mail** | `AIToolMail` | Send emails via SMTP | `4D.SMTPTransporter` |\n| **Notification** | `AIToolNotification` | Send OS or webhook notifications | `DISPLAY NOTIFICATION`, `4D.HTTPRequest` |\n\n## Requirements\n\n- [4D AIKit](https://github.com/4d/4D-AIKit) (already declared in `Project/Sources/dependencies.json`)\n- [ExpressionLanguage](https://github.com/mesopelagique/ExpressionLanguage) for `AIToolCalculator` (already declared in `Project/Sources/dependencies.json`)\n- OpenAI API key in `~/.openai` for tests and demo (or edit `TestOpenAI`)\n\n## Quick Start\n\n### 1. Register a tool\n\nEach tool class follows the same pattern — it exposes a `tools` collection and handler methods matching tool names. Registration is a single call:\n\n\u003e Note: this runnable example uses an OpenAI client/helper, so it needs an API key.\n\n```4d\nvar $client:=cs.AIKit.OpenAI.new()\nvar $helper:=$client.chat.create(\"You are a helpful assistant.\"; {model: \"gpt-4o-mini\"})\n$helper.autoHandleToolCalls:=True\n\n// Create and register a tool\nvar $webFetch:=cs.agtools.AIToolWebFetch.new({ \\\n  allowedDomains: [\"*.wikipedia.org\"; \"httpbin.org\"] \\\n})\n$helper.registerTools($webFetch)\n\n// The LLM will automatically use the tool when needed\nvar $result:=$helper.prompt(\"Fetch https://httpbin.org/html and summarize it.\")\n```\n\n### 2. Combine multiple tools\n\n```4d\n// Register all tools on a single helper\n$helper.registerTools(cs.agtools.AIToolWebFetch.new({allowedDomains: [\"*.wikipedia.org\"]}))\n$helper.registerTools(cs.agtools.AIToolSearch.new({maxResults: 3}))\n$helper.registerTools(cs.agtools.AIToolFileSystem.new({allowedPaths: [\"/tmp/sandbox/\"]; readOnly: False}))\n$helper.registerTools(cs.agtools.AIToolCommand.new({allowedCommands: [\"echo\"; \"date\"; \"ls\"]}))\n$helper.registerTools(cs.agtools.AIToolData.new({allowedDataclasses: [\"Product\"]; maxRecords: 20}))\n$helper.registerTools(cs.agtools.AIToolImage.new($client; {outputFolder: Folder(\"/PACKAGE/images\")}))\n$helper.registerTools(cs.agtools.AIToolCalculator.new())\n$helper.registerTools(cs.agtools.AIToolNotification.new())\n\n// The LLM orchestrates across all tools\nvar $result:=$helper.prompt(\"Search for 4D programming, fetch the top result, and save a summary to /tmp/sandbox/summary.md\")\n```\n\nSee `demo_agent` method for a complete multi-tool example.\n\n## Tool Overview\n\n### AIToolWebFetch\n\nFetches web page content via `4D.HTTPRequest`.\n\n```4d\nvar $tool:=cs.agtools.AIToolWebFetch.new({ \\\n  allowedDomains: [\"*.wikipedia.org\"]; \\  // Domain whitelist (⚠️ required for security)\n  timeout: 15; \\\n  maxResponseSize: 50000 \\\n})\n```\n\n**Security:** Domain whitelist, SSRF protection (blocks internal IPs), content-type filtering, response size cap.\n\n### AIToolSearch\n\nSearches the web via DuckDuckGo's HTML endpoint.\n\n```4d\nvar $tool:=cs.agtools.AIToolSearch.new({ \\\n  maxResults: 5; \\\n  timeout: 10 \\\n})\n```\n\n**Security:** Query sanitization, result count cap. Note: search results are untrusted (prompt injection risk).\n\n### AIToolFileSystem\n\nFile and folder operations using `4D.File` / `4D.Folder`.\n\n```4d\nvar $tool:=cs.agtools.AIToolFileSystem.new({ \\\n  allowedPaths: [\"/Users/me/project/\"]; \\  // Sandbox (⚠️ required)\n  deniedPaths: [\"*.env\"; \"*.key\"]; \\\n  readOnly: True \\                          // Disable writes when not needed\n})\n```\n\n**Tools:** `list_directory`, `read_file`, `write_file`, `create_directory`, `delete_file`, `move_item`, `copy_file`  \n**Security:** Path sandbox, path traversal blocking, denied path patterns, read-only mode, file size limit.\n\n### AIToolCommand\n\nShell command execution via `4D.SystemWorker`.\n\n```4d\nvar $tool:=cs.agtools.AIToolCommand.new({ \\\n  allowedCommands: [\"echo\"; \"date\"; \"ls\"; \"cat\"]; \\  // Mandatory whitelist\n  blockMetacharacters: True; \\                         // Block |, ;, \u0026\u0026, etc.\n  timeout: 10 \\\n})\n```\n\n**🔴 Highest risk tool.** No commands execute without an explicit whitelist.  \n**Security:** Mandatory command whitelist, metacharacter blocking, timeout, output size cap.\n\n### AIToolData\n\n4D database access via ORDA.\n\n```4d\nvar $tool:=cs.agtools.AIToolData.new({ \\\n  allowedDataclasses: [\"Product\"; \"Category\"]; \\  // Table whitelist\n  maxRecords: 50; \\\n  readOnly: True \\\n})\n```\n\n**Tools:** `list_dataclasses`, `get_dataclass_info`, `query_data`  \n**Security:** Dataclass whitelist, record limit, read-only by default, attribute projection.\n\n### AIToolImage\n\nGenerate images from text prompts via the OpenAI Images API. Requires an OpenAI client instance.\n\n```4d\nvar $tool:=cs.agtools.AIToolImage.new($client; { \\\n  defaultModel: \"dall-e-3\"; \\\n  allowedSizes: New collection(\"1024x1024\"); \\\n  outputFolder: Folder(\"/PACKAGE/images\") \\\n})\n```\n\n**Tools:** `generate_image`  \n**Security:** Prompt length cap, model/size whitelists, output folder restriction. Note: each call costs API credits.\n\n### AIToolCalculator\n\nSafe math expression evaluation via the [ExpressionLanguage](https://github.com/mesopelagique/ExpressionLanguage) component. A sandboxed alternative to giving the LLM a \"run code\" tool — no access to 4D commands, file I/O, network, or database.\n\n```4d\nvar $tool:=cs.agtools.AIToolCalculator.new({ \\\n  maxExpressionLength: 500 \\\n})\n```\n\n**Tools:** `evaluate_expression`  \n**Security:** 🟢 Lowest risk tool. Sandboxed expression engine — only registered math functions available (abs, round, sqrt, pow, log, sin/cos/tan, min, max, floor, ceil, pi, e, random). No code execution possible.\n\n### AIToolNotification\n\nSend notifications using the local OS notification center (`DISPLAY NOTIFICATION`) or an optional webhook integration.\n\n```4d\nvar $tool:=cs.agtools.AIToolNotification.new({ \\\n  allowedChannels: [\"os\"; \"webhook\"]; \\\n  defaultChannel: \"os\"; \\\n  webhookURL: \"https://hooks.example.com/notify\" \\\n})\n```\n\n**Tools:** `send_notification`  \n**Security:** Channel allowlist, title/text length caps, optional webhook endpoint control.\n\n## Documentation\n\n- **[Security Guide](Documentation/tools-security.md)** — Risk analysis and secure configuration for each tool\n- **API Reference:**\n  - [AIToolWebFetch](Documentation/Classes/AIToolWebFetch.md)\n  - [AIToolSearch](Documentation/Classes/AIToolSearch.md)\n  - [AIToolFileSystem](Documentation/Classes/AIToolFileSystem.md)\n  - [AIToolCommand](Documentation/Classes/AIToolCommand.md)\n  - [AIToolData](Documentation/Classes/AIToolData.md)\n  - [AIToolImage](Documentation/Classes/AIToolImage.md)\n  - [AIToolCalculator](Documentation/Classes/AIToolCalculator.md)\n  - [AIToolNotification](Documentation/Classes/AIToolNotification.md)\n\n## Roadmap\n\n### Future Tools\n\nIdeas for tools that could be added in the future:\n\n| Tool | Description |\n|------|-------------|\n| **Vector Store Conversational Memory** | Store conversation history in a vector store and retrieve relevant parts of past conversations based on the current input. Enables long-term context recall beyond the token window. |\n| **Vector Store Data Retrieval (RAG)** | Look up entities from a dataclass using vector embeddings and semantic similarity — a Retrieval-Augmented Generation pattern. The agent asks a natural language question, and the tool returns the most relevant records. |\n| **Planning** | Break a user goal into ordered, executable steps for an autonomous agent. Sends the goal to an LLM client that returns a structured plan the agent can follow step by step. |\n| **Calendar** | Read/create/update calendar events via 4D NetKit (Google Calendar, Microsoft Outlook). |\n| **Gmail / Outlook Mail** | Extend `AIToolMail` with 4D NetKit OAuth2 providers for Gmail and Microsoft 365, replacing raw SMTP. |\n| **PTY Shell** | Execute bash commands in a real terminal PTY session using [PTY4DPlugin](https://github.com/mesopelagique/PTY4DPlugin). Unlike `AIToolCommand` (which uses `4D.SystemWorker`), a PTY session supports interactive programs, ANSI output, and persistent shell state across calls — closer to a human developer's terminal experience. |\n\n\u003e Contributions and ideas welcome — open an issue or PR.\n\n### Others\n\n**Human-in-the-Loop Authorization**: Require explicit user approval before sensitive operations (for example: deleting a file, writing outside allowed paths, or requesting access to a new directory not in the whitelist).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmesopelagique%2Faikitagenttools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmesopelagique%2Faikitagenttools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmesopelagique%2Faikitagenttools/lists"}