supernal-interface

name	supernal-interface
description	Universal AI Interface framework for making applications AI-controllable. Use when adding AI tool decorators, setting up chat adapters, creating AI-callable functions, or integrating CopilotKit.

Supernal Interface - AI Controllability Framework

Installation

npm install @supernal/interface

Core Concept

Decorate functions → AI can call them with full type safety.

Quick Start

1. Decorate Functions

import { Tool } from '@supernal/interface';

class TodoApp {
  @Tool({
    name: 'add_todo',
    description: 'Add a new todo item',
    category: 'productivity'
  })
  async addTodo(text: string): Promise<Todo> {
    return this.db.create({ text, done: false });
  }

  @Tool({
    name: 'complete_todo',
    description: 'Mark a todo as complete'
  })
  async completeTodo(id: string): Promise<void> {
    await this.db.update(id, { done: true });
  }
}

2. Set Up Adapter

import { createCopilotKitAdapter, ChatUIProvider } from '@supernal/interface';

const adapter = createCopilotKitAdapter({
  autoRegisterTools: true,
  autoRegisterReadables: true
});

function App() {
  return (
    <ChatUIProvider adapter={adapter}>
      <YourApp />
    </ChatUIProvider>
  );
}

3. Done

AI assistants can now discover and call your decorated functions.

Decorators

Decorator	Purpose
@Tool	Expose function as AI-callable tool
@ToolProvider	Class containing multiple tools
@Component	React component with AI context

Adapters

CopilotKit (recommended)

import { createCopilotKitAdapter } from '@supernal/interface';

const adapter = createCopilotKitAdapter({
  autoRegisterTools: true
});

Custom Adapter

import { ChatUIAdapter } from '@supernal/interface';

class MyAdapter implements ChatUIAdapter {
  name = 'my-adapter';
  registerTools(tools) { /* convert to your format */ }
  render(props) { return <MyChat {...props} />; }
}

React Hooks

import { useToolBinding, usePersistedState, useChatWithContext } from '@supernal/interface';

// Bind a tool to component state
const [todos, setTodos] = useToolBinding('todos', []);

// Persist state across sessions
const [prefs, setPrefs] = usePersistedState('user-prefs', defaults);

// Chat with app context
const { messages, send } = useChatWithContext();

Storage Adapters

import { StateManager, LocalStorageAdapter } from '@supernal/interface/storage';

const storage = StateManager.getInstance('myapp', new LocalStorageAdapter());
await storage.setState('user', { name: 'Alice' });

Testing

import { GherkinParser, TestRunner } from '@supernal/interface/testing';

const feature = GherkinParser.parseFeature(gherkinText);
const tests = await TestRunner.generateTests({ framework: 'jest' });

Enterprise Features

Available at supernal.ai/enterprise:

• Auto test generation from decorators
• Story system (50-80% performance boost)
• Architecture visualization
• Multi-model routing
• Audit & compliance logging