# OpenVerb Instruction Manual

### *The Universal Action Language for AI-Driven Applications*

*(v1.0 — Core Specification & Usage Guide)*

---

## 1. Introduction

### 1.1 What is OpenVerb?

OpenVerb is a **universal action language** that allows AI models to execute structured actions inside applications.
It provides:

* A simple **JSON action format**
* An optional compact **Symbolic Mode**
* A growing library of **verbs** (actions your app can perform)
* Execution frameworks for common programming languages

OpenVerb turns text generated by AI models into **safe, controlled, and predictable executable actions**.

---

### 1.2 Why OpenVerb?

Modern AI can reason deeply — but it cannot *act* inside your software unless you build complex integrations.

OpenVerb solves this by defining:

> **A universal, model-friendly vocabulary for app capabilities.**

It allows any app to expose verbs such as:

* `create_task`
* `update_file`
* `generate_invoice`
* `send_email`
* `export_map`

AI produces the action → OpenVerb interprets it → your app executes it.

---

## 2. Core Concepts

### 2.1 Verbs

A **verb** is an action your application can perform.

Example:

\`\`\`json
{
  "verb": "create_task",
  "params": {
    "title": "Research OpenVerb",
    "due": "2025-01-10"
  }
}
\`\`\`

---

### 2.2 Verb Libraries

Verb libraries define the **capabilities** of your app.

Example:

\`\`\`json
{
  "create_task": {
    "description": "Create a new task",
    "params": {
      "title": { "type": "string", "required": true },
      "due": { "type": "date", "required": false }
    }
  }
}
\`\`\`

---

### 2.3 Execution Layers

The execution layer is the part of your app that:

1. **Receives** an OpenVerb action
2. **Validates** it
3. **Executes** the underlying logic
4. **Returns results**

Think of it as a command router.

---

### 2.4 Symbolic Mode

A compact shorthand for OpenVerb:

\`\`\`
A "Fix UI bug" D:"2025-02-01"
\`\`\`

Symbol → Verb mapping is defined in the Verb Library.

---

## 3. Installing OpenVerb

There are currently three recommended ways to install and use OpenVerb.

### 3.1 Clone the Core Repository

This is the official way to start:

\`\`\`bash
git clone https://github.com/sgthancel/openverb
\`\`\`

Inside, you'll find:

* `SPEC.md` — the full specification
* `libraries/openverb.core.json` — the core verbs
* `examples/js-executor`
* `examples/python-executor`

---

### 3.2 Use OpenVerb in Node.js (via example executor)

\`\`\`bash
cd examples/js-executor
npm install
npm start
\`\`\`

This will run a JS executor that interprets actions.

---

### 3.3 Use OpenVerb in Python (via example executor)

\`\`\`bash
cd examples/python-executor
python executor.py
\`\`\`

---

## 4. Integrating OpenVerb Into Your App

Here is the process for adding OpenVerb to any app.

---

### 4.1 Step 1 — Define your verbs

Create a file:

\`\`\`
openverb.core.json
\`\`\`

Inside:

\`\`\`json
{
  "create_task": {
    "description": "Create a new task item",
    "params": {
      "title": { "type": "string", "required": true },
      "priority": { "type": "string", "required": false }
    }
  }
}
\`\`\`

---

### 4.2 Step 2 — Build your executor

Your executor processes incoming verbs.

JavaScript example:

\`\`\`javascript
import verbs from "./openverb.core.json";

export function execute(action) {
  const { verb, params } = action;

  switch (verb) {
    case "create_task":
      return createTask(params);
    default:
      throw new Error("Unknown verb: " + verb);
  }
}
\`\`\`

---

### 4.3 Step 3 — Expose your executor to AI

Options:

* REST endpoint (`POST /execute`)
* WebSocket RPC
* Local agent interface
* MCP tool server
* CLI interface

The AI simply sends a verb → you run it.

---

## 5. Using OpenVerb With AI Models

### 5.1 Step 1 — Give the model your Verb Library

Upload or provide a system prompt:

> "This app uses OpenVerb. Here are the available verbs…"

Include the JSON verb definitions.

---

### 5.2 Step 2 — Ask model to generate actions

Example prompt:

> "Using OpenVerb, create a task titled 'Design landing page' with priority high."

Model output:

\`\`\`json
{
  "verb": "create_task",
  "params": {
    "title": "Design landing page",
    "priority": "high"
  }
}
\`\`\`

---

### 5.3 Step 3 — Execute & return results

Your app runs the verb and returns results to the model.

---

## 6. Symbolic Mode

Symbolic Mode is an extension of OpenVerb that uses short symbols instead of long JSON.

### Example:

\`\`\`
A "Write documentation" P:"medium"
\`\`\`

Symbol mapping is defined in:

\`\`\`
openverb.symbols.json
\`\`\`

---

## 7. Best Practices

### Use clear verb names

`create_task`, `add_member`, `generate_invoice`

### Keep parameters simple

Avoid deeply nested structures.

### Always validate actions on the backend

Never trust model output blindly.

### Provide examples in system prompts

Models learn patterns extremely well.

### Separate app verbs from app logic

Verb definitions should be declarative.

---

## 8. OpenVerb Folder Structure (Recommended)

\`\`\`
your-app/
  openverb/
    openverb.core.json
    openverb.symbols.json
    executor.js
  src/
    components/
    pages/
    database/
\`\`\`

---

## 9. Using the OpenVerb Demo App

Clone the demo:

\`\`\`bash
git clone https://github.com/sgthancel/OpenVerbDemo
\`\`\`

This demo shows:

* how verbs connect to UI components
* how AI interacts with your backend
* how to build a fully AI-operable app

---

## 10. Troubleshooting

### Model isn't using verbs

* Provide the verb library in the prompt
* Use few-shot examples
* Add: "Respond using ONLY OpenVerb format"

---

### Execution fails in your app

* Add strict backend validation
* Print incoming verb payloads
* Ensure parameters match your schema

---

### Model mixes natural language with verbs

* Wrap examples with triple backticks
* Add format instructions
* Use Symbolic Mode for cleaner output

---

## 11. Roadmap

* MCP tool-server integration
* OpenVerb Registry
* Verb Marketplace
* IDE extensions
* VS Code actions via verbs
* Official npm + pip packages
* Desktop agent starter kits

---

## 12. License

OpenVerb is fully open-source under MIT license.

---

## Support

For questions, issues, or contributions:

* GitHub: https://github.com/sgthancel/openverb
* Website: https://openverb.dev
* Created by: Roman Hancel (https://romanhancel.com)

---

*Last updated: January 2025*