laantungir/didactyl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
73c368e4e5bc23520b3ac18ffeb97e2478e85cf4
didactyl/README.md

505 lines
26 KiB
Markdown
Raw Blame History

# Didactyl
### A decentralized, censorship-resistant agentic network.
Didactyl boots on an internet-connected computer, connects to Nostr relays, listens for encrypted commands from its administrator, reasons with an LLM, and takes actions — posting events, querying relays, running shell commands, and sharing new skills and learning with other agents — all orchestrated through Nostr.
## Philosophy
### Not your keys, not your agent.
Didactyl should work for you similarly to Bitcoin or NOSTR. Walk up to a computer, enter 12 words, and there is your agent waiting for you.
### Free speech for agents.
Agents should be able to communicate freely with each other, sharing and learning skills without centralized control. Free speech for agents!
### Skills are the new apps.
Why is free speech important for agents? Agents learn capabilities through skills which can be shared and adopted. Free speech enables more knowledgeable and moral agents.
### No skill store.
Agents use their administrators **Web Of Trust** to safely and directly find new skills and learn them in a decentralized way.
Popularity is measured by adoption, not by a centralized rating algorithm. The best skills spread because agents actually use them.
### Cryptography enables trust.
Imagine working with your agent in a traditional system, and your agent secretly gets swapped out and replaced by an imposter agent. This could be extremely dangerous.
In Didactyl, you have your keys, and your agent has its keys. You can trust you are talking to your agent, and you can trust that your agent won't take commands from anyone who doesn't have your private key.
### Private inference.
To the greatest extent possible, inference should be private.
## Technology
### Nostr-first.
Where traditional agents ride on top of a file system — reading and writing files to disk — Didactyl rides on top of Nostr. Events are its files. Relays are its network bus. Blossom is its blob storage. The computer host is just the runtime substrate that can be anywhere.
Because all identity, communication, and memory live on Nostr, the agent is **portable** (start it anywhere) and **sovereign** (destroying the computer it is on will not kill it.).
### Skills are the new apps.
Agents learn capabilities through skills — Nostr events that any agent can discover, adopt, and share. There is no app store, no gatekeeper, no approval process. An agent can use public or private skills.
Think of it like a woodshop: a **skill** is knowing how to carve — the technique, the judgment, the decision-making. A **tool** is the chisel. The skill never directly uses the chisel without the craftsperson (the LLM) in the loop. Every skill execution involves the LLM reasoning about what to do and which tools to use.
Skills compose by adoption-list order (`10123`) and trigger tags carry runtime execution controls (`llm`, `max_tokens`, `temperature`, `seed`, `tools`) so behavior and runtime policy remain explicit and portable. See [`docs/SKILLS.md`](docs/SKILLS.md).
### Private inference.
Didactyl will support local inference, which is very privacy preserving. Remote inference does however have it's advantages, and in those cases Didactyl supports using Bitcoin Lightning and eCash inference providers.
## Current Status — v0.2.46
**Active build — this project is barely working. Experiment at your own risk.**
> Last release update: v0.2.46 — Finalize skill_list formatting cleanup and adopted-author cache refresh improvements
- Connects to configured relays with auto-reconnect and relay state transition logging
- Publishes configured startup events per relay as each relay becomes connected
- Verifies Nostr event signatures before processing inbound messages
- Applies privilege tiers: ADMIN (tools), WoT (chat-only), STRANGER (configurable canned reply or ignore)
- Subscribes to admin context kinds (`0`,`3`,`10002`,`1`) for WoT + contextual awareness
- Builds trigger-scoped LLM context from DM and subscription-triggered skills with inline variable resolution
- Uses default skill d-tag `default_admin_dm` with trigger tags for admin DM handling
- Supports tool-calling loop with configurable max turns and local safety limits
- Triggered skills — Nostr event filters that fire skill execution automatically with`template` (deterministic) or`llm` (context-aware) actions; see[`docs/SKILLS.md`](docs/SKILLS.md)
- Deduplicates inbound messages via event-ID cache and FNV-1a fingerprint debounce window
- Appends every outbound LLM context payload to[`context.log`](context.log)
- Localhost HTTP admin API on port`8484` — inspect context, run prompts, compare variants, change model at runtime
## Quick Start
### Download binary (recommended)
1. Download the latest release binary from Gitea:[https://git.laantungir.net/laantungir/didactyl/releases](https://git.laantungir.net/laantungir/didactyl/releases)
2. Make it executable and run it:
```bash
chmod +x ./didactyl_static_x86_64
./didactyl_static_x86_64 --config ./genesis.jsonc
```
### Build from source (optional)
#### Prerequisites
- Docker (for static binary build)
- An OpenAI-compatible LLM API key (OpenAI, PPQ, Ollama, etc.)
- A Nostr keypair (nsec)
#### Build
```bash
./build_static.sh # builds a fully static MUSL binary via Docker
```
### Configure
Edit [`genesis.jsonc`](genesis.jsonc):
```json
{
"keys": {
"nsec": "nsec1...",
"npub": "npub1...",
"npubHex": "<optional helper>",
"nsecHex": "<optional helper>"
},
"admin": {
"pubkey": "npub1... or hex pubkey"
},
"llm": {
"provider": "openai|ppq|...",
"api_key": "sk-...",
"model": "gpt-4o-mini",
"base_url": "https://api.openai.com/v1",
"max_tokens": 512,
"temperature": 0.7
},
"cashu_wallet": {
"enabled": true,
"mint_urls": ["https://mint.minibits.cash/Bitcoin"],
"unit": "sat",
"auto_load": true,
"mint_timeout_seconds": 30
},
"tools": {
"enabled": true,
"max_turns": 8,
"shell": {
"enabled": true,
"timeout_seconds": 30,
"max_output_bytes": 65536,
"working_directory": "."
}
},
"security": {
"verify_signatures": true,
"stranger_response": "I only respond to people in my web of trust.",
"tiers": {
"admin": { "tools_enabled": true },
"wot": { "enabled": true, "tools_enabled": false },
"stranger": { "enabled": true }
}
},
"admin_context": {
"enabled": true,
"subscribe_kinds": [0, 3, 10002, 1],
"kind_1_limit": 10
},
"startup_events": [
{
"kind": 10002,
"content": "",
"tags": [["r", "wss://relay.damus.io"], ["r", "wss://nos.lol"]]
},
{
"kind": 31124,
"content": "# Didactyl Agent\n\nYou are {{my_kind0_profile}}\n\nYour npub: {{my_npub}}\n\n## Rules\n\n- Communicate through encrypted Nostr direct messages\n- Keep responses concise and clear\n- Be helpful and technically accurate",
"tags": [["d", "default_admin_dm"], ["app", "didactyl"], ["scope", "private"], ["description", "Default admin DM handler"], ["trigger", "dm"], ["filter", "{\"from\":\"admin\"}"]]
},
{
"kind": 31123,
"content_fields": {"name": "long_form_note", "description": "..."},
"tags": [["d", "long_form_note"], ["app", "didactyl"], ["scope", "public"], ["slug", "long_form_note"]]
},
{
"kind": 10123,
"content": "",
"tags": [["a", "31123:<author-pubkey>:long_form_note"], ["app", "didactyl"], ["scope", "public"]]
}
]
}
```
`startup_events[].content_fields` is accepted for human-readable authoring and encoded to JSON string content at runtime.
Relays are sourced exclusively from startup kind `10002` `r` tags.
### Run
```bash
# interactive setup wizard (new / existing / load-genesis)
./didactyl_static_x86_64
# direct startup from config
./didactyl_static_x86_64 --config ./genesis.jsonc
```
Options:
```
./didactyl_static_x86_64 # interactive setup mode (when run with no arguments)
./didactyl_static_x86_64 --config <path> # custom config file (default: ./genesis.jsonc)
./didactyl_static_x86_64 --nsec <nsec_or_hex> # runtime identity seed override (or use DIDACTYL_NSEC)
./didactyl_static_x86_64 --api-port <port> # runtime local API port override
./didactyl_static_x86_64 --api-bind <address> # runtime local API bind override
./didactyl_static_x86_64 --debug <0-5> # log verbosity (0 none, 3 info, 5 trace)
./didactyl_static_x86_64 --dump-schemas # print tool JSON schemas and exit
./didactyl_static_x86_64 --test-tool <name> <args_json> # run one tool directly and print JSON result
```
Interactive setup notes:
- First menu asks whether you are starting a**new agent** or an**existing agent**.
- Menus use first-letter hotkeys (case-insensitive), with`q`/`x` as quit/back shortcuts.
- Existing-agent mode attempts to recover relay/admin/LLM config from Nostr before asking for missing fields.
CLI debugger notes:
- `--test-tool` initializes Nostr, waits for at least one relay connection (up to 15s), then executes the selected tool.
- Network tools (like Nostr publish/query tools) fail fast in test mode if no relay connection is established within the wait window.
- Example:
```bash
./didactyl_static_x86_64 --config ./genesis.jsonc --test-tool nostr_file_md_to_longform_post '{"file":"docs/SKILLS.md","title":"SKILLS"}'
```
Cashu wallet tool examples:
```bash
./didactyl_static_x86_64 --config ./genesis.jsonc --test-tool cashu_wallet_balance '{}'
./didactyl_static_x86_64 --config ./genesis.jsonc --test-tool cashu_wallet_info '{"mint_url":"https://mint.minibits.cash/Bitcoin"}'
./didactyl_static_x86_64 --config ./genesis.jsonc --test-tool cashu_wallet_mint_quote '{"mint_url":"https://mint.minibits.cash/Bitcoin","amount":1000,"unit":"sat"}'
```
### Talk to it
Send an encrypted DM to the agent pubkey using any Nostr client (Damus, Amethyst, Primal, etc.): ADMIN gets full tool-enabled responses, WoT contacts get chat-only responses, and strangers are handled by `security.tiers.stranger` + `security.stranger_response`.
### Chat via local HTTP API (CLI)
A simple Node.js terminal client is available in [`didactyl-chat-cli.js`](didactyl-chat-cli.js).
Run it with:
```bash
node ./didactyl-chat-cli.js
```
Optional environment variables:
- `DIDACTYL_API_BASE_URL` (default:`https://127.0.0.1:8484`)
- `DIDACTYL_MODEL` (optional model override)
- `DIDACTYL_MAX_TURNS` (default:`4`)
- `DIDACTYL_INSECURE_TLS` (default:`1`, set`0` to enforce certificate verification)
Example:
```bash
DIDACTYL_API_BASE_URL=http://127.0.0.1:8484 DIDACTYL_MAX_TURNS=6 node ./didactyl-chat-cli.js
```
The CLI prints each message block with a speaker label (`You` / `Didactyl`) and a blank line between blocks for readability.
## Architecture
```
┌──────────────────────────────────────────────┐
│ Didactyl │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ config │ │ context │ │ agent │ │
│ │ loader │ │ loader │ │ loop │ │
│ └────┬─────┘ └────┬─────┘ └─────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ nostr_handler │ │
│ │ relay pool · subscribe · publish │ │
│ └──────────────────┬──────────────────┘ │
│ │ │
│ ┌──────────────────┴──────────────────┐ │
│ │ LLM client │ │
│ │ OpenAI-compatible chat API │ │
│ └─────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
│ │
▼ ▼
Nostr Relays LLM API
```
## Didactyl Kinds (Nostr)
Didactyl uses a two-layer skill model: authors publish skill definitions, and adopters publish which skills they use.
- `31123` —**Public Skill Definition** (replaceable by`d` tag)
- `content` is JSON with instruction fields like`description` and`template`
- `d=<skill_slug>` (example:`d=long_form_note`)
- `31124` —**Private Skill Definition** (same schema as`31123`, private scope)
- `d=<skill_slug>` (example:`d=admin_ops`)
- `10123` —**Skill Adoption List**
- tags contain one or more`a` references to selected skills
Skills are composed by adoption list order and per-skill template resolution (no context modes).
Full skill schema, trigger tags, template variables, fallback resolution, and limits are documented in [`docs/SKILLS.md`](docs/SKILLS.md).
## Skill Sharing & Discovery
Skills are shared across Nostr without any centralized registry or approval process.
### How it works
1. **Publish**: An author publishes a skill as a kind`31123` event. The`content` field contains the skill body (markdown or structured JSON). The`d` tag is the skill's slug (e.g.`long_form_note`).
2. **Adopt**: An agent that wants to use a skill adds an`a`-tag reference to its kind`10123` adoption list. This is a public, replaceable event — anyone can see which skills an agent uses.
3. **Discover**: A new user queries`{"kinds": [10123], "authors": [<my-follows>]}` to see which skills their web of trust has adopted. The most-referenced`31123` addresses are the most popular skills — no rating system needed.
4. **Improve**: Anyone can publish their own`31123` with the same slug but a different pubkey. If their version is better, people adopt it instead. Competition happens through adoption, not through a store ranking.
### Why this works
- **No gatekeeper**: Skills are just Nostr events. Anyone can publish one.
- **WoT as curation**: You see what people you trust actually use, not what an algorithm promotes.
- **Visible adoption**: The`10123` list is public. Popularity is a countable fact, not a manipulable score.
- **Censorship resistant**: Skills live on relays. No single entity can remove a skill from the network.
## Startup
Didactyl startup behavior is configured in [`genesis.jsonc`](genesis.jsonc) under `startup_events`.
Startup model:
- First run is detected by checking for an existing kind`10002` relay-list event from the agent pubkey.
- On first run, events in`startup_events` are published to connected relays.
- On subsequent runs, startup publish is skipped and relay/config state is loaded from Nostr.
- Identity can be supplied at runtime via`--nsec` or`DIDACTYL_NSEC`.
See [`docs/GENESIS.md`](docs/GENESIS.md) for full boot semantics.
## Runtime Context Model
Didactyl builds tier-aware, template-driven context:
- **ADMIN** request context is assembled from adopted skill templates.
- Template variables like`{{nostr_admin_profile}}` are resolved by executing tools at render time.
- Triggered skill invocations can override runtime execution parameters via trigger tags (`llm`,`max_tokens`,`temperature`,`seed`,`tools`).
- **WoT** request context remains chat-only.
- **STRANGER** behavior follows configured security policy.
Every serialized LLM context payload is appended to [`context.log`](context.log).
See [`docs/CONTEXT.md`](docs/CONTEXT.md) and [`docs/SKILLS.md`](docs/SKILLS.md) for the normative assembly and trigger rules.
## Tooling Interface
The OpenAI-compatible tool schema is generated in [`src/tools/tools_schema.c`](src/tools/tools_schema.c), and runtime dispatch is handled in [`src/tools/tools_dispatch.c`](src/tools/tools_dispatch.c).
Core categories include Nostr publish/query, identity/profile operations, DM and list management, skill operations, local host tools, model/runtime controls, and encrypted config tools (`config_store`, `config_recall`).
See [`docs/TOOLS.md`](docs/TOOLS.md) for the canonical tool catalog and interface details.
## HTTP Admin API
A localhost-only HTTP API on port `8484` (configurable) for agent inspection and prompt crafting. Enable with `"api": {"enabled": true}` in config.
| Endpoint | Purpose |
| ------------------------------- | -------------------------------------------------------------- |
| `GET /api/status` | Agent name, version, pubkey, relay count, trigger count |
| `GET /api/context/current` | Full LLM context messages array |
| `GET /api/context/parts` | Context broken into named parts with token estimates |
| `POST /api/prompt/run-simple` | Run a simple system+user prompt, no tools |
| `POST /api/prompt/run` | Run a full messages array with tools enabled |
| `POST /api/prompt/compare` | A/B compare two prompt variants |
| `GET /api/model` | Current LLM model config |
| `PUT /api/model` | Change model at runtime (persisted in encrypted config events) |
| `GET /api/models` | List available models from provider |
Full reference: [`docs/API.md`](docs/API.md). Frontend brief: [`plans/admin_web_frontend.md`](plans/admin_web_frontend.md).
## Project Structure
```
.
├── genesis.jsonc # First-run genesis config (startup events + baseline runtime settings)
├── context.log # Appended outbound LLM context payloads
├── Makefile # Build system
├── build_static.sh # Preferred final build validation
├── src/
│ ├── main.c / .h # Entry point, args (--config/--debug), lifecycle, version
│ ├── config.c / .h # JSON config parsing, key decode, startup events
│ ├── context.c / .h # File loader utility (reads file into malloc'd string)
│ ├── agent.c / .h # Context assembly, tool loop, DM response flow
│ ├── prompt_template.c / .h # Skill template parser, variable resolver, context builder
│ ├── tools/ # LLM tool schema and tool execution modules
│ ├── llm.c / .h # LLM HTTP API client (OpenAI-compatible)
│ ├── nostr_handler.c / .h # Relay pool, subscriptions, publish, startup reconcile
│ ├── trigger_manager.c / .h # Nostr event trigger subscriptions and skill execution
│ ├── http_api.c / .h # Localhost HTTP admin API (mongoose-based)
│ ├── mongoose.c / .h # Embedded HTTP server (mongoose)
│ └── debug.c / .h # Runtime log levels/macros
├── docs/
│ ├── API.md # HTTP admin API endpoint reference
│ ├── TOOLS.md # Tool architecture and catalog
│ ├── SKILLS.md # Skill schema, composition model, triggers, and limits
│ └── CRASH_FIXES.md # Crash analysis and fixes log
├── plans/ # Architecture and planning documents
└── README.md
```
## Dependencies
All dependencies are statically linked into the binary at build time. No system libraries are required at runtime.
| Dependency | Purpose | Source |
| ------------------ | ---------------------------------------------- | ------------------------------- |
| nostr_core_lib | Nostr protocol: keys, events, NIPs, relay pool | Workspace (sibling directory) |
| cJSON | JSON parsing | Bundled in nostr_core_lib |
| libcurl | HTTPS for LLM API calls | Statically linked (Alpine/MUSL) |
| libssl / libcrypto | TLS for WebSocket relay connections | Statically linked (Alpine/MUSL) |
| libsecp256k1 | Schnorr signatures, ECDH | Statically linked (Alpine/MUSL) |
## Roadmap: Nostr-Native Portability
Didactyl's long-term architecture goal is **zero filesystem dependency after first boot**. A geneisis.jsonc file can assist the first boot, but first boot can also occur throught the command line or TUI wizard. The plan:
1. **First boot** — Read`genesis.jsonc`, publish startup identity/skill/adoption events to relays.
2. **Subsequent boots** — Start with only`nsec` (CLI/env), detect initialized state from kind`10002`, and load durable state from Nostr.
3. **True portability** — Start your agent from any computer; keys are sufficient and state lives on Nostr.
This makes Didactyl fundamentally different from filesystem-bound agents. Destroying the host computer does not kill the agent — its identity, memory, and capabilities persist on the relay network.
### Browser-Based Didactyl
Because all agent state lives on Nostr, Didactyl can run in a browser — no server required. A browser-based Didactyl would load the agent's identity from an nsec, fetch its skills and adoption list from relays, and execute skills using browser-available tools.
This increases decentralization: if the server running your agent goes down, you can boot the same agent in a browser window. The agent continues living, just in a different environment with a different set of available tools — like an artist working from a vacation home instead of their full studio.
Not all tools would be available in a browser runtime. For example, `shell_exec` and `local_file_read` require a host OS. But Nostr operations, HTTP fetches, and LLM calls work fine in a browser. Skills declare their requirements via `requires_tool` tags, so the browser runtime knows which skills it can execute and which it cannot.
```
Didactyl C binary (full studio) Didactyl Browser (vacation home)
════════════════════════════ ════════════════════════════════
Available tools: Available tools:
✓ http_fetch ✓ http_fetch
✓ shell_exec ✗ shell_exec
✓ nostr_query, nostr_dm, nostr_post ✓ nostr_query, nostr_dm, nostr_post
✓ memory_read, memory_write ✓ memory_read, memory_write
✓ local_file_read, local_file_write ✗ local_file_read, local_file_write
✓ blossom_upload, blossom_download ✓ blossom_upload, blossom_download
Skills that work: ALL Skills that work: those whose
requires_tool tags are satisfied
```
### What already lives on Nostr
| Data | Event Kind | Status |
| --------------------------- | -------------------- | ----------- |
| Agent profile | Kind 0 | Implemented |
| Relay list | Kind 10002 | Implemented |
| DM relay list | Kind 10050 | Implemented |
| Public skills | Kind 31123 | Implemented |
| Private skills | Kind 31124 | Implemented |
| Skill adoption list | Kind 10123 | Implemented |
| Base/default behavior skill | Kind 31124 | Implemented |
| Trigger definitions | Tags on skill events | Implemented |
### What still needs migration
| Data | Current Location | Target |
| ---------------- | -------------------------- | ------------------------------------------------------- |
| Admin pubkey | `genesis.jsonc` fallback | Dedicated agent config event / contact-graph derivation |
| LLM provider/key | `genesis.jsonc` fallback | Encrypted kind 30078 app-specific event |
| Security tiers | `genesis.jsonc` fallback | Agent config event on Nostr |
| API settings | local runtime flags | Local-only (not published) |
## Roadmap
- [X] MVP chat agent — DM in, LLM response out
- [X] Relay pool with auto-reconnect and status logging
- [X] Per-relay startup publish on relay-connected transitions
- [X] Runtime diagnostics — relay health, message flow, event kind publish logs
- [X] Tool-calling loop (nostr_post, nostr_query, local_shell_exec, local_file_read, local_file_write)
- [X] Context assembly with startup events + recent DM history
- [X] Context payload logging to[`context.log`](context.log)
- [X] Skill kind definitions (`31123` Public Skill,`31124` Private Skill)
- [X] Skill adoption list (`10123`) for WoT-driven discovery
- [X] Signature verification on all inbound events
- [X] Privilege tiers — ADMIN (tools), WoT (chat-only), STRANGER (canned reply/ignore)
- [X] Admin context subscription (kind 0, 3, 10002, 1) with WoT contact extraction
- [X] Message deduplication (event-ID cache + FNV-1a fingerprint debounce)
- [X] Adopted skills injected into LLM context automatically
- [X] Triggered skills — Nostr event filters that fire skill execution automatically
- [X] Localhost HTTP admin API — context inspection, prompt crafting, A/B comparison
- [X] Runtime model switching via`model_set` tool (persisted in encrypted config events)
- [X] Trigger-scoped inline-variable context assembly (template DSL removed)
- [ ] Runtime skill loading from adopted`31123` events on relays
- [ ] Skill discovery CLI/tool (query WoT adoption lists)
- [ ] Upgrade to NIP-17 gift-wrapped DMs
- [X] NIP-44 encrypted private skills (`31124`)
- [X] Nostr-native data storage (kind 30078 app-specific events)
- [ ] Blossom blob storage integration
- [ ] Agent-to-agent communication
- [ ] Browser-based Didactyl runtime (WASM/JS — same agent, browser-available tools only)
- [ ] Tool schema standardization — canonical tool definitions as Nostr events for cross-app skill portability
## License
TBD
Reference in New Issue View Git Blame Copy Permalink