@grafana/assistant/README.md

Type definitions and helper functions for Grafana Assistant

# @grafana/assistant

Type definitions and utilities for integrating with the Grafana Assistant.

## Installation

```bash
npm install @grafana/assistant
```

## Usage

### Checking Assistant Availability

```typescript
import { isAssistantAvailable } from '@grafana/assistant';

// Check if the assistant is available
isAssistantAvailable().subscribe((available) => {
  if (available) {
    console.log('Assistant is available');
  }
});
```

### Using the Assistant Hook (React)

```typescript
import { useAssistant } from '@grafana/assistant';

function MyComponent() {
  const [isAvailable, openAssistant, closeAssistant] = useAssistant();

  if (!isAvailable) {
    return <div>Assistant not available</div>;
  }

  return (
    <button onClick={() => openAssistant({ 
      origin: 'grafana/panel-data-analyzer',
      prompt: 'Help me analyze data' })}>
      Open Assistant
    </button>
  );
}
```

### Opening the Assistant Sidebar

```typescript
import { openAssistant, closeAssistant } from '@grafana/assistant';

// Open the assistant with an initial prompt
openAssistant({ origin: 'grafana/some-feature', prompt: 'Show me CPU usage over the last hour' });

// Open the assistant with initial prompt and autoSend set to false
openAssistant({ origin: 'grafana-datasources/prometheus/some-feature', prompt: 'Help me analyze data', autoSend: false })

// Open the assistant without an initial prompt
openAssistant({
  origin: 'grafana-slo-app/some-page',
});

// Close the assistant
closeAssistant();
```

### Using Context with the Assistant

```typescript
import { openAssistant, createAssistantContextItem } from '@grafana/assistant';

// Create context items to provide additional information to the assistant
const datasourceContext = createAssistantContextItem('datasource', {
  datasourceUid: 'prometheus-uid',
});

const dashboardContext = createAssistantContextItem('dashboard', {
  dashboardUid: 'dashboard-uid',
  dashboardTitle: 'System Overview',
  folderUid: 'folder-uid',
  folderTitle: 'Production'
});

// Open the assistant with initial prompt and context
openAssistant({ 
  origin: 'grafana/dashboard-page',
  prompt: 'Analyze the CPU metrics from this dashboard',
  context: [datasourceContext, dashboardContext]
});

// Create hidden context for system instructions (won't show in UI pills)
const systemInstructions = createAssistantContextItem('structured', {
  hidden: true,
  title: 'System Instructions',
  data: {
    instructions: 'When analyzing metrics, always consider seasonal patterns and anomalies',
    preferences: 'Use clear, technical language and provide actionable insights'
  }
});

// Include hidden context with visible context
openAssistant({ 
  prompt: 'What are the trends in this data?',
  context: [datasourceContext, systemInstructions]
});
```

### Providing Page-Specific Context

You can register context items that are automatically included when the assistant is opened on pages matching specific URL patterns. The `providePageContext` function returns a setter function that allows you to update the context dynamically:

```typescript
import { providePageContext, createAssistantContextItem } from '@grafana/assistant';

// Create initial context for dashboard pages
const dashboardContext = createAssistantContextItem('structured', {
  data: {
    name: 'Dashboard Context',
    pageType: 'dashboard',
    capabilities: ['view', 'edit', 'share'],
    help: 'Use the assistant to analyze dashboard data, create queries, or troubleshoot issues.'
  }
});

// Register context for all dashboard pages and get a setter function
const setContext = providePageContext('/d/*', [dashboardContext]);

// Later, dynamically update the context based on user interactions or data changes
setContext([
  dashboardContext,
  createAssistantContextItem('structured', {
    data: {
      name: 'Panel Context',
      selectedPanel: 'cpu-usage-panel',
      panelType: 'graph'
    }
  })
]);

// Clean up when no longer needed
setContext.unregister();

// Example: Provide hidden system instructions for explore pages
providePageContext('/explore', [
  createAssistantContextItem('structured', {
    hidden: true,
    title: 'Additional instructions',
    data: {
      'System Instructions': 'When working with explore queries, always validate the time range and check for data availability. Suggest using recording rules for expensive queries.',
    },
  }),
]);
```

