Actions System

Actions are the universal unit of work in Open Genie. They are named, parameterized operations that can be triggered by the AI, cron jobs, webhooks, or direct API calls.

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  AI Tool Call │     │  Cron Job    │     │  Webhook     │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            ↓
                  ┌─────────────────┐
                  │  Action Registry │
                  │                 │
                  │  execute(name,  │
                  │    params)      │
                  └────────┬────────┘
                           ↓
                  ┌─────────────────┐
                  │  Action Handler  │
                  │  (function)      │
                  └────────┬────────┘
                           ↓
                  ┌─────────────────┐
                  │  ActionResult    │
                  │  { output, err } │
                  └─────────────────┘

Action Registry (lib/actions/registry.ts)

The registry is a singleton that stores all registered actions and provides methods to execute them.

Registering an Action

import { actionRegistry } from "@/lib/actions/registry";

actionRegistry.register({
  name: "my_action",
  description: "Does something useful",
  parameters: {
    type: "object",
    properties: {
      input: { type: "string", description: "The input value" },
    },
    required: ["input"],
  },
  handler: async (params) => {
    // Do work...
    return { output: `Processed: ${params.input}` };
  },
});

Executing an Action

const result = await actionRegistry.execute("my_action", { input: "hello" });
// result = { output: "Processed: hello" }
// or
// result = { error: "Something went wrong" }

Converting to Ollama Tools

const tools = actionRegistry.toOllamaTools();
// Returns OpenAI-compatible tool definitions for function calling

Listing Actions

const actions = actionRegistry.list();
// [{ name, description, parameters }, ...]

Built-in Actions

Open Genie ships with 8 built-in actions registered at boot:

send_notification

Send a push notification to connected devices.

Parameter	Type	Required	Description
title	string	yes	Notification title
body	string	yes	Notification body
target	string	no	"all", "phones", "tablets", or a specific device ID
level	string	no	"info", "warning", "critical"

play_media

Send a media playback command to a device.

Parameter	Type	Required	Description
mediaId	string	yes	ID of the media file
deviceId	string	yes	Target device

capture_camera

Trigger an immediate camera capture and vision analysis.

Parameter	Type	Required	Description
cameraId	string	yes	Camera to capture from

Returns the vision analysis result.

ollama_query

Send a direct query to Ollama outside of a conversation context.

Parameter	Type	Required	Description
prompt	string	yes	The query to send
model	string	no	Override the default model

read_memory

Query the memory system.

Parameter	Type	Required	Description
category	string	no	Filter by category
search	string	no	Full-text search

update_memory

Create or update a memory entry.

Parameter	Type	Required	Description
category	string	yes	Memory category
key	string	yes	Entry key
value	string	yes	Entry value

fetch_url

Make an HTTP request to an external URL.

Parameter	Type	Required	Description
url	string	yes	Target URL
method	string	no	HTTP method (default: "GET")
body	object	no	Request body (for POST/PUT)
headers	object	no	Custom headers

create_reminder

Create a reminder with optional recurrence.

Parameter	Type	Required	Description
title	string	yes	Reminder text
dueAt	string	yes	ISO 8601 datetime
repeat	string	no	Repeat schedule (cron expression or keyword)

REST API

Method	Path	Description
GET	/api/actions	List all registered actions
POST	/api/actions/[name]/execute	Execute an action by name

Execute via API

curl -X POST http://localhost:3000/api/actions/send_notification/execute \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "body": "Hello from API", "target": "all"}'

Key Files

File	Purpose
lib/actions/registry.ts	ActionRegistry class
lib/actions/index.ts	Registers all built-in actions
lib/actions/send-notification.ts	Notification action
lib/actions/play-media.ts	Media playback action
lib/actions/capture-camera.ts	Camera capture action
lib/actions/ollama-query.ts	Direct Ollama query
lib/actions/read-memory.ts	Memory read action
lib/actions/update-memory.ts	Memory write action
lib/actions/fetch-url.ts	HTTP fetch action
lib/actions/create-reminder.ts	Reminder creation action