Ragie Describe

A utility for generating knowledge base descriptions that are useful for AI tools and LLM routing. This tool analyzes documents in a Ragie partition and creates concise, coherent descriptions that help AI systems understand what information is available in the knowledge base.

Features

• Document Analysis: Retrieves and analyzes documents from a Ragie partition
• Intelligent Summarization: Combines multiple document summaries into coherent descriptions
• AI-Optimized Output: Generates descriptions specifically formatted for LLM tool routing
• Flexible Configuration: Configurable document limits and output formats
• Shell-Safe Output: Optional JSON-escaped output for shell scripting

Installation

Prerequisites

• Node.js (v18 or higher)
• A Ragie account and API key
• An OpenAI API key

Setup

git clone <repository-url>
cd ragie-desc
npm install

Configuration

Set the following environment variables:

export RAGIE_API_KEY="your-ragie-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Usage

Development Mode (Recommended)

Run the tool in development mode with hot reloading:

npm run dev -- --partition "your-partition-name"

Basic Usage

Generate a description for a Ragie partition:

npm run dev -- --partition "your-partition-name"

Advanced Options

npm run dev -- \
  --partition "your-partition-name" \
  --max-documents 20 \
  --escape

Command Line Options

• --partition <partition>: The Ragie partition to analyze (required)
• --max-documents <number>: Maximum number of documents to process (default: 10)
• --escape: Output description in JSON and shell-safe format

Production Build (Optional)

If you need to build for production:

npm run build
node build/index.js --partition "your-partition-name"

How It Works

1. Document Retrieval: Fetches documents from the specified Ragie partition
2. Summary Extraction: Gets summaries for each document (up to the specified limit)
3. Progressive Collapse: Combines summaries iteratively using OpenAI's o4-mini model
4. Final Rephrasing: Uses GPT-4.1 to create a final, AI-optimized description

The tool is designed to create descriptions that help AI systems understand what information is available in a knowledge base, making it easier to route tool calls appropriately.

Output Formats

Standard Output

Description:

This knowledge base contains information about...

Escaped Output (with --escape flag)

This knowledge base contains information about...

(Suitable for shell scripting and JSON embedding)

Examples

Generate a basic description

npm run dev -- --partition "product-docs"

Generate a description with more documents

npm run dev -- --partition "support-articles" --max-documents 25

Use in a shell script

DESCRIPTION=$(npm run dev -- --partition "api-docs" --escape)
echo "Knowledge base description: $DESCRIPTION"

API Reference

The tool uses the following APIs:

• Ragie API: For document retrieval and summary extraction
• OpenAI API: For text processing and description generation
  • o4-mini: For combining summaries
  • GPT-4.1: For final description rephrasing

Error Handling

The tool includes error handling for:

• Missing API keys
• Invalid partition names
• Documents without summaries
• API rate limits and network issues

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the Ragie documentation
• Open an issue on GitHub
• Contact [email protected]