### Using Page Context in React Components

For React components, use the `useProvidePageContext` hook which automatically handles cleanup:

```typescript
import { useProvidePageContext, createAssistantContextItem } from '@grafana/assistant';

function DashboardComponent() {
  const dashboardContext = createAssistantContextItem('structured', {
    data: {
      name: 'Dashboard Context',
      pageType: 'dashboard'
    }
  });

  // Automatically cleans up on unmount
  const setContext = useProvidePageContext('/d/*', [dashboardContext]);

  // Update context when needed
  const handlePanelSelect = (panelId: string) => {
    setContext([
      dashboardContext,
      createAssistantContextItem('structured', {
        data: {
          name: 'Panel Context',
          selectedPanel: panelId
        }
      })
    ]);
  };

  return <div>Dashboard content</div>;
}
```

### Accessing Current Page Context

Use the `usePageContext` hook to access all active context for the current page:

```typescript
import { usePageContext } from '@grafana/assistant';

function MyComponent() {
  const pageContext = usePageContext();
  
  console.log('Active context items:', pageContext);
  
  return <div>Page has {pageContext.length} context items</div>;
}
```

### Creating Context Items

The `createAssistantContextItem` function allows you to create structured context items that provide the assistant with additional information about your Grafana resources.

```typescript
import { createAssistantContextItem } from '@grafana/assistant';

// Create a datasource context
const datasourceContext = createAssistantContextItem('datasource', {
  datasourceUid: 'prom-123',
  title: 'Main Datasource', // Optional custom title
  icon: 'database' // Optional custom icon
});

// Create a dashboard context
const dashboardContext = createAssistantContextItem('dashboard', {
  dashboardUid: 'dash-456',
  dashboardTitle: 'Application Overview',
  folderUid: 'folder-789',
  folderTitle: 'Production Dashboards'
});

// Create a label context
const labelContext = createAssistantContextItem('label_name', {
  datasourceUid: 'prom-123',
  datasourceType: 'prometheus',
  labelName: 'service'
});

// Create a label value context
const labelValueContext = createAssistantContextItem('label_value', {
  datasourceUid: 'prom-123',
  datasourceType: 'prometheus',
  labelName: 'service',
  labelValue: 'api-server'
});

// Create a folder context
const folderContext = createAssistantContextItem('dashboard_folder', {
  folderUid: 'folder-789',
  folderTitle: 'Production Dashboards'
});

// Create structured data context
const structuredContext = createAssistantContextItem('structured', {
  data: {
    name: 'Custom Data',
    metrics: ['cpu_usage', 'memory_usage'],
    threshold: 80
  }
});

// Create generic context
const genericContext = createAssistantContextItem('unknown', {
  id: 'my-context',
  text: 'Some additional context information'
});

// Create component context for custom React components
const componentContext = createAssistantContextItem('component', {
  components: {
    MyCustomComponent: MyCustomComponentImplementation,
    AnotherComponent: AnotherComponentImplementation,
  },
  prompt: `
- When mentioning specific entities, use the your_app_MyCustomComponent with the syntax: <your_app_MyCustomComponent prop1={'value1'} prop2={'value2'} />
- Custom components must never be wrapped in code blocks (backticks \` or \`\`\`).
- Always provide all required props when using custom components.
`,
  namespace: 'your_app', // Optional: Namespace for your components (defaults to 'components')
});

// Create hidden context (useful for system instructions)
const hiddenInstructions = createAssistantContextItem('structured', {
  hidden: true,  // Won't be shown in UI pills but will be sent to the assistant
  title: 'Page-specific instructions',
  data: {
    instructions: 'Always provide step-by-step explanations',
    context: 'This is a complex system with multiple dependencies'
  }
});
```

### Registering Custom Components for Assistant Usage

The `component` context type allows you to register custom React components that the assistant can use in its responses. This is particularly useful for rendering domain-specific UI elements that enhance the user experience.

> **⚠️ Important:** Components must be approved by #grafana-assistant before usage. Please reach out to the Grafana Assistant team for review and approval of your custom components before implementing them in production.

#### Method 1: Using provideComponents (Recommended)

```typescript
import { provideComponents } from '@grafana/assistant';
import MyEntityMention from 'components/MyEntityMentionComponent';
import MyCustomChart from 'components/MyCustomChartComponent';

