@zemerik/gemini-assist 1.1.1-beta

package/README.md

@@ -0,0 +1,220 @@
+# Gemini Assist v1.1.1-Beta
+
+AI Assistant CLI tool powered by Google Gemini API. Interact with Google's Gemini AI model directly from your terminal.
+
+**🚀 Hybrid Architecture: 50% JavaScript, 50% Rust**  
+This project uses Rust for core API operations and JavaScript for the CLI interface, providing the best of both worlds: Rust's performance and JavaScript's flexibility.
+
+## Features
+
+- 🤖 **Interactive Chat Mode** - Have conversations with Gemini AI
+- 💬 **Single Query Mode** - Quick one-off questions
+- 🎨 **Beautiful CLI Interface** - Colorful, user-friendly terminal experience
+- ⚙️ **Configurable** - Customize model, temperature, and more
+- 📦 **Easy Installation** - Simple npm package installation
+- 🔑 **Secure API Key Management** - Support for environment variables
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 14.0.0
+- For Rust build: Rust toolchain (optional, JS fallback available)
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g gemini-assist
+```
+
+### Building Rust Components
+
+The package includes Rust bindings for better performance. To build them:
+
+```bash
+npm install -g @napi-rs/cli
+npm run build
+```
+
+If Rust bindings aren't available, the CLI automatically falls back to a JavaScript implementation. See [README_RUST.md](README_RUST.md) for details.
+
+### Local Installation
+
+```bash
+npm install gemini-assist
+```
+
+## Getting Started
+
+### 1. Get Your Gemini API Key
+
+1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
+2. Sign in with your Google account
+3. Create a new API key
+4. Copy your API key
+
+### 2. Set Your API Key
+
+**Option A: Environment Variable (Recommended)**
+
+```bash
+export GEMINI_API_KEY=your_api_key_here
+```
+
+**Option B: Command Line Flag**
+
+```bash
+gemini-assist --api-key your_api_key_here "Your question here"
+```
+
+**Option C: .env File (Recommended for Local Development)**
+
+Create a `.env` file in your project directory:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Then edit .env and add your API key
+# GEMINI_API_KEY=your_api_key_here
+```
+
+The `.env` file is automatically loaded by the CLI using the `dotenv` package.
+
+## Usage
+
+### Interactive Mode
+
+Start an interactive chat session:
+
+```bash
+gemini-assist --interactive
+```
+
+Or simply:
+
+```bash
+gemini-assist
+```
+
+In interactive mode:
+- Type your questions and press Enter
+- Type `exit`, `quit`, `bye`, or `q` to end the session
+- Type `clear` to clear the screen
+
+### Single Query Mode
+
+Ask a quick question:
+
+```bash
+gemini-assist "What is the capital of France?"
+```
+
+### Command Line Options
+
+```bash
+gemini-assist [options] [query]
+
+Options:
+  -V, --version          Show version number
+  -k, --api-key <key>    Gemini API key (or set GEMINI_API_KEY env variable)
+  -m, --model <model>    Gemini model to use (default: gemini-1.5-flash)
+  -i, --interactive      Start interactive chat mode
+  -t, --temperature <value>  Temperature for response 0-1 (default: 0.7)
+  -h, --help             Display help for command
+```
+
+### Examples
+
+```bash
+# Interactive mode with custom model
+gemini-assist --interactive --model gemini-1.5-pro
+
+# Single query with custom temperature
+gemini-assist -t 0.9 "Write a creative story"
+
+# Using alias
+gassist "Explain quantum computing"
+```
+
+## Programmatic Usage
+
+You can also use Gemini Assist as a Node.js module:
+
+```javascript
+const { GeminiClient } = require('gemini-assist');
+
+const client = new GeminiClient('your-api-key', {
+  model: 'gemini-1.5-flash',
+  temperature: 0.7
+});
+
+async function chat() {
+  const response = await client.chat('Hello, how are you?');
+  console.log(response);
+}
+
+chat();
+```
+
+## Available Models
+
+- `gemini-2.5-flash` (default) - Latest fast and efficient model
+- `gemini-1.5-flash` - Fast and efficient, previous version
+- `gemini-1.5-pro` - More capable model for complex tasks
+- `gemini-pro` - Legacy model (may be deprecated)
+
+**Note:** Model availability depends on your API key's access level. If a model doesn't work, try another one.
+
+## Configuration
+
+### Environment Variables
+
+- `GEMINI_API_KEY` - Your Gemini API key (required)
+- `DEBUG` - Set to `true` for detailed error messages
+
+## Troubleshooting
+
+### API Key Issues
+
+If you get an "Invalid API key" error:
+1. Verify your API key at [Google AI Studio](https://makersuite.google.com/app/apikey)
+2. Make sure there are no extra spaces when copying the key
+3. Check that the `GEMINI_API_KEY` environment variable is set correctly
+
+### Rate Limits
+
+If you encounter rate limit errors:
+- Wait a few moments before trying again
+- Check your API quota at Google AI Studio
+- Consider upgrading your API plan if needed
+
+### Safety Filters
+
+If content is blocked by safety filters:
+- Rephrase your query
+- Avoid potentially harmful or inappropriate content
+- Check Google's content policy
+
+## Requirements
+
+- Node.js >= 14.0.0
+- npm or yarn
+- Valid Gemini API key
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues, questions, or feature requests, please open an issue on the project repository.
+
+---
+
+**Version:** 1.1.1-Beta  
+**Powered by:** Google Gemini API

package/README_RUST.md

@@ -0,0 +1,134 @@
+# Rust Integration Guide
+
+This project is a **50% JavaScript, 50% Rust** hybrid implementation.
+
+## Architecture
+
+- **Rust (50%)**: Core Gemini API client logic, HTTP requests, and performance-critical operations
+- **JavaScript (50%)**: CLI interface, user interaction, command parsing, and UI/UX
+
+## Building the Rust Component
+
+### Prerequisites
+
+1. Install Rust: https://rustup.rs/
+2. Install Node.js (v14+)
+3. Install napi-rs CLI:
+   ```bash
+   npm install -g @napi-rs/cli
+   ```
+
+### Build Commands
+
+```bash
+# Build Rust bindings for all platforms (release mode)
+npm run build
+
+# Build for development (debug mode)
+npm run build:debug
+
+# Build for current platform only
+cargo build --release
+```
+
+### Project Structure
+
+```
+Gemini Assist/
+├── Cargo.toml              # Rust package configuration
+├── build.rs                # NAPI build script
+├── src/
+│   ├── lib.rs              # NAPI bindings entry point
+│   └── gemini_client.rs    # Rust Gemini API client
+├── bin/
+│   └── gemini-assist.js    # JavaScript CLI entry point
+└── src/
+    ├── gemini.js           # JS wrapper (uses Rust when available)
+    └── utils.js            # JS utilities
+```
+
+## How It Works
+
+1. **Rust Client** (`src/gemini_client.rs`):
+   - Handles all HTTP communication with Gemini API
+   - Manages chat history in memory
+   - Processes API responses and error handling
+   - Uses `reqwest` for async HTTP requests
+
+2. **NAPI Bindings** (`src/lib.rs`):
+   - Exposes Rust functions to Node.js
+   - Handles async operations with Tokio
+   - Provides type-safe JavaScript interop
+
+3. **JavaScript Wrapper** (`src/gemini.js`):
+   - Attempts to load Rust native bindings
+   - Falls back to JavaScript implementation if Rust not available
+   - Provides seamless API compatibility
+
+## Development
+
+### Testing Rust Code
+
+```bash
+# Run Rust tests
+cargo test
+
+# Check Rust code
+cargo clippy
+
+# Format Rust code
+cargo fmt
+```
+
+### Development Workflow
+
+1. Make changes to Rust code in `src/gemini_client.rs` or `src/lib.rs`
+2. Rebuild: `npm run build:debug`
+3. Test: `npm start --interactive`
+
+### Fallback Behavior
+
+If Rust bindings aren't available:
+- The CLI automatically falls back to the JavaScript implementation
+- Uses `@google/generative-ai` SDK instead
+- All functionality remains available
+
+## Performance Benefits
+
+The Rust implementation provides:
+- **Faster HTTP requests** (Rust's async runtime)
+- **Lower memory usage** (no V8 overhead for API calls)
+- **Better error handling** (Rust's type system)
+- **Thread safety** (Tokio async runtime)
+
+## Troubleshooting
+
+### Rust Not Building
+
+```bash
+# Ensure Rust is installed
+rustc --version
+
+# Update Rust toolchain
+rustup update
+
+# Clean and rebuild
+cargo clean
+npm run build
+```
+
+### Module Not Found
+
+If you see "Cannot find module '../index.node'":
+- Run `npm run build` to compile Rust bindings
+- Ensure you're on a supported platform
+- Check `package.json` napi configuration
+
+### Platform Support
+
+Rust bindings are built for:
+- macOS (x86_64, ARM64)
+- Linux (x86_64, ARM64, musl)
+- Windows (x86_64, ARM64)
+
+For other platforms, JavaScript fallback will be used.

package/RELEASE_NOTES.md

@@ -0,0 +1,124 @@
+# Release Notes - Gemini Assist v1.1.1-Beta
+
+## 🎉 Gemini Assist v1.1.1-Beta
+
+**Release Date:** December 2024  
+**Version:** 1.1.1-Beta  
+**Status:** Beta Release
+
+---
+
+## Overview
+
+Gemini Assist v1.1.1-Beta is the first beta release of our AI Assistant CLI tool, bringing the power of Google's Gemini AI directly to your terminal. This release focuses on core functionality, ease of use, and a polished command-line experience.
+
+## ✨ New Features
+
+### Core Functionality
+- **Interactive Chat Mode** - Engage in natural conversations with Gemini AI through an intuitive terminal interface
+- **Single Query Mode** - Quick one-off questions for fast answers without starting a full chat session
+- **Dual Command Support** - Use either `gemini-assist` or the shorter `gassist` alias
+
+### API Integration
+- **Full Gemini API Support** - Seamless integration with Google's Generative AI SDK
+- **Multiple Model Support** - Choose between different Gemini models (gemini-pro, gemini-pro-vision)
+- **Configurable Parameters** - Customize temperature and other generation parameters
+
+### User Experience
+- **Beautiful CLI Interface** - Colorful, user-friendly terminal output with chalk styling
+- **Welcome Screen** - Professional welcome message on startup
+- **Error Handling** - Comprehensive error messages with helpful troubleshooting tips
+- **Command History** - Maintains conversation context during interactive sessions
+
+### Developer Experience
+- **Programmatic API** - Use as an npm package in your Node.js projects
+- **Environment Variable Support** - Secure API key management via .env files
+- **Flexible Configuration** - Multiple ways to configure API keys and options
+
+## 🔧 Technical Details
+
+### Dependencies
+- `@google/generative-ai` (^0.21.0) - Official Google Generative AI SDK
+- `commander` (^11.1.0) - Command-line interface framework
+- `chalk` (^4.1.2) - Terminal string styling
+- `dotenv` (^16.4.5) - Environment variable management
+
+### Architecture
+- Modular design with separate concerns:
+  - `bin/gemini-assist.js` - CLI entry point and command handling
+  - `src/gemini.js` - Gemini API client and chat logic
+  - `src/utils.js` - Utility functions and helpers
+  - `index.js` - Programmatic API export
+
+### Supported Platforms
+- macOS
+- Linux
+- Windows (with Node.js)
+
+## 📋 Usage Examples
+
+### Basic Interactive Mode
+```bash
+gemini-assist --interactive
+```
+
+### Single Query
+```bash
+gemini-assist "Explain quantum computing in simple terms"
+```
+
+### Custom Configuration
+```bash
+gemini-assist --model gemini-pro --temperature 0.9 --interactive
+```
+
+## 🐛 Known Issues
+
+- Chat history is not persisted between sessions
+- No support for file uploads or multimodal inputs in this release
+- Rate limiting errors may occur with free-tier API keys
+
+## 🔮 Upcoming Features (Planned)
+
+- Chat history persistence
+- Multi-modal support (images, files)
+- Streaming responses for real-time output
+- Custom prompt templates
+- Conversation export/import
+- Plugin system for extensibility
+
+## 📝 Installation
+
+```bash
+npm install -g gemini-assist
+```
+
+## 🔑 Getting Started
+
+1. Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
+2. Set environment variable: `export GEMINI_API_KEY=your_key`
+3. Run: `gemini-assist --interactive`
+
+## ⚠️ Beta Notice
+
+This is a beta release. While we've tested the core functionality, you may encounter:
+- Occasional API errors
+- Performance variations
+- Missing features compared to future stable releases
+
+We welcome feedback and bug reports to help improve the tool!
+
+## 🙏 Acknowledgments
+
+- Google Gemini API team for the powerful AI capabilities
+- Open source community for the excellent npm packages used
+
+## 📄 License
+
+MIT License - See LICENSE file for details
+
+---
+
+**Download:** `npm install -g gemini-assist`  
+**Documentation:** See README.md  
+**Issues:** Please report via GitHub Issues

package/bin/gemini-assist.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const readline = require('readline');
+const path = require('path');
+require('dotenv').config();
+
+const { GeminiClient } = require('../src/gemini');
+const { validateApiKey, printWelcome, printError } = require('../src/utils');
+
+const packageJson = require('../package.json');
+
+// CLI Configuration
+program
+  .name('gemini-assist')
+  .description('AI Assistant CLI powered by Google Gemini API')
+  .version(packageJson.version)
+  .option('-k, --api-key <key>', 'Gemini API key (or set GEMINI_API_KEY env variable)')
+  .option('-m, --model <model>', 'Gemini model to use (default: gemini-2.5-flash)')
+  .option('-i, --interactive', 'Start interactive chat mode', false)
+  .option('-t, --temperature <value>', 'Temperature for response (0-1)', '0.7')
+  .parse(process.argv);
+
+const options = program.opts();
+
+async function main() {
+  try {
+    // Get API key
+    const apiKey = options.apiKey || process.env.GEMINI_API_KEY;
+    
+    if (!apiKey) {
+      printError('API key is required. Set GEMINI_API_KEY environment variable or use --api-key flag.');
+      console.log(chalk.yellow('\nTo get your API key:'));
+      console.log(chalk.cyan('  1. Visit https://makersuite.google.com/app/apikey'));
+      console.log(chalk.cyan('  2. Create a new API key'));
+      console.log(chalk.cyan('  3. Create a .env file in the project root:'));
+      console.log(chalk.gray('     cp .env.example .env'));
+      console.log(chalk.cyan('  4. Add your API key to .env file:'));
+      console.log(chalk.gray('     GEMINI_API_KEY=your_key_here'));
+      console.log(chalk.cyan('  OR set it as environment variable:'));
+      console.log(chalk.gray('     export GEMINI_API_KEY=your_key_here\n'));
+      process.exit(1);
+    }
+
+    if (!validateApiKey(apiKey)) {
+      printError('Invalid API key format. Please check your API key.');
+      process.exit(1);
+    }
+
+    // Initialize Gemini client
+    const client = new GeminiClient(apiKey, {
+      model: options.model,
+      temperature: parseFloat(options.temperature)
+    });
+
+    // Interactive mode
+    if (options.interactive || process.argv.length === 2) {
+      await startInteractiveMode(client);
+    } else {
+      // Single query mode
+      const query = program.args.join(' ');
+      if (!query) {
+        printError('Please provide a query or use --interactive mode.');
+        program.help();
+        process.exit(1);
+      }
+
+      const response = await client.chat(query);
+      console.log(chalk.green('\n' + response + '\n'));
+    }
+  } catch (error) {
+    printError(`Error: ${error.message}`);
+    if (process.env.DEBUG) {
+      console.error(error);
+    }
+    process.exit(1);
+  }
+}
+
+async function startInteractiveMode(client) {
+  printWelcome();
+  
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: chalk.cyan('You> ')
+  });
+
+  console.log(chalk.gray('Type your message and press Enter. Type "exit", "quit", or "bye" to end the conversation.\n'));
+
+  rl.prompt();
+
+  rl.on('line', async (input) => {
+    const query = input.trim();
+
+    if (!query) {
+      rl.prompt();
+      return;
+    }
+
+    // Exit commands
+    if (['exit', 'quit', 'bye', 'q'].includes(query.toLowerCase())) {
+      console.log(chalk.yellow('\nGoodbye! 👋\n'));
+      rl.close();
+      return;
+    }
+
+    // Clear command
+    if (query.toLowerCase() === 'clear') {
+      console.clear();
+      printWelcome();
+      rl.prompt();
+      return;
+    }
+
+    // Show thinking indicator
+    process.stdout.write(chalk.gray('Gemini> '));
+    
+    try {
+      const response = await client.chat(query);
+      console.log(chalk.green(response) + '\n');
+    } catch (error) {
+      printError(`Error: ${error.message}`);
+    }
+
+    rl.prompt();
+  });
+
+  rl.on('close', () => {
+    process.exit(0);
+  });
+}
+
+// Run the CLI
+main();

package/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}

package/gitignore

@@ -0,0 +1 @@
+test-*.js

package/index.d.ts

@@ -0,0 +1,13 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare function validateApiKeyRust(apiKey: string): boolean
+export declare function rustVersion(): string
+export declare class RustGeminiClient {
+  constructor(apiKey: string, modelName?: string | undefined | null, temperature?: number | undefined | null)
+  chat(prompt: string): Promise<string>
+  clearHistory(): Promise<void>
+  getHistoryCount(): Promise<number>
+}