supernal-interface

# Supernal Interface - AI Controllability Framework

## Installation

```bash
npm install @supernal/interface
```

## Core Concept

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

## Quick Start

### 1. Decorate Functions

```typescript
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

```typescript
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)
```typescript
import { createCopilotKitAdapter } from '@supernal/interface';

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

### Custom Adapter
```typescript
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

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

// Bind a tool to component state
const [todos, setTodos] = us...