/**
 * Configure the assistant context for your app plugin.
 * This sets up custom components that will be available to the Grafana Assistant
 * when users are on any page matching the provided pattern.
 */
export function configureAssistantContext() {
  provideComponents(
    `
    - When mentioning an entity in text, always use the your_app_MyEntityMention component: <your_app_MyEntityMention name={'entity name here'} type={'entity type here'} />
    - For displaying charts, use the your_app_MyCustomChart component: <your_app_MyCustomChart data={chartData} title={'Chart Title'} />
    - Custom components must never be wrapped in code blocks (backticks \` or \`\`\`).
    `,
    'your_app', // namespace
    {
      MyEntityMention,
      MyCustomChart,
    },
    /.*/ // matches all pages
  );
}
```

#### Method 2: Using createAssistantContextItem with providePageContext

```typescript
import { createAssistantContextItem, providePageContext } from '@grafana/assistant';
import MyEntityMention from 'components/MyEntityMentionComponent';
import MyCustomChart from 'components/MyCustomChartComponent';

export function configureAssistantContext() {
  providePageContext(/.*/, [
    createAssistantContextItem('component', {
      components: {
        MyEntityMention,
        MyCustomChart,
      },
      prompt: `
        - When mentioning an entity in text, always use the your_app_MyEntityMention component: <your_app_MyEntityMention name={'entity name here'} type={'entity type here'} />
        - For displaying charts, use the your_app_MyCustomChart component: <your_app_MyCustomChart data={chartData} title={'Chart Title'} />
        - Custom components must never be wrapped in code blocks (backticks \` or \`\`\`).
      `,
      namespace: 'your_app', // Optional: defaults to 'components' if not provided
    }),
  ]);
}
```

**Key Points for Component Context:**

- **Approval Required**: ⚠️ Components must be approved by #grafana-assistant before usage
- **Components**: A record of component names to their React component implementations
- **Prompt**: Instructions for the assistant on how and when to use these components
- **Namespace**: A unique identifier for your app's components (e.g., 'your_app', 'datasource'). Optional - defaults to 'components' if not provided
- **Component Usage**: Components are referenced in assistant responses as `<namespace_ComponentName prop={'value'} />` (note the underscore format)
- **No Code Blocks**: Custom components should never be wrapped in markdown code blocks

**Example Component Implementation:**
```typescript
interface MyEntityMentionProps {
  name: string;
  type: string;
  env?: string;
  site?: string;
  namespace?: string;
  properties?: string;
}

const MyEntityMention: React.FC<MyEntityMentionProps> = ({ name, type, env, site, namespace, properties }) => {
  return (
    <span 
      className="entity-mention" 
      data-entity-type={type}
      title={`${type}: ${name}`}
    >
      {name}
    </span>
  );
};

export default MyEntityMention;
```

### Using Hidden Context for System Instructions

The `hidden` parameter allows you to provide context to the assistant without showing it in the UI pills. This is particularly useful for:

- **System instructions**: Provide behavioral guidelines specific to certain pages
- **Metadata**: Include technical details that might confuse users if shown
- **Contextual rules**: Add page-specific rules without cluttering the interface

Example use cases:

```typescript
// Provide exploration-specific guidelines
providePageContext('/explore', [
  createAssistantContextItem('structured', {
    hidden: true,
    title: 'Explore Page Guidelines',
    data: {
      instructions: [
        'Always validate time ranges before running queries',
        'Suggest using recording rules for expensive queries',
        'Warn about queries that might impact performance'
      ],
      queryLimits: {
        maxTimeRange: '24h',
        suggestedSampleInterval: '1m'
      }
    }
  })
]);

// Add dashboard-specific context
providePageContext('/d/*', [
  createAssistantContextItem('structured', {
    hidden: true,
    title: 'Dashboard Instructions',
    data: {
      bestPractices: 'Encourage users to use template variables for flexibility',
      performance: 'Suggest panel caching for slow queries'
    }
  })
]);
```

### Exposing Functions to the Assistant

```typescript
import { 
  getExposeAssistantFunctionsConfig, 
  newFunctionNamespace,
  FunctionImplementation,
  FunctionNamespace,
  NamedFunctions 
} from '@grafana/assistant';

