@nomyx/assistant/README.md

A powerful assistant library and cli for your AI projects. works with Vertex AI (Claude and Gemini)

# @nomyx/assistant

A powerful and flexible AI assistant framework for your projects. This package provides both a library for programmatic use and a command-line interface, supporting multiple AI providers including OpenAI, Anthropic, Azure, Vertex AI, and OpenRouter.

## Features

- Supports multiple AI providers (OpenAI, Anthropic, Azure, Vertex AI, OpenRouter)
- Can be used as a library in your JavaScript/TypeScript projects
- Provides a command-line interface for quick interactions
- Includes a semantic cache for improved performance
- Supports structured prompts and prompt registries
- Includes tools for code analysis and generation
- Provides context management and persistent state

## Installation

```bash
npm install @nomyx/assistant
```

## Usage as a Library

### Basic Usage

```javascript
import { AIAssistant } from '@nomyx/assistant';

const assistant = new AIAssistant();
await assistant.initialize();

const response = await assistant.processRequest("What is the capital of France?");
console.log(response);
```

### Advanced Usage

```javascript
import { AIAssistant, StructuredPrompt, PromptRegistry } from '@nomyx/assistant';

// Create a custom prompt
const customPrompt = new StructuredPrompt({
  name: 'custom_greeting',
  content: 'Hello, {{name}}! Welcome to {{place}}.',
  parameters: {
    name: { type: 'string', description: 'The name of the person to greet' },
    place: { type: 'string', description: 'The place to welcome the person to' }
  }
});

// Register the prompt
const promptRegistry = new PromptRegistry();
promptRegistry.registerPrompt(customPrompt);

// Create an assistant with custom options
const assistant = new AIAssistant({
  promptRegistry,
  maxRetries: 3,
  timeoutMs: 30000,
  providerName: 'openai'
});

await assistant.initialize();

// Use the custom prompt
const response = await assistant.processRequest('custom_greeting', { name: 'Alice', place: 'Wonderland' });
console.log(response);
```

## Usage as a Command-line Tool

After installation, you can use the `ai` command in your terminal:

### Single Query Mode

```bash
ai "What is the capital of France?"
```

### Interactive Mode

```bash
ai
```

This will start an interactive session where you can type multiple queries.

### Testing Providers

To test different AI providers:

```bash
ai --test
```

## Configuration

The assistant can be configured to use different AI providers. Set the following environment variables to configure the provider:

- `AI_PROVIDER`: The name of the AI provider to use (e.g., 'openai', 'anthropic', 'azure', 'vertex', 'openrouter')

### Provider-specific Environment Variables

#### OpenAI
- `OPENAI_API_KEY`: Your OpenAI API key
- `OPENAI_API_MODEL`: The model to use (default: 'gpt-4')

#### Anthropic
- `ANTHROPIC_API_KEY`: Your Anthropic API key
- `ANTHROPIC_MODEL`: The model to use

#### Azure
- `AZURE_SUBSCRIPTION_ID`: Your Azure subscription ID
- `AZURE_OPENAI_API_KEY`: Your Azure OpenAI API key
- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint
- `AZURE_OPENAI_DEPLOYMENT_NAME`: Your Azure OpenAI deployment name

#### Vertex AI
- `GOOGLE_PROJECT_ID`: Your Google Cloud project ID
- `GOOGLE_GEMINI_LOCATION`: The location of your Gemini model
- `GOOGLE_GEMINI_MODEL`: The Gemini model to use
- `GOOGLE_APPLICATION_CREDENTIALS`: Path to your Google Cloud credentials file

#### OpenRouter
- `OPENROUTER_API_KEY`: Your OpenRouter API key
- `OPENROUTER_MODEL`: The model to use
- `OPENROUTER_HTTP_REFERER`: The HTTP referer to use with OpenRouter
- `OPENROUTER_X_TITLE`: The X-Title to use with OpenRouter

## Available Scripts

- `npm run build`: Clean the dist directory and compile TypeScript files
- `npm run clean`: Remove the dist directory
- `npm test`: Run tests
- `npm run test:watch`: Run tests in watch mode
- `npm run test:providers`: Test different AI providers

## API Reference

### AIAssistant

The main class for interacting with the AI assistant.

#### Methods

- `initialize()`: Initialize the assistant
- `processRequest(query: string, options?: ProcessRequestOptions): Promise<string>`: Process a request and return the AI's response
- `setContext(context: any)`: Set the context for future requests
- `clearContext()`: Clear the current context

### StructuredPrompt

A class for creating structured prompts with parameters.

#### Constructor

```javascript
new StructuredPrompt({
  name: string,
  content: string,
  parameters: Record<string, ParameterDefinition>
})
```

### PromptRegistry

A class for registering and managing prompts.

#### Methods

- `registerPrompt(prompt: StructuredPrompt)`: Register a new prompt
- `getPrompt(name: string): StructuredPrompt | undefined`: Get a registered prompt by name

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the ISC License.

## Support

If you encounter any problems or have any questions, please open an issue on the GitHub repository.