@ameshkin/agent-handler

A comprehensive agent handler library for OpenAI-powered applications with RAG, observability, evaluation, memory management, and more.

✨ Features

• 🤖 AI-Powered Components - Chat, search, autosuggest, and grammar correction
• 🔍 RAG & Search - Enterprise-grade semantic search with vector stores
• 📊 Observability - Agent execution tracing and monitoring
• ✅ Evaluation - Test datasets and automated scoring
• 💬 Memory Management - Conversation history and context management
• 📝 Prompt Management - Versioned prompt library and optimization
• 🔒 Security - AI-powered vulnerability scanning
• 🛠️ CLI Tools - Command-line interface for assistant management
• ⚡ TypeScript - Fully typed with TypeScript 5.5
• 🧪 Well Tested - 579 tests across 61 test files

📦 Installation

npm install @ameshkin/agent-handler

🚀 Quick Start

Basic Chat Component

import { ChatBox } from '@ameshkin/agent-handler/react/components/ChatBox';

function App() {
  return (
    <ChatBox
      value={message}
      onChange={setMessage}
      onSubmit={handleSubmit}
      assistantId="asst_xxx"
    />
  );
}

AI Search

import { AISearchBox } from '@ameshkin/agent-handler/react/components/AISearchBox';

function SearchPage() {
  return (
    <AISearchBox
      assistantId="asst_xxx"
      onResults={(results) => console.log(results)}
    />
  );
}

CLI Usage

# Install globally
npm install -g @ameshkin/agent-handler

# Index files for RAG
agent-handler index --profile dev

# Run assistant
agent-handler run --profile dev "What is this project about?"

📚 Documentation

Comprehensive documentation is available in the .docs directory:

• Complete Documentation - Full feature guide
• API Routes - Server endpoints
• CLI Commands - Command reference
• Configuration - Config schema

Popular Guides

• Chat & AI Search - One-line AI components
• Observability & Tracing - Execution monitoring
• Memory Management - Conversation history
• Grammar Assistant - AI grammar correction
• Sentinel Security Scanner - Vulnerability scanning

🧪 Testing

This package uses Vitest for unit/integration tests and Cucumber/Gherkin for BDD-style feature tests.

Quick Start

# Run all tests (CI-safe, non-watch)
npm test

# CI-style run (recommended for CI/Cursor)
npm run test:ci

# Watch mode (local development only)
npm run test:watch

# Coverage report
npm run test:coverage

# BDD/Gherkin features
npm run test:features

Test Commands

All test commands are non-watch and CI-safe by default:

• npm test - Run all Vitest tests once
• npm run test:ci - Recommended for CI/Cursor (basic reporter, non-watch)
• npm run test:watch - Watch mode (local development only)
• npm run test:ui - Vitest UI dashboard (runs once, local only)
• npm run test:coverage - Generate coverage report
• npm run test:features - Run Gherkin feature tests
• npm run test:features:ci - Gherkin with progress format (CI-safe)

For detailed testing documentation, see TESTING.md.

🎯 Core Modules

React Components

• ChatBox - Full-featured chat interface
• AISearchBox - AI-powered search component
• AutosuggestBox - Intelligent autocomplete
• GrammarButton - AI grammar correction
• TokenDisplay - Token usage visualization
• AgentHandlerPanel - Admin control panel

Server Functions

• runChat - Execute chat conversations
• runAISearch - Perform AI-powered searches
• uploadFilesToVectorStore - Manage vector stores
• attachAssistant - Configure assistants

LangChain-Inspired Features

• Observability - Execution tracing and monitoring
• Evaluation - Test datasets and automated scoring
• Memory - Conversation history and context management
• Prompts - Versioned prompt library and optimization

CLI Commands

• agent-handler index - Index files for RAG
• agent-handler run - Execute assistant
• agent-handler agents - List assistants
• agent-handler doctor - Health check

📊 Project Status

• ✅ Production Ready - All P0 features complete
• ✅ Well Tested - 556 tests, ~80% coverage
• ✅ Type Safe - Full TypeScript support
• ✅ Documented - Comprehensive guides and API docs

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• npm Package
• GitHub Repository
• Documentation
• Issue Tracker

Made with ❤️ by @ameshkin