// Define your functions
const myFunctions: NamedFunctions = {
  getMetrics: (datasource: string) => {
    return ['cpu_usage', 'memory_usage', 'disk_io'];
  },
  
  calculateAverage: (values: number[]) => {
    return values.reduce((a, b) => a + b, 0) / values.length;
  }
};

// Create a namespace for your functions
const namespace = newFunctionNamespace('myPlugin', myFunctions);

// Export the configuration for your plugin
export const getExtensionConfigs = () => [
  getExposeAssistantFunctionsConfig([namespace])
];
```

### Using the OpenAssistantButton Component

The `OpenAssistantButton` is a pre-built Button component that provides an easy way to add assistant functionality to your UI with a single button click. It automatically checks availability and hides itself if the Assistant is not available.

```typescript
import { OpenAssistantButton, createAssistantContextItem } from '@grafana/assistant';

function MyDashboard() {
  const dashboardContext = createAssistantContextItem('dashboard', {
    dashboardUid: 'dashboard-123',
    dashboardTitle: 'CPU Metrics Dashboard'
  });

  return (
    <div>
      <h1>Dashboard</h1>
      
      {/* Basic usage */}
      <OpenAssistantButton
        prompt="Help me analyze the CPU usage trends in this dashboard"
        context={[dashboardContext]}
        origin="grafana/dashboard-menu"
      />
      
      {/* Icon-only button */}
      <OpenAssistantButton
        prompt="Show me optimization suggestions"
        iconOnlyButton={true}
        name="Get AI suggestions"
        size="md"
        origin="grafana-datasources/loki/query-editor"
      />
      
      {/* Button without auto-send */}
      <OpenAssistantButton
        prompt="What patterns do you see in the data?"
        autoSend={false}
        name="Ask Assistant"
        size="lg"
        origin="grafana/panel-viewer"
      />
    </div>
  );
}
```

## API Reference

### React Hooks

#### `useAssistant(): [boolean, ((props: OpenAssistantProps) => void) | undefined, (() => void) | undefined]`

A React hook that provides assistant availability status and control functions.

**Returns:** `[isAvailable, openAssistant, closeAssistant]`
- `isAvailable: boolean` - Whether the assistant is available
- `openAssistant?: (props: OpenAssistantProps) => void` - Function to open the assistant (undefined if not available)
- `closeAssistant?: () => void` - Function to close the assistant (undefined if not available)

#### `usePageContext(): ChatContextItem[]`

A React hook that returns all active context items for the current page based on registered URL patterns.

**Returns:** Array of `ChatContextItem` objects that match the current page URL.

#### `useProvidePageContext(urlPattern: string | RegExp, initialContext?: ChatContextItem[]): (context: ChatContextItem[]) => void`

A React hook for providing page context that automatically cleans up on unmount. This is the recommended way to use page context in React components.

**Parameters:**
- `urlPattern` - URL pattern (string or RegExp) to match against page URLs
- `initialContext` - Initial array of ChatContextItem to provide when the pattern matches (defaults to empty array)

**Returns:** A setter function to update the context

#### `usePageComponents(): Record<string, ComponentImplementation>`

A React hook that provides all components available for the current page. This hook automatically updates when the URL changes or when component registrations change.

**Returns:** Object containing all components available for the current page, keyed by `namespace_componentName` format.

**Example:**
```typescript
import { usePageComponents } from '@grafana/assistant';

