135 lines
5.5 KiB
Markdown
135 lines
5.5 KiB
Markdown
# Didactyl — Tools
|
|
|
|
See also: [SKILLS.md](SKILLS.md)
|
|
|
|
## Overview
|
|
|
|
Didactyl is a **Nostr-first sovereign AI agent** that receives commands via encrypted DMs, reasons with an LLM, and takes actions through **tools**.
|
|
|
|
This document describes the tools architecture: what tools are, how they are exposed to the model, how execution loops work, what tool categories exist, and how access is gated.
|
|
|
|
---
|
|
|
|
## What Tools Are
|
|
|
|
Tools are in the agent's hands — the chisels in the woodshop. They are hardcoded C functions that the LLM can invoke during a conversation to take actions in the world.
|
|
|
|
A **skill** teaches the agent *how* to carve — the technique, the judgment, the decision-making. A **tool** is the chisel — the physical capability. The skill never directly uses the chisel without the craftsperson (the LLM) in the loop. If you want a hardcoded program that runs without reasoning, that's a tool or an external program — not a skill.
|
|
|
|
## How Tools Work
|
|
|
|
1. Admin sends a DM to didactyl
|
|
2. The agent builds an LLM request with the message, context, and a JSON schema of all available tools
|
|
3. The LLM decides whether to call a tool or respond directly
|
|
4. If a tool is called, didactyl executes it and feeds the result back to the LLM
|
|
5. The loop repeats until the LLM produces a final text response
|
|
6. The response is sent back as a DM
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Admin
|
|
participant Agent as Didactyl Agent Loop
|
|
participant LLM as LLM API
|
|
participant Tools as Tool Registry
|
|
|
|
Admin->>Agent: Encrypted DM
|
|
Agent->>LLM: messages + tool schemas
|
|
|
|
loop Until final answer
|
|
LLM->>Agent: tool_call request
|
|
Agent->>Tools: dispatch tool
|
|
Tools->>Agent: result JSON
|
|
Agent->>LLM: tool result + continue
|
|
end
|
|
|
|
LLM->>Agent: final text response
|
|
Agent->>Admin: Encrypted DM reply
|
|
```
|
|
|
|
---
|
|
|
|
## Tool Categories
|
|
|
|
### Nostr Event & Messaging Tools
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `nostr_post` | Publish a Nostr event to connected relays |
|
|
| `nostr_delete` | Request deletion of one or more previously published events (NIP-09 kind 5) |
|
|
| `nostr_react` | React to a Nostr event with like/dislike/emoji (NIP-25 kind 7) |
|
|
| `nostr_query` | Query events from relays using a Nostr filter |
|
|
| `nostr_dm_send` | Send a NIP-04 encrypted DM |
|
|
| `nostr_dm_send_nip17` | Send a private DM using NIP-17 gift wrap protocol |
|
|
|
|
### Nostr Identity & Utility Tools
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `nostr_profile_get` | Look up a Nostr profile (kind 0 metadata) by pubkey |
|
|
| `nostr_nip05_lookup` | Look up or verify a NIP-05 identifier (`user@domain`) |
|
|
| `nostr_encode` | Encode a Nostr entity into `nostr:` URI (`npub`, `note`, `nprofile`, `nevent`, `naddr`) |
|
|
| `nostr_decode` | Decode a Nostr bech32/`nostr:` URI into components |
|
|
| `nostr_relay_status` | Get connection status and statistics for all relays |
|
|
| `nostr_relay_info` | Fetch NIP-11 relay information document |
|
|
| `nostr_encrypt` | Encrypt plaintext using NIP-44 for a recipient |
|
|
| `nostr_decrypt` | Decrypt NIP-44 ciphertext from a sender |
|
|
| `nostr_list_manage` | Add/remove tag tuples in replaceable list events (NIP-51 style) |
|
|
|
|
### Skills & Trigger Tools
|
|
|
|
These tools manage skill and trigger lifecycle; skill semantics and trigger execution details are documented in [SKILLS.md](SKILLS.md).
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `skill_create` | Create or update a skill definition as kind `31123`/`31124` and optionally auto-adopt it |
|
|
| `skill_list` | List this agent's published skills, optionally filtered by scope |
|
|
| `skill_adopt` | Adopt a skill by adding its address to kind `10123` adoption list |
|
|
| `skill_remove` | Remove a skill address from kind `10123` adoption list |
|
|
| `skill_search` | Search public skills by query/author and optionally rank by adoption popularity |
|
|
| `trigger_list` | List active triggered skills and their runtime status |
|
|
|
|
### LLM / Model Management Tools
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `model_get` | Get current active LLM runtime configuration (excluding API key) |
|
|
| `model_set` | Update active LLM configuration and persist it to `config.jsonc` |
|
|
| `model_list` | List available model IDs using provider OpenAI-compatible `/models` endpoint |
|
|
|
|
### System & Runtime Tools
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `agent_version` | Return current Didactyl version and metadata from build macros |
|
|
| `local_http_fetch` | Fetch HTTP(S) resources with optional method, headers, timeout, and body |
|
|
| `local_shell_exec` | Execute a shell command and return stdout/stderr |
|
|
| `local_file_read` | Read a local file as text from the configured working directory |
|
|
| `local_file_write` | Write text content to a local file in the configured working directory |
|
|
| `tool_list` | List available tools with name, description, and JSON parameter schema |
|
|
|
|
### Content Publishing Conveniences
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `nostr_post_readme` | Publish `README.md` as kind `30023` with deterministic d-tag `readme.md` |
|
|
| `nostr_file_md_to_longform_post` | Read a markdown file and publish it as kind `30023` longform post (defaults d-tag to lowercase filename) |
|
|
|
|
---
|
|
|
|
## Security Model
|
|
|
|
Tool access is gated by sender tier:
|
|
|
|
| Tier | Identity | Tools | Response |
|
|
|------|----------|-------|----------|
|
|
| **ADMIN** | Configured admin pubkey | All tools | Full LLM with context |
|
|
| **WOT** | In admin's kind 3 contact list | None | Chat-only LLM |
|
|
| **STRANGER** | Anyone else | None | Configurable static response |
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- Skill definitions, adoption, triggers, and autonomous activation: [SKILLS.md](SKILLS.md)
|
|
- Combined index page: [TOOLS_AND_SKILLS.md](TOOLS_AND_SKILLS.md)
|