@abra-actions/sdk/README.md

A lightweight TypeScript SDK to expose frontend functions to LLMs via natural language.

![Banner](./assets/banner.png)
# Abra Assistant - Enable Users to Talk to Your App in Minutes

## 🚀 Overview

**abra** is a TypeScript SDK that enables natural language interaction with your application's functions. Import the functions you'd like to expose into the action registry and run a single command to enable execution via natural language commands — all on your own infrastructure.

---

## ✨ Features

- **TypeScript Integration** – Automatically extracts type information from your functions
- **LLM-Powered** – Uses LLM models to understand user intent
- **Zero Boilerplate** – Just import functions into the registry, no annotations or decorators
- **Type Safety** – Validates and transforms user input based on your type definitions
- **No Data Leakage** – Only function names and optional descriptions are sent to the LLM; your code and data stay private
- **Executes Locally** – All actions are run through your code, on your infra, with your auth and security context

---

## 🛠️ Installation

```bash
npm install abra-actions
```

---

## 🔗 Quick Start

### 1. Initialize abra

```bash
abra-actions init 
```

OR: 

```bash
npx abra-actions init
```

This command sets up the abra scaffold in your `/src` directory:

- `./abra_actions/actionRegistry.ts` – Import and register your callable functions here
- `./abra-actions__gactions.json` – Generated manifest of all actions and types
- `./abra.config.ts` – Lightweight wrapper to execute actions via the registry

---

### 2. Register your API_KEY

```ts
// src/abra.config.ts
// AUTO-GENERATED BY ABRA CLI
// Customize this config file as needed

import actionRegistry from './abra-actions/actionRegistry';
import actions from './abra-actions/__generated__/actions.json';

const abraConfig = {
  apiKey: process.env.ABRA_API_KEY || "", // Place API key here. 
  actionRegistry,
  actions: actions.actions
};

export default abraConfig;
```

---

### 3. Import your functions

```ts
// src/abra-actions/actionRegistry.ts

// AUTO-GENERATED BY ABRA CLI — DO NOT EDIT MANUALLY
import {
  createPolicyForId,
  exportAdminCSV,
} from '../admin/handlers'

const actionRegistry: RegistryEntry[] = [
  { 
    name: "Create Policy",
    function: createPolicyForId, 
    description: "Creates a given policy type for the given policy customer.",
    suggested: true,
    suggestion: "Create an AI policy for Acme Inc."
  },
  {
    name: "Export Admin CSV",
    function: exportAdminCSV,
    description: "Downloads a CSV file containing the admin data for a given customer.",
    suggested: true,
    suggestion: "Find the Admin data for Acme Inc."
  }
]

export type RegistryEntry = {
  name: string,
  function: Function,
  description?: string,
  suggested?: boolean,
  suggestion?: string,
}

export default actionRegistry;

```

---

### 4. Generate the actions

```bash
abra-actions generate 
```

OR: 

```bash
npx abra-actions generate
```

This command:
- Populates `actions.json` with metadata about your functions
- We collect:
  - Function Name
  - Function Description (optional)
  - Parameter Names
  - Destructured Types

---

### 5. Use the assistant in your UI

```tsx
import { AbraAssistant } from '@abra-actions/sdk/AbraAssistant';
import config from './abra.config.ts';

function MyComponent() {
  return (
    <div>
      <h1>My App</h1>
      <AbraAssistant config={config} />
    </div>
  );
}
```

---

**Function Execution:**
Abra executes functions entirely within your infrastructure, any parameter filtering, logging, and other security mechanisms remain in tact when executing a function via the Abra Assistant. 


**How Does it Work?:**
When the `actions.json` is generated, the SDK locates your imported functions and uses TypeScript's compiler and typing system to destructure custom parameter types. The built-in component then uses your API key to send function metadata and user intent into the LLM, where when an action is returned from the API the built-in executor invokes your imported function with the assumed parameters as if a user interacted with it via the UI.



## 📄 License

**MIT**

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request.