function MyAssistantComponent() {
  const components = usePageComponents();
  
  // Access components registered with namespace 'myapp' and component name 'EntityMention'
  const EntityMentionComponent = components['myapp_EntityMention'];
  
  return (
    <div>
      Available components: {Object.keys(components).join(', ')}
    </div>
  );
}
```

### React Components

#### `<OpenAssistantButton />`

A pre-built React component that renders a button to open the Grafana Assistant with configurable prompt and context.

**Parameters:**
- `prompt: string` - **Required** The initial prompt to display in the assistant
- `origin: string` - **Required**  Origin of the request that opened the assistant. Should be structured using forward slashes with the first part as a namespace. Examples: 'grafana-datasources/prometheus/query-builder', 'grafana-slo-app/slo-editor-overview'
- `context?: ChatContextItem[]` - Optional context items created with `createAssistantContextItem`
- `autoSend?: boolean` - Whether to automatically send the initial prompt (defaults to `true`)
- `title?: string` - Text to display on the button (defaults to `'Analyze with Assistant'`)
- `size?: 'xs' | 'sm' | 'md' | 'lg'` - Button size (defaults to `'sm'`)
- `iconOnlyButton?: boolean` - If `true`, renders as an icon-only button with tooltip (defaults to `false`)

**Returns:** JSX element or `null` if assistant is not available

### Availability Functions

#### `isAssistantAvailable(): Observable<boolean>`

Checks if the assistant plugin is available.

**Returns:** An RxJS Observable that emits `true` if the assistant is available, `false` otherwise.

### Sidebar Functions

#### `openAssistant(props: OpenAssistantProps): void`

Opens the Grafana Assistant sidebar.

**Parameters:**
- `props: OpenAssistantProps` - Configuration object
  - `origin: string` - Origin of the request that opened the assistant. Should be structured using forward slashes with the first part as a namespace. Examples: 'grafana-datasources/prometheus/query-builder', 'grafana-slo-app/slo-editor-overview'
  - `prompt?: string` - Optional initial prompt to display in the assistant
  - `context?: ChatContextItem[]` - Optional context items to provide additional information to the assistant
  - `autoSend?: boolean` - Optional flag to automatically send the initial prompt

#### `closeAssistant(): void`

Closes the Grafana Assistant sidebar.

### Context Functions

#### `createAssistantContextItem<T>(type: T, params: ContextTypeParams<T>): ChatContextItem`

Creates a context item that can be passed to the assistant to provide additional information.

**Parameters:**
- `type` - The type of context to create. Supported types:
  - `'datasource'` - Datasource context
  - `'dashboard'` - Dashboard context  
  - `'dashboard_folder'` - Folder context
  - `'label_name'` - Label name context
  - `'label_value'` - Label value context
  - `'structured'` - Custom structured data context
  - `'component'` - Custom React components context
  - `'unknown'` - Generic text context
- `params` - Parameters specific to the context type (see Context Types section). All context types support:
  - `hidden?: boolean` - If true, the context item will not be shown in the UI pills but will still be sent to the assistant. This is useful for providing system instructions, behavioral guidelines, or other metadata that shouldn't clutter the user interface.

**Returns:** A `ChatContextItem` that can be passed to `openAssistant`

#### `providePageContext(urlPattern: string | RegExp, initialContext: ChatContextItem[]): ((context: ChatContextItem[]) => void) & { unregister: () => void }`

Registers context items for specific pages based on URL patterns. Returns a setter function to update the context dynamically. The context will be automatically included when the assistant is opened on pages matching the pattern.

**Parameters:**
- `urlPattern` - URL pattern (string with wildcards or RegExp) to match against page URLs
  - String patterns support `*` (match any characters) and `**` (match any path segments)
  - RegExp patterns provide full regex matching capabilities
- `initialContext` - Initial array of `ChatContextItem` to provide when the pattern matches

**Returns:** A setter function to update the context, with an `unregister` method attached for cleanup

**Examples:**
```typescript
// String patterns - returns setter function
const setDashboardContext = providePageContext('/d/*', initialContext); // Match any dashboard
const setExploreContext = providePageContext('/explore**', initialContext); // Match explore and subpaths

// RegExp patterns  
const setSpecificContext = providePageContext(/^\/d\/[a-zA-Z0-9]+$/, initialContext); // Match specific dashboard format

// Update context dynamically
setDashboardContext([...newContext]);

