Getting Started with OpenVerb

Learn how to integrate OpenVerb into your app in under 5 minutes. Use your own API keys, your own models, and your own logic.

Installation

JavaScript/TypeScript (npm)

npm install openverb

Or clone from GitHub and import locally:

git clone https://github.com/sgthancel/openverb.git

Python (pip)

pip install openverb

Or clone from GitHub and import locally:

git clone https://github.com/sgthancel/openverb.git

Quick Start Guide

Load the Verb Library

Import and load the OpenVerb core library JSON:

// JavaScript
import { loadVerbLibrary } from 'openverb';

const verbs = loadVerbLibrary('./libraries/openverb.core.json');
console.log(verbs.namespace); // "openverb.core"

# Python
from openverb import load_core

verbs = load_core()
print(verbs['namespace'])  # "openverb.core"

Create an Executor

// JavaScript
import { createExecutor } from 'openverb';

const executor = createExecutor(verbs);

executor.register('create_item', async ({ collection, data }) => {
  // Your actual app logic here
  const id = await db[collection].insert(data);
  return { id, ...data };
});

executor.register('list_items', async ({ collection }) => {
  const items = await db[collection].findAll();
  return { items };
});

# Python
from openverb import Executor

executor = Executor(verbs)

@executor.register('create_item')
async def create_item(collection, data):
    # Your actual app logic here
    id = db[collection].insert(data)
    return {'id': id, **data}

@executor.register('list_items')
async def list_items(collection):
    items = db[collection].find_all()
    return {'items': items}

Connect Your Own LLM

Use your own API key with OpenAI, Anthropic, or any LLM provider:

// JavaScript (OpenAI example)
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    {
      role: 'system',
      content: `You may issue OpenVerb actions using these verbs:
${JSON.stringify(verbs.verbs, null, 2)}

When you want to perform an action, output:
<action>
verb: verb_name
params:
  param1: value1
  param2: value2
</action>`
    },
    {
      role: 'user',
      content: 'Create a new project for Smith Construction'
    }
  ]
});

🔐 Your API key stays on your side. OpenVerb never touches your LLM or data.

Parse and Execute Actions

Extract the action from the AI response and execute it:

// JavaScript
import { parseAction } from 'openverb';

const aiOutput = response.choices[0].message.content;

// AI outputs something like:
// <action>
// verb: create_item
// params:
//   collection: "projects"
//   data:
//     client: "Smith Construction"
// </action>

const action = parseAction(aiOutput);
// { verb: 'create_item', params: { collection: 'projects', data: {...} } }

const result = await executor.run(action);
console.log(result);
// { id: '123', client: 'Smith Construction' }

// Your app updates automatically based on the result!

Complete Working Example

Here's a full end-to-end example showing natural language → verb action → app update:

import OpenAI from 'openai';
import { loadVerbLibrary, createExecutor, parseAction } from 'openverb';

// 1. Load verbs
const verbs = loadVerbLibrary('./libraries/openverb.core.json');

// 2. Create executor and register handlers
const executor = createExecutor(verbs);
const db = { projects: [] };

executor.register('create_item', async ({ collection, data }) => {
  const id = String(db[collection].length);
  const item = { id, ...data };
  db[collection].push(item);
  return item;
});

// 3. Setup AI
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// 4. User input
const userInput = "Create a new project for Smith Construction";

// 5. Get AI response
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    {
      role: 'system',
      content: `You can issue OpenVerb actions. Available verbs: ${JSON.stringify(verbs.verbs)}`
    },
    { role: 'user', content: userInput }
  ]
});

// 6. Parse and execute
const action = parseAction(response.choices[0].message.content);
const result = await executor.run(action);

console.log('Result:', result);
// { id: '0', client: 'Smith Construction' }

console.log('Database:', db.projects);
// [{ id: '0', client: 'Smith Construction' }]