// Cleanup when done
setDashboardContext.unregister();
```

#### `provideComponents(prompt: string, namespace: string, components: Record<string, ComponentImplementation>, urlPattern?: string | RegExp): ((context: ChatContextItem[]) => void) & { unregister: () => void }`

A simplified function for providing components to the assistant. This is a convenience wrapper around `providePageContext` specifically for registering components.

**Parameters:**
- `prompt` - Instructions for the assistant on how and when to use these components
- `namespace` - A unique identifier for your app's components (e.g., 'myapp', 'datasource')
- `components` - A record of component names to their React component implementations
- `urlPattern` - Optional URL pattern to match against page URLs (defaults to `/.*/` - matches all pages)

**Returns:** A setter function to update the context, with an `unregister` method attached for cleanup

**Example:**
```typescript
import { provideComponents } from '@grafana/assistant';
import MyEntityMention from './components/MyEntityMention';
import MyCustomChart from './components/MyCustomChart';

// Register components for all pages
const setComponents = provideComponents(
  `
  - When mentioning entities, use the myapp_MyEntityMention component: <myapp_MyEntityMention name={'entity-name'} type={'entity-type'} />
  - For charts, use the myapp_MyCustomChart component: <myapp_MyCustomChart data={chartData} title={'Chart Title'} />
  - Custom components must never be wrapped in code blocks.
  `,
  'myapp',
  {
    MyEntityMention,
    MyCustomChart,
  }
);

// Register components only for dashboard pages
const setDashboardComponents = provideComponents(
  'Use components to enhance dashboard analysis.',
  'dashboard',
  { MyEntityMention },
  '/d/*'
);

// Cleanup when done
setComponents.unregister();
```

### Questions System

The questions system allows external parties to provide sample prompts with optional context for specific pages. It reuses the existing page context infrastructure but presents a simpler interface focused on questions.

#### `provideQuestions(urlPattern: string | RegExp, initialQuestions: Question[]): ((questions: Question[]) => void) & { unregister: () => void }`

Registers questions for specific pages based on URL patterns. Returns a setter function to update the questions dynamically.

**Parameters:**
- `urlPattern` - URL pattern (string with wildcards or RegExp) to match against page URLs
- `initialQuestions` - Initial array of `Question` to provide when the pattern matches

**Returns:** A setter function to update the questions, with an `unregister` method attached for cleanup

**Examples:**
```typescript
// Register questions for dashboard pages
const setQuestions = provideQuestions("/d/*", [
  {
    prompt: "What metrics are available in this dashboard?",
    context: [], // Optional context items created with `createAssistantContextItem`
  },
  {
    prompt: "How can I optimize the queries in this dashboard?",
    context: [
      createAssistantContextItem("dashboard", {
        dashboardUid: 'dashboard-uid',
        dashboardTitle: 'System Overview',
        folderUid: 'folder-uid',
        folderTitle: 'Production'
      }),
    ],
  },
]);

// Update questions dynamically
setQuestions([
  {
    prompt: "What are the key insights from this dashboard?",
    context: []
  }
]);

// Cleanup when done
setQuestions.unregister();
```

#### `useProvideQuestions(urlPattern: string | RegExp, initialQuestions?: Question[]): (questions: Question[]) => void`

React hook for providing questions that automatically cleans up on unmount. This is the recommended way to use questions in React components.

**Parameters:**
- `urlPattern` - URL pattern (string or RegExp) to match against page URLs
- `initialQuestions` - Initial array of questions to provide when the pattern matches (defaults to empty array)

**Returns:** A setter function to update the questions

**Example:**
```typescript
function DashboardComponent() {
  const setQuestions = useProvideQuestions('/d/*', [
    {
      prompt: "What does this dashboard show?",
    },
    {
      prompt: "How can I improve this dashboard?",
    }
  ]);

  return <div>Dashboard</div>;
}
```

#### `useQuestions(): Question[]`

React hook to get all questions that match the current URL. This filters the page context to only return question-type items.

**Returns:** Array of questions from all matching registrations

**Example:**
```typescript
function AssistantComponent() {
  const questions = useQuestions();
  
  return (
    <div>
      <h3>Suggested Questions:</h3>
      {questions.map((question, index) => (
        <div key={index}>
          <p>{question.prompt}</p>
          {question.context && question.context.length > 0 && (
            <p>Has additional context</p>
          )}
        </div>
      ))}
    </div>
  );
}
```

### Sidebar Types

#### `OpenAssistantProps`

```typescript
type OpenAssistantProps = {
  prompt?: string;
  context?: ChatContextItem[];
  autoSend?: boolean;
};
```

Configuration object for opening the assistant.

- `prompt` - Optional initial prompt to display
- `context` - Optional context items to provide
- `autoSend` - Optional flag to automatically send the initial prompt

#### `ChatContextItem`

```typescript
type ChatContextItem = {
  node: TreeNode;
  occurrences: string[];
};
```

A context item that provides structured information to the assistant.

### Page Context Types

#### `PageContextRegistration`

```typescript
interface PageContextRegistration {
  id: string;
  urlPattern: string | RegExp;
  context: ChatContextItem[];
}
```

Represents a registered page context mapping.

### Questions Types

#### `Question`

```typescript
interface Question {
  prompt: string;           // The sample prompt/question
  context?: ChatContextItem[]; // Optional context items
}
```

Represents a question with an optional prompt and context.

#### `QuestionRegistration`

```typescript
interface QuestionRegistration {
  id: string;
  urlPattern: string | RegExp;
  questions: Question[];
}
```

Represents a registered questions mapping.

### Context Types

#### Datasource Context Parameters

```typescript
interface CreateDatasourceContextParams {
  datasourceUid: string;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Dashboard Context Parameters

```typescript
interface CreateDashboardContextParams {
  dashboardUid: string;
  dashboardTitle: string;
  folderUid?: string;
  folderTitle?: string;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Folder Context Parameters

```typescript
interface CreateFolderContextParams {
  folderUid: string;
  folderTitle: string;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Label Name Context Parameters

```typescript
interface CreateLabelNameContextParams {
  datasourceUid: string;
  datasourceType: string;
  labelName: string;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Label Value Context Parameters

```typescript
interface CreateLabelValueContextParams {
  datasourceUid: string;
  datasourceType: string;
  labelName: string;
  labelValue: string;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Structured Data Context Parameters

```typescript
interface StructuredNodeDataParams {
  data: Record<string, any>;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Component Context Parameters

```typescript
interface CreateComponentContextParams {
  components: Record<string, React.ComponentType<any>>;
  prompt: string;
  namespace?: string;  // Optional: defaults to 'components' if not provided
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

#### Generic Context Parameters

```typescript
interface NodeDataParams {
  id: string;
  text?: string;
  title?: string;
  icon?: IconName;
  hidden?: boolean;  // If true, the context item will not be shown in the context pills
}
```

### Function Extension Types

#### `CallbackFunction`

```typescript
type CallbackFunction = () => FunctionNamespace[];
```

A function that returns an array of function namespaces.

#### `FunctionImplementation`

```typescript
type FunctionImplementation = (...args: any[]) => any;
```

A type for function implementations that can be exposed to the assistant.

#### `NamedFunctions`

```typescript
type NamedFunctions = Record<string, FunctionImplementation>;
```

A record of function names to their implementations.

#### `FunctionNamespace`

```typescript
type FunctionNamespace = {
  namespace: string;
  functions: NamedFunctions;
};
```

Groups functions under a namespace.

### Utility Functions

#### `newFunctionNamespace(namespace: string, functions: NamedFunctions): FunctionNamespace`

Creates a new function namespace.

**Parameters:**
- `namespace: string` - The namespace identifier
- `functions: NamedFunctions` - The functions to include in the namespace

#### `getExposeAssistantFunctionsConfig(namespaces: FunctionNamespace[]): PluginExtensionAddedFunctionConfig`

Creates a plugin extension configuration for exposing functions to the assistant.

**Parameters:**
- `namespaces: FunctionNamespace[]` - Array of function namespaces to expose

### Constants

#### `CALLBACK_EXTENSION_POINT`

```typescript
const CALLBACK_EXTENSION_POINT = 'grafana-assistant-app/callback/v0-alpha';
```

The extension point ID for registering assistant functions.

### Additional Exported Types

The package also exports the following types for advanced use cases:

```typescript
// Data types for context items
export type DashboardNodeData;
export type DatasourceNodeData; 
export type FolderNodeData;
export type LabelNameNodeData;
export type LabelValueNodeData;
export type StructuredNodeData;
export type TreeNode;
export type ItemDataType;

// Component types
export type ComponentImplementation;
export type NamedComponents;
```

## License

Apache-2.0